|
JavaTM Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
java.lang.Object javax.imageio.ImageReader
public abstract class ImageReader
用来解析和解码图像的抽象超类。在 Java Image I/O 框架的上下文中读入图像的类必须创建此类的子类。
ImageReader
对象通常由特定格式的服务提供者接口 (SPI) 类实例化。服务提供者类(例如 ImageReaderSpi
的实例)向 IIORegistry
注册,后者使用前者进行格式识别和表示可用格式 reader 和 writer。
在设置输入源时(使用 setInput
方法),可以将它标记为“只向前搜索”。此设置意味着包含在输入源中的图像将只按顺序读取,可能允许 reader 避免缓存包含与以前已经读取的图像关联的数据的那些输入部分。
ImageWriter
,
IIORegistry
,
ImageReaderSpi
字段摘要 | |
---|---|
protected Locale[] |
availableLocales 可以用来本地化警告消息的 Locale 组成的数组,如果不支持本地化,则为 null 。 |
protected boolean |
ignoreMetadata 如果当前输入源已经被 setInput 标记为允许忽略元数据,则为 true 。 |
protected Object |
input 由 setInput 设置并由 getInput 获取的 ImageInputStream 或其他 Object 。 |
protected Locale |
locale 用于本地化的当前 Locale ,如果没有设置,则为 null 。 |
protected int |
minIndex 用来读取的最小有效索引,最初为 0。 |
protected ImageReaderSpi |
originatingProvider 实例化此对象的 ImageReaderSpi ,如果其身份未知或不存在,则为 null 。 |
protected List<IIOReadProgressListener> |
progressListeners 当前已注册 IIOReadProgressListener 组成的 List ,默认情况下初始化为 null ,它与空 List 同义。 |
protected boolean |
seekForwardOnly 如果当前输入源已经被 setInput 标记为允许只向前搜索,则为 true 。 |
protected List<IIOReadUpdateListener> |
updateListeners 当前已注册 IIOReadUpdateListener 组成的 List ,默认情况下初始化为 null ,它与空 List 同义。 |
protected List<IIOReadWarningListener> |
warningListeners 当前已注册 IIOReadWarningListener 组成的 List ,默认情况下初始化为 null ,它与空 List 同义。 |
protected List<Locale> |
warningLocales 与每个当前已注册 IIOReadWarningListener 关联的 Locale 组成的 List ,默认情况下初始化为 null ,它与空 List 同义。 |
构造方法摘要 | |
---|---|
protected |
ImageReader(ImageReaderSpi originatingProvider) 构造一个 ImageReader ,并将其 originatingProvider 字段设置为所提供的值。 |
方法摘要 | |
---|---|
void |
abort() 请求中止当前所有读取操作。 |
protected boolean |
abortRequested() 如果从实例化 reader 或调用 clearAbortRequest 时起,已经请求了中止当前读取操作,则返回 true 。 |
void |
addIIOReadProgressListener(IIOReadProgressListener listener) 将 IIOReadProgressListener 添加到已注册的进度侦听器列表中。 |
void |
addIIOReadUpdateListener(IIOReadUpdateListener listener) 将 IIOReadUpdateListener 添加到已注册的更新侦听器列表中。 |
void |
addIIOReadWarningListener(IIOReadWarningListener listener) 将 IIOReadWarningListener 添加到已注册的警告侦听器的列表中。 |
boolean |
canReadRaster() 如果此插件支持只读取像素数据的 ,则返回 true 。 |
protected static void |
checkReadParamBandSettings(ImageReadParam param, int numSrcBands, int numDstBands) reader 可用来测试 ImageReadParam 的源和目标 band 设置的有效性的实用方法。 |
protected void |
clearAbortRequest() 清除任何以前的中止请求。 |
protected static void |
computeRegions(ImageReadParam param, int srcWidth, int srcHeight, BufferedImage image, Rectangle srcRegion, Rectangle destRegion) 计算感兴趣的源区域和目标区域,将源图像的宽度和高度、可选目标图像和可选 ImageReadParam 都考虑在内。 |
void |
dispose() 允许释放此对象占用的所有资源。 |
float |
getAspectRatio(int imageIndex) 以 float 的形式返回给定图像的高宽比(即宽度除以高度)。 |
Locale[] |
getAvailableLocales() 返回可用来初始化警告侦听器和压缩设置值的 Locale 所组成的数组。 |
ImageReadParam |
getDefaultReadParam() 返回一个适合此格式的默认 ImageReadParam 对象。 |
protected static BufferedImage |
getDestination(ImageReadParam param, Iterator<ImageTypeSpecifier> imageTypes, int width, int height) 返回应该在其中写入解码的像素数据的 BufferedImage 。 |
String |
getFormatName() 返回一个标识输入源格式的 String 。 |
abstract int |
getHeight(int imageIndex) 返回输入源中的给定图像的高度,以像素为单位。 |
abstract IIOMetadata |
getImageMetadata(int imageIndex) 返回包含与给定图像关联的元数据的 IIOMetadata 对象,如果 reader 不支持读取元数据、被设置为忽略元数据,或者没有元数据可用,则返回 null 。 |
IIOMetadata |
getImageMetadata(int imageIndex, String formatName, Set<String> nodeNames) 返回表示与给定图像关联的元数据的 IIOMetadata 对象,如果 reader 不支持读取元数据或者没有元数据可用,则返回 null 。 |
abstract Iterator<ImageTypeSpecifier> |
getImageTypes(int imageIndex) 以 ImageTypeSpecifier 形式返回包含可能的图像类型的 Iterator ,给定图像可能被解码成这些类型。 |
Object |
getInput() 返回以前设置为输入源的 ImageInputStream 或其他 Object 。 |
Locale |
getLocale() 返回当前设置的 Locale ,如果没有设置 Locale,则返回 null 。 |
int |
getMinIndex() 返回用于读取图像、缩略图或图像元数据的最低有效索引。 |
abstract int |
getNumImages(boolean allowSearch) 返回当前输入源中可用的图像数,不包括缩略图。 |
int |
getNumThumbnails(int imageIndex) 返回与给定图像关联的缩略图预览图像的数量。 |
ImageReaderSpi |
getOriginatingProvider() 返回传入构造方法的 ImageReaderSpi 。 |
ImageTypeSpecifier |
getRawImageType(int imageIndex) 返回一个 ImageTypeSpecifier ,指示最能代表图像“原始”内部格式的 SampleModel 和 ColorModel 。 |
protected static Rectangle |
getSourceRegion(ImageReadParam param, int srcWidth, int srcHeight) reader 可用来计算应该读取的源图像区域的一个实用方法,计算时考虑任何源区域,并在所提供的 ImageReadParam 中对偏移量设置进行二次取样。 |
abstract IIOMetadata |
getStreamMetadata() 返回一个 IIOMetadata 对象,它表示作为一个整体与输入源关联的元数据(即不与任何特定图像关联);如果 reader 不支持读取元数据、被设置为忽略元数据,或者没有元数据可用,则返回 null 。 |
IIOMetadata |
getStreamMetadata(String formatName, Set<String> nodeNames) 返回一个 IIOMetadata 对象,它表示作为一个整体与输入源关联的元数据(即不与任何特定图像关联)。 |
int |
getThumbnailHeight(int imageIndex, int thumbnailIndex) 返回通过索引 thumbnailIndex 指定的缩略图预览图像的高度,其与通过索引 ImageIndex 指定的图像关联。 |
int |
getThumbnailWidth(int imageIndex, int thumbnailIndex) 返回通过索引 thumbnailIndex 指定的缩略图预览图像的宽度,其与通过索引 ImageIndex 指定的图像关联。 |
int |
getTileGridXOffset(int imageIndex) 返回给定图像中 tile (0, 0) 的左上角的 X 坐标。 |
int |
getTileGridYOffset(int imageIndex) 返回给定图像中 tile (0, 0) 的左上角的 Y 坐标。 |
int |
getTileHeight(int imageIndex) 返回给定图像中 tile 的高度。 |
int |
getTileWidth(int imageIndex) 返回给定图像中 tile 的宽度。 |
abstract int |
getWidth(int imageIndex) 返回输入源中的给定图像的宽度,以像素为单位。 |
boolean |
hasThumbnails(int imageIndex) 如果给定图像具有与之关联的缩略图预览图像,则返回 true 。 |
boolean |
isIgnoringMetadata() 如果已经通过传递 true 作为 setInput 方法的 ignoreMetadata 参数将当前输入源标记为允许忽略元数据,则返回 true 。 |
boolean |
isImageTiled(int imageIndex) 如果图像被组织成 tile(即等大小的非重叠矩形),则返回 true 。 |
boolean |
isRandomAccessEasy(int imageIndex) 如果给定图像的存储格式不会给像素的随机访问带来内在妨碍,则返回 true 。 |
boolean |
isSeekForwardOnly() 如果已经通过传递 true 作为 setInput 方法的 seekForwardOnly 参数将当前输入源标记为只向前搜索,则返回 true 。 |
protected void |
processImageComplete() 通过调用所有已注册 IIOReadProgressListener 的 imageComplete 方法向其广播图像读取的完成。 |
protected void |
processImageProgress(float percentageDone) 通过调用所有已注册 IIOReadProgressListener 的 imageProgress 方法向其广播图像完成的当前百分比。 |
protected void |
processImageStarted(int imageIndex) 通过调用所有已注册 IIOReadProgressListener 的 imageStarted 方法向其广播图像读取起始处。 |
protected void |
processImageUpdate(BufferedImage theImage, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands) 通过调用所有已注册 IIOReadUpdateListener 的 imageUpdate 方法向其广播样本集合的更新。 |
protected void |
processPassComplete(BufferedImage theImage) 通过调用所有已注册 IIOReadUpdateListener 的 passComplete 方法向其广播逐步传递的结束。 |
protected void |
processPassStarted(BufferedImage theImage, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands) 通过调用所有已注册 IIOReadUpdateListener 的 passStarted 方法向其广播逐步传递的开始。 |
protected void |
processReadAborted() 通过调用所有已注册 IIOReadProgressListener 的 readAborted 方法向其广播读取已经中止。 |
protected void |
processSequenceComplete() 通过调用所有已注册 IIOReadProgressListener 的 sequenceComplete 方法向其广播图像读取序列的完成。 |
protected void |
processSequenceStarted(int minIndex) 通过调用所有已注册 IIOReadProgressListener 的 sequenceStarted 方法向其广播图像读取序列的起始处。 |
protected void |
processThumbnailComplete() 通过调用所有已注册 IIOReadProgressListener 的 thumbnailComplete 方法向其广播缩略图读取的完成。 |
protected void |
processThumbnailPassComplete(BufferedImage theThumbnail) 通过调用所有已注册 IIOReadUpdateListener 的 thumbnailPassComplete 方法向其广播缩略图逐步传递的结束。 |
protected void |
processThumbnailPassStarted(BufferedImage theThumbnail, int pass, int minPass, int maxPass, int minX, int minY, int periodX, int periodY, int[] bands) 通过调用所有已注册 IIOReadUpdateListener 的 thumbnailPassStarted 方法向其广播缩略图逐步传递的开始。 |
protected void |
processThumbnailProgress(float percentageDone) 通过调用所有已注册 IIOReadProgressListener 的 thumbnailProgress 方法向其广播缩略图完成的当前百分比。 |
protected void |
processThumbnailStarted(int imageIndex, int thumbnailIndex) 通过调用所有已注册 IIOReadProgressListener 的 thumbnailStarted 方法向其广播缩略图读取的起始处。 |
protected void |
processThumbnailUpdate(BufferedImage theThumbnail, int minX, int minY, int width, int height, int periodX, int periodY, int[] bands) 通过调用所有已注册 IIOReadUpdateListener 的 thumbnailUpdate 方法向其广播缩略图图像中样本集合的更新。 |
protected void |
processWarningOccurred(String warning) 通过调用所有已注册 IIOReadWarningListener 的 warningOccurred 方法向其广播警告消息。 |
protected void |
processWarningOccurred(String baseName, String keyword) 通过使用取自 ResourceBundle 的字符串调用所有已注册 IIOReadWarningListener 的 warningOccurred 方法向其广播本地化警告消息。 |
BufferedImage |
read(int imageIndex) 使用默认 ImageReadParam 读取通过索引 imageIndex 指定的图像,并将其作为一个完整的 BufferedImage 返回。 |
abstract BufferedImage |
read(int imageIndex, ImageReadParam param) 使用所提供的 ImageReadParam 读取通过索引 imageIndex 指定的对象,并将它作为一个完整的 BufferedImage 返回。 |
IIOImage |
readAll(int imageIndex, ImageReadParam param) 使用所提供的 ImageReadParam 读取通过索引 imageIndex 指定的图像,并返回包含图像、缩略图和相关图像元数据的 IIOImage 。 |
Iterator<IIOImage> |
readAll(Iterator<? extends ImageReadParam> params) 以 IIOImage 对象形式返回包含输入源中所有图像、缩略图和元数据的 Iterator ,从 getMinIndex 给定的索引开始。 |
RenderedImage |
readAsRenderedImage(int imageIndex, ImageReadParam param) 返回一个 RenderedImage 对象,该对象包含通过索引 imageIndex 指定的图像的内容。 |
boolean |
readerSupportsThumbnails() 如果此 reader 所理解的图像格式支持与之关联的缩略图预览图像,则返回 true 。 |
Raster |
readRaster(int imageIndex, ImageReadParam param) 返回包含图像流中原始像素数据的新 Raster 对象,不应用任何颜色转换。 |
BufferedImage |
readThumbnail(int imageIndex, int thumbnailIndex) 以 BufferedImage 形式返回通过索引 thumbnailIndex 指定的缩略图预览图像,其与通过索引 ImageIndex 指定的图像关联。 |
BufferedImage |
readTile(int imageIndex, int tileX, int tileY) 读取由 tileX 和 tileY 参数指示的 tile,并以 BufferedImage 形式返回。 |
Raster |
readTileRaster(int imageIndex, int tileX, int tileY) 返回包含 tile 中的原始像素数据的新 Raster 对象,不应用任何颜色转换。 |
void |
removeAllIIOReadProgressListeners() 移除所有当前已注册的 IIOReadProgressListener 对象。 |
void |
removeAllIIOReadUpdateListeners() 移除所有当前已注册的 IIOReadUpdateListener 对象。 |
void |
removeAllIIOReadWarningListeners() 移除所有当前已注册的 IIOReadWarningListener 对象。 |
void |
removeIIOReadProgressListener(IIOReadProgressListener listener) 从已注册的进度侦听器列表中移除 IIOReadProgressListener 。 |
void |
removeIIOReadUpdateListener(IIOReadUpdateListener listener) 从已注册的更新侦听器列表中移除 IIOReadUpdateListener 。 |
void |
removeIIOReadWarningListener(IIOReadWarningListener listener) 从已注册的错误侦听器列表中移除 IIOReadWarningListener 。 |
void |
reset() 将 ImageReader 恢复到其初始状态。 |
void |
setInput(Object input) 设置用于给定的 ImageInputStream 或其他 Object 的输入源。 |
void |
setInput(Object input, boolean seekForwardOnly) 设置用于给定的 ImageInputStream 或其他 Object 的输入源。 |
void |
setInput(Object input, boolean seekForwardOnly, boolean ignoreMetadata) 设置用于给定的 ImageInputStream 或其他 Object 的输入源。 |
void |
setLocale(Locale locale) 将此 ImageReader 的当前 Locale 设置为给定值。 |
从类 java.lang.Object 继承的方法 |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
字段详细信息 |
---|
protected ImageReaderSpi originatingProvider
ImageReaderSpi
,如果其身份未知或不存在,则为
null
。默认情况下初始化为
null
。
protected Object input
setInput
设置并由
getInput
获取的
ImageInputStream
或其他
Object
。默认情况下初始化为
null
。
protected boolean seekForwardOnly
setInput
标记为允许只向前搜索,则为
true
。默认情况下,该值为
false
。
minIndex
,
setInput(java.lang.Object, boolean, boolean)
protected boolean ignoreMetadata
setInput
标记为允许忽略元数据,则为
true
。默认情况下,该值为
false
。
setInput(java.lang.Object, boolean, boolean)
protected int minIndex
seekForwardOnly
为
true
,各种方法在试图访问与拥有更低索引的图像关联的数据时将抛出
IndexOutOfBoundsException
。
seekForwardOnly
,
setInput(java.lang.Object, boolean, boolean)
protected Locale[] availableLocales
Locale
组成的数组,如果不支持本地化,则为
null
。
protected Locale locale
Locale
,如果没有设置,则为
null
。
protected List<IIOReadWarningListener> warningListeners
IIOReadWarningListener
组成的
List
,默认情况下初始化为
null
,它与空
List
同义。
protected List<Locale> warningLocales
IIOReadWarningListener
关联的
Locale
组成的
List
,默认情况下初始化为
null
,它与空
List
同义。
protected List<IIOReadProgressListener> progressListeners
IIOReadProgressListener
组成的
List
,默认情况下初始化为
null
,它与空
List
同义。
protected List<IIOReadUpdateListener> updateListeners
IIOReadUpdateListener
组成的
List
,默认情况下初始化为
null
,它与空
List
同义。
构造方法详细信息 |
---|
protected ImageReader(ImageReaderSpi originatingProvider)
ImageReader
,并将其
originatingProvider
字段设置为所提供的值。
利用扩展的子类应该为提供具有签名 (ImageReaderSpi, Object)
的构造方法来获取扩展对象。如果扩展对象不合适,则将抛出 IllegalArgumentException
。
originatingProvider
- 调用此构造方法的
ImageReaderSpi
,或者为
null
。
方法详细信息 |
---|
public String getFormatName() throws IOException
String
。
默认实现返回 originatingProvider.getFormatNames()[0]
。没有原始服务提供者的实现或者希望使用不同命名策略的实现应该重写此方法。
String
形式的格式名称。
IOException
- 如果从输入源中读取信息时发生错误。
public ImageReaderSpi getOriginatingProvider()
ImageReaderSpi
。注意,此值可能为
null
。
ImageReaderSpi
或
null
。
ImageReaderSpi
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()
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()
public void setInput(Object input)
ImageInputStream
或其他
Object
的输入源。输入源必须在使用任何查询或读取方法之前设置。如果
input
为
null
,则将移除所有当前设置的输入源。无论是哪种情况,
minIndex
的值都将被初始化为 0。
此方法等效于 setInput(input, false, false)
。
input
- 将来解码时用到的
ImageInputStream
或其他
Object
。
IllegalArgumentException
- 如果
input
不是原始服务提供者的
getInputTypes
方法返回的某个类的实例,或者不是一个
ImageInputStream
。
getInput()
public Object getInput()
ImageInputStream
或其他
Object
。如果没有设置输入源,则返回
null
。
Object
;或者
null
。
ImageInputStream
,
setInput(java.lang.Object, boolean, boolean)
public boolean isSeekForwardOnly()
true
作为
setInput
方法的
seekForwardOnly
参数将当前输入源标记为只向前搜索,则返回
true
。
true
。
setInput(java.lang.Object, boolean, boolean)
public boolean isIgnoringMetadata()
true
作为
setInput
方法的
ignoreMetadata
参数将当前输入源标记为允许忽略元数据,则返回
true
。
true
。
setInput(java.lang.Object, boolean, boolean)
public int getMinIndex()
seekForwardOnly()
为
false
,此值通常仍然为 0,指示可能进行随机访问。否则,它将包含最近一次访问的索引值,并单调递增。
public Locale[] getAvailableLocales()
Locale
所组成的数组。返回
null
值指示不支持本地化。
如果 availableLocales
实例变量是非 null
的,则默认实现返回该变量的副本,否则返回 null
。
setLocale
的参数的
Locale
所组成的数组,或者返回
null
。
public void setLocale(Locale locale)
ImageReader
的当前
Locale
设置为给定值。值为
null
则移除所有以前的设置值,并指示 reader 应该根据需要对其进行本地化。
locale
- 所需的
Locale
,或者为
null
。
IllegalArgumentException
- 如果
locale
为非
null
,但它不是
getAvailableLocales
返回的值之一。
getLocale()
public Locale getLocale()
Locale
,如果没有设置 Locale,则返回
null
。
Locale
或
null
。
setLocale(java.util.Locale)
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)
public abstract int getWidth(int imageIndex) throws IOException
如果可以将图像呈现为用户指定大小,则此方法将返回默认宽度。
imageIndex
- 要查询的图像的索引。
int
形式的图像宽度。
IllegalStateException
- 如果尚未设置输入源。
IndexOutOfBoundsException
- 如果所提供的索引超出范围。
IOException
- 如果从输入源中读取宽度信息时发生错误。
public abstract int getHeight(int imageIndex) throws IOException
如果可以将图像呈现为用户指定大小,则此方法将返回默认高度。
imageIndex
- 要查询的图像的索引。
int
形式的图像高度。
IllegalStateException
- 如果尚未设置输入源。
IndexOutOfBoundsException
- 如果所提供的索引超出范围。
IOException
- 如果从输入源中读取高度信息时发生错误。
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
- 如果在读取过程中发生错误。
public float getAspectRatio(int imageIndex) throws IOException
float
的形式返回给定图像的高宽比(即宽度除以高度)。对于本来就可以调整大小的图像,此方法提供了一个在已知所需高度的情况下确定适当宽度的方法,反之亦然。对于不可调整大小的图像,则使用真实宽度和高度。
默认实现只是返回 (float)getWidth(imageIndex)/getHeight(imageIndex)
。
imageIndex
- 要查询的图像的索引。
float
值。
IllegalStateException
- 如果尚未设置输入源。
IndexOutOfBoundsException
- 如果所提供的索引超出范围。
IOException
- 如果在读取过程中发生错误。
public ImageTypeSpecifier getRawImageType(int imageIndex) throws IOException
ImageTypeSpecifier
,指示最能代表图像“原始”内部格式的
SampleModel
和
ColorModel
。例如,对于 JPEG 图像,原始类型可能有一个 YCbCr 颜色空间,即使该图像在显示之前会按照惯例被转换为一个 RGB 颜色空间。返回值还应该包含在
getImageTypes
返回的值所组成的列表中。
默认实现只返回 getImageType
所提供列表中的第一项。
imageIndex
- 要查询的图像的索引。
ImageTypeSpecifier
。
IllegalStateException
- 如果尚未设置输入源。
IndexOutOfBoundsException
- 如果所提供的索引超出范围。
IOException
- 如果从输入源中读取格式信息时发生错误。
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)
public ImageReadParam getDefaultReadParam()
ImageReadParam
对象。所有子类都应该定义一个用于所有参数的默认值集合,并使用此调用返回这些值。可以在设置输入源之前调用此方法。
默认实现构造并返回一个新的 ImageReadParam
对象,该对象不允许源进行缩放(也就是说,它返回 new ImageReadParam()
)。
ImageReadParam
对象。
public abstract IIOMetadata getStreamMetadata() throws IOException
IIOMetadata
对象,它表示作为一个整体与输入源关联的元数据(即不与任何特定图像关联);如果 reader 不支持读取元数据、被设置为忽略元数据,或者没有元数据可用,则返回
null
。
IIOMetadata
对象或者
null
。
IOException
- 如果在读取过程中发生错误。
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
- 如果在读取过程中发生错误。
public abstract IIOMetadata getImageMetadata(int imageIndex) throws IOException
IIOMetadata
对象,如果 reader 不支持读取元数据、被设置为忽略元数据,或者没有元数据可用,则返回
null
。
imageIndex
- 其元数据将被获取的图像的索引。
IIOMetadata
对象或者
null
。
IllegalStateException
- 如果尚未设置输入源。
IndexOutOfBoundsException
- 如果所提供的索引超出范围。
IOException
- 如果在读取过程中发生错误。
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
- 如果在读取过程中发生错误。
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
- 如果在读取过程中发生错误。
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
- 如果读取期间发生错误。
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
- 如果读取期间发生错误。
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
public boolean canReadRaster()
Raster
,则返回
true
。如果此方法返回
false
,则调用
readRaster
或
readTileRaster
将抛出
UnsupportedOperationException
。
默认实现返回 false
。
Raster
,则返回
true
。
readRaster(int, javax.imageio.ImageReadParam)
,
readTileRaster(int, int, int)
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
public boolean isImageTiled(int imageIndex) throws IOException
true
。
reader 插件可以选择是否将图像中出现的 tiling 按其存储时的原样公开。甚至可以选择图像中没有显式存在 tiling 时公开 tiling。通常,只有在对访问单独的 tile 有利(在速度或空间方面)时才应该公开 tiling。不管 reader 是否公开 tiling,它必须能够读取 ImageReadParam
中指定的任意矩形区域。
对于可以保证所有平铺所有图像或者不平铺图像的 reader,分别返回 true
或 false
,而不必访问任何图像数据。在这种情况下,即使输入源没有设置或者图像索引超出范围,也未必抛出异常。
默认实现返回 false
。
imageIndex
- 要查询的图像的索引。
true
。
IllegalStateException
- 如果需要输入源来确定返回值,但没有设置输入源。
IndexOutOfBoundsException
- 如果必须访问某一图像来确定返回值,但所提供的索引超出范围。
IOException
- 如果在读取过程中发生错误。
public int getTileWidth(int imageIndex) throws IOException
默认实现返回 getWidth(imageIndex)
,对于非平铺图像也是如此。支持 tiling 的 reader 应该重写此方法。
imageIndex
- 要查询的图像的索引。
IllegalStateException
- 如果尚未设置输入源。
IndexOutOfBoundsException
- 如果所提供的索引超出范围。
IOException
- 如果在读取过程中发生错误。
public int getTileHeight(int imageIndex) throws IOException
默认实现返回 getHeight(imageIndex)
,对于非平铺图像也是如此。支持 tiling 的 reader 应该重写此方法。
imageIndex
- 要查询的图像的索引。
IllegalStateException
- 如果尚未设置输入源。
IndexOutOfBoundsException
- 如果所提供的索引超出范围。
IOException
- 如果在读取过程中发生错误。
public int getTileGridXOffset(int imageIndex) throws IOException
对于 tile 网格 X 偏移量总是具有相同值(通常为 0)的 reader,返回该值,而不必访问任何图像数据。在这种情况下,即使输入源没有设置或者图像索引超出范围,也未必抛出异常。
默认实现返回 0,对于大多数格式的非平铺图像和平铺图像也是如此。支持 tiling、具有非 (0, 0) 偏移量的 reader 应该重写此方法。
imageIndex
- 要查询的图像的索引。
IllegalStateException
- 如果需要输入源来确定返回值,但没有设置输入源。
IndexOutOfBoundsException
- 如果必须访问某一图像来确定返回值,但所提供的索引超出范围。
IOException
- 如果在读取过程中发生错误。
public int getTileGridYOffset(int imageIndex) throws IOException
对于 tile 网格 Y 偏移量总是具有相同值(通常为 0)的 reader,返回该值,而不必访问任何图像数据。在这种情况下,即使输入源没有设置或者图像索引超出范围,也未必抛出异常。
默认实现返回 0,对于大多数格式的非平铺图像和平铺图像也是如此。支持 tiling、具有非 (0, 0) 偏移量的 reader 应该重写此方法。
imageIndex
- 要查询的图像的索引。
IllegalStateException
- 如果需要输入源来确定返回值,但没有设置输入源。
IndexOutOfBoundsException
- 如果必须访问某一图像来确定返回值,但所提供的索引超出范围。
IOException
- 如果在读取过程中发生错误。
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
- 如果在读取过程中发生错误。
public Raster readTileRaster(int imageIndex, int tileX, int tileY) throws IOException
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
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
- 如果读取期间发生错误。
public boolean readerSupportsThumbnails()
true
。默认实现返回
false
。
如果此方法返回 false
,hasThumbnails
和 getNumThumbnails
将分别返回 false
和 0
,而 readThumbnail
将抛出 UnsupportedOperationException
(不管其参数如何)。
不支持缩略图的 reader 不需要实现任何与缩略图有关的方法。
true
。
public boolean hasThumbnails(int imageIndex) throws IOException
true
。如果该格式不支持缩略图(
readerSupportsThumbnails
返回
false
),则无论是否已经设置了输入源或者
imageIndex
是否在范围内,其都将将返回
false
。
默认实现在 getNumThumbnails
的返回值大于 0 的情况下返回 true
。
imageIndex
- 要查询的图像的索引。
true
。
IllegalStateException
- 如果 reader 支持缩略图但尚未设置输入源。
IndexOutOfBoundsException
- 如果 reader 支持缩略图但
imageIndex
超出范围。
IOException
- 如果在读取过程中发生错误。
public int getNumThumbnails(int imageIndex) throws IOException
readerSupportsThumbnails
返回
false
),则无论是否已经设置了输入源或者
imageIndex
是否在范围内,其都将将返回
0
。
默认实现返回 0,不检查其参数。
imageIndex
- 要查询的图像的索引。
IllegalStateException
- 如果 reader 支持缩略图但尚未设置输入源。
IndexOutOfBoundsException
- 如果 reader 支持缩略图但
imageIndex
超出范围。
IOException
- 如果在读取过程中发生错误。
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
- 如果在读取过程中发生错误。
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
- 如果在读取过程中发生错误。
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
- 如果在读取过程中发生错误。
public void abort()
reader 应该在开始每个读取操作时调用 clearAbortRequest
,并在读取期间定期轮询 abortRequested
的值。
protected boolean abortRequested()
clearAbortRequest
时起,已经请求了中止当前读取操作,则返回
true
。
true
。
abort()
,
clearAbortRequest()
protected void clearAbortRequest()
abortRequested
将返回
false
。
abort()
,
abortRequested()
public void addIIOReadWarningListener(IIOReadWarningListener listener)
IIOReadWarningListener
添加到已注册的警告侦听器的列表中。如果
listener
为
null
,则不会抛出任何异常并且不执行任何操作。将本地化发送到给定侦听器的消息(如果可能)以匹配当前
Locale
。如果没有设置
Locale
,则可将警告消息本地化为适合 reader 的形式。
listener
- 要注册的
IIOReadWarningListener
。
removeIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener)
public void removeIIOReadWarningListener(IIOReadWarningListener listener)
IIOReadWarningListener
。如果以前没有注册侦听器,或者
listener
为
null
,则不会抛出任何异常并且不执行任何操作。
listener
- 要取消注册的 IIOReadWarningListener。
addIIOReadWarningListener(javax.imageio.event.IIOReadWarningListener)
public void removeAllIIOReadWarningListeners()
IIOReadWarningListener
对象。
默认实现将 warningListeners
和 warningLocales
实例变量设置为 null
。
public void addIIOReadProgressListener(IIOReadProgressListener listener)
IIOReadProgressListener
添加到已注册的进度侦听器列表中。如果
listener
为
null
,则不会抛出任何异常并且不执行任何操作。
listener
- 要注册的 IIOReadProgressListener。
removeIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener)
public void removeIIOReadProgressListener(IIOReadProgressListener listener)
IIOReadProgressListener
。如果以前没有注册侦听器,或者
listener
为
null
,则不会抛出任何异常并且不执行任何操作。
listener
- 要取消注册的 IIOReadProgressListener。
addIIOReadProgressListener(javax.imageio.event.IIOReadProgressListener)
public void removeAllIIOReadProgressListeners()
IIOReadProgressListener
对象。
默认实现将 progressListeners
实例变量设置为 null
。
public void addIIOReadUpdateListener(IIOReadUpdateListener listener)
IIOReadUpdateListener
添加到已注册的更新侦听器列表中。如果
listener
为
null
,则不会抛出任何异常并且不执行任何操作。在解码图像和缩略图时,侦听器将接收像素更新的通知,该通知中包括逐步传递的起始处和结束处。
如果不存在更新侦听器,则 reader 可以选择对目标图像和/或缩略图的像素执行较少的更新,这能促使更加有效的解码。
例如,在逐步 JPEG 解码过程中,每个传递都包含对一个系数集合的更新数据,如果侦听器存在,则必须将这些系数变换成像素值并转换为用于每个传递的 RGB 颜色空间。如果不存在侦听器,则可以累计这些系数,并只变换最终结果和转换颜色一次。
无论是否执行中间的更新,解码的最终结果都相同。因此,如果只需要最终图像,则最好不注册任何 IIOReadUpdateListener
。通常,在通过与本地 CPU 处理相比非常慢的网络连接获取图像时,逐步更新是最有效的;而通过快速连接时,逐步更新实际上会降低图像的显示速度。
listener
- 要注册的 IIOReadUpdateListener。
removeIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener)
public void removeIIOReadUpdateListener(IIOReadUpdateListener listener)
IIOReadUpdateListener
。如果以前没有注册侦听器,或者
listener
为
null
,则不会抛出任何异常并且不执行任何操作。
listener
- 要取消注册的 IIOReadUpdateListener。
addIIOReadUpdateListener(javax.imageio.event.IIOReadUpdateListener)
public void removeAllIIOReadUpdateListeners()
IIOReadUpdateListener
对象。
默认实现将 updateListeners
实例变量设置为 null
。
protected void processSequenceStarted(int minIndex)
IIOReadProgressListener
的
sequenceStarted
方法向其广播图像读取序列的起始处。子类可以将此方法用作一个便捷方法。
minIndex
- 将读取的最低索引。
protected void processSequenceComplete()
IIOReadProgressListener
的
sequenceComplete
方法向其广播图像读取序列的完成。子类可以将此方法用作一个便捷方法。
protected void processImageStarted(int imageIndex)
IIOReadProgressListener
的
imageStarted
方法向其广播图像读取起始处。子类可以将此方法用作一个便捷方法。
imageIndex
- 即将读取的图像的索引。
protected void processImageProgress(float percentageDone)
IIOReadProgressListener
的
imageProgress
方法向其广播图像完成的当前百分比。子类可以将此方法用作一个便捷方法。
percentageDone
-
float
值形式的当前完成百分比。
protected void processImageComplete()
IIOReadProgressListener
的
imageComplete
方法向其广播图像读取的完成。子类可以将此方法用作一个便捷方法。
protected void processThumbnailStarted(int imageIndex, int thumbnailIndex)
IIOReadProgressListener
的
thumbnailStarted
方法向其广播缩略图读取的起始处。子类可以将此方法用作一个便捷方法。
imageIndex
- 与该缩略图关联的图像的索引。
thumbnailIndex
- 缩略图的索引。
protected void processThumbnailProgress(float percentageDone)
IIOReadProgressListener
的
thumbnailProgress
方法向其广播缩略图完成的当前百分比。子类可以将此方法用作一个便捷方法。
percentageDone
-
float
值形式的当前完成百分比。
protected void processThumbnailComplete()
IIOReadProgressListener
的
thumbnailComplete
方法向其广播缩略图读取的完成。子类可以将此方法用作一个便捷方法。
protected void processReadAborted()
IIOReadProgressListener
的
readAborted
方法向其广播读取已经中止。子类可以将此方法用作一个便捷方法。
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
数组。
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
数组。
protected void processPassComplete(BufferedImage theImage)
IIOReadUpdateListener
的
passComplete
方法向其广播逐步传递的结束。子类可以将此方法用作一个便捷方法。
theImage
- 将被更新的
BufferedImage
。
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
数组。
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
数组。
protected void processThumbnailPassComplete(BufferedImage theThumbnail)
IIOReadUpdateListener
的
thumbnailPassComplete
方法向其广播缩略图逐步传递的结束。子类可以将此方法用作一个便捷方法。
theThumbnail
- 将被更新的
BufferedImage
缩略图。
protected void processWarningOccurred(String warning)
IIOReadWarningListener
的
warningOccurred
方法向其广播警告消息。子类可以将此方法用作一个便捷方法。
warning
- 要发送的警告消息。
IllegalArgumentException
- 如果
warning
为
null
。
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
。
public void reset()
ImageReader
恢复到其初始状态。
默认实现调用 setInput(null, false)
、setLocale(null)
、removeAllIIOReadUpdateListeners()
、removeAllIIOReadWarningListeners()
、removeAllIIOReadProgressListeners()
和 clearAbortRequest
。
public void dispose()
finalize
除外)所产生的结果都是不确定的。
应用程序在确信不再使用此 ImageReader
时,调用此方法非常重要。否则,reader 将继续无限期地占用这些资源。
在超类中,此方法的默认实现不执行任何操作。子类实现应该确保所有资源(特别是本机资源)被释放。
protected static Rectangle getSourceRegion(ImageReadParam param, int srcWidth, int srcHeight)
ImageReadParam
中对偏移量设置进行二次取样。实际二次取样因子、目标大小和目标偏移量都
没有 考虑,因此必须进行进一步的裁剪。
computeRegions
方法执行所有必要的裁剪。
param
- 将使用的
ImageReadParam
,或者为
null
。
srcWidth
- 源图像的宽度。
srcHeight
- 源图像的高度。
Rectangle
形式的源区域。
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
- 如果所得到的源区域或目标区域为空。
protected static void checkReadParamBandSettings(ImageReadParam param, int numSrcBands, int numDstBands)
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 子集的无效规范。
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
。
|
JavaTM Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。