Package ca.cgjennings.apps.arkham.deck.item

Class AbstractRenderedItem

  • All Implemented Interfaces:
    FlippablePageItem, PageItem, java.io.Serializable, java.lang.Cloneable
    Direct Known Subclasses:
    CardFace, TextBox, Tile
    public abstract class AbstractRenderedItem
extends AbstractFlippableItem
    An item whose visual representation is generated from a bitmap. The bitmap may or may not be re-rendered to suit the resolution. To create an rendered item subclass, you must override renderImage(ca.cgjennings.apps.arkham.sheet.RenderTarget, double) to provide an appropriate image when required. If a change to the item state requires that the image be re-rendered, you must call clearCachedImages() and then AbstractItem.itemChanged() so that the image will be updated on the next paint. (For example, an item that displays an image from a file would call this if the user selected a new file.)

    By default, rendered items will transparently use a MIP map technique to cache results for different zoom levels in a page view. The MIP map cache works by rendering the image at a high resolution and then creating scaled versions (that is, scaling down the initial high resolution rendering rather than re-rendering the image for each resolution). The pre-scaled images improve image quality and drawing performance at common view scales. You can disable this cache (see setMipMapCacheEnabled(boolean)), but be aware that you will then be asked to re-render the image every time the view scale changes unless you implement your own caching method.

    Author:
    Chris Jennings
    See Also:
    Serialized Form

    • Field Detail

      • render

        protected transient java.awt.image.BufferedImage render

    • Constructor Detail

      • AbstractRenderedItem

        public AbstractRenderedItem()
        Creates a new rendered item.

    • Method Detail

      • paint

        public void paint​(java.awt.Graphics2D g,
                  RenderTarget target,
                  double renderResolutionHint)
        Description copied from interface: PageItem
        Paint this item at its current location. The graphics context will be scaled so that 1 unit represents 1 point. The resolution hint is a suggestion as to the resolution the item should be rendered at if it must be converted to a bitmap before being drawn. It may or may not represent the actual resolution of the output target.
        Specified by:
        paint in interface PageItem
        Specified by:
        paint in class AbstractItem
        Parameters:
        g - the graphics context to paint to
        target - the type of destination being drawn to
        renderResolutionHint - a source resolution hint

      • getWidth

        public double getWidth()
        Return the width of this item. The result is corrected for the item's current orientation. Subclasses should override getUprightWidth() to provide the item's width in its upright orientation.
        Specified by:
        getWidth in interface PageItem
        Specified by:
        getWidth in class AbstractItem
        Returns:
        the width of this item, in points

      • getUprightWidth

        protected abstract double getUprightWidth()
        Return the width of this item in its standard, upright orientation.
        Returns:
        the width of the unoriented item

      • getHeight

        public double getHeight()
        Return the height of this item. The result is corrected for the item's current orientation. Subclasses should override getUprightWidth() to provide the item's hright in its upright orientation.
        Specified by:
        getHeight in interface PageItem
        Specified by:
        getHeight in class AbstractItem
        Returns:
        the height of this item, in points

      • getUprightHeight

        protected abstract double getUprightHeight()
        Return the height of this item in its standard, upright orientation.
        Returns:
        the height of the unoriented item

      • getThumbnailIcon

        public javax.swing.Icon getThumbnailIcon()
        Description copied from interface: PageItem
        Returns a small representative icon for this item. The icon should be ICON_SIZE pixels wide and high.
        Specified by:
        getThumbnailIcon in interface PageItem
        Specified by:
        getThumbnailIcon in class AbstractItem

      • clearCachedIcon

        protected void clearCachedIcon()
        Ensure that the thumbnail image is regenerated the next time getThumbnailIcon() is called.

      • renderImage

        protected abstract java.awt.image.BufferedImage renderImage​(RenderTarget target,
                                                            double resolution)
        Render an image based on the target and resolution hints. This is called whenever the item's image is required. The image should always be rendered in the upright, unmirrored position. An oriented image will be generated automatically as needed.

        It is recommended that subclasses cache results if possible, in which case clearCachedImages() should be overridden to clear the cached result before calling the super implementation.

        Parameters:
        target - the target type for rendering
        resolution - the resolution that the item should be rendered at
        Returns:
        an image representing the item's current state

      • clearCachedImages

        public void clearCachedImages()
        Clear any cached image data held by this object. The base class clears any cached oriented results and the MIP map cache (if enabled). Subclasses should override this (calling super.clearCachedImages) if the renderImage(ca.cgjennings.apps.arkham.sheet.RenderTarget, double) implementation caches results.

      • createOrientedImage

        protected java.awt.image.BufferedImage createOrientedImage​(java.awt.image.BufferedImage source,
                                                           int orientation)
        Given an upright, unmirrored source image, this method returns an oriented version of the image. If the requested orientation is upright, the original image is returned.
        Parameters:
        source - the rendered image
        orientation - the required orientation
        Returns:
        a version of the source image rotated or flipped into the required orientation

      • writeImpl

        protected void writeImpl​(java.io.ObjectOutputStream out)
                  throws java.io.IOException
        Overrides:
        writeImpl in class AbstractFlippableItem
        Throws:
        java.io.IOException

      • readImpl

        protected void readImpl​(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
        Overrides:
        readImpl in class AbstractFlippableItem
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException

      • setMipMapCacheEnabled

        protected void setMipMapCacheEnabled​(boolean enable)
        Sets whether the built-in MIP map mechanism is enabled. By default, the rendered item will transparently create and use MIP mapped versions of the bitmap to improve painting speed and target. Subclasses may call this method to disable the MIP map mechanism. To do so, you must call setMipMapCacheEnabled( false ) in both the constructor and readImpl(java.io.ObjectInputStream).
        Parameters:
        enable - if true, the MIP map painting mechanism is enabled
        Since:
        3.0
        See Also:
        isMipMapCacheEnabled()

      • isMipMapCacheEnabled

        protected final boolean isMipMapCacheEnabled()
        Returns true if the MIP map mechanism is currently enabled on this item.
        Returns:
        true if MIP mapping is enabled
        Since:
        3.0
        See Also:
        setMipMapCacheEnabled(boolean)

      • isMipMapCacheEnabledByDefault

        protected boolean isMipMapCacheEnabledByDefault()
        Returns true if the MIP map cache should be enabled by default for this item type. Subclasses can override this to disable this mechanism. (The base class returns true.)
        Returns:
        true if the MIP map cache should automatically be enabled during construction or deserialization

      • scaleMipMapUpAtHighZoom

        protected boolean scaleMipMapUpAtHighZoom​(RenderTarget target,
                                          double resolution)
        Returns true if the highest resolution MIP map image should be scaled up at high zoom levels. This method is called when the MIP map cache is enabled but the current zoom level of the view requires an image with higher resolution than the maximum resolution used by the MIP map cache. If it returns true, then the highest resolution MIP map image will be scaled up to the requested resolution. If it returns false, then a new rendering will be requested at the exact resolution needed, just as if the MIP map cache was disabled.

        It is generally faster and consumes less memory to scale up the MIP map image than to render a new image. However, scaling up the MIP map image reduces visual fidelity at high zoom levels. By overriding this method, subclasses can optimize this trade-off for their particular item type.

        The value returned by the base class is unspecified because it may change in future versions.

        Parameters:
        target - the rendering target of the request
        resolution - the desired image resolution
        Returns:
        whether the rendering engine should scale up the highest resolution MIP map image or render the image at the exact resolution required
        See Also:
        setMipMapCacheEnabled(boolean)

      • clone

        public PageItem clone()
        Description copied from interface: PageItem
        Returns a new page item, using this item as a template. The new item should generally be a deep copy, not sharing any objects with the original unless those objects are immutable. The deck editor absolutely relies on this method being implemented correctly! (For example, drag-and-drop and clipboard operations use clones to create copies of existing items.)
        Specified by:
        clone in interface PageItem
        Overrides:
        clone in class AbstractItem
        Returns:
        a new copy of this page item