java.awt.image
Class SampleModel

java.lang.Object
  extended by java.awt.image.SampleModel
Direct Known Subclasses:
ComponentSampleModel, MultiPixelPackedSampleModel, SinglePixelPackedSampleModel

public abstract class SampleModel
extends Object

A SampleModel is used to access pixel data from a DataBuffer. This is used by the 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 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.
 Object getDataElements(int x, int y, int w, int h, Object obj, DataBuffer data)
           
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.
 int getDataType()
          Returns the type of the 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()
           
 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.
 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.
 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.
 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.
 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.
 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.
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.
 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.
 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.
 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.
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.
 void setDataElements(int x, int y, int w, int h, Object obj, DataBuffer data)
           
abstract  void setDataElements(int x, int y, Object obj, DataBuffer data)
           
 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 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, int[] iArray, 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, 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.
 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, 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 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 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.
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 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.
 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, 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

width

protected int width
Width of 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.


dataType

protected int dataType
The DataBuffer type that is used to store the data of the 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 DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT, DataBuffer.TYPE_SHORT, DataBuffer.TYPE_INT, DataBuffer.TYPE_FLOAT, DataBuffer.TYPE_DOUBLE or 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 Integer.MAX_VALUE.
Method Detail

getWidth

public final int getWidth()
Returns the width of the pixel data accessible via this SampleModel.

Returns:
The width.
See Also:
getHeight()

getHeight

public final int getHeight()
Returns the height of the pixel data accessible via this SampleModel.

Returns:
The height.
See Also:
getWidth()

getNumBands

public final int getNumBands()
Returns the number of bands for this SampleModel.

Returns:
The number of bands.

getNumDataElements

public abstract int getNumDataElements()

getDataType

public final int getDataType()
Returns the type of the DataBuffer that this SampleModel accesses.

Returns:
The data buffer type.

getTransferType

public int getTransferType()

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.

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)

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)

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.

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.
See Also:
getSample(int, int, int, DataBuffer)

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.
See Also:
getSample(int, int, int, DataBuffer)

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.

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

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.

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

createDataBuffer

public abstract DataBuffer createDataBuffer()
Creates a new DataBuffer of the correct type and size for this SampleModel.

Returns:
The data buffer.

getSampleSize

public abstract int[] getSampleSize()
Returns an array containing the size (in bits) for each band accessed by the SampleModel.

Returns:
An array.
See Also:
getSampleSize(int)

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