模块 java.desktop
包 javax.imageio

类 ImageReadParam

java.lang.Object
javax.imageio.IIOParam
javax.imageio.ImageReadParam
已知子类：
JPEGImageReadParam , TIFFImageReadParam
public class ImageReadParam extends IIOParam
描述如何解码流的类。此类或其子类的实例用于向 ImageReader 的实例提供说明性“操作方法”信息。

作为文件或流的一部分编码的图像可以被认为在多个维度上扩展：宽度和高度的空间维度、多个波段和多个渐进式解码通道。此类允许选择所有这些维度的图像的连续（超）矩形子区域进行解码。此外，空间维度可以被不连续地子采样。最后，可以通过控制目标图像的 ColorModel 和 SampleModel 来指定颜色和格式转换，方法是提供 BufferedImage 或使用 ImageTypeSpecifier 。

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

ImageReadParam 实例维护的状态独立于正在解码的任何特定图像。当实际解码发生时，读取参数中设置的值将与从流中解码的图像的实际属性以及将接收解码像素数据的目标 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 的评论中描述的算法，将每个像素的源样本映射到目标波段。

插件编写者可以通过提供实现额外的插件特定接口的子类来扩展 ImageReadParam 的功能。由插件来记录哪些接口可用以及如何使用它们。读者会默默地忽略他们不知道的 ImageReadParam 子类的任何扩展功能。此外，他们可能会忽略在通过 getDefaultReadParam 创建自己的 ImageReadParam 实例时通常禁用的任何可选功能。

请注意，除非某个功能存在查询方法，否则所有ImageReader实现都必须支持它（例如源渲染大小是可选的，但必须支持子采样）。

参见：

  • 字段详细信息

    • canSetSourceRenderSize

      protected boolean canSetSourceRenderSize
      true 如果此 ImageReadParam 允许设置源渲染尺寸。默认情况下，值为 false 。子类必须手动设置此值。

      不支持设置源渲染大小的 ImageReader 应将此值设置为 false 。

    • sourceRenderSize

      protected Dimension  sourceRenderSize
      源的所需渲染宽度和高度，如果 canSetSourceRenderSize 是 true 或 null 。

      ImageReader 不支持设置源渲染大小的 s 可能会忽略此值。

    • destination

      protected BufferedImage  destination
      当前目的地 BufferedImage 或 null（如果未设置）。默认情况下，值为 null 。

    • destinationBands

      protected int[] destinationBands
      要使用的目标波段集，作为 int 的数组。默认情况下，该值为 null ，表示应按顺序写入所有目标带。

    • 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 。

  • 方法详情

    • setDestination

      public void setDestination(BufferedImage  destination)
      提供一个 BufferedImage 用作解码像素数据的目的地。当前设置的图像将由 read 、 readAll 和 readRaster 方法写入，并且这些方法将返回对它的引用。

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

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

      在读取时，检查图像以验证其 ColorModel 和 SampleModel 对应于从 ImageReader 的 getImageTypes 方法返回的 ImageTypeSpecifier 之一。如果没有，读者将抛出一个 IIOException 。

      参数：
      destination - 要写入的 BufferedImage，或 null。
      参见：

    • getDestination

      public BufferedImage  getDestination()
      返回当前由 setDestination 方法设置的 BufferedImage，如果未设置则返回 null。
      返回：
      要写入的 BufferedImage。
      参见：

    • setDestinationBands

      public void setDestinationBands(int[] destinationBands)
      设置将放置数据的目标波段的索引。不允许重复索引。

      null 值表示将使用所有目标频段。

      如果未指定目标图像，选择目标条带子集不会影响读取输出图像中的条带数；创建的目标图像仍将具有相同数量的波段，就好像从未调用过此方法一样。如果目标图像中需要不同数量的波段，则必须使用 ImageReadParam.setDestination 方法提供图像。

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

      参数：
      destinationBands - 要使用的整数波段索引数组。
      抛出：
      IllegalArgumentException - 如果 destinationBands 包含负值或重复值。
      参见：

    • getDestinationBands

      public int[] getDestinationBands()
      返回将放置数据的波段索引集。如果未设置任何值，则返回null 以指示将使用所有目标频段。
      返回：
      要使用的目标频段的索引，或 null 。
      参见：

    • canSetSourceRenderSize

      public boolean canSetSourceRenderSize()
      返回 true 如果此读取器允许在解码过程中通过 setSourceRenderSize 方法以任意大小呈现源图像。如果此方法返回 false ，对 setSourceRenderSize 的调用将抛出 UnsupportedOperationException 。
      返回：
      true 如果支持设置源渲染大小。
      参见：

    • setSourceRenderSize

      public void setSourceRenderSize(Dimension  size) throws UnsupportedOperationException
      如果图像能够以任意大小呈现，请将源宽度和高度设置为提供的值。请注意，ImageReader 上的 getWidth 和 getHeight 方法返回的值不受此方法的影响；他们将继续返回图像的默认大小。类似地，如果图像也被平铺，则平铺宽度和高度根据默认大小给出。

      通常，应选择宽度和高度，使宽度与高度的比率非常接近图像的纵横比，如从 ImageReader.getAspectRatio 返回的那样。

      如果此插件不允许设置渲染大小，则会抛出UnsupportedOperationException。

      要删除渲染大小设置，请为 size 传入值 null。

      参数：
      size - 一个 Dimension 指示所需的宽度和高度。
      抛出：
      IllegalArgumentException - 如果宽度或高度为负数或 0。
      UnsupportedOperationException - 如果此插件不支持调整图像大小。
      参见：

    • getSourceRenderSize

      public Dimension  getSourceRenderSize()
      如果已通过 setSourceRenderSize 方法设置，则返回将在解码期间呈现的源图像的宽度和高度。 null 值表示未进行任何设置。
      返回：
      源图像的渲染宽度和高度为 Dimension 。
      参见：

    • setSourceProgressivePasses

      public void setSourceProgressivePasses(int minPass, int numPasses)
      设置将被解码的渐进通道的范围。超出此范围的通行证将被忽略。

      渐进通道是对整个图像的重新编码，通常以逐渐提高的有效分辨率进行，但需要更大的传输带宽。渐进式编码最常见的用途是在 JPEG 格式中，其中连续传递包括高频图像内容的更详细表示。

      要解码的实际通道数是在解码期间根据流中可用的实际通道数确定的。因此，如果 minPass + numPasses - 1 大于最后可用通道的索引，则解码将以该通道结束。

      Integer.MAX_VALUE 的 numPasses 值表示应读取从 minPass 向前的所有传递。否则，最后一次通过的索引（IE, 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

      public int getSourceMinProgressivePass()
      返回将被解码的第一个渐进通道的索引。如果没有设置任何值，将返回 0（这是正确的值）。
      返回：
      将被解码的第一遍的索引。
      参见：

    • getSourceMaxProgressivePass

      public int getSourceMaxProgressivePass()
      如果 getSourceNumProgressivePasses 等于 Integer.MAX_VALUE ，则返回 Integer.MAX_VALUE 。否则，返回 getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1 。
      返回：
      要读取的最后一遍的索引，或 Integer.MAX_VALUE 。

    • getSourceNumProgressivePasses

      public int getSourceNumProgressivePasses()
      返回将被解码的渐进通道数。如果未设置任何值，将返回 Integer.MAX_VALUE（这是正确的值）。
      返回：
      将被解码的通道数。
      参见：