ImageLoader (クラス)
public abstract ImageLoader
インポート元： CURL.GUI.STANDARD. package 内で定義されています CURL.GRAPHICS.IMAGEIO.BASE.

ImageLoaderクラスは、様々なフォーマットのイメージファイルからイメージのロードや抽出またはイメージの情報を取得するメソッドやデータをカプセル化します。

説明

ImageLoaderは、可能であればメモリ上にイメージ全体を初期化しないという点においてImageDataと異なります。ImageLoader.get-imageを呼び出すことにより、イメージのどの部分のイメージデータでも呼び出すことが出来ます。
この結果、高圧縮のファイルフォーマットの場合にメモリの使用量を減らすことが出来ます。例えば、 イメージを表示する場合に、イメージと同じ大きさのPixmapを作り続けることを防ぐ為に、より小さなPixmapを使って、複数のステップで大きなイメージの一部分を呼び出すことが出来ます。 この手順に関する情報については、ImageLoader.get-image-infoをご覧ください。
幾つかの場合においては、これよりも優れたテクニックがあるかも知れないことに留意してください。例えば、 クライアント/サーバーが対応したアプリケーションでは、クライアントではなくサーバーがイメージのサイズを調整し分割する場合、より小さなデータを転送し、応答をあげ、より小さなメモリ使用量を実現することが出来るかも知れません。

注意事項

ImageLoaderは、ストリームやファイルをオープンし続けません。しかしながら、ファイルコンテンツの表現をメモリに保持し続ける必要があります。この事は、特に大きなソースファイルの場合に、ImageLoaderの参照を維持しないことが望ましいかもしれないことを意味しています。
また、全てのイメージやイメージフォーマットが部分抽出をサポートするわけではないことに注意してください。現時点では、TIFFファイルだけにおいて、ImageLoaderを使用するメリットがあります。他のフォーマットでは、ImageDataを使用して実装されており、メモリ上にデコードされた Pixmapを保持します。
サポートされるフォーマットでも、抽出されるサブイメージの粒度は劇的に異なります。すなわち、抽出できるもっとも小さな領域は、幾つかの走査線や小さな長方形のタイルなど様々です。イメージ全体に依存します。(このサイズは、ImageLoader.get-image-infoから返されるoptimal-get-width ＊optimal-get-heightと同じになります。) これらの寸法の一時的な中間バッファは、イメージの抽出中に作成されます。それでも、高圧縮されたファイルにImageLoaderを使用することは、メモリオーバーヘッドを最小限にするのに役立ちます。何故ならば、このバッファは必要な時だけ一時的に存在し、可能であればイメージ間で再利用されるからです。
導入: バージョン 7.0

コンストラクタ
default:このImageLoaderを初期化するためにサブクラスから呼び出されます。
コンストラクタ protected {ImageLoader.default
image-count:int,
loop-count:int,
properties:{HashTable-of String, any} = {new {HashTable-of String, any}, efficient-size = 0 }
}
from-stream:ByteInputStream から ImageLoader をロードします。
ファクトリ public {ImageLoader.from-stream
bis:ByteInputStream,
mime-type:String,
pixel-count-limit:int = max-int
}:ImageLoader
from-url:Url から ImageLoader をロードします。
ファクトリ public {ImageLoader.from-url
url:Url,
mime-type:#String = null,
pixel-count-limit:int = max-int
}:ImageLoader

プロパティ
image-count:このイメージファイルに含まれているイメージの数。
フィールド public constant ImageLoader.image-count:int
loop-count:フレームのループ回数。
フィールド public constant ImageLoader.loop-count:int
properties:ロードされた画像のファイルフォーマットで定義されたイメージプロパティ。
フィールド public constant ImageLoader.properties:{HashTable-of String, any}

メソッド
get-image:このImageLoaderの中のイメージの1つの一部分を取得します。
public final {ImageLoader.get-image
image-index:int,
x:int = 0,
y:int = 0,
width:int = -1,
height:int = -1,
out:#Pixmap = null
}:Pixmap
get-image-at-scale:このImageLoaderのイメージ全体を、スケーリングされた表現で取得します。
public {ImageLoader.get-image-at-scale
image-index:int,
x-scale:double,
y-scale:double,
src-x:int = 0,
src-y:int = 0,
src-width:int = -1,
src-height:int = -1,
resample-algorithm:PixmapResampleAlgorithm,
out:#Pixmap = null
}:(result:Pixmap, result-width:int, result-height:int)
get-image-at-size:このImageLoaderのイメージ全体を、スケーリングされた表現で取得します。
public {ImageLoader.get-image-at-size
image-index:int,
width:int,
height:int,
resample-algorithm:PixmapResampleAlgorithm,
src-x:int = 0,
src-y:int = 0,
src-width:int = -1,
src-height:int = -1,
out:#Pixmap = null,
preserve-aspect-ratio?:bool = true
}:(result:Pixmap, result-width:int, result-height:int)
get-image-aux:内部実装メソッド。 ImageLoaderのサブクラスによってオーバーライドされます。
protected abstract {ImageLoader.get-image-aux
image-index:int,
x:int,
y:int,
width:int,
height:int,
out:Pixmap
}:void
get-image-info:可能であれば、イメージをインスタンス化することなく、特定イメージの情報を取得します。
public final {ImageLoader.get-image-info
image-index:int
}:(width:int, height:int, delay:Time, optimal-get-width:int, optimal-get-height:int)
get-image-info-aux:内部実装メソッド。 ImageLoaderのサブクラスによってオーバーライドされます。
protected abstract {ImageLoader.get-image-info-aux
image-index:int
}:(width:int, height:int, delay:Time, optimal-get-width:int, optimal-get-height:int)
メソッド 継承 Object: object-describe, object-describe-for-debugging, object-serialize



コンストラクタ詳細
default (コンストラクタ)
protected {ImageLoader.default
image-count:int,
loop-count:int,
properties:{HashTable-of String, any} = {new {HashTable-of String, any}, efficient-size = 0 }
}

このImageLoaderを初期化するためにサブクラスから呼び出されます。


from-stream (ファクトリ)
public {ImageLoader.from-stream
bis:ByteInputStream,
mime-type:String,
pixel-count-limit:int = max-int
}:ImageLoader

ByteInputStream から ImageLoader をロードします。

bis: イメージのロード元の ByteInputStream。
mime-type: イメージの content-type。

一般的なイメージの content-type は "image/jpeg"、"image/gif" および "image/bmp" です。
pixel-count-limit: イメージが壊れている (または使用不可能である) と宣言する前にロードするピクセルの最大数。既定値は無限です。

説明

ImageLoaderの詳細については、クラスの記述を参照してください。

from-url (ファクトリ)
public {ImageLoader.from-url
url:Url,
mime-type:#String = null,
pixel-count-limit:int = max-int
}:ImageLoader

Url から ImageLoader をロードします。

url: イメージのロード元を示す Url。
mime-type: イメージの content-type。

mime-type が null (既定) の場合はストリームまたはファイル名の拡張子から取得されます。

一般的なイメージの content-type は "image/jpeg"、"image/gif" および "image/bmp" です。
pixel-count-limit: イメージが壊れている (または使用不可能である) と宣言する前にロードするピクセルの最大数。既定値は無限です。

説明

ImageLoaderの詳細については、クラスの記述を参照してください。


プロパティ詳細
image-count (フィールド)
public constant ImageLoader.image-count:int

このイメージファイルに含まれているイメージの数。


loop-count (フィールド)
public constant ImageLoader.loop-count:int

フレームのループ回数。

説明

値 0 は無限ループを意味します。

properties (フィールド)
public constant ImageLoader.properties:{HashTable-of String, any}

ロードされた画像のファイルフォーマットで定義されたイメージプロパティ。





メソッド詳細
get-image (メソッド)
public final {ImageLoader.get-image
image-index:int,
x:int = 0,
y:int = 0,
width:int = -1,
height:int = -1,
out:#Pixmap = null
}:Pixmap

このImageLoaderの中のイメージの1つの一部分を取得します。

image-index: このImageLoader内のイメージのインデックス。この値は正であり、ImageLoader.image-countよりも小さくなければなりません。そうでなければArrayBoundsExceptionがスローされます。
x: 呼び出すイメージデータのx座標の開始位置。この値は、正の値かつイメージの幅よりも小さい必要があります。そうでなければ、ArrayBoundsExceptionがスローされます。
y: 呼び出すイメージデータのy座標の開始位置。この値は、正の値かつイメージの高さよりも小さい必要があります。そうでなければ、ArrayBoundsExceptionがスローされます。
width: 返されるイメージの幅。この値は0以上でかつ、(x + width)はソースイメージの幅以下でなければなりません。そうでなければ、ArrayBoundsException がスローされます。-1は、”イメージの残り”を示す特別な値で、(image-width - x)と解釈されます。
height: 返されるイメージの高さ。この値は0以上でかつ、(y + height) はソースイメージの高さ以下でなければなりません。そうでなければ、ArrayBoundsException がスローされます。-1は、”イメージの残り”を示す特別な値で、(image-height - y)と解釈されます。
out: 結果が格納されるオプションのPixmap 。これによりメモリーアロケーションの必要性を減らすことが出来ます。out がnullであるか、その寸法が、指定されたwidth または heightよりも小さい場合、新しいPixmap がアロケーションされます。この為、out が使用されるとは仮定しないでください。代わりに、常に戻り値を使用してください。このパラメータが、結果よりも大きい時に使用される可能性があることを考慮する必要があります。結果よりもパラメータが大きくなるのは、（座標 0,0で始まっている）Pixmapの左上四半部に結果が位置するような場合です。Pixmap の残りの部分は未定義の状態になります。

戻り値

image-indexで指定されたイメージのサブセットを含むPixmap。Pixmapの幅と高さは、outを指定しない場合には、widthとheightパラメータと同じになります。 outを指定し、またそれが必要以上に大きい場合でも、その値が使われます。したがって、outに格納されるイメージのサイズを信頼してはいけません。

説明

outが使われており、それが必要上に大きい場合、結果のピクセルは左上の角に位置します。ピクセル 0, 0から始まります。
ImageLoaderの詳細の情報は、クラスの説明をご覧ください。ImageLoader.get-image-infoは、widthとheightの有効な選択肢の情報を提供します。

get-image-at-scale (メソッド)
public {ImageLoader.get-image-at-scale
image-index:int,
x-scale:double,
y-scale:double,
src-x:int = 0,
src-y:int = 0,
src-width:int = -1,
src-height:int = -1,
resample-algorithm:PixmapResampleAlgorithm,
out:#Pixmap = null
}:(result:Pixmap, result-width:int, result-height:int)

このImageLoaderのイメージ全体を、スケーリングされた表現で取得します。

image-index: このImageLoader内のイメージのインデックス。この値は正であり、ImageLoader.image-countよりも小さくなければなりません。そうでなければArrayBoundsExceptionがスローされます。
x-scale: 適用される垂直方向のスケーリング要因。結果の寸法は、x-scale * source-widthになります。結果はもっとも近いintegerに丸められます。
x-scale: 適用される垂直方向のスケーリング要因。結果の寸法は、y-scale * source-heightになります。 結果はもっとも近いintegerに丸められます。
resample-algorithm: イメージの拡大縮小を計算する際に使用されるアルゴリズム。オプションによって、計算コストが大きく異なることに注意してください。
src-x: 呼び出すイメージデータのx座標の開始位置。座標は、サイズ変更がされていないソースイメージの基準座標系で指定されます。この値は、正の値かつイメージの幅よりも小さい必要があります。そうでなければ、ArrayBoundsExceptionがスローされます。
src-y: 呼び出すイメージデータのy座標の開始位置。座標は、サイズ変更がされていないソースイメージの基準座標系で指定されます。この値は、正の値かつイメージの高さよりも小さい必要があります。そうでなければ、ArrayBoundsExceptionがスローされます。
src-width: ソースイメージから呼び出されるエリアの幅。座標は、サイズ変更がされていないソースイメージの基準座標系で指定されます。この値は、0以上かつ、(src-x + src-width)は、ソースイメージの幅以下である必要があります。そうでない場合には、ArrayBoundsExceptionがスローされます。-1は、”イメージの残り”を示す特別な値で、(image-width - src-x)と解釈されます。
src-height: ソースイメージから呼び出されるエリアの高さ。座標は、サイズ変更がされていないソースイメージの基準座標系で指定されます。この値は、0以上かつ、(src-y + src-height)は、ソースイメージの高さ以下である必要があります。そうでない場合には、ArrayBoundsExceptionがスローされます。-1は、”イメージの残り”を示す特別な値で、(image-height - src-y)と解釈されます。
out: 結果が格納されるオプションのPixmap 。これによりメモリーアロケーションの必要性を減らすことが出来ます。out がnullであるか、その寸法が、指定されたwidth または heightよりも小さい場合、新しいPixmap がアロケーションされます。この為、out が使用されるとは仮定しないでください。代わりに、常に戻り値を使用してください。このパラメータが、結果よりも大きい時に使用される可能性があることを考慮する必要があります。結果よりもパラメータが大きくなるのは、（座標 0,0で始まっている）Pixmapの左上四半部に結果が位置するような場合です。Pixmap の残りの部分は未定義の状態になります。

戻り値

ソースイメージから要求されたサブセットを含むPixmap。それは、指定されたサイズにスケールダウンされ、イメージ データで満たされたPixmap寸法にあわせるようにします。丸め誤差の為、これらの値は予想される値としばしば異なることに注意してください。また、outが指定されている場合、戻されるPixmapのサイズとも異なることがあります。常に戻り値の寸法を使う必要があります。

説明

このメソッドは、ImageLoader.get-image を使ってタイル状の呼び出しを実行します。; これは、一度にピクセルの最適な寸法(ImageLoader.get-image-infoの戻り値)以外の呼び出しを行いません。 単独でこれらのかたまりをスケーリングします。この事は、オリジナルの合理的な複製を生成する為に、大きなイメージの全てをロードする必要がなりことを保証します。
ImageLoader.get-image-at-sizeも参照してください。

get-image-at-size (メソッド)
public {ImageLoader.get-image-at-size
image-index:int,
width:int,
height:int,
resample-algorithm:PixmapResampleAlgorithm,
src-x:int = 0,
src-y:int = 0,
src-width:int = -1,
src-height:int = -1,
out:#Pixmap = null,
preserve-aspect-ratio?:bool = true
}:(result:Pixmap, result-width:int, result-height:int)

このImageLoaderのイメージ全体を、スケーリングされた表現で取得します。

image-index: このImageLoader内のイメージのインデックス。この値は正であり、ImageLoader.image-countよりも小さくなければなりません。そうでなければArrayBoundsExceptionがスローされます。
width: 返されるイメージの幅。これは、src-widthと共に水平スケーリング要因を決定します。preserve-aspect-ratio? がtrueの場合、この値が小さくされることがあります。以下をご覧ください。
height: 返されるイメージの高さ。これは、src-heightと共に垂直スケーリング要因を決定します。preserve-aspect-ratio? がtrueの場合、この値が小さくされることがあります。以下をご覧ください。
resample-algorithm: イメージの拡大縮小を計算する際に使用されるアルゴリズム。オプションによって、計算コストが大きく異なることに注意してください。
src-x: 呼び出すイメージデータのx座標の開始位置。座標は、サイズ変更がされていないソースイメージの基準座標系で指定されます。この値は、正の値かつイメージの幅よりも小さい必要があります。そうでなければ、ArrayBoundsExceptionがスローされます。
src-y: 呼び出すイメージデータのy座標の開始位置。座標は、サイズ変更がされていないソースイメージの基準座標系で指定されます。この値は、正の値かつイメージの高さよりも小さい必要があります。そうでなければ、ArrayBoundsExceptionがスローされます。
src-width: ソースイメージから呼び出されるエリアの幅。座標は、サイズ変更がされていないソースイメージの基準座標系で指定されます。この値は、0以上かつ、(src-x + src-width)は、ソースイメージの幅以下である必要があります。そうでない場合には、ArrayBoundsExceptionがスローされます。-1は、”イメージの残り”を示す特別な値で、(image-width - src-x)と解釈されます。
src-height: ソースイメージから呼び出されるエリアの高さ。座標は、サイズ変更がされていないソースイメージの基準座標系で指定されます。この値は、0以上かつ、(src-y + src-height)は、ソースイメージの高さ以下である必要があります。そうでない場合には、ArrayBoundsExceptionがスローされます。-1は、”イメージの残り”を示す特別な値で、(image-height - src-y)と解釈されます。
out: 結果が格納されるオプションのPixmap 。これによりメモリーアロケーションの必要性を減らすことが出来ます。out がnullであるか、その寸法が、指定されたwidth または heightよりも小さい場合、新しいPixmap がアロケーションされます。この為、out が使用されるとは仮定しないでください。代わりに、常に戻り値を使用してください。このパラメータが、結果よりも大きい時に使用される可能性があることを考慮する必要があります。結果よりもパラメータが大きくなるのは、（座標 0,0で始まっている）Pixmapの左上四半部に結果が位置するような場合です。Pixmap の残りの部分は未定義の状態になります。
preserve-aspect-ratio?: 返されたイメージが、入力と同じ縦横比であることを保証するかどうかを示します。詳細は以下をご覧ください。

戻り値

ソースイメージから要求されたサブセットを含むPixmap。それは、指定されたサイズにスケールダウンされ、イメージ データで満たされたPixmap 寸法にあわせるようにします。preserve-aspect-ratio? がtrueの場合、指定したサイズと異なることがあることに注意してください。また、outが指定されている場合、戻されるPixmapのサイズとも異なることがあります。 常に戻り値の寸法を使う必要があります。

説明

このメソッドは、ImageLoader.get-image を使ってタイル状の呼び出しを実行します。; これは、一度にピクセルの最適な寸法(ImageLoader.get-image-infoの戻り値)以外の呼び出しを行いません。 単独でこれらのかたまりをスケーリングします。この事は、オリジナルの合理的な複製を生成する為に、大きなイメージの全てをロードする必要がなりことを保証します。


結果がオリジナルと同じように見えることを保証したい時は、preserve-aspect-ratio?をtrueに設定します。これにより結果の縦横比は、オリジナルイメージの縦横比に可能な限り近づくことを保証します。 そうでなければ歪みが生じるかも知れません。preserve-aspect-ratio? は、指定された寸法に減らすように実行されます。すなわちこのメソッドの出力は、幅はwidth以下、高さはheightになります。


ImageLoader.get-image-at-scaleも参照してください。

get-image-aux (メソッド)
protected abstract {ImageLoader.get-image-aux
image-index:int,
x:int,
y:int,
width:int,
height:int,
out:Pixmap
}:void

内部実装メソッド。 ImageLoaderのサブクラスによってオーバーライドされます。

説明

ImageLoader.get-imageは、正しいレンジ内であることが保証されている（例えば、width = -1は、正の値に変換されます。）パラメータと、充分な寸法であることが保証されているPixmapでこのメソッドを呼び出します。そうでなければ全てのパラメータは同一になります。

get-image-info (メソッド)
public final {ImageLoader.get-image-info
image-index:int
}:(width:int, height:int, delay:Time, optimal-get-width:int, optimal-get-height:int)

可能であれば、イメージをインスタンス化することなく、特定イメージの情報を取得します。

image-index: このImageLoader内のイメージのインデックス。この値は正であり、ImageLoader.image-countよりも小さくなければなりません。そうでなければArrayBoundsExceptionがスローされます。

戻り値

このメソッドは幾つかの値を返します。:

注意事項

optimal-get-widthとoptimal-get-heightは、特定のレンジ内に収まることを保証しません。正の値であることと、イメージの高さと幅以下であることだけ保証されます。特に、幾つかのイメージでは、有効なサブイメージ検索を許可するような構成になっていません。その様な場合、これらの値は、イメージの高さや幅と同じになります。他のイメージでは、情報の検索にいかなる制限を設けないかもしれません。このよう場合、これらの値はゼロになります。現時点では、これはTIFFイメージ以外のイメージに当てはまります。何故ならTIFFイメージだけがファイル全体をデコードしてバッファに取り込む事無く、読み取ることが出来るからです。
詳細に関しては、ImageLoaderのクラスの説明をご覧ください。

get-image-info-aux (メソッド)
protected abstract {ImageLoader.get-image-info-aux
image-index:int
}:(width:int, height:int, delay:Time, optimal-get-width:int, optimal-get-height:int)

内部実装メソッド。 ImageLoaderのサブクラスによってオーバーライドされます。

説明

ImageLoader.get-image-infoは、有効であることが保証されているimage-indexでこのメソッドを呼び出します。そうでなければ、パラメーターと戻り値は、同じになります。