com.jblend.graphics.sprite
クラス SpriteCanvas

java.lang.Object
  |
  +--javax.microedition.lcdui.Displayable
        |
        +--javax.microedition.lcdui.Canvas
              |
              +--com.jblend.graphics.sprite.SpriteCanvas

public abstract class SpriteCanvas
extends javax.microedition.lcdui.Canvas

SpriteCanvas クラスはスプライトデータを操作するためのクラスです。


1. SpriteCanvas 概要

クラス構成

SpriteCanvasは、MIDPのCanvasクラスを継承したクラスです。Canvasの機能に加えて、スプライト描画機能を提供します。Javaアプリケーション側でSpriteCanvasまたはその派生クラスのインスタンスを生成して使用します。

SpriteCanvasの描画機能を使うには、通常のCanvas派生クラスの使い方と同様にDisplayオブジェクトのsetCurrent()メソッドによってSpriteCanvasオブジェクトを「現在のDisplayable」として指定します。そして、SpriteCanvasのメソッドを呼び出します。

SpriteCanvasの描画機能以外の、例えばキーイベントに関する制御などは、Canvasクラスの機構に沿って実装してください。例えばキーイベントを待ち受けるには、CanvasクラスのkeyPressed()などのメソッドをオーバーライドします。

機能概要

スプライトデータは、各画素256色、縦横それぞれ8画素の正方ブロックのグラフィックスデータです。SpriteCanvasでは、スプライトデータに対し、左右反転、上下反転、回転、カラーパレットによる色データ指定などの画像処理を行い、「仮想画面」や「フレームバッファ」に描画する機能を提供します。

仮想画面は移動機にひとつ存在し、その画面サイズは移動機に依存します。仮想画面の内容はフレームバッファに転送できます。フレームバッファはSpriteCanvasオブジェクトが保持する一種のスクリーンバッファで、JavaアプリケーションがSpriteCanvasのメソッドによって生成する必要があります。

典型的な使用方法では、Javaアプリケーションは仮想画面に描画した背景内容をフレームバッファに転送し、さらにその上にスプライトデータを描画した後、フレームバッファ全体を「実画面」に転送します。実画面に転送された画像は移動機の画面に表示され、ユーザーの目に見える形となります。Javaアプリケーションはこれらの処理をすべてSpriteCanvasのメソッドによって行います。なお、仮想画面への描画は、スプライトデータの描画だけでなく、MIDPのGraphicsクラスによる描画も可能です。

スプライトデータに対する画像処理は「スプライト処理コマンド」によって表現します。図1にスプライト処理コマンドの概念を示します。

sprite_command_model_jp.gif

図1. スプライト処理コマンドモデル

Javaアプリケーションは8*8画素のスプライトデータを用意してSpriteCanvasオブジェクトに登録します。SpriteCanvasオブジェクトはスプライトデータ配列を保持します。画像処理を伴う描画を実行しても、SpriteCanvasが保持するスプライトデータは変更されません。

スプライト処理コマンドには、処理の対象とするスプライトデータおよび画像処理の内容を設定します。図1の例では、スプライト処理コマンドcmd1、cmd2、cmd3、cmd4 はスプライトデータAを処理対象とし、それぞれ異なる角度の回転が指定されています。また、cmd5、cmd6、cmd9 はスプライトデータCを処理対象とし、それぞれ異なる色変換が指定されています。

Javaアプリケーションは、SpriteCanvasのメソッドを使用してスプライト処理コマンドを作成し、描画先の位置とともにSpriteCanvasの描画メソッドに指定してスプライト描画を要求します。スプライトをひとつ描画するごとにメソッドを呼び出す必要があります。仮想画面とフレームバッファそれぞれについて、描画メソッドが用意されています。

2. データ構造

ここでは、SpriteCanvasクラスで用いられるデータ構造を説明します。

2.1. スプライトデータ配列

図2にスプライトデータの構造を示します。

sprite_data_structure_jp.gif

図2. スプライトデータ構造

ひとつのスプライトデータは、縦横それぞれ8画素(計64画素)で、1画素あたり1バイトで表現します。図2の左側に示した走査方向で配置する必要があります。

Javaアプリケーションは、SpriteCanvasオブジェクトを生成するとき、登録可能なスプライトデータの数(最大256)をコンストラクタに指定します。SpriteCanvasオブジェクトは、この数を要素数とするスプライトデータ配列を内部に生成します。Javaアプリケーションは、この配列の個々の要素をsetPattern()メソッドによって登録する必要があります。このとき、図2の右側に示すように、先頭を0とし、最大値を255とするインデックス値で要素の位置を指定します。このインデックス値は、後述の「スプライト処理コマンド」で使用します。

2.2. カラーパレット

図3にカラーパレットの構造を示します。
sprite_color_palette_jp.gif

図3. スプライトデータ用カラーパレット

スプライトデータの各画素値を表現する1バイトは、図3に示す、24ビットカラー(パレット値)を要素とする配列(カラーパレット)のインデックス値です。パレット値は24ビットのRGB色空間上の色を、RGB各色1バイトのデータからR*0x10000 + G*0x100 + Bで演算した整数値(4バイト整数)です。画素値が決まると、カラーパレットの要素(以後パレットエントリと呼びます)によって、その画素の色が24ビットカラーで決定されます。

JavaアプリケーションがSpriteCanvasオブジェクトを生成するとき、登録可能なパレットエントリの数(最大256)を指定します。SpriteCanvasオブジェクトは、この数を要素数とするカラーパレットを内部に生成します。生成時のパレット値の値は0です。Javaアプリケーションは、この配列の個々の要素をsetPalette()メソッドによって登録する必要があります。

3.スプライト処理コマンド

スプライト処理コマンドはcreateCharacterCommand() メソッドで作成します。 このメソッドには表1に示す項目をパラメータとして与えます。

表1. スプライト処理コマンド
項目 内容
offset パレットオフセット(0〜7):
この値に32を掛けた値をスプライトデータの画素値に加算した結果の下位8ビットをカラーパレットインデックス値として画素の色を決定します。offsetの値を変化させることで、同じスプライトデータを異なる色で描画することが可能になります。ただし、フレームバッファへの描画で、かつtransparentがtrueのときは、画素値が0の画素は透明とみなされ、offsetの値は描画結果に反映されません。
transparent 透明色の利用(false: 透明色を利用しない、true: 透明色を利用する):
フレームバッファへの描画において、transparentがtrueの場合、値が0の画素は透明とみなされ、既に描画されている背景色のまま描画されます。これ以外の場合、すなわち仮想画面への描画の場合やフレームバッファへの描画においてtransparentがfalseの場合には、すべての画素はoffsetの値によるパレットオフセット処理を含めてカラーパレットの値により色が決定されます。
rotation 回転(0: 回転なし、1: 90度、2: 180度、3: 270度):
指定された回転角度で、スプライトデータを時計回り方向に回転します。
isUpsideDown 上下反転(false: 反転なし、 true: 反転):
"true"のとき、上下に反転します。
isRightsideLeft 左右反転(false: 反転なし、 true: 反転):
"true"のとき、左右に反転します。
patternNo スプライト番号:
スプライトデータをスプライトデータ配列のインデックス値で指定します。

スプライト処理コマンドが表現する画像処理の順番は、「回転」、「上下反転」、「左右反転」の順です。

Javaアプリケーションは、SpriteCanvasのcreateCharacterCommand()メソッドに表 2-1の項目を指定してスプライト処理コマンドを作成します。そして、作成したコマンドを、フレームバッファに描画する場合はdrawSpriteChar()メソッド、仮想画面に描画する場合はdrawBackground()メソッドにそれぞれ指定して描画を要求します。

4. 仮想画面/フレームバッファ/実画面

sprite_offscreens_jp.gif

図4. 画面バッファ(仮想画面、フレームバッファ)と実画面

SpriteCanvas では「仮想画面」、「フレームバッファ」の2つの画面バッファを使用します。「フレームバッファ」の内容を、最終的には「実画面」に転送することで実際に移動機の画面に表示します。図4に、これらの画面の関連を示します。

実画面
実画面は、移動機端末のLCDディスプレイに表示される画面のビデオメモリです。実画面に描画すると、LCDディスプレイに表示されます。実画面の幅と高さは、CanvasクラスのgetWidth()メソッド、およびgetHeight()でそれぞれ取得できます。

仮想画面
仮想画面は一種のオフスクリーンバッファで、スプライトデータで背景画像を描画するための画面として使用します。仮想画面は端末にひとつだけ存在し、その幅と高さは固定されています。幅と高さはSpriteCanvasクラスのスタティックメソッドgetVirtualWidth()、およびgetVirtualHeight()でそれぞれ取得できます。

フレームバッファ
フレームバッファも一種のオフスクリーンバッファで、仮想画面に描画した背景を転送し、その上にスプライトデータを描画する用途に使用します。最終的にはフレームバッファの内容は、実画面に転送してユーザーに表示します。 フレームバッファは、JavaアプリケーションがSpriteCanvasオブジェクトを生成した後に、createFrameBuffer()メソッドによってひとつ生成する必要があります。このとき、フレームバッファの幅、高さを指定しますが、これらの大きさは実画面のサイズ以下でなくてはなりません。 フレームバッファは移動機のメモリリソースを消費します。SpriteCanvasオブジェクトによる描画を必要としないときにはdisposeFrameBuffer()メソッドによってフレームバッファを解放できます。ただしdisposeFrameBuffer()メソッドが呼び出された時点で、フレームバッファに描画された内容は失われます。また、フレームバッファが生成されていない状態で、フレームバッファの存在を前提としたメソッドを呼び出すと例外が発生します。

画像転送
仮想画面の内容は、copyArea()メソッドでフレームバッファに転送できます。このとき、転送元の領域および転送先の位置を指定します。 フレームバッファの内容は、drawFrameBuffer()メソッドで実画面に転送できます。このとき、実画面上の転送先の位置を指定します。転送される領域のサイズはフレームバッファのサイズです。

仮想画面の内容は、画面内で移動できます。移動するにはcopyFullScreen()メソッドを用い、移動先の座標(dx, dy)を指定します。図5はdx、dyに両方とも正の値を指定した場合の例です。
sprite_scrolling_jp.gif

図5. 仮想画面のスクロール

copyArea()drawFrameBuffer()、またはcopyFullScreen()による転送や移動の結果、画面からはみ出た部分の画像は捨てられるだけで、例外は発生しません。

5. SpriteCanvasの使用手順

JavaアプリケーションがSpriteCanvasクラスを使用する場合の概略の使用手順を図6に示します。図6の右側には使用するメソッド名を記載しています。

sprite_ctrl_jp.gif

図6. SpriteCanvasクラス使用手順

  1. SpriteCanvasまたはその派生クラスのインスタンスを生成します。スプライトデータとカラーパレットそれぞれについての登録可能最大数をSpriteCanvasのコンストラクタに与えます。SpriteCanvasオブジェクトは指定された数でスプライトデータ配列とカラーパレット配列を保持します。

  2. 個々のスプライトデータを、SpriteCanvasオブジェクトにsetPattern()メソッドで登録します。また、個々のカラーパレットをsetPallete()メソッドでSpriteCanvasオブジェクトに登録します。スプライトデータとパレットが設定されていると、スプライトデータの描画が可能になります。

  3. DisplayオブジェクトのsetCurrent()メソッドを呼び出し、生成したSpriteCanvasオブジェクトを「現在のDisplayable」として指定します。

  4. SpriteCanvasのcreateFrameBuffer()でフレームバッファを生成します。このとき、フレームバッファの幅と高さを指定します。幅と高さは実画面のサイズ以下の値にしてください。

  5. スプライトデータを描画するためには、スプライト処理コマンドをcreateCharacterCommand()で作成します。そして、フレームバッファに描画するときはdrawSpriteChar()メソッドで、仮想画面に描画するときはdrawBackground()メソッドで描画します。いずれの場合もスプライト処理コマンドと画面(フレームバッファまたは仮想画面)上の描画位置を指定します。 仮想画面の内容は、copyFullScreen()メソッドで移動できます。また、仮想画面の内容は、copyArea()メソッドでフレームバッファに転送できます。 フレームバッファに形成した内容は、drawFrameBuffer()メソッドで実画面に転送するとユーザの目に見える形となります。

  6. スプライト描画処理を行わないときは、disposeFrameBuffer()でフレームバッファを開放できます。再開するときは、createFrameBuffer()によってフレームバッファを生成し直す必要があります。

  7. SpriteCanvasの使用を中断するには、別のDisplayable派生オブジェクトを「現在のDisplayable」として設定します。


クラス javax.microedition.lcdui.Canvas から継承したフィールド
DOWN, FIRE, GAME_A, GAME_B, GAME_C, GAME_D, KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_POUND, KEY_STAR, LEFT, RIGHT, UP
 
コンストラクタの概要
SpriteCanvas(int numPalettes, int numPatterns)
          SpriteCanvasコンストラクタ。
 
メソッドの概要
 void copyArea(int sx, int sy, int fw, int fh, int tx, int ty)
          仮想画面からフレームバッファへの転送を行う。
 void copyFullScreen(int tx, int ty)
          仮想画面全体を指定の位置にコピーする。
static short createCharacterCommand(int offset, boolean transparent, int rotation, boolean isUpsideDown, boolean isRightsideLeft, int patternNo)
          描画コマンドを作成する。
 void createFrameBuffer(int fw, int fh)
          フレームバッファを作成する。
 void disposeFrameBuffer()
          スプライト機能の利用を終了する。
 void drawBackground(short command, short x, short y)
          背景を仮想画面に描画する。
 void drawFrameBuffer(int tx, int ty)
          フレームバッファの内容を実画面に転送する。
 void drawSpriteChar(short command, short x, short y)
          スプライトキャラクターをフレームバッファに描画する。
static int getVirtualHeight()
          仮想画面の高さを取得する。
static int getVirtualWidth()
          仮想画面の幅を取得する。
 void setPalette(int index, int palette)
          パレットデータを設定する。
 void setPattern(int index, byte[] data)
          パターンデータを設定する。
 
クラス javax.microedition.lcdui.Canvas から継承したメソッド
getGameAction, getHeight, getKeyCode, getKeyName, getWidth, hasPointerEvents, hasPointerMotionEvents, hasRepeatEvents, hideNotify, isDoubleBuffered, keyPressed, keyReleased, keyRepeated, paint, pointerDragged, pointerPressed, pointerReleased, repaint, repaint, serviceRepaints, showNotify
 
クラス javax.microedition.lcdui.Displayable から継承したメソッド
addCommand, isShown, removeCommand, setCommandListener
 
クラス java.lang.Object から継承したメソッド
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

コンストラクタの詳細

SpriteCanvas

public SpriteCanvas(int numPalettes,
                    int numPatterns)
SpriteCanvasコンストラクタ。
パラメータ:
numPalettes - パレット数
numPatterns - パターン数
例外:
java.lang.IllegalArgumentException - パレット数、パターン数が1〜256でない場合に発生する。
メソッドの詳細

createFrameBuffer

public void createFrameBuffer(int fw,
                              int fh)
フレームバッファを作成する。
指定サイズのフレームバッファを作成します。 サイズは最大で実画面サイズです。 システム内で同時に1つのみ作成可能です。
パラメータ:
fw - フレームバッファの幅
fh - フレームバッファの高さ
例外:
IllegalStateException - フレームバッファが作成済みの場合に発生する。
java.lang.IllegalArgumentException - フレームバッファのサイズが実画面より大きい場合に発生する。
java.lang.RuntimeException - Nativeスプライト機能が設定に失敗した場合に発生する。

disposeFrameBuffer

public void disposeFrameBuffer()
スプライト機能の利用を終了する。
フレームバッファが作成されていない場合は何もしません。

getVirtualWidth

public static int getVirtualWidth()
仮想画面の幅を取得する。
戻り値:
int - 仮想画面の幅

getVirtualHeight

public static int getVirtualHeight()
仮想画面の高さを取得する。
戻り値:
int - 仮想画面の高さ

setPalette

public void setPalette(int index,
                       int palette)
パレットデータを設定する。 パレットデータは24bitである。
パラメータ:
index - パレットインデックス
palette - パレットデータ
例外:
ArrayIndexOutOfBoundsException - パレットインデックスがコンストラクタで 指定した数を超えた場合に発生する。
java.lang.RuntimeException - Nativeスプライト機能が設定に失敗した場合に発生する。

setPattern

public void setPattern(int index,
                       byte[] data)
パターンデータを設定する。 パターンデータは1キャラクタ8×8の64byteである。
パラメータ:
index - パターンインデックス
data - パターンデータ
例外:
ArrayIndexOutOfBoundsException - パターンインデックスがコンストラクタで 指定した数を超えた場合に発生する。
java.lang.IllegalArgumentException - 引数 data がnullまたは配列サイズが64以外の場合に発生する。
java.lang.RuntimeException - Nativeスプライト機能が設定に失敗した場合に発生する。

createCharacterCommand

public static short createCharacterCommand(int offset,
                                           boolean transparent,
                                           int rotation,
                                           boolean isUpsideDown,
                                           boolean isRightsideLeft,
                                           int patternNo)
描画コマンドを作成する。 効果は回転、上下反転、左右反転の順に適応される。
パラメータ:
offset - パレットオフセット(0〜7)
transparent - 透過色の利用(true:利用)
rotation - 回転(回転なし:0、90度:1、180度:2、270度:3)
isUpsideDown - 上下反転(true:反転)
isRightsideLeft - 左右反転(true:反転)
patternNo - パターン番号
例外:
java.lang.IllegalArgumentException - 不適切な値が指定された場合に発生する。

drawSpriteChar

public void drawSpriteChar(short command,
                           short x,
                           short y)
スプライトキャラクターをフレームバッファに描画する。 描画コマンドはcreateCharacterCommandで作成されたものを使用する。
パラメータ:
command - 描画コマンド
x - 描画X座標
y - 描画Y座標
例外:
java.lang.IllegalArgumentException - パターン番号がコンストラクタで指定した数を超えた 場合に発生する。
IllegalStateException - フレームバッファが未生成の場合に発生する。
java.lang.RuntimeException - Nativeスプライト機能が描画に失敗した場合に発生する。

drawBackground

public void drawBackground(short command,
                           short x,
                           short y)
背景を仮想画面に描画する。 描画コマンドはcreateCharacterCommandで作成されたものを使用する。 描画コマンドのうち、透過機能は無視される。 setCurrentされていない場合、描画は行わない。
パラメータ:
command - 描画コマンド
x - 描画X座標(8ピクセル単位)
y - 描画Y座標(8ピクセル単位)
例外:
java.lang.IllegalArgumentException - パターン番号がコンストラクタで指定した数を超えた場合に発生する。
java.lang.RuntimeException - Nativeスプライト機能が描画に失敗した場合に発生する。

copyArea

public void copyArea(int sx,
                     int sy,
                     int fw,
                     int fh,
                     int tx,
                     int ty)
仮想画面からフレームバッファへの転送を行う。 フレームバッファに描かれていたスプライトキャラクターは上書きされる。 setCurrentされていない場合、転送は行わない。
パラメータ:
sx - 転送元X座標
sy - 転送元Y座標
fw - コピーする幅
fh - コピーする高さ
tx - フレームバッファ上のX座標
ty - フレームバッファ上のY座標
例外:
IllegalStateException - フレームバッファが未生成の場合に発生する。
java.lang.IllegalArgumentException - 転送元座標が負の場合に発生する。
java.lang.IllegalArgumentException - フレームバッファのサイズ指定が異常な場合に発生する。
java.lang.RuntimeException - Nativeスプライト機能が描画に失敗した場合に発生する。

copyFullScreen

public void copyFullScreen(int tx,
                           int ty)
仮想画面全体を指定の位置にコピーする。 setCurrentされていない場合、コピーは行わない。
パラメータ:
tx - コピー先X座標
ty - コピー先Y座標
例外:
java.lang.RuntimeException - Nativeスプライト機能が描画に失敗した場合に発生する。

drawFrameBuffer

public void drawFrameBuffer(int tx,
                            int ty)
フレームバッファの内容を実画面に転送する。
パラメータ:
tx - 実画面のX座標
ty - 実画面のY座標
例外:
IllegalStateException - フレームバッファが未生成の場合に発生する。
java.lang.RuntimeException - Nativeスプライト機能が描画に失敗した場合に発生する。