Module  java.desktop
软件包  javax.imageio

Class ImageWriteParam

  • 已知直接子类：
    BMPImageWriteParam ， JPEGImageWriteParam 

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

    用于特定图像格式的插件可以定义该类的子类，并从其ImageWriter实现的getDefaultWriteParam方法返回该类的对象。 例如，内置的JPEG writer插件将返回javax.imageio.plugins.jpeg.JPEGImageWriteParam实例。

    要写入的图像的区域由首先将图像的实际边界与由IIOParam.setSourceRegion指定的矩形IIOParam.setSourceRegion （如果有的话）确定。 如果生成的矩形的宽度或高度为零，作者将抛出一个IIOException 。 如果交集不为空，则写入将从第一个子采样像素开始，并根据IIOParam.setSourceSubsampling指定的水平和垂直子采样因子在相交的边界内包含附加像素。

    可以在四种模式之一中设置诸如平铺，逐行编码和压缩的各种特征。 MODE_DISABLED禁用功能; MODE_DEFAULT启用具有写入控制参数值的功能; MODE_EXPLICIT启用该功能并允许使用set方法提供其他参数; 和MODE_COPY_FROM_METADATA从传递给作者的流和图像元数据对象复制相关参数值。 所有功能的默认值为MODE_COPY_FROM_METADATA 。 鼓励在子类中提供的非标准功能，但不需要使用类似的方案。

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

    请注意，除非存在某种功能的查询方法，否则必须由所有ImageWriter实现支持（ 例如逐行编码是可选的，但必须支持子采样）。

    另请参见：
    ImageReadParam

    • 字段详细信息

      • canWriteTiles

        protected boolean canWriteTiles
        A boolean是true如果这个ImageWriteParam允许设置瓦片宽度和瓦片高度参数。 默认值为false 。 子类必须手动设置该值。

        不支持写入false贴的子类应确保此值设置为false 。

      • preferredTileSizes

        protected Dimension[] preferredTileSizes
        一组优选的瓷砖尺寸范围对。 默认值为null ，表示没有首选尺寸。 如果值不是null ，则它的长度必须至少为2。

        不支持写图块的子类可能会忽略此值。

        另请参见：
        getPreferredTileSizes()

      • tilingSet

        protected boolean tilingSet
        A boolean如果已经指定了平铺参数，则为true 。

        不支持写图块的子类可能会忽略此值。

      • tileWidth

        protected int tileWidth
        每个瓦片的宽度如果已经设置了平铺，否则为0。

        不支持平铺的子类可能忽略此值。

      • tileHeight

        protected int tileHeight
        每个瓦片的高度如果平铺已设置，否则为0。 初始值为0 。

        不支持平铺的子类可能忽略此值。

      • canOffsetTiles

        protected boolean canOffsetTiles
        A boolean是true如果这个ImageWriteParam允许设置平铺网格偏移参数。 默认值为false 。 子类必须手动设置该值。

        不支持编写图块的子类，或支持写入但不支持拼贴的子类必须确保将此值设置为false 。

      • tileGridXOffset

        protected int tileGridXOffset
        如果已经设置了平铺，则瓦片网格原点应从图像原点水平偏移，否则为0。 初始值为0 。

        不支持偏移图块的子类可能忽略此值。

      • tileGridYOffset

        protected int tileGridYOffset
        如果平铺已设置，则瓦片网格原点应与图像原点垂直偏移，否则为0。 初始值为0 。

        不支持偏移图块的子类可能忽略此值。

      • canWriteProgressive

        protected boolean canWriteProgressive
        A boolean是true如果这个ImageWriteParam允许图像被写入作为逐渐增加的质量通行序列。 默认值为false 。 子类必须手动设置该值。

        不支持逐行编码的子类必须确保此值设置为false 。

      • canWriteCompressed

        protected boolean canWriteCompressed
        A boolean是true如果这个作者可以使用压缩书写图像。 默认值为false 。 子类必须手动设置该值。

        不支持压缩的子类必须确保此值设置为false 。

      • compressionTypes

        protected String[] compressionTypes
        String的数组包含可用压缩类型的名称。 子类必须手动设置该值。

        不支持压缩的子类可能忽略此值。

      • compressionType

        protected String compressionType
        A String包含当前压缩类型的名称，如果没有设置， null 。

        不支持压缩的子类可能忽略此值。

      • compressionQuality

        protected float compressionQuality
        A float包含当前的压缩质量设置。 初始值为1.0F 。

        不支持压缩的子类可能忽略此值。

      • locale

        protected Locale locale
        A Locale用于本地化压缩类型名称和质量描述，或null使用默认值Locale 。 子类必须手动设置该值。

    • 构造方法详细信息

      • ImageWriteParam

        protected ImageWriteParam​()
        构造一个空的ImageWriteParam 。 子类可以正确设置实例变量。

      • ImageWriteParam

        public ImageWriteParam​(Locale locale)
        构造一个 ImageWriteParam集使用给定的 Locale 。
        参数
        locale -一个 Locale使用本地化压缩类型名称和质量描述，或 null 。

    • 方法详细信息

      • getLocale

        public Locale getLocale​()
        如果仅支持默认值 Locale则返回当前设置的 Locale或 null 。
        结果
        目前为 Locale ，或 null 。

      • canWriteTiles

        public boolean canWriteTiles​()
        如果作家在写作时可以执行true则返回true 。 如果这个方法返回false ，那么setTiling会抛出一个UnsupportedOperationException 。
        结果
        true如果作者支持平铺。
        另请参见：
        canOffsetTiles() ， setTiling(int, int, int, int)

      • canOffsetTiles

        public boolean canOffsetTiles​()
        如果作者在写入时可以执行非零网格偏移的平铺，则返回true 。 如果此方法返回false ，则setTiling将抛出一个UnsupportedOperationException如果网格偏移参数不为零。 如果canWriteTiles返回false ，此方法也将返回false 。
        结果
        true如果作者支持非零瓦片偏移。
        另请参见：
        canWriteTiles() ， setTiling(int, int, int, int)

      • setTilingMode

        public void setTilingMode​(int mode)
        确定图像是否将平铺在输出流中，如果是，将确定平铺参数的确定方式。 模式解释如下：
        • MODE_DISABLED - 图像不会被平铺。 setTiling将会抛出一个IllegalStateException 。
        • MODE_DEFAULT - 图像将使用默认参数进行平铺。 setTiling会抛出一个IllegalStateException 。
        • MODE_EXPLICIT - 图像将按照setTiling中给出的参数进行平铺。 任何先前设置的平铺参数都将被丢弃。
        • MODE_COPY_FROM_METADATA - 图像将符合传入到写入的元数据对象。 setTiling会抛出一个IllegalStateException 。
        参数
        mode - 用于平铺的模式。
        异常
        UnsupportedOperationException - 如果 canWriteTiles返回 false 。
        IllegalArgumentException - 如果 mode不是上面列出的一种模式。
        另请参见：
        setTiling(int, int, int, int) ， getTilingMode()

      • getTilingMode

        public int getTilingMode​()
        如果支持平铺，返回当前的平铺模式。 否则会抛出一个UnsupportedOperationException 。
        结果
        当前的平铺模式。
        异常
        UnsupportedOperationException - 如果 canWriteTiles返回 false 。
        另请参见：
        setTilingMode(int)

      • getPreferredTileSizes

        public Dimension[] getPreferredTileSizes​()
        返回一个Dimension s的数组，表示瓦片的合法尺寸范围，因为它们将被编码在输出文件或流中。 返回的数组是一个副本。

        信息作为一组对返回; 一对的第一个元素包含（包括）最小宽度和高度，第二个元素包含（包含）最大宽度和高度。 在一起，每对都定义了一个有效的大小范围。 要指定固定的大小，请对两个元素使用相同的宽度和高度。 要指定任意范围，使用值null代替Dimension的实际数组。

        如果在构造函数中没有指定数组，但是允许平铺，那么此方法将返回null 。

        结果
        Dimension的阵列至少有两个，即 null 。
        异常
        UnsupportedOperationException - 如果插件不支持 UnsupportedOperationException 。

      • setTiling

        public void setTiling​(int tileWidth,
                      int tileHeight,
                      int tileGridXOffset,
                      int tileGridYOffset)
        指定图像应该平铺在输出流中。 tileWidth和tileHeight参数指定文件中图块的宽度和高度。 如果图块宽度或高度大于图像的宽度或高度，则图像不会在该维度中平铺。

        如果canOffsetTiles返回false ，则tileGridXOffset和tileGridYOffset参数必须为零。

        参数
        tileWidth - 每个瓷砖的宽度。
        tileHeight - 每个瓷砖的高度。
        tileGridXOffset - 瓦片网格的水平偏移。
        tileGridYOffset - 瓦片网格的垂直偏移。
        异常
        UnsupportedOperationException - 如果插件不支持平铺。
        IllegalStateException - 如果平铺模式不是 MODE_EXPLICIT 。
        UnsupportedOperationException - 如果插件不支持网格偏移，并且网格偏移量不为零。
        IllegalArgumentException - 如果瓷砖尺寸不在 getPreferredTileSizes返回的允许范围之内。
        IllegalArgumentException - 如果 tileWidth或 tileHeight小于或等于0。
        另请参见：
        canWriteTiles ， canOffsetTiles ， getTileWidth() ， getTileHeight() ， getTileGridXOffset() ， getTileGridYOffset()

      • canWriteProgressive

        public boolean canWriteProgressive​()
        返回 true如果作者可以将图像作为逐渐增加的质量的一系列通过书写出来。
        结果
        true如果作者支持逐行编码。
        另请参见：
        setProgressiveMode(int) ， getProgressiveMode()

      • setProgressiveMode

        public void setProgressiveMode​(int mode)
        指定写入器将以逐行模式写入图像，以使流包含一系列增加质量的扫描。 如果不支持渐进式编码，则会抛出UnsupportedOperationException 。

        模式参数确定如何选择progression参数，并且必须是MODE_DISABLED ， MODE_COPY_FROM_METADATA ，或MODE_DEFAULT 。 否则抛出一个IllegalArgumentException 。

        模式解释如下：

        • MODE_DISABLED - 无进展。 使用它来关闭进度。
        • MODE_COPY_FROM_METADATA - 输出图像将使用传入作者的元数据对象中发现的任何进度参数。
        • MODE_DEFAULT - 图像将逐步写入，并由作者选择参数。

        默认值为MODE_COPY_FROM_METADATA 。

        参数
        mode - 在输出流中设置进度的模式。
        异常
        UnsupportedOperationException - 如果作者不支持逐行编码。
        IllegalArgumentException - 如果 mode不是上面列出的一种模式。
        另请参见：
        getProgressiveMode()

      • getProgressiveMode

        public int getProgressiveMode​()
        返回以逐行方式写入流的当前模式。
        结果
        逐行编码的当前模式。
        异常
        UnsupportedOperationException - 如果作者不支持逐行编码。
        另请参见：
        setProgressiveMode(int)

      • canWriteCompressed

        public boolean canWriteCompressed​()
        如果此作者支持压缩，则返回 true 。
        结果
        true如果作者支持压缩。

      • setCompressionMode

        public void setCompressionMode​(int mode)
        指定是否执行压缩，如果需要确定压缩参数。 mode参数必须是四种模式之一，解释如下：
        • MODE_DISABLED - 如果模式设置为MODE_DISABLED ，查询或修改压缩类型或参数的方法将抛出IllegalStateException （如果插件通常支持压缩）。 一些作者，例如JPEG，通常不提供未压缩的输出。 在这种情况下，尝试将模式设置为MODE_DISABLED将会抛出一个UnsupportedOperationException并且不会改变模式。
        • MODE_EXPLICIT - 使用此ImageWriteParam指定的压缩类型和质量设置进行压缩。 任何先前设置的压缩参数都被丢弃。
        • MODE_COPY_FROM_METADATA - 使用传入到作者的元数据对象中指定的任何压缩参数。
        • MODE_DEFAULT - 使用默认压缩参数。

        默认值为MODE_COPY_FROM_METADATA 。

        参数
        mode - 在输出流中设置压缩的模式。
        异常
        UnsupportedOperationException - 如果写入程序不支持压缩，或者不支持请求的模式。
        IllegalArgumentException - 如果 mode不是上面列出的一种模式。
        另请参见：
        getCompressionMode()

      • getCompressionTypes

        public String[] getCompressionTypes​()
        返回可用压缩类型的列表，如数组或String s或null如果可能无法使用这些接口选择压缩类型。 返回的数组是一个副本。

        如果作者仅提供单一的强制性压缩形式，则不需要提供任何命名的压缩类型。 命名的压缩类型只能在用户能够在不同方案之间进行有意义的选择的地方使用。

        默认实现检查是否支持压缩，如果不支持， UnsupportedOperationException抛出UnsupportedOperationException 。 否则，如果它是非null ，则返回一个compressionTypes实例变量的克隆，否则返回null 。

        结果
        String的数组包含（非本地化）可用压缩类型的名称，或 null 。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。

      • setCompressionType

        public void setCompressionType​(String compressionType)
        将压缩类型设置为getCompressionTypes指示的值getCompressionTypes 。 如果传入值为null ，则删除任何先前的设置。

        默认实现检查压缩是否受支持，压缩模式是否为MODE_EXPLICIT 。 如果是这样，它调用getCompressionTypes并检查是否compressionType是合法值之一。 如果是，则设置compressionType实例变量。 如果compressionType为null ，则不执行任何检查，将设置实例变量。

        参数
        compressionType -一个的 String通过返回小号 getCompressionTypes ，或 null ，以消除任何先前的设置。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        UnsupportedOperationException - 如果没有可设置的压缩类型。
        IllegalArgumentException - 如果 compressionType是非 null但不是由 getCompressionTypes返回的值 getCompressionTypes 。
        另请参见：
        getCompressionTypes() ， getCompressionType() ， unsetCompression()

      • getCompressionType

        public String getCompressionType​()
        返回当前设置的压缩类型，如果没有设置，则返回null 。 从String返回的类型中返回getCompressionTypes 。 如果没有设置压缩类型，则返回null 。

        默认实现检查压缩是否受支持，压缩模式是否为MODE_EXPLICIT 。 如果是，则返回compressionType实例变量的值。

        结果
        当前压缩类型为 String ，如果没有设置类型， null 。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        另请参见：
        setCompressionType(java.lang.String)

      • getLocalizedCompressionTypeName

        public String getLocalizedCompressionTypeName​()
        返回当前压缩类型名称的本地化版本，使用Locale通过返回getLocale 。

        默认实现检查压缩是否受支持，压缩模式是否为MODE_EXPLICIT 。 如果是，如果compressionType是non-null ，那么返回的值是getCompressionType 。

        结果
        一个 String包含当前压缩类型的名称的本地化版本。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果没有设置压缩类型。

      • isCompressionLossless

        public boolean isCompressionLossless​()
        如果当前压缩类型提供无损压缩，则返回true 。 如果插件仅提供一种强制性的压缩类型，则可以先调用此方法，而不setCompressionType调用setCompressionType 。

        如果有多种压缩类型，但没有设置，则抛出IllegalStateException 。

        默认实现检查是否支持压缩，压缩模式是MODE_EXPLICIT 。 如果是，如果getCompressionTypes()是null或getCompressionType()是非null true作为方便返回。

        结果
        true如果当前的压缩类型是无损的。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果一组合法的压缩类型是非 null ，当前的压缩类型是 null 。

      • setCompressionQuality

        public void setCompressionQuality​(float quality)
        将压缩质量设置为0和1之间的值。 默认情况下，仅支持单个压缩质量设置; 作者可以提供ImageWriteParam扩展版本，提供更多的控制。 对于有损压缩方案，压缩质量应该控制文件大小和图像质量之间的折衷（例如，通过在编写JPEG图像时选择量化表）。 对于无损方案，可以使用压缩质量来控制文件大小和执行压缩所花费的时间之间的折衷（例如，通过优化行过滤器并在编写PNG图像时设置ZLIB压缩级别）。

        0.0的压缩质量设置最通俗地解释为“高压缩是重要的”，而1.0的设置最通常被解释为“高图像质量很重要”。

        如果有多种压缩类型，但没有设置，则抛出IllegalStateException 。

        默认实现检查是否支持压缩，压缩模式为MODE_EXPLICIT 。 如果是，如果getCompressionTypes()返回null或compressionType是非null它设置的compressionQuality实例变量。

        参数
        quality -一个 float之间 0和 1指示期望的质量水平。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果一组法定压缩类型为非 null ，当前压缩类型为 null 。
        IllegalArgumentException - 如果 quality不在 0和 1之间，包括在内。
        另请参见：
        getCompressionQuality()

      • getCompressionQuality

        public float getCompressionQuality​()
        返回当前的压缩质量设置。

        如果有多种压缩类型，但没有设置，则抛出IllegalStateException 。

        默认实现检查压缩是否受支持，而压缩模式是MODE_EXPLICIT 。 如果是，如果getCompressionTypes()为null或getCompressionType()为非null ，则返回compressionQuality实例变量的值。

        结果
        当前的压缩质量设置。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果一组法定压缩类型为非 null ，当前压缩类型为 null 。
        另请参见：
        setCompressionQuality(float)

      • getBitRate

        public float getBitRate​(float quality)
        返回float指示在给定质量水平下每个输入图像数据位的输出数据的位数的估计。 该值通常在0和1之间，较小的值表示更多的压缩。 使用特殊值-1.0F表示没有可用的估计。

        如果有多种压缩类型，但没有设置，则抛出IllegalStateException 。

        默认实现检查压缩是否受支持，压缩模式是MODE_EXPLICIT 。 如果是，如果getCompressionTypes()是null或getCompressionType()是非null ，而quality是在界限内，则返回-1.0 。

        参数
        quality - 要查询比特率的质量设置。
        结果
        压缩比特率的估计，如果没有估计可用， -1.0F 。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果一组法定压缩类型是非 null ，当前的压缩类型是 null 。
        IllegalArgumentException - 如果 quality不在 0和 1之间，包括在内。

      • getCompressionQualityDescriptions

        public String[] getCompressionQualityDescriptions​()
        返回String s的数组，可以与getCompressionQualityValues一起使用，作为设置或显示压缩质量级别的用户界面的一部分。 所述String具有索引i提供质量水平之间的范围内的描述getCompressionQualityValues[i]和getCompressionQualityValues[i + 1] 。 需要注意的是阵列的长度从返回getCompressionQualityValues将始终是一个大于从返回getCompressionQualityDescriptions 。

        作为一个例子，字符串“好”，“较好”和“最佳”可与范围相关[0, .33) ， [.33, .66) ，并[.66, 1.0] 。 在这种情况下， getCompressionQualityDescriptions将返回{ "Good", "Better", "Best" }而getCompressionQualityValues将返回{ 0.0F, .33F, .66F, 1.0F } 。

        如果没有可用的描述，则返回null 。 如果null从返回getCompressionQualityValues ，这种方法也必须返回null 。

        这个说明应该是本地化的，由Locale返回的getLocale ，如果是非null 。

        如果有多种压缩类型，但没有设置， IllegalStateException抛出IllegalStateException 。

        默认实现检查压缩是否受支持，压缩模式是MODE_EXPLICIT 。 如果是，如果getCompressionTypes()是null或getCompressionType()是非null ，它返回null 。

        结果
        String的数组包含压缩质量等级的本地化描述。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果一组法定压缩类型是非 null ，当前的压缩类型是 null 。
        另请参见：
        getCompressionQualityValues()

      • getCompressionQualityValues

        public float[] getCompressionQualityValues​()
        返回float的数组，可以与getCompressionQualityDescriptions一起使用，作为设置或显示压缩质量等级的用户界面的一部分。 有关详细信息，请参阅getCompressionQualityDescriptions 。

        如果没有可用的描述，则返回null 。 如果null从返回getCompressionQualityDescriptions ，这种方法也必须返回null 。

        如果有多种压缩类型，但没有设置，则抛出IllegalStateException 。

        默认实现检查压缩是否受支持，而压缩模式是MODE_EXPLICIT 。 如果是，如果getCompressionTypes()是null或getCompressionType()是非null ，它返回null 。

        结果
        float s的阵列，表示 String的 getCompressionQualityDescriptions描述的压缩质量水平之间的边界。
        异常
        UnsupportedOperationException - 如果作者不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果一组法定压缩类型是非 null ，当前的压缩类型是 null 。
        另请参见：
        getCompressionQualityDescriptions()