org.geotoolkit.image
Class DeferredPlanarImage

Object
  PlanarImage
      DeferredPlanarImage

All Implemented Interfaces:

RenderedImage, TileObserver, WritableRenderedImage, EventListener, ImageJAI, PropertyChangeEmitter, PropertySource, TileComputationListener, WritablePropertySource, Disposable

public final class DeferredPlanarImage
extends PlanarImage
implements WritableRenderedImage, TileObserver, TileComputationListener, Disposable

A tiled image to be used by renderer when the actual image may take a while to compute. This image wraps an arbitrary rendered image, which may (or may not) be some image expensive to compute. When a tile is requested (through a call to getTile(int, int) but the tile is not available in the wrapped image, then this class returns some default (usually black) tile and start the real tile computation in a background thread. When the actual tile is available, this class fire a tileUpdate event, thus given a chance to a renderer to repaint again this image with the new tiles.

Example of use:

public class Renderer extends JPanel implements TileObserver {
    private DeferredPlanarImage image;

    public Renderer(RenderedImage toPaint) {
        image = new DeferredPlanarImage(toPaint);
        image.addTileObserver(this);
    }

    public void tileUpdate(WritableRenderedImage source,
            int tileX, int tileY, boolean willBeWritable)
    {
        repaint();
    }

    public void paint(Graphics gr) {
        ((Graphics2D) gr).drawRenderedImage(image);
    }
}

Since:

2.3

Version:

3.00

Author:

Rémi Eve (IRD), Martin Desruisseaux (IRD)

Module:

coverage/geotk-coverage (download)

View source code for this class

Field Summary

Fields inherited from class PlanarImage

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

Constructor Summary

DeferredPlanarImage(RenderedImage source)
Constructs a new instance of DeferredPlanarImage.

Method Summary

void	addTileObserver(TileObserver observer) Adds an observer.
void	dispose() Provides a hint that this image will no longer be accessed from a reference in user space.
Vector<RenderedImage>	getSources() Returns the source images.
Raster	getTile(int tileX, int tileY) Returns the specified tile, or a default one if the requested tile is not yet available.
WritableRaster	getWritableTile(int tileX, int tileY) Checks out a tile for writing.
Point[]	getWritableTileIndices() Returns an array of Point objects indicating which tiles are checked out for writing.
boolean	hasTileWriters() Returns whether any tile is checked out for writing.
boolean	isTileWritable(int tileX, int tileY) Returns whether a tile is currently checked out for writing.
void	releaseWritableTile(int tileX, int tileY) Relinquishes the right to write to a tile.
void	removeTileObserver(TileObserver observer) Removes an observer.
void	setData(Raster r) Sets a rectangle of the image to the contents of the raster.
void	tileCancelled(Object eventSource, TileRequest[] requests, PlanarImage image, int tileX, int tileY) Invoked when a tile computation has been canceled.
void	tileComputationFailure(Object eventSource, TileRequest[] requests, PlanarImage image, int tileX, int tileY, Throwable cause) Invoked when a tile computation failed.
void	tileComputed(Object eventSource, TileRequest[] requests, PlanarImage image, int tileX, int tileY, Raster tile) Invoked when a tile has been computed.
void	tileUpdate(WritableRenderedImage source, int tileX, int tileY, boolean willBeWritable) Invoked if the underlying image is writable and one of its tile changed.

Methods inherited from class PlanarImage

addPropertyChangeListener, addPropertyChangeListener, addSink, addSink, addSource, addTileComputationListener, cancelTiles, copyData, copyData, copyExtendedData, createColorModel, createSnapshot, createWritableRaster, 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, 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 Object

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

Methods inherited from interface RenderedImage

copyData, getColorModel, getData, getData, getHeight, getMinTileX, getMinTileY, getMinX, getMinY, getNumXTiles, getNumYTiles, getProperty, getPropertyNames, getSampleModel, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileWidth, getWidth

Constructor Detail

DeferredPlanarImage

public DeferredPlanarImage(RenderedImage source)

Constructs a new instance of DeferredPlanarImage.

Parameters:

source - The source image.

Method Detail

getSources

public Vector<RenderedImage> getSources()

Returns the source images.

Specified by:

getSources in interface RenderedImage

Overrides:

getSources in class PlanarImage

getTile

public Raster getTile(int tileX,
                      int tileY)

Returns the specified tile, or a default one if the requested tile is not yet available. If the requested tile is not immediately available, then an empty tile is returned and a notification will be sent later through TileObserver when the real tile will be available.

Specified by:

getTile in interface RenderedImage

Specified by:

getTile in class PlanarImage

Parameters:

tileX - Tile X index.

tileY - Tile Y index.

Returns:

The requested tile.

tileComputed

public void tileComputed(Object eventSource,
                         TileRequest[] requests,
                         PlanarImage image,
                         int tileX,
                         int tileY,
                         Raster tile)

Invoked when a tile has been computed.

Specified by:

tileComputed in interface TileComputationListener

Parameters:

eventSource - The caller of this method.

requests - The relevant tile computation requests as returned by the method used to queue the tile.

image - The image for which tiles are being computed as specified to the TileScheduler.

tileX - The X index of the tile in the tile array.

tileY - The Y index of the tile in the tile array.

tile - The computed tile.

tileCancelled

public void tileCancelled(Object eventSource,
                          TileRequest[] requests,
                          PlanarImage image,
                          int tileX,
                          int tileY)

Invoked when a tile computation has been canceled. The default implementation does nothing.

Specified by:

tileCancelled in interface TileComputationListener

Parameters:

eventSource - The caller of this method.

requests - The relevant tile computation requests as returned by the method used to queue the tile.

image - The image for which tiles are being computed as specified to the TileScheduler.

tileX - The X index of the tile in the tile array.

tileY - The Y index of the tile in the tile array.

tileComputationFailure

public void tileComputationFailure(Object eventSource,
                                   TileRequest[] requests,
                                   PlanarImage image,
                                   int tileX,
                                   int tileY,
                                   Throwable cause)

Invoked when a tile computation failed. Default implementation log a warning and lets the program continue as usual. We are not throwing an exception since this failure will alter the visual rendering, but will not otherwise harm the system.

Specified by:

tileComputationFailure in interface TileComputationListener

Parameters:

eventSource - The caller of this method.

requests - The relevant tile computation requests as returned by the method used to queue the tile.

image - The image for which tiles are being computed as specified to the TileScheduler.

tileX - The X index of the tile in the tile array.

tileY - The Y index of the tile in the tile array.

cause - The cause of the failure.

tileUpdate

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

Invoked if the underlying image is writable and one of its tile changed. This method forward the call to every registered listener.

Specified by:

tileUpdate in interface TileObserver

addTileObserver

public void addTileObserver(TileObserver observer)

Adds an observer. This observer will be notified everytime a tile initially empty become available. If the observer is already present, it will receive multiple notifications.

Specified by:

addTileObserver in interface WritableRenderedImage

Parameters:

observer - The observer to add.

removeTileObserver

public void removeTileObserver(TileObserver observer)

Removes an observer. If the observer was not registered, nothing happens. If the observer was registered for multiple notifications, it will now be registered for one fewer.

Specified by:

removeTileObserver in interface WritableRenderedImage

Parameters:

observer - The observer to remove.

getWritableTile

public WritableRaster getWritableTile(int tileX,
                                      int tileY)

Checks out a tile for writing. Since DeferredPlanarImage are not really writable, this method throws an UnsupportedOperationException.

Specified by:

getWritableTile in interface WritableRenderedImage

releaseWritableTile

public void releaseWritableTile(int tileX,
                                int tileY)

Relinquishes the right to write to a tile. Since DeferredPlanarImage are not really writable, this method throws an IllegalStateException (the state is really illegal since getWritableTile(int, int) should never have succeeded).

Specified by:

releaseWritableTile in interface WritableRenderedImage

hasTileWriters

public boolean hasTileWriters()

Returns whether any tile is checked out for writing.

Specified by:

hasTileWriters in interface WritableRenderedImage

isTileWritable

public boolean isTileWritable(int tileX,
                              int tileY)

Returns whether a tile is currently checked out for writing.

Specified by:

isTileWritable in interface WritableRenderedImage

getWritableTileIndices

public Point[] getWritableTileIndices()

Returns an array of Point objects indicating which tiles are checked out for writing. Returns null if none are checked out.

Specified by:

getWritableTileIndices in interface WritableRenderedImage

setData

public void setData(Raster r)

Sets a rectangle of the image to the contents of the raster. Since DeferredPlanarImage are not really writable, this method throws an UnsupportedOperationException.

Specified by:

setData in interface WritableRenderedImage

dispose

public void dispose()

Provides a hint that this image will no longer be accessed from a reference in user space. NOTE: this method dispose the image given to the constructor as well. This is because DeferredPlanarImage is used as a "view" of an other image, and the user shouldn't know that he is not using directly the other image.

Specified by:

dispose in interface Disposable

Overrides:

dispose in class PlanarImage