|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--javax.media.jai.PixelAccessor
This is a utility class that may be used to access the pixel data
stored in a RenderedImage's Rasters, as
well as performing pixel-to-color data translation based on the
image's SampleModel and ColorModel. It
also provides several static methods to determine information about
the image data.
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.
| Field Summary | |
int |
bufferType
The type of the DataBuffer's data array used to store the
pixel data by the image's SampleModel. |
ColorModel |
colorModel
The image's ColorModel. |
int[] |
componentSize
The size, in number of bits, of all the color/alpha components. |
int |
componentType
The type of the color/alpha components, determined based on the component size. |
boolean |
hasCompatibleCM
Set to true if the image has a non-null
ColorModel which is compatible with the image's
SampleModel; false otherwise. |
boolean |
isComponentCM
Set to true if the image has a
ComponentColorModel;
false otherwise. |
boolean |
isComponentSM
true if the image has a
ComponentSampleModel;
false otherwise. |
boolean |
isIndexCM
Set to true if the image has an
IndexColorModel;
false otherwise. |
boolean |
isMultiPixelPackedSM
true if the image has a
MultiPixelPackedSampleModel;
false otherwise. |
boolean |
isPacked
Set to true if the pixel data of this image may be
packed into a byte array. |
boolean |
isPackedCM
Set to true if the image has a
PackedColorModel;
false otherwise. |
boolean |
isSinglePixelPackedSM
true if the image has a
SinglePixelPackedSampleModel;
false otherwise. |
int |
numBands
The number of bands (samples) per pixel. |
int |
numComponents
The total number of color/alpha components in the image's ColorModel. |
SampleModel |
sampleModel
The image's SampleModel. |
int[] |
sampleSize
The size, in number of bits, of all the pixel samples. |
int |
sampleType
The data type of the pixel samples, determined based on the sample size. |
int |
transferType
The type of the primitive array used to transfer the pixel data by the image's SampleModel. |
static int |
TYPE_BIT
Tag for single-bit data type. |
| Constructor Summary | |
PixelAccessor(RenderedImage image)
Constructs a PixelAccessor from a
RenderedImage. |
|
PixelAccessor(SampleModel sm,
ColorModel cm)
Constructs a PixelAccessor given a valid
SampleModel and a (possibly null)
ColorModel. |
|
| Method Summary | |
UnpackedImageData |
getComponents(Raster raster,
Rectangle rect,
int type)
Returns an array of unnormalized color/alpha components in the ColorSpace defined in the image's
ColorModel. |
UnpackedImageData |
getComponentsRGB(Raster raster,
Rectangle rect)
Returns an array of color/alpha components scaled from 0 to 255 in the default sRGB ColorSpace. |
static int |
getDestNumBands(Vector sources)
Returns the smallest number of bands of all the sources. |
static int |
getDestPixelType(Vector sources)
Returns the largest data type of all the sources. |
PackedImageData |
getPackedPixels(Raster raster,
Rectangle rect,
boolean isDest,
boolean coerceZeroOffset)
Returns a region of the pixel data within a Raster
in a packed byte array. |
UnpackedImageData |
getPixels(Raster raster,
Rectangle rect,
int type,
boolean isDest)
Returns a region of the pixel data within a Raster
in an unpacked primitive array. |
static int |
getPixelType(SampleModel sm)
Determines the pixel type based on the SampleModel. |
static boolean |
isPackedOperation(PixelAccessor[] srcs,
PixelAccessor dst)
Returns true if the destination and/or all the
sources are single-bit, single-band images, and their pixel
data may be packed into a byte array. |
static boolean |
isPackedOperation(PixelAccessor src,
PixelAccessor dst)
Returns true if the destination and the source
are both single-bit, single-band images, and their pixel
data may be packed into a byte array. |
static boolean |
isPackedOperation(PixelAccessor src1,
PixelAccessor src2,
PixelAccessor dst)
Returns true if the destination and both sources
are all single-bit, single-band images, and their pixel
data may be packed into a byte array. |
void |
setComponents(UnpackedImageData uid)
Given an array of unnormalized color/alpha components, this method performs color-to-pixel translation, and sets the translated pixel data back to the Raster within
a specific region. |
void |
setComponentsRGB(UnpackedImageData uid)
Given an array of normalized (between 0 and 255) alpha/RGB color components, this method performs color-to-pixel translation, and sets the translated pixel data back to the Raster
within a specific region. |
void |
setPackedPixels(PackedImageData pid)
Sets a region of the pixel data within a Raster
using a primitive array. |
void |
setPixels(UnpackedImageData uid)
Sets a region of the pixel data within a Raster
using a primitive array. |
void |
setPixels(UnpackedImageData uid,
boolean clamp)
Sets a region of the pixel data within a Raster
using a primitive array. |
| Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
| Field Detail |
public static final int TYPE_BIT
public final SampleModel sampleModel
SampleModel.public final ColorModel colorModel
ColorModel.public final boolean isComponentSM
true if the image has a
ComponentSampleModel;
false otherwise.public final boolean isMultiPixelPackedSM
true if the image has a
MultiPixelPackedSampleModel;
false otherwise.public final boolean isSinglePixelPackedSM
true if the image has a
SinglePixelPackedSampleModel;
false otherwise.public final int sampleType
public final int bufferType
DataBuffer's data array used to store the
pixel data by the image's SampleModel. This is the same
value as that returned by SampleModel.getDataType().public final int transferType
SampleModel. This is the same value as
that returned by SampleModel.getTransferType().public final int numBands
SampleModel.getNumBands().public final int[] sampleSize
SampleModel.getSampleSize().public final boolean isPacked
true if the pixel data of this image may be
packed into a byte array. That is, each pixel has
1 sample (1 band) with a sample size of 1 bit. If this variable
is true, getPackedPixels() should return
a valid result, with 8 pixels packed into 1 byte.public final boolean hasCompatibleCM
true if the image has a non-null
ColorModel which is compatible with the image's
SampleModel; false otherwise.public final boolean isComponentCM
true if the image has a
ComponentColorModel;
false otherwise.public final boolean isIndexCM
true if the image has an
IndexColorModel;
false otherwise.public final boolean isPackedCM
true if the image has a
PackedColorModel;
false otherwise.public final int componentType
public final int numComponents
ColorModel. This is the same value as that
returned by ColorModel.getNumComponents().public final int[] componentSize
ColorModel.getComponentSize().| Constructor Detail |
public PixelAccessor(RenderedImage image)
PixelAccessor from a
RenderedImage.
The RenderedImage must have a valid
SampleModel, but may or may not have a valid
ColorModel.image - The image whose data are to be accessed.image is
null, or if the image does not have a valid
SampleModel.
public PixelAccessor(SampleModel sm,
ColorModel cm)
PixelAccessor given a valid
SampleModel and a (possibly null)
ColorModel.sm - The SampleModel for the image to be accessed.
Must be valid.cm - The ColorModel for the image to be accessed.
May be null.sm is null.| Method Detail |
public static int getPixelType(SampleModel sm)
SampleModel.
The pixel type signifies the data type for a PixelAccessor.
For ComponentSampleModel, the pixel type is the same
as the type of the DataBuffer used to store the pixel
data. For all other types of SampleModel, the pixel
type is determined based on the sample sizes.sm - The SampleModel of the image.public static int getDestPixelType(Vector sources)
PixelAccessor.
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.
sources - A Vector of RenderedImage
sources.sources is
null.sources
is not a RenderedImage.public static int getDestNumBands(Vector sources)
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.
sources - A Vector of RenderedImage
sources.sources is
null.sources
is not a RenderedImage.
public static boolean isPackedOperation(PixelAccessor[] srcs,
PixelAccessor dst)
true if the destination and/or all the
sources are single-bit, single-band images, and their pixel
data may be packed into a byte array.
If so, then the operations may be done in the packed format.srcs - The array of source PixelAccesors.dst - The destination PixelAccesor.true if a packed operation is possible.
public static boolean isPackedOperation(PixelAccessor src,
PixelAccessor dst)
true if the destination and the source
are both single-bit, single-band images, and their pixel
data may be packed into a byte array.
If so, then the operations may be done in the packed format.srcs - The source PixelAccesor.dst - The destination PixelAccesor.true if a packed operation is possible.
public static boolean isPackedOperation(PixelAccessor src1,
PixelAccessor src2,
PixelAccessor dst)
true if the destination and both sources
are all single-bit, single-band images, and their pixel
data may be packed into a byte array.
If so, then the operations may be done in the packed format.src1 - The first source PixelAccesor.src2 - The second source PixelAccesor.dst - The destination PixelAccesor.true if a packed operation is possible.
public UnpackedImageData getPixels(Raster raster,
Rectangle rect,
int type,
boolean isDest)
Raster
in an unpacked primitive array. The returned data are
retrieved from the Raster's DataBuffer;
no pixel-to-color translation is performed.
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.
raster - The Raster that contains the pixel data.rect - The region of interest within the Raster
where the pixels are accessed.type - The type of the primitive array used to return the
pixel samples.isDest - Indicates whether this Raster is a
destination Raster. That is, its pixels have
not been computed.UnpackedImageData object.type is not a
valid data type defined in DataBuffer, or
is not large enough to hold the pixel samples from the
specified Raster.rect is not
contained by the bounds of the specified Raster.public void setPixels(UnpackedImageData uid)
Raster
using a primitive array. This method copies data only if
the set flag in UnpackedImageData is
true. Performs clamping by default.
The UnpackedImageData should be obtained by
calling the getPixels() method.
uid - The UnpackedImageData object to set.uid is
null.
public void setPixels(UnpackedImageData uid,
boolean clamp)
Raster
using a primitive array. This method only copies data only if
the set flag in UnpackedImageData is
true.
The UnpackedImageData should be obtained by
calling the getPixels() method.
uid - The UnpackedImageData object to set.clamp - A boolean set to true if clamping
is to be performed.uid is
null.
public PackedImageData getPackedPixels(Raster raster,
Rectangle rect,
boolean isDest,
boolean coerceZeroOffset)
Raster
in a packed byte array. The returned data are
retrieved from the Raster's DataBuffer;
no pixel-to-color translation is performed.
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.
raster - The Raster that contains the pixel data.rect - The region of interest within the Raster
where the pixels are accessed.isDest - Indicates whether this Raster is a
destination Raster. That is, its pixels have
not been computed.coerceZeroOffset - If true the returned
PackedImageData will be forced to have a
bitOffset and offset of zero
and a lineStride of (rect.width+7)/8.
The coercedZeroOffset field of the returned
PackedImageData will be set to true.PackedImageData with its data filled in.Raster's SampleModel are not
single-band and single-bit.rect is not
within the bounds of the specified Raster.public void setPackedPixels(PackedImageData pid)
Raster
using a primitive array. This method copies data only if
the set flag in PackedImageData is
true.
The PackedImageData should be obtained by
calling the getPackedPixels() method.
pid - The PackedImageData object whose pixels
are to be written.pid is
null.
public UnpackedImageData getComponents(Raster raster,
Rectangle rect,
int type)
ColorSpace defined in the image's
ColorModel. This method retrieves the pixel data
within the specified rectangular region from the
Raster, performs the pixel-to-color translation based
on the image's ColorModel, and returns the components
in the order specified by the ColorSpace.
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.
raster - The Raster that contains the pixel data.rect - The region of interest within the Raster
where the pixels are accessed.type - The type of the primitive array used to return the
color/alpha components with.UnpackedImageData with its data filled in.ColorModel that is compatible with its
SampleModel.type is not a
valid data type defined in DataBuffer, or
is not large enough to hold the translated color/alpha
components.rect is not
contained by the bounds of the specified Raster.public void setComponents(UnpackedImageData uid)
Raster within
a specific region. It is very important that the components
array along with access information are obtained by calling
the getComponents() method, or errors
will occur.
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.
uid - The UnpackedImageData whose data is to be set.uid is
null.
public UnpackedImageData getComponentsRGB(Raster raster,
Rectangle rect)
ColorSpace. This method
retrieves the pixel data within the specified rectangular region
from the Raster, performs the pixel-to-color translation
based on the image's ColorModel, and returns the
components in the order specified by the ColorSpace.
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.
raster - The Raster that contains the pixel data.rect - The region of interest within the Raster
where the pixels are accessed.UnpackedImageData with its data filled in.ColorModel that is compatible with its
SampleModel.rect is not
contained by the bounds of the specified Raster.public void setComponentsRGB(UnpackedImageData uid)
Raster
within a specific region. It is very important that the components
array along with access information are obtained by calling
the getComponentsRGB() method, or errors
will occur.
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.
uid - The UnpackedImageData to set.uid is
null.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||