javax.imageio
类 ImageReadParam

java.lang.Object
  javax.imageio.IIOParam
      javax.imageio.ImageReadParam

直接已知子类：

JPEGImageReadParam

public class ImageReadParam
extends IIOParam

描述如何对流进行解码的类。此类的实例或其子类用于提供 ImageReader 实例的规定“入门”信息。

编码为文件或流的一部分的图像可以被认为是向多维扩展的：宽度和高度的空间维数、band 的数量以及逐步解码传递。此类允许选中所有这些维数中的图像的相邻（不相邻）矩形子区域来进行解码。此外，可以不连续地对空间维数进行二次取样。最后，颜色和格式转换可以通过控制目标图像的 ColorModel 和 SampleModel 来指定，或者通过提供 BufferedImage 或使用 ImageTypeSpecifier 来指定。

ImageReadParam 对象用于指定如何在输入时从 Java Image I/O 框架的上下文中的流转换一幅图像或一组图像。用于特定图像格式的插件将从其 ImageReader 实现的 getDefaultReadParam 方法中返回 ImageReadParam 的实例。

由 ImageReadParam 实例维护的状态与将被解码的任何特定图像无关。在进行实际解码时，read 参数中设置的值与将解码的图像的实际属性组合在一起，这些属性来自将接收解码像素数据的流和目标 BufferedImage。例如，使用 setSourceRegion 设置的源区域将首先与实际有效源区域相交。结果将由 getDestinationOffset 返回的值转换，得到的矩形与实际有效目标区域相交，从而产生将被写入的目标区域。

由 ImageReadParam 指定的参数将被应用于图像，如下所示。首先，如果已经通过 setSourceRenderSize 设置呈现大小，则整个解码图像将按 getSourceRenderSize 给出的大小来呈现。否则，图像的实际大小将由 ImageReader.getWidth 和 ImageReader.getHeight 给定。

接下来，将根据 getSourceXOffset、getSourceYOffset、getSourceWidth 和 getSourceHeight 指定的源区域裁剪图像。

然后根据 IIOParam.setSourceSubsampling 中给出的因子对得到的区域进行二次取样。第一个像素、每一行的像素数和行数都取决于二次取样设置值。调用所得矩形的最小 X 和 Y 坐标 (minX, minY)、其宽度 w 及其高度 h。

将此矩形偏移 (getDestinationOffset().x, getDestinationOffset().y)，并根据目标边界进行裁剪。如果没有设置目标图像，则定义目标图像的宽度为 getDestinationOffset().x + w，高度为 getDestinationOffset().y + h，以便源区域的所有像素都可以写入目标区域中。

二次取样之后放入目标图像中的像素以及写入由 getSourceMinProgressivePass 和 getSourceNumProgressivePasses 指定的某一逐步传递中的那些像素都传递给下一步骤。

最后，根据 setDestinationBands 的注释中描述的算法，将每个像素的源样本映射到目标 band。

插件 writer 可以通过提供实现额外的、特定于插件的接口来扩展 ImageReadParam 的功能。由插件负责记录哪些接口可用以及如何使用。reader 将安静地忽略所有其未知的 ImageReadParam 子类扩展功能。此外，将忽略通常在通过 getDefaultReadParam 创建自己的 ImageReadParam 实例时禁用的所有可选功能。

注意，如果不存在针对某一功能的查询方法，所有 ImageReader 实现就必须都支持该功能（例如，源呈现大小是可选的，但二次取样必须受支持）。

另请参见：

ImageReader, ImageWriter, ImageWriteParam

字段摘要

protected boolean	canSetSourceRenderSize 如果此 ImageReadParam 允许设置源呈现维数，则为 true。
protected BufferedImage	destination 当前目标 BufferedImage；如果没有设置目标图像，则为 null。
protected int[]	destinationBands 要使用的目标 band 集合（int 数组的形式）。
protected int	minProgressivePass 从源中读取的逐步传递的最小索引。
protected int	numProgressivePasses 从源中读取的逐步传递的最大数量。
protected Dimension	sourceRenderSize 如果 canSetSourceRenderSize 为 true，则为源的所需呈现宽度和高度；或者为 null。

从类 javax.imageio.IIOParam 继承的字段

controller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, subsamplingYOffset

构造方法摘要

ImageReadParam()
构造一个 ImageReadParam。

方法摘要

boolean	canSetSourceRenderSize() 如果此 reader 允许通过使用 setSourceRenderSize 方法以任意大小将源图像呈现为解码过程的一部分，则返回 true。
BufferedImage	getDestination() 返回当前由 setDestination 方法设置的 BufferedImage，如果没有设置，则返回 null。
int[]	getDestinationBands() 返回 band 索引的集合，数据将置于该集合中。
int	getSourceMaxProgressivePass() 如果 getSourceNumProgressivePasses 等于 Integer.MAX_VALUE，则返回 Integer.MAX_VALUE。
int	getSourceMinProgressivePass() 返回将被解码的第一个逐步传递的索引。
int	getSourceNumProgressivePasses() 返回将被解码的逐步传递的数量。
Dimension	getSourceRenderSize() 返回解码期间将呈现的源图像的宽度和高度，如果已经通过 setSourceRenderSize 方法设置了的话。
void	setDestination(BufferedImage destination) 提供一个 BufferedImage，将其用作解码像素数据的目标。
void	setDestinationBands(int[] destinationBands) 设置将在其中放置数据的目标 band 的索引。
void	setDestinationType(ImageTypeSpecifier destinationType) 使用 ImageTypeSpecifier 设置目标图像的所需图像类型。
void	setSourceProgressivePasses(int minPass, int numPasses) 设置将被解码的逐步传递的范围。
void	setSourceRenderSize(Dimension size) 如果能够以任意大小呈现图像，则将源宽度和高度设置为所提供的值。

从类 javax.imageio.IIOParam 继承的方法

activateController, getController, getDefaultController, getDestinationOffset, getDestinationType, getSourceBands, getSourceRegion, getSourceXSubsampling, getSourceYSubsampling, getSubsamplingXOffset, getSubsamplingYOffset, hasController, setController, setDestinationOffset, setSourceBands, setSourceRegion, setSourceSubsampling

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

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

字段详细信息

canSetSourceRenderSize

protected boolean canSetSourceRenderSize

如果此 ImageReadParam 允许设置源呈现维数，则为 true。默认情况下，该值为 false。子类必须手工设置此值。

不支持设置源呈现大小的 ImageReader 应该将该值设置为 false。

sourceRenderSize

protected Dimension sourceRenderSize

如果 canSetSourceRenderSize 为 true，则为源的所需呈现宽度和高度；或者为 null。

不支持设置源呈现大小的 ImageReader 可以忽略此值。

destination

protected BufferedImage destination

当前目标 BufferedImage；如果没有设置目标图像，则为 null。默认情况下，该值为 null。

destinationBands

protected int[] destinationBands

要使用的目标 band 集合（int 数组的形式）。默认情况下，该值为 null，指示应该按顺序写入的所有目标 band。

minProgressivePass

protected int minProgressivePass

从源中读取的逐步传递的最小索引。默认情况下，该值被设置为 0，指示应该解码从第一个可用传递开始的传递。

子类应该确保此值为非负。

numProgressivePasses

protected int numProgressivePasses

从源中读取的逐步传递的最大数量。默认情况下，该值被设置为 Integer.MAX_VALUE，指示应该解码直至最后一个可用传递（包括）的传递。

子类应该确保此值为正数。此外，如果该值不是 Integer.MAX_VALUE，则 minProgressivePass + numProgressivePasses - 1 不应该超过 Integer.MAX_VALUE。

构造方法详细信息

ImageReadParam

public ImageReadParam()

构造一个 ImageReadParam。

方法详细信息

setDestinationType

public void setDestinationType(ImageTypeSpecifier destinationType)

从类 IIOParam 复制的描述

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

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

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

覆盖：

类 IIOParam 中的 setDestinationType

参数：

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

另请参见：

IIOParam.getDestinationType()

setDestination

public void setDestination(BufferedImage destination)

提供一个 BufferedImage，将其用作解码像素数据的目标。当前设置的图像将由 read、readAll 和 readRaster 方法写入，对该图像的引用将由这些方法返回。

来自上述那些方法的像素数据将从 getDestinationOffset 指定的偏移量开始写入。

如果 destination 为 null，则新创建的 BufferedImage 将由这些方法返回。

在读取时，检查该图像来验证其 ColorModel 和 SampleModel 是否对应于从 ImageReader 的 getImageTypes 方法返回的 ImageTypeSpecifier 之一。如果不对应，则 reader 将抛出 IIOException。

参数：

destination - 要写入数据的 BufferedImage，或者为 null。

另请参见：

getDestination()

getDestination

public BufferedImage getDestination()

返回当前由 setDestination 方法设置的 BufferedImage，如果没有设置，则返回 null。

返回：

要写入数据的 BufferedImage。

另请参见：

setDestination(java.awt.image.BufferedImage)

setDestinationBands

public void setDestinationBands(int[] destinationBands)

设置将在其中放置数据的目标 band 的索引。索引不能重复。

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

如果没有指定目标图像，选择目标 band 子集不会影响某一读取操作的输出图像中的 band 数；所创建的目标图像仍然拥有相同的 band 数，就像从未调用此方法一样。如果需要目标图像中不同数量的 band，则必须使用 ImageReadParam.setDestination 方法提供一幅图像。

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

参数：

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

抛出：

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

另请参见：

getDestinationBands(), IIOParam.getSourceBands(), ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int)

getDestinationBands

public int[] getDestinationBands()

返回 band 索引的集合，数据将置于该集合中。如果没有设置任何值，则返回 null，指示将使用所有目标 band。

返回：

要使用的目标 band 的索引；或者 null。

另请参见：

setDestinationBands(int[])

canSetSourceRenderSize

public boolean canSetSourceRenderSize()

如果此 reader 允许通过使用 setSourceRenderSize 方法以任意大小将源图像呈现为解码过程的一部分，则返回 true。如果此方法返回 false，那么调用 setSourceRenderSize 将抛出 UnsupportedOperationException。

返回：

如果支持设置源呈现大小，则返回 true。

另请参见：

setSourceRenderSize(java.awt.Dimension)

setSourceRenderSize

public void setSourceRenderSize(Dimension size)
                         throws UnsupportedOperationException

如果能够以任意大小呈现图像，则将源宽度和高度设置为所提供的值。注意，从 ImageReader 上的 getWidth 和 getHeight 方法返回的值不受此方法的影响；它们将继续返回图像的默认大小。类似地，如果图像被平铺，那么平铺宽度和高度也是根据默认大小给出的。

通常应该选定宽度和高度，使宽度与高度的比率接近近似的图像高宽比（从 ImageReader.getAspectRatio 中返回）。

如果此插件不允许设置呈现大小，则抛出 UnsupportedOperationException。

要移除呈现大小设置值，为 size 传入一个 null 值。

参数：

size - 指示所需宽度和高度 Dimension。

抛出：

IllegalArgumentException - 如果宽度或高度为负数或 0。

UnsupportedOperationException - 如果此插件不支持重新设置图像大小。

另请参见：

getSourceRenderSize(), ImageReader.getWidth(int), ImageReader.getHeight(int), ImageReader.getAspectRatio(int)

getSourceRenderSize

public Dimension getSourceRenderSize()

返回解码期间将呈现的源图像的宽度和高度，如果已经通过 setSourceRenderSize 方法设置了的话。null 值指示没有进行设置。

返回：

源图像的呈现宽度和高度（Dimension 的形式）。

另请参见：

setSourceRenderSize(java.awt.Dimension)

setSourceProgressivePasses

public void setSourceProgressivePasses(int minPass,
                                       int numPasses)

设置将被解码的逐步传递的范围。此范围之外的传递将被忽略。

逐步传递是整个图像的重新编码，通常以逐步变高的有效分辨率进行，但要求有更高的传输带宽。最常使用的逐步编码是以 JPEG 格式进行的，其中连续的传递包括高频图像内容的更详细的表示形式。

将被解码的传递的实际数量是在解码期间根据流中可用的实际传递数来确定的。因此，如果 minPass + numPasses - 1 大于最后一个可用传递的索引，则解码将在该传递结束。

Integer.MAX_VALUE 的值为 numPasses 指示应该读取从 minPass 开始的所有传递。否则，最后一个传递的索引（即 minPass + numPasses - 1）一定不能超过 Integer.MAX_VALUE。

如果没有 unsetSourceProgressivePasses 方法，通过调用 setSourceProgressivePasses(0, Integer.MAX_VALUE) 可以达到相同的效果。

参数：

minPass - 要解码的第一个传递的索引。

numPasses - 要解码的传递的最大数量。

抛出：

IllegalArgumentException - 如果 minPass 为负数，numPasses 为负数或 0，或者 numPasses 小于 Integer.MAX_VALUE，但 minPass + numPasses - 1 大于 INTEGER.MAX_VALUE。

另请参见：

getSourceMinProgressivePass(), getSourceMaxProgressivePass()

getSourceMinProgressivePass

public int getSourceMinProgressivePass()

返回将被解码的第一个逐步传递的索引。如果没有设置任何值，则返回 0（此为修正值）。

返回：

将被解码的第一个传递的索引。

另请参见：

setSourceProgressivePasses(int, int), getSourceNumProgressivePasses()

getSourceMaxProgressivePass

public int getSourceMaxProgressivePass()

如果 getSourceNumProgressivePasses 等于 Integer.MAX_VALUE，则返回 Integer.MAX_VALUE。否则返回 getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1。

返回：

将被读取的最后一个传递的索引；或者 Integer.MAX_VALUE。

getSourceNumProgressivePasses

public int getSourceNumProgressivePasses()

返回将被解码的逐步传递的数量。如果没有设置任何值，则返回 Integer.MAX_VALUE（此为修正值）。

返回：

将被解码的传递的数量。

另请参见：

setSourceProgressivePasses(int, int), getSourceMinProgressivePass()