Module java.desktop
Package javax.imageio

Class ImageWriter

java.lang.Object
javax.imageio.ImageWriter
所有已实现的接口:
ImageTranscoder
public abstract class ImageWriter extends Object implements ImageTranscoder
用于编码和写入图像的抽象超类。必须由在Java Image I/O框架上下文中写出图像的类来继承此类。

ImageWriter对象通常由特定格式的服务提供者类实例化。服务提供者类已在IIORegistry中注册，IIORegistry用于格式识别和显示可用格式的读取器和写入器。

参见:

  • Field Details

    • originatingProvider

      protected ImageWriterSpi originatingProvider
      实例化此对象的ImageWriterSpi，如果其标识未知或不存在，则为null。默认情况下，它初始化为null。

    • output

      protected Object output
      由setOutput设置并由getOutput检索的ImageOutputStream或其他Object。默认情况下，它初始化为null。

    • availableLocales

      protected Locale[] availableLocales
      可用于本地化警告消息和压缩设置值的Locale数组，如果不支持本地化，则为null。默认情况下，它初始化为null。

    • locale

      protected Locale locale
      用于本地化的当前Locale，如果尚未设置，则为null。默认情况下，它被初始化为null。

    • warningListeners

      protected List<IIOWriteWarningListener> warningListeners
      当前注册的IIOWriteWarningListener的List，默认情况下初始化为null，与空List同义。

    • warningLocales

      protected List<Locale> warningLocales
      一个List，包含每个warningListeners元素的Locale，默认情况下初始化为null，与空List同义。

    • progressListeners

      protected List<IIOWriteProgressListener> progressListeners
      当前注册的IIOWriteProgressListener的List，默认情况下初始化为null，与空List同义。

  • Constructor Details

    • ImageWriter

      protected ImageWriter(ImageWriterSpi originatingProvider)
      构造一个ImageWriter并将其originatingProvider实例变量设置为提供的值。

      使用扩展的子类应该提供一个带有签名(ImageWriterSpi, Object)的构造函数，以便检索扩展对象。如果扩展对象不合适，则应抛出IllegalArgumentException。

      参数：
      originatingProvider - 构造此对象的ImageWriterSpi，或null。

  • Method Details

    • getOriginatingProvider

      public ImageWriterSpi getOriginatingProvider()
      返回创建此ImageWriter的ImageWriterSpi对象，如果此对象不是通过IIORegistry创建的，则返回null。

      默认实现返回originatingProvider实例变量的值。

      返回：
      一个ImageWriterSpi，或null。
      参见：

    • setOutput

      public void setOutput(Object output)
      将目的地设置为给定的ImageOutputStream或其他Object。假定目的地已准备好接受数据，并且不会在每次写入结束时关闭。这允许分布式成像应用程序通过单个网络连接传输一系列图像。如果output为null，则将删除任何当前设置的输出。

      如果output是ImageOutputStream，则对write、writeToSequence和prepareWriteEmpty/endWriteEmpty方法的调用将保留流的现有内容。其他写入方法，如writeInsert、replaceStreamMetadata、replaceImageMetadata、replacePixels、prepareInsertEmpty/endInsertEmpty和endWriteSequence，需要流的全部内容可读可写，并且可能更改流的任何部分。

      除了ImageOutputStream之外的一般Object的使用适用于直接与输出设备或成像协议交互的写入器。合法类的集合由写入器的服务提供程序的getOutputTypes方法进行广告；大多数写入器将返回一个只包含ImageOutputStream.class的单元素数组，以指示它们仅接受ImageOutputStream。

      默认实现在检查output与原始提供程序广告的类集合之间的匹配后，将output实例变量设置为output的值。

      参数：
      output - 用于将来写入的ImageOutputStream或其他Object。
      抛出：
      IllegalArgumentException - 如果output不是由原始服务提供程序的getOutputTypes方法返回的类之一的实例。
      参见：

    • getOutput

      public Object getOutput()
      返回最近一次调用setOutput方法设置的ImageOutputStream或其他Object。如果尚未设置目的地，则返回null。

      默认实现返回output实例变量的值。

      返回：
      通过setOutput指定的Object，或null。
      参见：

    • getAvailableLocales

      public Locale[] getAvailableLocales()
      返回一个Locale数组，可用于本地化警告侦听器和压缩设置。返回null表示不支持本地化。

      如果availableLocales实例变量为非null，则默认实现返回availableLocales实例变量的克隆，否则返回null。

      返回：
      一个Locale数组，可用作setLocale的参数，或null。

    • setLocale

      public void setLocale(Locale locale)
      将此ImageWriter的当前Locale设置为给定值。值为null会删除任何先前的设置，并指示写入器应根据自己的判断进行本地化。

      默认实现检查locale与getAvailableLocales返回的值是否匹配，并在找到时设置locale实例变量。如果locale为null，则实例变量将被设置为null而不进行任何检查。

      参数：
      locale - 所需的Locale，或null。
      抛出：
      IllegalArgumentException - 如果locale为非null但不是getAvailableLocales返回的值之一。
      参见：

    • getLocale

      public Locale getLocale()
      返回当前设置的Locale，如果尚未设置，则返回null。

      默认实现返回locale实例变量的值。

      返回：
      当前Locale，或null。
      参见：

    • getDefaultWriteParam

      public ImageWriteParam getDefaultWriteParam()
      返回适用于此文件格式的ImageWriteParam对象的新实例，包含默认值，即如果未指定ImageWriteParam对象，则将使用的值。这对于调整仅有少量参数并保持默认设置不变非常有用。

      默认实现构造并返回一个新的ImageWriteParam对象，不允许平铺、渐进编码或压缩，并且将为当前Locale本地化（即，通过调用new ImageWriteParam(getLocale())获得的值）。

      各个插件可以返回启用了其他可选功能的ImageWriteParam实例，或者它们可以返回ImageWriteParam的插件特定子类的实例。

      返回：
      包含默认值的新ImageWriteParam对象。

    • getDefaultStreamMetadata

      public abstract IIOMetadata getDefaultStreamMetadata(ImageWriteParam param)
      返回包含编码图像流的默认值的IIOMetadata对象。可以使用由IIOMetadata.getAsTree方法返回的XML树结构、IIOMetadataController对象或通过插件特定接口操纵对象的内容，并将生成的数据提供给接受流元数据参数的write方法之一。

      在可能影响流元数据结构的情况下，可以提供可选的ImageWriteParam。

      如果提供的ImageWriteParam包含此写入器不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      不使用流元数据的写入器（例如，单图像格式的写入器）应返回null。

      参数：
      param - 将用于编码图像的ImageWriteParam，或null。
      返回：
      一个IIOMetadata对象。

    • getDefaultImageMetadata

      public abstract IIOMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param)
      返回包含编码给定类型图像的默认值的IIOMetadata对象。可以使用由IIOMetadata.getAsTree方法返回的XML树结构、IIOMetadataController对象或通过插件特定接口操纵对象的内容，并将生成的数据提供给接受图像元数据参数的write方法之一。

      在可能影响图像元数据结构的情况下，可以提供可选的ImageWriteParam。

      如果提供的ImageWriteParam包含此写入器不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      参数：
      imageType - 指示稍后要写入的图像格式的ImageTypeSpecifier。
      param - 将用于编码图像的ImageWriteParam，或null。
      返回：
      一个IIOMetadata对象。

    • getNumThumbnailsSupported

      public int getNumThumbnailsSupported(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata)
      返回正在写入的格式支持的缩略图数量，给定图像类型以及在编码期间将使用的任何其他写入参数和元数据对象。返回值为-1表示没有足够的信息可用。

      可以选择提供ImageWriteParam，以便在可能影响缩略图处理的情况下使用。

      如果提供的ImageWriteParam包含此写入器不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      默认实现返回0。

      参数:
      imageType - 一个指示要写入的图像类型的ImageTypeSpecifier，或null。
      param - 将用于写入的ImageWriteParam，或null。
      streamMetadata - 将用于写入的IIOMetadata对象，或null。
      imageMetadata - 将用于写入的IIOMetadata对象，或null。
      返回:
      根据提供的参数返回可能写入的缩略图数量，如果信息不足则返回-1。

    • getPreferredThumbnailSizes

      public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata)
      返回一个Dimension数组，指示缩略图图像在输出文件或流中编码时的合法大小范围。此信息仅供参考；写入器将根据需要调整任何提供的缩略图大小。

      信息以一组对的形式返回；一对的第一个元素包含一个（包含的）最小宽度和高度，第二个元素包含一个（包含的）最大宽度和高度。每对一起定义一个有效的大小范围。要指定固定大小，两个元素的宽度和高度将相同。返回值为null表示大小是任意的或未知的。

      可以选择提供一个ImageWriteParam，以处理缩略图处理的情况。

      如果提供的ImageWriteParam包含此写入器不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      默认实现返回null。

      参数:
      imageType - 一个指示要写入的图像类型的ImageTypeSpecifier，或null。
      param - 将用于写入的ImageWriteParam，或null。
      streamMetadata - 将用于写入的IIOMetadata对象，或null。
      imageMetadata - 将用于写入的IIOMetadata对象，或null。
      返回:
      至少有两个偶数长度的Dimension数组，或null。

    • canWriteRasters

      public boolean canWriteRasters()
      如果接受一个Raster（而不是RenderedImage）源图像的方法能够处理IIOImage参数，则返回true。如果此方法返回false，那么如果提供了包含Raster的IIOImage，这些方法将抛出UnsupportedOperationException。

      默认实现返回false。

      返回:
      如果支持Raster源，则返回true。

    • write

      public abstract void write(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param) throws IOException
      将包含单个图像、相关流和图像元数据以及缩略图的完整图像流附加到输出。将包含任何必要的头信息。如果输出是ImageOutputStream，则在当前寻位位置之前的现有内容不受影响，不需要可读或可写。

      必须事先使用setOutput方法设置输出。

      可以选择提供流元数据；如果为null，将使用默认流元数据。

      如果canWriteRasters返回true，则IIOImage可能包含Raster源。否则，必须包含RenderedImage源。

      如果需要，提供的缩略图将被调整大小，超出支持数量的任何缩略图将被忽略。如果格式需要提供未提供的额外缩略图，则写入器应在内部生成它们。

      可以选择提供ImageWriteParam以控制写入过程。如果param为null，将使用默认写入参数。

      如果提供的ImageWriteParam包含此写入器不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      参数:
      streamMetadata - 表示流元数据的IIOMetadata对象，或null以使用默认值。
      image - 包含要写入的图像、缩略图和元数据的IIOImage对象。
      param - 一个ImageWriteParam，或null以使用默认的ImageWriteParam。
      抛出:
      IllegalStateException - 如果未设置输出。
      UnsupportedOperationException - 如果image包含Raster且canWriteRasters返回false。
      IllegalArgumentException - 如果image为null。
      IOException - 如果在写入过程中发生错误。

    • write

      public void write(IIOImage image) throws IOException
      将包含默认元数据和缩略图的单个图像流附加到输出。此方法是write(null, image, null)的简写。
      参数:
      image - 包含要写入的图像、缩略图和元数据的IIOImage对象。
      抛出:
      IllegalStateException - 如果未设置输出。
      IllegalArgumentException - 如果image为null。
      UnsupportedOperationException - 如果image包含Raster且canWriteRasters返回false。
      IOException - 如果在写入过程中发生错误。

    • write

      public void write(RenderedImage image) throws IOException
      将包含默认元数据和缩略图的单个图像流附加到输出。此方法是write(null, new IIOImage(image, null, null), null)的简写。
      参数:
      image - 要写入的RenderedImage。
      抛出:
      IllegalStateException - 如果未设置输出。
      IllegalArgumentException - 如果image为null。
      IOException - 如果在写入过程中发生错误。

    • canWriteSequence

      public boolean canWriteSequence()
      如果写入器能够将图像附加到已包含头信息和可能先前图像的图像流中，则返回true。

      如果canWriteSequence返回false，writeToSequence和endWriteSequence将抛出UnsupportedOperationException。

      默认实现返回false。

      返回:
      如果可以按顺序附加图像，则返回true。

    • prepareWriteSequence

      public void prepareWriteSequence(IIOMetadata streamMetadata) throws IOException
      使用提供的流元数据对象准备流以接受一系列后续的writeToSequence调用。如果应在图像数据之前写入元数据，则将元数据写入流。如果参数为null，则使用默认流元数据。

      如果输出是ImageOutputStream，则在此方法之前刷新输出在当前寻位位置之前的现有内容，不需要可读或可写。如果格式要求endWriteSequence能够倒带以修补头信息，例如单个TIFF文件中的一系列图像，则此方法写入的元数据必须保留在流的可写部分。其他格式可能会在此方法之后和每个图像之后刷新流。

      如果canWriteSequence返回false，此方法将抛出UnsupportedOperationException。

      必须事先使用setOutput方法设置输出。

      默认实现如果输出为null则抛出IllegalStateException，否则抛出UnsupportedOperationException。

      参数:
      streamMetadata - 一个流元数据对象，或null。
      抛出:
      IllegalStateException - 如果未设置输出。
      UnsupportedOperationException - 如果canWriteSequence返回false。
      IOException - 如果写入流元数据时发生错误。

    • writeToSequence

      public void writeToSequence(IIOImage image, ImageWriteParam param) throws IOException
      追加单个图像及可能相关的元数据和缩略图到输出。如果输出是一个ImageOutputStream，则当前寻位位置之前的输出内容可能会被刷新，不需要可读或可写，除非插件需要在调用endWriteSequence时修补头信息（例如TIFF）。

      如果canWriteSequence返回false，此方法将抛出UnsupportedOperationException异常。

      必须事先使用setOutput方法设置输出。

      必须事先调用prepareWriteSequence，否则将抛出IllegalStateException异常。

      如果canWriteRasters返回true，则IIOImage可能包含Raster源。否则，必须包含RenderedImage源。

      提供的缩略图将根据需要调整大小，超出支持数量的任何缩略图将被忽略。如果格式需要提供未提供的额外缩略图，则编写器将在内部生成它们。

      可以选择提供一个ImageWriteParam来控制写入过程。如果param为null，将使用默认的写入参数。

      如果提供的ImageWriteParam包含此编写器不支持的可选设置值（例如渐进编码或任何特定格式的设置），它们将被忽略。

      如果输出为null，默认实现将抛出IllegalStateException，否则将抛出UnsupportedOperationException。

      参数:
      image - 包含要写入的图像、缩略图和元数据的IIOImage对象。
      param - 一个ImageWriteParam，或null以使用默认的ImageWriteParam。
      抛出:
      IllegalStateException - 如果未设置输出，或未调用prepareWriteSequence。
      UnsupportedOperationException - 如果canWriteSequence返回false。
      IllegalArgumentException - 如果image为null。
      UnsupportedOperationException - 如果image包含Raster且canWriteRasters返回false。
      IOException - 如果写入过程中发生错误。

    • endWriteSequence

      public void endWriteSequence() throws IOException
      完成使用prepareWriteSequence开始的图像序列的写入。将写出应该出现在图像序列末尾的任何流元数据，并在必要时修补序列开头的任何头信息。如果输出是一个ImageOutputStream，则通过流元数据结束时的数据将被刷新，不需要可读或可写。

      如果canWriteSequence返回false，此方法将抛出UnsupportedOperationException异常。

      如果输出为null，默认实现将抛出IllegalStateException，否则将抛出UnsupportedOperationException。

      抛出:
      IllegalStateException - 如果未设置输出，或未调用prepareWriteSequence。
      UnsupportedOperationException - 如果canWriteSequence返回false。
      IOException - 如果写入过程中发生错误。

    • canReplaceStreamMetadata

      public boolean canReplaceStreamMetadata() throws IOException
      如果可能替换输出中已存在的流元数据，则返回true。

      如果输出为null，默认实现将抛出IllegalStateException，否则返回false。

      返回:
      true表示允许替换流元数据。
      抛出:
      IllegalStateException - 如果未设置输出。
      IOException - 如果在查询过程中发生I/O错误。

    • replaceStreamMetadata

      public void replaceStreamMetadata(IIOMetadata streamMetadata) throws IOException
      用新信息替换输出中的流元数据。如果输出是一个ImageOutputStream，则将检查并可能编辑流的先前内容以为新数据腾出空间。输出的所有先前内容必须可供读取和写入。

      如果canReplaceStreamMetadata返回false，将抛出UnsupportedOperationException异常。

      如果输出为null，默认实现将抛出IllegalStateException，否则将抛出UnsupportedOperationException。

      参数:
      streamMetadata - 表示流元数据的IIOMetadata对象，或null以使用默认值。
      抛出:
      IllegalStateException - 如果未设置输出。
      UnsupportedOperationException - 如果canReplaceStreamMetadata返回false。
      IOException - 如果写入过程中发生错误。

    • canReplaceImageMetadata

      public boolean canReplaceImageMetadata(int imageIndex) throws IOException
      如果可以替换与索引imageIndex对应的现有图像的图像元数据，则返回true。如果此方法返回false，则调用replaceImageMetadata(imageIndex)将抛出UnsupportedOperationException异常。

      不支持任何图像元数据替换的编写器可能会返回false，而不对索引进行边界检查。

      如果输出为null，默认实现将抛出IllegalStateException，否则将根据imageIndex的值返回false。

      参数:
      imageIndex - 要替换其元数据的图像的索引。
      返回:
      true表示可以替换给定图像的图像元数据。
      抛出:
      IllegalStateException - 如果未设置输出。
      IndexOutOfBoundsException - 如果编写器通常支持图像元数据替换，但imageIndex小于0或大于最大可用索引。
      IOException - 如果在查询过程中发生I/O错误。

    • replaceImageMetadata

      public void replaceImageMetadata(int imageIndex, IIOMetadata imageMetadata) throws IOException
      替换与现有图像关联的图像元数据。

      如果canReplaceImageMetadata(imageIndex)返回false，将抛出UnsupportedOperationException异常。

      如果输出为null，默认实现将抛出IllegalStateException，否则将抛出UnsupportedOperationException。

      参数:
      imageIndex - 要替换其元数据的图像的索引。
      imageMetadata - 表示图像元数据的IIOMetadata对象，或null。
      抛出:
      IllegalStateException - 如果未设置输出。
      UnsupportedOperationException - 如果canReplaceImageMetadata返回false。
      IndexOutOfBoundsException - 如果imageIndex小于0或大于最大可用索引。
      IOException - 如果写入过程中发生错误。

    • canInsertImage

      public boolean canInsertImage(int imageIndex) throws IOException
      如果编写器支持在给定索引处插入新图像，则返回true。索引大于或等于插入索引的现有图像的索引将增加1。可以使用-1的值作为比当前最大索引大1的索引。

      不支持任何图像插入的编写器可能会返回false，而不对索引进行边界检查。

      如果输出为null，默认实现将抛出IllegalStateException，否则将根据imageIndex的值返回false。

      参数:
      imageIndex - 要插入图像的索引。
      返回:
      true表示可以在给定索引处插入图像。
      抛出:
      IllegalStateException - 如果未设置输出。
      IndexOutOfBoundsException - 如果编写器通常支持图像插入，但imageIndex小于-1或大于最大可用索引。
      IOException - 如果在查询过程中发生I/O错误。

    • writeInsert

      public void writeInsert(int imageIndex, IIOImage image, ImageWriteParam param) throws IOException
      插入新图像到现有图像流中。保留索引大于imageIndex的现有图像，并且它们的索引都增加1。可以使用imageIndex为-1来表示比先前最大索引大1的索引；也就是说，它将导致图像逻辑上附加到序列的末尾。如果输出是一个ImageOutputStream，则整个流必须可读且可写。

      如果canInsertImage(imageIndex)返回false，将抛出UnsupportedOperationException异常。

      可以选择提供一个ImageWriteParam来控制写入过程。如果param为null，将使用默认的写入参数。

      如果提供的ImageWriteParam包含此写入器不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      如果输出为null，默认实现会抛出IllegalStateException，否则会抛出UnsupportedOperationException。

      参数:
      imageIndex - 要写入图像的索引。
      image - 包含要写入的图像、缩略图和元数据的IIOImage对象。
      param - 一个ImageWriteParam，或者null以使用默认的ImageWriteParam。
      抛出:
      IllegalStateException - 如果未设置输出。
      UnsupportedOperationException - 如果canInsertImage(imageIndex)返回false。
      IllegalArgumentException - 如果image为null。
      IndexOutOfBoundsException - 如果imageIndex小于-1或大于最大可用索引。
      UnsupportedOperationException - 如果image包含一个Raster且canWriteRasters返回false。
      IOException - 如果写入过程中发生错误。

    • canRemoveImage

      public boolean canRemoveImage(int imageIndex) throws IOException
      如果写入器支持删除给定索引处现有图像，则返回true。具有大于插入索引的索引的现有图像的索引将减少1。

      不支持任何图像删除的写入器可能会在不对索引进行边界检查的情况下返回false。

      默认实现会抛出IllegalStateException（如果输出为null），否则会返回false而不检查imageIndex的值。

      参数:
      imageIndex - 要删除的图像的索引。
      返回:
      true如果可以删除给定的图像。
      抛出:
      IllegalStateException - 如果未设置输出。
      IndexOutOfBoundsException - 如果写入器通常支持图像删除，但imageIndex小于0或大于最大可用索引。
      IOException - 如果在查询过程中发生I/O错误。

    • removeImage

      public void removeImage(int imageIndex) throws IOException
      从流中移除图像。

      如果canRemoveImage(imageIndex)返回false，将抛出UnsupportedOperationException异常。

      移除可能会或可能不会导致实际文件大小的减小。

      默认实现会抛出IllegalStateException（如果输出为null），否则会抛出UnsupportedOperationException。

      参数:
      imageIndex - 要移除的图像的索引。
      抛出:
      IllegalStateException - 如果未设置输出。
      UnsupportedOperationException - 如果canRemoveImage(imageIndex)返回false。
      IndexOutOfBoundsException - 如果imageIndex小于0或大于最大可用索引。
      IOException - 如果在移除过程中发生I/O错误。

    • canWriteEmpty

      public boolean canWriteEmpty() throws IOException
      如果写入器支持将由未定义像素值和相关元数据和缩略图组成的单个图像的完整图像流写入输出，则返回true。像素值可以通过将来调用replacePixels方法来定义。如果输出是一个ImageOutputStream，则在当前寻址位置之前的现有内容不受影响，也不需要可读或可写。

      默认实现会抛出IllegalStateException（如果输出为null），否则会返回false。

      返回:
      true如果支持具有稍后定义内容的完整图像流的写入。
      抛出:
      IllegalStateException - 如果未设置输出。
      IOException - 如果在查询过程中发生I/O错误。

    • prepareWriteEmpty

      public void prepareWriteEmpty(IIOMetadata streamMetadata, ImageTypeSpecifier imageType, int width, int height, IIOMetadata imageMetadata, List<? extends BufferedImage> thumbnails, ImageWriteParam param) throws IOException
      开始写入完整图像流，包括一个具有未定义像素值和相关元数据和缩略图的单个图像到输出。像素值将由将来调用replacePixels方法来定义。如果输出是一个ImageOutputStream，则在当前寻址位置之前的现有内容不受影响，也不需要可读或可写。

      写入过程直到调用endWriteEmpty为止。在调用prepareWriteEmpty和endWriteEmpty之间可以发生对prepareReplacePixels、replacePixels和endReplacePixels的调用。但是，不能嵌套调用prepareWriteEmpty，并且prepareWriteEmpty和prepareInsertEmpty的调用不能交错进行。

      如果canWriteEmpty返回false，将抛出UnsupportedOperationException异常。

      可以选择提供一个ImageWriteParam来控制写入过程。如果param为null，将使用默认的写入参数。

      如果提供的ImageWriteParam包含此写入器不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      默认实现会抛出IllegalStateException（如果输出为null），否则会抛出UnsupportedOperationException。

      参数:
      streamMetadata - 表示流元数据的IIOMetadata对象，或者null以使用默认值。
      imageType - 描述图像布局的ImageTypeSpecifier。
      width - 图像的宽度。
      height - 图像的高度。
      imageMetadata - 表示图像元数据的IIOMetadata对象，或者null。
      thumbnails - 用于此图像的BufferedImage缩略图的List，或者null。
      param - 一个ImageWriteParam，或者null以使用默认的ImageWriteParam。
      抛出:
      IllegalStateException - 如果未设置输出。
      UnsupportedOperationException - 如果canWriteEmpty返回false。
      IllegalStateException - 如果之前调用了prepareWriteEmpty而没有相应调用endWriteEmpty。
      IllegalStateException - 如果之前调用了prepareInsertEmpty而没有相应调用endInsertEmpty。
      IllegalArgumentException - 如果imageType为null或thumbnails包含null引用或除BufferedImage之外的对象。
      IllegalArgumentException - 如果宽度或高度小于1。
      IOException - 如果在写入过程中发生I/O错误。

    • endWriteEmpty

      public void endWriteEmpty() throws IOException
      完成之前使用prepareWriteEmpty开始的新图像的写入。

      如果canWriteEmpty()返回false，将抛出UnsupportedOperationException异常。

      默认实现会抛出IllegalStateException（如果输出为null），否则会抛出UnsupportedOperationException。

      抛出:
      IllegalStateException - 如果输出未设置。
      UnsupportedOperationException - 如果canWriteEmpty(imageIndex)返回false。
      IllegalStateException - 如果之前调用prepareWriteEmpty而没有相应调用endWriteEmpty。
      IllegalStateException - 如果之前调用prepareInsertEmpty而没有相应调用endInsertEmpty。
      IllegalStateException - 如果调用prepareReiplacePixels而没有匹配的endReplacePixels。
      IOException - 写入过程中发生I/O错误。

    • canInsertEmpty

      public boolean canInsertEmpty(int imageIndex) throws IOException
      返回true如果写入器支持在给定索引处插入新的空图像。图像的像素值未定义，并且可以使用replacePixels方法逐步指定。索引大于或等于插入索引的现有图像的索引将增加1。可以使用imageIndex的值-1表示比当前最大索引大1的索引。

      不支持插入空图像的写入器可能会在不对索引进行边界检查的情况下返回false。

      如果输出为null，默认实现会抛出IllegalStateException，否则会返回false而不检查imageIndex的值。

      参数:
      imageIndex - 要插入图像的索引。
      返回:
      true如果可以在给定索引处插入空图像。
      抛出:
      IllegalStateException - 如果输出未设置。
      IndexOutOfBoundsException - 如果写入器通常支持插入空图像，但imageIndex小于-1或大于最大可用索引。
      IOException - 查询过程中发生I/O错误。

    • prepareInsertEmpty

      public void prepareInsertEmpty(int imageIndex, ImageTypeSpecifier imageType, int width, int height, IIOMetadata imageMetadata, List<? extends BufferedImage> thumbnails, ImageWriteParam param) throws IOException
      开始将具有未定义像素值的新图像插入到现有图像流中。索引大于imageIndex的现有图像将被保留，并且它们的索引将分别增加1。可以使用imageIndex的值-1表示比先前最大索引大1的索引；也就是说，它将导致图像逻辑上附加到序列的末尾。如果输出是ImageOutputStream，则整个流必须可读且可写。

      图像内容可以稍后使用replacePixels方法提供。插入操作直到调用endInsertEmpty才算完成。在调用prepareInsertEmpty和endInsertEmpty之间可以调用prepareReplacePixels、replacePixels和endReplacePixels。但是，不能嵌套调用prepareInsertEmpty，并且不能在prepareWriteEmpty和prepareInsertEmpty之间交替调用。

      如果canInsertEmpty(imageIndex)返回false，将抛出UnsupportedOperationException。

      可以选择提供一个ImageWriteParam来控制写入过程。如果param为null，将使用默认的写入参数。

      如果提供的ImageWriteParam包含此写入器不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      如果输出为null，默认实现会抛出IllegalStateException，否则会抛出UnsupportedOperationException。

      参数:
      imageIndex - 要写入图像的索引。
      imageType -描述图像布局的ImageTypeSpecifier。
      width - 图像的宽度。
      height - 图像的高度。
      imageMetadata - 表示图像元数据的IIOMetadata对象，或null。
      thumbnails - 包含此图像的BufferedImage缩略图的List，或null。
      param - 一个ImageWriteParam，或null以使用默认的ImageWriteParam。
      抛出:
      IllegalStateException - 如果输出未设置。
      UnsupportedOperationException - 如果canInsertEmpty(imageIndex)返回false。
      IndexOutOfBoundsException - 如果imageIndex小于-1或大于最大可用索引。
      IllegalStateException - 如果之前调用prepareInsertEmpty而没有相应调用endInsertEmpty。
      IllegalStateException - 如果之前调用prepareWriteEmpty而没有相应调用endWriteEmpty。
      IllegalArgumentException - 如果imageType为null或thumbnails包含null引用或不是BufferedImage的对象。
      IllegalArgumentException - 如果宽度或高度小于1。
      IOException - 写入过程中发生I/O错误。

    • endInsertEmpty

      public void endInsertEmpty() throws IOException
      完成先前调用prepareInsertEmpty开始的新图像的插入。

      如果输出为null，默认实现会抛出IllegalStateException，否则会抛出UnsupportedOperationException。

      抛出:
      IllegalStateException - 如果输出未设置。
      UnsupportedOperationException - 如果canInsertEmpty(imageIndex)返回false。
      IllegalStateException - 如果之前调用prepareInsertEmpty而没有相应调用endInsertEmpty。
      IllegalStateException - 如果之前调用prepareWriteEmpty而没有相应调用endWriteEmpty。
      IllegalStateException - 如果调用prepareReplacePixels而没有匹配的endReplacePixels。
      IOException - 写入过程中发生I/O错误。

    • canReplacePixels

      public boolean canReplacePixels(int imageIndex) throws IOException
      返回true如果写入器允许使用replacePixels方法替换给定图像的像素。

      不支持任何像素替换的写入器可能会在不对索引进行边界检查的情况下返回false。

      如果输出为null，默认实现会抛出IllegalStateException，否则会返回false而不检查imageIndex的值。

      参数:
      imageIndex - 要替换像素的图像的索引。
      返回:
      true如果可以替换给定图像的像素。
      抛出:
      IllegalStateException - 如果输出未设置。
      IndexOutOfBoundsException - 如果写入器通常支持像素替换，但imageIndex小于0或大于最大可用索引。
      IOException - 查询过程中发生I/O错误。

    • prepareReplacePixels

      public void prepareReplacePixels(int imageIndex, Rectangle region) throws IOException
      准备写入器处理一系列对replacePixels方法的调用。受影响的像素区域将针对提供的进行裁剪

      如果canReplacePixels返回false，将抛出UnsupportedOperationException。

      如果输出为null，默认实现会抛出IllegalStateException，否则会抛出UnsupportedOperationException。

      参数:
      imageIndex - 要替换其像素的图像的索引。
      region - 一个将用于裁剪未来像素区域的Rectangle。
      抛出:
      IllegalStateException - 如果输出尚未设置。
      UnsupportedOperationException - 如果canReplacePixels(imageIndex)返回false。
      IndexOutOfBoundsException - 如果imageIndex小于0或大于最大可用索引。
      IllegalStateException - 如果之前调用了prepareReplacePixels而没有匹配的endReplacePixels调用（即，不允许嵌套）。
      IllegalArgumentException - 如果region为null或宽度或高度小于1。
      IOException - 如果在准备过程中发生I/O错误。

    • replacePixels

      public void replacePixels(RenderedImage image, ImageWriteParam param) throws IOException
      用给定图像的一部分替换已存在于输出中的图像的一部分。图像数据必须匹配或可转换为现有图像的图像布局。

      目标区域在param参数中指定，并将被裁剪为图像边界和提供给prepareReplacePixels的区域。源的至少一个像素不能被裁剪，否则将抛出异常。

      可以选择提供ImageWriteParam以控制写入过程。如果param为null，将使用默认的写入参数。

      如果提供的ImageWriteParam包含此写入程序不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      此方法只能在调用prepareReplacePixels之后调用，否则将抛出IllegalStateException。

      默认实现会在输出为null时抛出IllegalStateException，否则抛出UnsupportedOperationException。

      参数:
      image - 包含源像素的RenderedImage。
      param - 一个ImageWriteParam，或null以使用默认的ImageWriteParam。
      抛出:
      IllegalStateException - 如果输出尚未设置。
      UnsupportedOperationException - 如果canReplacePixels(imageIndex)返回false。
      IllegalStateException - 如果没有之前调用prepareReplacePixels而没有匹配的endReplacePixels调用。
      IllegalArgumentException - 如果以下任一情况为真：
      • image为null。
      • 相交区域不包含至少一个像素。
      • image的布局与现有图像布局不匹配，或者此写入程序无法将其转换为现有图像布局。
      IOException - 如果在写入过程中发生I/O错误。

    • replacePixels

      public void replacePixels(Raster raster, ImageWriteParam param) throws IOException
      用给定Raster的一部分替换已存在于输出中的图像的一部分。图像数据必须匹配或可转换为现有图像的图像布局。

      可以选择提供ImageWriteParam以控制写入过程。如果param为null，将使用默认的写入参数。

      目标区域在param参数中指定，并将被裁剪为图像边界和提供给prepareReplacePixels的区域。源的至少一个像素不能被裁剪，否则将抛出异常。

      如果提供的ImageWriteParam包含此写入程序不支持的可选设置值（例如渐进编码或任何特定于格式的设置），它们将被忽略。

      此方法只能在调用prepareReplacePixels之后调用，否则将抛出IllegalStateException。

      默认实现会在输出为null时抛出IllegalStateException，否则抛出UnsupportedOperationException。

      参数:
      raster - 包含源像素的Raster。
      param - 一个ImageWriteParam，或null以使用默认的ImageWriteParam。
      抛出:
      IllegalStateException - 如果输出尚未设置。
      UnsupportedOperationException - 如果canReplacePixels(imageIndex)返回false。
      IllegalStateException - 如果没有之前调用prepareReplacePixels而没有匹配的endReplacePixels调用。
      UnsupportedOperationException - 如果canWriteRasters返回false。
      IllegalArgumentException - 如果以下任一情况为真：
      • raster为null。
      • 相交区域不包含至少一个像素。
      • raster的布局与现有图像布局不匹配，或者此写入程序无法将其转换为现有图像布局。
      IOException - 如果在写入过程中发生I/O错误。

    • endReplacePixels

      public void endReplacePixels() throws IOException
      终止对replacePixels的一系列调用。

      如果canReplacePixels返回false，将抛出UnsupportedOperationException。

      默认实现会在输出为null时抛出IllegalStateException，否则抛出UnsupportedOperationException。

      抛出:
      IllegalStateException - 如果输出尚未设置。
      UnsupportedOperationException - 如果canReplacePixels(imageIndex)返回false。
      IllegalStateException - 如果没有之前调用prepareReplacePixels而没有匹配的endReplacePixels调用。
      IOException - 如果在写入过程中发生I/O错误。

    • abort

      public void abort()
      请求中止任何当前写入操作。中止后的输出内容将是未定义的。

      写入程序应在每次写入操作开始时调用clearAbortRequest，并在写入过程中定期轮询abortRequested的值。

    • abortRequested

      protected boolean abortRequested()
      如果自写入程序实例化以来或调用clearAbortRequest以来已发出中止当前写入操作的请求，则返回true。
      返回:
      如果应中止当前写入操作，则返回true。
      参见:

    • clearAbortRequest

      protected void clearAbortRequest()
      清除任何先前的中止请求。调用此方法后，abortRequested将返回false。
      参见:

    • addIIOWriteWarningListener

      public void addIIOWriteWarningListener(IIOWriteWarningListener listener)
      将一个IIOWriteWarningListener添加到已注册的警告侦听器列表中。如果listener为null，则不会抛出异常，也不会执行任何操作。发送到给定侦听器的消息将在可能的情况下本地化，以匹配当前的Locale。如果未设置Locale，则警告消息可能会根据写入程序的看法进行本地化。
      参数:
      listener - 要注册的IIOWriteWarningListener。
      参见:

    • removeIIOWriteWarningListener

      public void removeIIOWriteWarningListener(IIOWriteWarningListener listener)
      从已注册的警告侦听器列表中删除一个IIOWriteWarningListener。如果侦听器先前未注册，或者listener为null，则不会抛出异常，也不会执行任何操作。
      参数:
      listener - 要注销的IIOWriteWarningListener。
      参见:

    • removeAllIIOWriteWarningListeners

      public void removeAllIIOWriteWarningListeners()
      删除当前所有已注册的IIOWriteWarningListener对象。

      默认实现将warningListeners和warningLocales实例变量设置为null。

    • addIIOWriteProgressListener

      public void addIIOWriteProgressListener(IIOWriteProgressListener listener)
      将一个IIOWriteProgressListener添加到已注册的进度监听器列表中。如果listener为null，则不会抛出异常，也不会执行任何操作。
      参数:
      listener - 要注册的IIOWriteProgressListener。
      参见:

    • removeIIOWriteProgressListener

      public void removeIIOWriteProgressListener(IIOWriteProgressListener listener)
      从已注册的进度监听器列表中移除一个IIOWriteProgressListener。如果监听器之前未注册，或者listener为null，则不会抛出异常，也不会执行任何操作。
      参数:
      listener - 要注销的IIOWriteProgressListener。
      参见:

    • removeAllIIOWriteProgressListeners

      public void removeAllIIOWriteProgressListeners()
      移除当前所有已注册的IIOWriteProgressListener对象。

      默认实现将progressListeners实例变量设置为null。

    • processImageStarted

      protected void processImageStarted(int imageIndex)
      通过调用它们的imageStarted方法，向所有已注册的IIOWriteProgressListener广播图像写入的开始。子类可以使用此方法作为一种便利。
      参数:
      imageIndex - 即将被写入的图像的索引。

    • processImageProgress

      protected void processImageProgress(float percentageDone)
      通过调用它们的imageProgress方法，向所有已注册的IIOWriteProgressListener广播图像完成的当前百分比。子类可以使用此方法作为一种便利。
      参数:
      percentageDone - 当前完成百分比，作为float。

    • processImageComplete

      protected void processImageComplete()
      通过调用它们的imageComplete方法，向所有已注册的IIOWriteProgressListener广播图像写入的完成。子类可以使用此方法作为一种便利。

    • processThumbnailStarted

      protected void processThumbnailStarted(int imageIndex, int thumbnailIndex)
      通过调用它们的thumbnailStarted方法，向所有已注册的IIOWriteProgressListener广播缩略图写入的开始。子类可以使用此方法作为一种便利。
      参数:
      imageIndex - 与缩略图关联的图像的索引。
      thumbnailIndex - 缩略图的索引。

    • processThumbnailProgress

      protected void processThumbnailProgress(float percentageDone)
      通过调用它们的thumbnailProgress方法，向所有已注册的IIOWriteProgressListener广播缩略图完成的当前百分比。子类可以使用此方法作为一种便利。
      参数:
      percentageDone - 当前完成百分比，作为float。

    • processThumbnailComplete

      protected void processThumbnailComplete()
      通过调用它们的thumbnailComplete方法，向所有已注册的IIOWriteProgressListener广播缩略图写入的完成。子类可以使用此方法作为一种便利。

    • processWriteAborted

      protected void processWriteAborted()
      通过调用它们的writeAborted方法，向所有已注册的IIOWriteProgressListener广播写入操作已中止。子类可以使用此方法作为一种便利。

    • processWarningOccurred

      protected void processWarningOccurred(int imageIndex, String warning)
      通过调用它们的warningOccurred方法，向所有已注册的IIOWriteWarningListener广播警告消息。子类可以使用此方法作为一种便利。
      参数:
      imageIndex - 发生警告的图像的索引。
      warning - 警告消息。
      抛出:
      IllegalArgumentException - 如果warning为null。

    • processWarningOccurred

      protected void processWarningOccurred(int imageIndex, String baseName, String keyword)
      通过从ResourceBundle中获取的字符串调用它们的warningOccurred方法，向所有已注册的IIOWriteWarningListener广播本地化的警告消息。子类可以使用此方法作为一种便利。
      参数:
      imageIndex - 发生警告的图像的索引。
      baseName - 包含本地化警告消息的一组ResourceBundle的基本名称。
      keyword - 在ResourceBundle集合中用于索引警告消息的关键字。
      抛出:
      IllegalArgumentException - 如果baseName为null。
      IllegalArgumentException - 如果keyword为null。
      IllegalArgumentException - 如果无法找到适当的ResourceBundle。
      IllegalArgumentException - 如果在定位的ResourceBundle中找不到命名资源。
      IllegalArgumentException - 如果从ResourceBundle中检索的对象不是String。

    • reset

      public void reset()
      将ImageWriter恢复到初始状态。

      默认实现调用setOutput(null)、setLocale(null)、removeAllIIOWriteWarningListeners()、removeAllIIOWriteProgressListeners()和clearAbortRequest。

    • dispose

      public void dispose()
      允许释放此对象持有的任何资源。在调用此方法后继续调用任何其他方法（除了finalize）的结果是未定义的。

      当应用程序知道不再需要使用此ImageWriter时，调用此方法非常重要。否则，写入器可能会无限期地保留资源。

      在超类中此方法的默认实现不执行任何操作。子类实现应确保释放所有资源，特别是本机资源。