模块 java.desktop
包 javax.imageio

类 IIOParam

java.lang.Object
javax.imageio.IIOParam
已知子类：
ImageReadParam , ImageWriteParam
public abstract class IIOParam extends 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 ，要使用的源波段集如 setSourceBands 方法的注释中所述。任何值都不允许为负数。

    • destinationType

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

    • destinationOffset

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

    • defaultController

      protected IIOParamController  defaultController
      当调用 activateController 方法时，默认 IIOParamController 将用于为此 IIOParam 对象提供设置。这个默认值应该由选择提供自己的默认控制器的子类设置，通常是一个 GUI，用于设置参数。
      参见：

    • controller

      protected IIOParamController  controller
      当调用 activateController 方法时，将用于为此 IIOParam 对象提供设置的 IIOParamController。此值覆盖任何默认控制器，即使为 null。
      参见：

  • 构造方法详细信息

    • IIOParam

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

  • 方法详情

    • setSourceRegion

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

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

      sourceRegion 的 null 值将删除任何区域规范，从而导致使用整个图像。

      参数：
      sourceRegion - 一个 Rectangle 指定感兴趣的源区域，或 null 。
      抛出：
      IllegalArgumentException - 如果 sourceRegion 为非 null 且 sourceRegion.x 或 sourceRegion.y 为负。
      IllegalArgumentException - 如果 sourceRegion 是非 null 并且 sourceRegion.width 或 sourceRegion.height 是负数或 0。
      IllegalStateException - 如果子采样使得该区域的子采样宽度或高度为零。
      参见：

    • getSourceRegion

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

    • setSourceSubsampling

      public void setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset)
      指定要应用于 I/O 的抽取子采样。 sourceXSubsampling 和 sourceYSubsampling 参数指定子采样周期（IE，每个源像素后要前进的行数和列数）。具体来说，周期为 1 将使用每一行或每一列；周期为 2 将每隔一行或每隔一列使用一次。 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 - 区域内第一个子样本的水平偏移，如果未设置区域，则在图像内。
      subsamplingYOffset - 区域内第一个子样本的水平偏移，如果未设置区域，则在图像内。
      抛出：
      IllegalArgumentException - 如果任一周期为负或 0，或者任一网格偏移为负或大于相应周期。
      IllegalStateException - 如果源区域使得子采样输出不包含像素。

    • getSourceXSubsampling

      public int getSourceXSubsampling()
      返回每个像素要前进的源列数。

      如果尚未调用 setSourceSubsampling，则返回 1（这是正确的值）。

      返回：
      源子采样 X 周期。
      参见：

    • getSourceYSubsampling

      public int getSourceYSubsampling()
      返回每个像素要前进的行数。

      如果尚未调用 setSourceSubsampling，则返回 1（这是正确的值）。

      返回：
      源子采样 Y 周期。
      参见：

    • getSubsamplingXOffset

      public int getSubsamplingXOffset()
      返回子采样网格的水平偏移量。

      如果尚未调用 setSourceSubsampling，则返回 0（这是正确的值）。

      返回：
      源子采样网格 X 偏移量。
      参见：

    • getSubsamplingYOffset

      public int getSubsamplingYOffset()
      返回子采样网格的垂直偏移量。

      如果尚未调用 setSourceSubsampling，则返回 0（这是正确的值）。

      返回：
      源子采样网格 Y 偏移量。
      参见：

    • setSourceBands

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

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

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

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

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

    • getSourceBands

      public int[] getSourceBands()
      返回要使用的源波段集。返回值是由最近调用 setSourceBands 或 null（如果没有调用 setSourceBands）设置的值。

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

      返回：
      要使用的源波段集，或 null 。
      参见：

    • setDestinationType

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

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

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

      参数：
      destinationType - ImageTypeSpecifier 用于确定目标布局和颜色类型。
      参见：

    • getDestinationType

      public ImageTypeSpecifier  getDestinationType()
      返回读取返回的图像类型，如果通过调用 setDestination(ImageTypeSpecifier) 设置为 ImageTypeSpecifier 。如果未设置，则返回 null。
      返回：
      描述目标类型的 ImageTypeSpecifier 或 null 。
      参见：

    • setDestinationOffset

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

      读取时，目标 BufferedImage 内要写入的区域将从该偏移量开始，其宽度和高度由感兴趣的源区域、二次采样参数和目标边界决定。

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

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

      参数：
      destinationOffset - 目标中的偏移量，如 Point 。
      抛出：
      IllegalArgumentException - 如果 destinationOffset 是 null。
      参见：

    • getDestinationOffset

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

      如果尚未调用 setDestinationOffsets，则返回 X 和 Y 值为零的 Point（这是正确的值）。

      返回：
      目标偏移量为 Point 。
      参见：

    • setController

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

    • getController

      public IIOParamController  getController()
      返回当前安装的任何 IIOParamController。如果有一个 null 或最近调用 setController 的参数，这可能是默认值。
      返回：
      当前安装的 IIOParamController 或 null 。
      参见：

    • getDefaultController

      public IIOParamController  getDefaultController()
      返回默认值 IIOParamController ，如果有的话，不管当前安装的控制器是什么。如果没有默认控制器，则返回 null 。
      返回：
      默认 IIOParamController 或 null 。
      参见：

    • hasController

      public boolean hasController()
      如果为此 IIOParam 对象安装了控制器，则返回 true。如果 getController 不返回 null，这将返回 true。
      返回：
      true 如果安装了控制器。
      参见：

    • activateController

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

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

      返回：
      true 如果控制器正常完成。
      抛出：
      IllegalStateException - 如果当前没有安装控制器。
      参见：