Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

javax.media.jai
Class OpImage

java.lang.Object
  |
  +--javax.media.jai.PlanarImage
        |
        +--javax.media.jai.OpImage
All Implemented Interfaces:
ImageJAI, PropertyChangeEmitter, PropertySource, RenderedImage, WritablePropertySource
Direct Known Subclasses:
AreaOpImage, GeometricOpImage, PointOpImage, SourcelessOpImage, StatisticsOpImage, UntiledOpImage
public abstract class OpImage
extends PlanarImage

This is the base class for all image operations. It provides a home for information and functionalities common to all the op-image classes, and implements various utility methods that may be useful to a specific operation. Image operations may be divided into different categories based on their characteristics. A subclass, extending OpImage, represents a category and implements methods unique and common to those operations. Each individual operator should extend the subclass that represents the specific category that operator belongs to.

The layout variables of an OpImage are inherited from the PlanarImage superclass. The layout should be set when the OpImage is constructed. Each subclass must set the appropriate layout variables and supply them via the ImageLayout argument at construction time. This class simply modifies these settings as described in the OpImage constructor comments before forwarding the layout to the PlanarImage constructor. If a subclass needs to modify any of the layout settings subsequent to invoking its superclass constructors it should use the setImageLayout() method defined in PlanarImage in preference to setting the layout variables directly.

A RenderedImage's pixel data type and number of bands are defined by its SampleModel, while the ColorModel translates the pixel data into color/alpha components in the specific ColorSpace that is associated with the ColorModel.

By default, the operators provided by Java Advanced Imaging (JAI) operate on the image's pixel data only. That is, the computations are performed on the data described by the image's SampleModel. No color translation is performed prior to the actual computation by the operator, regardless of the type of the ColorModel an image has. If a user intends to have an operation performed on the color data, he must perform the color translation explicitly prior to invoking the operation.

There are those operators that specifically deal with the color/alpha data of an image. Such an operator must state its behavior in its OperationDescriptor explicitly and explain its intended usage of the image's color/alpha component data. In such cases, the image's ColorModel as well as the associated ColorSpace should be considered.

However there are certain operations, the results of which are incorrect when the source has colormapped imagery, i.e. the source has an IndexColorModel, and the computations are performed on the image's non color transformed pixel data. In JAI, such operations are those that are implemented as subclasses of AreaOpImage, GeometricOpImage, and the "format" operation. These operations set the JAI.KEY_REPLACE_INDEX_COLOR_MODEL RenderingHint to true, thus ensuring that the operations are performed correctly on the colormapped imagery, not treating the indices into the color map as pixel data.

The tile cache and scheduler are handled by this class. JAI provides a default implementation for TileCache and TileScheduler. However, they may be overriden by each application. An OpImage may share a common cache with other OpImages, or it may have a private cache of its own. To override an existing cache, use the setTileCache method; an input argument of null indicates that this image should not have a tile cache.

The getTile method may be used to request a tile of the image. The default implementation of this method in this class first checks whether the requested tile is in the tile cache, and if not, uses the default TileScheduler to schedule the tile for computation. Once the tile has been computed, it is added to the cache and returned as a Raster.

The JAI tile scheduler assumes that when a request is made to schedule a tile for computation via the scheduleTile method, that tile is not currently in the cache. To avoid a cycle, it calls OpImage.computeTile for the actual tile computation.

The default implementation of the computeTile method in this class first creates a new Raster to represent the requested tile, then calls one of the two computeRect methods to compute the actual pixel values and store the result in the DataBuffer of the Raster.

Two variants of the computeRect method exist.

The first (with input arguments Raster[], WritableRaster, and Rectangle) is used when the OpImage is constructed with the cobbleSources argument set to true. This indicates that the source data must be cobbled into a single Raster and that all the necessary source data are provided in order to compute the rectangular region of the destination image. The source Raster array contains one entry for each source image.

The second (with input arguments PlanarImage[], WritableRaster, and Rectangle) is used when the OpImage is constructed with the cobbleSources argument set to false. This indicates that the source data are not cobbled into a single Raster; instead an array of PlanarImages, one for each source, supply the source data and each image is responsible for performing its own data accesses. This variant is generally useful if iterators are to be used for the underlying implementation of accessing the image data.

The two computeRect methods are not abstract because normally only one needs to be implemented by the subclass depending on the cobbleSources value. The default implementation of these two methods in this class throws a RuntimeException.

Every operator who follows the above default implementation must supply an overridden version of at least one of the computeRect method variants, and specify which one is to be called via the cobbleSources argument of the constructor, or an exception will be thrown at run time.

If a subclass overrides getTile not to call computeTile, does not use the JAI implementation of TileScheduler, overrides computeTile not to call computeRect, or does not follow the above default implementation in any way, then it may need to handle issues such as tile caching, multi-threading, and etc. by itself and may not need to override some of the methods described above. In some cases, some of the methods or variables are even irrelevant. However, subclasses should be careful when not following the default path for computing a tile. Most importantly, when a subclass overrides getTile, it should also override computeTile.

To request multiple tiles at a time, it is preferable to call the getTiles method with a complete list of the requested tiles' indices, than to call getTile once per tile. The implementation of getTiles in this class is optimized using multi-threading so that multiple tiles are computed simultaneously.

See Also:
PlanarImage, AreaOpImage, GeometricOpImage, PointOpImage, StatisticsOpImage, SourcelessOpImage

Field Summary
protected  TileCache cache
          The cache object used to cache this image's tiles.
protected  boolean cobbleSources
          Indicates which one of the two computeRect variants should be called by the computeTile method.
static int OP_COMPUTE_BOUND
          A constant indicating that an operation is likely to spend its time mainly performing computation.
static int OP_IO_BOUND
          A constant indicating that an operation is likely to spend its time mainly performing local I/O.
static int OP_NETWORK_BOUND
          A constant indicating that an operation is likely to spend its time mainly performing network I/O.
protected  Object tileCacheMetric
          Metric used to produce an ordered list of tiles.
protected  TileRecycler tileRecycler
          A TileRecycler for use in createTile().
 
Fields inherited from class javax.media.jai.PlanarImage
colorModel, eventManager, height, minX, minY, properties, sampleModel, tileFactory, tileGridXOffset, tileGridYOffset, tileHeight, tileWidth, width
 
Constructor Summary
OpImage(Vector sources, ImageLayout layout, Map configuration, boolean cobbleSources)
          Constructor.
 
Method Summary
protected  void addTileToCache(int tileX, int tileY, Raster tile)
          Adds a tile to the tile cache.
 void cancelTiles(TileRequest request, Point[] tileIndices)
          Issue an advisory cancellation request to nullify processing of the indicated tiles via the TileScheduler for this image.
protected  void computeRect(PlanarImage[] sources, WritableRaster dest, Rectangle destRect)
          Computes a rectangle of output, given PlanarImage sources.
protected  void computeRect(Raster[] sources, WritableRaster dest, Rectangle destRect)
          Computes a rectangle of output, given Raster sources.
 boolean computesUniqueTiles()
          Returns true if the OpImage returns an unique Raster object every time computeTile is called.
 Raster computeTile(int tileX, int tileY)
          Computes the image data of a tile.
protected  WritableRaster createTile(int tileX, int tileY)
          Creates a WritableRaster at the given tile grid position.
 void dispose()
          Uncaches all tiles and calls super.dispose().
static int getExpandedNumBands(SampleModel sampleModel, ColorModel colorModel)
          Deprecated. as of JAI 1.1.
protected  RasterFormatTag[] getFormatTags()
          Returns the image's format tags to be used with a RasterAccessor.
 int getOperationComputeType()
          Returns one of OP_COMPUTE_BOUND, OP_IO_BOUND, or OP_NETWORK_BOUND to indicate how the operation is likely to spend its time.
 Raster getTile(int tileX, int tileY)
          Returns a tile of this image as a Raster.
 TileCache getTileCache()
          Returns the tile cache object of this image by reference.
 Object getTileCacheMetric()
          Returns the tileCacheMetric instance variable by reference.
 Point[] getTileDependencies(int tileX, int tileY, int sourceIndex)
          Returns a list of indices of the tiles of a given source image that may be required in order to compute a given tile.
protected  Raster getTileFromCache(int tileX, int tileY)
          Retrieves a tile from the tile cache.
 TileRecycler getTileRecycler()
          Returns the value of the instance variable tileRecycler.
 Raster[] getTiles(Point[] tileIndices)
          Computes the tiles indicated by the given tile indices.
 boolean hasExtender(int sourceIndex)
          Deprecated. as of JAI 1.1.
 Point2D mapDestPoint(Point2D destPt, int sourceIndex)
          Computes the position in the specified source that best matches the supplied destination image position.
abstract  Rectangle mapDestRect(Rectangle destRect, int sourceIndex)
          Returns a conservative estimate of the region of a specified source that is required in order to compute the pixels of a given destination rectangle.
 Point2D mapSourcePoint(Point2D sourcePt, int sourceIndex)
          Computes the position in the destination that best matches the supplied source image position.
abstract  Rectangle mapSourceRect(Rectangle sourceRect, int sourceIndex)
          Returns a conservative estimate of the destination region that can potentially be affected by the pixels of a rectangle of a given source.
 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.
protected  void recycleTile(Raster tile)
          A tile recycling convenience method.
 void setTileCache(TileCache cache)
          Sets the tile cache object of this image.
protected static Vector vectorize(RenderedImage image)
          Stores a RenderedImage in a Vector.
protected static Vector vectorize(RenderedImage image1, RenderedImage image2)
          Stores two RenderedImages in a Vector.
protected static Vector vectorize(RenderedImage image1, RenderedImage image2, RenderedImage image3)
          Stores three RenderedImages in a Vector.
 
Methods inherited from class javax.media.jai.PlanarImage
addPropertyChangeListener, addPropertyChangeListener, addSink, addSink, addSource, addTileComputationListener, 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, getTileWidth, getWidth, overlapsMultipleTiles, 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
 

Field Detail

OP_COMPUTE_BOUND

public static final int OP_COMPUTE_BOUND
A constant indicating that an operation is likely to spend its time mainly performing computation.

OP_IO_BOUND

public static final int OP_IO_BOUND
A constant indicating that an operation is likely to spend its time mainly performing local I/O.

OP_NETWORK_BOUND

public static final int OP_NETWORK_BOUND
A constant indicating that an operation is likely to spend its time mainly performing network I/O.

cache

protected transient TileCache cache
The cache object used to cache this image's tiles. It may refer to a common cache shared by many OpImages or a private cache for this image only. If it is null, it indicates that this image does not have a tile cache.

tileCacheMetric

protected Object tileCacheMetric
Metric used to produce an ordered list of tiles. This determines which tiles are removed from the cache first if a memory control operation is required.
Since:
JAI 1.1

cobbleSources

protected boolean cobbleSources
Indicates which one of the two computeRect variants should be called by the computeTile method. If it is true, computeRect expects contiguous sources.

tileRecycler

protected TileRecycler tileRecycler
A TileRecycler for use in createTile(). May be null. This field is set by the configuration map passed to .
Since:
JAI 1.1.2
Constructor Detail

OpImage

public OpImage(Vector sources,
               ImageLayout layout,
               Map configuration,
               boolean cobbleSources)
Constructor.

The image's layout is encapsulated in the layout argument. The variables of the image layout which are not set in the layout parameter are copied from the first source if sources are available. In the case of the ColorModel, the copy is performed if and only if the ColorModel is compatible with the destination SampleModel and is not set by another higher priority mechanism as described presently.

Assuming that there is at least one source, the image's ColorModel will be set by the first applicable means in the following priority-ordered list:

  1. null ColorModel from ImageLayout;
  2. Non-null ColorModel from ImageLayout if compatible with SampleModel in ImageLayout or if SampleModel in ImageLayout is null;
  3. Value returned by ColorModelFactory set via the JAI.KEY_COLOR_MODEL_FACTORY configuration variable if compatible with SampleModel;
  4. An instance of a non-IndexColorModel (or null if no compatible non-IndexColorModel could be generated), if the source has an IndexColorModel and JAI.KEY_REPLACE_INDEX_COLOR_MODEL is Boolean.TRUE;
  5. ColorModel of first source if compatible with SampleModel;
  6. Value returned by default method specified by the JAI.KEY_DEFAULT_COLOR_MODEL_METHOD configuration variable if JAI.KEY_DEFAULT_COLOR_MODEL_ENABLED is Boolean.TRUE.
If it is not possible to set the ColorModel by any of these means it will remain null.

The image's tile dimensions will be set by the first applicable means in the following priority-ordered list. Note that each tile dimension, the tileWidth and the tileHeight, is considered independently :
  1. Tile dimension set in the ImageLayout (either by the user or the operator itself);
  2. Tile dimension of source, if source is non-null. The tile dimension will be clamped to the minimum of that of the source tile dimension and the image's corresponding dimension;
  3. Non-null default tile size returned by JAI.getDefaultTileSize(), if the corresponding image dimension is at least double the default tile size;
  4. The dimensions of the image itself;

The sources contains a list of immediate sources of this image. Elements in the list may not be null. If this image has no sources this argument should be null. This parameter is forwarded unmodified to the PlanarImage constructor.

The configuration contains a mapping of configuration variables and image properties. Entries which have keys of type RenderingHints.Key are taken to be configuration variables. Entries with a key which is either a String or a CaselessStringKey are interpreted as image properties. This parameter is forwarded unmodified to the PlanarImage constructor.

This image class recognizes the configuration variables referenced by the following keys:

The cobbleSources indicates which one of the two variants of the computeRect method should be called. If a subclass does not follow the default tile computation scheme, then this argument may be irrelevant.

Parameters:
layout - The layout of this image.
sources - The immediate sources of this image.
configuration - Configurable attributes of the image including configuration variables indexed by RenderingHints.Keys and image properties indexed by Strings or CaselessStringKeys. This parameter may be null.
cobbleSources - Indicates which variant of the computeRect method should be called.
Throws:
IllegalArgumentException - If sources is non-null and any object in sources is null.
RuntimeException - If default ColorModel setting is enabled via a hint in the configuration Map and the supplied Method does not conform to the requirements stated in the JAI class for the hint key KEY_DEFAULT_COLOR_MODEL_METHOD.
Since:
JAI 1.1
Method Detail

vectorize

protected static Vector vectorize(RenderedImage image)
Stores a RenderedImage in a Vector.
Parameters:
image - The image to be stored in the Vector.
Returns:
A Vector containing the image.
Throws:
IllegalArgumentException - if image is null.
Since:
JAI 1.1

vectorize

protected static Vector vectorize(RenderedImage image1,
                                  RenderedImage image2)
Stores two RenderedImages in a Vector.
Parameters:
image1 - The first image to be stored in the Vector.
image2 - The second image to be stored in the Vector.
Returns:
A Vector containing the images.
Throws:
IllegalArgumentException - if image1 or image2 is null.
Since:
JAI 1.1

vectorize

protected static Vector vectorize(RenderedImage image1,
                                  RenderedImage image2,
                                  RenderedImage image3)
Stores three RenderedImages in a Vector.
Parameters:
image1 - The first image to be stored in the Vector.
image2 - The second image to be stored in the Vector.
image3 - The third image to be stored in the Vector.
Returns:
A Vector containing the images.
Throws:
IllegalArgumentException - if image1 or image2 or image3 is null.
Since:
JAI 1.1

getTileCache

public TileCache getTileCache()
Returns the tile cache object of this image by reference. If this image does not have a tile cache, this method returns null.
Since:
JAI 1.1

setTileCache

public void setTileCache(TileCache cache)
Sets the tile cache object of this image. A null input indicates that this image should have no tile cache and subsequently computed tiles will not be cached.

The existing cache object is informed to release all the currently cached tiles of this image.

Parameters:
cache - A cache object to be used for caching this image's tiles, or null if no tile caching is desired.

getTileFromCache

protected Raster getTileFromCache(int tileX,
                                  int tileY)
Retrieves a tile from the tile cache. If this image does not have a tile cache, or the requested tile is not currently in the cache, this method returns null.
Parameters:
tileX - The X index of the tile.
tileY - The Y index of the tile.
Returns:
The requested tile as a Raster or null.

addTileToCache

protected void addTileToCache(int tileX,
                              int tileY,
                              Raster tile)
Adds a tile to the tile cache. If this image does not have a tile cache, this method does nothing.
Parameters:
tileX - The X index of the tile.
tileY - The Y index of the tile.
tile - The tile to be added to the cache.

getTileCacheMetric

public Object getTileCacheMetric()
Returns the tileCacheMetric instance variable by reference.
Since:
JAI 1.1

getTile

public Raster getTile(int tileX,
                      int tileY)
Returns a tile of this image as a Raster. If the requested tile is completely outside of this image's bounds, this method returns null.

This method attempts to retrieve the requested tile from the cache. If the tile is not currently in the cache, it schedules the tile for computation and adds it to the cache once the tile has been computed.

If a subclass overrides this method, then it needs to handle tile caching and scheduling. It should also override computeTile() which may be invoked directly by the TileScheduler.

Overrides:
getTile in class PlanarImage
Parameters:
tileX - The X index of the tile.
tileY - The Y index of the tile.

computeTile

public Raster computeTile(int tileX,
                          int tileY)
Computes the image data of a tile.

When a tile is requested via the getTile method and that tile is not in this image's tile cache, this method is invoked by the TileScheduler to compute the data of the new tile. Even though this method is marked public, it should not be called by the applications directly. Rather, it is meant to be called by the TileScheduler for the actual computation.

The implementation of this method in this class assumes that the requested tile either intersects the image, or is within the image's bounds. It creates a new Raster to represent the requested tile, then calls one of the two variants of computeRect to calculate the pixels of the tile that are within the image's bounds. The value of cobbleSources determines which variant of computeRect is invoked, as described in the class comments.

Subclasses may provide a more optimized implementation of this method. If they override this method not to call either variant of computeRect, then neither variant of computeRect needs to be implemented.

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

computeRect

protected void computeRect(Raster[] sources,
                           WritableRaster dest,
                           Rectangle destRect)
Computes a rectangle of output, given Raster sources. This method should be overridden by OpImage subclasses that make use of cobbled sources, as determined by the setting of the cobbleSources constructor argument to this class.

The source Rasters are guaranteed to include at least the area specified by mapDestRect(destRect) unless this area is empty or does not intersect the corresponding source in which case the source Raster will be null. Only the specified destination region should be written.

Since the subclasses of OpImage may choose between the cobbling and non-cobbling versions of computeRect, it is not possible to leave this method abstract in OpImage. Instead, a default implementation is provided that throws a RuntimeException.

Parameters:
sources - an array of source Rasters, one per source image.
dest - a WritableRaster to be filled in.
destRect - the Rectangle within the destination to be written.
Throws:
RuntimeException - If this method is invoked on the subclass that sets cobbleSources to true but does not supply an implementation of this method.

computeRect

protected void computeRect(PlanarImage[] sources,
                           WritableRaster dest,
                           Rectangle destRect)
Computes a rectangle of output, given PlanarImage sources. This method should be overridden by OpImage subclasses that do not require cobbled sources; typically they will instantiate iterators to perform source access, but they may access sources directly (via the SampleModel/DataBuffer interfaces) if they wish.

Since the subclasses of OpImage may choose between the cobbling and non-cobbling versions of computeRect, it is not possible to leave this method abstract in OpImage. Instead, a default implementation is provided that throws a RuntimeException.

Parameters:
sources - an array of PlanarImage sources.
dest - a WritableRaster to be filled in.
destRect - the Rectangle within the destination to be written.
Throws:
RuntimeException - If this method is invoked on the subclass that sets cobbleSources to false but does not supply an implementation of this method.

getTileDependencies

public Point[] getTileDependencies(int tileX,
                                   int tileY,
                                   int sourceIndex)
Returns a list of indices of the tiles of a given source image that may be required in order to compute a given tile. Ideally, only tiles that will be requested by means of calls to the source's getTile() method should be reported. The default implementation uses mapDestRect() to obtain a conservative estimate.

If no dependencies exist, this method returns null.

This method may be used by optimized implementations of JAI in order to predict future work and create an optimized schedule for performing it.

A given OpImage may mix calls to getTile() with calls to other methods such as getData() and copyData() in order to avoid requesting entire tiles where only a small portion is needed. In such a case, this method may be overridden to provide a more accurate estimate of the set of getTile() calls that will actually be performed.

Parameters:
tileX - the X index of the tile.
tileY - the Y index of the tile.
sourceIndex - the index of the source image.
Returns:
An array of Points indicating the source tile dependencies.
Throws:
IllegalArgumentException - If sourceIndex is negative or greater than the index of the last source.

getTiles

public Raster[] getTiles(Point[] tileIndices)
Computes the tiles indicated by the given tile indices. This call is preferable to a series of getTile() calls because certain implementations can make optimizations based on the knowledge that multiple tiles are being asked for at once.

The implementation of this method in this class uses multiple threads to compute multiple tiles at a time.

Overrides:
getTiles in class PlanarImage
Parameters:
tileIndices - An array of Points representing tile indices.
Returns:
An array of Rasters containing the tiles corresponding to the given tile indices.
Throws:
IllegalArgumentException - If tileIndices is null.

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 event source parameter passed to such listeners will be the TileScheduler and the image parameter will be this image.
Overrides:
queueTiles in class PlanarImage
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 via the TileScheduler for this image. This method should merely forward the request to the associated TileScheduler.
Overrides:
cancelTiles in class PlanarImage
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 one or more threads to compute the tiles, while others may ignore the hint.
Overrides:
prefetchTiles in class PlanarImage
Parameters:
tileIndices - A list of tile indices indicating which tiles to prefetch.
Throws:
IllegalArgumentException - If tileIndices is null.

mapDestPoint

public Point2D mapDestPoint(Point2D destPt,
                            int sourceIndex)
Computes the position in the specified source that best matches the supplied destination image position. If it is not possible to compute the requested position, null will be returned. If the point is mapped outside the source bounds, the coordinate value or null may be returned at the discretion of the implementation.

Floating-point input and output coordinates are supported, and recommended when possible. Subclass implementations may however use integer computation if necessary for simplicity.

The implementation in this class returns the value of pt in the following code snippet: 

 Rectangle destRect = new Rectangle((int)destPt.getX(),
                                    (int)destPt.getY(),
                                    1, 1);
 Rectangle sourceRect = mapDestRect(destRect, sourceIndex);
 Point2D pt = (Point2D)destPt.clone();
 pt.setLocation(sourceRect.x + (sourceRect.width - 1.0)/2.0,
                sourceRect.y + (sourceRect.height - 1.0)/2.0);
Subclasses requiring different behavior should override this method.

Parameters:
destPt - the position in destination image coordinates to map to source image coordinates.
sourceIndex - the index of the source image.
Returns:
a Point2D of the same class as destPt or null.
Throws:
IllegalArgumentException - if destPt is null.
IndexOutOfBoundsException - if sourceIndex is negative or greater than or equal to the number of sources.
Since:
JAI 1.1.2

mapSourcePoint

public Point2D mapSourcePoint(Point2D sourcePt,
                              int sourceIndex)
Computes the position in the destination that best matches the supplied source image position. If it is not possible to compute the requested position, null will be returned. If the point is mapped outside the destination bounds, the coordinate value or null may be returned at the discretion of the implementation.

Floating-point input and output coordinates are supported, and recommended when possible. Subclass implementations may however use integer computation if necessary for simplicity.

The implementation in this class returns the value of pt in the following code snippet: 

 Rectangle sourceRect = new Rectangle((int)sourcePt.getX(),
                                      (int)sourcePt.getY(),
                                      1, 1);
 Rectangle destRect = mapSourceRect(sourceRect, sourceIndex);
 Point2D pt = (Point2D)sourcePt.clone();
 pt.setLocation(destRect.x + (destRect.width - 1.0)/2.0,
                destRect.y + (destRect.height - 1.0)/2.0);
Parameters:
sourcePt - the position in source image coordinates to map to destination image coordinates.
sourceIndex - the index of the source image.
Returns:
a Point2D of the same class as sourcePt or null.
Throws:
IllegalArgumentException - if sourcePt is null.
IndexOutOfBoundsException - if sourceIndex is negative or greater than or equal to the number of sources.
Since:
JAI 1.1.2

mapSourceRect

public abstract Rectangle mapSourceRect(Rectangle sourceRect,
                                        int sourceIndex)
Returns a conservative estimate of the destination region that can potentially be affected by the pixels of a rectangle of a given source. An empty Rectangle may be returned if the destination is unaffected by the contents of the source rectangle. This is distinct from a null return value which serves rather to indicate that it is not possible to determine the bounds of the affected region. The safest interpretation of a null return value is that the entire destination might be affected by any pixel within the given source rectangle.
Parameters:
sourceRect - The Rectangle in source coordinates.
sourceIndex - The index of the source image.
Returns:
A Rectangle indicating the potentially affected destination region, or null if the region is unknown.
Throws:
IllegalArgumentException - If the source index is negative or greater than that of the last source.
IllegalArgumentException - If sourceRect is null.

mapDestRect

public abstract Rectangle mapDestRect(Rectangle destRect,
                                      int sourceIndex)
Returns a conservative estimate of the region of a specified source that is required in order to compute the pixels of a given destination rectangle. The computation may as appropriate clip the mapped Rectangle to the actual bounds of the source or may treat the source as having infinite extent. It is therefore the responsibility of the invoking object to constrain the region in accordance with its needs. Returning an empty Rectangle should indicate that the data of the source image in question are not required for the computation of the specified destination region. If the entire source image might be required to compute this destination region, then getSourceImage(sourceIndex).getBounds() should be returned.

To illustrate the issue of whether the source should be thought to have infinite extent, consider the case wherein computing a destination pixel requires multiple source pixels of context. At the source image boundary, these pixels might only be available if the source data were extrapolated, e.g., using a BorderExtender. If such an extender were available, destination pixels could be computed even if they mapped to a region on the source boundary so in this case the source could be considered to have infinite extent. If no such extender were available, only destination pixels with source context contained within the source image bounds could be considered so that it might be preferable to clip the rectangle to the source bounds.

Parameters:
destRect - The Rectangle in destination coordinates.
sourceIndex - The index of the source image.
Returns:
A non-null Rectangle indicating the required source region.
Throws:
IllegalArgumentException - If the source index is negative or greater than that of the last source.
IllegalArgumentException - If destRect is null.

getOperationComputeType

public int getOperationComputeType()
Returns one of OP_COMPUTE_BOUND, OP_IO_BOUND, or OP_NETWORK_BOUND to indicate how the operation is likely to spend its time. The answer does not affect the output of the operation, but may allow a scheduler to parallelize the computation of multiple operations more effectively.

The implementation of this method in this class returns OP_COMPUTE_BOUND.

computesUniqueTiles

public boolean computesUniqueTiles()
Returns true if the OpImage returns an unique Raster object every time computeTile is called. OpImages that internally cache Rasters and return them via computeTile should return false for this method.

The implementation of this method in this class always returns true.

dispose

public void dispose()
Uncaches all tiles and calls super.dispose(). If a TileRecycler was defined via the configuration variable JAI.KEY_TILE_RECYCLER when this image was constructed and tile recycling was enabled via the configuration variable JAI.KEY_CACHED_TILE_RECYCLING_ENABLED, then each of this image's tiles which is currently in the cache will be recycled. This method may be invoked more than once although invocations after the first one may do nothing.

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

Overrides:
dispose in class PlanarImage
Since:
JAI 1.1.2

hasExtender

public boolean hasExtender(int sourceIndex)
Deprecated. as of JAI 1.1.

Indicates whether the source with the given index has a BorderExtender. If the source index is out of bounds for the source vector of this OpImage then an ArrayIndexOutOfBoundsException may be thrown.
Parameters:
sourceIndex - The index of the source in question.
Returns:
true if the indicated source has an extender.

getExpandedNumBands

public static int getExpandedNumBands(SampleModel sampleModel,
                                      ColorModel colorModel)
Deprecated. as of JAI 1.1.

Returns the effective number of bands of an image with a given SampleModel and ColorModel. Normally, this is given by sampleModel.getNumBands(), but for images with an IndexColorModel the effective number of bands is given by colorModel.getNumComponents(), since a single physical sample represents multiple color components.

getFormatTags

protected RasterFormatTag[] getFormatTags()
Returns the image's format tags to be used with a RasterAccessor.

This method will compute and cache the tags the first time it is called on a particular image. The image's SampleModel and ColorModel must be set to their final values before calling this method.

Returns:
An array containing RasterFormatTags for the sources in the first getNumSources() elements and a RasterFormatTag for the destination in the last element.

getTileRecycler

public TileRecycler getTileRecycler()
Returns the value of the instance variable tileRecycler.
Since:
JAI 1.1.2

createTile

protected final WritableRaster createTile(int tileX,
                                          int tileY)
Creates a WritableRaster at the given tile grid position. The superclass method PlanarImage.createWritableRaster(SampleModel,Point) will be invoked with this image's SampleModel and the location of the specified tile.

Subclasses should ideally use this method to create destination tiles as this method will take advantage of any TileFactory specified to the OpImage at construction.

Since:
JAI 1.1.2

recycleTile

protected void recycleTile(Raster tile)
A tile recycling convenience method.

If tileRecycler is non-null, the call is forwarded to TileRecycler.recycleTile(Raster); otherwise the method does nothing.

This method is for use by subclasses which create Rasters with limited scope which therefore may easily be identified as safe candidates for recycling. This might occur for example within computeRect(Raster[],WritableRaster,Rectangle) or computeTile(int,int) wherein Rasters may be created for use within the method but be eligible for garbage collection once the method is exited.

Throws:
IllegalArgumentException - if tile is null.
Since:
JAI 1.1.2
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD