javax.imageio
類別 ImageReadParam

java.lang.Object
  javax.imageio.IIOParam
      javax.imageio.ImageReadParam

直接已知子類別：

JPEGImageReadParam

public class ImageReadParam
extends IIOParam

描述如何對串流進行解碼的類別。此類別的實例或其子類別用於提供 ImageReader 實例的規定“入門”資訊。

編碼為檔案或串流的一部分的圖像可以被認為是向多維擴展的：寬度和高度的空間維數、band 的數量以及逐步解碼傳遞。此類別允許選中所有這些維數中的圖像的相鄰（不相鄰）矩形子區域來進行解碼。此外，可以不連續地對空間維數進行二次取樣。最後，顏色和格式轉換可以通過控制目標圖像的 ColorModel 和 SampleModel 來指定，或者通過提供 BufferedImage 或使用 ImageTypeSpecifier 來指定。

ImageReadParam 物件用於指定如何在輸入時從 Java Image I/O 框架的上下文中的串流轉換一幅圖像或一組圖像。用於特定圖像格式的外掛程式將從其 ImageReader 實作的 getDefaultReadParam 方法中返回 ImageReadParam 的實例。

由 ImageReadParam 實例維護的狀態與將被解碼的任何特定圖像無關。在進行實際解碼時，read 參數中設置的值與將解碼的圖像的實際屬性組合在一起，這些屬性來自將接收解碼像素資料的串流和目標 BufferedImage。例如，使用 setSourceRegion 設置的源區域將首先與實際有效源區域相交。結果將由 getDestinationOffset 返回的值轉換，得到的矩形與實際有效目標區域相交，從而產生將被寫入的目標區域。

由 ImageReadParam 指定的參數將被應用於圖像，如下所示。首先，如果已經通過 setSourceRenderSize 設置呈現大小，則整個解碼圖像將按 getSourceRenderSize 給出的大小來呈現。否則，圖像的實際大小將由 ImageReader.getWidth 和 ImageReader.getHeight 給定。

接下來，將根據 getSourceXOffset、getSourceYOffset、getSourceWidth 和 getSourceHeight 指定的源區域裁剪圖像。

然後根據 IIOParam.setSourceSubsampling 中給出的因子對得到的區域進行二次取樣。第一個像素、每一行的像素數和行數都取決於二次取樣設置值。調用所得矩形的最小 X 和 Y 坐標 (minX, minY)、其寬度 w 及其高度 h。

將此矩形偏移 (getDestinationOffset().x, getDestinationOffset().y)，並根據目標邊界進行裁剪。如果沒有設置目標圖像，則定義目標圖像的寬度為 getDestinationOffset().x + w，高度為 getDestinationOffset().y + h，以便源區域的所有像素都可以寫入目標區域中。

二次取樣之後放入目標圖像中的像素以及寫入由 getSourceMinProgressivePass 和 getSourceNumProgressivePasses 指定的某一逐步傳遞中的那些像素都傳遞給下一步驟。

最後，根據 setDestinationBands 的註釋中描述的演算法，將每個像素的源樣本映射到目標 band。

外掛程式 writer 可以通過提供實作額外的、特定於外掛程式的介面來擴展 ImageReadParam 的功能。由外掛程式負責記錄哪些介面可用以及如何使用。reader 將安靜地忽略所有其未知的 ImageReadParam 子類別擴展功能。此外，將忽略通常在通過 getDefaultReadParam 創建自己的 ImageReadParam 實例時禁用的所有可選功能。

注意，如果不存在針對某一功能的查詢方法，所有 ImageReader 實作就必須都支持該功能（例如，源呈現大小是可選的，但二次取樣必須受支持）。

另請參見：

ImageReader, ImageWriter, ImageWriteParam

欄位摘要

protected boolean	canSetSourceRenderSize 如果此 ImageReadParam 允許設置源呈現維數，則為 true。
protected BufferedImage	destination 當前目標 BufferedImage；如果沒有設置目標圖像，則為 null。
protected int[]	destinationBands 要使用的目標 band 集合（int 陣列的形式）。
protected int	minProgressivePass 從源中讀取的逐步傳遞的最小索引。
protected int	numProgressivePasses 從源中讀取的逐步傳遞的最大數量。
protected Dimension	sourceRenderSize 如果 canSetSourceRenderSize 為 true，則為源的所需呈現寬度和高度；或者為 null。

從類別 javax.imageio.IIOParam 繼承的欄位

controller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, subsamplingYOffset

建構子摘要

ImageReadParam()
建構一個 ImageReadParam。

方法摘要

boolean	canSetSourceRenderSize() 如果此 reader 允許通過使用 setSourceRenderSize 方法以任意大小將源圖像呈現為解碼過程的一部分，則返回 true。
BufferedImage	getDestination() 返回當前由 setDestination 方法設置的 BufferedImage，如果沒有設置，則返回 null。
int[]	getDestinationBands() 返回 band 索引的集合，資料將置於該集合中。
int	getSourceMaxProgressivePass() 如果 getSourceNumProgressivePasses 等於 Integer.MAX_VALUE，則返回 Integer.MAX_VALUE。
int	getSourceMinProgressivePass() 返回將被解碼的第一個逐步傳遞的索引。
int	getSourceNumProgressivePasses() 返回將被解碼的逐步傳遞的數量。
Dimension	getSourceRenderSize() 返回解碼期間將呈現的源圖像的寬度和高度，如果已經通過 setSourceRenderSize 方法設置了的話。
void	setDestination(BufferedImage destination) 提供一個 BufferedImage，將其用作解碼像素資料的目標。
void	setDestinationBands(int[] destinationBands) 設置將在其中放置資料的目標 band 的索引。
void	setDestinationType(ImageTypeSpecifier destinationType) 使用 ImageTypeSpecifier 設置目標圖像的所需圖像型別。
void	setSourceProgressivePasses(int minPass, int numPasses) 設置將被解碼的逐步傳遞的範圍。
void	setSourceRenderSize(Dimension size) 如果能夠以任意大小呈現圖像，則將源寬度和高度設置為所提供的值。

從類別 javax.imageio.IIOParam 繼承的方法

activateController, getController, getDefaultController, getDestinationOffset, getDestinationType, getSourceBands, getSourceRegion, getSourceXSubsampling, getSourceYSubsampling, getSubsamplingXOffset, getSubsamplingYOffset, hasController, setController, setDestinationOffset, setSourceBands, setSourceRegion, setSourceSubsampling

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

欄位詳細資訊

canSetSourceRenderSize

protected boolean canSetSourceRenderSize

如果此 ImageReadParam 允許設置源呈現維數，則為 true。預設情況下，該值為 false。子類別必須手工設置此值。

不支持設置源呈現大小的 ImageReader 應該將該值設置為 false。

sourceRenderSize

protected Dimension sourceRenderSize

如果 canSetSourceRenderSize 為 true，則為源的所需呈現寬度和高度；或者為 null。

不支持設置源呈現大小的 ImageReader 可以忽略此值。

destination

protected BufferedImage destination

當前目標 BufferedImage；如果沒有設置目標圖像，則為 null。預設情況下，該值為 null。

destinationBands

protected int[] destinationBands

要使用的目標 band 集合（int 陣列的形式）。預設情況下，該值為 null，指示應該按順序寫入的所有目標 band。

minProgressivePass

protected int minProgressivePass

從源中讀取的逐步傳遞的最小索引。預設情況下，該值被設置為 0，指示應該解碼從第一個可用傳遞開始的傳遞。

子類別應該確保此值為非負。

numProgressivePasses

protected int numProgressivePasses

從源中讀取的逐步傳遞的最大數量。預設情況下，該值被設置為 Integer.MAX_VALUE，指示應該解碼直至最後一個可用傳遞（包括）的傳遞。

子類別應該確保此值為正數。此外，如果該值不是 Integer.MAX_VALUE，則 minProgressivePass + numProgressivePasses - 1 不應該超過 Integer.MAX_VALUE。

建構子詳細資訊

ImageReadParam

public ImageReadParam()

建構一個 ImageReadParam。

方法詳細資訊

setDestinationType

public void setDestinationType(ImageTypeSpecifier destinationType)

從類別 IIOParam 複製的描述

使用 ImageTypeSpecifier 設置目標圖像的所需圖像型別。

在讀取時，如果已經使用此方法設置目標區域的佈局，則每次調用 ImageReader 的 read 方法都將返回一個新的 BufferedImage，它使用由所提供的型別說明符指定的格式。此方法的一個副作用是，任何由 ImageReadParam.setDestination(BufferedImage) 設置的目標 BufferedImage 將不再被設置為目標。換句話說，在調用 setDestination((BufferedImage)null) 時可以考慮此方法。

在寫入時，或許會使用目標型別確定圖像的顏色型別。SampleModel 資訊將被忽略，其可以為 null。例如，一個 4 band 的圖像可以表示 CMYK 或 RGBA 資料。如果設置了目標型別，則其 ColorModel 將覆寫該圖像自身的所有 ColorModel。這在使用 setSourceBands 時極其重要，因為該圖像的 ColorModel 將參考整個圖像，而不是被寫入的 band 的子集。

覆寫：

類別 IIOParam 中的 setDestinationType

參數：

destinationType - 用來確定目標佈局和顏色型別的 ImageTypeSpecifier。

另請參見：

IIOParam.getDestinationType()

setDestination

public void setDestination(BufferedImage destination)

提供一個 BufferedImage，將其用作解碼像素資料的目標。當前設置的圖像將由 read、readAll 和 readRaster 方法寫入，對該圖像的參考將由這些方法返回。

來自上述那些方法的像素資料將從 getDestinationOffset 指定的偏移量開始寫入。

如果 destination 為 null，則新創建的 BufferedImage 將由這些方法返回。

在讀取時，檢查該圖像來驗證其 ColorModel 和 SampleModel 是否對應於從 ImageReader 的 getImageTypes 方法返回的 ImageTypeSpecifier 之一。如果不對應，則 reader 將拋出 IIOException。

參數：

destination - 要寫入資料的 BufferedImage，或者為 null。

另請參見：

getDestination()

getDestination

public BufferedImage getDestination()

返回當前由 setDestination 方法設置的 BufferedImage，如果沒有設置，則返回 null。

返回：

要寫入資料的 BufferedImage。

另請參見：

setDestination(java.awt.image.BufferedImage)

setDestinationBands

public void setDestinationBands(int[] destinationBands)

設置將在其中放置資料的目標 band 的索引。索引不能重複。

null 值指示所有目標 band 都將被使用。

如果沒有指定目標圖像，選擇目標 band 子集不會影響某一讀取操作的輸出圖像中的 band 數；所創建的目標圖像仍然擁有相同的 band 數，就像從未調用此方法一樣。如果需要目標圖像中不同數量的 band，則必須使用 ImageReadParam.setDestination 方法提供一幅圖像。

在讀取或寫入時，如果指定了大於最大目標 band 索引的值，或者要使用的源 band 的數量和目標 band 的數量不同，則 reader 或 writer 將拋出 IllegalArgumentException。可以使用 ImageReader.checkReadParamBandSettings 方法自動進行此測試。

參數：

destinationBands - 將要使用的整數 band 索引組成的陣列。

拋出：

IllegalArgumentException - 如果 destinationBands 套件含一個負數或重複的值。

另請參見：

getDestinationBands(), IIOParam.getSourceBands(), ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int)

getDestinationBands

public int[] getDestinationBands()

返回 band 索引的集合，資料將置於該集合中。如果沒有設置任何值，則返回 null，指示將使用所有目標 band。

返回：

要使用的目標 band 的索引；或者 null。

另請參見：

setDestinationBands(int[])

canSetSourceRenderSize

public boolean canSetSourceRenderSize()

如果此 reader 允許通過使用 setSourceRenderSize 方法以任意大小將源圖像呈現為解碼過程的一部分，則返回 true。如果此方法返回 false，那麼調用 setSourceRenderSize 將拋出 UnsupportedOperationException。

返回：

如果支持設置源呈現大小，則返回 true。

另請參見：

setSourceRenderSize(java.awt.Dimension)

setSourceRenderSize

public void setSourceRenderSize(Dimension size)
                         throws UnsupportedOperationException

如果能夠以任意大小呈現圖像，則將源寬度和高度設置為所提供的值。注意，從 ImageReader 上的 getWidth 和 getHeight 方法返回的值不受此方法的影響；它們將繼續返回圖像的預設大小。類似地，如果圖像被平鋪，那麼平鋪寬度和高度也是根據預設大小給出的。

通常應該選定寬度和高度，使寬度與高度的比率接近近似的圖像高寬比（從 ImageReader.getAspectRatio 中返回）。

如果此外掛程式不允許設置呈現大小，則拋出 UnsupportedOperationException。

要移除呈現大小設置值，為 size 傳入一個 null 值。

參數：

size - 指示所需寬度和高度 Dimension。

拋出：

IllegalArgumentException - 如果寬度或高度為負數或 0。

UnsupportedOperationException - 如果此外掛程式不支持重新設置圖像大小。

另請參見：

getSourceRenderSize(), ImageReader.getWidth(int), ImageReader.getHeight(int), ImageReader.getAspectRatio(int)

getSourceRenderSize

public Dimension getSourceRenderSize()

返回解碼期間將呈現的源圖像的寬度和高度，如果已經通過 setSourceRenderSize 方法設置了的話。null 值指示沒有進行設置。

返回：

源圖像的呈現寬度和高度（Dimension 的形式）。

另請參見：

setSourceRenderSize(java.awt.Dimension)

setSourceProgressivePasses

public void setSourceProgressivePasses(int minPass,
                                       int numPasses)

設置將被解碼的逐步傳遞的範圍。此範圍之外的傳遞將被忽略。

逐步傳遞是整個圖像的重新編碼，通常以逐步變高的有效分辨率進行，但要求有更高的傳輸帶寬。最常使用的逐步編碼是以 JPEG 格式進行的，其中連續的傳遞包括高頻圖像內容的更詳細的表示形式。

將被解碼的傳遞的實際數量是在解碼期間根據串流中可用的實際傳遞數來確定的。因此，如果 minPass + numPasses - 1 大於最後一個可用傳遞的索引，則解碼將在該傳遞結束。

Integer.MAX_VALUE 的值為 numPasses 指示應該讀取從 minPass 開始的所有傳遞。否則，最後一個傳遞的索引（即 minPass + numPasses - 1）一定不能超過 Integer.MAX_VALUE。

如果沒有 unsetSourceProgressivePasses 方法，通過調用 setSourceProgressivePasses(0, Integer.MAX_VALUE) 可以達到相同的效果。

參數：

minPass - 要解碼的第一個傳遞的索引。

numPasses - 要解碼的傳遞的最大數量。

拋出：

IllegalArgumentException - 如果 minPass 為負數，numPasses 為負數或 0，或者 numPasses 小於 Integer.MAX_VALUE，但 minPass + numPasses - 1 大於 INTEGER.MAX_VALUE。

另請參見：

getSourceMinProgressivePass(), getSourceMaxProgressivePass()

getSourceMinProgressivePass

public int getSourceMinProgressivePass()

返回將被解碼的第一個逐步傳遞的索引。如果沒有設置任何值，則返回 0（此為修正值）。

返回：

將被解碼的第一個傳遞的索引。

另請參見：

setSourceProgressivePasses(int, int), getSourceNumProgressivePasses()

getSourceMaxProgressivePass

public int getSourceMaxProgressivePass()

如果 getSourceNumProgressivePasses 等於 Integer.MAX_VALUE，則返回 Integer.MAX_VALUE。否則返回 getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1。

返回：

將被讀取的最後一個傳遞的索引；或者 Integer.MAX_VALUE。

getSourceNumProgressivePasses

public int getSourceNumProgressivePasses()

返回將被解碼的逐步傳遞的數量。如果沒有設置任何值，則返回 Integer.MAX_VALUE（此為修正值）。

返回：

將被解碼的傳遞的數量。

另請參見：

setSourceProgressivePasses(int, int), getSourceMinProgressivePass()