模块  java.desktop
软件包  javax.imageio

Class ImageReadParam

  • 已知直接子类：
    JPEGImageReadParam ， TIFFImageReadParam 
    public class ImageReadParam
extends IIOParam
    描述如何解码流的类。 此类或其子类的实例用于向ImageReader实例提供规定性的“操作方法”信息。

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

    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 。

    • 方法详细信息

      • 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)
        设置将放置数据的目标波段的索引。 不允许重复索引。

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

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

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

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

      • getDestinationBands

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

      • canSetSourceRenderSize

        public boolean canSetSourceRenderSize()
        如果此读取器允许通过setSourceRenderSize方法将源图像作为解码过程的一部分以任意大小呈现，则返回true 。 如果此方法返回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 。

        参数
        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大于最后可用传递的索引，则解码将以该传递结束。

        值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() ， getSourceMaxProgressivePass()

      • getSourceMaxProgressivePass

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