JavaTM Platform
Standard Ed. 6

javax.imageio
クラス ImageReadParam

java.lang.Object
  上位を拡張 javax.imageio.IIOParam
      上位を拡張 javax.imageio.ImageReadParam
直系の既知のサブクラス:
JPEGImageReadParam

public class ImageReadParam
extends IIOParam

ストリームが復号化される方法を記述するクラスです。このクラスまたはサブクラスのインスタンスは、ImageReader のインスタンスへ規定の「方法」についての情報を提供するために使用されます。

ファイルまたはストリームの一部として符号化されたイメージは、空間的な寸法の幅と高さ、バンド数、およびプログレッシブデコーディングパスの数など、複数の次元に拡大して考えられます。このクラスは、これらのすべての次元で、連続的なイメージの (ハイパー) 矩形サブ領域を使用して、復号化の選択を可能にします。さらに、空間的な寸法は非連続的に間引きできます。最後に、色および形式の変換は、BufferedImage を提供するか、ImageTypeSpecifier を使用することにより、デスティネーションイメージの ColorModelSampleModel を制御して指定されます。

ImageReadParam オブジェクトは、Java Image I/O フレームワークのコンテキストで、イメージまたはイメージのセットをストリームから入力に変換する方法を指定するために使用します。特定のイメージ形式のプラグインは、ImageReader 実装の getDefaultReadParam メソッドから ImageReadParam のインスタンスを返します。

ImageReadParam のインスタンスによって管理される状態は、復号化される特定のイメージから独立しています。実際に復号化が行われる場合、読み込みパラメータに設定された値は、ストリームから復号化中のイメージの実際のプロパティーおよび復号化されたピクセルデータを受け取るデスティネーション BufferedImage に結合されます。たとえば、setSourceRegion を使用して設定されたソース領域は、実際の有効なソース領域に最初に交差します。結果は、getDestinationOffset で返される値によって変換され、実際の有効なデスティネーション領域に交差する結果の矩形が、書き込まれるデスティネーション領域になります。

ImageReadParam によって指定されたパラメータは、次のようにイメージに適用されます。最初に、描画のサイズが setSourceRenderSize によって設定されている場合、復号化されるイメージ全体は getSourceRenderSize により指定されたサイズで描画されます。それ以外の場合、イメージは ImageReader.getWidth および ImageReader.getHeight によって指定された実際のサイズで描画されます。

次に、イメージは getSourceXOffsetgetSourceYOffsetgetSourceWidth、および getSourceHeight によって指定されたソース領域にクリップされます。

結果の領域は、IIOParam.setSourceSubsampling によって指定された係数によって間引きされます。最初のピクセル、行あたりピクセル数、および行数は、すべてサブサンプリング設定に依存します。幅 w、高さ h の結果の矩形の最小 X 座標と Y 座標 (minXminY) を呼び出します。

この矩形は、(getDestinationOffset().xgetDestinationOffset().y) にオフセットされ、デスティネーション境界にクリップされます。デスティネーションイメージが設定されていない場合、デスティネーションは、ソース領域のすべてのピクセルをデスティネーションに書き込みできるように、幅 getDestinationOffset().x + w、高さ getDestinationOffset().y + h に定義されます。

サブサンプリング後に、デスティネーションイメージ内に配置され、 getSourceMinProgressivePassgetSourceNumProgressivePasses によって指定されるプログレッシブパスの 1 つに書き込まれるピクセルは、次の手順に渡されます。

最後に、各ピクセルのソースサンプルは setDestinationBands のコメントに記述されるアルゴリズムを使用して、デスティネーションバンドにマッピングされます。

プラグインの書き込み側は、プラグイン固有の追加のインタフェースを実装するサブクラスを提供することにより、ImageReadParam の機能を拡張できます。どのインタフェースが利用可能か、それがどのように使用されるかは、プラグインによります。読み取り側は、認識しない ImageReadParam サブクラスの拡張機能をそのまま無視します。また、getDefaultReadParam を介して、読み取り側自体の ImageReadParam インスタンスを作成する場合、通常、使用不可であるオプション機能はすべて無視されます。

クエリーメソッドは、将来のために用意されている場合を除き、ImageReader のすべての実装でサポートされる必要があります。たとえば、ソースの描画サイズは省略可能ですが、サブサンプリングはサポートされる必要があります。

関連項目:
ImageReader, ImageWriter, ImageWriteParam

フィールドの概要
protected  boolean canSetSourceRenderSize
          この ImageReadParam がソースの描画寸法を設定できる場合は true です。
protected  BufferedImage destination
          現在のデスティネーション BufferedImage、または何も設定されていない場合は null です。
protected  int[] destinationBands
          int の配列としての、使用するデスティネーションバンドのセットです。
protected  int minProgressivePass
          ソースから読み取るプログレッシブパスの最小インデックスです。
protected  int numProgressivePasses
          ソースから読み取るプログレッシブパスの最大数です。
protected  Dimension sourceRenderSize
          canSetSourceRenderSizetrue の場合、目的のソース描画の幅と高さです。
 
クラス javax.imageio.IIOParam から継承されたフィールド
controller, defaultController, destinationOffset, destinationType, sourceBands, sourceRegion, sourceXSubsampling, sourceYSubsampling, subsamplingXOffset, subsamplingYOffset
 
コンストラクタの概要
ImageReadParam()
          ImageReadParam を構築します。
 
メソッドの概要
 boolean canSetSourceRenderSize()
          この読み取り側が、復号化プロセスの一部として、setSourceRenderSize メソッドによって、ソースイメージを任意のサイズで描画できるようにする場合、true を返します。
 BufferedImage getDestination()
          setDestination メソッドによって設定された BufferedImage、または何も設定されていない場合は null を返します。
 int[] getDestinationBands()
          データが配置されているバンドインデックスのセットを返します。
 int getSourceMaxProgressivePass()
          getSourceNumProgressivePassesInteger.MAX_VALUE と等しい場合、Integer.MAX_VALUE を返します。
 int getSourceMinProgressivePass()
          復号化される最初のプログレッシブパスのインデックスを返します。
 int getSourceNumProgressivePasses()
          復号化されるプログレッシブパスの数を返します。
 Dimension getSourceRenderSize()
          setSourceRenderSize メソッドによって設定されている場合、復号化の間に描画されるように、イメージの幅と高さを返します。
 void setDestination(BufferedImage destination)
          復号化されるピクセルデータのデスティネーションとして使用する BufferedImage を提供します。
 void setDestinationBands(int[] destinationBands)
          データが配置されているデスティネーションバンドのインデックスを設定します。
 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
canSetSourceRenderSizetrue の場合、目的のソース描画の幅と高さです。そうでない場合は null です。

ソースの描画サイズの設定をサポートしない ImageReader は、この値を無視します。


destination

protected BufferedImage destination
現在のデスティネーション BufferedImage、または何も設定されていない場合は null です。デフォルトの値は null です。


destinationBands

protected int[] destinationBands
int の配列としての、使用するデスティネーションバンドのセットです。デフォルトの値は null です。これは、すべてのデスティネーションバンドが順番に書き込まれることを示します。


minProgressivePass

protected int minProgressivePass
ソースから読み取るプログレッシブパスの最小インデックスです。デフォルトの値は 0 に設定されます。これは、使用可能な最初のパスから開始するパスが復号化されることを示します。

サブクラスは、この値が負にならないようにする必要があります。


numProgressivePasses

protected int numProgressivePasses
ソースから読み取るプログレッシブパスの最大数です。デフォルトの値は Integer.MAX_VALUE に設定されます。これは、使用可能な最後のパスまで復号化されることを示します。

サブクラスは、この値が正になるようにする必要があります。さらに、この値が Integer.MAX_VALUE ではない場合、minProgressivePass + numProgressivePasses - 1Integer.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 バンドのイメージは CMYK または RGBA データのいずれかで表せます。デスティネーションのタイプが設定された場合、その ColorModel はイメージ自体にあるすべての ColorModel をオーバーライドします。これは、イメージの ColorModel が、書き込まれたバンドのサブセットではなくイメージ全体を参照するので、setSourceBands を使用する場合に重要です。

オーバーライド:
クラス IIOParam 内の setDestinationType
パラメータ:
destinationType - デスティネーションのレイアウトとカラータイプを決定するために 使用する ImageTypeSpecifier
関連項目:
IIOParam.getDestinationType()

setDestination

public void setDestination(BufferedImage destination)
復号化されるピクセルデータのデスティネーションとして使用する BufferedImage を提供します。現在設定されているイメージは、readreadAll、および readRaster メソッドによって書き込まれ、これに対する参照はこれらのメソッドによって返されます。

上述のメソッドからのピクセルデータは、getDestinationOffset によって指定される座標の開始時に書き込まれます。

destinationnull の場合、新しく作成された BufferedImage は、これらのメソッドによって返されます。

読み込み時に、イメージの ColorModelSampleModel が、ImageReadergetImageTypes メソッドから返される ImageTypeSpecifier の 1 つに対応することを確認するために検査されます。対応しない場合、読み取り側は IIOException をスローします。

パラメータ:
destination - 書き込まれる BufferedImage、または null
関連項目:
getDestination()

getDestination

public BufferedImage getDestination()
setDestination メソッドによって設定された BufferedImage、または何も設定されていない場合は null を返します。

戻り値:
書き込まれる BufferedImage
関連項目:
setDestination(java.awt.image.BufferedImage)

setDestinationBands

public void setDestinationBands(int[] destinationBands)
データが配置されているデスティネーションバンドのインデックスを設定します。重複するインデックスは使用できません。

null は、すべてのデスティネーションバンドが使用されていることを示します。

デスティネーションバンドが指定されない場合、デスティネーションバンドのサブセットの選択は、読み込みの出力イメージのバンド数に影響を与えません。作成されるデスティネーションイメージは、このメソッドが呼び出されなかったかのように、同じバンド数を保持します。デスティネーションイメージに異なるバンド数が必要な場合、ImageReadParam.setDestination メソッドを使用してイメージを提供する必要があります。

デスティネーションバンドの最大インデックスより大きい値が指定された場合、または使用するソースバンドの数とデスティネーションバンドの数が異なる場合、読み込みまたは書き込み時に、読み取り側または書き込み側によって IllegalArgumentException がスローされます。ImageReader.checkReadParamBandSettings メソッドは、このテストを自動化するために使用されます。

パラメータ:
destinationBands - 使用する整数型バンドインデックスの 配列
例外:
IllegalArgumentException - destinationBands が 負または重複する値を保持する場合
関連項目:
getDestinationBands(), IIOParam.getSourceBands(), ImageReader.checkReadParamBandSettings(javax.imageio.ImageReadParam, int, int)

getDestinationBands

public int[] getDestinationBands()
データが配置されているバンドインデックスのセットを返します。値が設定されていない場合、すべてのデスティネーションバンドが使用されていることを示す null が返されます。

戻り値:
使用するデスティネーションバンドのインデックス、 または null
関連項目:
setDestinationBands(int[])

canSetSourceRenderSize

public boolean canSetSourceRenderSize()
この読み取り側が、復号化プロセスの一部として、setSourceRenderSize メソッドによって、ソースイメージを任意のサイズで描画できるようにする場合、true を返します。このメソッドが false を返す場合、setSourceRenderSize の呼び出しは UnsupportedOperationException をスローします。

戻り値:
ソース描画サイズの設定をサポートする場合は true
関連項目:
setSourceRenderSize(java.awt.Dimension)

setSourceRenderSize

public void setSourceRenderSize(Dimension size)
                         throws UnsupportedOperationException
イメージを任意のサイズで描画できる場合、ソースの幅と高さを指定された値に設定します。ImageReadergetWidth および 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_VALUEnumPasses の値は、minPass より前方のすべてのパスが読み取られることを示します。そうでない場合、最後のパスのインデックス (つまり、minPass + numPasses - 1) は Integer.MAX_VALUE を超えてはいけません。

unsetSourceProgressivePasses メソッドはありません。setSourceProgressivePasses(0, Integer.MAX_VALUE) の呼び出しによって、同じ効果が得られます。

パラメータ:
minPass - 復号化される最初のパスのインデックス
numPasses - 復号化されるパスの最大数
例外:
IllegalArgumentException - minPass が負、 numPasses が負または 0、または numPassesInteger.MAX_VALUE より小さく、minPass + numPasses - 1INTEGER.MAX_VALUE より大きい場合
関連項目:
getSourceMinProgressivePass(), getSourceMaxProgressivePass()

getSourceMinProgressivePass

public int getSourceMinProgressivePass()
復号化される最初のプログレッシブパスのインデックスを返します。値が設定されていない場合、正しい値 0 が返されます。

戻り値:
復号化される最初のパスのインデックス
関連項目:
setSourceProgressivePasses(int, int), getSourceNumProgressivePasses()

getSourceMaxProgressivePass

public int getSourceMaxProgressivePass()
getSourceNumProgressivePassesInteger.MAX_VALUE と等しい場合、Integer.MAX_VALUE を返します。それ以外の場合、getSourceMinProgressivePass() + getSourceNumProgressivePasses() - 1 を返します。

戻り値:
読み取られる最後のパスのインデックス、または Integer.MAX_VALUE

getSourceNumProgressivePasses

public int getSourceNumProgressivePasses()
復号化されるプログレッシブパスの数を返します。値が設定されていない場合、正しい値 Integer.MAX_VALUE が返されます。

戻り値:
復号化されるパスの数
関連項目:
setSourceProgressivePasses(int, int), getSourceMinProgressivePass()

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。