Class AbstractRenderedItem
- java.lang.Object
-
- ca.cgjennings.apps.arkham.deck.item.AbstractItem
-
- ca.cgjennings.apps.arkham.deck.item.AbstractFlippableItem
-
- ca.cgjennings.apps.arkham.deck.item.AbstractRenderedItem
-
- All Implemented Interfaces:
FlippablePageItem
,PageItem
,java.io.Serializable
,java.lang.Cloneable
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 overriderenderImage(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 callclearCachedImages()
and thenAbstractItem.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
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface ca.cgjennings.apps.arkham.deck.item.PageItem
PageItem.SnapClass, PageItem.SnapTarget
-
-
Field Summary
Fields Modifier and Type Field Description protected java.awt.image.BufferedImage
render
-
Fields inherited from class ca.cgjennings.apps.arkham.deck.item.AbstractFlippableItem
orientation
-
Fields inherited from class ca.cgjennings.apps.arkham.deck.item.AbstractItem
dragHandles, group, parent, selectionLock, snapClass, snapTarget, snapToClasses, xOff, yOff
-
Fields inherited from interface ca.cgjennings.apps.arkham.deck.item.PageItem
ICON_SIZE, ORIENT_MIRROR_TURN_LEFT, ORIENT_MIRROR_TURN_RIGHT, ORIENT_MIRROR_UPRIGHT, ORIENT_MIRROR_UPSIDEDOWN, ORIENT_TURN_LEFT, ORIENT_TURN_RIGHT, ORIENT_UPRIGHT, ORIENT_UPSIDEDOWN
-
-
Constructor Summary
Constructors Constructor Description AbstractRenderedItem()
Creates a new rendered item.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected void
clearCachedIcon()
Ensure that the thumbnail image is regenerated the next timegetThumbnailIcon()
is called.void
clearCachedImages()
Clear any cached image data held by this object.PageItem
clone()
Returns a new page item, using this item as a template.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.double
getHeight()
Return the height of this item.protected java.awt.image.BufferedImage
getOrientedImage(RenderTarget target, double resolution)
Returns an image of this item that is correctly oriented.javax.swing.Icon
getThumbnailIcon()
Returns a small representative icon for this item.protected abstract double
getUprightHeight()
Return the height of this item in its standard, upright orientation.protected abstract double
getUprightWidth()
Return the width of this item in its standard, upright orientation.double
getWidth()
Return the width of this item.protected boolean
isMipMapCacheEnabled()
Returnstrue
if the MIP map mechanism is currently enabled on this item.protected boolean
isMipMapCacheEnabledByDefault()
Returnstrue
if the MIP map cache should be enabled by default for this item type.void
paint(java.awt.Graphics2D g, RenderTarget target, double renderResolutionHint)
Paint this item at its current location.void
prepareToPaint(RenderTarget target, double renderResolutionHint)
Update any cached representations needed to paint this item at the specified settings.protected void
readImpl(java.io.ObjectInputStream in)
protected abstract java.awt.image.BufferedImage
renderImage(RenderTarget target, double resolution)
Render an image based on the target and resolution hints.protected boolean
scaleMipMapUpAtHighZoom(RenderTarget target, double resolution)
Returnstrue
if the highest resolution MIP map image should be scaled up at high zoom levels.protected void
setMipMapCacheEnabled(boolean enable)
Sets whether the built-in MIP map mechanism is enabled.protected void
writeImpl(java.io.ObjectOutputStream out)
-
Methods inherited from class ca.cgjennings.apps.arkham.deck.item.AbstractFlippableItem
flip, getOrientation, setOrientation, turnLeft, turnRight
-
Methods inherited from class ca.cgjennings.apps.arkham.deck.item.AbstractItem
customizePopupMenu, getBleedMargin, getClassesSnappedTo, getClientProperty, getDragHandles, getFoldMarks, getGroup, getLocation, getOutline, getPage, getRectangle, getSnapClass, getSnapTarget, getX, getY, hasExteriorHandles, hitTest, isBleedMarginMarked, isHorizontal, isMirrored, isSelectionLocked, isTurned0DegreesFrom, isTurned180DegreesFrom, isTurned90DegreesFrom, isVertical, itemChanged, itemChanging, putClientProperty, setClassesSnappedTo, setGroup, setLocation, setLocation, setPage, setSelectionLocked, setSnapClass, setSnapTarget, setX, setY, toString
-
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface ca.cgjennings.apps.arkham.deck.item.PageItem
customizePopupMenu, getBleedMargin, getClassesSnappedTo, getClientProperty, getDragHandles, getFoldMarks, getGroup, getLocation, getName, getOutline, getPage, getRectangle, getSnapClass, getSnapTarget, getX, getY, hasExteriorHandles, hitTest, isBleedMarginMarked, isHorizontal, isMirrored, isSelectionLocked, isTurned0DegreesFrom, isTurned180DegreesFrom, isTurned90DegreesFrom, isVertical, putClientProperty, setClassesSnappedTo, setGroup, setLocation, setLocation, setPage, setSelectionLocked, setSnapClass, setSnapTarget, setX, setY
-
-
-
-
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 interfacePageItem
- Specified by:
paint
in classAbstractItem
- Parameters:
g
- the graphics context to paint totarget
- the type of destination being drawn torenderResolutionHint
- a source resolution hint
-
prepareToPaint
public void prepareToPaint(RenderTarget target, double renderResolutionHint)
Description copied from interface:PageItem
Update any cached representations needed to paint this item at the specified settings. It is not required that this be called prior to callingPageItem.paint(java.awt.Graphics2D, ca.cgjennings.apps.arkham.sheet.RenderTarget, double)
. Rather, the intent is that if this method returns without throwing any exceptions (such asOutOfMemoryError
), then a call toPageItem.paint(java.awt.Graphics2D, ca.cgjennings.apps.arkham.sheet.RenderTarget, double)
with the same settings is also expected to succeed. Thus, this method may be called prior to rendering at high resolution and if it throws anOutOfMemoryError
, the application can attempt to recover by freeing up resources before trying to paint again.If this
PageItem
does not require rendering to a buffer, then this method may do nothing.- Specified by:
prepareToPaint
in interfacePageItem
- Overrides:
prepareToPaint
in classAbstractItem
- Parameters:
target
- the rendering targetrenderResolutionHint
- a hint regarding output resolution- See Also:
PageItem.paint(java.awt.Graphics2D, ca.cgjennings.apps.arkham.sheet.RenderTarget, double)
-
getWidth
public double getWidth()
Return the width of this item. The result is corrected for the item's current orientation. Subclasses should overridegetUprightWidth()
to provide the item's width in its upright orientation.- Specified by:
getWidth
in interfacePageItem
- Specified by:
getWidth
in classAbstractItem
- 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 overridegetUprightWidth()
to provide the item's hright in its upright orientation.- Specified by:
getHeight
in interfacePageItem
- Specified by:
getHeight
in classAbstractItem
- 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 beICON_SIZE
pixels wide and high.- Specified by:
getThumbnailIcon
in interfacePageItem
- Specified by:
getThumbnailIcon
in classAbstractItem
-
clearCachedIcon
protected void clearCachedIcon()
Ensure that the thumbnail image is regenerated the next timegetThumbnailIcon()
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 thesuper
implementation.- Parameters:
target
- the target type for renderingresolution
- the resolution that the item should be rendered at- Returns:
- an image representing the item's current state
-
getOrientedImage
protected java.awt.image.BufferedImage getOrientedImage(RenderTarget target, double resolution)
Returns an image of this item that is correctly oriented. (If the card is rotated or flipped, the image will be flipped and/or rotated accordingly.) This method callsrenderImage(ca.cgjennings.apps.arkham.sheet.RenderTarget, double)
in order to obtain the upright version of the image, andcreateOrientedImage(java.awt.image.BufferedImage, int)
to change the orientation if required.The oriented result is cached, and on future calls the cached image will be returned if the orientation is the same and
renderImage(ca.cgjennings.apps.arkham.sheet.RenderTarget, double)
returns the same image instance as the previous call.- Parameters:
target
- the rendering targetresolution
- the desired resolution of the image, in pixels per inch- Returns:
- an oriented image of this item
-
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 (callingsuper.clearCachedImages
) if therenderImage(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 imageorientation
- 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 classAbstractFlippableItem
- Throws:
java.io.IOException
-
readImpl
protected void readImpl(java.io.ObjectInputStream in) throws java.io.IOException, java.lang.ClassNotFoundException
- Overrides:
readImpl
in classAbstractFlippableItem
- 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 callsetMipMapCacheEnabled( false )
in both the constructor andreadImpl(java.io.ObjectInputStream)
.- Parameters:
enable
- iftrue
, the MIP map painting mechanism is enabled- Since:
- 3.0
- See Also:
isMipMapCacheEnabled()
-
isMipMapCacheEnabled
protected final boolean isMipMapCacheEnabled()
Returnstrue
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()
Returnstrue
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 returnstrue
.)- Returns:
true
if the MIP map cache should automatically be enabled during construction or deserialization
-
scaleMipMapUpAtHighZoom
protected boolean scaleMipMapUpAtHighZoom(RenderTarget target, double resolution)
Returnstrue
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 returnstrue
, then the highest resolution MIP map image will be scaled up to the requested resolution. If it returnsfalse
, 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 requestresolution
- 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 interfacePageItem
- Overrides:
clone
in classAbstractItem
- Returns:
- a new copy of this page item
-
-