Module  java.desktop
软件包  javax.imageio

Class ImageReadParam

  • 已知直接子类：
    JPEGImageReadParam ， TIFFImageReadParam 

    public class ImageReadParam
extends IIOParam
    描述流如何解码的类。 该类或其子类的实例用于向ImageReader实例提供规定的“how-to”信息。

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

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

    由ImageReadParam实例维护的状态与被解码的任何特定图像无关。 当实际解码发生时，将读取参数中设置的值与正在从流解码的图像的实际属性和将接收解码的像素数据的目的地BufferedImage 。 例如，使用setSourceRegion设置的源区域将首先与实际的有效源区域相交。 结果将按getDestinationOffset返回的值进行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指定的逐行通过之一进行写入的getSourceNumProgressivePasses将传递到下一步。

    最后，根据setDestinationBands的评论中描述的算法将每个像素的源样本映射到目标频带。

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

    请注意，除非存在某种能力的查询方法，否则必须由所有ImageReader实施支持（ 例如，源渲染大小是可选的，但必须支持子抽样）。

    另请参见：
    ImageReader ， ImageWriter ， ImageWriteParam

    • 字段详细信息

      • canSetSourceRenderSize

        protected boolean canSetSourceRenderSize
        true如果这个ImageReadParam允许设置源渲染维度。 默认值为false 。 子类必须手动设置此值。

        不支持设置源渲染大小的ImageReader s应将此值设置为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 。

    • 方法详细信息

      • setDestinationType

        public void setDestinationType​(ImageTypeSpecifier destinationType)
        描述从类复制： IIOParam
        使用ImageTypeSpecifier设置目标图像的所需图像类型。

        读取时，如果使用此方法设置了目的地的布局，则每次调用ImageReader read方法将使用提供的类型说明符指定的格式返回新的BufferedImage 。 作为副作用，任何目的地BufferedImage组由ImageReadParam.setDestination(BufferedImage)将不再被设定为目的地。 换句话说，这种方法可以被认为是调用setDestination((BufferedImage)null) 。

        当写入时，目的地类型可能用于确定图像的颜色类型。 SampleModel信息将被忽略，可能是null 。 例如，4带图像可以表示CMYK或RGBA数据。 如果设置了目的地类型，其ColorModel将覆盖图像本身的任何ColorModel 。 当使用setSourceBands时，这是至关重要的，因为图像的ColorModel将引用整个图像，而不是要写入的频带子集。

        重写：
        setDestinationType在 IIOParam
        参数
        destinationType - 用于确定目的地布局和颜色类型的 ImageTypeSpecifier 。
        另请参见：
        IIOParam.getDestinationType()

      • setDestination

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

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

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

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

        参数
        destination - 要写入的BufferedImage，或 null 。
        另请参见：
        getDestination()

      • setDestinationBands

        public void setDestinationBands​(int[] destinationBands)
        设置要放置数据的目标频带的索引。 不允许重复索引。

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

        如果没有指定目的地图像，则选择目的地频带子集不会影响读取的输出图像中的频带数; 创建的目标图像仍然具有相同数量的带，就像该方法从未被调用一样。 如果需要目标图像中的不同数量的频带，则必须使用ImageReadParam.setDestination方法提供图像。

        在阅读或写入时，如果已经指定了大于最大目的地频段索引的值，或者要使用的源频带和目标频带数量不同，读写器将抛出IllegalArgumentException 。 ImageReader.checkReadParamBandSettings方法可用于自动化此测试。

        参数
        destinationBands - 要使用的整数带索引数组。
        异常
        IllegalArgumentException - 如果 destinationBands包含负值或重复值。
        另请参见：
        getDestinationBands() ， IIOParam.getSourceBands() ， ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int)

      • getDestinationBands

        public int[] getDestinationBands​()
        返回将放置数据的频带索引集。 如果没有设置值，则返回null ，表示将使用所有目标频带。
        结果
        要使用的目的地频段的索引，或 null 。
        另请参见：
        setDestinationBands(int[])

      • canSetSourceRenderSize

        public boolean canSetSourceRenderSize​()
        返回true如果这个读出器允许源图像以任意大小来呈现作为解码过程的一部分，由所述的装置setSourceRenderSize方法。 如果此方法返回false ，则对setSourceRenderSize调用将抛出一个UnsupportedOperationException 。
        结果
        true如果设置源渲染大小被支持。
        另请参见：
        setSourceRenderSize(java.awt.Dimension)

      • setSourceRenderSize

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

        通常，宽度和高度应该被选择为使得宽度与高度的比率近似于从ImageReader.getAspectRatio返回的图像的纵横比。

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

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

        参数
        size - 一个 Dimension表示所需的宽度和高度。
        异常
        IllegalArgumentException - 如果宽度或高度为负或为0。
        UnsupportedOperationException - 如果此插件不支持图像调整大小。
        另请参见：
        getSourceRenderSize() ， ImageReader.getWidth(int) ， ImageReader.getHeight(int) ， ImageReader.getAspectRatio(int)

      • getSourceRenderSize

        public Dimension getSourceRenderSize​()
        返回源图像在解码过程中渲染的宽度和高度（如果已通过setSourceRenderSize方法设置）。 A null值表示没有设置。
        结果
        源图像的渲染宽度和高度为 Dimension 。
        另请参见：
        setSourceRenderSize(java.awt.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 - 要解码的 minPass的索引。
        numPasses - 要解码的最大通过次数。
        异常
        IllegalArgumentException - 如果 minPass为负数， numPasses为负数或为 numPasses则 numPasses为 Integer.MAX_VALUE但 minPass + numPasses - 1为 INTEGER.MAX_VALUE 。
        另请参见：
        getSourceMinProgressivePass() ， getSourceMaxProgressivePass()

      • getSourceMaxProgressivePass

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