java.awt.image
类 SampleModel

java.lang.Object
  java.awt.image.SampleModel

直接已知子类：

ComponentSampleModel, MultiPixelPackedSampleModel, SinglePixelPackedSampleModel

public abstract class SampleModel
     

      extends 
      Object
     

此抽象类定义一个提取图像像素样本的接口。所有图像数据都被表示成一个像素集合。每个像素由多个样本组成。样本是一个图像 band 的基本数据，band 由图像中某一特定类型的所有样本组成。例如，一个像素可能包含三个样本，分别表示红、绿、蓝的分量。在包含此相素的图像中有三个 band。其中一个 band 由图像中所有像素的红色样本组成。第二个 band 由所有绿色样本组成，第三个 band 由所有蓝色样本组成。像素可以以各种格式存储。例如，特定 band 中的所有样本可以连续存储，单个像素的所有样本也可以连续存储。

SampleModel 的子类指定它们能够表示的样本类型（例如，无符号 8 位 byte、有符号 16 位 short 等），并且可以指定如何在内存中组织样本。在 Java 2D(tm) API 中，内置的图像处理运算符可能无法处理所有可能的样本类型，但通常可以处理 16 位或 16 位以下的无符号整数样本。某些运算符支持更大范围的样本类型。

像素的集合被表示为一个 Raster，它由 DataBuffer 和 SampleModel 组成。SampleModel 允许访问 DataBuffer 中的样本，并提供程序员可以用来直接操作 DataBuffer 中样本和像素的低级别信息。

此类通常是处理图像的一个回调方法。更为有效的代码将 SampleModel 强行转换为适当的子类，并提取直接操作 DataBuffer 中的像素所需的信息。

另请参见：

DataBuffer, Raster, ComponentSampleModel, PixelInterleavedSampleModel, BandedSampleModel, MultiPixelPackedSampleModel, SinglePixelPackedSampleModel

width

protected int width

此 SampleModel 描述的图像数据区域的宽度（以像素位单位）。

height

protected int height

此 SampleModel 描述的图像数据区域的高度（以像素位单位）。

numBands

protected int numBands

此 SampleModel 描述的图像数据的 band 数。

dataType

protected int dataType

存储像素数据的 DataBuffer 的数据类型。

另请参见：

DataBuffer

SampleModel

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

构造一个具有指定参数的 SampleModel。

参数：

dataType - 存储像素数据的 DataBuffer 的数据类型。

w - 图像数据区域的宽度（以像素为单位）。

h - 图像数据区域的高度（以像素为单位）。

numBands - 图像数据的 band 数。

抛出：

IllegalArgumentException - 如果 w 或 h 不大于 0

IllegalArgumentException - 如果 w 和 h 的乘积大于 Integer.MAX_VALUE

IllegalArgumentException - 如果 dataType 不是受支持的数据类型之一

getWidth

public final int getWidth()

返回像素宽度。

返回：

此 SampleModel 描述的图像数据区域的宽度（以像素为单位）。

getHeight

public final int getHeight()

返回像素高度。

返回：

此 SampleModel 描述的图像数据区域的高度（以像素为单位）。

getNumBands

public final int getNumBands()

返回图像数据的总 band 数。

返回：

此 SampleModel 描述的图像数据的 band 数。

getNumDataElements

public abstract int getNumDataElements()

返回通过 getDataElements 和 setDataElements 方法传输一个像素所需的数据元素数。当通过这些方法传输像素时，可以使用压缩或非压缩格式，具体取决于 SampleModel 的实现。使用这些方法，像素就可以作为基本类型的 getNumDataElements() 元素数组传输，基本类型由 getTransferType() 给定。TransferType 可以与 DataType 的存储数据类型相同，也可以不同。

返回：

数据元素的数量。

另请参见：

getDataElements(int, int, Object, DataBuffer), getDataElements(int, int, int, int, Object, DataBuffer), setDataElements(int, int, Object, DataBuffer), setDataElements(int, int, int, int, Object, DataBuffer), getTransferType()

getDataType

public final int getDataType()

返回存储像素数据的 DataBuffer 的数据类型。

返回：

数据类型。

getTransferType

public int getTransferType()

返回通过 getDataElements 和 setDataElements 方法传输像素所使用的 TransferType。当通过这些方法传输像素时，可以使用压缩或非压缩格式，具体取决于 SampleModel 的实现。使用这些方法，像素就可以作为基本类型的 getNumDataElements() 元素数组传输，基本类型由 getTransferType() 给定。TransferType 可以与 DataType 的存储数据类型相同，也可以不同。TransferType 将是 DataBuffer 中定义的类型之一。

返回：

传输类型。

另请参见：

getDataElements(int, int, Object, DataBuffer), getDataElements(int, int, int, int, Object, DataBuffer), setDataElements(int, int, Object, DataBuffer), setDataElements(int, int, int, int, Object, DataBuffer), getNumDataElements(), DataBuffer

getPixel

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

在一个 int 数组中返回指定像素的样本，每个数组元素对应一个样本。如果坐标不在边界内，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 像素位置的 X 坐标

y - 像素位置的 Y 坐标

iArray - 如果不为 null，则在此数组中返回样本

data - 包含图像数据的 DataBuffer

返回：

指定像素的样本。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 iArray 太小而不能容纳输出。

另请参见：

setPixel(int, int, int[], DataBuffer)

getDataElements

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

在 TransferType 类型的基本数组中返回单个像素的数据。对于 Java 2D API 所支持的图像数据，这将是 DataBuffer.TYPE_BYTE、DataBuffer.TYPE_USHORT、DataBuffer.TYPE_INT、DataBuffer.TYPE_SHORT、DataBuffer.TYPE_FLOAT 或 DataBuffer.TYPE_DOUBLE 中的一个。可以使用压缩格式返回数据，从而提高数据传输的效率。通常，obj 应作为 null 传入，从而 Object 将被自动创建，并具有正确的基本数据类型。

以下代码说明了如何将一个像素的数据从 DataBuffer db1（其存储布局由 SampleModel sm1 描述）传输到 DataBuffer db2（其存储布局由 SampleModel sm2 描述）。该传输通常比使用 getPixel/setPixel 更有效。

             SampleModel sm1, sm2;
             DataBuffer db1, db2;
             sm2.setDataElements(x, y, sm1.getDataElements(x, y, null, db1), db2);
 

如果两个 SampleModel 具有相同的 band 数量，相应 band 的每个样本具有相同的位数，且 TransferType 相同，则使用 getDataElements/setDataElements 在两个 DataBuffer/SampleModel 对之间进行传输是合法的。

如果 obj 不为 null，则它应是 TransferType 类型的基本数组。否则抛出 ClassCastException。如果坐标不在边界内，或者 obj 不为 null 且大小不足以保存像素数据，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 像素位置的 X 坐标。

y - 像素位置的 Y 坐标。

obj - 如果不为 null，则 obj 是接收返回像素数据的基本数组。

data - 包含图像数据的 DataBuffer。

返回：

指定像素的数据元素。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 obj 太小而不能容纳输出。

另请参见：

getNumDataElements(), getTransferType(), DataBuffer, setDataElements(int, int, Object, DataBuffer)

getDataElements

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

在 TransferType 类型基本数组中返回指定像素矩形的像素数据。对于 Java 2D API 所支持的图像数据，这将是 DataBuffer.TYPE_BYTE、DataBuffer.TYPE_USHORT、DataBuffer.TYPE_INT、DataBuffer.TYPE_SHORT、DataBuffer.TYPE_FLOAT 或 DataBuffer.TYPE_DOUBLE 中的一个。可以使用压缩格式返回数据，从而提高数据传输的效率。通常，obj 作为 null 传入，从而 Object 将被自动创建，并具有正确的基本数据类型。

以下代码说明了如何将一个像素的数据从 DataBuffer db1（其存储布局由 SampleModel sm1 描述）传输到 DataBuffer db2（其存储布局由 SampleModel sm2 描述）。该传输通常比使用 getPixels/setPixels 更有效。

             SampleModel sm1, sm2;
             DataBuffer db1, db2;
             sm2.setDataElements(x, y, w, h, sm1.getDataElements(x, y, w,
                           h, null, db1), db2);
 

如果两个 SampleModel 具有相同的 band 数量，相应 band 的每个样本具有相同的位数，且 TransferType 相同，则使用 getDataElements/setDataElements 在两个 DataBuffer/SampleModel 对之间进行传输是合法的。

如果 obj 不为 null，则它应是 TransferType 类型的基本数组。否则抛出 ClassCastException。如果坐标不在边界内，或者 obj 不为 null 且大小不足以保存像素数据，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 像素矩形的最小 X 坐标。

y - 像素矩形的最小 Y 坐标。

w - 像素矩形的宽度。

h - 像素矩形的高度。

obj - 如果不为 null，则 obj 是接收返回像素数据的基本数组。

data - 包含图像数据的 DataBuffer。

返回：

指定像素区域的数据元素。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 obj 太小而不能容纳输出。

另请参见：

getNumDataElements(), getTransferType(), setDataElements(int, int, int, int, Object, DataBuffer), DataBuffer

setDataElements

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

根据 TransferType 类型基本数组设置指定 DataBuffer 中单个像素的数据。对于 Java 2D API 所支持的图像数据，这将是 DataBuffer.TYPE_BYTE、DataBuffer.TYPE_USHORT、DataBuffer.TYPE_INT、DataBuffer.TYPE_SHORT、DataBuffer.TYPE_FLOAT 或 DataBuffer.TYPE_DOUBLE 中的一个。数组中的数据可以是压缩格式，从而提高数据传输的效率。

以下代码说明了如何将一个像素的数据从 DataBuffer db1（其存储布局由 SampleModel sm1 描述）传输到 DataBuffer db2（其存储布局由 SampleModel sm2 描述）。该传输通常比使用 getPixel/setPixel 更有效。

             SampleModel sm1, sm2;
             DataBuffer db1, db2;
             sm2.setDataElements(x, y, sm1.getDataElements(x, y, null, db1),
                           db2);
 

如果两个 SampleModel 具有相同的 band 数量，相应 band 的每个样本具有相同的位数，且 TransferType 相同，则使用 getDataElements/setDataElements 在两个 DataBuffer/SampleModel 对之间进行传输是合法的。

obj 必须是 TransferType 类型的基本数组。否则抛出 ClassCastException。如果坐标不在边界内，或者 obj 的大小不足以容纳像素数据，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 像素位置的 X 坐标。

y - 像素位置的 Y 坐标。

obj - 包含像素数据的基本数组。

data - 包含图像数据的 DataBuffer。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 obj 太小而不能容纳输入。

另请参见：

getNumDataElements(), getTransferType(), getDataElements(int, int, Object, DataBuffer), DataBuffer

setDataElements

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

根据 TransferType 类型的基本数组设置指定 DataBuffer 中像素矩形的数据。对于 Java 2D API 所支持的图像数据，这将是 DataBuffer.TYPE_BYTE、DataBuffer.TYPE_USHORT、DataBuffer.TYPE_INT、DataBuffer.TYPE_SHORT、DataBuffer.TYPE_FLOAT 或 DataBuffer.TYPE_DOUBLE 中的一个。数组中的数据可以是压缩格式，从而提高数据传输的效率。

以下代码说明了如何将一个像素的数据从 DataBuffer db1（其存储布局由 SampleModel sm1 描述）传输到 DataBuffer db2（其存储布局由 SampleModel sm2 描述）。该传输通常比使用 getPixels/setPixels 更有效。

             SampleModel sm1, sm2;
             DataBuffer db1, db2;
             sm2.setDataElements(x, y, w, h, sm1.getDataElements(x, y, w, h,
                           null, db1), db2);
 

如果两个 SampleModel 具有相同的 band 数量，相应 band 的每个样本具有相同的位数，且 TransferType 相同，则使用 getDataElements/setDataElements 在两个 DataBuffer/SampleModel 对之间进行传输是合法的。

obj 必须是 TransferType 类型的基本数组。否则抛出 ClassCastException。如果坐标不在边界内，或者 obj 的大小不足以容纳像素数据，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 像素矩形的最小 X 坐标。

y - 像素矩形的最小 Y 坐标。

w - 像素矩形的宽度。

h - 像素矩形的高度。

obj - 包含像素数据的基本数组。

data - 包含图像数据的 DataBuffer。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 obj 太小而不能容纳输入。

另请参见：

getNumDataElements(), getTransferType(), getDataElements(int, int, int, int, Object, DataBuffer), DataBuffer

getPixel

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

在一个 float 数组中返回指定像素的样本。如果坐标不在边界内，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 像素位置的 X 坐标。

y - 像素位置的 Y 坐标。

fArray - 如果不为 null，则在此数组中返回样本。

data - 包含图像数据的 DataBuffer。

返回：

指定像素的样本。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 fArray 太小而不能容纳输出。

另请参见：

setPixel(int, int, float[], DataBuffer)

getPixel

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

在一个 double 数组中返回指定像素的样本。如果坐标不在边界内，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 像素位置的 X 坐标。

y - 像素位置的 Y 坐标。

dArray - 如果不为 null，则在此数组中返回样本。

data - 包含图像数据的 DataBuffer。

返回：

指定像素的样本。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 dArray 太小而不能容纳输出。

另请参见：

setPixel(int, int, double[], DataBuffer)

getPixels

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

在一个 int 数组中返回像素矩形的所有样本，每个数组元素对应一个样本。如果坐标不在边界内，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 左上角像素位置的 X 坐标。

y - 左上角像素位置的 Y 坐标。

w - 像素矩形的宽度。

h - 像素矩形的高度。

iArray - 如果不为 null，则在此数组中返回样本。

data - 包含图像数据的 DataBuffer。

返回：

指定像素区域的样本。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 iArray 太小而不能容纳输出。

另请参见：

setPixels(int, int, int, int, int[], DataBuffer)

getPixels

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

在一个 float 数组中返回像素矩形的所有样本，每个数组元素对应一个样本。如果坐标不在边界内，则抛出 ArrayIndexOutOfBoundsException。

参数：

x - 左上角像素位置的 X 坐标。

y - 左上角像素位置的 Y 坐标。

w - 像素矩形的宽度。

h - 像素矩形的高度。

fArray - 如果不为 null，则在此数组中返回样本。

data - 包含图像数据的 DataBuffer。

返回：

指定像素区域的样本。

抛出：

NullPointerException - 如果 data 为 null。

ArrayIndexOutOfBoundsException - 如果坐标不在边界内，或者 fArray 太小而不能容纳输出。

另请参见：

setPixels(int, int, int, int, float[], DataBuffer)

getPixels

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