Graphics2DFramework ライブラリ
- 目次 -
概要 - Abstract
このライブラリ graphics2d.Graphics2DFramework は、2DCG( 2次元グラフィックス )を手軽に扱うための軽量フレームワークです。
VCSSLの標準ライブラリ「 Graphics2D 」や「 GUI 」だけを用いて、ゼロから2DCGプログラムを記述する場合、
ウィンドウ・レンダラー(描画エンジン)の生成や、アニメーションループ、基本的なイベントハンドラなど、いくつかの定型的な処理を、毎回記述しなければいけません。
そこで、この Graphics2DFramework では、上述のような定型処理を、雛形のようにあらかじめ用意する事によって、手軽な2DCG利用をサポートします。
・必要な処理の記述
Graphics2DFramework は、構造的には、単体で既に完成した2DCGプログラムです。実際、単体で実行する事が可能です。
ただし、単体では何の描画内容も無いため、ただ白い画面が表示されるだけです。
そこで実際には、自作モジュールから Graphics2DFramework を import し、3Dモデルの配置や移動など、必要な処理を記述します。
そういった処理は、いくつかの決まった名前の関数を定義し、そこに記述します。つまり、GUIなどのイベントハンドラと同じ仕組みです。
するとそれらのイベントハンドラ関数を、Graphics3DFramework が適切なタイミングで自動実行します。
Graphics2DFramework が自動実行するイベントハンドラ関数は、下記のものがあります。定義は必須では無いので、必要な関数だけを定義し、記述して下さい。
- void onStart( int renderer ) - 起動時に一度だけ実行されます。スプライトの生成・配置などの初期化処理は、ここに記述します。旧称 initialize も使用可能です。
- void onExit( int renderer ) - 終了時に一度だけ実行されます。終了時に行いたい処理があれば、ここに記述します。旧称 finalize も使用可能です。
- void onPaint( int renderer ) - 画面更新タイミング(毎秒数十回)で毎回実行されます。アニメーションの2DCG描き込み(直接描画)を行いたい場合などは、ここに記述します。旧称 paint も使用可能です。
- void onUpdate( int renderer ) - 画面更新タイミング(毎秒数十回)の間で毎回実行されます。スプライトの移動などを行いたい場合などは、ここに記述します。旧称 update も使用可能です。
- void onResize( int renderer ) - ウィンドウサイズが変更された場合に実行されます。画面に配置したGUI部品のレイアウト調整などを行いたい場合は、ここに記述します。旧称 resize も使用可能です。
・ウィンドウのカスタマイズ
Graphics2DFramework では、ウィンドウ内に余白領域を設定し、そこにボタンやテキストフィールドなどのGUI部品を配置する事ができます。
余白の設定は、setMarginTop ( int margin ) 関数や setMarginLeft ( int margin ) 関数などで行います。
そして getWindow ( ) 関数でウィンドウのIDを取得し、余白領域にGUI部品を自由に配置してください。
・フレームレート調整
加えて、Graphics2DFramework は、フレームレートの自動調整機構も備えています。
具体的には、Graphics2DFramework は、毎フレーム間の所要時間を計測し、常に設定された目標フレームレートに近づくよう、アニメーションループのウェイト ( 待機時間 ) を自動調整します。
目標フレームレートは setFrameRate ( float rate ) で設定します。また、実測フレームレートは getCurrentFrameRate ( ) で取得可能です。
・処理落ち
なお、実行環境の処理速度にも依存しますが、描画する画面サイズが大きかったり、描画内容が重かったりすると、
アニメーションの待機時間を最小にしても、実測フレームレートが目標フレームレートに達しなくなる現象 ―― 処理落ち ―― が生じます。
処理落ちが発生すると、画面の再描画処理が追いつかなくなり、画面がちらつく場合があります。
その場合は、目標フレームレートを実測フレームレートの限界よりも余裕のある値に設定する事で、画面のちらつきを抑える事ができます。
しかし、実測フレームレートは環境に大きく依存するため、代わりに setAnimationWaitMin ( int wait ) 関数でアニメーションウェイトの下限値(ミリ秒単位)を大きめに設定する事でも、
画面のちらつきを抑える事ができます( ただしこの場合、実測フレームレートの限界は低下します )。
目次 - Index
- int getGraphics()
- 2DCGのグラフィックスIDを返します。
- int getRenderer()
- 2DCGのレンダラーIDを返します。
- int getImageLabel()
- 描画内容を表示する、画像ラベルのGUIコンポーネントIDを返します。
- int getGraphicsLabel()
- 画像ラベルのGUIコンポーネントIDを返します。この関数には、より新しい getImageLabel がサポートされています。この関数は互換目的でサポートされています。
- int getWindow()
- ウィンドウのGUIコンポーネントIDを返します。
- void setAnimationState(bool enable)
- アニメーションモードの有効/無効を設定します。
- bool getAnimationState()
- アニメーションの有効/無効を取得します。
- void setFrameRate(float rate)
- アニメーションの画面更新頻度( 1秒間あたりの描画回数 )を設定します。
- float getFrameRate()
- アニメーションの画面更新頻度( 1秒間あたりの描画回数 )の設定値を取得します。
- float getCurrentFrameRate()
- アニメーションの画面更新頻度( 1秒間あたりの描画回数 )の実測値を取得します。
- int getLastFrameTime()
- アニメーションの最終画面更新時刻を取得します。時刻は、プログラム開始時刻からの経過時間を、通常はミリ秒単位で表したものが返されます。ただし単位は処理系によって異なる可能性があります。処理系の依存性を完全に排除するためには、Time.millisecond関数を挟んで使用して下さい。
- void setPaintGraphics2DState(bool b)
- 画面描画時(paintコール前)に、自動でGraphics2D.paintGraphics2Dをコールするかどうかを設定します。trueを指定すると自動でコールされます。falseに設定すると自動でコールされないので、paintイベントハンドラなどで明示的にコールする必要があります。
- bool getPaintGraphics2DState()
- 画面描画時(paintコール前)に、自動でGraphics2D.paintGraphics2Dをコールするかどうかを取得します。
- void setBackgroundColor(int r, int g, int b, int a)
- 背景色を設定します。引数には、背景色の 赤,緑,青,α成分 を、0〜255の範囲で指定します。
- void setBackgroundColor(int color[ ])
- 背景色を設定します。引数には、背景色の 赤,緑,青,α成分 を、0〜255の範囲で格納した配列を指定します。
- int[ ] getBackgroundColor()
- 背景色を取得します。戻り値には、背景色の 赤,緑,青,α成分 を、0〜255の範囲で格納した配列が返されます。
- void setWindowTitle(string title)
- ウィンドウタイトルを設定します。
- string getWindowTitle()
- ウィンドウタイトルを取得します。
- void setWindowSize(int width, int height)
- ウィンドウサイズを設定します。
- void setWindowSize(int size[ ])
- ウィンドウサイズを設定します。
- int[ ] getWindowSize()
- ウィンドウサイズを取得します。
- void setWindowLocation(int x, int y)
- ウィンドウの位置を設定します。
- void setWindowLocation(int location[ ])
- ウィンドウの位置を設定します。
- int[ ] getWindowLocation()
- ウィンドウの位置を取得します。
- void setMarginRight(int margin)
- ウィンドウ右側の余白を設定します。
- int getMarginRight()
- ウィンドウ右側の余白を取得します。
- void setMarginLeft(int margin)
- ウィンドウ左側の余白を設定します。
- int getMarginLeft()
- ウィンドウ左側の余白を取得します。
- void setMarginTop(int margin)
- ウィンドウ上側の余白を設定します。
- int getMarginTop()
- ウィンドウ上側の余白を取得します。
- void setMarginBottom(int margin)
- ウィンドウ下側の余白を設定します。
- int getMarginBottom()
- ウィンドウ下側の余白を取得します。
- void setAnimationWaitMin(int wait)
- アニメーションウェイト(メインループのウェイト)の下限値を設定します。
- int getAnimationWaitMin()
- アニメーションウェイト(メインループのウェイト)の下限値を設定します。
- void setAnimationWaitMax(int wait)
- アニメーションウェイト(メインループのウェイト)の上限値を設定します。
- int getAnimationWaitMax()
- アニメーションウェイト(メインループのウェイト)の上限値を設定します。
- void setMainLoopState(bool state)
- メインループの継続状態を設定します。falseに設定するとアニメーションのメインループを脱出し、プログラムを終了します。
- bool getMainLoopState()
- メインループの継続状態を取得します。
- string[ ] getMainArgument()
- main関数の引数を取得します。
- void export( string filePath, string format, float quality )
- 現在の描画ラベルの内容を、画像ファイルに出力します。ファイルの出力は、この関数をコールした瞬間に行われるわけでは無く、次回の画面更新タイミングに合わせて実行されます。
- void main( string args[ ] )
- main関数です。通常は自動で実行され、frameworkMain関数をコールします。ただし、メインプログラムでmain関数を定義する場合は、こちらは自動で実行されなくなるので、下記のframeworkMainを明示的に呼ぶ必要があります。
- void frameworkMain( string args[ ] )
- フレームワークのメイン処理です。通常はmain関数から自動で実行されます。ただし、メインプログラムでmain関数を定義する場合は、自動で実行されなくなるので、適当なタイミングで呼ぶ必要があります。
- void onWindowResize( int id, int width, int height )
- ウィンドウがリサイズされた際にコールされるイベントハンドラです。
- void onWindowClose( int id )
- ウィンドウが閉じられた際にコールされるイベントハンドラです。
- void paintWindow()
- ウィンドウの再描画を行います。アニメーションの画面更新タイミングで自動的にコールされますが、任意のタイミングで明示的に呼び出して再描画させる事も可能です。
- void render()
- paint関数などをコールし、画面表示内容を描画します。通常は自動で実行されますが、アニメーションを無効にしている場合などは、画面更新時に明示的に呼び出す必要があります。
構造体 - Structs
- なし - None -
変数 - Variables
- なし - None -
関数 - Functions
文法的定義 - Signature |
int getGraphics() |
関数名 - Name |
getGraphics |
役割 - Role |
2DCGのグラフィックスIDを返します。 |
戻り値 - Return |
(int型) 2DCGのグラフィックスID |
文法的定義 - Signature |
int getRenderer() |
関数名 - Name |
getRenderer |
役割 - Role |
2DCGのレンダラーIDを返します。 |
戻り値 - Return |
(int型) 2DCGのレンダラーID |
文法的定義 - Signature |
int getImageLabel() |
関数名 - Name |
getImageLabel |
役割 - Role |
描画内容を表示する、画像ラベルのGUIコンポーネントIDを返します。 |
戻り値 - Return |
(int型) 画像ラベルのGUIコンポーネントID |
文法的定義 - Signature |
int getGraphicsLabel() |
関数名 - Name |
getGraphicsLabel |
役割 - Role |
画像ラベルのGUIコンポーネントIDを返します。この関数には、より新しい getImageLabel がサポートされています。この関数は互換目的でサポートされています。 |
戻り値 - Return |
(int型) 描画領域ラベルのGUIコンポーネントID |
文法的定義 - Signature |
int getWindow() |
関数名 - Name |
getWindow |
役割 - Role |
ウィンドウのGUIコンポーネントIDを返します。 |
戻り値 - Return |
(int型) ウィンドウのGUIコンポーネントID |
文法的定義 - Signature |
void setAnimationState(bool enable) |
関数名 - Name |
setAnimationState |
役割 - Role |
アニメーションモードの有効/無効を設定します。 |
引数 - Arguments |
(bool型) enable : アニメーションモードの有効/無効(trueならば有効) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
bool getAnimationState() |
関数名 - Name |
getAnimationState |
役割 - Role |
アニメーションの有効/無効を取得します。 |
戻り値 - Return |
(bool型) アニメーションモード有効/無効(trueならば有効) |
文法的定義 - Signature |
void setFrameRate(float rate) |
関数名 - Name |
setFrameRate |
役割 - Role |
アニメーションの画面更新頻度( 1秒間あたりの描画回数 )を設定します。 |
引数 - Arguments |
(float型) rate : 画面更新頻度 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
float getFrameRate() |
関数名 - Name |
getFrameRate |
役割 - Role |
アニメーションの画面更新頻度( 1秒間あたりの描画回数 )の設定値を取得します。 |
戻り値 - Return |
(float型) 画面更新頻度(設定値) |
文法的定義 - Signature |
float getCurrentFrameRate() |
関数名 - Name |
getCurrentFrameRate |
役割 - Role |
アニメーションの画面更新頻度( 1秒間あたりの描画回数 )の実測値を取得します。 |
戻り値 - Return |
(float型) 画面更新頻度(実測値) |
文法的定義 - Signature |
int getLastFrameTime() |
関数名 - Name |
getLastFrameTime |
役割 - Role |
アニメーションの最終画面更新時刻を取得します。時刻は、プログラム開始時刻からの経過時間を、通常はミリ秒単位で表したものが返されます。ただし単位は処理系によって異なる可能性があります。処理系の依存性を完全に排除するためには、Time.millisecond関数を挟んで使用して下さい。 |
戻り値 - Return |
(int型) 最終画面更新時刻(通常はミリ秒単位) |
文法的定義 - Signature |
void setPaintGraphics2DState(bool b) |
関数名 - Name |
setPaintGraphics2DState |
役割 - Role |
画面描画時(paintコール前)に、自動でGraphics2D.paintGraphics2Dをコールするかどうかを設定します。trueを指定すると自動でコールされます。falseに設定すると自動でコールされないので、paintイベントハンドラなどで明示的にコールする必要があります。 |
引数 - Arguments |
state : 設定した状態 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
bool getPaintGraphics2DState() |
関数名 - Name |
getPaintGraphics2DState |
役割 - Role |
画面描画時(paintコール前)に、自動でGraphics2D.paintGraphics2Dをコールするかどうかを取得します。 |
戻り値 - Return |
(bool型) 取得した状態 |
文法的定義 - Signature |
void setBackgroundColor(int r, int g, int b, int a) |
関数名 - Name |
setBackgroundColor |
役割 - Role |
背景色を設定します。引数には、背景色の 赤,緑,青,α成分 を、0〜255の範囲で指定します。 |
引数 - Arguments |
(int型) r : 背景色(赤、0〜255) (int型) g : 背景色(緑、0〜255) (int型) b : 背景色(青、0〜255) (int型) a : 背景色(α成分、0〜255) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void setBackgroundColor(int color[ ]) |
関数名 - Name |
setBackgroundColor |
役割 - Role |
背景色を設定します。引数には、背景色の 赤,緑,青,α成分 を、0〜255の範囲で格納した配列を指定します。 |
引数 - Arguments |
(int[]型) color : 背景色配列([0]=赤、[1]=緑、[2]=青、[3]=α成分、各0〜255) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int[ ] getBackgroundColor() |
関数名 - Name |
getBackgroundColor |
役割 - Role |
背景色を取得します。戻り値には、背景色の 赤,緑,青,α成分 を、0〜255の範囲で格納した配列が返されます。 |
戻り値 - Return |
(int[]型) 背景色配列([0]=赤、[1]=緑、[2]=青、[3]=α成分、各0〜255) |
文法的定義 - Signature |
void setWindowTitle(string title) |
関数名 - Name |
setWindowTitle |
役割 - Role |
ウィンドウタイトルを設定します。 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
string getWindowTitle() |
関数名 - Name |
getWindowTitle |
役割 - Role |
ウィンドウタイトルを取得します。 |
戻り値 - Return |
(string型) |
文法的定義 - Signature |
void setWindowSize(int width, int height) |
関数名 - Name |
setWindowSize |
役割 - Role |
ウィンドウサイズを設定します。 |
引数 - Arguments |
(int型) width : 幅 (int型) height : 高さ |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void setWindowSize(int size[ ]) |
関数名 - Name |
setWindowSize |
役割 - Role |
ウィンドウサイズを設定します。 |
引数 - Arguments |
(int[]型) size : ウィンドウサイズ([0]=幅、[1]=高さ) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int[ ] getWindowSize() |
関数名 - Name |
getWindowSize |
役割 - Role |
ウィンドウサイズを取得します。 |
戻り値 - Return |
(int[]型) ウィンドウサイズ([0]=幅、[1]=高さ) |
文法的定義 - Signature |
void setWindowLocation(int x, int y) |
関数名 - Name |
setWindowLocation |
役割 - Role |
ウィンドウの位置を設定します。 |
引数 - Arguments |
(int型) x : ウィンドウ左上のX座標 (int型) y : ウィンドウ左上のY座標 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void setWindowLocation(int location[ ]) |
関数名 - Name |
setWindowLocation |
役割 - Role |
ウィンドウの位置を設定します。 |
引数 - Arguments |
size : ウィンドウ左上の座標([0]=X座標、[1]=Y座標) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int[ ] getWindowLocation() |
関数名 - Name |
getWindowLocation |
役割 - Role |
ウィンドウの位置を取得します。 |
戻り値 - Return |
(int[]型) ウィンドウ左上の座標([0]=X座標、[1]=Y座標) |
文法的定義 - Signature |
void setMarginRight(int margin) |
関数名 - Name |
setMarginRight |
役割 - Role |
ウィンドウ右側の余白を設定します。 |
引数 - Arguments |
(int型) margin : 余白(ピクセル) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int getMarginRight() |
関数名 - Name |
getMarginRight |
役割 - Role |
ウィンドウ右側の余白を取得します。 |
戻り値 - Return |
(int型) 余白(ピクセル) |
文法的定義 - Signature |
void setMarginLeft(int margin) |
関数名 - Name |
setMarginLeft |
役割 - Role |
ウィンドウ左側の余白を設定します。 |
引数 - Arguments |
m : 余白(ピクセル) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int getMarginLeft() |
関数名 - Name |
getMarginLeft |
役割 - Role |
ウィンドウ左側の余白を取得します。 |
戻り値 - Return |
(int型) 余白(ピクセル) |
文法的定義 - Signature |
void setMarginTop(int margin) |
関数名 - Name |
setMarginTop |
役割 - Role |
ウィンドウ上側の余白を設定します。 |
引数 - Arguments |
m : 余白(ピクセル) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int getMarginTop() |
関数名 - Name |
getMarginTop |
役割 - Role |
ウィンドウ上側の余白を取得します。 |
戻り値 - Return |
(int型) 余白(ピクセル) |
文法的定義 - Signature |
void setMarginBottom(int margin) |
関数名 - Name |
setMarginBottom |
役割 - Role |
ウィンドウ下側の余白を設定します。 |
引数 - Arguments |
m : 余白(ピクセル) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int getMarginBottom() |
関数名 - Name |
getMarginBottom |
役割 - Role |
ウィンドウ下側の余白を取得します。 |
戻り値 - Return |
(int型) 余白(ピクセル) |
文法的定義 - Signature |
void setAnimationWaitMin(int wait) |
関数名 - Name |
setAnimationWaitMin |
役割 - Role |
アニメーションウェイト(メインループのウェイト)の下限値を設定します。 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int getAnimationWaitMin() |
関数名 - Name |
getAnimationWaitMin |
役割 - Role |
アニメーションウェイト(メインループのウェイト)の下限値を設定します。 |
戻り値 - Return |
(int型) |
文法的定義 - Signature |
void setAnimationWaitMax(int wait) |
関数名 - Name |
setAnimationWaitMax |
役割 - Role |
アニメーションウェイト(メインループのウェイト)の上限値を設定します。 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
int getAnimationWaitMax() |
関数名 - Name |
getAnimationWaitMax |
役割 - Role |
アニメーションウェイト(メインループのウェイト)の上限値を設定します。 |
戻り値 - Return |
(int型) |
文法的定義 - Signature |
void setMainLoopState(bool state) |
関数名 - Name |
setMainLoopState |
役割 - Role |
メインループの継続状態を設定します。falseに設定するとアニメーションのメインループを脱出し、プログラムを終了します。 |
引数 - Arguments |
(bool型) state : メインループの継続状態 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
bool getMainLoopState() |
関数名 - Name |
getMainLoopState |
役割 - Role |
メインループの継続状態を取得します。 |
戻り値 - Return |
(bool型) メインループの継続状態 |
文法的定義 - Signature |
string[ ] getMainArgument() |
関数名 - Name |
getMainArgument |
役割 - Role |
main関数の引数を取得します。 |
戻り値 - Return |
(string[]型) main関数の引数 |
文法的定義 - Signature |
void export( string filePath, string format, float quality ) |
関数名 - Name |
export |
役割 - Role |
現在の描画ラベルの内容を、画像ファイルに出力します。ファイルの出力は、この関数をコールした瞬間に行われるわけでは無く、次回の画面更新タイミングに合わせて実行されます。 |
引数 - Arguments |
(string型) filePath : 出力ファイル名またはファイルパス (string型) format : ファイル形式("PNG"または"JPEG") (float型) quality : 品質 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void main( string args[ ] ) |
関数名 - Name |
main |
役割 - Role |
main関数です。通常は自動で実行され、frameworkMain関数をコールします。ただし、メインプログラムでmain関数を定義する場合は、こちらは自動で実行されなくなるので、下記のframeworkMainを明示的に呼ぶ必要があります。 |
引数 - Arguments |
(string[]型) args : メイン引数( getMainArgument関数で取得可能 ) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void frameworkMain( string args[ ] ) |
関数名 - Name |
frameworkMain |
役割 - Role |
フレームワークのメイン処理です。通常はmain関数から自動で実行されます。ただし、メインプログラムでmain関数を定義する場合は、自動で実行されなくなるので、適当なタイミングで呼ぶ必要があります。 |
引数 - Arguments |
(string[]型) args : メイン引数( getMainArgument関数で取得可能 ) |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void onWindowResize( int id, int width, int height ) |
関数名 - Name |
onWindowResize |
役割 - Role |
ウィンドウがリサイズされた際にコールされるイベントハンドラです。 |
引数 - Arguments |
(int型) id : ウィンドウのGUIコンポーネントID (int型) width : ウィンドウの幅 (int型) height : ウィンドウの高さ |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void onWindowClose( int id ) |
関数名 - Name |
onWindowClose |
役割 - Role |
ウィンドウが閉じられた際にコールされるイベントハンドラです。 |
引数 - Arguments |
(int型) id : ウィンドウのGUIコンポーネントID |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void paintWindow() |
関数名 - Name |
paintWindow |
役割 - Role |
ウィンドウの再描画を行います。アニメーションの画面更新タイミングで自動的にコールされますが、任意のタイミングで明示的に呼び出して再描画させる事も可能です。 |
戻り値 - Return |
(void型) |
文法的定義 - Signature |
void render() |
関数名 - Name |
render |
役割 - Role |
paint関数などをコールし、画面表示内容を描画します。通常は自動で実行されますが、アニメーションを無効にしている場合などは、画面更新時に明示的に呼び出す必要があります。 |
戻り値 - Return |
(void型) |