java.awt.image
Class ComponentSampleModel

java.lang.Object
  extended by java.awt.image.SampleModel
      extended by java.awt.image.ComponentSampleModel
Direct Known Subclasses:
BandedSampleModel, PixelInterleavedSampleModel

public class ComponentSampleModel
extends SampleModel

ComponentSampleModel supports a flexible organization of pixel samples in memory, permitting pixel samples to be interleaved by band, by scanline, and by pixel. A DataBuffer for this sample model has K banks of data. Pixels have N samples, so there are N bands in the DataBuffer. Each band is completely contained in one bank of data, but a bank may contain more than one band. Each pixel sample is stored in a single data element. Within a bank, each band begins at an offset stored in bandOffsets. The banks containing the band is given by bankIndices. Within the bank, there are three dimensions - band, pixel, and scanline. The dimension ordering is controlled by bandOffset, pixelStride, and scanlineStride, which means that any combination of interleavings is supported.


Field Summary
protected  int[] bandOffsets
          The offsets to the first sample for each band.
protected  int[] bankIndices
          The indices of the bank used to store each band in a data buffer.
protected  int numBands
          The number of bands in the image.
protected  int numBanks
          Used when creating data buffers.
protected  int pixelStride
          The number of data elements between a sample for one pixel and the corresponding sample for the next pixel in the same row.
protected  int scanlineStride
          The number of data elements between a sample in one row and the corresponding sample in the next row.
 
Fields inherited from class java.awt.image.SampleModel
dataType, height, width
 
Constructor Summary
ComponentSampleModel(int dataType, int w, int h, int pixelStride, int scanlineStride, int[] bandOffsets)
          Creates a new sample model that assumes that all bands are stored in a single bank of the DataBuffer.
ComponentSampleModel(int dataType, int w, int h, int pixelStride, int scanlineStride, int[] bankIndices, int[] bandOffsets)
          Creates a new sample model that assumes that all bands are stored in a single bank of the DataBuffer.
 
Method Summary
 SampleModel createCompatibleSampleModel(int w, int h)
          Creates a new sample model that is compatible with this one, but with the specified dimensions.
 DataBuffer createDataBuffer()
          Creates a new data buffer that is compatible with this sample model.
 SampleModel createSubsetSampleModel(int[] bands)
          Creates a new sample model that provides access to a subset of the bands that this sample model supports.
 boolean equals(Object obj)
          Tests this sample model for equality with an arbitrary object.
 int[] getBandOffsets()
          Returns the offsets to the first sample in each band.
 int[] getBankIndices()
          Returns the indices of the bank(s) in the DataBuffer used to store the samples for each band.
 Object getDataElements(int x, int y, Object obj, DataBuffer data)
          Returns the samples for the pixel at location (x, y) in a primitive array (the array type is determined by the data type for this model).
 int getNumDataElements()
          Returns the number of data elements used to store the samples for one pixel.
 int getOffset(int x, int y)
          Returns the offset of the sample in band 0 for the pixel at location (x, y).
 int getOffset(int x, int y, int b)
          Returns the offset of the sample in band b for the pixel at location (x, y).
 int[] getPixel(int x, int y, int[] iArray, DataBuffer data)
          Returns all the samples for the pixel at location (x, y) stored in the specified data buffer.
 int[] getPixels(int x, int y, int w, int h, int[] iArray, DataBuffer data)
          Returns the samples for all the pixels in a rectangular region.
 int getPixelStride()
          Returns the distance (in terms of element indices) between the sample for one pixel and the corresponding sample for the next pixel in a row.
 int getSample(int x, int y, int b, DataBuffer data)
          Returns the sample for band b of the pixel at (x, y) that is stored in the specified data buffer.
 int[] getSampleSize()
          Returns the size in bits for each sample (one per band).
 int getSampleSize(int band)
          Returns the size in bits for the samples in the specified band.
 int getScanlineStride()
          Returns the distance (in terms of element indices) between the sample for one pixel and the corresponding sample for the equivalent pixel in the next row.
 int hashCode()
          Returns a hash code for this sample model.
 void setDataElements(int x, int y, Object obj, DataBuffer data)
          Sets the samples for the pixel at location (x, y) from the supplied primitive array (the array type must be consistent with the data type for this model).
 void setPixel(int x, int y, int[] iArray, DataBuffer data)
          Sets the sample values for the pixel at location (x, y) stored in the specified data buffer.
 void setSample(int x, int y, int b, int s, DataBuffer data)
          Sets the sample value for band b of the pixel at location (x, y) in the specified data buffer.
 
Methods inherited from class java.awt.image.SampleModel
getDataElements, getDataType, getHeight, getNumBands, getPixel, getPixel, getPixels, getPixels, getSampleDouble, getSampleFloat, getSamples, getSamples, getSamples, getTransferType, getWidth, setDataElements, setPixel, setPixel, setPixels, setPixels, setPixels, setSample, setSample, setSamples, setSamples, setSamples
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

bandOffsets

protected int[] bandOffsets
The offsets to the first sample for each band.


bankIndices

protected int[] bankIndices
The indices of the bank used to store each band in a data buffer.


numBands

protected int numBands
The number of bands in the image.


numBanks

protected int numBanks
Used when creating data buffers.


scanlineStride

protected int scanlineStride
The number of data elements between a sample in one row and the corresponding sample in the next row.


pixelStride

protected int pixelStride
The number of data elements between a sample for one pixel and the corresponding sample for the next pixel in the same row.

Constructor Detail

ComponentSampleModel

public ComponentSampleModel(int dataType,
                            int w,
                            int h,
                            int pixelStride,
                            int scanlineStride,
                            int[] bandOffsets)
Creates a new sample model that assumes that all bands are stored in a single bank of the DataBuffer.

Note that the bandOffsets array is copied to internal storage to prevent subsequent changes to the array from affecting this object.

Parameters:
dataType - the data type (one of DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT, DataBuffer.TYPE_SHORT, DataBuffer.TYPE_INT, DataBuffer.TYPE_FLOAT or DataBuffer.TYPE_DOUBLE).
w - the width in pixels.
h - the height in pixels.
pixelStride - the number of data elements in the step from a sample in one pixel to the corresponding sample in the next pixel.
scanlineStride - the number of data elements in the step from a sample in a pixel to the corresponding sample in the pixel in the next row.
bandOffsets - the offset to the first element for each band, with the size of the array defining the number of bands (null not permitted).
Throws:
IllegalArgumentException - if dataType is not one of the specified values.
IllegalArgumentException - if w is less than or equal to zero.
IllegalArgumentException - if h is less than or equal to zero.
IllegalArgumentException - if w * h exceeds Integer.MAX_VALUE.
IllegalArgumentException - if pixelStride is negative.
IllegalArgumentException - if scanlineStride is less than or equal to zero.
IllegalArgumentException - if bandOffsets has zero length.

ComponentSampleModel

public ComponentSampleModel(int dataType,
                            int w,
                            int h,
                            int pixelStride,
                            int scanlineStride,
                            int[] bankIndices,
                            int[] bandOffsets)
Creates a new sample model that assumes that all bands are stored in a single bank of the DataBuffer.

Parameters:
dataType - the data type (one of DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT, DataBuffer.TYPE_SHORT, DataBuffer.TYPE_INT, DataBuffer.TYPE_FLOAT or DataBuffer.TYPE_DOUBLE).
w - the width in pixels.
h - the height in pixels.
pixelStride - the number of data elements in the step from a sample in one pixel to the corresponding sample in the next pixel.
scanlineStride - the number of data elements in the step from a sample in a pixel to the corresponding sample in the pixel in the next row.
bankIndices - the index of the bank in which each band is stored (null not permitted). This array is copied to internal storage so that subsequent updates to the array do not affect the sample model.
bandOffsets - the offset to the first element for each band, with the size of the array defining the number of bands (null not permitted). This array is copied to internal storage so that subsequent updates to the array do not affect the sample model.
Throws:
IllegalArgumentException - if dataType is not one of the specified values.
IllegalArgumentException - if w is less than or equal to zero.
IllegalArgumentException - if h is less than or equal to zero.
IllegalArgumentException - if w * h exceeds Integer.MAX_VALUE.
IllegalArgumentException - if pixelStride is negative.
IllegalArgumentException - if scanlineStride is less than or equal to zero.
IllegalArgumentException - if bandOffsets has zero length.
Method Detail

createCompatibleSampleModel

public SampleModel createCompatibleSampleModel(int w,
                                               int h)
Creates a new sample model that is compatible with this one, but with the specified dimensions.

Specified by:
createCompatibleSampleModel in class SampleModel
Parameters:
w - the width (must be greater than zero).
h - the height (must be greater than zero).
Returns:
A new sample model.

createSubsetSampleModel

public SampleModel createSubsetSampleModel(int[] bands)
Creates a new sample model that provides access to a subset of the bands that this sample model supports.

Specified by:
createSubsetSampleModel in class SampleModel
Parameters:
bands - the bands (null not permitted).
Returns:
The new sample model.

createDataBuffer

public DataBuffer createDataBuffer()
Creates a new data buffer that is compatible with this sample model.

Specified by:
createDataBuffer in class SampleModel
Returns:
The new data buffer.

getOffset

public int getOffset(int x,
                     int y)
Returns the offset of the sample in band 0 for the pixel at location (x, y). This offset can be used to read a sample value from a DataBuffer.

Parameters:
x - the x-coordinate.
y - the y-coordinate.
Returns:
The offset.
See Also:
getOffset(int, int, int)

getOffset

public int getOffset(int x,
                     int y,
                     int b)
Returns the offset of the sample in band b for the pixel at location (x, y). This offset can be used to read a sample value from a DataBuffer.

Parameters:
x - the x-coordinate.
y - the y-coordinate.
b - the band index.
Returns:
The offset.

getSampleSize

public final int[] getSampleSize()
Returns the size in bits for each sample (one per band). For this sample model, each band has the same sample size and this is determined by the data type for the sample model.

Specified by:
getSampleSize in class SampleModel
Returns:
The sample sizes.
See Also:
SampleModel.getDataType()

getSampleSize

public final int getSampleSize(int band)
Returns the size in bits for the samples in the specified band. In this class, the sample size is the same for every band and is determined from the data type for the model.

Specified by:
getSampleSize in class SampleModel
Parameters:
band - the band index (ignored here).
Returns:
The sample size in bits.
See Also:
SampleModel.getDataType()

getBankIndices

public final int[] getBankIndices()
Returns the indices of the bank(s) in the DataBuffer used to store the samples for each band. The returned array is a copy, so that altering it will not impact the sample model.

Returns:
The bank indices.

getBandOffsets

public final int[] getBandOffsets()
Returns the offsets to the first sample in each band. The returned array is a copy, so that altering it will not impact the sample model.

Returns:
The offsets.

getScanlineStride

public final int getScanlineStride()
Returns the distance (in terms of element indices) between the sample for one pixel and the corresponding sample for the equivalent pixel in the next row. This is used in the calculation of the element offset for retrieving samples from a DataBuffer.

Returns:
The distance between pixel samples in consecutive rows.

getPixelStride

public final int getPixelStride()
Returns the distance (in terms of element indices) between the sample for one pixel and the corresponding sample for the next pixel in a row. This is used in the calculation of the element offset for retrieving samples from a DataBuffer.

Returns:
The distance between pixel samples in the same row.

getNumDataElements

public final int getNumDataElements()
Returns the number of data elements used to store the samples for one pixel. In this model, this is the same as the number of bands.

Specified by:
getNumDataElements in class SampleModel
Returns:
The number of data elements used to store the samples for one pixel.

getDataElements

public Object getDataElements(int x,
                              int y,
                              Object obj,
                              DataBuffer data)
Returns the samples for the pixel at location (x, y) in a primitive array (the array type is determined by the data type for this model). The obj argument provides an option to supply an existing array to hold the result, if this is null a new array will be allocated.

Specified by:
getDataElements in class SampleModel
Parameters:
x - the x-coordinate.
y - the y-coordinate.
obj - a primitive array that, if not null, will be used to store and return the sample values.
data - the data buffer (null not permitted).
Returns:
An array of sample values for the specified pixel.

getPixel

public int[] getPixel(int x,
                      int y,
                      int[] iArray,
                      DataBuffer data)
Returns all the samples for the pixel at location (x, y) stored in the specified data buffer.

Overrides:
getPixel in class SampleModel
Parameters:
x - the x-coordinate.
y - the y-coordinate.
iArray - an array that will be populated with the sample values and returned as the result. The size of this array should be equal to the number of bands in the model. If the array is null, a new array is created.
data - the data buffer (null not permitted).
Returns:
The samples for the specified pixel.
See Also:
setPixel(int, int, int[], DataBuffer)

getPixels

public int[] getPixels(int x,
                       int y,
                       int w,
                       int h,
                       int[] iArray,
                       DataBuffer data)
Returns the samples for all the pixels in a rectangular region.

Overrides:
getPixels in class SampleModel
Parameters:
x - the x-coordinate.
y - the y-coordinate.
w - the width.
h - the height.
iArray - an array that if non-null will be populated with the sample values and returned as the result.
data - the data buffer (null not permitted).
Returns:
The samples for all the pixels in the rectangle.

getSample

public int getSample(int x,
                     int y,
                     int b,
                     DataBuffer data)
Returns the sample for band b of the pixel at (x, y) that is stored in the specified data buffer.

Specified by:
getSample in class SampleModel
Parameters:
x - the x-coordinate.
y - the y-coordinate.
b - the band index.
data - the data buffer (null not permitted).
Returns:
The sample value.
Throws:
ArrayIndexOutOfBoundsException - if (x, y) is outside the bounds [0, 0, width, height].
See Also:
setSample(int, int, int, int, DataBuffer)

setDataElements

public void setDataElements(int x,
                            int y,
                            Object obj,
                            DataBuffer data)
Sets the samples for the pixel at location (x, y) from the supplied primitive array (the array type must be consistent with the data type for this model).

Specified by:
setDataElements in class SampleModel
Parameters:
x - the x-coordinate.
y - the y-coordinate.
obj - a primitive array containing the pixel's sample values.
data - the data buffer (null not permitted).
See Also:
setDataElements(int, int, Object, DataBuffer)

setPixel

public void setPixel(int x,
                     int y,
                     int[] iArray,
                     DataBuffer data)
Sets the sample values for the pixel at location (x, y) stored in the specified data buffer.

Overrides:
setPixel in class SampleModel
Parameters:
x - the x-coordinate.
y - the y-coordinate.
iArray - the pixel sample values (null not permitted).
data - the data buffer (null not permitted).
See Also:
getPixel(int, int, int[], DataBuffer)

setSample

public void setSample(int x,
                      int y,
                      int b,
                      int s,
                      DataBuffer data)
Sets the sample value for band b of the pixel at location (x, y) in the specified data buffer.

Specified by:
setSample in class SampleModel
Parameters:
x - the x-coordinate.
y - the y-coordinate.
b - the band index.
s - the sample value.
data - the data buffer (null not permitted).
See Also:
getSample(int, int, int, DataBuffer)

equals

public boolean equals(Object obj)
Tests this sample model for equality with an arbitrary object. Returns true if and only if:

Overrides:
equals in class Object
Parameters:
obj - the object to test (null permitted).
Returns:
true if this sample model is equal to obj, and false otherwise.
See Also:
Object.hashCode()

hashCode

public int hashCode()
Returns a hash code for this sample model.

Overrides:
hashCode in class Object
Returns:
The hash code.
See Also:
Object.equals(Object), System.identityHashCode(Object)