Class AbstractPortrait

  • All Implemented Interfaces:
    Portrait
    Direct Known Subclasses:
    DefaultPortrait

    public abstract class AbstractPortrait
    extends java.lang.Object
    implements Portrait
    An abstract base class for Portrait implementations. This base class implements the Point2D-based pan methods in terms of setPanX, setPanY, getPanX, and getPanY. It also returns a default set of portrait features supporting source-changing, panning, and scaling, but not rotation. Accordingly, it provides dummy implementations of the rotation getter/setter methods that enforce an immutable angle of 0 degrees. It provides a no-op implementation of Portrait.installDefault(). It implements getClipStencil() to return null, but it provides some static helper methods for subclasses that wish to provide non-null stencils.
    Since:
    3.0
    Author:
    Chris Jennings
    See Also:
    DefaultPortrait
    • Constructor Detail

      • AbstractPortrait

        public AbstractPortrait()
    • Method Detail

      • setPan

        public void setPan​(java.awt.geom.Point2D pan)
        Sets the pan value from a reference point.

        The base class calls Portrait.setPanX(double) and Portrait.setPanY(double) using the x and y values stored in pan.

        Specified by:
        setPan in interface Portrait
        Parameters:
        pan - a point set to the new X and Y pan values
      • getPan

        public java.awt.geom.Point2D getPan​(java.awt.geom.Point2D dest)
        Returns the pan value as a Point2D. The pan values will be stored in dest; if null, a new point object will be allocated and returned.

        The base class calls Portrait.getPanX() and Portrait.getPanY() to obtain x and y values to store in the destination point.

        Specified by:
        getPan in interface Portrait
        Parameters:
        dest - a point object to store the pan value in
        Returns:
        the point object that contains the pan value
      • getRotation

        public double getRotation()
        Returns the rotation angle for the portrait image. The default rotation is usually 0, but it differs by component. Positive angles turn in the anti-clockwise direction, while negative angles turn in the clockwise direction.

        The base class always returns 0 since the abstract portrait does not support rotation by default.

        Specified by:
        getRotation in interface Portrait
        Returns:
        the rotation angle, in degrees
      • setRotation

        public void setRotation​(double angleInDegrees)
        Sets the rotation angle for the portrait image.

        The base class does nothing since the abstract portrait does not support rotation by default.

        Specified by:
        setRotation in interface Portrait
        Parameters:
        angleInDegrees - the rotation angle, in degrees
      • getClipStencil

        public java.awt.image.BufferedImage getClipStencil()
        Optionally returns an image that describes how the portrait will "show through" surrounding card features. The image's alpha channel is taken to represent a mask for the features that appear over the portrait area. For example, pixels with an alpha of 0 will show the portrait image only, and pixels with an alpha of 255 will show part of a sheet feature that obscures the underlying portrait. In other words, the alpha channel describes the shape of the portrait. If the portrait is simply an unobscured rectangle (that is, nothing is drawn overtop of it), this method can simply return null.

        Note: The value returned by this method is not guaranteed to be accurate and should not be relied on.

        The base class returns null, indicating that the portrait area is unobscured.

        Specified by:
        getClipStencil in interface Portrait
        Returns:
        an image whose alpha channel describes the obscured areas of the portrait, or null
      • createStencil

        public static java.awt.image.BufferedImage createStencil​(java.awt.image.BufferedImage template,
                                                                 java.awt.Rectangle portraitRegion)
        Returns an image suitable for use with getClipStencil(). This method is best used when a sheet's template image has a translucent "hole" that defines the shape of the portrait area. (The portrait is drawn, and then the template is drawn overtop.) It returns the subimage of the template image covered by the given region.

        If an image other than the sheet's template image is used, and that image is not the same size as the template image, then the coordinates of the supplied rectangle must be adjusted accordingly.

        If the resulting image would have no transparent or translucent pixels (that is, if every pixel would have an alpha value of 255), then this method returns null. This is consistent with how null is interpreted when it is returned from getClipStencil(), because if the subimage is completely opaque then the portrait is presumably being drawn over the template rather than under it.

        Parameters:
        template - the sheet's template image
        portraitRegion - the rectangular area covered by the portrait on the template image
        Returns:
        the subimage of the template covered by the portrait rectangle, or null if the template image is null or completely opaque
        Throws:
        java.lang.NullPointerException - if the portrait region is null
      • createStencil

        public static java.awt.image.BufferedImage createStencil​(Settings s,
                                                                 java.lang.String templateKey,
                                                                 java.lang.String portraitRegionKey)
        Creates an image suitable for use with getClipStencil(). This method obtains an image and rectangle from settings values and then calls createStencil(java.awt.image.BufferedImage, java.awt.Rectangle) to create the stencil image.
        Parameters:
        s - the settings to use to look up the keys
        templateKey - a setting key that names an image resource to load
        portraitRegionKey - a setting key (without "-region") that describes the clip region
        Returns:
        the subimage of the template image referenced by templateKey covered by the portrait rectangle described by portraitRegionKey, or null if the resulting image would be completely opaque
        See Also:
        createStencil(java.awt.image.BufferedImage, java.awt.Rectangle)
      • getImageFromIdentifier

        public static java.awt.image.BufferedImage getImageFromIdentifier​(java.lang.String resource,
                                                                          java.awt.Dimension portraitClipSize)
        Loads a user-supplied image. This method is similar to StrangeImage.get(java.lang.String), but it will automatically convert vector images to bitmaps. The size of the bitmap is chosen to be suitable for the specified portrait region.
        Parameters:
        resource - the image identifier to load
        portraitClipSize - the portrait region size to target for vector images
        Returns:
        an image to use as the portrait source