Module java.desktop
Package javax.imageio

Class ImageReadParam

java.lang.Object
javax.imageio.IIOParam
javax.imageio.ImageReadParam
直接已知的子类:
JPEGImageReadParam, TIFFImageReadParam
public class ImageReadParam extends IIOParam
描述流如何解码的类。此类或其子类的实例用于向ImageReader的实例提供规定性的“如何”信息。

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

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

ImageReadParam的实例维护的状态与正在解码的任何特定图像无关。当实际解码发生时，读取参数中设置的值将与从流中解码的实际图像的属性以及将接收解码的像素数据的目标BufferedImage的实际属性相结合。例如，使用setSourceRegion设置的源区域将首先与实际有效的源区域相交。结果将由getDestinationOffset返回的值进行平移，并将得到的矩形与实际有效的目标区域相交以产生将要写入的目标区域。

ImageReadParam指定的参数应用于图像如下。首先，如果通过setSourceRenderSize设置了渲染大小，则整个解码图像将以getSourceRenderSize给定的大小呈现。否则，图像具有其由ImageReader.getWidth和ImageReader.getHeight给出的自然大小。

接下来，图像将根据由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实现必须支持该功能（例如，源渲染大小是可选的，但必须支持子采样）。

参见:

  • Field Details

    • 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
      要使用的目标波段集，作为int数组。默认情况下，该值为null，表示应按顺序写入所有目标波段。

    • minProgressivePass

      protected int minProgressivePass
      从源读取的渐进通道的最小索引。默认情况下，该值设置为0，表示应解码从第一个可用通道开始的通道。

      子类应确保此值为非负。

    • numProgressivePasses

      protected int numProgressivePasses
      从源读取的渐进通道的最大数量。默认情况下，该值设置为Integer.MAX_VALUE，表示应解码直到包括最后一个可用通道的通道。

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

  • Constructor Details

    • ImageReadParam

      public ImageReadParam()
      构造一个ImageReadParam。

  • Method Details

    • 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方法提供图像。

      在读取或写入时，如果指定了大于最大目标波段索引的值，或者源波段和要使用的目标波段数量不同，读取器或写入器将抛出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大于最后一个可用传递的索引，则解码将以该传递结束。

      numPasses的值为Integer.MAX_VALUE表示应读取从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

      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（这是正确的值）。
      返回:
      将被解码的传递数量。
      参见: