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 {@link AreaOpImage}, {@link GeometricOpImage}, and the "format" operation. These operations set the {@link JAI#KEY_REPLACE_INDEX_COLOR_MODEL} RenderingHintto 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 PlanarImage
@see AreaOpImage
@see GeometricOpImage
@see PointOpImage
@see StatisticsOpImage
@see SourcelessOpImage
| |
| |
| |
| |
| |
| |
| |
| |