javax.microedition.lcdui
クラス Image

java.lang.Object
  javax.microedition.lcdui.Image

public class Image
extends Object

Image クラスはグラフィカルなイメージ・データを保持するために使用します。 イメージ・オブジェクトはディスプレイ装置とは無関係に存在します。 それらはオフスクリーン・メモリに存在し、アプリケーションが明示的に表示するように記述する（Canvas オブジェクトの paint(Graphics) メソッド内において）か、Alert および Form スクリーンにイメージ・オブジェクトを設定し、そのスクリーンがカレントに設定されるまでディスプレイには表示されません。

イメージ・オブジェクトはそれが作成された方法によって不変タイプと可変タイプのいずれかになります。 不変タイプのイメージは、一般的にリソース・バンドルやファイル、ネットワーク等から固定的なイメージ・データをロードして作成されます。 このタイプのイメージは作成された後に内容を変更することはできません。 可変タイプのイメージは白のピクセルのみを含む空白のイメージとして作成します。 アプリケーションはこのタイプのイメージ・オブジェクトに対して任意の描画を行うことができます。

Image は Alert、Choice、Form または ImageItem の中に配置することができます。 高レベル・ユーザーインタフェースの実装は、アプリケーションに通知することなく、いつでも表示を更新する必要に迫られることがあります。 想定可能な振る舞いを提供するために、高レベル・ユーザーインタフェース・オブジェクトはスナップショットによるイメージを用います。 つまり、可変タイプのイメージが Alert、Choice、Form または ImageItem の中に配置される際に、現在の内容についてのスナップショットを作成します。 そして、このスナップショットを高レベル・ユーザーインタフェース・コンポーネントのその後の全ての描画で使用します。 アプリケーションがイメージの内容を変更したら、アプリケーションは変更した内容を表示するために、イメージを含むコンポーネントを更新（例えば ImageItem.setImage メソッドの呼び出し）しなければなりません。

可変タイプのイメージから createImage メソッドを使用して不変タイプのイメージを作成することができます。 同様に、以下のような記述を行うことで、不変タイプのイメージから可変タイプのイメージを作成することができます：

     Image source; // コピー元のイメージ
     source = Image.createImage(...);
     Image copy = Image.createImage(source.getWidth(), source.getHeight());
     Graphics g = copy.getGraphics();
     g.drawImage(source, 0, 0, TOP | LEFT);

アルファ処理

可変タイプのイメージに含まれるピクセルは常に全てが完全に不透明です。 不変タイプのイメージは完全に不透明なピクセル（alpha = 2bitdepth - 1）、完全に透明なピクセル（alpha = 0）、および半透明なピクセル（0 < alpha < 2bitdepth - 1）を含むことがあります（bitdepth がソース・データのサンプル辺りのビット数を示します）。

実装は不変タイプのイメージおいて、完全に不透明なピクセルと完全に透明なピクセルの格納、処理およびレンダリングをサポートしなければなりません。 ソース・データからイメージを作成する際（PNG ファイル、または ARGB データの配列に関わらず）に、ソース・データの完全に不透明なピクセルは新しいイメージにおいて常に完全に不透明なピクセルにしなければなりません。同様にソース・データの完全に透明なピクセルは新しいイメージにおいて常に完全に透明なピクセルにしなければなりません。

半透明の処理が必要なピクセル・データの扱いは実装がレンダリング時にアルファ・ブレンディングをサポートするか否かによります。 実装がアルファ・ブレンディングをサポートするなら、ソース・データの半透明なピクセルは新しいイメージにおいて半透明なピクセルにしなければなりません。 結果としてアルファ値はプラットフォームによってサポートされる半透明のレベル数に一致するように変更されることがあります（Display.numAlphaLevels() メソッドを参照してください）。 実装がアルファ・ブレンディングをサポートしないのであれば、新しいイメージではソース・データの半透明のピクセルは全て完全に透明なピクセルに置き換えなければなりません。

PNG イメージ・フォーマット

実装は「PNG(Portable Network Graphics : 可搬性のあるネットワーク・グラフィックス ) フォーマット バージョン 1.0」をサポートすることが要求されます。 また、PNG 仕様書によって定められた最小セットの要件に対して、全ての MIDP 実装は従う必要があります。 同様に、MIDP 実装は PNG イメージの取り扱いに関して、ここで与えられた追加の要件に従わなければなりません。 ここにリストアップした要件と矛盾する PNG 仕様書で定められたいかなる推奨にも優先することに注意してください。

重要なチャンク

PNG が指定する「重要な」チャンクの全てをサポートしなければなりません。 以下のパラグラフでこれらの重要なチャンクについて説明します。

IHDR チャンク

MIDP デバイスは IHDR チャンクに含まれる次の値を扱えなければなりません：

• 幅と高さが正数で指定される限りサポートします。 しかし、非常に巨大なイメージはメモリの制約により読み込むことができないことがあります。 結果として得られる Image オブジェクトの大きさは PNG イメージの大きさと一致しなければなりません。 つまり、値は getWidth() および getHeight() とレンダリングする際の幅と高さは等しくなければなりません。そしてその幅と高さは IHDR チャンクが指定するものです。
• イメージの表示品質はディスプレイ・デバイスの能力に依存しますが、カラー・タイプは全てサポートします。 アルファ・チャンネル・データを含んでいるカラー・タイプもサポートします。
• カラー・タイプ 4 および 6（それぞれ、グレースケールとアルファおよび RGB とアルファ）のアルファ・チャネルをデコードできなければなりません。 全てのピクセルにおいて、アルファ値がゼロである場合は透明であると扱わなければなりません。 全てのピクセルにおいて、アルファ値が 255（8 ビットイメージの場合）または 65535（16 ビットイメージの場合）の場合は不透明であると扱わなければなりません。 アルファ・ブレンディングによるレンダリングをサポートするなら、結果として得られるイメージに中間のアルファ値をそのまま反映しなければなりません。 アルファ・ブレンディングをサポートしないのであれば、中間のアルファ値を持つ全てのピクセルを完全に透明なピクセルに置き換えなければなりません。
• 指定されたカラー・タイプのための全ビット深度をサポートします。
• 圧縮方式 0（deflate）がサポートする唯一の圧縮方式です。 この方式は"zlib"圧縮技術を用います。これは jar ファイルにも用いられています。 このため、実装によっては展開するコードを JAR ファイルの読み出しを行うコードと共有することを選択することができます。 PNG 仕様で述べられるように、圧縮データストリーム内には圧縮および非圧縮の両方のデータを含むことができます。
• フィルタ方式は圧縮を最適化するために使用することができる、一連のエンコーディング・スキームを表します。 PNG 仕様は現在 5 つの基本となるフィルタ・タイプを適用型のフィルタリング・スキームである、1 つのフィルタ・メソッド（メソッド 0）に定義しています。 イメージの中で空間的な類似性を用いて deflate アルゴリズムによる最適な圧縮を行うために不可欠なフィルタリングを行います。 このため、MIDP デバイスはフィルタ・メソッド 0 によって定義される 5 つのフィルタ・タイプ全てをサポートしなければなりません。
• MIDP デバイスはインターレース方式 0（None）またはインターレース方式 1（Adam 7）によってエンコードされた PNG イメージを読み込めることが要求されます。 MIDP においてロードするイメージは静止画であるため、イメージのレンダリングによってオーバーラップが発生することはありません。 このため、アプリケーションにとってインターレース方式 1 を使用する利点は何もありません。 インターレース・イメージの読み込みサポートは、PNG が持つ互換性の確保および既に入手済みのインターレース・イメージを開発者が使用できるようにする利便性のために必要となります。

PLTE チャンク

パレットベースのイメージをサポートしなければなりません。

IDAT チャンク

イメージ・データはフィルタ・メソッド 0 によって定義された 5 つのフィルタ・タイプ（None、Sub、Up、Average、Paeth）のいずれかを使用してエンコードされます。

IEND チャンク

イメージが有効であると判断するためにこのチャンクを発見しなければなりません。

付随的なチャンク

PNG はいくつかの PNG イメージで存在するかもしれませんが、イメージのデコードには重要ではない「付随的な」チャンクを定義しています。

tRNS チャンクについて。 全ての実装は tRNS チャンクをサポートしなければなりません。 このチャンクは、各ピクセルのアルファ・チャネル・データに寄らないで透明を実装するために使用します。 カラー・タイプ 0 および 2 において、特定のグレーあるいは RGB 値を透明なピクセルとするように定義します。 この場合、これらの値が完全に透明な状態として実装はピクセルを扱わなければなりません。 オリジナルのイメージ・ビット深度を用いることで、ピクセル値の比較を実際のピクセル値に基づいて行わなければなりません； つまり、ピクセル値をデバイスの表示能力を反映するための再抽出を行う前に、この比較を行わなければなりません。 カラー・タイプ 3（インデックス化されたカラー）では、8 ビットのアルファ値をカラー・パレットの各エントリーに対して潜在的に提供します。 この場合、0 のアルファ値は完全に透明なピクセルとして扱わなければなりません。そして、それと同様に完全に不透明としてアルファ値が 255 のピクセルを扱わなければなりません。 アルファ・ブレンディングによるレンダリングをサポートするなら、結果として得られるイメージに中間のアルファ値をそのまま反映しなければなりません。 アルファ・ブレンディングをサポートしないのであれば、中間のアルファ値を持つ全てのピクセルを完全に透明なピクセルに置き換えなければなりません。

実装は他の付属的なチャンクのいずれかをサポートするかもしれません（しかし必須ではありません）。 実装は発見したサポートしない付随的なチャンクはエラーとせずに無視しなければなりません。 現在定義されている任意の付随的なチャンクは以下の通りです：

     cHRM gAMA hIST iCCP iTXt pHYs
     sBIT sPLT sRGB tEXt tIME zTXt

参考資料

Portable Network Graphics Specification. Version 1.0. W3C Recommendation, October 1, 1996. http://www.w3.org/TR/REC-png.html . Also available as RFC 2083, http://www.ietf.org/rfc/rfc2083.txt .

導入されたバージョン:

MIDP 1.0

createImage

public static Image createImage(int width,
                                int height)

オフスクリーンで描画を行うためのイメージ（可変タイプ）を作成します。 新しく作成されたイメージ内の全てのピクセルは白で塗り潰されています。 イメージの幅および高さはいずれも 0 以上でなければなりません。

パラメータ:

width - 新しく作成するイメージの幅を渡します。

height - 新しく作成するイメージの高さを渡します。

戻り値:

新しく作成したイメージを返します。

例外:

IllegalArgumentException - width あるいは height が不正な場合に throw します。

createImage

public static Image createImage(Image source)

指定されたイメージから不変タイプのイメージを作成します。 指定されたイメージが可変タイプのイメージの場合、イメージをコピーした不変タイプのイメージを作成して返します。 指定されたイメージが不変タイプのイメージの場合、実装は新しいイメージを作成せずに、そのイメージをそのまま返します。 不変タイプのソース・イメージが透明情報を含んでいるなら、この情報は新しいイメージに変わりがない状態でコピーします。

このメソッドは可変イメージの内容を Choice オブジェクトに設置するのに役立ちます。 アプリケーションは createImage(w, h) メソッドを使用してオフスクリーンを作成し、getGraphics() メソッドで得たグラフィックス・オブジェクトを使用して描画を行い、続いてこのメソッドで不変タイプのイメージにコピーします。 そして、不変タイプのイメージのコピーを Choice オブジェクトに設置することができます。

パラメータ:

source - コピーする対象のソース・イメージを渡します。

戻り値:

新しく作成した不変タイプのイメージを返します。

createImage

public static Image createImage(String name)
                         throws IOException

指定された名前のリソースからイメージ・データを取得し、デコードした結果を持つ不変タイプのイメージを返します。 name パラメータは、class.getResourceAsStream(name) によって定義されたリソース名です。 リソース名を解決するための規則は java.lang パッケージドキュメントのアプリケーション・リソース・ファイルで定義されています。

パラメータ:

name - サポートしているイメージ・フォーマットのうちの１つのイメージ・データを含んでいるリソースの名前を渡します。

戻り値:

作成したイメージを返します。

例外:

IOException - 指定されたリソースが存在しないか、データの読み出しができないか、イメージ・データがデコードできない場合に throw します。

createImage

public static Image createImage(byte[] imagedata,
                                int imageoffset,
                                int imagelength)

指定されたバイト配列内にに格納されたデータから、指定されたオフセットと長さのデータをデコードして不変タイプのイメージを作成します。 データは PNG のような実装がサポートする、自己認識可能なイメージ・ファイルでなければなりません。

imageoffset と imagelength パラメータは imagedata バイト配列内のデータを指定します。 imageoffset はバイト配列内の使用開始位置を指定します。 つまり、imageoffset は、0 〜 imagedata.length - 1 の範囲内でなければなりません。 imagelength は使用するデータのバイト数を指定します。 これは正数でなければならず、imageoffset + imagelength が imagedata.length を超えてはなりません。

このメソッドは永続的な記憶装置やネットワークなどの多様なソースからイメージをロードする場合に使用します。

パラメータ:

imagedata - サポートするイメージ・データを格納したバイト配列を渡します。

imageoffset - バイト配列内のデータの開始位置を渡します。

imagelength - バイト配列内のデータの長さを渡します。

戻り値:

作成したイメージを返します。

例外:

ArrayIndexOutOfBoundsException - imageoffset あるいは imagelength が不正な場合に throw します。

NullPointerException - imageoffset が null である場合に throw します。

IllegalArgumentException - imagedata のフォーマットに誤りがあるかサポートしていないフォーマットの場合に throw します。

createImage

public static Image createImage(Image image,
                                int x,
                                int y,
                                int width,
                                int height,
                                int transform)

指定したように変形させ、ソース・イメージから指定した矩形のピクセルを用いて不変タイプのイメージを作成します。

ソース・イメージは可変または不変タイプのいずれでもかまいません。 ソース・イメージが不変タイプで透明情報が存在するならば、新しいイメージに変化させずにコピーします。

デバイスによっては、あらかじめ変形しているイメージは、より高速に描画するために drawRegion を用いてその場（on the fly）でイメージを変形するかもしれません。 しかし、そのようにイメージを作成するとヒープ・スペースを追加で消費するため、このテクニックは描画速度が重要であるイメージについてのみ適用すべきです。

使用できる変形機能は Sprite クラスで定義されている以下の１つでなければなりません：
Sprite.TRANS_NONE - 指定されたイメージ領域を変形せずにコピーします。
Sprite.TRANS_ROT90 - 指定されたイメージ領域を時計回りに９０度回転してコピーします。
Sprite.TRANS_ROT180 - 指定されたイメージ領域を時計回りに１８０度回転してコピーします。
Sprite.TRANS_ROT270 - 指定されたイメージ領域を時計回りに２７０度回転してコピーします。
Sprite.TRANS_MIRROR - 指定されたイメージ領域を水平中央辺りで反転してコピーします。
Sprite.TRANS_MIRROR_ROT90 - 指定されたイメージ領域を水平中央辺りで反転した後、時計回りに９０度回転してコピーします。
Sprite.TRANS_MIRROR_ROT180 - 指定されたイメージ領域を水平中央辺りで反転した後、時計回りに１８０度回転してコピーします。
Sprite.TRANS_MIRROR_ROT270 - 指定されたイメージ領域を水平中央辺りで反転した後、時計回りに２７０度回転してコピーします。

返されるイメージのサイズは変形が適用された指定した領域のサイズとなります。 例えば領域が 100 x 50 ピクセルで transform が Sprite.TRANS_ROT90 である場合、返されるイメージは 50 x 100 となります。

注記：以下の条件を全て満たすなら、このメソッドは新しいオブジェクトを作成せずに、そのままソース・イメージ image を返すことがあります：

• ソース・イメージは不変タイプ；
• 領域の指定はソース・イメージの全体を示す；
  そして
• 変形の指定が TRANS_NONE

パラメータ:

image - コピーするソース・イメージを渡します。

x - コピーする領域の水平位置（X 座標）を渡します。

y - コピーする領域の垂直位置（Y 座標）を渡します。

width - コピーする領域の幅を渡します。

height - コピーする領域の高さを渡します。

transform - 領域に適する変形値を渡します。

戻り値:

新しい不変タイプのイメージを返します。

例外:

NullPointerException - image が null ならば throw します。

IllegalArgumentException - コピーすべき領域がソース・イメージのそれを超えているか、width または height がゼロまたはそれ以下であるか、transform が不正な値であれば throw します。

導入されたバージョン:

MIDP 2.0

createImage

public static Image createImage(InputStream stream)
                         throws IOException

InputStream オブジェクトから得たイメージ・データをデコードして不変タイプのイメージを作成します。 このメソッドは全てのイメージ・データの読み出しおよびデコードが完了するまでブロックします。 このメソッドによる処理が完了（通常処理で戻るか、または例外を throw したかに関わらず）したあとも、stream はオープン状態を維持しますが、現在位置は未定義です。

パラメータ:

stream - サポートするイメージ・フォーマットの１つのイメージ・データを含むリソースに接続したストリームを渡します。

戻り値:

作成したイメージを返します。

例外:

NullPointerException - stream が null である場合に throw します。

IOException - 入出力でエラーが発生するか、イメージ・データをロードできない場合か、イメージ・データをデコードできない場合に throw します。

導入されたバージョン:

MIDP 2.0

getGraphics

public Graphics getGraphics()

このイメージに描画を行う新しいグラフィックス・オブジェクトを作成します。 このメソッドによって Graphics オブジェクトを作成できるのは可変タイプのみです。 不変タイプの Image オブジェクトに対してこのメソッドを呼び出すと IllegalStateException を throw します。 Image オブジェクトが可変タイプであるかどうかは isMutable() メソッドで調べることができます。

新しく作成された Graphics オブジェクトは次の特性を持っています：

• 描画先はこの Image オブジェクトです；
• クリップ領域は Image 全体です；
• カレントのカラーは黒です；
• フォントは Font クラスの getDefaultFont() メソッドで返されるフォントと同一です；
• ストローク・スタイルは SOLID です； そして
• 座標の原点はイメージの左上コーナーに位置します。

このメソッドを使用して作成した Graphics オブジェクトの寿命は無期限です。 また、オブジェクトは任意のスレッドによっていつでも使用することができます。

戻り値:

このイメージに描画するためのグラフィックス・オブジェクトを返します。

例外:

IllegalStateException - イメージが不変モードの場合に throw します。

getWidth

public int getWidth()

イメージの幅をピクセル数で返します。 返す値はレンダリングを行うイメージの実際の幅を反映していなければなりません。

戻り値:

イメージの幅を返します。

getHeight

public int getHeight()

イメージの高さをピクセル数で返します。 返す値はレンダリングを行うイメージの実際の高さを反映していなければなりません。

戻り値:

イメージの高さを返します。

isMutable

public boolean isMutable()

このイメージが可変タイプであるか否かを判定します。 可変タイプの場合、このオブジェクトの getGraphics() メソッドから得た Graphics オブジェクトによって描画を行うことができます。

戻り値:

可変タイプの場合は true を、そうでなければ false を返します。

createRGBImage

public static Image createRGBImage(int[] rgb,
                                   int width,
                                   int height,
                                   boolean processAlpha)

0xAARRGGBB で指定された ARGB 値による配列から不変タイプのイメージを作成します。 rgb 配列の行は水平に左から右へ、行ごとに上から下へ向けて配置します。 processAlpha が true ならば、高位バイトは透明度を指定します； つまり、0x00RRGGBB は完全に透明なピクセルを意味し、0xFFRRGGBB は完全に不透明なピクセルを意味します。 中間的な値は半透明を意味します。 実装がイメージレンダリング操作においてアルファ・ブレンディングをサポートしないなら、全ての半透明なピクセルを完全な透明なピクセルに置き換えなければなりません（さらに踏み込んだ内容についてはアルファ処理を参照してください）。 processAlpha が false であるなら、アルファ値を無視して、全てのピクセルを完全に不透明として扱わなければなりません。

P(a,b) がイメージの列 a と行 b が示す位置のピクセルの値を意味し、行と列は上端をゼロとして開始し、下へ向かって付番し、行は左端をゼロとして開始し、右へ向かって付番すると考えてください。 この操作は以下のように定義することができます：

     P(a, b) = rgbData[offset + (a - x) + (b - y) * width]

条件：

     x <= a < x + width
     y <= b < y + height

パラメータ:

rgb - イメージを構成する ARGB 値配列を渡します。

width - イメージの幅を渡します。

height - イメージの高さを渡します。

processAlpha - アルファ・チャネルを含む場合は true を、ピクセルは全て完全に不透明なら false を渡します。

戻り値:

作成されたイメージを返します。

例外:

NullPointerException - rgb が null である場合に throw します。

IllegalArgumentException - 幅あるいは高さのどちらがゼロあるいはそれ以下である場合に throw します。

ArrayIndexOutOfBoundsException - rgb の長さが width * height よりも短い場合に throw します。

導入されたバージョン:

MIDP 2.0

getRGB

public void getRGB(int[] rgbData,
                   int offset,
                   int scanlength,
                   int x,
                   int y,
                   int width,
                   int height)

このイメージの指定された矩形から ARGB ピクセル・データを取得して、提供された整数配列に格納します。 各ピクセル地は 0xAARRGGBB 形式で格納します。それは、高位バイトにアルファ・チャネル、残りのバイトにはカラー成分の赤、緑および青を含みます。 アルファ・チャネルはピクセルの透明度を指定します。その値が 0x00 ならば完全に透明なピクセルであることを示し、その値が 0xFF ならば完全に不透明なピクセルであることを示します。

返す値は、createRGBImage や PNG イメージなどのオリジナル・ソースからの値と同一であることは保証されません。 カラー値はデバイスの表示能力を反映して再構成されているかもしれません（例えば、赤、緑または青のピクセルはグレースケールデバイスにて同じグレー値で全て表されるかもしれません）。 アルファ・ブレンディングをサポートしないデバイスでは、アルファ値が 0xFF のピクセルを完全に不透明として扱い、アルファ値が 0x00 およびその他の値のピクセルは完全に透明として扱います（さらに詳細な解説はアルファ処理を参照してください）。 アルファ・ブレンディングをサポートするデバイスでは、アルファ・チャネルの値はサポートする半透明レベルの段階数に応じて再構成されているかもしれません。

P(a,b) がイメージの列 a と行 b が示す位置のピクセルの値を意味し、行と列は上端をゼロとして開始し、下へ向かって付番し、行は左端をゼロとして開始し、右へ向かって付番すると考えてください。 この操作は以下のように定義することができます：

     P(a, b) = rgbData[offset + (a - x) + (b - y) * scanlength]

条件：

     x <= a < x + width
     y <= b < y + height

ソース矩形がイメージの領域を超えないことが必要です。この条件：

     x >= 0
     y >= 0
     x + width <= image width
     y + height <= image height

これらの条件のいずれかが満たされない場合は IllegalArgumentException を throw します。 このほかでは、width <= 0 あるいは height <= 0 という場合にはどのような例外も throw されずに、ピクセル・データは何も rgbData にコピーされません。

パラメータ:

rgbData - ARGB ピクセル・データを格納する整数配列を渡します。

offset - 最初の ARGB 値を格納する配列のインデックスを渡します。

scanlength - 配列の連続した列に対応するピクセル範囲の配列オフセットに対応する値を渡します。

x - 領域の左上角の X 座標を渡します。

y - 領域の左上角の Y 座標を渡します。

width - 領域の幅を渡します。

height - 領域の高さを渡します。

例外:

ArrayIndexOutOfBoundsException - 要求した操作による rgbData の要素へのインデックス・アクセスが負数あるいは長さを超えた場合に throw します。

IllegalArgumentException - 指定された領域がソース・イメージの範囲を超える場合および scanlength の絶対値が width よりも小さい場合に throw します。

NullPointerException - rgbData が null の場合に throw します。

導入されたバージョン:

MIDP 2.0