javax.imageio
类 ImageReader

java.lang.Object
  javax.imageio.ImageReader

public abstract class ImageReader
extends Object

用来解析和解码图像的抽象超类。在 Java Image I/O 框架的上下文中读入图像的类必须创建此类的子类。

ImageReader 对象通常由特定格式的服务提供者接口 (SPI) 类实例化。服务提供者类（例如 ImageReaderSpi 的实例）向 IIORegistry 注册，后者使用前者进行格式识别和表示可用格式 reader 和 writer。

在设置输入源时（使用 setInput 方法），可以将它标记为“只向前搜索”。此设置意味着包含在输入源中的图像将只按顺序读取，可能允许 reader 避免缓存包含与以前已经读取的图像关联的数据的那些输入部分。

另请参见：

ImageWriter, IIORegistry, ImageReaderSpi

originatingProvider

protected ImageReaderSpi originatingProvider

实例化此对象的 ImageReaderSpi，如果其身份未知或不存在，则为 null。默认情况下初始化为 null。

input

protected Object input

由 setInput 设置并由 getInput 获取的 ImageInputStream 或其他 Object。默认情况下初始化为 null。

seekForwardOnly

protected boolean seekForwardOnly

如果当前输入源已经被 setInput 标记为允许只向前搜索，则为 true。默认情况下，该值为 false。

另请参见：

minIndex, setInput(java.lang.Object, boolean, boolean)

ignoreMetadata

protected boolean ignoreMetadata

如果当前输入源已经被 setInput 标记为允许忽略元数据，则为 true。默认情况下，该值为 false。

另请参见：

setInput(java.lang.Object, boolean, boolean)

minIndex

protected int minIndex

用来读取的最小有效索引，最初为 0。如果 seekForwardOnly 为 true ，各种方法在试图访问与拥有更低索引的图像关联的数据时将抛出 IndexOutOfBoundsException。

另请参见：

seekForwardOnly, setInput(java.lang.Object, boolean, boolean)

availableLocales

protected Locale[] availableLocales

可以用来本地化警告消息的 Locale 组成的数组，如果不支持本地化，则为 null。

locale

protected Locale locale

用于本地化的当前 Locale，如果没有设置，则为 null。

warningListeners

protected List<IIOReadWarningListener> warningListeners

当前已注册 IIOReadWarningListener 组成的 List，默认情况下初始化为 null，它与空 List 同义。

warningLocales

protected List<Locale> warningLocales

与每个当前已注册 IIOReadWarningListener 关联的 Locale 组成的 List，默认情况下初始化为 null，它与空 List 同义。

progressListeners

protected List<IIOReadProgressListener> progressListeners

当前已注册 IIOReadProgressListener 组成的 List，默认情况下初始化为 null，它与空 List 同义。

updateListeners

protected List<IIOReadUpdateListener> updateListeners

当前已注册 IIOReadUpdateListener 组成的 List，默认情况下初始化为 null，它与空 List 同义。

ImageReader

protected ImageReader(ImageReaderSpi originatingProvider)

构造一个 ImageReader，并将其 originatingProvider 字段设置为所提供的值。

利用扩展的子类应该为提供具有签名 (ImageReaderSpi, Object) 的构造方法来获取扩展对象。如果扩展对象不合适，则将抛出 IllegalArgumentException。

参数：

originatingProvider - 调用此构造方法的 ImageReaderSpi，或者为 null。

getFormatName

public String getFormatName()
                     throws IOException

返回一个标识输入源格式的 String。

默认实现返回 originatingProvider.getFormatNames()[0]。没有原始服务提供者的实现或者希望使用不同命名策略的实现应该重写此方法。

返回：

String 形式的格式名称。

抛出：

IOException - 如果从输入源中读取信息时发生错误。

getOriginatingProvider

public ImageReaderSpi getOriginatingProvider()

返回传入构造方法的 ImageReaderSpi。注意，此值可能为 null。

返回：

一个 ImageReaderSpi 或 null。

另请参见：

ImageReaderSpi

setInput

public void setInput(Object input,
                     boolean seekForwardOnly,
                     boolean ignoreMetadata)

设置用于给定的 ImageInputStream 或其他 Object 的输入源。输入源必须在使用任何查询或读取方法之前设置。如果 input 为 null，则将移除所有当前设置的输入源。无论是哪种情况，minIndex 的值都将被初始化为 0。

seekForwardOnly 参数控制在读取每个图像（或者缩略图或图像元数据）时，由 getMinIndex 返回的值是否增加。如果 seekForwardOnly 为 true，则在 index < this.minIndex 的情况下调用 read(index) 将抛出 IndexOutOfBoundsException；否则 minIndex 的值将被设置为 index。如果 seekForwardOnly 为 false，则 minIndex 的值将仍然为 0，不考虑任何读取操作。

如果将 ignoreMetadata 参数设置为 true，则允许 reader 忽略读取操作期间遇到的任何元数据。后续调用 getStreamMetadata 和 getImageMetadata 方法可能返回 null，从 readAll 返回的 IIOImage 的 getMetadata 方法可能返回 null。设置此参数可允许 reader 更有效地工作。reader 可以选择忽略此设置值，正常地返回元数据。

子类应该注意移除任何基于以前的流缓存的信息，比如标题信息或部分解码的图像数据。

直接与捕获设备或图像协议交互的 reader 应该使用一般的 Object，而不是 ImageInputStream。合法类的集合由 reader 的服务提供者的 getInputTypes 方法公开。大多数 reader 将返回一个只包含 ImageInputStream.class 的单元素数组，指示其只接受 ImageInputStream。

默认实现根据 originatingProvider.getInputTypes() 返回的列表检查 input 参数，如果该参数不是列表中某个类的实例，则操作失败。如果将原始提供者设置为 null，则只在 input 是一个 ImageInputStream 时接受输入。

参数：

input - 将来解码时用到的 ImageInputStream 或其他 Object。

seekForwardOnly - 如果为 true，则只能按升序从此输入源中读取图像和元数据。

ignoreMetadata - 如果为 true，则可以在读取期间忽略元数据。

抛出：

IllegalArgumentException - 如果 input 不是原始服务提供者的 getInputTypes 方法返回的某个类的实例，或者不是一个 ImageInputStream。

另请参见：

ImageInputStream, getInput(), ImageReaderSpi.getInputTypes()

setInput

public void setInput(Object input,
                     boolean seekForwardOnly)

设置用于给定的 ImageInputStream 或其他 Object 的输入源。输入源必须在使用任何查询或读取方法之前设置。如果 input 为 null，则将移除所有当前设置的输入源。无论是哪种情况，minIndex 的值都将被初始化为 0。

seekForwardOnly 参数控制在读取每个图像（或者缩略图或图像元数据）时，由 getMinIndex 返回的值是否增加。如果 seekForwardOnly 为 true，则在 index < this.minIndex 的情况下调用 read(index) 将抛出 IndexOutOfBoundsException；否则 minIndex 的值将被设置为 index。如果 seekForwardOnly 为 false，则 minIndex 的值将仍然为 0，不考虑任何读取操作。

此方法等效于 setInput(input, seekForwardOnly, false)。

参数：

input - 将来解码时用到的 ImageInputStream 或其他 Object。

seekForwardOnly - 如果为 true，则只能按升序从此输入源中读取图像和元数据。

抛出：

IllegalArgumentException - 如果 input 不是原始服务提供者的 getInputTypes 方法返回的某个类的实例，或者不是一个 ImageInputStream。

另请参见：

getInput()

setInput

public void setInput(Object input)

设置用于给定的 ImageInputStream 或其他 Object 的输入源。输入源必须在使用任何查询或读取方法之前设置。如果 input 为 null，则将移除所有当前设置的输入源。无论是哪种情况，minIndex 的值都将被初始化为 0。

此方法等效于 setInput(input, false, false)。

参数：

input - 将来解码时用到的 ImageInputStream 或其他 Object。

抛出：

IllegalArgumentException - 如果 input 不是原始服务提供者的 getInputTypes 方法返回的某个类的实例，或者不是一个 ImageInputStream。

另请参见：

getInput()

getInput

public Object getInput()

返回以前设置为输入源的 ImageInputStream 或其他 Object。如果没有设置输入源，则返回 null。

返回：

将来解码时用到的 Object；或者 null。

另请参见：

ImageInputStream, setInput(java.lang.Object, boolean, boolean)

isSeekForwardOnly

public boolean isSeekForwardOnly()

如果已经通过传递 true 作为 setInput 方法的 seekForwardOnly 参数将当前输入源标记为只向前搜索，则返回 true。

返回：

如果输入源是只向前搜索的，则返回 true。

另请参见：

setInput(java.lang.Object, boolean, boolean)

isIgnoringMetadata

public boolean isIgnoringMetadata()

如果已经通过传递 true 作为 setInput 方法的 ignoreMetadata 参数将当前输入源标记为允许忽略元数据，则返回 true。

返回：

如果可以忽略元数据，则返回 true。

另请参见：

setInput(java.lang.Object, boolean, boolean)

getMinIndex

public int getMinIndex()

返回用于读取图像、缩略图或图像元数据的最低有效索引。如果 seekForwardOnly() 为 false，此值通常仍然为 0，指示可能进行随机访问。否则，它将包含最近一次访问的索引值，并单调递增。

返回：

可读取的最小合法索引。

getAvailableLocales

public Locale[] getAvailableLocales()

返回可用来初始化警告侦听器和压缩设置值的 Locale 所组成的数组。返回 null 值指示不支持本地化。

如果 availableLocales 实例变量是非 null 的，则默认实现返回该变量的副本，否则返回 null。

返回：

可以用作 setLocale 的参数的 Locale 所组成的数组，或者返回 null。

setLocale

public void setLocale(Locale locale)

将此 ImageReader 的当前 Locale 设置为给定值。值为 null 则移除所有以前的设置值，并指示 reader 应该根据需要对其进行本地化。

参数：

locale - 所需的 Locale，或者为 null。

抛出：

IllegalArgumentException - 如果 locale 为非 null，但它不是 getAvailableLocales 返回的值之一。

另请参见：

getLocale()

getLocale

public Locale getLocale()

返回当前设置的 Locale，如果没有设置 Locale，则返回 null。

返回：

当前 Locale 或 null。

另请参见：

setLocale(java.util.Locale)

getNumImages

public abstract int getNumImages(boolean allowSearch)
                          throws IOException

返回当前输入源中可用的图像数，不包括缩略图。

注意，一些图像格式（比如动画 GIF）并不指定流中存在多少图像。因此，确定图像数就需要扫描整个流，并且可能需要内存用来缓冲。如果图像是按顺序处理的，则可能更有效的方法是：使用递增的索引来调用 read，直到抛出 IndexOutOfBoundsException 指示不再有图像可用。可以将 allowSearch 参数设置为 false，指示不需要进行彻底搜索；返回值为 -1 则指示搜索是必要的。如果已在 seekForwardOnly 设置为 true 的情况下指定输入，则此方法在 allowSearch 被设置为 true 时将抛出 IllegalStateException。

参数：

allowSearch - 如果为 true，则将返回真实的图像数，即使需要进行搜索。如果该参数为 false，则 reader 返回 -1，不执行搜索。

返回：

int 形式的图像数，如果 allowSearch 为 false，则返回 -1，并且将需要搜索。

抛出：

IllegalStateException - 如果没有设置输入源，或者已在 seekForwardOnly 设置为 true 的情况下指定了输入。

IOException - 如果从输入源中读取信息时发生错误。

另请参见：

setInput(java.lang.Object, boolean, boolean)

getWidth

public abstract int getWidth(int imageIndex)
                      throws IOException

返回输入源中的给定图像的宽度，以像素为单位。

如果可以将图像呈现为用户指定大小，则此方法将返回默认宽度。

参数：

imageIndex - 要查询的图像的索引。

返回：

int 形式的图像宽度。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果从输入源中读取宽度信息时发生错误。

getHeight

public abstract int getHeight(int imageIndex)
                       throws IOException

返回输入源中的给定图像的高度，以像素为单位。

如果可以将图像呈现为用户指定大小，则此方法将返回默认高度。

参数：

imageIndex - 要查询的图像的索引。

返回：

int 形式的图像高度。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果从输入源中读取高度信息时发生错误。

isRandomAccessEasy

public boolean isRandomAccessEasy(int imageIndex)
                           throws IOException

如果给定图像的存储格式不会给像素的随机访问带来内在妨碍，则返回 true。对于大多数压缩格式（比如 JPEG），此方法应该返回 false，因为除了感兴趣的区域以外，可能还需要对图像的绝大部分进行解码。

对于希望更加有效的程序而言，这只是一个提示。所有 reader 必须能够读取在 ImageReadParam 中指定的任意区域。

注意，从此方法返回 false 的格式可能仍然允许进行平铺（例如，JPEG 格式的 Restart Marker），随机访问对于 tile 可能相当有效。参见 isImageTiled。

对于保证所有图像都支持轻松随机访问或者都不支持轻松随机访问的 reader，分别返回 true 或 false，而不必访问任何图像数据。在这种情况下，即使输入源没有设置或者图像索引超出范围，也未必抛出异常。

默认实现返回 false。

参数：

imageIndex - 要查询的图像的索引。

返回：

如果读取给定图像的感兴趣区域可能是有效的，则返回 true。

抛出：

IllegalStateException - 如果需要输入源来确定返回值，但没有设置输入源。

IndexOutOfBoundsException - 如果必须访问某一图像来确定返回值，但所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

getAspectRatio

public float getAspectRatio(int imageIndex)
                     throws IOException

以 float 的形式返回给定图像的高宽比（即宽度除以高度）。对于本来就可以调整大小的图像，此方法提供了一个在已知所需高度的情况下确定适当宽度的方法，反之亦然。对于不可调整大小的图像，则使用真实宽度和高度。

默认实现只是返回 (float)getWidth(imageIndex)/getHeight(imageIndex)。

参数：

imageIndex - 要查询的图像的索引。

返回：

指示给定图像高宽比的 float 值。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

getRawImageType

public ImageTypeSpecifier getRawImageType(int imageIndex)
                                   throws IOException

返回一个 ImageTypeSpecifier，指示最能代表图像“原始”内部格式的 SampleModel 和 ColorModel。例如，对于 JPEG 图像，原始类型可能有一个 YCbCr 颜色空间，即使该图像在显示之前会按照惯例被转换为一个 RGB 颜色空间。返回值还应该包含在 getImageTypes 返回的值所组成的列表中。

默认实现只返回 getImageType 所提供列表中的第一项。

参数：

imageIndex - 要查询的图像的索引。

返回：

一个 ImageTypeSpecifier。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果从输入源中读取格式信息时发生错误。

getImageTypes

public abstract Iterator<ImageTypeSpecifier> getImageTypes(int imageIndex)
                                                    throws IOException

以 ImageTypeSpecifier 形式返回包含可能的图像类型的 Iterator，给定图像可能被解码成这些类型。至少将返回一个合法图像类型。

迭代器的第一个元素应该是用于解码图像的最“自然的”类型，所带来的损失尽可能的少。例如，对于 JPEG 图像，第一项应该是 RGB 图像，即使图像数据内部存储在 YCbCr 颜色空间中。

参数：

imageIndex - 将被 retrieved 的图像的索引。

返回：

一个 Iterator，它至少包含一个表示用来解码当前给定图像的荐图像类型的 ImageTypeSpecifier。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果从输入源中读取格式信息时发生错误。

另请参见：

ImageReadParam.setDestination(BufferedImage), ImageReadParam.setDestinationType(ImageTypeSpecifier)

getDefaultReadParam

public ImageReadParam getDefaultReadParam()

返回一个适合此格式的默认 ImageReadParam 对象。所有子类都应该定义一个用于所有参数的默认值集合，并使用此调用返回这些值。可以在设置输入源之前调用此方法。

默认实现构造并返回一个新的 ImageReadParam 对象，该对象不允许源进行缩放（也就是说，它返回 new ImageReadParam()）。

返回：

一个可以使用一组默认设置控制解码过程的 ImageReadParam 对象。

getStreamMetadata

public abstract IIOMetadata getStreamMetadata()
                                       throws IOException

返回一个 IIOMetadata 对象，它表示作为一个整体与输入源关联的元数据（即不与任何特定图像关联）；如果 reader 不支持读取元数据、被设置为忽略元数据，或者没有元数据可用，则返回 null。

返回：

IIOMetadata 对象或者 null。

抛出：

IOException - 如果在读取过程中发生错误。

getStreamMetadata

public IIOMetadata getStreamMetadata(String formatName,
                                     Set<String> nodeNames)
                              throws IOException

返回一个 IIOMetadata 对象，它表示作为一个整体与输入源关联的元数据（即不与任何特定图像关联）。如果不存在这样的数据，则返回 null。

得到的元数据对象只负责以 formatName 指定的格式返回文档。在所有返回的文档中，只需要返回其名称是 nodeNames 成员的节点。这样，基于实际需要的信息，由 reader 处理的元数据数量可以保持在最低限度。

如果 formatName 不是受支持的元数据格式的名称，则返回 null。

在所有情况下，返回一个功能强于确实必需的元数据对象是合法的。格式名称和节点名称仅仅是用来减少 reader 工作负荷的提示。

默认实现在检查格式名称是否受支持之后返回调用 getStreamMetadata() 的结果。如果不受支持，则返回 null。

参数：

formatName - 可用来从返回的 IIOMetadata 对象中获取文档的元数据格式名称。

nodeNames - 包含可包含在获取到的文档中的节点名称所组成的 Set。

返回：

IIOMetadata 对象或者 null。

抛出：

IllegalArgumentException - 如果 formatName 为 null。

IllegalArgumentException - 如果 nodeNames 为 null。

IOException - 如果在读取过程中发生错误。

getImageMetadata

public abstract IIOMetadata getImageMetadata(int imageIndex)
                                      throws IOException

返回包含与给定图像关联的元数据的 IIOMetadata 对象，如果 reader 不支持读取元数据、被设置为忽略元数据，或者没有元数据可用，则返回 null。

参数：

imageIndex - 其元数据将被获取的图像的索引。

返回：

IIOMetadata 对象或者 null。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

getImageMetadata

public IIOMetadata getImageMetadata(int imageIndex,
                                    String formatName,
                                    Set<String> nodeNames)
                             throws IOException

返回表示与给定图像关联的元数据的 IIOMetadata 对象，如果 reader 不支持读取元数据或者没有元数据可用，则返回 null。

得到的元数据对象只负责以 formatName 指定的格式返回文档。在所有返回的文档中，只需要返回其名称是 nodeNames 成员的节点。这样，基于实际需要的信息，由 reader 处理的元数据数量可以保持在最低限度。

如果 formatName 不是受支持的元数据格式的名称，则返回 null。

在所有情况下，返回一个功能强于确实必需的元数据对象是合法的。格式名称和节点名称仅仅是用来减少 reader 工作负荷的提示。

默认实现在检查格式名称是否受支持之后返回调用 getImageMetadata(imageIndex) 的结果。如果不受支持，则返回 null。

参数：

imageIndex - 其元数据将被获取的图像的索引。

formatName - 可用来从返回的 IIOMetadata 对象中获取文档的元数据格式名称。

nodeNames - 包含可包含在获取到的文档中的节点名称所组成的 Set。

返回：

IIOMetadata 对象或者 null。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IllegalArgumentException - 如果 formatName 为 null。

IllegalArgumentException - 如果 nodeNames 为 null。

IOException - 如果在读取过程中发生错误。

read

public BufferedImage read(int imageIndex)
                   throws IOException

使用默认 ImageReadParam 读取通过索引 imageIndex 指定的图像，并将其作为一个完整的 BufferedImage 返回。这是一个调用 read(imageIndex, null) 的便捷方法。

返回的图像将根据从 getImageTypes 中返回的第一个 ImageTypeSpecifier 进行格式化。

所有已注册的 IIOReadProgressListener 对象将通过以下方式获得通知：首先调用其 imageStarted 方法，然后在读取过程中调用其 imageProgress 方法。最后，将调用其 imageComplete 方法。解码像素时，IIOReadUpdateListener 对象可以在读取期间的其他时间更新。最后，IIOReadWarningListener 对象将接收解码期间发生的所有非致命警告。

参数：

imageIndex - 将被获取的图像的索引。

返回：

BufferedImage 形式的所需图像部分。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

read

public abstract BufferedImage read(int imageIndex,
                                   ImageReadParam param)
                            throws IOException

使用所提供的 ImageReadParam 读取通过索引 imageIndex 指定的对象，并将它作为一个完整的 BufferedImage 返回。

实际返回的 BufferedImage 将使用 getDestination 方法定义的算法来选择。

所有已注册的 IIOReadProgressListener 对象将通过以下方式获得通知：首先调用其 imageStarted 方法，然后在读取过程中调用其 imageProgress 方法。最后，将调用其 imageComplete 方法。解码像素时，IIOReadUpdateListener 对象可以在读取期间的其他时间更新。最后，IIOReadWarningListener 对象将接收解码期间发生的所有非致命警告。

要读取的源 band 和要写入的目标 band 的集合通过在所提供的 ImageReadParam 上调用 getSourceBands 和 getDestinationBands 确定。如果这些方法返回的数组的长度不同、源 band 集合包含一个比最大可用源索引更大的索引，或者目标 band 集合包含一个比最大的合法目标索引更大的索引，则抛出 IllegalArgumentException。

如果所提供的 ImageReadParam 包含不受此 reader 支持的可选设置值（例如 源呈现大小或任何特定于格式的设置），则将忽略这些设置。

参数：

imageIndex - 将被获取的图像的索引。

param - 用来控制读取过程的 ImageReadParam，或者为 null。

返回：

BufferedImage 形式的所需图像部分。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IllegalArgumentException - 如果由 param.getSourceBands 和 param.getDestinationBands 指定的源 band 和目标 band 的集合在长度上不同，或者包含超出范围的索引。

IllegalArgumentException - 如果所得图像的宽度或高度小于 1。

IOException - 如果读取期间发生错误。

readAll

public IIOImage readAll(int imageIndex,
                        ImageReadParam param)
                 throws IOException

使用所提供的 ImageReadParam 读取通过索引 imageIndex 指定的图像，并返回包含图像、缩略图和相关图像元数据的 IIOImage。

由返回的 IIOImage 实际引用的 BufferedImage 将使用 getDestination 方法定义的算法来选择。

所有已注册的 IIOReadProgressListener 对象将通过以下方式获得通知：首先调用其 imageStarted 方法，然后在读取过程中调用其 imageProgress 方法。最后，将调用其 imageComplete 方法。解码像素时，IIOReadUpdateListener 对象可以在读取期间的其他时间更新。最后，IIOReadWarningListener 对象将接收解码期间发生的所有非致命警告。

要读取的源 band 和要写入的目标 band 的集合通过在所提供的 ImageReadParam 上调用 getSourceBands 和 getDestinationBands 确定。如果这些方法返回的数组的长度不同、源 band 集合包含一个比最大可用源索引更大的索引，或者目标 band 集合包含一个比最大的合法目标索引更大的索引，则抛出 IllegalArgumentException。

无论怎样设置区域，缩略图都将以其完整形式返回。

如果所提供的 ImageReadParam 包含不受此 reader 支持的可选设置值（例如 源呈现大小或任何特定于格式的设置），则将忽略这些设置。

参数：

imageIndex - 将被获取的图像的索引。

param - 用来控制读取过程的 ImageReadParam，或者为 null。

返回：

一个 IIOImage，包含所需图像部分、一个缩略图集合和关联的图像元数据。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IllegalArgumentException - 如果由 param.getSourceBands 和 param.getDestinationBands 指定的源 band 和目标 band 的集合在长度上不同，或者包含超出范围的索引。

IllegalArgumentException - 如果所得图像的宽度或高度小于 1。

IOException - 如果读取期间发生错误。

readAll

public Iterator<IIOImage> readAll(Iterator<? extends ImageReadParam> params)
                           throws IOException

以 IIOImage 对象形式返回包含输入源中所有图像、缩略图和元数据的 Iterator，从 getMinIndex 给定的索引开始。提供一个包含 ImageReadParam 对象的 Iterator，从输入源中读取的每个图像使用一个元素，直到不再有图像可用。如果 read 参数的 Iterator 超出了元素的范围，但输入源中仍然有更多的可用图像，则将默认 read 参数用于剩余的图像。

如果 params 为 null，则将默认 read 参数用于所有图像。

由返回的 IIOImage 实际引用的 BufferedImage 将使用 getDestination 方法定义的算法来选择。

所有已注册 IIOReadProgressListener 对象都将通过调用其 sequenceStarted 方法一次获得通知。然后，对于每个解码图像，都将调用 imageStarted，随后在读取过程中调用 imageProgress，最后调用 imageComplete。sequenceComplete 方法将在解码最后一幅图像后调用。解码像素时，IIOReadUpdateListener 对象可以在读取期间的其他时间更新。最后，IIOReadWarningListener 对象将接收解码期间发生的所有非致命警告。

要读取的源 band 和要写入的目标 band 的集合通过在所提供的 ImageReadParam 上调用 getSourceBands 和 getDestinationBands 确定。如果这些方法返回的数组的长度不同、源 band 集合包含一个比最大可用源索引更大的索引，或者目标 band 集合包含一个比最大的合法目标索引更大的索引，则抛出 IllegalArgumentException。

无论怎样设置区域，缩略图都将以其完整形式返回。

如果任何所提供的 ImageReadParam 都包含不受此 reader 支持的可选设置值（例如 源呈现大小或任何特定于格式的设置），则将忽略这些设置。

参数：

params - 包含 ImageReadParam 对象的 Iterator。

返回：

将输入源的内容表示为 IIOImage 的 Iterator。

抛出：

IllegalStateException - 如果尚未设置输入源。

IllegalArgumentException - 如果 params 的非 null 元素不是一个 ImageReadParam。

IllegalArgumentException - 如果由 param.getSourceBands 和 param.getDestinationBands 指定的源 band 和目标 band 的集合在长度上不同，或者包含超出范围的索引。

IllegalArgumentException - 如果所得图像的宽度或高度小于 1。

IOException - 如果读取期间发生错误。

另请参见：

ImageReadParam, IIOImage

canReadRaster

public boolean canReadRaster()

如果此插件支持只读取像素数据的 Raster，则返回 true。如果此方法返回 false，则调用 readRaster 或 readTileRaster 将抛出 UnsupportedOperationException。

默认实现返回 false。

返回：

如果此插件支持读取原始 Raster，则返回 true。

另请参见：

readRaster(int, javax.imageio.ImageReadParam), readTileRaster(int, int, int)

readRaster

public Raster readRaster(int imageIndex,
                         ImageReadParam param)
                  throws IOException

返回包含图像流中原始像素数据的新 Raster 对象，不应用任何颜色转换。应用程序必须确定如何通过其他方法解释像素数据。所提供的 ImageReadParam 对象中的任何 destination 或 image-type 参数都被忽略，但其他所有参数的使用与 read 方法完全相同，唯一的不同在于所有的目标偏移量被用作逻辑偏移量而不是物理偏移量。所返回的 Raster 的大小将始终是裁剪为实际图像的源区域大小。忽略流自身中的逻辑偏移量。

此方法允许使用通常应用颜色转换的格式（比如 JPEG）以及通常没有关联颜色空间的格式（比如遥感数据或医学成像数据）来提供对原始像素数据的访问。

所有已注册的 readUpdateListener 都被忽略，因为没有 BufferedImage，但会调用其他所有侦听器，就像将它们用于 read 方法那样。

如果 canReadRaster() 返回 false，则此方法抛出 UnsupportedOperationException。

如果所提供的 ImageReadParam 包含不受此 reader 支持的可选设置值（例如 源呈现大小或任何特定于格式的设置），则将忽略这些设置。

默认的实现抛出 UnsupportedOperationException。

参数：

imageIndex - 要读取的图像的索引。

param - 用来控制读取过程的 ImageReadParam，或者为 null。

返回：

Raster 形式的所需图像部分。

抛出：

UnsupportedOperationException - 如果此插件不支持读取原始 Raster。

IllegalStateException - 如果输入源尚未设置。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

另请参见：

canReadRaster(), read(int), Raster

isImageTiled

public boolean isImageTiled(int imageIndex)
                     throws IOException

如果图像被组织成 tile（即等大小的非重叠矩形），则返回 true。

reader 插件可以选择是否将图像中出现的 tiling 按其存储时的原样公开。甚至可以选择图像中没有显式存在 tiling 时公开 tiling。通常，只有在对访问单独的 tile 有利（在速度或空间方面）时才应该公开 tiling。不管 reader 是否公开 tiling，它必须能够读取 ImageReadParam 中指定的任意矩形区域。

对于可以保证所有平铺所有图像或者不平铺图像的 reader，分别返回 true 或 false，而不必访问任何图像数据。在这种情况下，即使输入源没有设置或者图像索引超出范围，也未必抛出异常。

默认实现返回 false。

参数：

imageIndex - 要查询的图像的索引。

返回：

如果图像被平铺，则返回 true。

抛出：

IllegalStateException - 如果需要输入源来确定返回值，但没有设置输入源。

IndexOutOfBoundsException - 如果必须访问某一图像来确定返回值，但所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

getTileWidth

public int getTileWidth(int imageIndex)
                 throws IOException

返回给定图像中 tile 的宽度。

默认实现返回 getWidth(imageIndex)，对于非平铺图像也是如此。支持 tiling 的 reader 应该重写此方法。

参数：

imageIndex - 要查询的图像的索引。

返回：

tile 的宽度。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

getTileHeight

public int getTileHeight(int imageIndex)
                  throws IOException

返回给定图像中 tile 的高度。

默认实现返回 getHeight(imageIndex)，对于非平铺图像也是如此。支持 tiling 的 reader 应该重写此方法。

参数：

imageIndex - 要查询的图像的索引。

返回：

tile 的高度。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

getTileGridXOffset

public int getTileGridXOffset(int imageIndex)
                       throws IOException

返回给定图像中 tile (0, 0) 的左上角的 X 坐标。

对于 tile 网格 X 偏移量总是具有相同值（通常为 0）的 reader，返回该值，而不必访问任何图像数据。在这种情况下，即使输入源没有设置或者图像索引超出范围，也未必抛出异常。

默认实现返回 0，对于大多数格式的非平铺图像和平铺图像也是如此。支持 tiling、具有非 (0, 0) 偏移量的 reader 应该重写此方法。

参数：

imageIndex - 要查询的图像的索引。

返回：

tile 网格的 X 偏移量。

抛出：

IllegalStateException - 如果需要输入源来确定返回值，但没有设置输入源。

IndexOutOfBoundsException - 如果必须访问某一图像来确定返回值，但所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

getTileGridYOffset

public int getTileGridYOffset(int imageIndex)
                       throws IOException

返回给定图像中 tile (0, 0) 的左上角的 Y 坐标。

对于 tile 网格 Y 偏移量总是具有相同值（通常为 0）的 reader，返回该值，而不必访问任何图像数据。在这种情况下，即使输入源没有设置或者图像索引超出范围，也未必抛出异常。

默认实现返回 0，对于大多数格式的非平铺图像和平铺图像也是如此。支持 tiling、具有非 (0, 0) 偏移量的 reader 应该重写此方法。

参数：

imageIndex - 要查询的图像的索引。

返回：

tile 网格的 Y 偏移量。

抛出：

IllegalStateException - 如果需要输入源来确定返回值，但没有设置输入源。

IndexOutOfBoundsException - 如果必须访问某一图像来确定返回值，但所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

readTile

public BufferedImage readTile(int imageIndex,
                              int tileX,
                              int tileY)
                       throws IOException

读取由 tileX 和 tileY 参数指示的 tile，并以 BufferedImage 形式返回。如果参数超出范围，则抛出 IllegalArgumentException。如果图像是非平铺的，则 0, 0 值将返回整个图像；其他值都将导致抛出 IllegalArgumentException。

此方法只是一个便捷方法，它等效于调用带有一个 read 参数的 read(int, ImageReadParam)，该参数指定源区域的偏移量为 tileX*getTileWidth(imageIndex), tileY*getTileHeight(imageIndex)，宽度和高度为 getTileWidth(imageIndex) 和 getTileHeight(imageIndex)；并在因子为 1 和偏移量为 0 的情况下进行二次取样。要对 tile 进行二次取样，需要使用指定此区域的 read 参数和不同的二次取样参数调用 read。

默认实现在 tileX 和 tileY 为 0 时返回整个图像，其他情况则抛出 IllegalArgumentException。

参数：

imageIndex - 将被获取的图像的索引。

tileX - 将被获取的 tile 的列索引（从 0 开始）。

tileY - 将被获取的 tile 的行索引（从 0 开始）。

返回：

BufferedImage 形式的 tile。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果 imageIndex 超出范围。

IllegalArgumentException - 如果 tile 的索引超出范围。

IOException - 如果在读取过程中发生错误。

readTileRaster

public Raster readTileRaster(int imageIndex,
                             int tileX,
                             int tileY)
                      throws IOException

返回包含 tile 中的原始像素数据的新 Raster 对象，不应用任何颜色转换。应用程序必须确定如何通过其他方法解释像素数据。

如果 canReadRaster() 返回 false，则此方法抛出 UnsupportedOperationException。

默认实现检查是否支持读取 Raster，如果支持且 tileX 和 tileY 为 0，则调用 readRaster(imageIndex, null)，否则抛出 IllegalArgumentException。

参数：

imageIndex - 将被获取的图像的索引。

tileX - 将被获取的 tile 的列索引（从 0 开始）。

tileY - 将被获取的 tile 的行索引（从 0 开始）。

返回：

Raster 形式的 tile。

抛出：

UnsupportedOperationException - 如果此插件不支持读取原始 Raster。

IllegalArgumentException - 如果 tile 索引超出范围。

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果 imageIndex 超出范围。

IOException - 如果在读取过程中发生错误。

另请参见：

readTile(int, int, int), readRaster(int, javax.imageio.ImageReadParam), Raster

readAsRenderedImage

public RenderedImage readAsRenderedImage(int imageIndex,
                                         ImageReadParam param)
                                  throws IOException

返回一个 RenderedImage 对象，该对象包含通过索引 imageIndex 指定的图像的内容。默认情况下，返回的图像是由 read(imageIndex, param) 返回的 BufferedImage。

此方法的语义在某些方面可能不同于其他 read 方法的语义。首先，可以忽略 ImageReadParam 中设置的任何目标图像和/或图像类型。其次，不保证进行一般的侦听器调用，或者进行这些调用时不保证它们是有意义的。这是因为在返回时（甚至任何时候）返回的图像可能并不完全由像素数据填充。

如果所提供的 ImageReadParam 包含不受此 reader 支持的可选设置值（例如 源呈现大小或任何特定于格式的设置），则将忽略这些设置。

默认实现调用 read(imageIndex, param)。

参数：

imageIndex - 将被获取的图像的索引。

param - 用来控制读取过程的 ImageReadParam，或者为 null。

返回：

提供图像视图的 RenderedImage 对象。

抛出：

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果所提供的索引超出范围。

IllegalArgumentException - 如果由 param.getSourceBands 和 param.getDestinationBands 指定的源 band 和目标 band 的集合在长度上不同，或者包含超出范围的索引。

IllegalArgumentException - 如果所得图像的宽度或高度小于 1。

IOException - 如果读取期间发生错误。

readerSupportsThumbnails

public boolean readerSupportsThumbnails()

如果此 reader 所理解的图像格式支持与之关联的缩略图预览图像，则返回 true。默认实现返回 false。

如果此方法返回 false，hasThumbnails 和 getNumThumbnails 将分别返回 false 和 0，而 readThumbnail 将抛出 UnsupportedOperationException（不管其参数如何）。

不支持缩略图的 reader 不需要实现任何与缩略图有关的方法。

返回：

如果支持缩略图，则返回 true。

hasThumbnails

public boolean hasThumbnails(int imageIndex)
                      throws IOException

如果给定图像具有与之关联的缩略图预览图像，则返回 true。如果该格式不支持缩略图（readerSupportsThumbnails 返回 false），则无论是否已经设置了输入源或者 imageIndex 是否在范围内，其都将将返回 false。

默认实现在 getNumThumbnails 的返回值大于 0 的情况下返回 true。

参数：

imageIndex - 要查询的图像的索引。

返回：

如果给定图像具有缩略图，则返回 true。

抛出：

IllegalStateException - 如果 reader 支持缩略图但尚未设置输入源。

IndexOutOfBoundsException - 如果 reader 支持缩略图但 imageIndex 超出范围。

IOException - 如果在读取过程中发生错误。

getNumThumbnails

public int getNumThumbnails(int imageIndex)
                     throws IOException

返回与给定图像关联的缩略图预览图像的数量。如果该格式不支持缩略图（readerSupportsThumbnails 返回 false），则无论是否已经设置了输入源或者 imageIndex 是否在范围内，其都将将返回 0。

默认实现返回 0，不检查其参数。

参数：

imageIndex - 要查询的图像的索引。

返回：

与给定图像关联的缩略图的数量。

抛出：

IllegalStateException - 如果 reader 支持缩略图但尚未设置输入源。

IndexOutOfBoundsException - 如果 reader 支持缩略图但 imageIndex 超出范围。

IOException - 如果在读取过程中发生错误。

getThumbnailWidth

public int getThumbnailWidth(int imageIndex,
                             int thumbnailIndex)
                      throws IOException

返回通过索引 thumbnailIndex 指定的缩略图预览图像的宽度，其与通过索引 ImageIndex 指定的图像关联。

如果 reader 不支持缩略图（readerSupportsThumbnails 返回 false），则将抛出 UnsupportedOperationException。

默认实现返回 readThumbnail(imageindex, thumbnailIndex).getWidth()。所以，为了避免强行读取缩略图，子类应该重写此方法（如果有可能）。

参数：

imageIndex - 将被获取的图像的索引。

thumbnailIndex - 将被获取的缩略图的索引。

返回：

int 形式的所需缩略图宽度。

抛出：

UnsupportedOperationException - 如果不支持缩略图。

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果任何一个所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

getThumbnailHeight

public int getThumbnailHeight(int imageIndex,
                              int thumbnailIndex)
                       throws IOException

返回通过索引 thumbnailIndex 指定的缩略图预览图像的高度，其与通过索引 ImageIndex 指定的图像关联。

如果 reader 不支持缩略图（readerSupportsThumbnails 返回 false），则将抛出 UnsupportedOperationException。

默认实现返回 readThumbnail(imageindex, thumbnailIndex).getHeight()。所以，为了避免强行读取缩略图，子类应该重写此方法（如果有可能）。

参数：

imageIndex - 将被获取的图像的索引。

thumbnailIndex - 将被获取的缩略图的索引。

返回：

int 形式的所需缩略图高度。

抛出：

UnsupportedOperationException - 如果不支持缩略图。

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果任何一个所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

readThumbnail

public BufferedImage readThumbnail(int imageIndex,
                                   int thumbnailIndex)
                            throws IOException

以 BufferedImage 形式返回通过索引 thumbnailIndex 指定的缩略图预览图像，其与通过索引 ImageIndex 指定的图像关联。

所有已注册 IIOReadProgressListener 对象都将通过调用其 thumbnailStarted、thumbnailProgress 和 thumbnailComplete 方法获得通知。

如果 reader 不支持缩略图（readerSupportsThumbnails 返回 false），则无论是否已经设置了输入源或者索引是否在范围内，其都将抛出 UnsupportedOperationException。

默认的实现抛出 UnsupportedOperationException。

参数：

imageIndex - 将被获取的图像的索引。

thumbnailIndex - 将被获取的缩略图的索引。

返回：

BufferedImage 形式的所需缩略图。

抛出：

UnsupportedOperationException - 如果不支持缩略图。

IllegalStateException - 如果尚未设置输入源。

IndexOutOfBoundsException - 如果任何一个所提供的索引超出范围。

IOException - 如果在读取过程中发生错误。

abort

public void abort()

请求中止当前所有读取操作。中止后图像的内容将是不确定的。

reader 应该在开始每个读取操作时调用 clearAbortRequest，并在读取期间定期轮询 abortRequested 的值。

abortRequested

protected boolean abortRequested()

如果从实例化 reader 或调用 clearAbortRequest 时起，已经请求了中止当前读取操作，则返回 true。

返回：

如果应该中止当前读取操作，则返回 true。

另请参见：

abort(), clearAbortRequest()

clearAbortRequest

protected void clearAbortRequest()

清除任何以前的中止请求。在已调用此方法之后，abortRequested 将返回 false。

另请参见：

abort(), abortRequested()

addIIOReadWarningListener

public void addIIOReadWarningListener(IIOReadWarningListener listener)

将 IIOReadWarningListener 添加到已注册的警告侦听器的列表中。如果 listener 为 null，则不会抛出任何异常并且不执行任何操作。将本地化发送到给定侦听器的消息（如果可能）以匹配当前 Locale。如果没有设置 Locale，则可将警告消息本地化为适合 reader 的形式。

参数：

listener - 要注册的 IIOReadWarningListener。

另请参见：

removeIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener)

removeIIOReadWarningListener

public void removeIIOReadWarningListener(IIOReadWarningListener listener)

从已注册的错误侦听器列表中移除 IIOReadWarningListener。如果以前没有注册侦听器，或者 listener 为 null，则不会抛出任何异常并且不执行任何操作。

参数：

listener - 要取消注册的 IIOReadWarningListener。

另请参见：

addIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener)

removeAllIIOReadWarningListeners

public void removeAllIIOReadWarningListeners()

移除所有当前已注册的 IIOReadWarningListener 对象。

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

addIIOReadProgressListener

public void addIIOReadProgressListener(IIOReadProgressListener listener)

将 IIOReadProgressListener 添加到已注册的进度侦听器列表中。如果 listener 为 null，则不会抛出任何异常并且不执行任何操作。

参数：

listener - 要注册的 IIOReadProgressListener。

另请参见：

removeIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener)

removeIIOReadProgressListener

public void removeIIOReadProgressListener(IIOReadProgressListener listener)

从已注册的进度侦听器列表中移除 IIOReadProgressListener。如果以前没有注册侦听器，或者 listener 为 null，则不会抛出任何异常并且不执行任何操作。

参数：

listener - 要取消注册的 IIOReadProgressListener。

另请参见：

addIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener)

removeAllIIOReadProgressListeners

public void removeAllIIOReadProgressListeners()

移除所有当前已注册的 IIOReadProgressListener 对象。

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

addIIOReadUpdateListener

public void addIIOReadUpdateListener(IIOReadUpdateListener listener)

将 IIOReadUpdateListener 添加到已注册的更新侦听器列表中。如果 listener 为 null，则不会抛出任何异常并且不执行任何操作。在解码图像和缩略图时，侦听器将接收像素更新的通知，该通知中包括逐步传递的起始处和结束处。

如果不存在更新侦听器，则 reader 可以选择对目标图像和/或缩略图的像素执行较少的更新，这能促使更加有效的解码。

例如，在逐步 JPEG 解码过程中，每个传递都包含对一个系数集合的更新数据，如果侦听器存在，则必须将这些系数变换成像素值并转换为用于每个传递的 RGB 颜色空间。如果不存在侦听器，则可以累计这些系数，并只变换最终结果和转换颜色一次。

无论是否执行中间的更新，解码的最终结果都相同。因此，如果只需要最终图像，则最好不注册任何 IIOReadUpdateListener。通常，在通过与本地 CPU 处理相比非常慢的网络连接获取图像时，逐步更新是最有效的；而通过快速连接时，逐步更新实际上会降低图像的显示速度。

参数：

listener - 要注册的 IIOReadUpdateListener。

另请参见：

removeIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener)

removeIIOReadUpdateListener

public void removeIIOReadUpdateListener(IIOReadUpdateListener listener)

从已注册的更新侦听器列表中移除 IIOReadUpdateListener。如果以前没有注册侦听器，或者 listener 为 null，则不会抛出任何异常并且不执行任何操作。

参数：

listener - 要取消注册的 IIOReadUpdateListener。

另请参见：

addIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener)

removeAllIIOReadUpdateListeners

public void removeAllIIOReadUpdateListeners()

移除所有当前已注册的 IIOReadUpdateListener 对象。

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

processSequenceStarted

protected void processSequenceStarted(int minIndex)

通过调用所有已注册 IIOReadProgressListener 的 sequenceStarted 方法向其广播图像读取序列的起始处。子类可以将此方法用作一个便捷方法。

参数：

minIndex - 将读取的最低索引。

processSequenceComplete

protected void processSequenceComplete()

通过调用所有已注册 IIOReadProgressListener 的 sequenceComplete 方法向其广播图像读取序列的完成。子类可以将此方法用作一个便捷方法。

processImageStarted

protected void processImageStarted(int imageIndex)

通过调用所有已注册 IIOReadProgressListener 的 imageStarted 方法向其广播图像读取起始处。子类可以将此方法用作一个便捷方法。

参数：

imageIndex - 即将读取的图像的索引。

processImageProgress

protected void processImageProgress(float percentageDone)

通过调用所有已注册 IIOReadProgressListener 的 imageProgress 方法向其广播图像完成的当前百分比。子类可以将此方法用作一个便捷方法。

参数：

percentageDone - float 值形式的当前完成百分比。

processImageComplete

protected void processImageComplete()

通过调用所有已注册 IIOReadProgressListener 的 imageComplete 方法向其广播图像读取的完成。子类可以将此方法用作一个便捷方法。

processThumbnailStarted

protected void processThumbnailStarted(int imageIndex,
                                       int thumbnailIndex)

通过调用所有已注册 IIOReadProgressListener 的 thumbnailStarted 方法向其广播缩略图读取的起始处。子类可以将此方法用作一个便捷方法。

参数：

imageIndex - 与该缩略图关联的图像的索引。

thumbnailIndex - 缩略图的索引。

processThumbnailProgress

protected void processThumbnailProgress(float percentageDone)

通过调用所有已注册 IIOReadProgressListener 的 thumbnailProgress 方法向其广播缩略图完成的当前百分比。子类可以将此方法用作一个便捷方法。

参数：

percentageDone - float 值形式的当前完成百分比。

processThumbnailComplete

protected void processThumbnailComplete()

通过调用所有已注册 IIOReadProgressListener 的 thumbnailComplete 方法向其广播缩略图读取的完成。子类可以将此方法用作一个便捷方法。

processReadAborted

protected void processReadAborted()

通过调用所有已注册 IIOReadProgressListener 的 readAborted 方法向其广播读取已经中止。子类可以将此方法用作一个便捷方法。

processPassStarted

protected void processPassStarted(BufferedImage theImage,
                                  int pass,
                                  int minPass,
                                  int maxPass,
                                  int minX,
                                  int minY,
                                  int periodX,
                                  int periodY,
                                  int[] bands)

通过调用所有已注册 IIOReadUpdateListener 的 passStarted 方法向其广播逐步传递的开始。子类可以将此方法用作一个便捷方法。

参数：

theImage - 将被更新的 BufferedImage。

pass - 当前传递的索引，从 0 开始。

minPass - 将被解码的第一个传递的索引。

maxPass - 将要解码的最后一个传递的索引。

minX - 包含在该传递中的左上角像素的 X 坐标。

minY - 包含在该传递中的左上角像素的 Y 坐标。

periodX - 像素间的水平间距。

periodY - 像素间的垂直间距。

bands - 指示受影响目标 band 集合的 int 数组。

processImageUpdate

protected void processImageUpdate(BufferedImage theImage,
                                  int minX,
                                  int minY,
                                  int width,
                                  int height,
                                  int periodX,
                                  int periodY,
                                  int[] bands)

通过调用所有已注册 IIOReadUpdateListener 的 imageUpdate 方法向其广播样本集合的更新。子类可以将此方法用作一个便捷方法。

参数：

theImage - 将被更新的 BufferedImage。

minX - 包含在该传递中的左上角像素的 X 坐标。

minY - 包含在该传递中的左上角像素的 Y 坐标。

width - 将被更新的区域的总宽度，包括将跳过的像素（如果 periodX > 1）。

height - 将被更新的区域的总高度，包括将跳过的像素（如果 periodY > 1）。

periodX - 像素间的水平间距。

periodY - 像素间的垂直间距。

bands - 指示受影响目标 band 集合的 int 数组。

processPassComplete

protected void processPassComplete(BufferedImage theImage)

通过调用所有已注册 IIOReadUpdateListener 的 passComplete 方法向其广播逐步传递的结束。子类可以将此方法用作一个便捷方法。

参数：

theImage - 将被更新的 BufferedImage。

processThumbnailPassStarted

protected void processThumbnailPassStarted(BufferedImage theThumbnail,
                                           int pass,
                                           int minPass,
                                           int maxPass,
                                           int minX,
                                           int minY,
                                           int periodX,
                                           int periodY,
                                           int[] bands)

通过调用所有已注册 IIOReadUpdateListener 的 thumbnailPassStarted 方法向其广播缩略图逐步传递的开始。子类可以将此方法用作一个便捷方法。

参数：

theThumbnail - 将被更新的 BufferedImage 缩略图。

pass - 当前传递的索引，从 0 开始。

minPass - 将被解码的第一个传递的索引。

maxPass - 将要解码的最后一个传递的索引。

minX - 包含在该传递中的左上角像素的 X 坐标。

minY - 包含在该传递中的左上角像素的 Y 坐标。

periodX - 像素间的水平间距。

periodY - 像素间的垂直间距。

bands - 指示受影响目标 band 集合的 int 数组。

processThumbnailUpdate

protected void processThumbnailUpdate(BufferedImage theThumbnail,
                                      int minX,
                                      int minY,
                                      int width,
                                      int height,
                                      int periodX,
                                      int periodY,
                                      int[] bands)

通过调用所有已注册 IIOReadUpdateListener 的 thumbnailUpdate 方法向其广播缩略图图像中样本集合的更新。子类可以将此方法用作一个便捷方法。

参数：

theThumbnail - 将被更新的 BufferedImage 缩略图。

minX - 包含在该传递中的左上角像素的 X 坐标。

minY - 包含在该传递中的左上角像素的 Y 坐标。

width - 将被更新的区域的总宽度，包括将跳过的像素（如果 periodX > 1）。

height - 将被更新的区域的总高度，包括将跳过的像素（如果 periodY > 1）。

periodX - 像素间的水平间距。

periodY - 像素间的垂直间距。

bands - 指示受影响目标 band 集合的 int 数组。

processThumbnailPassComplete

protected void processThumbnailPassComplete(BufferedImage theThumbnail)

通过调用所有已注册 IIOReadUpdateListener 的 thumbnailPassComplete 方法向其广播缩略图逐步传递的结束。子类可以将此方法用作一个便捷方法。

参数：

theThumbnail - 将被更新的 BufferedImage 缩略图。

processWarningOccurred

protected void processWarningOccurred(String warning)

通过调用所有已注册 IIOReadWarningListener 的 warningOccurred 方法向其广播警告消息。子类可以将此方法用作一个便捷方法。

参数：

warning - 要发送的警告消息。

抛出：

IllegalArgumentException - 如果 warning 为 null。

processWarningOccurred

protected void processWarningOccurred(String baseName,
                                      String keyword)

通过使用取自 ResourceBundle 的字符串调用所有已注册 IIOReadWarningListener 的 warningOccurred 方法向其广播本地化警告消息。子类可以将此方法用作一个便捷方法。

参数：

baseName - 包含本地化警告消息的 ResourceBundle 集合的基本名称。

keyword - 用来搜索 ResourceBundle 集合中的警告消息的关键字。

抛出：

IllegalArgumentException - 如果 baseName 为 null。

IllegalArgumentException - 如果 keyword 为 null。

IllegalArgumentException - 如果无法定位合适的 ResourceBundle。

IllegalArgumentException - 如果在定位的 ResourceBundle 中无法找到指定的资源。

IllegalArgumentException - 如果从 ResourceBundle 中获取到的对象不是 String。

reset

public void reset()

将 ImageReader 恢复到其初始状态。

默认实现调用 setInput(null, false)、setLocale(null)、removeAllIIOReadUpdateListeners()、removeAllIIOReadWarningListeners()、removeAllIIOReadProgressListeners() 和 clearAbortRequest。

dispose

public void dispose()

允许释放此对象占用的所有资源。在调用此方法后调用其他任何方法（finalize 除外）所产生的结果都是不确定的。

应用程序在确信不再使用此 ImageReader 时，调用此方法非常重要。否则，reader 将继续无限期地占用这些资源。

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

getSourceRegion

protected static Rectangle getSourceRegion(ImageReadParam param,
                                           int srcWidth,
                                           int srcHeight)

reader 可用来计算应该读取的源图像区域的一个实用方法，计算时考虑任何源区域，并在所提供的 ImageReadParam 中对偏移量设置进行二次取样。实际二次取样因子、目标大小和目标偏移量都没有 考虑，因此必须进行进一步的裁剪。computeRegions 方法执行所有必要的裁剪。

参数：

param - 将使用的 ImageReadParam，或者为 null。

srcWidth - 源图像的宽度。

srcHeight - 源图像的高度。

返回：

Rectangle 形式的源区域。

computeRegions

protected static void computeRegions(ImageReadParam param,
                                     int srcWidth,
                                     int srcHeight,
                                     BufferedImage image,
                                     Rectangle srcRegion,
                                     Rectangle destRegion)

计算感兴趣的源区域和目标区域，将源图像的宽度和高度、可选目标图像和可选 ImageReadParam 都考虑在内。源区域从整个源图像开始。如果指定了一感兴趣的区域，则其将裁剪在 ImageReadParam 中指定的源区域。

如果任何区域的目标偏移量都为负，则裁剪源区域，使其左上部与目标图像的左上部一致，裁剪时将二次取样考虑在内。然后裁剪结果，使其与目标图像（如果指定了目标图像）右下部一致，将二次取样和目标偏移量考虑在内。

类似地，从源图像开始的目标区域被转换成 ImageReadParam 中给定的目标偏移量（如果有），并最终被裁剪成目标图像（如果有）。

如果源区域或目标区域的最终宽度或高度为 0，则抛出 IllegalArgumentException。

只有需要对源区域进行裁剪时，才能使用 getSourceRegion 方法。

参数：

param - 一个 ImageReadParam，或者为 null。

srcWidth - 源图像的宽度。

srcHeight - 源图像的高度。

image - 将成为目标图像的 BufferedImage，或者为 null。

srcRegion - 将使用感兴趣的源区域填充的 Rectangle。

destRegion - 将使用感兴趣的目标区域填充的 Rectangle。

抛出：

IllegalArgumentException - 如果 srcRegion 为 null。

IllegalArgumentException - 如果 dstRegion 为 null。

IllegalArgumentException - 如果所得到的源区域或目标区域为空。

checkReadParamBandSettings

protected static void checkReadParamBandSettings(ImageReadParam param,
                                                 int numSrcBands,
                                                 int numDstBands)

reader 可用来测试 ImageReadParam 的源和目标 band 设置的有效性的实用方法。只要 reader 一确定输入流中存在的目标图像的 band 数，以及将写入的目标图像的 band 数，就可以调用此方法。

该方法根据参数使用 getSourceBands 和 getDestinationBands 方法获取源和目标 band 设置值数组（如果 param 为 null ，则将其视为 null）。如果源 band 设置值数组为 null，则认为其等同于数组 { 0, 1, ..., numSrcBands - 1 }，对于目标 band 设置值数组情况类似。

然后该方法测试两个数组的长度是否相等，以及是否两个数组都没有包含大于最大可用 band 索引的值。

任何失败都将导致抛出 IllegalArgumentException；而成功则导致方法正常返回。

参数：

param - 将用来读取图像 ImageReadParam。

numSrcBands - 输入源中存在的图像的 band 数。

numDstBands - 将被写入的目标图像中的 band 数。

抛出：

IllegalArgumentException - 如果 param 包含源和/或目标 band 子集的无效规范。

getDestination

protected static BufferedImage getDestination(ImageReadParam param,
                                              Iterator<ImageTypeSpecifier> imageTypes,
                                              int width,
                                              int height)
                                       throws IIOException

返回应该在其中写入解码的像素数据的 BufferedImage。通过检查所提供的 ImageReadParam（如果非 null）来确定图像；如果其 getDestination 方法返回一个非 null 值，则返回该图像。否则，调用 param.getDestinationType 方法来确定是否指定了某一特定图像类型。如果已指定，则在检查其是否等于 imageTypes 中包含的类型之一后使用所返回的 ImageTypeSpecifier。

如果 param 为 null 或者上述步骤没有生成一幅图像或 ImageTypeSpecifier，则使用从 imageTypes 参数获得的第一个值。通常，调用者会将 imageTypes 设置为 getImageTypes(imageIndex) 的值。

接下来，通过调用 computeRegions 确定图像的维数。将被解码的图像的实际宽度和高度以 width 和 height 参数的形式传入。

参数：

param - 将用来获得目标图像或图像类型的 ImageReadParam，或者为 null。

imageTypes - 指示合法图像类型的 ImageTypeSpecifier 的 Iterator（默认类型最先使用）。

width - 开始解码的图像或 tile 的实际宽度。

height - 开始解码的图像或 tile 的实际高度。

返回：

应该在其中写入解码的像素数据的 BufferedImage。

抛出：

IIOException - 如果由 param 指定的 ImageTypeSpecifier 与来自 imageTypes 的任何合法类型不匹配。

IllegalArgumentException - 如果 imageTypes 为 null 或空，或者从中获取到的对象类型不是 ImageTypeSpecifier。

IllegalArgumentException - 如果得到的图像宽度或高度小于 1。

IllegalArgumentException - 如果 width 和 height 的值大于 Integer.MAX_VALUE。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。