javax.media.jai
Class RasterAccessor

java.lang.Object
  extended byjavax.media.jai.RasterAccessor

public class RasterAccessor
extends Object

An adapter class for presenting non-binary image data in a ComponentSampleModel format and binary image data in a zero-offset byte array format even when the original data are not so stored. RasterAccessor is meant to make the common (ComponentSampleModel) case fast and other formats possible without forcing the OpImage writer to cover more than one case per non-binary data type.

When constructing a RasterAccessor with a source(s) that has an IndexColorModel and a destination that has a non-IndexColorModel, RasterAccessor will perform expansion of the source pixels. If the source(s) and the destination have an IndexColorModel, then RasterAccessor will assume that the operation can correctly process an IndexColorModel source and will not expand the source pixels (colormap indices) into color components. Refer to JAI.KEY_REPLACE_INDEX_COLOR_MODEL for a mechanism by which the destination image's ColorModel is set to a non-IndexColorModel to cause RasterAccessor to expand the source's IndexColorModel.

Binary data are handled as a special case. In general image data are considered to be binary when the image has a single-banded MultiPixelPackedSampleModel with one bit per pixel. This may be verified by invoking the isBinary() method. For this case the methods getBinaryDataArray() and copyBinaryDataToRaster() should be used to access and set, respectively, the binary data in packed form. If the binary data are to be accessed in expanded form, i.e., as bytes, then the usual byte methods getByteDataArray(), getByteDataArrays(), and copyDataToRaster() should be used.


Field Summary
protected  int[] bandDataOffsets
          The bandOffset + subRasterOffset + DataBufferOffset into each of the numBand data arrays
protected  int[] bandOffsets
          Offset from a pixel's offset to a band of that pixel
protected  byte[] binaryDataArray
          The image data for the binary case.
protected  byte[][] byteDataArrays
          The image data in a two-dimensional byte array.
static int COPIED
          Flag indicating data is a copy of the raster's data.
static int COPY_MASK
          The bits of a FormatTag associated with how dataArrays are obtained.
static int DATATYPE_MASK
          The bits of a FormatTagID associated with pixel datatype.
static int DEFAULTEXPANSION
          Flag indicating ColorModel data should be used only in copied case
protected  double[][] doubleDataArrays
          The image data in a two-dimensional double array.
static int EXPANDED
          Flag indicating ColorModel data should be interpreted.
static int EXPANSION_MASK
          The bits of a FormatTag associated with how ColorModels are used.
protected  float[][] floatDataArrays
          The image data in a two-dimensional float array.
protected  int formatTagID
          Tag indicating the data type of the data and whether it's copied
protected  int[][] intDataArrays
          The image data in a two-dimensional int array.
protected  int numBands
          The number of bands per pixel in the data array.
protected  int pixelStride
          The pixel stride of the image data in each data array
protected  Raster raster
          The raster that is the source of pixel data.
protected  int rectHeight
          The height of the rectangle this RasterAccessor addresses.
protected  int rectWidth
          The width of the rectangle this RasterAccessor addresses.
protected  int rectX
          The x coordinate of upper-left corner of the rectangle this RasterAccessor addresses.
protected  int rectY
          The y coordinate of upper-left corner of the rectangle this RasterAccessor addresses.
protected  int scanlineStride
          The scanline stride of the image data in each data array
protected  short[][] shortDataArrays
          The image data in a two-dimensional short array.
static int TAG_BYTE_EXPANDED
          FormatTagID indicating data in byte arrays and expanded.
static int TAG_BYTE_UNCOPIED
          FormatTagID indicating data in byte arrays and uncopied.
static int TAG_DOUBLE_COPIED
          FormatTagID indicating data in double arrays and copied.
static int TAG_DOUBLE_UNCOPIED
          FormatTagID indicating data in double arrays and uncopied.
static int TAG_FLOAT_COPIED
          FormatTagID indicating data in float arrays and copied.
static int TAG_FLOAT_UNCOPIED
          FormatTagID indicating data in float arrays and uncopied.
static int TAG_INT_COPIED
          FormatTagID indicating data in int arrays and copied.
static int TAG_INT_UNCOPIED
          FormatTagID indicating data in int arrays and uncopied.
static int TAG_SHORT_UNCOPIED
          FormatTagID indicating data in short arrays and uncopied.
static int TAG_USHORT_UNCOPIED
          FormatTagID indicating data in unsigned short arrays and uncopied.
static int UNCOPIED
          Flag indicating data is raster's data.
static int UNEXPANDED
          Flag indicating ColorModel info should be ignored
 
Constructor Summary
RasterAccessor(Raster raster, Rectangle rect, RasterFormatTag rft, ColorModel theColorModel)
          Constructs a RasterAccessor object out of a Raster, Rectangle and formatTagID returned from RasterFormat.findCompatibleTag().
 
Method Summary
 void clampDataArrays()
          Clamps data array values to a range that the underlying raster can deal with.
 void copyBinaryDataToRaster()
          For the case of binary data (isBinary() returns true), copy the binary data back into the Raster of the RasterAccessor.
 void copyDataToRaster()
          Copies data back into the RasterAccessor's raster.
static int findCompatibleTag(SampleModel[] srcSampleModels, SampleModel dstSampleModel)
          Returns the most efficient FormatTagID that is compatible with the destination SampleModel and all source SampleModels.
static RasterFormatTag[] findCompatibleTags(RenderedImage[] srcs, RenderedImage dst)
          Finds the appropriate tags for the constructor, based on the SampleModel and ColorModel of all the source and destination.
 int getBandOffset(int b)
          Returns the offset of a specific band's first sample into the DataBuffer including the DataBuffer's offset.
 int[] getBandOffsets()
          Returns the bandDataOffsets into the dataArrays.
 byte[] getBinaryDataArray()
          For the case of binary data (isBinary() returns true), return the binary data as a packed byte array.
 byte[] getByteDataArray(int b)
          Returns the image data as a byte array for a specific band.
 byte[][] getByteDataArrays()
          Returns the image data as a byte array.
 Object getDataArray(int b)
          Returns the image data as an Object for a specific band.
 int getDataType()
          Returns the data type of the RasterAccessor object.
 double[] getDoubleDataArray(int b)
          Returns the image data as a double array for a specific band.
 double[][] getDoubleDataArrays()
          Returns the image data as a double array.
 float[] getFloatDataArray(int b)
          Returns the image data as a float array for a specific band.
 float[][] getFloatDataArrays()
          Returns the image data as a float array.
 int getHeight()
          Returns the height of the RasterAccessor's accessible area.
 int[] getIntDataArray(int b)
          Returns the image data as an int array for a specific band.
 int[][] getIntDataArrays()
          Returns the image data as an int array.
 int getNumBands()
          Returns the numBands of the presented area.
 int getOffsetForBand(int b)
          Returns the offset of a specified band's sample from any pixel offset.
 int[] getOffsetsForBands()
          Returns the offset of all band's samples from any pixel offset.
 int getPixelStride()
          Returns the pixelStride for the image data.
 int getScanlineStride()
          Returns the scanlineStride for the image data.
 short[] getShortDataArray(int b)
          Returns the image data as a short array for a specific band.
 short[][] getShortDataArrays()
          Returns the image data as a short array.
 int getWidth()
          Returns the width of the RasterAccessor's accessible area.
 int getX()
          Returns the x coordinate of the upper-left corner of the RasterAccessor's accessible area.
 int getY()
          Returns the y coordinate of the upper-left corner of the RasterAccessor's accessible area.
 boolean isBinary()
          Whether the RasterAccessor represents binary data.
 boolean isDataCopy()
          Returns true if the RasterAccessors's data is copied from it's raster.
 boolean needsClamping()
          Indicates if the RasterAccessor has a larger dynamic range than the underlying Raster.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COPY_MASK

public static final int COPY_MASK
The bits of a FormatTag associated with how dataArrays are obtained.

See Also:
Constant Field Values

UNCOPIED

public static final int UNCOPIED
Flag indicating data is raster's data.

See Also:
Constant Field Values

COPIED

public static final int COPIED
Flag indicating data is a copy of the raster's data.

See Also:
Constant Field Values

EXPANSION_MASK

public static final int EXPANSION_MASK
The bits of a FormatTag associated with how ColorModels are used.

See Also:
Constant Field Values

DEFAULTEXPANSION

public static final int DEFAULTEXPANSION
Flag indicating ColorModel data should be used only in copied case

See Also:
Constant Field Values

EXPANDED

public static final int EXPANDED
Flag indicating ColorModel data should be interpreted.

See Also:
Constant Field Values

UNEXPANDED

public static final int UNEXPANDED
Flag indicating ColorModel info should be ignored

See Also:
Constant Field Values

DATATYPE_MASK

public static final int DATATYPE_MASK
The bits of a FormatTagID associated with pixel datatype.

See Also:
Constant Field Values

TAG_BYTE_UNCOPIED

public static final int TAG_BYTE_UNCOPIED
FormatTagID indicating data in byte arrays and uncopied.

See Also:
Constant Field Values

TAG_USHORT_UNCOPIED

public static final int TAG_USHORT_UNCOPIED
FormatTagID indicating data in unsigned short arrays and uncopied.

See Also:
Constant Field Values

TAG_SHORT_UNCOPIED

public static final int TAG_SHORT_UNCOPIED
FormatTagID indicating data in short arrays and uncopied.

See Also:
Constant Field Values

TAG_INT_UNCOPIED

public static final int TAG_INT_UNCOPIED
FormatTagID indicating data in int arrays and uncopied.

See Also:
Constant Field Values

TAG_FLOAT_UNCOPIED

public static final int TAG_FLOAT_UNCOPIED
FormatTagID indicating data in float arrays and uncopied.

See Also:
Constant Field Values

TAG_DOUBLE_UNCOPIED

public static final int TAG_DOUBLE_UNCOPIED
FormatTagID indicating data in double arrays and uncopied.

See Also:
Constant Field Values

TAG_INT_COPIED

public static final int TAG_INT_COPIED
FormatTagID indicating data in int arrays and copied.

See Also:
Constant Field Values

TAG_FLOAT_COPIED

public static final int TAG_FLOAT_COPIED
FormatTagID indicating data in float arrays and copied.

See Also:
Constant Field Values

TAG_DOUBLE_COPIED

public static final int TAG_DOUBLE_COPIED
FormatTagID indicating data in double arrays and copied.

See Also:
Constant Field Values

TAG_BYTE_EXPANDED

public static final int TAG_BYTE_EXPANDED
FormatTagID indicating data in byte arrays and expanded.

See Also:
Constant Field Values

raster

protected Raster raster
The raster that is the source of pixel data.


rectWidth

protected int rectWidth
The width of the rectangle this RasterAccessor addresses.


rectHeight

protected int rectHeight
The height of the rectangle this RasterAccessor addresses.


rectX

protected int rectX
The x coordinate of upper-left corner of the rectangle this RasterAccessor addresses.


rectY

protected int rectY
The y coordinate of upper-left corner of the rectangle this RasterAccessor addresses.


formatTagID

protected int formatTagID
Tag indicating the data type of the data and whether it's copied


binaryDataArray

protected byte[] binaryDataArray
The image data for the binary case. The data will be packed as eight bits per byte with no bit offset, i.e., the first bit in each image line will be the left-most bit of the first byte of the line. The line stride in bytes will be (int)((rectWidth+7)/8). The length of the array will be rectHeight multiplied by the line stride.

Since:
JAI 1.1

byteDataArrays

protected byte[][] byteDataArrays
The image data in a two-dimensional byte array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_BYTE. byteDataArrays.length will equal numBands. Note that often the numBands subArrays will all point to the same place in memory.

For the case of binary data this variable will not be initialized until getByteDataArrays() or getByteDataArray(int b) is invoked.


shortDataArrays

protected short[][] shortDataArrays
The image data in a two-dimensional short array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_USHORT or DataBuffer.TYPE_SHORT. shortDataArrays.length will equal numBands. Note that often the numBands subArrays will all point to the same place in memory.


intDataArrays

protected int[][] intDataArrays
The image data in a two-dimensional int array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_INT. intDataArrays.length will equal numBands. Note that often the numBands subArrays will all point to the same place in memory.


floatDataArrays

protected float[][] floatDataArrays
The image data in a two-dimensional float array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_FLOAT. floatDataArrays.length will equal numBands. Note that often the numBand subArrays will all point to the same place in memory.


doubleDataArrays

protected double[][] doubleDataArrays
The image data in a two-dimensional double array. This value will be non-null only if getDataType() returns DataBuffer.TYPE_DOUBLE. doubleDataArrays.length will equal numBands. Note that often the numBand subArrays will all point to the same place in memory.


bandDataOffsets

protected int[] bandDataOffsets
The bandOffset + subRasterOffset + DataBufferOffset into each of the numBand data arrays


bandOffsets

protected int[] bandOffsets
Offset from a pixel's offset to a band of that pixel


numBands

protected int numBands
The number of bands per pixel in the data array.


scanlineStride

protected int scanlineStride
The scanline stride of the image data in each data array


pixelStride

protected int pixelStride
The pixel stride of the image data in each data array

Constructor Detail

RasterAccessor

public RasterAccessor(Raster raster,
                      Rectangle rect,
                      RasterFormatTag rft,
                      ColorModel theColorModel)
Constructs a RasterAccessor object out of a Raster, Rectangle and formatTagID returned from RasterFormat.findCompatibleTag().

The RasterFormatTag must agree with the raster's SampleModel and ColorModel. It is best to obtain the correct tag using the findCompatibleTags static method.

Parameters:
raster - The raster to be accessed
rect - A Rectangle from the raster to be accessed
rft - The RasterFormatTag associated with the Raster
theColorModel - The ColorModel for color components
Throws:
ClassCastException - if the data type of RasterFormatTag does not agree with the actual data type of the Raster.
IllegalArgumentException - if raster, rect, or rft is null.
IllegalArgumentException - if the Rectangle is not contained within Raster's bounds.
Method Detail

findCompatibleTags

public static RasterFormatTag[] findCompatibleTags(RenderedImage[] srcs,
                                                   RenderedImage dst)
Finds the appropriate tags for the constructor, based on the SampleModel and ColorModel of all the source and destination.

Parameters:
srcs - The operations sources; may be null which is taken to be equivalent to zero sources.
dst - The operation destination.
Returns:
An array containing RasterFormatTags for the sources in the first src.length elements and a RasterFormatTag for the destination in the last element.
Throws:
NullPointerException - if dst is null.

findCompatibleTag

public static int findCompatibleTag(SampleModel[] srcSampleModels,
                                    SampleModel dstSampleModel)
Returns the most efficient FormatTagID that is compatible with the destination SampleModel and all source SampleModels. Since there is no ColorModel associated with a SampleModel, this method does not expand the data buffer as it has no access to the Raster's ColorModel.


getX

public int getX()
Returns the x coordinate of the upper-left corner of the RasterAccessor's accessible area.


getY

public int getY()
Returns the y coordinate of the upper-left corner of the RasterAccessor's accessible area.


getWidth

public int getWidth()
Returns the width of the RasterAccessor's accessible area.


getHeight

public int getHeight()
Returns the height of the RasterAccessor's accessible area.


getNumBands

public int getNumBands()
Returns the numBands of the presented area.


isBinary

public boolean isBinary()
Whether the RasterAccessor represents binary data. This occurs when the Raster has a MultiPixelPackedSampleModel with a single band and one bit per pixel.

Since:
JAI 1.1

getBinaryDataArray

public byte[] getBinaryDataArray()
For the case of binary data (isBinary() returns true), return the binary data as a packed byte array. The data will be packed as eight bits per byte with no bit offset, i.e., the first bit in each image line will be the left-most of the first byte of the line. The line stride in bytes will be (int)((getWidth()+7)/8). The length of the returned array will be the line stride multiplied by getHeight()

Returns:
the binary data as a packed array of bytes with zero offset of null if the data are not binary.
Since:
JAI 1.1

getByteDataArrays

public byte[][] getByteDataArrays()
Returns the image data as a byte array. Non-null only if getDataType = DataBuffer.TYPE_BYTE.

For the case of binary data the corresponding instance variable byteDataArrays will not be initialized until this method or getByteDataArray(int b) is invoked. The binary data will be returned as bytes with value 0 or 1.


getByteDataArray

public byte[] getByteDataArray(int b)
Returns the image data as a byte array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_BYTE.


getShortDataArrays

public short[][] getShortDataArrays()
Returns the image data as a short array. Non-null only if getDataType = DataBuffer.TYPE_USHORT or DataBuffer.TYPE_SHORT.


getShortDataArray

public short[] getShortDataArray(int b)
Returns the image data as a short array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_USHORT or DataBuffer.TYPE_SHORT.


getIntDataArrays

public int[][] getIntDataArrays()
Returns the image data as an int array. Non-null only if getDataType = DataBuffer.TYPE_INT.


getIntDataArray

public int[] getIntDataArray(int b)
Returns the image data as an int array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_INT.


getFloatDataArrays

public float[][] getFloatDataArrays()
Returns the image data as a float array. Non-null only if getDataType = DataBuffer.TYPE_FLOAT.


getFloatDataArray

public float[] getFloatDataArray(int b)
Returns the image data as a float array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_FLOAT.


getDoubleDataArrays

public double[][] getDoubleDataArrays()
Returns the image data as a double array. Non-null only if getDataType = DataBuffer.TYPE_DOUBLE


getDoubleDataArray

public double[] getDoubleDataArray(int b)
Returns the image data as a double array for a specific band. Non-null only if getDataType = DataBuffer.TYPE_DOUBLE


getDataArray

public Object getDataArray(int b)
Returns the image data as an Object for a specific band.

Parameters:
b - The index of the image band of interest.

getBandOffsets

public int[] getBandOffsets()
Returns the bandDataOffsets into the dataArrays.


getOffsetsForBands

public int[] getOffsetsForBands()
Returns the offset of all band's samples from any pixel offset.


getBandOffset

public int getBandOffset(int b)
Returns the offset of a specific band's first sample into the DataBuffer including the DataBuffer's offset.


getOffsetForBand

public int getOffsetForBand(int b)
Returns the offset of a specified band's sample from any pixel offset.


getScanlineStride

public int getScanlineStride()
Returns the scanlineStride for the image data.

For binary data this stride is applies to the arrays returned by getByteDataArray() and getByteDataArrays() if the data are accessed as bytes; it does not apply to the array returned by getBinaryDataArray() when the data are accessed as bits packed into bytes.


getPixelStride

public int getPixelStride()
Returns the pixelStride for the image data.


getDataType

public int getDataType()
Returns the data type of the RasterAccessor object. Note that this datatype is not necessarily the same data type as the underlying raster.


isDataCopy

public boolean isDataCopy()
Returns true if the RasterAccessors's data is copied from it's raster.


copyBinaryDataToRaster

public void copyBinaryDataToRaster()
For the case of binary data (isBinary() returns true), copy the binary data back into the Raster of the RasterAccessor. If this method is invoked in the non-binary case it does nothing. Any bit offset in the original SampleModel will be accounted for.

Since:
JAI 1.1

copyDataToRaster

public void copyDataToRaster()
Copies data back into the RasterAccessor's raster. Note that the data is cast from the intermediate data format to the raster's format. If clamping is needed, the call clampDataArrays() method needs to be called before calling the copyDataToRaster() method. Note: the raster is expected to be writable - typically a destination raster - otherwise, a run-time exception will occur.

If the data are binary, then the target bit will be set if and only if the corresponding byte is non-zero.


needsClamping

public boolean needsClamping()
Indicates if the RasterAccessor has a larger dynamic range than the underlying Raster. Except in special cases, where the op knows something special, this call will determine whether or not clampDataArrays() needs to be called.


clampDataArrays

public void clampDataArrays()
Clamps data array values to a range that the underlying raster can deal with. For example, if the underlying raster stores data as bytes, but the samples are unpacked into integer arrays by the RasterAccessor for an operation, the operation will need to call clampDataArrays() so that the data in the int arrays is restricted to the range 0..255 before a setPixels() call is made on the underlying raster. Note that some operations (for example, lookup) can guarantee that their results don't need clamping so they can call RasterAccessor.copyDataToRaster() without first calling this function.