Java Doc for OpImage.java in  » 6.0-JDK-Modules » Java-Advanced-Imaging » javax » media » jai » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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
See Also:   AreaOpImage
See Also:   GeometricOpImage
See Also:   PointOpImage
See Also:   StatisticsOpImage
See Also:   SourcelessOpImage

The image's layout is encapsulated in the layout argument.

Checks whether the sources parameter is null and optionally whether all elements are non-null.
Parameters:
  sources - The source Vector.
Parameters:
  checkElements - Whether the elements are to be checked.

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.

This method will compute and cache the tags the first time it is called on a particular image.

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.

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.

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.

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:

• JAI.KEY_TILE_CACHE: specifies the TileCache in which to store the image tiles; if this key is not supplied no tile caching will be performed.
• JAI.KEY_TILE_CACHE_METRIC: establishes an ordering of tiles stored in the tile cache. This ordering is used to determine which tiles will be removed first, if a condition causes tiles to be removed from the cache.
• JAI.KEY_TILE_SCHEDULER: specifies the TileScheduler to use to schedule tile computation; if this key is not supplied the default scheduler will be used.
• JAI.KEY_COLOR_MODEL_FACTORY: specifies a ColorModelFactory to be used to generate the ColorModel of the image. If such a callback is provided it will be invoked if and only if either no ImageLayout hint is given, or an ImageLayout hint is given but contains a non-null ColorModel which is incompatible with the image SampleModel. In other words, such a callback provides the second priority mechanism for setting the ColorModel of the image.
• JAI.KEY_DEFAULT_COLOR_MODEL_ENABLED: specifies whether a default ColorModel will be derived if none is specified and one cannot be inherited from the first source; if this key is not supplied a default ColorModel will be computed if necessary.
• JAI.KEY_DEFAULT_COLOR_MODEL_METHOD: specifies the method to be used to compute the default ColorModel; if this key is not supplied and a default ColorModel is required, PlanarImage.createColorModel() will be used to compute it.
• JAI.KEY_TILE_FACTORY: specifies a TileFactory to be used to generate the tiles of the image via TileFactory.createTile(SampleModelPoint) . If no such configuration variable is given, a new Raster will be created for each image tile. This behavior may be overridden by subclasses which have alternate means of saving memory, for example as in the case of point operations which may overwrite a source image not referenced by user code. Note that the corresponding instance variable is actually set by the superclass constructor.
• JAI.KEY_TILE_RECYCLER: specifies a TileRecycler to be used to recycle the tiles of the image when the dispose() method is invoked. If such a configuration variable is set, the image has a non-null TileCache, and tile recycling is enabled, then invoking dispose() will cause each of the tiles of this image currently in the cache to be passed to the configured TileRecycler
via TileRecycler.recycleTile(Raster) .
• JAI.KEY_CACHED_TILE_RECYCLING_ENABLED: specifies a Boolean value which indicates whether {#dispose()} should pass to tileRecycler.recycleTile() any image tiles remaining in the cache.

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.
Parameters:
  sources - The immediate sources of this image.
Parameters:
  configuration - Configurable attributes of the image includingconfiguration variables indexed byRenderingHints.Keys and image properties indexedby Strings or CaselessStringKeys.This parameter may be null.
Parameters:
  cobbleSources - Indicates which variant of thecomputeRect method should be called.
throws:
  IllegalArgumentException - If sourcesis non-null and any object insources is null.
throws:
  RuntimeException - If default ColorModel settingis enabled via a hint in the configuration Mapand the supplied Method does not conform to therequirements stated in the JAI class for thehint key KEY_DEFAULT_COLOR_MODEL_METHOD.
since:
   JAI 1.1

Checks whether the sources parameter is null and optionally whether all elements are non-null.
Parameters:
  sources - The source Vector.
Parameters:
  checkElements - Whether the elements are to be checked. The sources parameter unmodified.
throws:
  IllegalArgumentException - If sourcesis null.
throws:
  IllegalArgumentException - If checkElementsis true, sourcesis non-null and any object insources is null.

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.

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.
Parameters:
  dest - a WritableRaster to be filled in.
Parameters:
  destRect - the Rectangle within thedestination to be written.
throws:
  RuntimeException - If this method is invoked on the subclassthat sets cobbleSources to falsebut does not supply an implementation of this method.

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.
Parameters:
  tileY - The Y index of the tile.

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

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.

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

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. An array containing RasterFormatTags for thesources in the first getNumSources() elements and aRasterFormatTag for the destination in the last element.

The implementation of this method in this class returns OP_COMPUTE_BOUND.

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.
Parameters:
  tileX - The X index of the tile.
Parameters:
  tileY - The Y index of the tile.

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.
Parameters:
  tileY - the Y index of the tile.
Parameters:
  sourceIndex - the index of the source image. An array of Points indicating the sourcetile dependencies.
throws:
  IllegalArgumentException - If sourceIndex isnegative or greater than the index of the last source.

The implementation of this method in this class uses multiple threads to compute multiple tiles at a time.
Parameters:
  tileIndices - An array of Points representingtile indices. An array of Rasters containing the tilescorresponding to the given tile indices.
throws:
  IllegalArgumentException - If tileIndices isnull.

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);
 

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.

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);
 

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 OpImage.computeRect(Raster[],WritableRaster,Rectangle) or OpImage.computeTile(int,int) wherein Rasters may be created for use within the method but be eligible for garbage collection once the method is exited.

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'stiles, or null if no tile caching is desired.