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

This class is intended to help classes that need to access the pixel and/or color data of a RenderedImage, such as an OpImage, in an optimized fashion. Most of the variables defined in this class are public so that other classes may use them directly. However, the variables are also declared final so that other classes can not modify their values.

In general, the pixel data of a RenderedImage may be obtained by calling the getPixels() method. By definition, the pixel data of an image are the data described by the image's SampleModel and stored in the image's Rasters. No consideration of any kind is given to the image's ColorModel. If no error is found, the pixel data are returned in the primitive arrays of the type specified by the caller in an unpacked format, along with access information. Therefore, the specified data type must be one of the valid types defined in DataBuffer and large enough (in bit depth) to hold the pixel data of the image.

The pixel data of a binary image may be obtained in a packed format by calling the getPackedPixels() method. It returns the data in a packed byte array, with 8 pixels packed into 1 byte. The format of the data in the array is similar to the format described by the MultiPixelPackedSampleModel, where the end of each scanline is padded to the end of the byte if necessary. Note that this method returns a valid result only if and only if the image is a single-band bit image, that is, each pixel has only 1 sample with a sample size of 1 bit.

Two corresponding "set" methods are also provided for setting the computed pixel data back into the Raster's DataBuffer: setPixels() for unpacked data, and setPackedPixels() for packed data. It is very important that the caller uses the correct "set" method that matches the "get" method used to obtain the data, or errors will occur.

The color/alpha data of the RenderedImage may be obtained by calling the getComponents() method which returns the unnormalized data in the ColorSpace specified in the ColorModel, or the getComponentsRGB() method which returns the data scaled from 0 to 255 in the default sRGB ColorSpace. These methods retrieve the pixel data from the Raster, and perform the pixel-to-color translation. Therefore, in order for these two methods to return a valid result, the image must have a valid ColorModel.

Similarly, two "set" methods may be used to perform the color-to-pixel translation, and set the pixel data back to the Raster's DataBuffer. Again, it is important that the "get" and "set" methods are matched up correctly.

In addition, several static methods are included in this class for the convenience of OpImage developers, who may use them to help determine the appropriate destination SampleModel type.
since:
   JAI 1.1

In order for this method to return a valid result, the image must have a valid ColorModel that is compatible with the image's SampleModel. Further, the SampleModel and ColorModel must have the same transferType.

The component data are stored in a primitive array of the type specified by the type argument. It must be one of the valid data types defined in DataBuffer and large (in bit depth) enough to hold the color/alpha components, or an exception is thrown. This means type should be greater than or equal to componentType. To avoid extra array copy, it is best to use DataBuffer.TYPE_INT for this argument.

The Rectangle specifies the region of interest within which the pixel data are to be retrieved. It must be completely inside the Raster's boundary, or else this method throws an exception.
Parameters:
  raster - The Raster that contains the pixel data.
Parameters:
  rect - The region of interest within the Rasterwhere the pixels are accessed.
Parameters:
  type - The type of the primitive array used to return thecolor/alpha components with. The UnpackedImageData with its data filled in.
throws:
  IllegalArgumentException - If the image does not have a validColorModel that is compatible with itsSampleModel.
throws:
  IllegalArgumentException - If type is not avalid data type defined in DataBuffer, oris not large enough to hold the translated color/alphacomponents.
throws:
  IllegalArgumentException - If rect is notcontained by the bounds of the specified Raster.

In order for this method to return a valid result, the image must have a valid ColorModel that is compatible with the image's SampleModel. Further, the SampleModel and ColorModel must have the same transferType.

The component data are stored in a two-dimensional, band-interleaved, byte array, because the components are always scaled from 0 to 255. Red is band 0, green is band 1, blue is band 2, and alpha is band 3.

The Rectangle specifies the region of interest within which the pixel data are to be retrieved. It must be completely inside the Raster's boundary, or this method will throw an exception.
Parameters:
  raster - The Raster that contains the pixel data.
Parameters:
  rect - The region of interest within the Rasterwhere the pixels are accessed. The UnpackedImageData with its data filled in.
throws:
  IllegalArgumentException - If the image does not have a validColorModel that is compatible with itsSampleModel.
throws:
  IllegalArgumentException - If rect is notcontained by the bounds of the specified Raster.

In general, if an operation has multiple sources, and some sources have 1 band and others have multiple bands, the single band may be applied to the multiple bands one at a time. (An example of this would be the MultiplyOpImage). Therefore, in such a case, this method returns the smallest band count among the multi-band sources.

If there is no object in the source Vector, this method returns 0. All the objects in the source Vector must be RenderedImages.

When determining the result, only information from each image's SampleModel are used. No consideration is given to the image's ColorModel.
Parameters:
  sources - A Vector of RenderedImagesources. The minimum number of destination bands.
throws:
  IllegalArgumentException - If sources isnull.
throws:
  ClassCastException - If any object in sourcesis not a RenderedImage.

If all the sources are single-bit images, this method returns TYPE_BIT (defined in this class) so that the destination does not use unnecessary memory for some operations. This includes all images whose SampleModel is single-banded and whose sample size is 1, regardless of the type of ColorModel the image may have. If an operation does not wish to deal with packed data, it should use TYPE_BYTE for pixel computation.

If there is no object in the source Vector, this method returns TYPE_UNDEFINED. All the objects in the source Vector must be RenderedImages.

When determining the result, only information from each image's SampleModel is used. No consideration is given to the image's ColorModel.
Parameters:
  sources - A Vector of RenderedImagesources. The largest data type which can accomodate all sources.
throws:
  IllegalArgumentException - If sources isnull.
throws:
  ClassCastException - If any object in sourcesis not a RenderedImage.

This method only returns a valid result when the pixels are single-band and single-bit. All other types of data result in an exception. The data are packed in such a format that eight pixels are packed into one byte, and the end of each scanline is padded with zeros to the end of the byte.

In general, this method is called when operations are to be performed on the bit data in a packed format directly, to save memory usage. The static method isPackedOperation should be used to determine whether the destination and/or its sources are suitable for performing operations to a packed array.

The Rectangle specifies the region of interest within which the pixel data are to be retrieved. It must be completely inside the Raster's boundary, or this method will throw an exception.
Parameters:
  raster - The Raster that contains the pixel data.
Parameters:
  rect - The region of interest within the Rasterwhere the pixels are accessed.
Parameters:
  isDest - Indicates whether this Raster is adestination Raster. That is, its pixels havenot been computed.
Parameters:
  coerceZeroOffset - If true the returnedPackedImageData will be forced to have abitOffset and offset of zeroand a lineStride of (rect.width+7)/8.The coercedZeroOffset field of the returnedPackedImageData will be set to true. The PackedImageData with its data filled in.
throws:
  IllegalArgumentException - If data described by theRaster's SampleModel are notsingle-band and single-bit.
throws:
  IllegalArgumentException - If rect is notwithin the bounds of the specified Raster.

The primitive array is of the type specified by the type argument. It must be one of the valid data types defined in DataBuffer and large (in bit depth) enough to hold the pixel samples, or an exception will be thrown. This means type should be greater than or equal to sampleType.

The Rectangle specifies the region of interest within which the pixel data are to be retrieved. It must be completely inside the Raster's boundary, or else this method throws an exception.

This method tries to avoid copying data as much as possible. If it is unable to reformat the pixel data in the way requested, or if the pixels do not have enough data to satisfy the request, this method throws an exception.
Parameters:
  raster - The Raster that contains the pixel data.
Parameters:
  rect - The region of interest within the Rasterwhere the pixels are accessed.
Parameters:
  type - The type of the primitive array used to return thepixel samples.
Parameters:
  isDest - Indicates whether this Raster is adestination Raster. That is, its pixels havenot been computed. The pixel data in an UnpackedImageData object.
throws:
  IllegalArgumentException - If type is not avalid data type defined in DataBuffer, oris not large enough to hold the pixel samples from thespecified Raster.
throws:
  IllegalArgumentException - If rect is notcontained by the bounds of the specified Raster.

In order for this method to return a valid result, the image must have a valid ColorModel that is compatible with the image's SampleModel. Further, the SampleModel and ColorModel must have the same transferType.

This method sets data only if the set flag in UnpackedImageData is true.
Parameters:
  uid - The UnpackedImageData whose data is to be set.
throws:
  IllegalArgumentException - If the uid isnull.

In order for this method to return a valid result, the image must have a valid ColorModel that is compatible with the image's SampleModel. Furthermore, the SampleModel and ColorModel must have the same transferType.

This method sets data only if the set flag in UnpackedImageData is true.
Parameters:
  uid - The UnpackedImageData to set.
throws:
  IllegalArgumentException - If the uid isnull.

The PackedImageData should be obtained by calling the getPackedPixels() method.
Parameters:
  pid - The PackedImageData object whose pixelsare to be written.
throws:
  IllegalArgumentException - If the pid isnull.

The UnpackedImageData should be obtained by calling the getPixels() method.
Parameters:
  uid - The UnpackedImageData object to set.
throws:
  IllegalArgumentException - If the uid isnull.

The UnpackedImageData should be obtained by calling the getPixels() method.
Parameters:
  uid - The UnpackedImageData object to set.
Parameters:
  clamp - A boolean set to true if clampingis to be performed.
throws:
  IllegalArgumentException - If the uid isnull.