javax.media.jai
Class SnapshotImage

java.lang.Object
  |
  +--javax.media.jai.PlanarImage
        |
        +--javax.media.jai.SnapshotImage

All Implemented Interfaces:

ImageJAI, PropertyChangeEmitter, PropertySource, RenderedImage, TileObserver, WritablePropertySource

public class SnapshotImage

extends PlanarImage

implements TileObserver

A class providing an arbitrary number of synchronous views of a possibly changing WritableRenderedImage. SnapshotImage is responsible for stabilizing changing sources in order to allow deferred execution of operations dependent on such sources.

Any RenderedImage may be used as the source of a SnapshotImage; if it is a WritableRenderedImage, the SnapshotImage will register itself as a TileObserver and make copies of tiles that are about to change. Multiple versions of each tile are maintained internally, as long as they are in demand. SnapshotImage is able to track demand and should be able to simply forward requests for tiles to the source most of the time, without the need to make a copy.

When used as a source, calls to getTile will simply be passed along to the source. In other words, SnapshotImage is completely transparent. However, by calling createSnapshot() an instance of a non-public PlanarImage subclass (called Snapshot in this implementation) will be created and returned. This image will always return tile data with contents as of the time of its construction.

When a particular Snapshot is no longer needed, its dispose() method may be called. The dispose() method will be called automatically when the Snapshot is finalized by the garbage collector. Disposing of the Snapshot allows tile data held by the Snapshot that is not needed by any other Snapshot to be disposed of as well.

This implementation of SnapshotImage makes use of a doubly-linked list of Snapshot objects. A new Snapshot is added to the tail of the list whenever createSnapshot() is called. Each Snapshot has a cache containing copies of any tiles that were writable at the time of its construction, as well as any tiles that become writable between the time of its construction and the construction of the next Snapshot.

When asked for a tile, a Snapshot checks its local cache and returns its version of the tile if one is found. Otherwise, it forwards the request onto its successor. This process continues until the latest Snapshot is reached; if it does not contain a copy of the tile, the tile is requested from the real source image.

When a Snapshot is no longer needed, its dispose() method attempts to push the contents of its tile cache back to the previous Snapshot in the linked list. If that image possesses a version of the same tile, the tile is not pushed back and may be discarded.

See Also:

RenderedImage, TileObserver, WritableRenderedImage, PlanarImage

Fields inherited from class javax.media.jai.PlanarImage

colorModel, eventManager, height, minX, minY, properties, sampleModel, tileFactory, tileGridXOffset, tileGridYOffset, tileHeight, tileWidth, width

Constructor Summary

SnapshotImage(PlanarImage source)
Constructs a SnapshotImage from a PlanarImage source.

Method Summary

PlanarImage	createSnapshot() Creates a snapshot of this image.
Raster	getTile(int tileX, int tileY) Returns a non-snapshotted tile from the source.
protected PlanarImage	getTrueSource() Returns the PlanarImage source of this SnapshotImage.
void	tileUpdate(WritableRenderedImage source, int tileX, int tileY, boolean willBeWritable) Receives the information that a tile is either about to become writable, or is about to become no longer writable.

Methods inherited from class javax.media.jai.PlanarImage

addPropertyChangeListener, addPropertyChangeListener, addSink, addSink, addSource, addTileComputationListener, cancelTiles, copyData, copyData, copyExtendedData, createColorModel, createWritableRaster, dispose, finalize, getAsBufferedImage, getAsBufferedImage, getBounds, getColorModel, getData, getData, getDefaultColorModel, getExtendedData, getGraphics, getHeight, getImageID, getMaxTileX, getMaxTileY, getMaxX, getMaxY, getMinTileX, getMinTileY, getMinX, getMinY, getNumBands, getNumSources, getNumXTiles, getNumYTiles, getProperties, getProperty, getPropertyClass, getPropertyNames, getPropertyNames, getSampleModel, getSinks, getSource, getSourceImage, getSourceObject, getSources, getSplits, getTileComputationListeners, getTileFactory, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileIndices, getTileRect, getTiles, getTiles, getTileWidth, getWidth, overlapsMultipleTiles, prefetchTiles, queueTiles, removeProperty, removePropertyChangeListener, removePropertyChangeListener, removeSink, removeSink, removeSinks, removeSource, removeSources, removeTileComputationListener, setImageLayout, setProperties, setProperty, setSource, setSources, tileXToX, tileXToX, tileYToY, tileYToY, toString, wrapRenderedImage, XToTileX, XToTileX, YToTileY, YToTileY

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SnapshotImage

public SnapshotImage(PlanarImage source)

Constructs a SnapshotImage from a PlanarImage source.

Parameters:

source - a PlanarImage source.

Throws:

IllegalArgumentException - if source is null.

Method Detail

getTrueSource

protected PlanarImage getTrueSource()

Returns the PlanarImage source of this SnapshotImage.

Returns:

a PlanarImage that is the source of data for this image.

createSnapshot

public PlanarImage createSnapshot()

Creates a snapshot of this image. This snapshot may be used indefinitely, and will always appear to have the pixel data that this image has currently. The snapshot is semantically a copy of this image but may be implemented in a more efficient manner. Multiple snapshots taken at different times may share tiles that have not changed, and tiles that are currently static in this image's source do not need to be copied at all.

Overrides:

createSnapshot in class PlanarImage

Returns:

a PlanarImage snapshot.

tileUpdate

public void tileUpdate(WritableRenderedImage source,
                       int tileX,
                       int tileY,
                       boolean willBeWritable)

Receives the information that a tile is either about to become writable, or is about to become no longer writable.

Specified by:

tileUpdate in interface TileObserver

Parameters:

source - the WritableRenderedImage for which we are an observer.

tileX - the X index of the tile.

tileY - the Y index of the tile.

willBeWritable - true if the tile is becoming writable.

getTile

public Raster getTile(int tileX,
                      int tileY)

Returns a non-snapshotted tile from the source.

Overrides:

getTile in class PlanarImage

Parameters:

tileX - the X index of the tile.

tileY - the Y index of the tile.

Returns:

the tile as a Raster.