模块  java.desktop
软件包  javax.imageio

Class ImageWriteParam

  • 已知直接子类：
    BMPImageWriteParam ， JPEGImageWriteParam 
    public class ImageWriteParamextends IIOParam
    描述如何编码流的类。 此类或其子类的实例用于向ImageWriter实例提供规定的“操作方法”信息。

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

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

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

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

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

    另请参见：
    ImageReadParam

    • 字段详细信息

      • canWriteTiles

        protected boolean canWriteTiles
        如果此ImageWriteParam允许设置切片宽度和切片高度参数， boolean ，即true 。 默认情况下，该值为false 。 子类必须手动设置值。

        不支持编写切片的子类应确保将此值设置为false 。

      • preferredTileSizes

        protected Dimension[] preferredTileSizes
        一组优选的图块尺寸范围对。 默认值为null ，表示没有首选大小。 如果值为非null ，则其长度必须至少为2。

        不支持编写切片的子类可能会忽略此值。

        另请参见：
        getPreferredTileSizes()

      • tilingSet

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

        不支持编写切片的子类可能会忽略此值。

      • tileWidth

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

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

      • tileHeight

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

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

      • canOffsetTiles

        protected boolean canOffsetTiles
        如果此ImageWriteParam允许设置平铺网格偏移参数， boolean ，即true 。 默认情况下，该值为false 。 子类必须手动设置值。

        不支持编写切片或支持写入但不支持偏移切片的子类必须确保此值设置为false 。

      • tileGridXOffset

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

        不支持偏移切片的子类可能会忽略此值。

      • tileGridYOffset

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

        不支持偏移切片的子类可能会忽略此值。

      • canWriteProgressive

        protected boolean canWriteProgressive
        如果此ImageWriteParam允许将图像写为递增质量传递的渐进序列， boolean ，即true 。 默认情况下，该值为false 。 子类必须手动设置值。

        不支持渐进式编码的子类必须确保将此值设置为false 。

      • canWriteCompressed

        protected boolean canWriteCompressed
        如果此编写者可以使用压缩编写图像，则为boolean ，即true 。 默认情况下，该值为false 。 子类必须手动设置值。

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

      • compressionTypes

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

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

      • compressionType

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

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

      • compressionQuality

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

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

      • locale

        protected Locale locale
        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 。 如果此方法返回false ，则setTiling将抛出UnsupportedOperationException 。
        结果
        true如果作者支持平铺。
        另请参见：
        canOffsetTiles() ， setTiling(int, int, int, int)

      • canOffsetTiles

        public boolean canOffsetTiles()
        如果编写者在写入时可以使用非零网格偏移执行平铺，则返回true 。 如果此方法返回false ，则如果网格偏移参数不为零，则setTiling将抛出UnsupportedOperationException 。 如果canWriteTiles返回false ，则此方法也将返回false 。
        结果
        true如果 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的数组，指示tile的合法大小范围，因为它们将在输出文件或流中进行编码。 返回的数组是副本。

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

        如果在构造函数上未指定数组，但允许平铺，则此方法返回null 。

        结果
        Dimension的数组，偶数长度至少为2，或 null 。
        异常
        UnsupportedOperationException - 如果插件不支持平铺。

      • canWriteProgressive

        public boolean canWriteProgressive()
        如果作者可以将图像写为一系列逐渐增加质量的过程，则返回 true 。
        结果
        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_COPY_FROM_METADATA的元数据对象中找到的任何进度参数。
        • MODE_DEFAULT - 图像将逐步写入，参数选择参数。

        默认值为MODE_COPY_FROM_METADATA 。

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

      • canWriteCompressed

        public boolean canWriteCompressed()
        如果此writer支持压缩，则返回 true 。
        结果
        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 - 使用传递给writer的元数据对象中指定的任何压缩参数。
        • MODE_DEFAULT - 使用默认压缩参数。

        默认值为MODE_COPY_FROM_METADATA 。

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

      • getCompressionTypes

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

        如果编写器仅提供单个强制形式的压缩，则不必提供任何命名的压缩类型。 仅当用户能够在不同方案之间做出有意义的选择时，才应使用命名压缩类型。

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

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

      • setCompressionType

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

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

        参数
        compressionType -在一个 String通过返回小号 getCompressionTypes ，或 null删除所有以前的设置。
        异常
        UnsupportedOperationException - 如果 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 - 如果 UnsupportedOperationException器不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        另请参见：
        setCompressionType(java.lang.String)

      • getLocalizedCompressionTypeName

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

        默认实现检查是否支持压缩，压缩模式为MODE_EXPLICIT 。 如果是这样， compressionType为non-null的价值getCompressionType返回的方便。

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

      • isCompressionLossless

        public boolean isCompressionLossless()
        如果当前压缩类型提供无损压缩，则返回true 。 如果插件仅提供一种强制压缩类型，则可以在不首先调用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 - 如果 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 - 如果 UnsupportedOperationException器不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果合法压缩类型集为非 null且当前压缩类型为 null 。
        IllegalArgumentException - 如果 quality不在 0和 1之间，包括在内。

      • getCompressionQualityDescriptions

        public String[] getCompressionQualityDescriptions()
        返回String的数组，该数组可与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 。

        如果非null ，则应将Locale返回的getLocale进行本地化描述。

        如果存在多个压缩类型但未设置任何压缩类型，则抛出IllegalStateException 。

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

        结果
        String的数组，包含压缩质量级别的本地化描述。
        异常
        UnsupportedOperationException - 如果 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的阵列， float指示压缩质量水平之间的边界，如 String的 getCompressionQualityDescriptions 。
        异常
        UnsupportedOperationException - 如果 UnsupportedOperationException器不支持压缩。
        IllegalStateException - 如果压缩模式不是 MODE_EXPLICIT 。
        IllegalStateException - 如果合法压缩类型集为非 null且当前压缩类型为 null 。
        另请参见：
        getCompressionQualityDescriptions()