java.lang.Object javax.imageio.IIOParam
public abstract class IIOParam
所有描述应该如何对流进行编码和解码的类的超类。此类包含由 ImageReadParam
和 ImageWriteParam
共享的所有变量和方法。
此类提供指定源区域和目标区域的机制。在进行读取操作时,源区域是流,内存储图像是目标区域。进行写入操作时则正好相反。在进行写入时,目标区域只能伴随支持像素替换的 writer 使用。
使用可移动的二次取样网格,可以为 reader 和 writer 指定抽取十分之一的二次取样。
可以选定源 band 和目标 band 的子集。
字段摘要 | |
---|---|
protected IIOParamController |
controller 调用 activateController 方法时,将用来为此 IIOParam 对象提供设置值的 IIOParamController 。 |
protected IIOParamController |
defaultController 调用 activateController 方法时,将用来为此 IIOParam 对象提供设置值的默认 IIOParamController 。 |
protected Point |
destinationOffset 目标区域中的偏移量,应将左上部解码像素置于此处。 |
protected ImageTypeSpecifier |
destinationType 一个 ImageTypeSpecifier ,用来在进行读取操作时生成目标图像,或者在进行写入操作时设置输出颜色类型。 |
protected int[] |
sourceBands 指示将使用的源 band 的 int 数组,或为 null 。 |
protected Rectangle |
sourceRegion 源区域;如果没有设置源区域,则为 null 。 |
protected int |
sourceXSubsampling 在水平方向应用抽取十分之一的二次取样。 |
protected int |
sourceYSubsampling 在垂直方向应用抽取十分之一的二次取样。 |
protected int |
subsamplingXOffset 在进行二次取样之前,将水平偏移量应用于二次取样网格。 |
protected int |
subsamplingYOffset 在进行二次取样之前,将垂直偏移量应用于二次取样网格。 |
构造方法摘要 | |
---|---|
protected |
IIOParam() 受保护的构造方法,只能由子类调用。 |
方法摘要 | |
---|---|
boolean |
activateController() 激活为此 IIOParam 对象安装的 IIOParamController ,并返回得到的值。 |
IIOParamController |
getController() 返回当前已安装的所有 IIOParamController 。 |
IIOParamController |
getDefaultController() 返回默认 IIOParamController (如果有),不考虑当前安装的控制器。 |
Point |
getDestinationOffset() 返回目标图像中的偏移量,像素将置于该处。 |
ImageTypeSpecifier |
getDestinationType() 以 ImageTypeSpecifier 的形式返回将由读取操作返回的图像类型,如果通过调用 setDestination(ImageTypeSpecifier) 设置了类型的话。 |
int[] |
getSourceBands() 返回要使用的源 band 的集合。 |
Rectangle |
getSourceRegion() 返回将使用的源区域。 |
int |
getSourceXSubsampling() 返回对于每个像素要前进的源列数。 |
int |
getSourceYSubsampling() 返回对于每个像素要前进的行数。 |
int |
getSubsamplingXOffset() 返回二次取样网格的水平偏移量。 |
int |
getSubsamplingYOffset() 返回二次取样网格的垂直偏移量。 |
boolean |
hasController() 如果有一个为此 IIOParam 对象安装的控制器,则返回 true 。 |
void |
setController(IIOParamController controller) 设置在调用 activateController 方法时用来为 IIOParam 对象提供设置值的 IIOParamController ,重写所有默认控制器。 |
void |
setDestinationOffset(Point destinationOffset) 指定目标图像中的偏移量。 |
void |
setDestinationType(ImageTypeSpecifier destinationType) 使用 ImageTypeSpecifier 设置目标图像的所需图像类型。 |
void |
setSourceBands(int[] sourceBands) 设置将要使用的源 band 的索引。 |
void |
setSourceRegion(Rectangle sourceRegion) 设置感兴趣的源区域。 |
void |
setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset) 指定进行 I/O 时应用的抽取十分之一的二次取样。 |
从类 java.lang.Object 继承的方法 |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
字段详细信息 |
---|
protected Rectangle sourceRegion
null
。
protected int sourceXSubsampling
1
。该值一定不能为负数或 0。
protected int sourceYSubsampling
1
。该值一定不能为负数或 0。
protected int subsamplingXOffset
protected int subsamplingYOffset
protected int[] sourceBands
int
数组,或为
null
。如果为
null
,则将使用的源 band 集合如
setSourceBands
方法的注释所述。不允许任何为负。
protected ImageTypeSpecifier destinationType
ImageTypeSpecifier
,用来在进行读取操作时生成目标图像,或者在进行写入操作时设置输出颜色类型。如果没有设置,则该值将为
null
。默认情况下,该值为
null
。
protected Point destinationOffset
protected IIOParamController defaultController
activateController
方法时,将用来为此
IIOParam
对象提供设置值的默认
IIOParamController
。此默认控制器应该由子类设置,这些子类可以选择提供自己的默认控制器(通常是一个 GUI)来设置参数。
protected IIOParamController controller
activateController
方法时,将用来为此
IIOParam
对象提供设置值的
IIOParamController
。此值重写任何默认控制器,即使为 null 时也是如此。
构造方法详细信息 |
---|
protected IIOParam()
方法详细信息 |
---|
public void setSourceRegion(Rectangle sourceRegion)
setSourceSubsampling
设置的二次取样因子。如果已经在二次取样中将此像素数设置为零,则将抛出
IllegalStateException
。
将根据需要限制此方法指定的感兴趣的源区域,使其适合源区域边界,以及在实际 I/O 时符合目标偏移量、宽度和高度。
sourceRegion
值为 null
表示将取消所有区域限制,这将导致使用整个图像。
sourceRegion
- 指定感兴趣的源区域的
Rectangle
;或为
null
。
IllegalArgumentException
- 如果
sourceRegion
不为
null
且
sourceRegion.x
或
sourceRegion.y
为负。
IllegalArgumentException
- 如果
sourceRegion
不为
null
且
sourceRegion.width
或
sourceRegion.height
为负数或 0。
IllegalStateException
- 如果二次取样将使此区域有一个为零的二次取样宽度或高度。
getSourceRegion()
,
setSourceSubsampling(int, int, int, int)
,
setDestinationOffset(java.awt.Point)
,
getDestinationOffset()
public Rectangle getSourceRegion()
setSourceRegion
设置的值,如果没有设置区域,则返回值将为
null
。
Rectangle
形式的感兴趣源区域;或者
null
。
setSourceRegion(java.awt.Rectangle)
public void setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling, int subsamplingXOffset, int subsamplingYOffset)
sourceXSubsampling
和
sourceYSubsampling
参数指定二次取样的周期(
即 每个源像素之后前进的行数和列数)。具体地说,周期为 1 将对每行或每列使用二次取样;周期为 2 则每隔一行或一列使用。
subsamplingXOffset
和
subsamplingYOffset
参数指定距离第一个二次取样像素的区域(或图像)原点的偏移量。在将一个非常大的源图像二次取样到将组合成一个完整的二次取样图像的目标区域中时,调整二次取样网格的原点对避免裂缝很有用。大多数用户只要让这些参数为 0 即可。
要使用的像素行和扫描行数量的计算如下所示。
扫描行中二次取样像素数的计算方式如下
truncate[(width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling]
。
如果在该区域中此宽度为零,则抛出 IllegalStateException
。
可以用类似的方法计算要使用的扫描行数。
可以将二次取样网格设置为从源区域原点以外的其他某个地方开始,如果正使用源区域创建大型图像的二次取样 tile,其中 tile 的宽度和高度不是二次取样周期的倍数,这将非常有用。如果在二次取样网格中不能使 tile 保持一致,则在 tile 的边界上会出现某些误差产物。通过调整每个 tile 的二次取样网格偏移量来校正,可避免这些误差产物。权宜之计是,为了避免出现误差产物,tile 的大小并不都是相同的。在这种情况下使用的网格偏移量的计算方式如下:
grid offset = [period - (region offset modulo period)] modulo period)
如果 sourceXSubsampling
或 sourceYSubsampling
为 0 或负数,则将抛出 IllegalArgumentException
。
如果 subsamplingXOffset
或 subsamplingYOffset
为负数或大于等于相应的周期,则将抛出 IllegalArgumentException
。
没有 unsetSourceSubsampling
方法;调用 setSourceSubsampling(1, 1, 0, 0)
来恢复默认值即可。
sourceXSubsampling
- 要在像素之间前进的列数。
sourceYSubsampling
- 要在像素之间前进的行数。
subsamplingXOffset
- 该区域或图像(如果没有设置区域)中第一次二次取样的水平偏移量。
subsamplingYOffset
- 该区域或图像(如果没有设置区域)中第一次二次取样的水平偏移量。
IllegalArgumentException
- 如果任意一个周期为负数或 0,或者任意一个网格偏移量为负数或大于相应的周期。
IllegalStateException
- 如果源区域中二次取样输出不包含任何像素。
public int getSourceXSubsampling()
如果尚未调用 setSourceSubsampling
,则返回 1(此为修正值)。
setSourceSubsampling(int, int, int, int)
,
getSourceYSubsampling()
public int getSourceYSubsampling()
如果尚未调用 setSourceSubsampling
,则返回 1(此为修正值)。
setSourceSubsampling(int, int, int, int)
,
getSourceXSubsampling()
public int getSubsamplingXOffset()
如果尚未调用 setSourceSubsampling
,则返回 0(此为修正值)。
setSourceSubsampling(int, int, int, int)
,
getSubsamplingYOffset()
public int getSubsamplingYOffset()
如果尚未调用 setSourceSubsampling
,则返回 0(此为修正值)。
setSourceSubsampling(int, int, int, int)
,
getSubsamplingXOffset()
public void setSourceBands(int[] sourceBands)
null
值指示所有源 band 都将被使用。
在进行读取时,如果指定大于最大可用源 band 索引的值,或者要使用的源 band 的数量与目标 band 的数量不同,则 reader 或 writer 将抛出 IllegalArgumentException
。可以使用 ImageReader.checkReadParamBandSettings
方法自动进行此测试。
根据语义,为该数组生成一个副本;调用此方法后对数组内容进行的更改对此 IIOParam
没有影响。
sourceBands
- 将要使用的整数 band 索引组成的数组。
IllegalArgumentException
- 如果
sourceBands
包含一个负数或重复的值。
getSourceBands()
,
ImageReadParam.setDestinationBands(int[])
,
ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int)
public int[] getSourceBands()
setSourceBands
设置的值,如果没有调用过
setSourceBands
,则返回
null
。
根据语义,返回的数组是一个副本;调用此方法后对数组内容进行的更改对此 IIOParam
没有影响。
null
。
setSourceBands(int[])
public void setDestinationType(ImageTypeSpecifier destinationType)
ImageTypeSpecifier
设置目标图像的所需图像类型。
在读取时,如果已经使用此方法设置目标区域的布局,则每次调用 ImageReader
的 read
方法都将返回一个新的 BufferedImage
,它使用由所提供的类型说明符指定的格式。此方法的一个副作用是,任何由 ImageReadParam.setDestination(BufferedImage)
设置的目标 BufferedImage
将不再被设置为目标。换句话说,在调用 setDestination((BufferedImage)null)
时可以考虑此方法。
在写入时,或许会使用目标类型确定图像的颜色类型。SampleModel
信息将被忽略,其可以为 null
。例如,一个 4 band 的图像可以表示 CMYK 或 RGBA 数据。如果设置了目标类型,则其 ColorModel
将重写该图像自身的所有 ColorModel
。这在使用 setSourceBands
时极其重要,因为该图像的 ColorModel
将引用整个图像,而不是被写入的 band 的子集。
destinationType
- 用来确定目标布局和颜色类型的
ImageTypeSpecifier
。
getDestinationType()
public ImageTypeSpecifier getDestinationType()
ImageTypeSpecifier
的形式返回将由读取操作返回的图像类型,如果通过调用
setDestination(ImageTypeSpecifier)
设置了类型的话。如果没有设置类型,则返回
null
。
ImageTypeSpecifier
;或者
null
。
setDestinationType(javax.imageio.ImageTypeSpecifier)
public void setDestinationOffset(Point destinationOffset)
在读取时,写入目标 BufferedImage
中的区域将从此偏移量开始,并且其宽度和高度是通过感兴趣的源区域、二次取样参数和目标边界确定的。
普通写入操作不受此方法的影响,只有使用 ImageWriter.replacePixels
执行的写入操作会受影响。对于此类写入操作,指定的偏移量位于其像素正被修改的输出流图像中。
没有 unsetDestinationOffset
方法;调用 setDestinationOffset(new Point(0, 0))
来恢复默认值即可。
destinationOffset
- 目标中
Point
形式的偏移量。
IllegalArgumentException
- 如果
destinationOffset
为
null
。
getDestinationOffset()
,
ImageWriter.replacePixels(java.awt.image.RenderedImage, javax.imageio.ImageWriteParam)
public Point getDestinationOffset()
如果尚未调用 setDestinationOffsets
,则返回 X 和 Y 值为零的 Point
(此为修正值)。
Point
形式的目标偏移量。
setDestinationOffset(java.awt.Point)
public void setController(IIOParamController controller)
activateController
方法时用来为
IIOParam
对象提供设置值的
IIOParamController
,重写所有默认控制器。如果该参数为
null
,则不使用任何控制器,包括所有默认控制器。要恢复默认值,请使用
setController(getDefaultController())
。
controller
- 一个适当的
IIOParamController
,或者为
null
。
IIOParamController
,
getController()
,
getDefaultController()
,
hasController()
,
activateController()
public IIOParamController getController()
IIOParamController
。返回值可以是默认控制器(如果有)、
null
或最近一次调用
setController
时使用的参数。
IIOParamController
;或者
null
。
IIOParamController
,
setController(javax.imageio.IIOParamController)
,
getDefaultController()
,
hasController()
,
activateController()
public IIOParamController getDefaultController()
IIOParamController
(如果有),不考虑当前安装的控制器。如果没有默认安装器,则返回
null
。
IIOParamController
或
null
。
IIOParamController
,
setController(IIOParamController)
,
getController()
,
hasController()
,
activateController()
public boolean hasController()
IIOParam
对象安装的控制器,则返回
true
。如果
getController
不返回
null
,则此方法将返回
true
。
true
。
IIOParamController
,
setController(IIOParamController)
,
getController()
,
getDefaultController()
,
activateController()
public boolean activateController()
IIOParam
对象安装的
IIOParamController
,并返回得到的值。当此方法返回
true
时,此
IIOParam
对象的所有值都已准备好进行下一次读取或写入操作。如果返回
false
,则此对象中没有任何设置会被干扰(
也就是说,用户取消了该操作)。
通常,控制器将是一个 GUI,为特定插件的 IIOParam
的子类提供用户界面。不过,控制器不必一定是 GUI。
true
。
IllegalStateException
- 如果当前没有安装控制器。
IIOParamController
,
setController(IIOParamController)
,
getController()
,
getDefaultController()
,
hasController()