java.awt.image

Class ComponentSampleModel

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.

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 {@link 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 {@link 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 {@link 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.

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.

UNKNOWN: This field shadows the protected numBands in SampleModel.

numBanks

protected int numBanks

Used when creating data buffers.

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.

scanlineStride

protected int scanlineStride

The number of data elements between a sample in one row and the corresponding sample in the next 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 {@link DataBuffer}.

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

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 {@link 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 {@link DataBuffer}.

Parameters: dataType the data type (one of {@link DataBuffer#TYPE_BYTE}, {@link DataBuffer#TYPE_USHORT}, {@link DataBuffer#TYPE_SHORT}, {@link DataBuffer#TYPE_INT}, {@link DataBuffer#TYPE_FLOAT} or {@link 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.

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.

Parameters: w the width (must be greater than zero). h the height (must be greater than zero).

Returns: A new sample model.

createDataBuffer

public DataBuffer createDataBuffer()

Creates a new data buffer that is compatible with this sample model.

Returns: The new data buffer.

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.

Parameters: bands the bands (null not permitted).

Returns: The new sample model.

equals

public boolean equals(Object obj)

Tests this sample model for equality with an arbitrary object. Returns true if and only if:

obj is not null;
obj is an instance of ComponentSampleModel;
both models have the same values for the dataType, width, height, pixelStride, scanlineStride, bandOffsets and bankIndices fields.

Parameters: obj the object to test (null permitted).

Returns: true if this sample model is equal to obj, and false otherwise.

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.

getBankIndices

public final int[] getBankIndices()

Returns the indices of the bank(s) in the {@link 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.

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.

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.

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.

Returns: The number of data elements used to store the samples for one pixel.

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 {@link DataBuffer}.

Parameters: x the x-coordinate. y the y-coordinate.

Returns: The offset.

See Also: ComponentSampleModel

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 {@link DataBuffer}.

Parameters: x the x-coordinate. y the y-coordinate. b the band index.

Returns: The offset.

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.

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.

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.

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.

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 {@link DataBuffer}.

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

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.

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: ComponentSampleModel

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.

Returns: The sample sizes.

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.

Parameters: band the band index (ignored here).

Returns: The sample size in bits.

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 {@link DataBuffer}.

Returns: The distance between pixel samples in consecutive rows.

hashCode

public int hashCode()

Returns a hash code for this sample model.

Returns: The hash code.

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).

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: ComponentSampleModel

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.

Parameters: x the x-coordinate. y the y-coordinate. iArray the pixel sample values (null not permitted). data the data buffer (null not permitted).

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.

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: ComponentSampleModel