模块  java.desktop
软件包  javax.imageio

Class IIOParam

  • 已知直接子类：
    ImageReadParam ， ImageWriteParam 
    public abstract class IIOParamextends Object
    所有类的超类，描述如何解码或编码流。 此类包含ImageReadParam和ImageWriteParam共享的所有变量和方法。

    此类提供了指定源区域和目标区域的机制。 读取时，源是流，内存中的图像是目标。 写作时，这些都是相反的。 在写入的情况下，目标区域可以仅与支持像素替换的写入器一起使用。

    可以使用可移动的二次采样网格为读取器和写入器指定抽取子采样。

    可以选择源和目标频带的子集。

    • 字段详细信息

      • sourceRegion

        protected Rectangle sourceRegion
        源区域，如果没有设置，则在 null 。

      • sourceXSubsampling

        protected int sourceXSubsampling
        要在水平方向上应用的抽取子采样。 默认情况下，该值为1 。 该值不得为负数或0。

      • sourceYSubsampling

        protected int sourceYSubsampling
        要在垂直方向上应用的抽取子采样。 默认情况下，该值为1 。 该值不得为负数或0。

      • subsamplingXOffset

        protected int subsamplingXOffset
        在二次采样之前应用于二次采样网格的水平偏移。 要使用的第一个像素将从该区域的原点偏移该量，如果没有指定区域，则偏移该图像的原点。

      • subsamplingYOffset

        protected int subsamplingYOffset
        在二次采样之前应用于二次采样网格的垂直偏移。 要使用的第一个像素将从该区域的原点偏移该量，如果没有指定区域，则偏移该图像的原点。

      • sourceBands

        protected int[] sourceBands
        int的数组，指示将使用哪些源带，或null 。 如果是null ， null使用的源带集合如setSourceBands方法的注释中所述。 不应该允许任何价值为负。

      • destinationType

        protected ImageTypeSpecifier destinationType
        ImageTypeSpecifier用于在读取时生成目标图像，或在写入时设置输出颜色类型。 如果已设置为非，则值为null 。 默认情况下，该值为null 。

      • destinationOffset

        protected Point destinationOffset
        应放置左上角解码像素的目标偏移量。 默认情况下，该值为（0,0）。

    • 构造方法详细信息

      • IIOParam

        protected IIOParam()
        受保护的构造函数只能由子类调用。

    • 方法详细信息

      • setSourceRegion

        public void setSourceRegion​(Rectangle sourceRegion)
        设置感兴趣的源区域。 感兴趣的区域被描述为矩形，源图像的左上角为像素（0,0）并且向下和向右增加值。 实际使用的像素数取决于setSourceSubsampling设置的子采样因子。 如果已设置子采样使得此数字为零，则将抛出IllegalStateException 。

        此方法指定的感兴趣源区域将根据需要进行剪裁，以适应源边界，以及实际I / O时的目标偏移，宽度和高度。

        的值null为sourceRegion将删除任何区域规范，引起要使用的整个图像。

        参数
        sourceRegion -一个 Rectangle指定感兴趣，或源极区域 null 。
        异常
        IllegalArgumentException - 如果 sourceRegion非 null且 sourceRegion.x或 sourceRegion.y为负数。
        IllegalArgumentException - 如果 sourceRegion非 null且 sourceRegion.width或 sourceRegion.height为负数或0。
        IllegalStateException - 如果子采样使得此区域的子采样宽度或高度为零。
        另请参见：
        getSourceRegion() ， setSourceSubsampling(int, int, int, int) ， setDestinationOffset(java.awt.Point) ， getDestinationOffset()

      • getSourceRegion

        public Rectangle getSourceRegion()
        返回要使用的源区域。 返回值是最近一次调用setSourceRegion设置的值，如果没有设置区域，则null 。
        结果
        感兴趣的源区域为 Rectangle或 null 。
        另请参见：
        setSourceRegion(java.awt.Rectangle)

      • setSourceSubsampling

        public void setSourceSubsampling​(int sourceXSubsampling,                                 int sourceYSubsampling,                                 int subsamplingXOffset,                                 int subsamplingYOffset)
        指定要应用于I / O的抽取子采样。 sourceXSubsampling和sourceYSubsampling参数指定子采样周期（ 即 ，在每个源像素之后前进的行数和列数）。 具体来说，1的周期将使用每一行或每列; 2周期将使用每隔一行或每列。 subsamplingXOffset和subsamplingYOffset参数指定subsamplingXOffset subsamplingYOffset采样像素的区域（或图像）原点的偏移量。 调整子样本网格的原点对于在将非常大的源图像二次采样到将被组装成完整的二次采样图像的目标区域时避免接缝是有用的。 大多数用户只想将这些参数保留为0。

        要使用的像素和扫描线的数量计算如下。

        扫描线中的二次采样像素数由下式给出

        truncate[(width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling] 。

        如果该区域的宽度为零，则抛出IllegalStateException 。

        可以类似地计算要使用的扫描线的数量。

        如果区域用于创建大图像的子采样切片，其中切片宽度和高度不是子采样周期的倍数，则将子采样网格设置为从源区域原点以外的某处开始的能力非常有用。 如果子采样网格在图块之间不一致，则图块边界处将存在工件。 通过调整每个瓦片的子采样网格偏移来补偿，可以避免这些伪像。 权衡是为了避免这些伪影，瓷砖的大小不一样。 在这种情况下使用的网格偏移量由下式给出：
        grid offset = [period - （region offset modulo period）] modulo period）

        如果sourceXSubsampling或sourceYSubsampling为0或为负数，则将抛出IllegalArgumentException 。

        如果subsamplingXOffset或subsamplingYOffset为负数或大于或等于相应的期间，则将抛出IllegalArgumentException 。

        没有unsetSourceSubsampling方法; 只需调用setSourceSubsampling(1, 1, 0, 0)即可恢复默认值。

        参数
        sourceXSubsampling - 像素之间前进的列数。
        sourceYSubsampling - 像素之间前进的行数。
        subsamplingXOffset - 区域内第一 subsamplingXOffset的水平偏移量，如果没有设置区域，则为图像内的水平偏移量。
        subsamplingYOffset - 区域内第一 subsamplingYOffset的水平偏移量，如果没有设置区域，则为图像内的水平偏移量。
        异常
        IllegalArgumentException - 如果任一周期为负或0，或者网格偏移为负或大于相应周期。
        IllegalStateException - 如果源区域使得子采样输出不包含像素。

      • setSourceBands

        public void setSourceBands​(int[] sourceBands)
        设置要使用的源波段的索引。 不允许重复索引。

        值null表示将使用所有源波段。

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

        从语义上讲，副本是由数组组成的; 此调用后对数组内容的更改对此IIOParam没有影响。

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

      • getSourceBands

        public int[] getSourceBands()
        返回要使用的源band的集合。 返回值是最近一次调用setSourceBands或null设置的值，如果没有调用setSourceBands 。

        从语义上讲，返回的数组是一个副本; 此调用后对数组内容的更改对此IIOParam没有影响。

        结果
        要使用的源波段组，或 null 。
        另请参见：
        setSourceBands(int[])

      • setDestinationType

        public void setDestinationType​(ImageTypeSpecifier destinationType)
        使用ImageTypeSpecifier为目标图像设置所需的图像类型。

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

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

        参数
        destinationType - 用于确定目标布局和颜色类型的 ImageTypeSpecifier 。
        另请参见：
        getDestinationType()

      • getDestinationType

        public ImageTypeSpecifier getDestinationType()
        返回由读返回图像的类型，如果是通过调用设置为setDestination(ImageTypeSpecifier) ，为ImageTypeSpecifier 。 如果未设置，则返回null 。
        结果
        描述目的地类型的 ImageTypeSpecifier ，或 null 。
        另请参见：
        setDestinationType(javax.imageio.ImageTypeSpecifier)

      • setDestinationOffset

        public void setDestinationOffset​(Point destinationOffset)
        指定目标图像中的偏移量，在此处放置未来的解码像素，读取时或写入区域的位置。

        在读取时，要在目标BufferedImage内写入的区域将从该偏移开始，并且具有由感兴趣的源区域，子采样参数和目的地边界确定的宽度和高度。

        正常写入不受此方法的影响，仅使用ImageWriter.replacePixels执行写入。 对于此类写入，指定的偏移量在输出流图像中，其像素正在被修改。

        没有unsetDestinationOffset方法; 只需调用setDestinationOffset(new Point(0, 0))即可恢复默认值。

        参数
        destinationOffset - 目的地的偏移量，为 Point 。
        异常
        IllegalArgumentException - 如果 destinationOffset是 null 。
        另请参见：
        getDestinationOffset() ， ImageWriter.replacePixels(java.awt.image.RenderedImage, javax.imageio.ImageWriteParam)

      • getDestinationOffset

        public Point getDestinationOffset()
        返回目标图像中要放置像素的偏移量。

        如果setDestinationOffsets没有被调用，一个Point零X和Y值返回（这是正确的值）。

        结果
        目标偏移量为 Point 。
        另请参见：
        setDestinationOffset(java.awt.Point)

      • setController

        public void setController​(IIOParamController controller)
        设置IIOParamController ，用于在调用activateController方法时为此IIOParam对象提供设置，从而覆盖任何默认控制器。 如果参数为null ，则不使用任何控制器，包括任何默认值。 要恢复默认值，请使用setController(getDefaultController()) 。
        参数
        controller - 适当的 IIOParamController或 null 。
        另请参见：
        IIOParamController ， getController() ， getDefaultController() ， hasController() ， activateController()

      • activateController

        public boolean activateController()
        激活此IIOParam对象的已安装IIOParamController并返回结果值。 当此方法返回true ，此IIOParam对象的所有值都将为下一个读取或写入操作做好准备。 如果返回false则此对象中的任何设置都不会受到干扰（ 即 ，用户取消了该操作）。

        通常，控制器将是为特定插件提供IIOParam的子类的用户界面的GUI。 但是，控制器不必是GUI。

        结果
        true如果控制器正常完成。
        异常
        IllegalStateException - 如果当前没有安装控制器。
        另请参见：
        IIOParamController ， setController(IIOParamController) ， getController() ， getDefaultController() ， hasController()