javax.imageio
類別 ImageWriteParam

java.lang.Object
  javax.imageio.IIOParam
      javax.imageio.ImageWriteParam

直接已知子類別：

BMPImageWriteParam, JPEGImageWriteParam

public class ImageWriteParam
extends IIOParam

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

用於特定圖像格式的外掛程式可以定義此類別的一個子類別，並從其 ImageWriter 實作的 getDefaultWriteParam 方法返回該類別的物件。例如，內置 JPEG writer 外掛程式將返回 javax.imageio.plugins.jpeg.JPEGImageWriteParam 的實例。

要寫入的圖像區域通過第一次將圖像的實際邊界與 IIOParam.setSourceRegion 指定的矩形（如果有）的相交來確定。如果所得矩形的寬度或高度為零，則該 writer 將拋出 IIOException。如果相交區域為非空(null)，則寫入操作將從第一個二次取樣的像素開始，並根據 IIOParam.setSourceSubsampling 指定的水平和垂直二次取樣因子包含相交邊界內額外的像素。

個別特徵（比如 tiling、逐步編碼和壓縮）可以用以下四種網要之一設置。MODE_DISABLED 禁用這些特徵；MODE_DEFAULT 使用帶有受控於 writer 的參數值啟用這些特徵；MODE_EXPLICIT 啟用這些特定並允許使用 set 方法提供額外的參數；MODE_COPY_FROM_METADATA 則從串流以及傳遞給 writer 的圖像元資料物件中複製相關的參數值。所有特徵的預設網要是 MODE_COPY_FROM_METADATA。鼓勵使用子類別中提供的非標準特徵，但不要求使用類似的方案。

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

注意，如果不存在針對某一功能的查詢方法，所有 ImageWriter 實作就必須都支持該功能（例如，逐步編碼是可選的，但二次取樣必須受支持）。

另請參見：

ImageReadParam

欄位摘要

protected boolean	canOffsetTiles 如果此 ImageWriteParam 允許使用 tiling 網格偏移量參數，則返回為 true 的 boolean 值。
protected boolean	canWriteCompressed 如果此 writer 可以使用壓縮寫入圖像，則返回為 true 的 boolean 值。
protected boolean	canWriteProgressive 如果此 ImageWriteParam 允許以一個質量遞增傳遞的逐步序列的方式寫入圖像，則返回為 true 的 boolean 值。
protected boolean	canWriteTiles 如果此 ImageWriteParam 允許設置 tile 的寬度和高度參數，則返回為 true 的 boolean 值。
protected int	compressionMode 控制壓縮設置的網要，必須將它設置為四個 MODE_* 值之一。
protected float	compressionQuality 包含當前壓縮質量設置的 float 值。
protected String	compressionType 包含當前壓縮型別名稱的 String，如果沒有設置壓縮型別，則返回 null。
protected String[]	compressionTypes 包含可用壓縮型別名稱的 String 陣列。
protected Locale	locale 用於本地化壓縮型別名稱和質量描述的 Locale，null 表示使用預設 Locale。
static int	MODE_COPY_FROM_METADATA 一個常數值，可以傳入諸如 setTilingMode、setProgressiveMode 或 setCompressionMode 之類別的方法中，以啟用用於以後的寫入操作的特徵。
static int	MODE_DEFAULT 一個常數值，可以傳入諸如 setTilingMode、setProgressiveMode 和 setCompressionMode 之類別的方法中，以啟用用於以後的寫入操作的特徵。
static int	MODE_DISABLED 一個常數值，可以傳入諸如 setTilingMode、setProgressiveMode 和 setCompressionMode 之類別的方法中，以禁用用於以後的寫入操作的某個特徵。
static int	MODE_EXPLICIT 一個常數值，可以傳入諸如 setTilingMode 或 setCompressionMode 之類別的方法中，以啟用用於以後的寫入操作的特徵。
protected Dimension[]	preferredTileSizes 首選 tile 大小範圍對組成的陣列。
protected int	progressiveMode 控制逐步編碼的網要，必須將它設置為除 MODE_EXPLICIT 以外的四個 MODE_* 值之一。
protected int	tileGridXOffset 如果已經設置 tiling，則返回 tile 網格原點應該從圖像原點水平偏移的量。
protected int	tileGridYOffset 如果已經設置 tiling，則返回 tile 網格原點應該從圖像原點垂直偏移的量。
protected int	tileHeight 如果已經設置 tiling，則返回每個 tile 的高度，否則返回 0。
protected int	tileWidth 如果已經設置 tiling，則返回每個 tile 的寬度，否則返回 0。
protected int	tilingMode 控制 tiling 設置的網要，必須將它設置為以下四個 MODE_* 值之一。
protected boolean	tilingSet 如果已經指定 tiling 參數，則返回一個為 true 的 boolean 值。

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

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

建構子摘要

protected	ImageWriteParam() 建構一個空的 ImageWriteParam。
	ImageWriteParam(Locale locale) 建構一個 ImageWriteParam 集，以使用給定 Locale。

方法摘要

boolean	canOffsetTiles() 如果 writer 在執行寫入操作的同時可以使用非零網格偏移量進行平鋪，則返回 true。
boolean	canWriteCompressed() 如果此 writer 支持壓縮，則返回 true。
boolean	canWriteProgressive() 如果 writer 能夠以一系列質量逐漸遞增的傳遞的方式將圖像寫出，則返回 true。
boolean	canWriteTiles() 如果 writer 在執行寫入操作的同時可以進行平鋪，則返回 true。
float	getBitRate(float quality) 返回一個 float 值，該值指示對給定質量級別上用於輸入圖像資料的每個位的輸出資料位數的估計。
int	getCompressionMode() 如果支持壓縮，則返回當前壓縮網要。
float	getCompressionQuality() 返回當前壓縮質量設置。
String[]	getCompressionQualityDescriptions() 返回一個 String 陣列，可作為使用者介面的一部分與 getCompressionQualityValues 一起使用，以設置或顯示壓縮質量級別。
float[]	getCompressionQualityValues() 返回一個 float 陣列，可作為使用者介面的一部分與 getCompressionQualityDescriptions 一起使用，以設置或顯示壓縮質量級別。
String	getCompressionType() 返回當前設置的壓縮型別，如果沒有設置任何壓縮型別，則返回 null。
String[]	getCompressionTypes() 以陣列或 String 形式返回可用壓縮型別的列表，如果不能使用這些介面選擇壓縮型別，則返回 null。
Locale	getLocale() 返回當前設置的 Locale，如果僅支持預設 Locale，則返回 null。
String	getLocalizedCompressionTypeName() 返回當前壓縮型別的本地化名稱，使用 getLocale 返回的 Locale。
Dimension[]	getPreferredTileSizes() 返回一個 Dimension 陣列，指示在輸出檔案或串流中進行編碼時 tile 的合法大小範圍。
int	getProgressiveMode() 返回以逐步方式將資料寫入串流的當前網要。
int	getTileGridXOffset() 返回圖像的水平 tile 網格偏移量，將根據該偏移量對輸出串流進行寫入。
int	getTileGridYOffset() 返回圖像的垂直 tile 網格偏移量，將根據該偏移量對輸出串流進行寫入。
int	getTileHeight() 返回圖像中每個 tile 的高度，將根據該高度對輸出串流進行寫入。
int	getTileWidth() 返回圖像中每個 tile 的寬度，將根據該寬度對輸出串流進行寫入。
int	getTilingMode() 如果支持平鋪，則返回當前平鋪網要。
boolean	isCompressionLossless() 如果當前壓縮型別提供無損失的壓縮，則返回 true。
void	setCompressionMode(int mode) 指定是否執行壓縮，如果執行壓縮，將如何確定 compression 參數。
void	setCompressionQuality(float quality) 將壓縮質量設置為 0 和 1 之間的某個值。
void	setCompressionType(String compressionType) 將壓縮型別設置為 getCompressionTypes 指示的值之一。
void	setProgressiveMode(int mode) 指定 writer 使用逐步網要寫出圖像，從而輸出串流將包含一系列質量遞增的掃瞄。
void	setTiling(int tileWidth, int tileHeight, int tileGridXOffset, int tileGridYOffset) 指定應該在輸出串流中平鋪圖像。
void	setTilingMode(int mode) 確定圖像在輸出串流中是否將被平鋪，如果將被平鋪，將如何確定 tiling 參數。
void	unsetCompression() 移除所有以前的壓縮型別和質量設置。
void	unsetTiling() 移除通過調用 setTiling 指定的所有以前的 tile 網格參數。

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

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

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

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

欄位詳細資訊

MODE_DISABLED

public static final int MODE_DISABLED

一個常數值，可以傳入諸如 setTilingMode、setProgressiveMode 和 setCompressionMode 之類別的方法中，以禁用用於以後的寫入操作的某個特徵。也就是說，在設置此網要時，該串流將不被平鋪、逐步編碼或壓縮，相關的存取器方法將拋出 IllegalStateException。

另請參見：

MODE_EXPLICIT, MODE_COPY_FROM_METADATA, MODE_DEFAULT, setProgressiveMode(int), getProgressiveMode(), setTilingMode(int), getTilingMode(), setCompressionMode(int), getCompressionMode(), 常數欄位值

MODE_DEFAULT

public static final int MODE_DEFAULT

一個常數值，可以傳入諸如 setTilingMode、setProgressiveMode 和 setCompressionMode 之類別的方法中，以啟用用於以後的寫入操作的特徵。也就是說，在啟用此網要時，將根據 writer 以與外掛程式有關的方式內部選擇的明智預設值來平鋪、逐步編碼和壓縮該串流，相關的存取器方法將拋出 IllegalStateException。

另請參見：

MODE_DISABLED, MODE_EXPLICIT, MODE_COPY_FROM_METADATA, setProgressiveMode(int), getProgressiveMode(), setTilingMode(int), getTilingMode(), setCompressionMode(int), getCompressionMode(), 常數欄位值

MODE_EXPLICIT

public static final int MODE_EXPLICIT

一個常數值，可以傳入諸如 setTilingMode 或 setCompressionMode 之類別的方法中，以啟用用於以後的寫入操作的特徵。也就是說，在設置此網要時，將根據為此類別中的相應 set 方法提供的額外資訊和可以從相應 get 方法中獲取到的資訊來平鋪或壓縮該串流。注意，此網要不支持逐步輸出。

另請參見：

MODE_DISABLED, MODE_COPY_FROM_METADATA, MODE_DEFAULT, setProgressiveMode(int), getProgressiveMode(), setTilingMode(int), getTilingMode(), setCompressionMode(int), getCompressionMode(), 常數欄位值

MODE_COPY_FROM_METADATA

public static final int MODE_COPY_FROM_METADATA

一個常數值，可以傳入諸如 setTilingMode、setProgressiveMode 或 setCompressionMode 之類別的方法中，以啟用用於以後的寫入操作的特徵。也就是說，在啟用此網要時，將根據傳入寫入操作的串流內容和/或圖像元資料來平鋪、逐步編碼和壓縮該串流，所有相關存取器方法都將拋出 IllegalStateException。

這是所有特徵的預設網要，因此，如果一個套件括元資料的讀取操作之後將進行包括元資料的寫入操作，則讀取操作將保留盡可能多的資訊。

另請參見：

MODE_DISABLED, MODE_EXPLICIT, MODE_DEFAULT, setProgressiveMode(int), getProgressiveMode(), setTilingMode(int), getTilingMode(), setCompressionMode(int), getCompressionMode(), 常數欄位值

canWriteTiles

protected boolean canWriteTiles

如果此 ImageWriteParam 允許設置 tile 的寬度和高度參數，則返回為 true 的 boolean 值。預設情況下，該值為 false。子類別必須手工設置該值。

不支持寫入 tile 的子類別應該確保此值被設置為 false。

tilingMode

protected int tilingMode

控制 tiling 設置的網要，必須將它設置為以下四個 MODE_* 值之一。預設值為 MODE_COPY_FROM_METADATA。

不支持寫入 tile 的子類別可以忽略此值。

另請參見：

MODE_DISABLED, MODE_EXPLICIT, MODE_COPY_FROM_METADATA, MODE_DEFAULT, setTilingMode(int), getTilingMode()

preferredTileSizes

protected Dimension[] preferredTileSizes

首選 tile 大小範圍對組成的陣列。預設值為 null，指示沒有首選大小。如果該值為非 null 值，則首選大小的平均長度必須至少為 2。

不支持寫入 tile 的子類別可以忽略此值。

另請參見：

getPreferredTileSizes()

tilingSet

protected boolean tilingSet

如果已經指定 tiling 參數，則返回一個為 true 的 boolean 值。

不支持寫入 tile 的子類別可以忽略此值。

tileWidth

protected int tileWidth

如果已經設置 tiling，則返回每個 tile 的寬度，否則返回 0。

不支持 tiling 的子類別可以忽略此值。

tileHeight

protected int tileHeight

如果已經設置 tiling，則返回每個 tile 的高度，否則返回 0。初始值為 0。

不支持 tiling 的子類別可以忽略此值。

canOffsetTiles

protected boolean canOffsetTiles

如果此 ImageWriteParam 允許使用 tiling 網格偏移量參數，則返回為 true 的 boolean 值。預設情況下，該值為 false。子類別必須手工設置該值。

不支持寫入 tile 的子類別或支持寫入 tile 但不支持將 tile 偏移的子類別必須確保此值被設置為 false。

tileGridXOffset

protected int tileGridXOffset

如果已經設置 tiling，則返回 tile 網格原點應該從圖像原點水平偏移的量。否則返回 0。初始值為 0。

不支持將 tile 偏移的子類別可以忽略此值。

tileGridYOffset

protected int tileGridYOffset

如果已經設置 tiling，則返回 tile 網格原點應該從圖像原點垂直偏移的量。否則返回 0。初始值為 0。

不支持將 tile 偏移的子類別可以忽略此值。

canWriteProgressive

protected boolean canWriteProgressive

如果此 ImageWriteParam 允許以一個質量遞增傳遞的逐步序列的方式寫入圖像，則返回為 true 的 boolean 值。預設情況下，該值為 false。子類別必須手工設置該值。

不支持逐步編碼的子類別必須確保此值被設置為 false。

progressiveMode

protected int progressiveMode

控制逐步編碼的網要，必須將它設置為除 MODE_EXPLICIT 以外的四個 MODE_* 值之一。預設值為 MODE_COPY_FROM_METADATA。

不支持逐步編碼的子類別可以忽略此值。

另請參見：

MODE_DISABLED, MODE_EXPLICIT, MODE_COPY_FROM_METADATA, MODE_DEFAULT, setProgressiveMode(int), getProgressiveMode()

canWriteCompressed

protected boolean canWriteCompressed

如果此 writer 可以使用壓縮寫入圖像，則返回為 true 的 boolean 值。預設情況下，該值為 false。子類別必須手工設置該值。

不支持壓縮的子類別必須確保此值被設置為 false。

compressionMode

protected int compressionMode

控制壓縮設置的網要，必須將它設置為四個 MODE_* 值之一。預設值為 MODE_COPY_FROM_METADATA。

不支持壓縮的子類別可以忽略此值。

另請參見：

MODE_DISABLED, MODE_EXPLICIT, MODE_COPY_FROM_METADATA, MODE_DEFAULT, setCompressionMode(int), getCompressionMode()

compressionTypes

protected String[] compressionTypes

包含可用壓縮型別名稱的 String 陣列。子類別必須手工設置該值。

不支持壓縮的子類別可以忽略此值。

compressionType

protected String compressionType

包含當前壓縮型別名稱的 String，如果沒有設置壓縮型別，則返回 null。

不支持壓縮的子類別可以忽略此值。

compressionQuality

protected float compressionQuality

包含當前壓縮質量設置的 float 值。初始值為 1.0F。

不支持壓縮的子類別可以忽略此值。

locale

protected Locale locale

用於本地化壓縮型別名稱和質量描述的 Locale，null 表示使用預設 Locale。子類別必須手工設置該值。

建構子詳細資訊

ImageWriteParam

protected ImageWriteParam()

建構一個空的 ImageWriteParam。由子類別負責恰當地設置實例變數。

ImageWriteParam

public ImageWriteParam(Locale locale)

建構一個 ImageWriteParam 集，以使用給定 Locale。

參數：

locale - 將用於本地化壓縮型別名稱和質量描述的 Locale，或者為 null。

方法詳細資訊

getLocale

public Locale getLocale()

返回當前設置的 Locale，如果僅支持預設 Locale，則返回 null。

返回：

當前 Locale 或 null。

canWriteTiles

public boolean canWriteTiles()

如果 writer 在執行寫入操作的同時可以進行平鋪，則返回 true。如果此方法返回 false，則 setTiling 將拋出 UnsupportedOperationException。

返回：

如果 writer 支持平鋪，則返回 true。

另請參見：

canOffsetTiles(), setTiling(int, int, int, int)

canOffsetTiles

public boolean canOffsetTiles()

如果 writer 在執行寫入操作的同時可以使用非零網格偏移量進行平鋪，則返回 true。如果此方法返回 false，則 setTiling 將拋出 UnsupportedOperationException，如果網格偏移量參數不同時為零的話。如果 canWriteTiles 返回 false，則此方法也將返回 false。

返回：

如果 writer 支持非零 tile 偏移量，則返回 true。

另請參見：

canWriteTiles(), setTiling(int, int, int, int)

setTilingMode

public void setTilingMode(int mode)

確定圖像在輸出串流中是否將被平鋪，如果將被平鋪，將如何確定 tiling 參數。對這些網要的解釋如下：

• MODE_DISABLED - 圖像不會被平鋪，setTiling 將拋出 IllegalStateException。
• MODE_DEFAULT - 將使用預設參數平鋪圖像。setTiling 將拋出 IllegalStateException。
• MODE_EXPLICIT - 將根據 setTiling 方法中給定的參數平鋪圖像。任何以前設置的 tiling 參數都將被丟棄。
• MODE_COPY_FROM_METADATA - 圖像將與傳入某一寫入操作中的元資料物件一致。setTiling 將拋出 IllegalStateException。

參數：

mode - 用於 tiling 的網要。

拋出：

UnsupportedOperationException - 如果 canWriteTiles 返回 false。

IllegalArgumentException - 如果 mode 不是上面列出的網要之一。

另請參見：

setTiling(int, int, int, int), getTilingMode()

getTilingMode

public int getTilingMode()

如果支持平鋪，則返回當前平鋪網要。否則拋出 UnsupportedOperationException。

返回：

當前平鋪網要。

拋出：

UnsupportedOperationException - 如果 canWriteTiles 返回 false。

另請參見：

setTilingMode(int)

getPreferredTileSizes

public Dimension[] getPreferredTileSizes()

返回一個 Dimension 陣列，指示在輸出檔案或串流中進行編碼時 tile 的合法大小範圍。返回的陣列是一個副本。

資訊以對集合的形式返回；對的第一個元素包含最小寬度和高度（包括在內），第二個元素包含最大寬度和高度（包括在內）。將其放到一起，每個對便定義了一個有效大小範圍。要定義固定大小，則對兩個元素使用相同的寬度和高度。要定義任意範圍，則使用 null 值替代實際 Dimension 陣列。

如果建構子上沒有指定陣列，但允許進行平鋪，則此方法返回 null。

返回：

一個 Dimension 陣列，其平均長度至少為 2；或者 null。

拋出：

UnsupportedOperationException - 如果外掛程式不支持平鋪。

setTiling

public void setTiling(int tileWidth,
                      int tileHeight,
                      int tileGridXOffset,
                      int tileGridYOffset)

指定應該在輸出串流中平鋪圖像。tileWidth 和 tileHeight 參數指定檔案中 tile 的寬度和高度。如果 tile 的寬度或高度大於圖像的寬度或高度，則圖像無法使用該維數平鋪。

如果 canOffsetTiles 返回 false，則 tileGridXOffset 和 tileGridYOffset 參數必須為零。

參數：

tileWidth - 每個 tile 的寬度。

tileHeight - 每個 tile 的高度。

tileGridXOffset - tile 網格的水平偏移量。

tileGridYOffset - tile 網格的垂直偏移量。

拋出：

UnsupportedOperationException - 如果外掛程式不支持平鋪。

IllegalStateException - 如果平鋪網要不為 MODE_EXPLICIT。

UnsupportedOperationException - 如果外掛程式不支持網格偏移量，且網格偏移量並不都為零。

IllegalArgumentException - 如果 tile 大小不在 getPreferredTileSizes 返回的某個所允許範圍內。

IllegalArgumentException - 如果 tileWidth 或 tileHeight 小於等於 0。

另請參見：

canWriteTiles, canOffsetTiles, getTileWidth(), getTileHeight(), getTileGridXOffset(), getTileGridYOffset()

unsetTiling

public void unsetTiling()

移除通過調用 setTiling 指定的所有以前的 tile 網格參數。

預設實作將實例變數 tileWidth、tileHeight、tileGridXOffset 和 tileGridYOffset 都設置為 0。

拋出：

UnsupportedOperationException - 如果外掛程式不支持平鋪。

IllegalStateException - 如果平鋪網要不為 MODE_EXPLICIT。

另請參見：

setTiling(int, int, int, int)

getTileWidth

public int getTileWidth()

返回圖像中每個 tile 的寬度，將根據該寬度對輸出串流進行寫入。如果沒有設置 tiling 參數，則拋出 IllegalStateException。

返回：

將用於編碼的 tile 寬度。

拋出：

UnsupportedOperationException - 如果外掛程式不支持平鋪。

IllegalStateException - 如果平鋪網要不為 MODE_EXPLICIT。

IllegalStateException - 如果尚未設置 tiling 參數。

另請參見：

setTiling(int, int, int, int), getTileHeight()

getTileHeight

public int getTileHeight()

返回圖像中每個 tile 的高度，將根據該高度對輸出串流進行寫入。如果沒有設置 tiling 參數，則拋出 IllegalStateException。

返回：

將用於編碼的 tile 高度。

拋出：

UnsupportedOperationException - 如果外掛程式不支持平鋪。

IllegalStateException - 如果平鋪網要不為 MODE_EXPLICIT。

IllegalStateException - 如果尚未設置 tiling 參數。

另請參見：

setTiling(int, int, int, int), getTileWidth()

getTileGridXOffset

public int getTileGridXOffset()

返回圖像的水平 tile 網格偏移量，將根據該偏移量對輸出串流進行寫入。如果沒有設置 tiling 參數，則拋出 IllegalStateException。

返回：

將用於編碼的 tile 網格 X 偏移量。

拋出：

UnsupportedOperationException - 如果外掛程式不支持平鋪。

IllegalStateException - 如果平鋪網要不為 MODE_EXPLICIT。

IllegalStateException - 如果尚未設置 tiling 參數。

另請參見：

setTiling(int, int, int, int), getTileGridYOffset()

getTileGridYOffset

public int getTileGridYOffset()

返回圖像的垂直 tile 網格偏移量，將根據該偏移量對輸出串流進行寫入。如果沒有設置 tiling 參數，則拋出 IllegalStateException。

返回：

將用於編碼的 tile 網格 Y 偏移量。

拋出：

UnsupportedOperationException - 如果外掛程式不支持平鋪。

IllegalStateException - 如果平鋪網要不為 MODE_EXPLICIT。

IllegalStateException - 如果尚未設置 tiling 參數。

另請參見：

setTiling(int, int, int, int), getTileGridXOffset()

canWriteProgressive

public boolean canWriteProgressive()

如果 writer 能夠以一系列質量逐漸遞增的傳遞的方式將圖像寫出，則返回 true。

返回：

如果 writer 支持逐步編碼，則返回 true。

另請參見：

setProgressiveMode(int), getProgressiveMode()

setProgressiveMode

public void setProgressiveMode(int mode)

指定 writer 使用逐步網要寫出圖像，從而輸出串流將包含一系列質量遞增的掃瞄。如果不支持逐步編碼，則將拋出 UnsupportedOperationException。

mode 參數確定如何選擇 progression 參數，並且必須是 MODE_DISABLED、MODE_COPY_FROM_METADATA 或 MODE_DEFAULT。否則拋出 IllegalArgumentException。

對這些網要的解釋如下：

• MODE_DISABLED - 不前進。使用此網要則停止前進。
• MODE_COPY_FROM_METADATA - 輸出圖像將使用在傳入 writer 的元資料物件中找到的任何 progression 參數。
• MODE_DEFAULT - 該圖像將被逐步寫入，參數由 writer 選擇。

預設值為 MODE_COPY_FROM_METADATA。

參數：

mode - 用來在輸出串流中設置進度的網要。

拋出：

UnsupportedOperationException - 如果 writer 不支持逐步編碼。

IllegalArgumentException - 如果 mode 不是上面列出的網要之一。

另請參見：

getProgressiveMode()

getProgressiveMode

public int getProgressiveMode()

返回以逐步方式將資料寫入串流的當前網要。

返回：

逐步編碼的當前網要。

拋出：

UnsupportedOperationException - 如果 writer 不支持逐步編碼。

另請參見：

setProgressiveMode(int)

canWriteCompressed

public boolean canWriteCompressed()

如果此 writer 支持壓縮，則返回 true。

返回：

如果 writer 支持壓縮，則返回 true。

setCompressionMode

public void setCompressionMode(int mode)

指定是否執行壓縮，如果執行壓縮，將如何確定 compression 參數。mode 參數必須是四種網要之一，對它們的解釋如下：

• MODE_DISABLED - 如果該網要被設置為 MODE_DISABLED，則查詢或修改壓縮型別或參數的方法將會拋出 IllegalStateException（如果外掛程式通常支持壓縮）。一些 writer（比如 JPEG）通常不提供未壓縮的輸出。在這種情況下，試圖將網要設置為 MODE_DISABLED 將會拋出 UnsupportedOperationException 並且將不更改該網要。
• MODE_EXPLICIT - 使用此 ImageWriteParam 中指定的壓縮型別和質量設置進行壓縮。任何以前設置的 compression 參數都將被丟棄。
• MODE_COPY_FROM_METADATA - 使用傳入 writer 的元資料物件中指定的 compression 參數。
• MODE_DEFAULT - 使用預設 compression 參數。

預設值為 MODE_COPY_FROM_METADATA。

參數：

mode - 用來在輸出串流中設置壓縮的網要。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮，或者不支持所請求的網要。

IllegalArgumentException - 如果 mode 不是上面列出的網要之一。

另請參見：

getCompressionMode()

getCompressionMode

public int getCompressionMode()

如果支持壓縮，則返回當前壓縮網要。

返回：

當前壓縮網要。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

另請參見：

setCompressionMode(int)

getCompressionTypes

public String[] getCompressionTypes()

以陣列或 String 形式返回可用壓縮型別的列表，如果不能使用這些介面選擇壓縮型別，則返回 null。返回的陣列是一個副本。

如果 writer 只提供某一強制形式的壓縮，則沒有必要提供所有指定的壓縮型別。指定壓縮型別只應該在使用者能夠在不同方案之間作出有意義選擇的情況下使用。

預設實作檢查是否支持壓縮，如果不支持，則拋出 UnsupportedOperationException。否則，如果 compressionTypes 實例變數為非 null，則返回該變數的副本，否則返回 null。

返回：

包含可用壓縮型別的（非本地化）名稱的 String 陣列，或者返回 null。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

setCompressionType

public void setCompressionType(String compressionType)

將壓縮型別設置為 getCompressionTypes 指示的值之一。如果傳入的是 null 值，則移除所有以前的設置。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是，則調用 getCompressionTypes 並檢查 compressionType 是否是合法值之一。如果是合法值，則設置 compressionType 實例變數。如果 compressionType 為 null，則設置該實例變數而不執行任何檢查。

參數：

compressionType - 由 getCompressionTypes 返回的 String 之一；或者為 null，表示移除所有以前的設置。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

UnsupportedOperationException - 如果沒有可設置的壓縮型別。

IllegalArgumentException - 如果 compressionType 為非 null 但不是 getCompressionTypes 返回的值之一。

另請參見：

getCompressionTypes(), getCompressionType(), unsetCompression()

getCompressionType

public String getCompressionType()

返回當前設置的壓縮型別，如果沒有設置任何壓縮型別，則返回 null。以 String 的形式返回該型別，它是 getCompressionTypes 返回的那些型別之一。如果沒有設置壓縮型別，則返回 null。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是這樣，則返回 compressionType 實例變數的值。

返回：

String 形式的當前壓縮型別，如果沒有設置壓縮型別，則返回 null。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

另請參見：

setCompressionType(java.lang.String)

unsetCompression

public void unsetCompression()

移除所有以前的壓縮型別和質量設置。

預設實作將實例變數 compressionType 設置為 null，並將實例變數 compressionQuality 設置為 1.0F。

拋出：

UnsupportedOperationException - 如果外掛程式不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

另請參見：

setCompressionType(java.lang.String), setCompressionQuality(float)

getLocalizedCompressionTypeName

public String getLocalizedCompressionTypeName()

返回當前壓縮型別的本地化名稱，使用 getLocale 返回的 Locale。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是這樣，或者 compressionType 為非 null，則作為一種便捷方式返回 getCompressionType 的值。

返回：

包含當前壓縮型別的本地化名稱的 String。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

IllegalStateException - 如果沒有設置壓縮型別。

isCompressionLossless

public boolean isCompressionLossless()

如果當前壓縮型別提供無損失的壓縮，則返回 true。如果外掛程式只提供一個強制壓縮型別，則可以在不先調用 setCompressionType 的情況下調用此方法。

如果有多個壓縮型別，但沒有設置任何一種壓縮型別，則拋出 IllegalStateException。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是這樣，而 getCompressionTypes() 為 null 或 getCompressionType() 為非 null，則作為一種便捷方式返回 true。

返回：

如果當前壓縮型別是無損失的，則返回 true。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

IllegalStateException - 如果合法壓縮型別集為非 null 並且當前壓縮型別為 null。

setCompressionQuality

public void setCompressionQuality(float quality)

將壓縮質量設置為 0 和 1 之間的某個值。預設情況下，只支持一種壓縮質量設置；writer 可以提供擴展的 ImageWriteParam，其提供了更多控制。對於有損失的壓縮方案，壓縮質量應該控制檔案大小與圖像質量之間的權衡（例如，通過在寫入 JPEG 圖像時選擇量化表）。對於無損失方案，可以使用壓縮質量控制檔案大小與執行壓縮所用時間之間的權衡（例如，通過在寫入 PNG 圖像時優化行過濾器並設置 ZLIB 壓縮級別）。

壓縮質量為 0.0 通常被解釋為“高度壓縮很重要”，而該設置為 1.0 通常被解釋為“高圖像質量很重要”。

如果有多個壓縮型別，但沒有設置任何一種壓縮型別，則拋出 IllegalStateException。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是這樣，而 getCompressionTypes() 返回 null 或 compressionType 為非 null，則設置 compressionQuality 實例變數。

參數：

quality - 指示所需質量級別的 0 與 1 之間的一個 float 值。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

IllegalStateException - 如果合法壓縮型別集為非 null 並且當前壓縮型別為 null。

IllegalArgumentException - 如果 quality 不在 0 與 1（包括兩者）之間。

另請參見：

getCompressionQuality()

getCompressionQuality

public float getCompressionQuality()

返回當前壓縮質量設置。

如果有多個壓縮型別，但沒有設置任何一種壓縮型別，則拋出 IllegalStateException。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是這樣，而 getCompressionTypes() 為 null 或 getCompressionType() 為非 null，則返回 compressionQuality 實例變數的值。

返回：

當前壓縮質量設置。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

IllegalStateException - 如果合法壓縮型別集為非 null 並且當前壓縮型別為 null。

另請參見：

setCompressionQuality(float)

getBitRate

public float getBitRate(float quality)

返回一個 float 值，該值指示對給定質量級別上用於輸入圖像資料的每個位的輸出資料位數的估計。該值通常位於 0 與 1 之間，值越小則壓縮得越緊。特殊值 -1.0F 用於指示沒有估計數可用。

如果有多個壓縮型別，但沒有設置任何一種壓縮型別，則拋出 IllegalStateException。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是這樣，而 getCompressionTypes() 為 null 或 getCompressionType() 為非 null，並且 quality 在適當範圍內，則返回 -1.0。

參數：

quality - 將查詢其位率 (bit rate) 的查詢設置。

返回：

壓縮位率的估計數，如果沒有估計數可用，則返回 -1.0F。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

IllegalStateException - 如果合法壓縮型別集為非 null 並且當前壓縮型別為 null。

IllegalArgumentException - 如果 quality 不在 0 與 1（包括兩者）之間。

getCompressionQualityDescriptions

public String[] getCompressionQualityDescriptions()

返回一個 String 陣列，可作為使用者介面的一部分與 getCompressionQualityValues 一起使用，以設置或顯示壓縮質量級別。索引為 i 的 String 提供對質量級別範圍的描述，該範圍在 getCompressionQualityValues[i] 與 getCompressionQualityValues[i + 1] 之間。注意，從 getCompressionQualityValues 返回的陣列長度將總是大於從 getCompressionQualityDescriptions 返回的陣列長度。

例如，字元串 "Good"、"Better" 和 "Best" 可以與範圍 [0, .33)、[.33, .66) 和 [.66, 1.0] 關聯。在這種情況下，getCompressionQualityDescriptions 將返回 { "Good", "Better", "Best" }，getCompressionQualityValues 將返回 { 0.0F, .33F, .66F, 1.0F }。

如果沒有描述可用，則返回 null。如果從 getCompressionQualityValues 返回 null，則此方法也必須返回 null。

應該為由 getLocale 返回的 Locale 將描述本地化，如果 Locale 為非 null 的話。

如果有多個壓縮型別，但沒有設置任何一種壓縮型別，則拋出 IllegalStateException。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是這樣，而 getCompressionTypes() 為 null 或 getCompressionType() 為非 null，則返回 null。

返回：

包含壓縮質量級別的本地化描述的 String 陣列。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

IllegalStateException - 如果合法壓縮型別集為非 null 並且當前壓縮型別為 null。

另請參見：

getCompressionQualityValues()

getCompressionQualityValues

public float[] getCompressionQualityValues()

返回一個 float 陣列，可作為使用者介面的一部分與 getCompressionQualityDescriptions 一起使用，以設置或顯示壓縮質量級別。有關更多資訊，請參閱 getCompressionQualityDescriptions。

如果沒有描述可用，則返回 null。如果從 getCompressionQualityDescriptions 返回 null，則此方法也必須返回 null。

如果有多個壓縮型別，但沒有設置任何一種壓縮型別，則拋出 IllegalStateException。

預設實作檢查是否支持壓縮，以及壓縮網要是否為 MODE_EXPLICIT。如果是這樣，而 getCompressionTypes() 為 null 或 getCompressionType() 為非 null，則返回 null。

返回：

一個 float 陣列，指示 getCompressionQualityDescriptions 中的 String 描述的壓縮質量級別之間的分界線。

拋出：

UnsupportedOperationException - 如果 writer 不支持壓縮。

IllegalStateException - 如果壓縮網要不是 MODE_EXPLICIT。

IllegalStateException - 如果合法壓縮型別集為非 null 並且當前壓縮型別為 null。

另請參見：

getCompressionQualityDescriptions()