org.geotools.image
Class DeferredPlanarImage

Object
  extended by PlanarImage
      extended by DeferredPlanarImage
All Implemented Interfaces:
RenderedImage, TileObserver, WritableRenderedImage, EventListener, ImageJAI, PropertyChangeEmitter, PropertySource, TileComputationListener, WritablePropertySource

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

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.

Simple 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
Author:
Remi Eve, Martin Desruisseaux (IRD)
Module:
modules/library/coverage (gt-coverage.jar)

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.
 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 cancelled.
 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, 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 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, getSources, 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

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 cancelled. The default implementation does nothing.

Specified by:
tileCancelled in interface TileComputationListener

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

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

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

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.

Overrides:
dispose in class PlanarImage


Copyright © 1996-2010 Geotools. All Rights Reserved.