javax.media.jai
Class PlanarImage

java.lang.Object
  |
  +--javax.media.jai.PlanarImage
All Implemented Interfaces:
ImageJAI, PropertyChangeEmitter, PropertySource, RenderedImage, WritablePropertySource
Direct Known Subclasses:
OpImage, PlanarImageServerProxy, RemoteImage, RenderedImageAdapter, RenderedOp, SnapshotImage, TiledImage

public abstract class PlanarImage
extends Object
implements ImageJAI, RenderedImage

A RenderedImage is expressed as a collection of pixels. A pixel is defined as a 1-by-1 square; its origin is the top-left corner of the square (0, 0), and its energy center is located at the center of the square (0.5, 0.5).

This is the fundamental base class of Java Advanced Imaging (JAI) that represents a two-dimensional RenderedImage.

This class provides a home for the information and functionalities common to all the JAI classes that implement the RenderedImage interface, such as the image's layout, sources, properties, etc. The image layout, sources, and properties may be set either at construction or subsequently using one of the mutator methods supplied for the respective attribute. In general this class does not perform sanity checking on the state of its variables so it is very important that subclasses set them correctly. This is of particular importance with respect to the image layout.

The layout of a PlanarImage is specified by variables minX, minY, width, height, tileGridXOffset, tileGridYOffset, tileWidth, tileHeight, sampleModel, and colorModel. These variables do not have any default settings so subclasses must set the appropriate ones at construction via the ImageLayout argument or subsequently using setImageLayout(). Otherwise, unexpected errors may occur. Although these variables have protected access, it is strongly recommended that subclasses not set the values of these variables directly but rather via setImageLayout() which performs a certain few initializations based on the layout values. The variables are defined to have protected access for convenience.

A PlanarImage may have any number of RenderedImage sources or no source at all.

All non-JAI RenderedImage instances must be converted into PlanarImages by means of the RenderedImageAdapter and WritableRenderedImageAdapter classes. The wrapRenderedImage method provides a convenient interface to both add a wrapper and take a snapshot if the image is writable. All of the PlanarImage constructors perform this wrapping automatically. Images that already extend PlanarImage will be returned unchanged by wrapRenderedImage; that is, it is idempotent.

Going in the other direction, existing code that makes use of the RenderedImage interface will be able to use PlanarImages directly, without any changes or recompilation. Therefore, within JAI, two-dimensional images are returned from methods as PlanarImages, even though incoming RenderedImages are accepted as arguments directly.

A PlanarImage may also have any number of properties of any type. If or how a property is used depends on the individual subclass. This class only stores the property information. If any PropertyChangeListeners are registered they will receive a PropertySourceChangeEvent for each change in an image property.

In general, methods in this class are implemented such that they use any class variables directly instead of through their accessors for performance reasons. Subclasses need to be careful when overriding this class' variable accessors that other appropriate methods are overriden as well.

PlanarImage implements a createSnapshot method that produces a new, immutable image with a copy of this image's current contents. In practice, this snapshot is only a virtual copy; it is managed by the SnapshotImage class in such a way as to minimize copying and memory footprint generally. Multiple calls to createSnapshot make use of a single SnapshotImage per PlanarImage in order to centralize version management. These mechanisms are transparent to the API user and are discussed here only for edification.

The source and sink lists have the effect of creating a graph structure between a set of PlanarImages. Note that the practice of making such bidirectional connections between images means that the garbage collector will not inform us when all user references to a node are lost, since there will still be internal references up until the point where the entire graph is detached from user space. A solution is available in the form of Reference Objects; see http://java.sun.com/products/jdk/1.3/docs/guide/refobs/ for more information. These classes include weak references that allow the Garbage Collector (GC) to collect objects they reference, setting the reference to null in the process.

The reference problem requires us to be careful about how we define the reachability of directed acyclic graph (DAG) nodes. If we were to allow nodes to be reached by arbitrary graph traversal, we would be unable to garbage collect any subgraphs of an active graph at all since any node may be reached from any other. Instead, we define the set of reachable nodes as those that may be accessed directly from a reference in user code, or that are the source (not sink) of a reachable node. Reachable nodes are always accessible, whether they are reached by traversing upwards or downwards in the DAG.

A DAG may also contain nodes that are not reachable, that is, they require a downward traversal at some point. For example, assume a node A is reachable, and a call to A.getSinks() yields a Vector containing a reference to a previously unreachable node B. The node B naturally becomes reachable by virtue of the new user reference pointing to it. However, if the user were to relinquish that reference, the node might be garbage collected, and a future call to A.getSinks() might no longer include B in its return value.

Because the set of sinks of a node is inherently unstable, only the getSinks method is provided for external access to the sink vector at a node. A hypothetical method such as getSink or getNumSinks would produce confusing results should a sink be garbage collected between that call and a subsequent call to getSinks.

See Also:
RenderedImage, Reference, WeakReference, ImageJAI, OpImage, RenderedImageAdapter, SnapshotImage, TiledImage

Field Summary
protected  ColorModel colorModel
          The image's ColorModel.
protected  PropertyChangeSupportJAI eventManager
          A helper object to manage firing events.
protected  int height
          The image's height in number of pixels.
protected  int minX
          The X coordinate of the image's top-left pixel.
protected  int minY
          The Y coordinate of the image's top-left pixel.
protected  WritablePropertySourceImpl properties
          A helper object to manage the image properties.
protected  SampleModel sampleModel
          The image's SampleModel.
protected  TileFactory tileFactory
          A TileFactory for use in createWritableRaster(SampleModel,Point).
protected  int tileGridXOffset
          The X coordinate of the top-left pixel of tile (0, 0).
protected  int tileGridYOffset
          The Y coordinate of the top-left pixel of tile (0, 0).
protected  int tileHeight
          The height of a tile in number of pixels.
protected  int tileWidth
          The width of a tile in number of pixels.
protected  int width
          The image's width in number of pixels.
 
Constructor Summary
PlanarImage()
          The default constructor.
PlanarImage(ImageLayout layout, Vector sources, Map properties)
          Constructor.
 
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
          Add a PropertyChangeListener to the listener list.
 void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)
          Add a PropertyChangeListener for a specific property.
 boolean addSink(Object sink)
          Adds an Object sink to the list of sinks.
protected  void addSink(PlanarImage sink)
          Deprecated. as of JAI 1.1. Use addSink(Object) instead.
protected  void addSource(Object source)
          Adds an Object source to the list of sources.
 void addTileComputationListener(TileComputationListener listener)
          Adds a TileComputationListener to the list of registered TileComputationListeners.
 void cancelTiles(TileRequest request, Point[] tileIndices)
          Issue an advisory cancellation request to nullify processing of the indicated tiles.
 WritableRaster copyData()
          Copies the entire image into a single raster.
 WritableRaster copyData(WritableRaster raster)
          Copies an arbitrary rectangular region of this image's pixel data into a caller-supplied WritableRaster.
 void copyExtendedData(WritableRaster dest, BorderExtender extender)
          Copies an arbitrary rectangular region of the RenderedImage into a caller-supplied WritableRaster.
static ColorModel createColorModel(SampleModel sm)
          Creates a ColorModel that may be used with the specified SampleModel.
 PlanarImage createSnapshot()
          Creates a snapshot, that is, a virtual copy of the image's current contents.
protected  WritableRaster createWritableRaster(SampleModel sampleModel, Point location)
          Creates a WritableRaster with the specified SampleModel and location.
 void dispose()
          Provides a hint that an image will no longer be accessed from a reference in user space.
protected  void finalize()
          Performs cleanup prior to garbage collection.
 BufferedImage getAsBufferedImage()
          Returns a copy of the entire image as a BufferedImage.
 BufferedImage getAsBufferedImage(Rectangle rect, ColorModel cm)
          Returns a copy of this image as a BufferedImage.
 Rectangle getBounds()
          Returns the image's bounds as a Rectangle.
 ColorModel getColorModel()
          Returns the ColorModel of the image.
 Raster getData()
          Returns the entire image in a single Raster.
 Raster getData(Rectangle region)
          Returns a specified region of this image in a Raster.
static ColorModel getDefaultColorModel(int dataType, int numBands)
          Returns a ComponentColorModel created based on the indicated dataType and numBands.
 Raster getExtendedData(Rectangle region, BorderExtender extender)
          Returns a copy of an arbitrary rectangular region of this image in a Raster.
 Graphics getGraphics()
          Returns a Graphics object that may be used to draw into this image.
 int getHeight()
          Returns the height of the image in number of pixels.
 Object getImageID()
          Returns a unique identifier (UID) for this PlanarImage.
 int getMaxTileX()
          Returns the horizontal index of the right-most column of tiles.
 int getMaxTileY()
          Returns the vertical index of the bottom-most row of tiles.
 int getMaxX()
          Returns the X coordinate of the column immediately to the right of the right-most column of the image.
 int getMaxY()
          Returns the Y coordinate of the row immediately below the bottom-most row of the image.
 int getMinTileX()
          Returns the horizontal index of the left-most column of tiles.
 int getMinTileY()
          Returns the vertical index of the top-most row of tiles.
 int getMinX()
          Returns the X coordinate of the left-most column of the image.
 int getMinY()
          Returns the Y coordinate of the top-most row of the image.
 int getNumBands()
          Retrieve the number of image bands.
 int getNumSources()
          Returns the number of immediate PlanarImage sources this image has.
 int getNumXTiles()
          Returns the number of tiles along the tile grid in the horizontal direction.
 int getNumYTiles()
          Returns the number of tiles along the tile grid in the vertical direction.
protected  Hashtable getProperties()
          Returns the internal Hashtable containing the image properties by reference.
 Object getProperty(String name)
          Gets a property from the property set of this image.
 Class getPropertyClass(String name)
          Returns the class expected to be returned by a request for the property with the specified name.
 String[] getPropertyNames()
          Returns a list of property names that are recognized by this image or null if none are recognized.
 String[] getPropertyNames(String prefix)
          Returns an array of Strings recognized as names by this property source that begin with the supplied prefix.
 SampleModel getSampleModel()
          Returns the SampleModel of the image.
 Vector getSinks()
          Returns a Vector containing the currently available PlanarImage sinks of this image (images for which this image is a source), or null if no sinks are present.
 PlanarImage getSource(int index)
          Deprecated. as of JAI 1.1. Use getSourceImage().
 PlanarImage getSourceImage(int index)
          Returns the immediate source indicated by the index.
 Object getSourceObject(int index)
          Returns the immediate source indicated by the index.
 Vector getSources()
          Returns this image's immediate source(s) in a Vector.
 void getSplits(IntegerSequence xSplits, IntegerSequence ySplits, Rectangle rect)
          Within a given rectangle, store the list of tile seams of both X and Y directions into the corresponding split sequence.
abstract  Raster getTile(int tileX, int tileY)
          Returns tile (tileX, tileY) as a Raster.
 TileComputationListener[] getTileComputationListeners()
          Retrieves a snapshot of the set of all registered TileComputationListeners as of the moment this method is invoked.
 TileFactory getTileFactory()
          Returns the value of the instance variable tileFactory.
 int getTileGridXOffset()
          Returns the X coordinate of the top-left pixel of tile (0, 0).
 int getTileGridYOffset()
          Returns the Y coordinate of the top-left pixel of tile (0, 0).
 int getTileHeight()
          Returns the height of a tile of this image in number of pixels.
 Point[] getTileIndices(Rectangle region)
          Returns an array containing the indices of all tiles which overlap the specified Rectangle.
 Rectangle getTileRect(int tileX, int tileY)
          Returns a Rectangle indicating the active area of a given tile.
 Raster[] getTiles()
          Computes and returns all tiles in the image.
 Raster[] getTiles(Point[] tileIndices)
          Returns the Rasters indicated by the tileIndices array.
 int getTileWidth()
          Returns the width of a tile of this image in number of pixels.
 int getWidth()
          Returns the width of the image in number of pixels.
 boolean overlapsMultipleTiles(Rectangle rect)
          Returns true if and only if the intersection of the specified Rectangle with the image bounds overlaps more than one tile.
 void prefetchTiles(Point[] tileIndices)
          Hints that the given tiles might be needed in the near future.
 TileRequest queueTiles(Point[] tileIndices)
          Queues a list of tiles for computation.
 void removeProperty(String name)
          Removes the named property from the PlanarImage.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Remove a PropertyChangeListener from the listener list.
 void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)
          Remove a PropertyChangeListener for a specific property.
 boolean removeSink(Object sink)
          Removes an Object sink from the list of sinks.
protected  boolean removeSink(PlanarImage sink)
          Deprecated. as of JAI 1.1. Use removeSink(Object) instead.
 void removeSinks()
          Removes all the sinks of this image.
protected  boolean removeSource(Object source)
          Removes an Object source from the list of sources.
protected  void removeSources()
          Removes all the sources of this image.
 void removeTileComputationListener(TileComputationListener listener)
          Removes a TileComputationListener from the list of registered TileComputationListeners.
protected  void setImageLayout(ImageLayout layout)
          Sets the image bounds, tile grid layout, SampleModel and ColorModel using values from an ImageLayout object.
protected  void setProperties(Hashtable properties)
          Sets the Hashtable containing the image properties to a given Hashtable.
 void setProperty(String name, Object value)
          Sets a property on a PlanarImage.
protected  void setSource(Object source, int index)
          Sets an immediate source of this image.
protected  void setSources(List sourceList)
          Sets the list of sources from a given List of PlanarImages.
 int tileXToX(int tx)
          Converts a horizontal tile index into the X coordinate of its upper left pixel.
static int tileXToX(int tx, int tileGridXOffset, int tileWidth)
          Converts a horizontal tile index into the X coordinate of its upper left pixel relative to a given tile grid layout specified by its X offset and tile width.
 int tileYToY(int ty)
          Converts a vertical tile index into the Y coordinate of its upper left pixel.
static int tileYToY(int ty, int tileGridYOffset, int tileHeight)
          Converts a vertical tile index into the Y coordinate of its upper left pixel relative to a given tile grid layout specified by its Y offset and tile height.
 String toString()
          Returns a String which includes the basic information of this image.
static PlanarImage wrapRenderedImage(RenderedImage image)
          Wraps an arbitrary RenderedImage to produce a PlanarImage.
 int XToTileX(int x)
          Converts a pixel's X coordinate into a horizontal tile index.
static int XToTileX(int x, int tileGridXOffset, int tileWidth)
          Converts a pixel's X coordinate into a horizontal tile index relative to a given tile grid layout specified by its X offset and tile width.
 int YToTileY(int y)
          Converts a pixel's Y coordinate into a vertical tile index.
static int YToTileY(int y, int tileGridYOffset, int tileHeight)
          Converts a pixel's Y coordinate into a vertical tile index relative to a given tile grid layout specified by its Y offset and tile height.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

minX

protected int minX
The X coordinate of the image's top-left pixel.

minY

protected int minY
The Y coordinate of the image's top-left pixel.

width

protected int width
The image's width in number of pixels.

height

protected int height
The image's height in number of pixels.

tileGridXOffset

protected int tileGridXOffset
The X coordinate of the top-left pixel of tile (0, 0).

tileGridYOffset

protected int tileGridYOffset
The Y coordinate of the top-left pixel of tile (0, 0).

tileWidth

protected int tileWidth
The width of a tile in number of pixels.

tileHeight

protected int tileHeight
The height of a tile in number of pixels.

sampleModel

protected SampleModel sampleModel
The image's SampleModel.

colorModel

protected ColorModel colorModel
The image's ColorModel.

tileFactory

protected TileFactory tileFactory
A TileFactory for use in createWritableRaster(SampleModel,Point). This field will be null unless initialized via the configuration properties passed to PlanarImage(ImageLayout,Vector,Map).
Since:
JAI 1.1.2

eventManager

protected PropertyChangeSupportJAI eventManager
A helper object to manage firing events.
Since:
JAI 1.1

properties

protected WritablePropertySourceImpl properties
A helper object to manage the image properties.
Since:
JAI 1.1
Constructor Detail

PlanarImage

public PlanarImage()
The default constructor.

The eventManager and properties helper fields are initialized by this constructor; no other non-private fields are set.


PlanarImage

public PlanarImage(ImageLayout layout,
                   Vector sources,
                   Map properties)
Constructor.

The image's layout is encapsulated in the layout argument. Note that no verification is performed to determine whether the image layout has been set either at construction or subsequently.

This constructor does not provide any default settings for the layout variables so all of those that will be used later must be set in the layout argument or subsequently via setImageLayout() before the values are used. Otherwise, unexpected errors may occur.

If the SampleModel is non-null and the supplied tile dimensions are positive, then if the dimensions of the supplied SampleModel differ from the tile dimensions, a new SampleModel will be created for the image from the supplied SampleModel but with dimensions equal to those of a tile.

If both the SampleModel and the ColorModel in the supplied ImageLayout are non-null they will be tested for compatibility. If the test fails an exception will be thrown. The test is that

The sources parameter contains a list of immediate sources of this image none of which may be null. All RenderedImages in the list are automatically converted into PlanarImages when necessary. If this image has no source, this argument should be null.

The properties parameter contains a mapping of image properties. All map entries which have a key which is either a String or a CaselessStringKey are interpreted as image properties and will be copied to the property database of this image. This parameter may be null.

If a TileFactory-valued mapping of the key JAI.KEY_TILE_FACTORY is present in properties, then set the instance variable tileFactory to the specified TileFactory. This TileFactory will be used by createWritableRaster(SampleModel,Point) to create Rasters, notably in getData(Rectangle), copyData(WritableRaster), and getExtendedData(Rectangle,BorderExtender).

The event and property helper fields are initialized by this constructor.

Parameters:
layout - The layout of this image or null.
sources - The immediate sources of this image or null.
properties - A Map containing the properties of this image or null.
Throws:
IllegalArgumentException - if a ColorModel is specified in the layout and it is incompatible with the SampleModel
IllegalArgumentException - If sources is non-null and any object in sources is null.
Since:
JAI 1.1
Method Detail

setImageLayout

protected void setImageLayout(ImageLayout layout)
Sets the image bounds, tile grid layout, SampleModel and ColorModel using values from an ImageLayout object.

If either of the tile dimensions is not set in the passed in ImageLayout object, then the tile dimension in question will be set to the corresponding image dimension.

If either of the tile grid offsets is not set in the passed in ImageLayout object, then the tile grid offset in question will be set to 0. The same is true for the minX , minY, width and height fields, if no value is set in the passed in ImageLayout object, they will be set to 0.

If the SampleModel is non-null and the supplied tile dimensions are positive, then if the dimensions of the supplied SampleModel differ from the tile dimensions, a new SampleModel will be created for the image from the supplied SampleModel but with dimensions equal to those of a tile.

If both the SampleModel and the ColorModel in the supplied ImageLayout are non-null they will be tested for compatibility. If the test fails an exception will be thrown. The test is that

Parameters:
layout - an ImageLayout that is used to selectively override the image's layout, SampleModel, and ColorModel. Only valid fields, i.e., those for which ImageLayout.isValid() returns true for the appropriate mask, are used.
Throws:
IllegalArgumentException - if layout is null.
IllegalArgumentException - if a ColorModel is specified in the layout and it is incompatible with the SampleModel
Since:
JAI 1.1

wrapRenderedImage

public static PlanarImage wrapRenderedImage(RenderedImage image)
Wraps an arbitrary RenderedImage to produce a PlanarImage. PlanarImage adds various properties to an image, such as source and sink vectors and the ability to produce snapshots, that are necessary for JAI.

If the image is already a PlanarImage, it is simply returned unchanged. Otherwise, the image is wrapped in a RenderedImageAdapter or WritableRenderedImageAdapter as appropriate.

Parameters:
image - The RenderedImage to be converted into a PlanarImage.
Returns:
A PlanarImage containing image's pixel data.
Throws:
IllegalArgumentException - If image is null.

createSnapshot

public PlanarImage createSnapshot()
Creates a snapshot, that is, a virtual copy of the image's current contents. If the image is not a WritableRenderedImage, it is returned unchanged. Otherwise, a SnapshotImage is created and the result of calling its createSnapshot() is returned.
Returns:
A PlanarImage with immutable contents.

getMinX

public int getMinX()
Returns the X coordinate of the left-most column of the image. The default implementation returns the corresponding instance variable.
Specified by:
getMinX in interface RenderedImage

getMaxX

public int getMaxX()
Returns the X coordinate of the column immediately to the right of the right-most column of the image.

This method is implemented in terms of getMinX() and getWidth() so that subclasses which override those methods do not need to override this one.


getMinY

public int getMinY()
Returns the Y coordinate of the top-most row of the image. The default implementation returns the corresponding instance variable.
Specified by:
getMinY in interface RenderedImage

getMaxY

public int getMaxY()
Returns the Y coordinate of the row immediately below the bottom-most row of the image.

This method is implemented in terms of getMinY() and getHeight() so that subclasses which override those methods do not need to override this one.


getWidth

public int getWidth()
Returns the width of the image in number of pixels. The default implementation returns the corresponding instance variable.
Specified by:
getWidth in interface RenderedImage

getHeight

public int getHeight()
Returns the height of the image in number of pixels. The default implementation returns the corresponding instance variable.
Specified by:
getHeight in interface RenderedImage

getNumBands

public int getNumBands()
Retrieve the number of image bands. Note that this will not equal the number of color components if the image has an IndexColorModel. This is equivalent to calling getSampleModel().getNumBands().
Since:
JAI 1.1

getBounds

public Rectangle getBounds()
Returns the image's bounds as a Rectangle.

The image's bounds are defined by the values returned by getMinX(), getMinY(), getWidth(), and getHeight(). A Rectangle is created based on these four methods and cached in this class. Each time that this method is invoked, the bounds of this Rectangle are updated with the values returned by the four aforementioned accessors.

Because this method returns the bounds variable by reference, the caller should not change the settings of the Rectangle. Otherwise, unexpected errors may occur. Likewise, if the caller expects this variable to be immutable it should clone the returned Rectangle if there is any possibility that it might be changed by the PlanarImage. This may generally occur only for instances of RenderedOp.


getTileGridXOffset

public int getTileGridXOffset()
Returns the X coordinate of the top-left pixel of tile (0, 0). The default implementation returns the corresponding instance variable.
Specified by:
getTileGridXOffset in interface RenderedImage

getTileGridYOffset

public int getTileGridYOffset()
Returns the Y coordinate of the top-left pixel of tile (0, 0). The default implementation returns the corresponding instance variable.
Specified by:
getTileGridYOffset in interface RenderedImage

getTileWidth

public int getTileWidth()
Returns the width of a tile of this image in number of pixels. The default implementation returns the corresponding instance variable.
Specified by:
getTileWidth in interface RenderedImage

getTileHeight

public int getTileHeight()
Returns the height of a tile of this image in number of pixels. The default implementation returns the corresponding instance variable.
Specified by:
getTileHeight in interface RenderedImage

getMinTileX

public int getMinTileX()
Returns the horizontal index of the left-most column of tiles.

This method is implemented in terms of the static method XToTileX() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.

Specified by:
getMinTileX in interface RenderedImage

getMaxTileX

public int getMaxTileX()
Returns the horizontal index of the right-most column of tiles.

This method is implemented in terms of the static method XToTileX() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.


getNumXTiles

public int getNumXTiles()
Returns the number of tiles along the tile grid in the horizontal direction.

This method is implemented in terms of the static method XToTileX() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.

Specified by:
getNumXTiles in interface RenderedImage

getMinTileY

public int getMinTileY()
Returns the vertical index of the top-most row of tiles.

This method is implemented in terms of the static method YToTileY() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.

Specified by:
getMinTileY in interface RenderedImage

getMaxTileY

public int getMaxTileY()
Returns the vertical index of the bottom-most row of tiles.

This method is implemented in terms of the static method YToTileY() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.


getNumYTiles

public int getNumYTiles()
Returns the number of tiles along the tile grid in the vertical direction.

This method is implemented in terms of the static method YToTileY() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.

Specified by:
getNumYTiles in interface RenderedImage

XToTileX

public static int XToTileX(int x,
                           int tileGridXOffset,
                           int tileWidth)
Converts a pixel's X coordinate into a horizontal tile index relative to a given tile grid layout specified by its X offset and tile width.

If tileWidth < 0, the results of this method are undefined. If tileWidth == 0, an ArithmeticException will be thrown.

Throws:
ArithmeticException - If tileWidth == 0.

YToTileY

public static int YToTileY(int y,
                           int tileGridYOffset,
                           int tileHeight)
Converts a pixel's Y coordinate into a vertical tile index relative to a given tile grid layout specified by its Y offset and tile height.

If tileHeight < 0, the results of this method are undefined. If tileHeight == 0, an ArithmeticException will be thrown.

Throws:
ArithmeticException - If tileHeight == 0.

XToTileX

public int XToTileX(int x)
Converts a pixel's X coordinate into a horizontal tile index. No attempt is made to detect out-of-range coordinates.

This method is implemented in terms of the static method XToTileX() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.

Parameters:
x - the X coordinate of a pixel.
Returns:
the X index of the tile containing the pixel.
Throws:
ArithmeticException - If the tile width of this image is 0.

YToTileY

public int YToTileY(int y)
Converts a pixel's Y coordinate into a vertical tile index. No attempt is made to detect out-of-range coordinates.

This method is implemented in terms of the static method YToTileY() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.

Parameters:
y - the Y coordinate of a pixel.
Returns:
the Y index of the tile containing the pixel.
Throws:
ArithmeticException - If the tile height of this image is 0.

tileXToX

public static int tileXToX(int tx,
                           int tileGridXOffset,
                           int tileWidth)
Converts a horizontal tile index into the X coordinate of its upper left pixel relative to a given tile grid layout specified by its X offset and tile width.

tileYToY

public static int tileYToY(int ty,
                           int tileGridYOffset,
                           int tileHeight)
Converts a vertical tile index into the Y coordinate of its upper left pixel relative to a given tile grid layout specified by its Y offset and tile height.

tileXToX

public int tileXToX(int tx)
Converts a horizontal tile index into the X coordinate of its upper left pixel. No attempt is made to detect out-of-range indices.

This method is implemented in terms of the static method tileXToX() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.

Parameters:
tx - the horizontal index of a tile.
Returns:
the X coordinate of the tile's upper left pixel.

tileYToY

public int tileYToY(int ty)
Converts a vertical tile index into the Y coordinate of its upper left pixel. No attempt is made to detect out-of-range indices.

This method is implemented in terms of the static method tileYToY() applied to the values returned by primitive layout accessors and so does not need to be implemented by subclasses.

Parameters:
ty - the vertical index of a tile.
Returns:
the Y coordinate of the tile's upper left pixel.

getTileRect

public Rectangle getTileRect(int tileX,
                             int tileY)
Returns a Rectangle indicating the active area of a given tile. The Rectangle is defined as the intersection of the tile area and the image bounds. No attempt is made to detect out-of-range indices; tile indices lying completely outside of the image will result in returning an empty Rectangle (width and/or height less than or equal to 0).

This method is implemented in terms of the primitive layout accessors and so does not need to be implemented by subclasses.

Parameters:
tileX - The X index of the tile.
tileY - The Y index of the tile.
Returns:
A Rectangle

getSampleModel

public SampleModel getSampleModel()
Returns the SampleModel of the image. The default implementation returns the corresponding instance variable.
Specified by:
getSampleModel in interface RenderedImage

getColorModel

public ColorModel getColorModel()
Returns the ColorModel of the image. The default implementation returns the corresponding instance variable.
Specified by:
getColorModel in interface RenderedImage

getDefaultColorModel

public static ColorModel getDefaultColorModel(int dataType,
                                              int numBands)
Returns a ComponentColorModel created based on the indicated dataType and numBands.

The dataType must be one of DataBuffer's TYPE_BYTE, TYPE_USHORT, TYPE_INT, TYPE_FLOAT, or TYPE_DOUBLE.

The numBands may range from 1 to 4, with the following ColorSpace and alpha settings:

The transparency is set to Transparency.TRANSLUCENT if alpha is used and to Transparency.OPAQUE otherwise.

All other inputs result in a null return value.

Parameters:
dataType - The data type of the ColorModel.
numBands - The number of bands of the pixels the created ColorModel is going to work with.
Since:
JAI 1.1

createColorModel

public static ColorModel createColorModel(SampleModel sm)
Creates a ColorModel that may be used with the specified SampleModel. If a suitable ColorModel cannot be found, this method returns null.

Suitable ColorModels are guaranteed to exist for all instances of ComponentSampleModel whose dataType is not DataBuffer.TYPE_SHORT and with no more than 4 bands. A ComponentColorModel of either type CS_GRAY or CS_sRGB is returned.

For 1- and 3- banded SampleModels, the returned ColorModel will be opaque. For 2- and 4-banded SampleModels, the output will use alpha transparency.

Additionally, an instance of DirectColorModel will be created for instances of SinglePixelPackedSampleModel with no more than 4 bands.

Finally, an instance of IndexColorModel will be created for instances of MultiPixelPackedSampleModel with a single band and a pixel bit stride of unity. This represents the case of binary data.

This method is intended as an useful utility for the creation of simple ColorModels for some common cases. In more complex situations, it may be necessary to instantiate the appropriate ColorModels directly.

Returns:
An instance of ColorModel that is suitable for the supplied SampleModel, or null.
Throws:
IllegalArgumentException - If sm is null.

getTileFactory

public TileFactory getTileFactory()
Returns the value of the instance variable tileFactory.
Since:
JAI 1.1.2

getNumSources

public int getNumSources()
Returns the number of immediate PlanarImage sources this image has. If this image has no source, this method returns 0.

getSources

public Vector getSources()
Returns this image's immediate source(s) in a Vector. If this image has no source, this method returns null.
Specified by:
getSources in interface RenderedImage

getSource

public PlanarImage getSource(int index)
Deprecated. as of JAI 1.1. Use getSourceImage().

Returns the immediate source indicated by the index. If there is no source corresponding to the specified index, this method throws an exception.
Parameters:
index - The index of the desired source.
Returns:
A PlanarImage source.
Throws:
ArrayIndexOutOfBoundsException - If this image has no immediate source, or if the index is negative or greater than the maximum source index.
See Also:
getSourceImage(int)

setSources

protected void setSources(List sourceList)
Sets the list of sources from a given List of PlanarImages. All of the existing sources are discarded. Any RenderedImage sources in the supplied list are wrapped using wrapRenderedImage(). The list of sinks of each prior PlanarImage source and of each current unwrapped PlanarImage source is adjusted as necessary such that this image is a sink of all such current sources but is removed as a sink of all such prior sources which are not also current.
Parameters:
sourceList - a List of PlanarImages.
Throws:
IllegalArgumentException - If sourceList is null or contains any null elements.

removeSources

protected void removeSources()
Removes all the sources of this image. This image is removed from the list of sinks of any prior PlanarImages sources.

getSourceImage

public PlanarImage getSourceImage(int index)
Returns the immediate source indicated by the index. If there is no source corresponding to the specified index, this method throws an exception.
Parameters:
index - The index of the desired source.
Returns:
A PlanarImage source.
Throws:
ArrayIndexOutOfBoundsException - If this image has no immediate source, or if the index is negative or greater than the maximum source index.
Since:
JAI 1.1

getSourceObject

public Object getSourceObject(int index)
Returns the immediate source indicated by the index. If there is no source corresponding to the specified index, this method throws an exception.
Parameters:
index - The index of the desired source.
Returns:
An Object source.
Throws:
ArrayIndexOutOfBoundsException - If this image has no immediate source, or if the index is negative or greater than the maximum source index.
Since:
JAI 1.1

addSource

protected void addSource(Object source)
Adds an Object source to the list of sources. If the source is a RenderedImage it is wrapped using wrapRenderedImage(). If the unwrapped source is a PlanarImage then this image is added to its list of sinks.
Parameters:
source - An Object to be added as an immediate source of this image.
Throws:
IllegalArgumentException - If source is null.
Since:
JAI 1.1

setSource

protected void setSource(Object source,
                         int index)
Sets an immediate source of this image. The source to be replaced with the new input Object is referred to by its index. This image must already have a source corresponding to the specified index. If the source is a RenderedImage it is wrapped using wrapRenderedImage(). If the unwrapped source is a PlanarImage then this image is added to its list of sinks. If a PlanarImage source previously existed at this index, this image is removed from its list of sinks.
Parameters:
source - A Object source to be set.
index - The index of the source to be set.
Throws:
ArrayIndexOutOfBoundsException - If this image has no immediate source, or if there is no source corresponding to the index value.
IllegalArgumentException - If source is null.
Since:
JAI 1.1

removeSource

protected boolean removeSource(Object source)
Removes an Object source from the list of sources. If the source is a PlanarImage then this image is removed from its list of sinks.
Parameters:
source - The Object source to be removed.
Returns:
true if the element was present, false otherwise.
Throws:
IllegalArgumentException - If source is null.
Since:
JAI 1.1

getSinks

public Vector getSinks()
Returns a Vector containing the currently available PlanarImage sinks of this image (images for which this image is a source), or null if no sinks are present.

Sinks are stored using weak references. This means that the set of sinks may change between calls to getSinks() if the garbage collector happens to identify a sink as not otherwise reachable (reachability is discussed in the class comments for this class).

Since the pool of sinks may change as garbage collection occurs, PlanarImage does not implement either a getSink(int index) or a getNumSinks() method. Instead, the caller must call getSinks(), which returns a Vector of normal references. As long as the returned Vector is referenced from user code, the images it references are reachable and may be reliably accessed.


addSink

public boolean addSink(Object sink)
Adds an Object sink to the list of sinks.
Returns:
true if the element was added, false otherwise.
Throws:
IllegalArgumentException - if sink is null.
Since:
JAI 1.1

removeSink

public boolean removeSink(Object sink)
Removes an Object sink from the list of sinks.
Returns:
true if the element was present, false otherwise.
Throws:
IllegalArgumentException - if sink is null.
Since:
JAI 1.1

addSink

protected void addSink(PlanarImage sink)
Deprecated. as of JAI 1.1. Use addSink(Object) instead.

Adds a PlanarImage sink to the list of sinks.
Parameters:
sink - A PlanarImage to be added as a sink.
Throws:
IllegalArgumentException - If sink is null.

removeSink

protected boolean removeSink(PlanarImage sink)
Deprecated. as of JAI 1.1. Use removeSink(Object) instead.

Removes a PlanarImage sink from the list of sinks.
Parameters:
sink - A PlanarImage sink to be removed.
Returns:
true if the element was present, false otherwise.
Throws:
IllegalArgumentException - If sink is null.
IndexOutOfBoundsException - If sink is not in the sink list.

removeSinks

public void removeSinks()
Removes all the sinks of this image.

getProperties

protected Hashtable getProperties()
Returns the internal Hashtable containing the image properties by reference.

setProperties

protected void setProperties(Hashtable properties)
Sets the Hashtable containing the image properties to a given Hashtable. The Hashtable is incorporated by reference and must not be altered by other classes after this method is called.

getProperty

public Object getProperty(String name)
Gets a property from the property set of this image. If the property name is not recognized, java.awt.Image.UndefinedProperty will be returned.
Specified by:
getProperty in interface PropertySource
Parameters:
name - the name of the property to get, as a String.
Returns:
A reference to the property Object, or the value java.awt.Image.UndefinedProperty.
Throws:
IllegalArgumentException - if propertyName is null.

getPropertyClass

public Class getPropertyClass(String name)
Returns the class expected to be returned by a request for the property with the specified name. If this information is unavailable, null will be returned.
Specified by:
getPropertyClass in interface PropertySource
Returns:
The Class expected to be return by a request for the value of this property or null.
Throws:
IllegalArgumentException - if name is null.
Since:
JAI 1.1

setProperty

public void setProperty(String name,
                        Object value)
Sets a property on a PlanarImage. Some PlanarImage subclasses may ignore attempts to set properties.
Specified by:
setProperty in interface WritablePropertySource
Parameters:
name - a String containing the property's name.
value - the property, as a general Object.
Throws:
IllegalArgumentException - If name or value is null.

removeProperty

public void removeProperty(String name)
Removes the named property from the PlanarImage. Some PlanarImage subclasses may ignore attempts to remove properties.
Specified by:
removeProperty in interface WritablePropertySource
Throws:
IllegalArgumentException - if name is null.
Since:
JAI 1.1

getPropertyNames

public String[] getPropertyNames()
Returns a list of property names that are recognized by this image or null if none are recognized.
Specified by:
getPropertyNames in interface PropertySource
Returns:
an array of Strings containing valid property names or null.

getPropertyNames

public String[] getPropertyNames(String prefix)
Returns an array of Strings recognized as names by this property source that begin with the supplied prefix. If no property names match, null will be returned. The comparison is done in a case-independent manner.

The default implementation calls getPropertyNames() and searches the list of names for matches.

Specified by:
getPropertyNames in interface PropertySource
Returns:
an array of Strings giving the valid property names.
Throws:
IllegalArgumentException - If prefix is null.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Add a PropertyChangeListener to the listener list. The listener is registered for all properties.
Specified by:
addPropertyChangeListener in interface PropertyChangeEmitter
Since:
JAI 1.1

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener listener)
Add a PropertyChangeListener for a specific property. The listener will be invoked only when a call on firePropertyChange names that specific property. The case of the name is ignored.
Specified by:
addPropertyChangeListener in interface PropertyChangeEmitter
Since:
JAI 1.1

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Remove a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.
Specified by:
removePropertyChangeListener in interface PropertyChangeEmitter
Since:
JAI 1.1

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener listener)
Remove a PropertyChangeListener for a specific property. The case of the name is ignored.
Specified by:
removePropertyChangeListener in interface PropertyChangeEmitter
Since:
JAI 1.1

addTileComputationListener

public void addTileComputationListener(TileComputationListener listener)
Adds a TileComputationListener to the list of registered TileComputationListeners. This listener will be notified when tiles requested via queueTiles() have been computed.
Parameters:
listener - The TileComputationListener to register.
Throws:
IllegalArgumentException - if listener is null.
Since:
JAI 1.1

removeTileComputationListener

public void removeTileComputationListener(TileComputationListener listener)
Removes a TileComputationListener from the list of registered TileComputationListeners.
Parameters:
listener - The TileComputationListener to unregister.
Throws:
IllegalArgumentException - if listener is null.
Since:
JAI 1.1

getTileComputationListeners

public TileComputationListener[] getTileComputationListeners()
Retrieves a snapshot of the set of all registered TileComputationListeners as of the moment this method is invoked.
Returns:
All TileComputationListeners or null if there are none.
Since:
JAI 1.1

getSplits

public void getSplits(IntegerSequence xSplits,
                      IntegerSequence ySplits,
                      Rectangle rect)
Within a given rectangle, store the list of tile seams of both X and Y directions into the corresponding split sequence.
Parameters:
xSplits - An IntegerSequence to which the tile seams in the X direction are to be added.
ySplits - An IntegerSequence to which the tile seams in the Y direction are to be added.
rect - The rectangular region of interest.
Throws:
IllegalArgumentException - If xSplits, ySplits, or rect is null.

getTileIndices

public Point[] getTileIndices(Rectangle region)
Returns an array containing the indices of all tiles which overlap the specified Rectangle. If the Rectangle does not intersect the image bounds then null will be returned. If an array is returned, it will be ordered in terms of the row major ordering of its contained tile indices. If the specified Rectangle is null, the tile indicies for the entire image will be returned.
Parameters:
region - The Rectangle of interest.
Returns:
An array of the indices of overlapping tiles or null if region does not intersect the image bounds.
Since:
JAI 1.1

overlapsMultipleTiles

public boolean overlapsMultipleTiles(Rectangle rect)
Returns true if and only if the intersection of the specified Rectangle with the image bounds overlaps more than one tile.
Throws:
IllegalArgumentException - if rect is null.

createWritableRaster

protected final WritableRaster createWritableRaster(SampleModel sampleModel,
                                                    Point location)
Creates a WritableRaster with the specified SampleModel and location. If tileFactory is non-null, it will be used to create the WritableRaster; otherwise RasterFactory.createWritableRaster(SampleModel,Point) will be used.
Parameters:
sampleModel - The SampleModel to use.
location - The origin of the WritableRaster; if null, (0, 0) will be used.
Throws:
IllegalArgumentException - if sampleModel is null.
Since:
JAI 1.1.2

getData

public Raster getData()
Returns the entire image in a single Raster. For images with multiple tiles this will require creating a new Raster and copying data from multiple tiles into it ("cobbling").

The returned Raster is semantically a copy. This means that subsequent updates to this image will not be reflected in the returned Raster. For non-writable (immutable) images, the returned value may be a reference to the image's internal data. The returned Raster should be considered non-writable; any attempt to alter its pixel data (such as by casting it to a WritableRaster or obtaining and modifying its DataBuffer) may result in undefined behavior. The copyData method should be used if the returned Raster is to be modified.

For a very large image, more than Integer.MAX_VALUE entries could be required in the returned Raster's underlying data array. Since the Java language does not permit such an array, an IllegalArgumentException will be thrown.

Specified by:
getData in interface RenderedImage
Returns:
A Raster containing the entire image data.
Throws:
IllegalArgumentException - If the size of the returned data is too large to be stored in a single Raster.

getData

public Raster getData(Rectangle region)
Returns a specified region of this image in a Raster.

The returned Raster is semantically a copy. This means that subsequent updates to this image will not be reflected in the returned Raster. For non-writable (immutable) images, the returned value may be a reference to the image's internal data. The returned Raster should be considered non-writable; any attempt to alter its pixel data (such as by casting it to a WritableRaster or obtaining and modifying its DataBuffer) may result in undefined behavior. The copyData method should be used if the returned Raster is to be modified.

The region of the image to be returned is specified by a Rectangle. This region may go beyond this image's boundary. If so, the pixels in the areas outside this image's boundary are left unset. Use getExtendedData if a specific extension policy is required.

The region parameter may also be null, in which case the entire image data is returned in the Raster.

If region is non-null but does not intersect the image bounds at all, an IllegalArgumentException will be thrown.

It is possible to request a region of an image that would require more than Integer.MAX_VALUE entries in the returned Raster's underlying data array. Since the Java language does not permit such an array, an IllegalArgumentException will be thrown.

Specified by:
getData in interface RenderedImage
Parameters:
region - The rectangular region of this image to be returned, or null.
Returns:
A Raster containing the specified image data.
Throws:
IllegalArgumentException - If the region does not intersect the image bounds.
IllegalArgumentException - If the size of the returned data is too large to be stored in a single Raster.

copyData

public WritableRaster copyData()
Copies the entire image into a single raster.

copyData

public WritableRaster copyData(WritableRaster raster)
Copies an arbitrary rectangular region of this image's pixel data into a caller-supplied WritableRaster. The region to be copied is defined as the boundary of the WritableRaster, which can be obtained by calling WritableRaster.getBounds().

The supplied WritableRaster may have a region that extends beyond this image's boundary, in which case only pixels in the part of the region that intersects this image are copied. The areas outside of this image's boundary are left untouched.

The supplied WritableRaster may also be null, in which case the entire image is copied into a newly-created WritableRaster with a SampleModel that is compatible with that of this image.

Specified by:
copyData in interface RenderedImage
Parameters:
raster - A WritableRaster to hold the copied pixel data of this image.
Returns:
A reference to the supplied WritableRaster, or to a new WritableRaster if the supplied one was null.

copyExtendedData

public void copyExtendedData(WritableRaster dest,
                             BorderExtender extender)
Copies an arbitrary rectangular region of the RenderedImage into a caller-supplied WritableRaster. The portion of the supplied WritableRaster that lies outside of the bounds of the image is computed by calling the given BorderExtender. The supplied WritableRaster must have a SampleModel that is compatible with that of the image.
Parameters:
dest - a WritableRaster to hold the returned portion of the image.
extender - an instance of BorderExtender.
Throws:
IllegalArgumentException - If dest or extender is null.

getExtendedData

public Raster getExtendedData(Rectangle region,
                              BorderExtender extender)
Returns a copy of an arbitrary rectangular region of this image in a Raster. The portion of the rectangle of interest ouside the bounds of the image will be computed by calling the given BorderExtender. If the region falls entirely within the image, extender will not be used in any way. Thus it is possible to use a null value for extender when it is known that no actual extension will be required.

The returned Raster should be considered non-writable; any attempt to alter its pixel data (such as by casting it to a WritableRaster or obtaining and modifying its DataBuffer) may result in undefined behavior. The copyExtendedData method should be used if the returned Raster is to be modified.

Parameters:
region - the region of the image to be returned.
extender - an instance of BorderExtender, used only if the region exceeds the image bounds, or null.
Returns:
a Raster containing the extended data.
Throws:
IllegalArgumentException - If region is null.
IllegalArgumentException - If the region exceeds the image bounds and extender is null.

getAsBufferedImage

public BufferedImage getAsBufferedImage(Rectangle rect,
                                        ColorModel cm)
Returns a copy of this image as a BufferedImage. A subarea of the image may be copied by supplying a Rectangle parameter; if it is set to null, the entire image is copied. The supplied Rectangle will be clipped to the image bounds. The image's ColorModel may be overridden by supplying a non-null second argument. The resulting ColorModel must be non-null and appropriate for the image's SampleModel.

The resulting BufferedImage will contain the full requested area, but will always have its top-left corner translated (0, 0) as required by the BufferedImage interface.

Parameters:
rect - The Rectangle of the image to be copied, or null to indicate that the entire image is to be copied.
cm - A ColorModel used to override this image's ColorModel, or null. The caller is responsible for supplying a ColorModel that is compatible with the image's SampleModel.
Throws:
IllegalArgumentException - If an incompatible, non-null ColorModel is supplied.
IllegalArgumentException - If no ColorModel is supplied, and the image ColorModel is null.

getAsBufferedImage

public BufferedImage getAsBufferedImage()
Returns a copy of the entire image as a BufferedImage. The image's ColorModel must be non-null, and appropriate for the image's SampleModel.
See Also:
BufferedImage

getGraphics

public Graphics getGraphics()
Returns a Graphics object that may be used to draw into this image. By default, an IllegalAccessError is thrown. Subclasses that support such drawing, such as TiledImage, may override this method to return a suitable Graphics object.

getTile

public abstract Raster getTile(int tileX,
                               int tileY)
Returns tile (tileX, tileY) as a Raster. Note that tileX and tileY are indices into the tile array, not pixel locations.

Subclasses must override this method to return a non-null value for all tile indices between getMinTile{X,Y} and getMaxTile{X,Y}, inclusive. Tile indices outside of this region should result in a return value of null.

Specified by:
getTile in interface RenderedImage
Parameters:
tileX - The X index of the requested tile in the tile array.
tileY - The Y index of the requested tile in the tile array.

getTiles

public Raster[] getTiles(Point[] tileIndices)
Returns the Rasters indicated by the tileIndices array. This call allows certain PlanarImage subclasses such as OpImage to take advantage of the knowledge that multiple tiles are requested at once.
Parameters:
tileIndices - An array of Points representing tile indices.
Returns:
An array of Raster containing the tiles corresponding to the given tile indices.
Throws:
IllegalArgumentException - If tileIndices is null.

getTiles

public Raster[] getTiles()
Computes and returns all tiles in the image. The tiles are returned in a sequence corresponding to the row-major order of their respective tile indices. The returned array may of course be ignored, e.g., in the case of a subclass which caches the tiles and the intent is to force their computation.

queueTiles

public TileRequest queueTiles(Point[] tileIndices)
Queues a list of tiles for computation. Registered listeners will be notified after each tile has been computed.

The TileScheduler of the default instance of the JAI class is used to process the tiles. If this TileScheduler has a positive parallelism this method will be non-blocking. The event source parameter passed to such listeners will be the TileScheduler and the image parameter will be this image.

Parameters:
tileIndices - A list of tile indices indicating which tiles to schedule for computation.
Throws:
IllegalArgumentException - If tileIndices is null.
Since:
JAI 1.1

cancelTiles

public void cancelTiles(TileRequest request,
                        Point[] tileIndices)
Issue an advisory cancellation request to nullify processing of the indicated tiles. It is legal to implement this method as a no-op.

The cancellation request is forwarded to the TileScheduler of the default instance of the JAI class.

Parameters:
request - The request for which tiles are to be cancelled.
tileIndices - The tiles to be cancelled; may be null. Any tiles not actually in the TileRequest will be ignored.
Throws:
IllegalArgumentException - If request is null.
Since:
JAI 1.1

prefetchTiles

public void prefetchTiles(Point[] tileIndices)
Hints that the given tiles might be needed in the near future. Some implementations may spawn a thread or threads to compute the tiles while others may ignore the hint.

The TileScheduler of the default instance of the JAI class is used to prefetch the tiles. If this TileScheduler has a positive prefetch parallelism this method will be non-blocking.

Parameters:
tileIndices - A list of tile indices indicating which tiles to prefetch.
Throws:
IllegalArgumentException - If tileIndices is null.

dispose

public void dispose()
Provides a hint that an image will no longer be accessed from a reference in user space. The results are equivalent to those that occur when the program loses its last reference to this image, the garbage collector discovers this, and finalize is called. This can be used as a hint in situations where waiting for garbage collection would be overly conservative.

PlanarImage defines this method to remove the image being disposed from the list of sinks in all of its source images. Subclasses should call super.dispose() in their dispose methods, if any.

The results of referencing an image after a call to dispose() are undefined.


finalize

protected void finalize()
                 throws Throwable
Performs cleanup prior to garbage collection.

PlanarImage defines this method to invoke the dispose() method.

Overrides:
finalize in class Object
Throws:
Throwable - if an error occurs in the garbage collector.

toString

public String toString()
Returns a String which includes the basic information of this image.
Overrides:
toString in class Object
Since:
JAI 1.1

getImageID

public Object getImageID()
Returns a unique identifier (UID) for this PlanarImage. This UID may be used when the potential redundancy of the value returned by the hashCode() method is unacceptable. An example of this is in generating a key for storing image tiles in a cache.