javax.imageio
類別 IIOParam

java.lang.Object
  javax.imageio.IIOParam

直接已知子類別：

ImageReadParam, ImageWriteParam

public abstract class IIOParam
extends Object

所有描述應該如何對串流進行編碼和解碼的類別的父級類別。此類別包含由 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

欄位詳細資訊

sourceRegion

protected Rectangle sourceRegion

源區域；如果沒有設置源區域，則為 null。

sourceXSubsampling

protected int sourceXSubsampling

在水平方向應用抽取十分之一的二次取樣。預設情況下，該值為 1。該值一定不能為負數或 0。

sourceYSubsampling

protected int sourceYSubsampling

在垂直方向應用抽取十分之一的二次取樣。預設情況下，該值為 1。該值一定不能為負數或 0。

subsamplingXOffset

protected int subsamplingXOffset

在進行二次取樣之前，將水平偏移量應用於二次取樣網格。要使用的第一個像素將距區域或圖像（如果沒有指定區域）的原點偏移此量。

subsamplingYOffset

protected int subsamplingYOffset

在進行二次取樣之前，將垂直偏移量應用於二次取樣網格。要使用的第一個像素將距區域或圖像（如果沒有指定區域）的起點偏移此量。

sourceBands

protected int[] sourceBands

指示將使用的源 band 的 int 陣列，或為 null。如果為 null，則將使用的源 band 集合如 setSourceBands 方法的註釋所述。不允許任何為負。

destinationType

protected ImageTypeSpecifier destinationType

一個 ImageTypeSpecifier，用來在進行讀取操作時產生目標圖像，或者在進行寫入操作時設置輸出顏色型別。如果沒有設置，則該值將為 null。預設情況下，該值為 null。

destinationOffset

protected Point destinationOffset

目標區域中的偏移量，應將左上部解碼像素置於此處。預設情況下，該值為 (0, 0)。

defaultController

protected IIOParamController defaultController

調用 activateController 方法時，將用來為此 IIOParam 物件提供設置值的預設 IIOParamController。此預設控制器應該由子類別設置，這些子類別可以選擇提供自己的預設控制器（通常是一個 GUI）來設置參數。

另請參見：

IIOParamController, getDefaultController(), activateController()

controller

protected IIOParamController controller

調用 activateController 方法時，將用來為此 IIOParam 物件提供設置值的 IIOParamController。此值覆寫任何預設控制器，即使為 null 時也是如此。

另請參見：

IIOParamController, setController(IIOParamController), hasController(), activateController()

建構子詳細資訊

IIOParam

protected IIOParam()

受保護的建構子，只能由子類別調用。

方法詳細資訊

setSourceRegion

public void setSourceRegion(Rectangle sourceRegion)

設置感興趣的源區域。感興趣的區域被描述為一個矩形，源圖像左上角為像素 (0, 0)，該值向下向右遞增。所使用的實際像素數將取決於由 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()

getSourceRegion

public Rectangle getSourceRegion()

返回將使用的源區域。返回的值是通過最近一次調用 setSourceRegion 設置的值，如果沒有設置區域，則返回值將為 null。

返回：

Rectangle 形式的感興趣源區域；或者 null。

另請參見：

setSourceRegion(java.awt.Rectangle)

setSourceSubsampling

public void setSourceSubsampling(int sourceXSubsampling,
                                 int sourceYSubsampling,
                                 int subsamplingXOffset,
                                 int subsamplingYOffset)

指定進行 I/O 時應用的抽取十分之一的二次取樣。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 - 如果源區域中二次取樣輸出不包含任何像素。

getSourceXSubsampling

public int getSourceXSubsampling()

返回對於每個像素要前進的源列數。

如果尚未調用 setSourceSubsampling，則返回 1（此為修正值）。

返回：

源二次取樣的 X 週期。

另請參見：

setSourceSubsampling(int, int, int, int), getSourceYSubsampling()

getSourceYSubsampling

public int getSourceYSubsampling()

返回對於每個像素要前進的行數。

如果尚未調用 setSourceSubsampling，則返回 1（此為修正值）。

返回：

源二次取樣的 Y 週期。

另請參見：

setSourceSubsampling(int, int, int, int), getSourceXSubsampling()

getSubsamplingXOffset

public int getSubsamplingXOffset()

返回二次取樣網格的水平偏移量。

如果尚未調用 setSourceSubsampling，則返回 0（此為修正值）。

返回：

源二次取樣網格的 X 偏移量。

另請參見：

setSourceSubsampling(int, int, int, int), getSubsamplingYOffset()

getSubsamplingYOffset

public int getSubsamplingYOffset()

返回二次取樣網格的垂直偏移量。

如果尚未調用 setSourceSubsampling，則返回 0（此為修正值）。

返回：

源二次取樣網格的 Y 偏移量。

另請參見：

setSourceSubsampling(int, int, int, int), getSubsamplingXOffset()

setSourceBands

public void setSourceBands(int[] sourceBands)

設置將要使用的源 band 的索引。索引不能重複。

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)

getSourceBands

public int[] getSourceBands()

返回要使用的源 band 的集合。返回的值是通過最近一次調用 setSourceBands 設置的值，如果沒有調用過 setSourceBands，則返回 null。

根據語義，返回的陣列是一個副本；調用此方法後對陣列內容進行的更改對此 IIOParam 沒有影響。

返回：

要使用的源 band 的集合；或者 null。

另請參見：

setSourceBands(int[])

setDestinationType

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()

getDestinationType

public ImageTypeSpecifier getDestinationType()

以 ImageTypeSpecifier 的形式返回將由讀取操作返回的圖像型別，如果通過調用 setDestination(ImageTypeSpecifier) 設置了型別的話。如果沒有設置型別，則返回 null。

返回：

描述目標型別的 ImageTypeSpecifier；或者 null。

另請參見：

setDestinationType(javax.imageio.ImageTypeSpecifier)

setDestinationOffset

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)

getDestinationOffset

public Point getDestinationOffset()

返回目標圖像中的偏移量，像素將置於該處。

如果尚未調用 setDestinationOffsets，則返回 X 和 Y 值為零的 Point（此為修正值）。

返回：

Point 形式的目標偏移量。

另請參見：

setDestinationOffset(java.awt.Point)

setController

public void setController(IIOParamController controller)

設置在調用 activateController 方法時用來為 IIOParam 物件提供設置值的 IIOParamController，覆寫所有預設控制器。如果該參數為 null，則不使用任何控制器，包括所有預設控制器。要恢復預設值，請使用 setController(getDefaultController())。

參數：

controller - 一個適當的 IIOParamController，或者為 null。

另請參見：

IIOParamController, getController(), getDefaultController(), hasController(), activateController()

getController

public IIOParamController getController()

返回當前已安裝的所有 IIOParamController。返回值可以是預設控制器（如果有）、null 或最近一次調用 setController 時使用的參數。

返回：

當前安裝的 IIOParamController；或者 null。

另請參見：

IIOParamController, setController(javax.imageio.IIOParamController), getDefaultController(), hasController(), activateController()

getDefaultController

public IIOParamController getDefaultController()

返回預設 IIOParamController（如果有），不考慮當前安裝的控制器。如果沒有預設安裝器，則返回 null。

返回：

預設 IIOParamController 或 null。

另請參見：

IIOParamController, setController(IIOParamController), getController(), hasController(), activateController()

hasController

public boolean hasController()

如果有一個為此 IIOParam 物件安裝的控制器，則返回 true。如果 getController 不返回 null，則此方法將返回 true。

返回：

如果安裝了一個控制器，則返回 true。

另請參見：

IIOParamController, setController(IIOParamController), getController(), getDefaultController(), activateController()

activateController

public boolean activateController()

啟動為此 IIOParam 物件安裝的 IIOParamController，並返回得到的值。當此方法返回 true 時，此 IIOParam 物件的所有值都已準備好進行下一次讀取或寫入操作。如果返回 false，則此物件中沒有任何設置會被干擾（也就是說，使用者取消了該操作）。

通常，控制器將是一個 GUI，為特定外掛程式的 IIOParam 的子類別提供使用者介面。不過，控制器不必一定是 GUI。

返回：

如果控制器完全正常，則返回 true。

拋出：

IllegalStateException - 如果當前沒有安裝控制器。

另請參見：

IIOParamController, setController(IIOParamController), getController(), getDefaultController(), hasController()