java.awt.image

Class SampleModel

public abstract class SampleModel extends Object

A SampleModel is used to access pixel data from a {@link DataBuffer}. This is used by the {@link Raster} class.

Field Summary
protected int	dataType The DataBuffer type that is used to store the data of the image described.
protected int	height Height of image described.
protected int	numBands Number of bands in the image described.
protected int	width Width of image described.

Constructor Summary
	SampleModel(int dataType, int w, int h, int numBands) Creates a new sample model with the specified attributes.

Method Summary
abstract SampleModel	createCompatibleSampleModel(int w, int h) Creates a new `SampleModel` that is compatible with this model and has the specified width and height.
abstract DataBuffer	createDataBuffer() Creates a new {@link DataBuffer} of the correct type and size for this `SampleModel`.
abstract SampleModel	createSubsetSampleModel(int[] bands) Return a SampleModel with a subset of the bands in this model.
abstract Object	getDataElements(int x, int y, Object obj, DataBuffer data) This method is provided as a faster alternative to getPixel(), that can be used when there is no need to decode the pixel into separate sample values.
Object	getDataElements(int x, int y, int w, int h, Object obj, DataBuffer data)
int	getDataType() Returns the type of the {@link DataBuffer} that this `SampleModel` accesses.
int	getHeight() Returns the height of the pixel data accessible via this `SampleModel`.
int	getNumBands() Returns the number of bands for this `SampleModel`.
abstract int	getNumDataElements()
int[]	getPixel(int x, int y, int[] iArray, DataBuffer data) Returns an array containing the samples for the pixel at (x, y) in the specified data buffer.
float[]	getPixel(int x, int y, float[] fArray, DataBuffer data) Returns an array containing the samples for the pixel at (x, y) in the specified data buffer.
double[]	getPixel(int x, int y, double[] dArray, DataBuffer data) Returns an array containing the samples for the pixel at (x, y) in the specified data buffer.
int[]	getPixels(int x, int y, int w, int h, int[] iArray, DataBuffer data) Returns an array containing the samples for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
float[]	getPixels(int x, int y, int w, int h, float[] fArray, DataBuffer data) Returns an array containing the samples for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
double[]	getPixels(int x, int y, int w, int h, double[] dArray, DataBuffer data) Returns an array containing the samples for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
abstract int	getSample(int x, int y, int b, DataBuffer data) Returns the sample value for the pixel at (x, y) in the specified data buffer.
double	getSampleDouble(int x, int y, int b, DataBuffer data) Returns the sample value for the pixel at (x, y) in the specified data buffer.
float	getSampleFloat(int x, int y, int b, DataBuffer data) Returns the sample value for the pixel at (x, y) in the specified data buffer.
int[]	getSamples(int x, int y, int w, int h, int b, int[] iArray, DataBuffer data) Returns an array containing the samples from one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
float[]	getSamples(int x, int y, int w, int h, int b, float[] fArray, DataBuffer data) Returns an array containing the samples from one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
double[]	getSamples(int x, int y, int w, int h, int b, double[] dArray, DataBuffer data) Returns an array containing the samples from one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
abstract int[]	getSampleSize() Returns an array containing the size (in bits) for each band accessed by the `SampleModel`.
abstract int	getSampleSize(int band) Returns the size (in bits) of the samples for the specified band.
int	getTransferType()
int	getWidth() Returns the width of the pixel data accessible via this `SampleModel`.
abstract void	setDataElements(int x, int y, Object obj, DataBuffer data)
void	setDataElements(int x, int y, int w, int h, Object obj, DataBuffer data)
void	setPixel(int x, int y, int[] iArray, DataBuffer data) Sets the samples for the pixel at (x, y) in the specified data buffer to the specified values.
void	setPixel(int x, int y, float[] fArray, DataBuffer data) Sets the samples for the pixel at (x, y) in the specified data buffer to the specified values.
void	setPixel(int x, int y, double[] dArray, DataBuffer data) Sets the samples for the pixel at (x, y) in the specified data buffer to the specified values.
void	setPixels(int x, int y, int w, int h, int[] iArray, DataBuffer data) Sets the sample values for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
void	setPixels(int x, int y, int w, int h, float[] fArray, DataBuffer data) Sets the sample values for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
void	setPixels(int x, int y, int w, int h, double[] dArray, DataBuffer data) Sets the sample values for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
abstract void	setSample(int x, int y, int b, int s, DataBuffer data) Sets the sample value for a band for the pixel at (x, y) in the specified data buffer.
void	setSample(int x, int y, int b, float s, DataBuffer data) Sets the sample value for a band for the pixel at (x, y) in the specified data buffer.
void	setSample(int x, int y, int b, double s, DataBuffer data) Sets the sample value for a band for the pixel at (x, y) in the specified data buffer.
void	setSamples(int x, int y, int w, int h, int b, int[] iArray, DataBuffer data) Sets the sample values for one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
void	setSamples(int x, int y, int w, int h, int b, float[] fArray, DataBuffer data) Sets the sample values for one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.
void	setSamples(int x, int y, int w, int h, int b, double[] dArray, DataBuffer data) Sets the sample values for one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.

Field Detail

dataType

protected int dataType

The DataBuffer type that is used to store the data of the image described.

height

protected int height

Height of image described.

numBands

protected int numBands

Number of bands in the image described. Package-private here, shadowed by ComponentSampleModel.

width

protected int width

Width of image described.

Constructor Detail

SampleModel

public SampleModel(int dataType, int w, int h, int numBands)

Creates a new sample model with the specified attributes.

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}, {@link DataBuffer#TYPE_DOUBLE} or {@link DataBuffer#TYPE_UNDEFINED}). w the width in pixels (must be greater than zero). h the height in pixels (must be greater than zero). numBands the number of bands (must be greater than zero).

Throws: IllegalArgumentException if dataType is not one of the listed 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 is greater than {@link Integer#MAX_VALUE}.

Method Detail

createCompatibleSampleModel

public abstract SampleModel createCompatibleSampleModel(int w, int h)

Creates a new SampleModel that is compatible with this model and has the specified width and height.

Parameters: w the width (in pixels). h the height (in pixels).

Returns: The new sample model.

createDataBuffer

public abstract DataBuffer createDataBuffer()

Creates a new {@link DataBuffer} of the correct type and size for this SampleModel.

Returns: The data buffer.

createSubsetSampleModel

public abstract SampleModel createSubsetSampleModel(int[] bands)

Return a SampleModel with a subset of the bands in this model. Selects bands.length bands from this sample model. The bands chosen are specified in the indices of bands[]. This also permits permuting the bands as well as taking a subset. Thus, giving an array with 1, 2, 3, ..., numbands, will give an identical sample model.

Parameters: bands Array with band indices to include.

Returns: A new sample model

getDataElements

public abstract Object getDataElements(int x, int y, Object obj, DataBuffer data)

This method is provided as a faster alternative to getPixel(), that can be used when there is no need to decode the pixel into separate sample values.

Parameters: obj An array to return the pixel data in. If null, an array of the right type and size will be created.

Returns: A single pixel as an array object of a primitive type, based on the transfer type. Eg. if transfer type is DataBuffer.TYPE_USHORT, then a short[] object is returned.

getDataElements

public Object getDataElements(int x, int y, int w, int h, Object obj, DataBuffer data)

getDataType

public final int getDataType()

Returns the type of the {@link DataBuffer} that this SampleModel accesses.

Returns: The data buffer type.

getHeight

public final int getHeight()

Returns the height of the pixel data accessible via this SampleModel.

Returns: The height.

getNumBands

public final int getNumBands()

Returns the number of bands for this SampleModel.

Returns: The number of bands.

getNumDataElements

public abstract int getNumDataElements()

getPixel

public int[] getPixel(int x, int y, int[] iArray, DataBuffer data)

Returns an array containing the samples for the pixel at (x, y) in the specified data buffer. If iArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. iArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The pixel sample values.

Throws: NullPointerException if data is null.

getPixel

public float[] getPixel(int x, int y, float[] fArray, DataBuffer data)

Returns an array containing the samples for the pixel at (x, y) in the specified data buffer. If fArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. fArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The pixel sample values.

Throws: NullPointerException if data is null.

getPixel

public double[] getPixel(int x, int y, double[] dArray, DataBuffer data)

Returns an array containing the samples for the pixel at (x, y) in the specified data buffer. If dArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. dArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The pixel sample values.

Throws: NullPointerException if data is null.

getPixels

public int[] getPixels(int x, int y, int w, int h, int[] iArray, DataBuffer data)

Returns an array containing the samples for the pixels in the region specified by (x, y, w, h) in the specified data buffer. The array is ordered by pixels (that is, all the samples for the first pixel are grouped together, followed by all the samples for the second pixel, and so on). If iArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. iArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The pixel sample values.

Throws: NullPointerException if data is null.

getPixels

public float[] getPixels(int x, int y, int w, int h, float[] fArray, DataBuffer data)

Returns an array containing the samples for the pixels in the region specified by (x, y, w, h) in the specified data buffer. The array is ordered by pixels (that is, all the samples for the first pixel are grouped together, followed by all the samples for the second pixel, and so on). If fArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. fArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The pixel sample values.

Throws: NullPointerException if data is null.

getPixels

public double[] getPixels(int x, int y, int w, int h, double[] dArray, DataBuffer data)

Returns an array containing the samples for the pixels in the region specified by (x, y, w, h) in the specified data buffer. The array is ordered by pixels (that is, all the samples for the first pixel are grouped together, followed by all the samples for the second pixel, and so on). If dArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. dArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The pixel sample values.

Throws: NullPointerException if data is null.

getSample

public abstract int getSample(int x, int y, int b, DataBuffer data)

Returns the sample value for the pixel at (x, y) in the specified data buffer.

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. b the band (in the range 0 to getNumBands() - 1). data the data buffer (null not permitted).

Returns: The sample value.

Throws: NullPointerException if data is null.

getSampleDouble

public double getSampleDouble(int x, int y, int b, DataBuffer data)

Returns the sample value for the pixel at (x, y) in the specified data buffer.

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. b the band (in the range 0 to getNumBands() - 1). data the data buffer (null not permitted).

Returns: The sample value.

Throws: NullPointerException if data is null.

getSampleFloat

public float getSampleFloat(int x, int y, int b, DataBuffer data)

Returns the sample value for the pixel at (x, y) in the specified data buffer.

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. b the band (in the range 0 to getNumBands() - 1). data the data buffer (null not permitted).

Returns: The sample value.

Throws: NullPointerException if data is null.

getSamples

public int[] getSamples(int x, int y, int w, int h, int b, int[] iArray, DataBuffer data)

Returns an array containing the samples from one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer. If iArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. b the band (in the range 0 to getNumBands() - 1). iArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The sample values.

Throws: NullPointerException if data is null.

getSamples

public float[] getSamples(int x, int y, int w, int h, int b, float[] fArray, DataBuffer data)

Returns an array containing the samples from one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer. If fArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. b the band (in the range 0 to getNumBands() - 1). fArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The sample values.

Throws: NullPointerException if data is null.

getSamples

public double[] getSamples(int x, int y, int w, int h, int b, double[] dArray, DataBuffer data)

Returns an array containing the samples from one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer. If dArray is not null, it will be populated with the sample values and returned as the result of this function (this avoids allocating a new array instance).

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. b the band (in the range 0 to getNumBands() - 1). dArray an array to populate with the sample values and return as the result (if null, a new array will be allocated). data the data buffer (null not permitted).

Returns: The sample values.

Throws: NullPointerException if data is null.

getSampleSize

public abstract int[] getSampleSize()

Returns an array containing the size (in bits) for each band accessed by the SampleModel.

Returns: An array.

getSampleSize

public abstract int getSampleSize(int band)

Returns the size (in bits) of the samples for the specified band.

Parameters: band the band (in the range 0 to getNumBands() - 1).

Returns: The sample size (in bits).

getTransferType

public int getTransferType()

getWidth

public final int getWidth()

Returns the width of the pixel data accessible via this SampleModel.

Returns: The width.

setDataElements

public abstract void setDataElements(int x, int y, Object obj, DataBuffer data)

setDataElements

public void setDataElements(int x, int y, int w, int h, Object obj, DataBuffer data)

setPixel

public void setPixel(int x, int y, int[] iArray, DataBuffer data)

Sets the samples for the pixel at (x, y) in the specified data buffer to the specified values.

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

Throws: NullPointerException if either iArray or data is null.

setPixel

public void setPixel(int x, int y, float[] fArray, DataBuffer data)

Sets the samples for the pixel at (x, y) in the specified data buffer to the specified values.

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

Throws: NullPointerException if either fArray or data is null.

setPixel

public void setPixel(int x, int y, double[] dArray, DataBuffer data)

Sets the samples for the pixel at (x, y) in the specified data buffer to the specified values.

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

Throws: NullPointerException if either dArray or data is null.

setPixels

public void setPixels(int x, int y, int w, int h, int[] iArray, DataBuffer data)

Sets the sample values for the pixels in the region specified by (x, y, w, h) in the specified data buffer. The array is ordered by pixels (that is, all the samples for the first pixel are grouped together, followed by all the samples for the second pixel, and so on).

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. iArray the pixel sample values (null not permitted). data the data buffer (null not permitted).

Throws: NullPointerException if either iArray or data is null.

setPixels

public void setPixels(int x, int y, int w, int h, float[] fArray, DataBuffer data)

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. fArray the pixel sample values (null not permitted). data the data buffer (null not permitted).

Throws: NullPointerException if either fArray or data is null.

setPixels

public void setPixels(int x, int y, int w, int h, double[] dArray, DataBuffer data)

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. dArray the pixel sample values (null not permitted). data the data buffer (null not permitted).

Throws: NullPointerException if either dArray or data is null.

setSample

public abstract void setSample(int x, int y, int b, int s, DataBuffer data)

Sets the sample value for a band for the pixel at (x, y) in the specified data buffer.

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. b the band (in the range 0 to getNumBands() - 1). s the sample value. data the data buffer (null not permitted).

Throws: NullPointerException if data is null.

setSample

public void setSample(int x, int y, int b, float s, DataBuffer data)

Sets the sample value for a band for the pixel at (x, y) in the specified data buffer.

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. b the band (in the range 0 to getNumBands() - 1). s the sample value. data the data buffer (null not permitted).

Throws: NullPointerException if data is null.

setSample

public void setSample(int x, int y, int b, double s, DataBuffer data)

Sets the sample value for a band for the pixel at (x, y) in the specified data buffer.

Parameters: x the x-coordinate of the pixel. y the y-coordinate of the pixel. b the band (in the range 0 to getNumBands() - 1). s the sample value. data the data buffer (null not permitted).

Throws: NullPointerException if data is null.

setSamples

public void setSamples(int x, int y, int w, int h, int b, int[] iArray, DataBuffer data)

Sets the sample values for one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. b the band (in the range 0 to getNumBands() - 1). iArray the sample values (null not permitted). data the data buffer (null not permitted).

Throws: NullPointerException if either iArray or data is null.

setSamples

public void setSamples(int x, int y, int w, int h, int b, float[] fArray, DataBuffer data)

Sets the sample values for one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. b the band (in the range 0 to getNumBands() - 1). fArray the sample values (null not permitted). data the data buffer (null not permitted).

Throws: NullPointerException if either iArray or data is null.

setSamples

public void setSamples(int x, int y, int w, int h, int b, double[] dArray, DataBuffer data)

Sets the sample values for one band for the pixels in the region specified by (x, y, w, h) in the specified data buffer.

Parameters: x the x-coordinate of the top-left pixel. y the y-coordinate of the top-left pixel. w the width of the region of pixels. h the height of the region of pixels. b the band (in the range 0 to getNumBands() - 1). dArray the sample values (null not permitted). data the data buffer (null not permitted).

Throws: NullPointerException if either iArray or data is null.