javax.imageio
类 IIOParam

java.lang.Object
  javax.imageio.IIOParam

直接已知子类：

ImageReadParam, ImageWriteParam

public abstract class IIOParam
extends Object

所有描述应该如何对流进行编码和解码的类的超类。此类包含由 ImageReadParam 和 ImageWriteParam 共享的所有变量和方法。

此类提供指定源区域和目标区域的机制。在进行读取操作时，源区域是流，内存储图像是目标区域。进行写入操作时则正好相反。在进行写入时，目标区域只能伴随支持像素替换的 writer 使用。

使用可移动的二次取样网格，可以为 reader 和 writer 指定抽取十分之一的二次取样。

可以选定源 band 和目标 band 的子集。

字段摘要

protected IIOParamController	controller 调用 activateController 方法时，将用来为此 IIOParam 对象提供设置值的 IIOParamController。
protected IIOParamController	defaultController 调用 activateController 方法时，将用来为此 IIOParam 对象提供设置值的默认 IIOParamController。
protected Point	destinationOffset 目标区域中的偏移量，应将左上部解码像素置于此处。
protected ImageTypeSpecifier	destinationType 一个 ImageTypeSpecifier，用来在进行读取操作时生成目标图像，或者在进行写入操作时设置输出颜色类型。
protected int[]	sourceBands 指示将使用的源 band 的 int 数组，或为 null。
protected Rectangle	sourceRegion 源区域；如果没有设置源区域，则为 null。
protected int	sourceXSubsampling 在水平方向应用抽取十分之一的二次取样。
protected int	sourceYSubsampling 在垂直方向应用抽取十分之一的二次取样。
protected int	subsamplingXOffset 在进行二次取样之前，将水平偏移量应用于二次取样网格。
protected int	subsamplingYOffset 在进行二次取样之前，将垂直偏移量应用于二次取样网格。

构造方法摘要

protected

IIOParam() 受保护的构造方法，只能由子类调用。

方法摘要

boolean	activateController() 激活为此 IIOParam 对象安装的 IIOParamController，并返回得到的值。
IIOParamController	getController() 返回当前已安装的所有 IIOParamController。
IIOParamController	getDefaultController() 返回默认 IIOParamController（如果有），不考虑当前安装的控制器。
Point	getDestinationOffset() 返回目标图像中的偏移量，像素将置于该处。
ImageTypeSpecifier	getDestinationType() 以 ImageTypeSpecifier 的形式返回将由读取操作返回的图像类型，如果通过调用 setDestination(ImageTypeSpecifier) 设置了类型的话。
int[]	getSourceBands() 返回要使用的源 band 的集合。
Rectangle	getSourceRegion() 返回将使用的源区域。
int	getSourceXSubsampling() 返回对于每个像素要前进的源列数。
int	getSourceYSubsampling() 返回对于每个像素要前进的行数。
int	getSubsamplingXOffset() 返回二次取样网格的水平偏移量。
int	getSubsamplingYOffset() 返回二次取样网格的垂直偏移量。
boolean	hasController() 如果有一个为此 IIOParam 对象安装的控制器，则返回 true。
void	setController(IIOParamController controller) 设置在调用 activateController 方法时用来为 IIOParam 对象提供设置值的 IIOParamController，重写所有默认控制器。
void	setDestinationOffset(Point destinationOffset) 指定目标图像中的偏移量。
void	setDestinationType(ImageTypeSpecifier destinationType) 使用 ImageTypeSpecifier 设置目标图像的所需图像类型。
void	setSourceBands(int[] sourceBands) 设置将要使用的源 band 的索引。
void	setSourceRegion(Rectangle sourceRegion) 设置感兴趣的源区域。
void	setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset) 指定进行 I/O 时应用的抽取十分之一的二次取样。

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

字段详细信息

sourceRegion

protected Rectangle sourceRegion

源区域；如果没有设置源区域，则为 null。

sourceXSubsampling

protected int sourceXSubsampling

在水平方向应用抽取十分之一的二次取样。默认情况下，该值为 1。该值一定不能为负数或 0。

sourceYSubsampling

protected int sourceYSubsampling

在垂直方向应用抽取十分之一的二次取样。默认情况下，该值为 1。该值一定不能为负数或 0。

subsamplingXOffset

protected int subsamplingXOffset

在进行二次取样之前，将水平偏移量应用于二次取样网格。要使用的第一个像素将距区域或图像（如果没有指定区域）的原点偏移此量。

subsamplingYOffset

protected int subsamplingYOffset

在进行二次取样之前，将垂直偏移量应用于二次取样网格。要使用的第一个像素将距区域或图像（如果没有指定区域）的起点偏移此量。

sourceBands

protected int[] sourceBands

指示将使用的源 band 的 int 数组，或为 null。如果为 null，则将使用的源 band 集合如 setSourceBands 方法的注释所述。不允许任何为负。

destinationType

protected ImageTypeSpecifier destinationType

一个 ImageTypeSpecifier，用来在进行读取操作时生成目标图像，或者在进行写入操作时设置输出颜色类型。如果没有设置，则该值将为 null。默认情况下，该值为 null。

destinationOffset

protected Point destinationOffset

目标区域中的偏移量，应将左上部解码像素置于此处。默认情况下，该值为 (0, 0)。

defaultController

protected IIOParamController defaultController

调用 activateController 方法时，将用来为此 IIOParam 对象提供设置值的默认 IIOParamController。此默认控制器应该由子类设置，这些子类可以选择提供自己的默认控制器（通常是一个 GUI）来设置参数。

另请参见：

IIOParamController, getDefaultController(), activateController()

controller

protected IIOParamController controller

调用 activateController 方法时，将用来为此 IIOParam 对象提供设置值的 IIOParamController。此值重写任何默认控制器，即使为 null 时也是如此。

另请参见：

IIOParamController, setController(IIOParamController), hasController(), activateController()

构造方法详细信息

IIOParam

protected IIOParam()

受保护的构造方法，只能由子类调用。

方法详细信息

setSourceRegion

public void setSourceRegion(Rectangle sourceRegion)

设置感兴趣的源区域。感兴趣的区域被描述为一个矩形，源图像左上角为像素 (0, 0)，该值向下向右递增。所使用的实际像素数将取决于由 setSourceSubsampling 设置的二次取样因子。如果已经在二次取样中将此像素数设置为零，则将抛出 IllegalStateException。

将根据需要限制此方法指定的感兴趣的源区域，使其适合源区域边界，以及在实际 I/O 时符合目标偏移量、宽度和高度。

sourceRegion 值为 null 表示将取消所有区域限制，这将导致使用整个图像。

参数：

sourceRegion - 指定感兴趣的源区域的 Rectangle；或为 null。

抛出：

IllegalArgumentException - 如果 sourceRegion 不为 null 且 sourceRegion.x 或 sourceRegion.y 为负。

IllegalArgumentException - 如果 sourceRegion 不为 null 且 sourceRegion.width 或 sourceRegion.height 为负数或 0。

IllegalStateException - 如果二次取样将使此区域有一个为零的二次取样宽度或高度。

另请参见：

getSourceRegion(), setSourceSubsampling(int, int, int, int), setDestinationOffset(java.awt.Point), getDestinationOffset()

getSourceRegion

public Rectangle getSourceRegion()

返回将使用的源区域。返回的值是通过最近一次调用 setSourceRegion 设置的值，如果没有设置区域，则返回值将为 null。

返回：

Rectangle 形式的感兴趣源区域；或者 null。

另请参见：

setSourceRegion(java.awt.Rectangle)

setSourceSubsampling

public void setSourceSubsampling(int sourceXSubsampling,
                                 int sourceYSubsampling,
                                 int subsamplingXOffset,
                                 int subsamplingYOffset)

指定进行 I/O 时应用的抽取十分之一的二次取样。sourceXSubsampling 和 sourceYSubsampling 参数指定二次取样的周期（即 每个源像素之后前进的行数和列数）。具体地说，周期为 1 将对每行或每列使用二次取样；周期为 2 则每隔一行或一列使用。subsamplingXOffset 和 subsamplingYOffset 参数指定距离第一个二次取样像素的区域（或图像）原点的偏移量。在将一个非常大的源图像二次取样到将组合成一个完整的二次取样图像的目标区域中时，调整二次取样网格的原点对避免裂缝很有用。大多数用户只要让这些参数为 0 即可。

要使用的像素行和扫描行数量的计算如下所示。

扫描行中二次取样像素数的计算方式如下

truncate[(width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling]。

如果在该区域中此宽度为零，则抛出 IllegalStateException。

可以用类似的方法计算要使用的扫描行数。

可以将二次取样网格设置为从源区域原点以外的其他某个地方开始，如果正使用源区域创建大型图像的二次取样 tile，其中 tile 的宽度和高度不是二次取样周期的倍数，这将非常有用。如果在二次取样网格中不能使 tile 保持一致，则在 tile 的边界上会出现某些误差产物。通过调整每个 tile 的二次取样网格偏移量来校正，可避免这些误差产物。权宜之计是，为了避免出现误差产物，tile 的大小并不都是相同的。在这种情况下使用的网格偏移量的计算方式如下：
grid offset = [period - (region offset modulo period)] modulo period)

如果 sourceXSubsampling 或 sourceYSubsampling 为 0 或负数，则将抛出 IllegalArgumentException。

如果 subsamplingXOffset 或 subsamplingYOffset 为负数或大于等于相应的周期，则将抛出 IllegalArgumentException。

没有 unsetSourceSubsampling 方法；调用 setSourceSubsampling(1, 1, 0, 0) 来恢复默认值即可。

参数：

sourceXSubsampling - 要在像素之间前进的列数。

sourceYSubsampling - 要在像素之间前进的行数。

subsamplingXOffset - 该区域或图像（如果没有设置区域）中第一次二次取样的水平偏移量。

subsamplingYOffset - 该区域或图像（如果没有设置区域）中第一次二次取样的水平偏移量。

抛出：

IllegalArgumentException - 如果任意一个周期为负数或 0，或者任意一个网格偏移量为负数或大于相应的周期。

IllegalStateException - 如果源区域中二次取样输出不包含任何像素。

getSourceXSubsampling

public int getSourceXSubsampling()

返回对于每个像素要前进的源列数。

如果尚未调用 setSourceSubsampling，则返回 1（此为修正值）。

返回：

源二次取样的 X 周期。

另请参见：

setSourceSubsampling(int, int, int, int), getSourceYSubsampling()

getSourceYSubsampling

public int getSourceYSubsampling()

返回对于每个像素要前进的行数。

如果尚未调用 setSourceSubsampling，则返回 1（此为修正值）。

返回：

源二次取样的 Y 周期。

另请参见：

setSourceSubsampling(int, int, int, int), getSourceXSubsampling()

getSubsamplingXOffset

public int getSubsamplingXOffset()

返回二次取样网格的水平偏移量。

如果尚未调用 setSourceSubsampling，则返回 0（此为修正值）。

返回：

源二次取样网格的 X 偏移量。

另请参见：

setSourceSubsampling(int, int, int, int), getSubsamplingYOffset()

getSubsamplingYOffset

public int getSubsamplingYOffset()

返回二次取样网格的垂直偏移量。

如果尚未调用 setSourceSubsampling，则返回 0（此为修正值）。

返回：

源二次取样网格的 Y 偏移量。

另请参见：

setSourceSubsampling(int, int, int, int), getSubsamplingXOffset()

setSourceBands

public void setSourceBands(int[] sourceBands)

设置将要使用的源 band 的索引。索引不能重复。

null 值指示所有源 band 都将被使用。

在进行读取时，如果指定大于最大可用源 band 索引的值，或者要使用的源 band 的数量与目标 band 的数量不同，则 reader 或 writer 将抛出 IllegalArgumentException。可以使用 ImageReader.checkReadParamBandSettings 方法自动进行此测试。

根据语义，为该数组生成一个副本；调用此方法后对数组内容进行的更改对此 IIOParam 没有影响。

参数：

sourceBands - 将要使用的整数 band 索引组成的数组。

抛出：

IllegalArgumentException - 如果 sourceBands 包含一个负数或重复的值。

另请参见：

getSourceBands(), ImageReadParam.setDestinationBands(int[]), ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int)

getSourceBands

public int[] getSourceBands()

返回要使用的源 band 的集合。返回的值是通过最近一次调用 setSourceBands 设置的值，如果没有调用过 setSourceBands，则返回 null。

根据语义，返回的数组是一个副本；调用此方法后对数组内容进行的更改对此 IIOParam 没有影响。

返回：

要使用的源 band 的集合；或者 null。

另请参见：

setSourceBands(int[])

setDestinationType

public void setDestinationType(ImageTypeSpecifier destinationType)

使用 ImageTypeSpecifier 设置目标图像的所需图像类型。

在读取时，如果已经使用此方法设置目标区域的布局，则每次调用 ImageReader 的 read 方法都将返回一个新的 BufferedImage，它使用由所提供的类型说明符指定的格式。此方法的一个副作用是，任何由 ImageReadParam.setDestination(BufferedImage) 设置的目标 BufferedImage 将不再被设置为目标。换句话说，在调用 setDestination((BufferedImage)null) 时可以考虑此方法。

在写入时，或许会使用目标类型确定图像的颜色类型。SampleModel 信息将被忽略，其可以为 null。例如，一个 4 band 的图像可以表示 CMYK 或 RGBA 数据。如果设置了目标类型，则其 ColorModel 将重写该图像自身的所有 ColorModel。这在使用 setSourceBands 时极其重要，因为该图像的 ColorModel 将引用整个图像，而不是被写入的 band 的子集。

参数：

destinationType - 用来确定目标布局和颜色类型的 ImageTypeSpecifier。

另请参见：

getDestinationType()

getDestinationType

public ImageTypeSpecifier getDestinationType()

以 ImageTypeSpecifier 的形式返回将由读取操作返回的图像类型，如果通过调用 setDestination(ImageTypeSpecifier) 设置了类型的话。如果没有设置类型，则返回 null。

返回：

描述目标类型的 ImageTypeSpecifier；或者 null。

另请参见：

setDestinationType(javax.imageio.ImageTypeSpecifier)

setDestinationOffset

public void setDestinationOffset(Point destinationOffset)

指定目标图像中的偏移量。在进行读取操作时，将在该处放置以后解码的像素；在进行写入操作时，将在该处写入一个区域。

在读取时，写入目标 BufferedImage 中的区域将从此偏移量开始，并且其宽度和高度是通过感兴趣的源区域、二次取样参数和目标边界确定的。

普通写入操作不受此方法的影响，只有使用 ImageWriter.replacePixels 执行的写入操作会受影响。对于此类写入操作，指定的偏移量位于其像素正被修改的输出流图像中。

没有 unsetDestinationOffset 方法；调用 setDestinationOffset(new Point(0, 0)) 来恢复默认值即可。

参数：

destinationOffset - 目标中 Point 形式的偏移量。

抛出：

IllegalArgumentException - 如果 destinationOffset 为 null。

另请参见：

getDestinationOffset(), ImageWriter.replacePixels(java.awt.image.RenderedImage, javax.imageio.ImageWriteParam)

getDestinationOffset

public Point getDestinationOffset()

返回目标图像中的偏移量，像素将置于该处。

如果尚未调用 setDestinationOffsets，则返回 X 和 Y 值为零的 Point（此为修正值）。

返回：

Point 形式的目标偏移量。

另请参见：

setDestinationOffset(java.awt.Point)

setController

public void setController(IIOParamController controller)

设置在调用 activateController 方法时用来为 IIOParam 对象提供设置值的 IIOParamController，重写所有默认控制器。如果该参数为 null，则不使用任何控制器，包括所有默认控制器。要恢复默认值，请使用 setController(getDefaultController())。

参数：

controller - 一个适当的 IIOParamController，或者为 null。

另请参见：

IIOParamController, getController(), getDefaultController(), hasController(), activateController()

getController

public IIOParamController getController()

返回当前已安装的所有 IIOParamController。返回值可以是默认控制器（如果有）、null 或最近一次调用 setController 时使用的参数。

返回：

当前安装的 IIOParamController；或者 null。

另请参见：

IIOParamController, setController(javax.imageio.IIOParamController), getDefaultController(), hasController(), activateController()

getDefaultController

public IIOParamController getDefaultController()

返回默认 IIOParamController（如果有），不考虑当前安装的控制器。如果没有默认安装器，则返回 null。

返回：

默认 IIOParamController 或 null。

另请参见：

IIOParamController, setController(IIOParamController), getController(), hasController(), activateController()

hasController

public boolean hasController()

如果有一个为此 IIOParam 对象安装的控制器，则返回 true。如果 getController 不返回 null，则此方法将返回 true。

返回：

如果安装了一个控制器，则返回 true。

另请参见：

IIOParamController, setController(IIOParamController), getController(), getDefaultController(), activateController()

activateController

public boolean activateController()

激活为此 IIOParam 对象安装的 IIOParamController，并返回得到的值。当此方法返回 true 时，此 IIOParam 对象的所有值都已准备好进行下一次读取或写入操作。如果返回 false，则此对象中没有任何设置会被干扰（也就是说，用户取消了该操作）。

通常，控制器将是一个 GUI，为特定插件的 IIOParam 的子类提供用户界面。不过，控制器不必一定是 GUI。

返回：

如果控制器完全正常，则返回 true。

抛出：

IllegalStateException - 如果当前没有安装控制器。

另请参见：

IIOParamController, setController(IIOParamController), getController(), getDefaultController(), hasController()