Graphics3DFramework


概要 - Abstract

このモジュール open.gui.Graphics3DFramework は、3DCG( 3次元グラフィックス )を手軽に扱うための軽量フレームワークです。

VCSSLの標準ライブラリ「 Graphics3D 」や「 GUI 」だけを用いて、ゼロから3DCGプログラムを記述する場合、
ウィンドウ・レンダラー(描画エンジン)の生成や、アニメーションループ、基本的なイベントハンドラなど、いくつかの定型的な処理を、毎回記述しなければいけません。
そこで、この Graphics3DFramework では、上述のような定型処理を、雛形のようにあらかじめ用意する事によって、手軽な3DCG利用をサポートします。

・必要な処理の記述

Graphics3DFramework は、構造的には、単体で既に完成した3DCGプログラムです。実際、単体で実行する事が可能です。
ただし、単体では何の3Dモデルも配置されておらず、ただ白い画面が表示されるだけです。

そこで実際には、自作モジュールから Graphics3DFramework を import し、3Dモデルの配置や移動など、必要な処理を記述します。
そういった処理は、いくつかの決まった名前の関数を定義し、そこに記述します。つまり、GUIなどのイベントハンドラと同じ仕組みです。
するとそれらの関数を、Graphics3DFramework が適切なタイミングで自動実行します。

Graphics3DFramework が自動実行する関数は、下記のものがあります。定義は必須では無いので、必要な関数だけを定義し、記述して下さい。

上記関数のいずれも、引数 renderer には、3DCGレンダラーのID が渡されます。これは3Dモデルの配置などに使用します。

・背景・前景の2DCG描画

なお、Graphics3DFramework は、前景・背景の2DCG描画もサポートしています。
ただしこの機能はデフォルトで無効になっているため、利用する前にそれぞれ setForegroundRendererState ( true ) 及び setBackgroundRendererState ( true ) を実行して下さい。
その後、 getForegroundRenderer ( ) 及び getBackgroundRenderer ( ) で 2DCGレンダラーのIDを取得し、paint関数内などで描画を行います。

・ウィンドウのカスタマイズ

Graphics3DFramework では、ウィンドウ内に余白領域を設定し、そこにボタンやテキストフィールドなどのGUI部品を配置する事ができます。
余白の設定は、setMarginTop ( int margin ) 関数や setMarginLeft ( int margin ) 関数などで行います。
そして getWindow ( ) 関数でウィンドウのIDを取得し、余白領域にGUI部品を自由に配置してください。

・フレームレート調整

加えて、Graphics3DFramework は、フレームレートの自動調整機構も備えています。
具体的には、Graphics3DFramework は、毎フレーム間の所要時間を計測し、常に設定された目標フレームレートに近づくよう、アニメーションループのウェイト ( 待機時間 ) を自動調整します。
目標フレームレートは setFrameRate ( float rate ) で設定します。また、実測フレームレートは getCurrentFrameRate ( ) で取得可能です。

・処理落ち

なお、実行環境の処理速度にも依存しますが、描画する画面サイズが大きかったり、描画内容が重かったりすると、
アニメーションの待機時間を最小にしても、実測フレームレートが目標フレームレートに達しなくなる現象 ―― 処理落ち ―― が生じます。

処理落ちが発生すると、画面の再描画処理が追いつかなくなり、画面がちらつく場合があります。
その場合は、目標フレームレートを実測フレームレートの限界よりも余裕のある値に設定する事で、画面のちらつきを抑える事ができます。
しかし、実測フレームレートは環境に大きく依存するため、代わりに setAnimationWaitMin ( int wait ) 関数でアニメーションウェイトの下限値(ミリ秒単位)を大きめに設定する事でも、
画面のちらつきを抑える事ができます( ただしこの場合、実測フレームレートの限界は低下します )。


構造体 - Structs

- なし - None -


変数 - Variables


関数 - Functions

宣言
- Declaration
int getGraphics()
詳細
- Description
3DCGのグラフィックスリソースIDを返します。
戻り値
- Return
3DCGのグラフィックスリソースID
宣言
- Declaration
int getBackgroundGraphics()
詳細
- Description
背景2DCGのグラフィックスリソースIDを返します。
戻り値
- Return
背景2DCGのグラフィックスリソースID
宣言
- Declaration
int getForegroundGraphics()
詳細
- Description
前景2DCGのグラフィックスリソースIDを返します。
戻り値
- Return
前景2DCGのグラフィックスリソースID
宣言
- Declaration
int getRenderer()
詳細
- Description
3DCGのレンダラーIDを返します。
戻り値
- Return
3DCGのレンダラーID
宣言
- Declaration
int getBackgroundRenderer()
詳細
- Description
背景2DCGのレンダラーIDを返します。
戻り値
- Return
背景2DCGのレンダラーID
宣言
- Declaration
int getForegroundRenderer()
詳細
- Description
前景2DCGのレンダラーIDを返します。
戻り値
- Return
前景2DCGのレンダラーID
宣言
- Declaration
void setBackgroundRendererState(bool state)
詳細
- Description
背景2DCGレンダラーの有効/無効を設定します。
引数
- Arguments
state : 背景2DCGレンダラーの有効/無効(trueならば有効)
宣言
- Declaration
void setForegroundRendererState(bool state)
詳細
- Description
前景2DCGレンダラーの有効/無効を設定します。
引数
- Arguments
state : 前景2DCGレンダラーの有効/無効(trueならば有効)
宣言
- Declaration
int getGraphicsLabel()
詳細
- Description
描画ラベルのGUIコンポーネントIDを返します。
戻り値
- Return
描画ラベルのGUIコンポーネントID
宣言
- Declaration
int getWindow()
詳細
- Description
ウィンドウのGUIコンポーネントIDを取得します。
戻り値
- Return
ウィンドウのGUIコンポーネントID
宣言
- Declaration
void setAnimationState(bool enable)
詳細
- Description
アニメーションモードの有効/無効を設定します。
引数
- Arguments
enable : アニメーションモードの有効/無効(trueならば有効)
宣言
- Declaration
bool getAnimationState()
詳細
- Description
アニメーションの有効/無効を取得します。
戻り値
- Return
アニメーションモード有効/無効(trueならば有効)
宣言
- Declaration
void setFrameRate(float rate)
詳細
- Description
アニメーションの画面更新頻度( 1秒間あたりの描画回数 )を設定します。
引数
- Arguments
rate : 画面更新頻度
宣言
- Declaration
float getFrameRate()
詳細
- Description
アニメーションの画面更新頻度( 1秒間あたりの描画回数 )の設定値を取得します。
戻り値
- Return
画面更新頻度(設定値)
宣言
- Declaration
float getCurrentFrameRate()
詳細
- Description
アニメーションの画面更新頻度( 1秒間あたりの描画回数 )の実測値を取得します。
戻り値
- Return
画面更新頻度(実測値)
宣言
- Declaration
int getLastFrameTime()
詳細
- Description
アニメーションの最終画面更新時刻を取得します。時刻は、プログラム開始時刻からの経過時間を、通常はミリ秒単位で表したものが返されます。ただし単位は処理系によって異なる可能性があります。処理系の依存性を完全に排除するためには、Time.millisecond関数を挟んで使用して下さい。
戻り値
- Return
最終画面更新時刻(通常はミリ秒単位)
宣言
- Declaration
void setPaintGraphics3DState(bool state)
詳細
- Description
画面描画時(paintコール前)に、自動でGraphics3D.paintGraphics3Dをコールするかどうかを設定します。trueを指定すると自動でコールされます。falseに設定すると自動でコールされないので、paintイベントハンドラなどで明示的にコールする必要があります。
引数
- Arguments
state : 設定した状態
宣言
- Declaration
void setPaintGraphics2DState(bool state)
詳細
- Description
画面描画時(paintコール前)の背景・前景描画において、自動でGraphics3D.paintGraphics2Dをコールするかどうかを設定します。trueを指定すると自動でコールされます。falseに設定すると自動でコールされないので、paintイベントハンドラなどで明示的にコールする必要があります。
引数
- Arguments
state : 設定した状態
宣言
- Declaration
bool getPaintGraphics3DState()
詳細
- Description
画面描画時(paintコール前)に、自動でGraphics3D.paintGraphics3Dをコールするかどうかを取得します。
戻り値
- Return
取得した状態
宣言
- Declaration
void setMagnification(float rate)
詳細
- Description
描画倍率を設定します。倍率は、視点から1.0の距離にある、半径1.0の円が、半径何ピクセルに描かれるかの比率に一致します。
引数
- Arguments
rate : 描画倍率
宣言
- Declaration
float getMagnification()
詳細
- Description
描画倍率を取得します。倍率は、視点から1.0の距離にある、半径1.0の円が、半径何ピクセルに描かれるかの比率に一致します。
戻り値
- Return
描画倍率
宣言
- Declaration
void setBackgroundColor(int r, int g, int b, int a)
詳細
- Description
背景色を設定します。引数には、背景色の 赤,緑,青,α成分 を、0~255の範囲で指定します。
引数
- Arguments
r : 背景色(赤、0~255)
g : 背景色(緑、0~255)
b : 背景色(青、0~255)
a : 背景色(α成分、0~255)
宣言
- Declaration
void setBackgroundColor(int color[])
詳細
- Description
背景色を設定します。引数には、背景色の 赤,緑,青,α成分 を、0~255の範囲で格納した配列を指定します。
引数
- Arguments
color : 背景色配列([0]=赤、[1]=緑、[2]=青、[3]=α成分、各0~255)
宣言
- Declaration
int[] getBackgroundColor()
詳細
- Description
背景色を取得します。戻り値には、背景色の 赤,緑,青,α成分 を、0~255の範囲で格納した配列が返されます。
戻り値
- Return
背景色配列([0]=赤、[1]=緑、[2]=青、[3]=α成分、各0~255)
宣言
- Declaration
void setDirectionalLightVector(float x, float y, float z)
詳細
- Description
平行光源の方向ベクトルを指定します。ベクトルは、ライトの存在する方向のベクトルを指定します。
引数
- Arguments
x : X成分
y : Y成分
z : Z成分
宣言
- Declaration
void setDirectionalLightVector(float v[])
詳細
- Description
平行光源の方向ベクトルを指定します。ベクトルは、ライトの存在する方向のベクトルを指定します。
引数
- Arguments
v : ベクトル成分配列( v[0]=X、v[1]=Y、v[2]=Z )
宣言
- Declaration
float[] getDirectionalLightVector()
詳細
- Description
平行光源の方向ベクトルを取得します。ベクトルは、ライトの存在する方向のベクトルが返されます。
戻り値
- Return
ベクトル成分配列( v[0]=X、v[1]=Y、v[2]=Z )
宣言
- Declaration
void setDirectionalLightBrightness(float power)
詳細
- Description
平行光源の輝度を指定します。
引数
- Arguments
power : 輝度
宣言
- Declaration
float getDirectionalLightBrightness()
詳細
- Description
平行光源の輝度を取得します。
戻り値
- Return
輝度
宣言
- Declaration
void setAmbientLightBrightness(float power)
詳細
- Description
アンビエント光源の輝度を指定します。
引数
- Arguments
power : 輝度
宣言
- Declaration
float getAmbientLightBrightness()
詳細
- Description
アンビエント光源の輝度を取得します。
戻り値
- Return
輝度
宣言
- Declaration
void setWindowTitle(string title)
詳細
- Description
ウィンドウタイトルを設定します。
宣言
- Declaration
string getWindowTitle()
詳細
- Description
ウィンドウタイトルを取得します。
宣言
- Declaration
void setWindowSize(int width, int height)
詳細
- Description
ウィンドウサイズを指定します。
引数
- Arguments
width : 幅
height : 高さ
宣言
- Declaration
void setWindowSize(int size[])
詳細
- Description
ウィンドウサイズを設定します。
引数
- Arguments
size : ウィンドウサイズ([0]=幅、[1]=高さ)
宣言
- Declaration
int[] getWindowSize()
詳細
- Description
ウィンドウサイズを取得します。
戻り値
- Return
ウィンドウサイズ([0]=幅、[1]=高さ)
宣言
- Declaration
void setMarginRight(int margin)
詳細
- Description
ウィンドウ右側の余白を設定します。
引数
- Arguments
margin : 余白(ピクセル)
宣言
- Declaration
int getMarginRight()
詳細
- Description
ウィンドウ右側の余白を取得します。
戻り値
- Return
余白(ピクセル)
宣言
- Declaration
void setMarginLeft(int margin)
詳細
- Description
ウィンドウ左側の余白を設定します。
引数
- Arguments
m : 余白(ピクセル)
宣言
- Declaration
int getMarginLeft()
詳細
- Description
ウィンドウ左側の余白を取得します。
戻り値
- Return
余白(ピクセル)
宣言
- Declaration
void setMarginTop(int margin)
詳細
- Description
ウィンドウ上側の余白を設定します。
引数
- Arguments
m : 余白(ピクセル)
宣言
- Declaration
int getMarginTop()
詳細
- Description
ウィンドウ上側の余白を取得します。
戻り値
- Return
余白(ピクセル)
宣言
- Declaration
void setMarginBottom(int margin)
詳細
- Description
ウィンドウ下側の余白を設定します。
引数
- Arguments
m : 余白(ピクセル)
宣言
- Declaration
int getMarginBottom()
詳細
- Description
ウィンドウ下側の余白を取得します。
戻り値
- Return
余白(ピクセル)
宣言
- Declaration
void setAnimationWaitMin(int wait)
詳細
- Description
アニメーションウェイト(メインループのウェイト)の下限値を設定します。
宣言
- Declaration
int getAnimationWaitMin()
詳細
- Description
アニメーションウェイト(メインループのウェイト)の下限値を設定します。
宣言
- Declaration
void setAnimationWaitMax(int wait)
詳細
- Description
アニメーションウェイト(メインループのウェイト)の上限値を設定します。
宣言
- Declaration
int getAnimationWaitMax()
詳細
- Description
アニメーションウェイト(メインループのウェイト)の上限値を設定します。
宣言
- Declaration
void setMainLoopState(bool state)
詳細
- Description
メインループの継続状態を設定します。falseに設定するとアニメーションのメインループを脱出し、プログラムを終了します。
引数
- Arguments
state : メインループの継続状態
宣言
- Declaration
bool getMainLoopState()
詳細
- Description
メインループの継続状態を取得します。
戻り値
- Return
メインループの継続状態
宣言
- Declaration
string[] getMainArgument()
詳細
- Description
main関数の引数を取得します。
戻り値
- Return
main関数の引数
宣言
- Declaration
void export( string filePath, string format, float quality )
詳細
- Description
現在の描画ラベルの内容を、画像ファイルに出力します。ファイルの出力は、この関数をコールした瞬間に行われるわけでは無く、次回の画面更新タイミングに合わせて実行されます。
引数
- Arguments
filePath : 出力ファイル名またはファイルパス
format : ファイル形式("PNG"または"JPEG")
quality : 品質
宣言
- Declaration
void main( string args[] )
詳細
- Description
main関数です。通常は自動で実行され、frameworkMain関数をコールします。ただし、メインプログラムでmain関数を定義する場合は、こちらは自動で実行されなくなるので、下記のframeworkMainを明示的に呼ぶ必要があります。
引数
- Arguments
args : メイン引数( getMainArgument関数で取得可能 )
宣言
- Declaration
void frameworkMain( string args[] )
詳細
- Description
フレームワークのメイン処理です。通常はmain関数から自動で実行されます。ただし、メインプログラムでmain関数を定義する場合は、自動で実行されなくなるので、適当なタイミングで呼ぶ必要があります。
引数
- Arguments
args : メイン引数( getMainArgument関数で取得可能 )
宣言
- Declaration
void paintWindow()
詳細
- Description
ウィンドウの再描画を行います。アニメーションの画面更新タイミングで自動的にコールされますが、任意のタイミングで明示的に呼び出して再描画させる事も可能です。
宣言
- Declaration
void onWindowClose( int id )
詳細
- Description
ウィンドウが閉じられた際にコールされるイベントハンドラです。
引数
- Arguments
id : ウィンドウのGUIコンポーネントID
宣言
- Declaration
void onWindowResize( int id, int width, int height )
詳細
- Description
ウィンドウがリサイズされた際にコールされるイベントハンドラです。
引数
- Arguments
id : ウィンドウのGUIコンポーネントID
width : ウィンドウの幅
height : ウィンドウの高さ