Zaurus GA 3D Engine マニュアル【導入まで】
Copyright 1999-2000 小笠原博之



GA 3D Engine のライブラリを実際にインストールして導入するまでの手順と、プロ
ジェクトの生成、ビルドまでを解説します。


●ライブラリ構造

・BASIC lib (bslib)

  ZaurusOS API周りや、基本的な処理を受け持つ汎用のルーチン集です。このライブ
  ラリは galib から呼び出されるため必須となります。

・GA 3D Engine (galib)

  リアルタイム描画転送、固定少数演算、レンダリングを担当するこのライブラリの
  中心です。以下のようなルーチン群が含まれています。

  ○数値演算ライブラリ
  ○レンダリングエンジン
  ○MESHライブラリ
	モデルデータをプログラム上で操作できます。モデルデータを作るツール環
	境がそろうまでの補助ルーチン群です。
  ○3Dスプライトライブラリ
	ゲームを実際に作る場合に必要になる、描画を補助するライブラリです。ス
	プライトといっても2Dではなく、3Dモデルのみ取り扱います。
  ○Z-sortライブラリ
	スプライトポリゴンの前後関係をより厳密に描画します。ある程度複雑なモ
	デルも描画できますが低速です。



●インストール作業

任意のフォルダを作成し、アーカイブを展開してできたファイルを全部その中にコ
ピーしてください。以後、フォルダの名前は「C:\GALIB」であると仮定し説明を行い
ます。

SZAB による開発や一連のデバッグ手順がわからない方は、先に SZAB 付属のマニュ
アル「プログラミングガイド」を参照されることをお勧めします。プログラミングガ
イドは SZAB マニュアルのセットに含まれています。SZAB サポートページからダウン
ロードすることもできます。



●プロジェクトの新規作成

プロジェクトを新規作成した場合に必要な設定作業を説明します。

SZAB を起動し、通常のアプリケーション開発と同じように、新規作成でプロジェクト
を作ってください。ここでは SZAB 4.3 を想定して説明を行います。

メニューの「ビルド」から「コンパイラ/リンカオプション」を選択します。

  (1) コンパイラオプションの CFLAGS に以下の文字列を追加してください。位置は
      任意です。これは include パスの追加を意味しています。

		-IC:/GALIB

  (2) リンカオプションの LKKFLAGS に「-LC:/GALIB」を挿入します。挿入位置は次
      の通りです。これはライブラリ検索ディレクトリの登録です。

		-L$(LIBDIR) -LC:/GALIB -Y UL,$(LIBDIR)

  (3) リンカオプションの LKKFLAGS2 にライブラリ「-lgalib -lbslib」を追加しま
      す。ここでの記述順序は重要です。必ず以下の順番を守ってください。最後に
      追加しただけは動作しません。

		-lgalib -lbslib -lzeuc -letc -lzaurus -lansi

[OK] を押してダイアログを閉じてください。これでライブラリの設定は終わりです。



●フォームへの登録

SZAB のフォームを使って、3D Engine を作成する手段を説明します。(適切なイベン
ト処理を行うのであれば必ずしもフォームを使う必要はありません)

  (1) SZAB のフォームエディタでダミーフォームを作成します。メニューの「構成
      品」「新規作成」から「フォーム」を選び「新規」を選択します。フォーム名
      を適当に付けます。(以下の説明ではフォーム名を TopForm としています)

  (2) フォームにダミーパーツを一つ配置します。フォーム上に何らかの部品が無い
      と SZAB でコンパイルがとおらないためです。ここではプログラム名を貼り付
      けることにします。

      フォームエディタ左側のツールバーから「ラベル・イメージコントロール」
      「DISPSTRING_RES」を選択し、リソース選択画面でプログラム名として入力し
      た文字列を選びます。

  (3) フォームのプロパティから、コールバックルーチンを以下のように編集します。


◎プロパティFormSetUp:
-----------------------------------------------------------------------------
void TopFormFormSetUp( APLFORMPTR AplForm, MESSAGE *Message )
{
	GaInit( AplForm->FormWnHandle ); // 初期化とハンドル登録
	// ユーザーアプリケーション関数設定
	GaSetAppFunction( AppInit, AppQuit, AppMove, AppDraw );
}
-----------------------------------------------------------------------------

◎プロパティFormEnd:
-----------------------------------------------------------------------------
void TopFormFormEnd( APLFORMPTR AplForm, MESSAGE *Message )
{
	GaQuit();
}
-----------------------------------------------------------------------------

◎プロパティFormOtherEvent:
-----------------------------------------------------------------------------
void TopFormFormOtherEvent( APLFORMPTR AplForm, MESSAGE *Message )
{
	GaExecMainLoop( Message ); //SystemTickIDで起動される、それ以外は無視
}
-----------------------------------------------------------------------------

フォームエディタ上での作業はこれで終わりです。



●アプリケーション関数のヘッダ作成

SZAB のユーザーヘッダファイル( ????_C_usr.h )を編集します。次の4行を書き加え
るだけです。
-----------------------------------------------------------------------------
extern void	AppInit();
extern void	AppQuit();
extern void	AppMove();
extern void	AppDraw();
-----------------------------------------------------------------------------

これで準備ができました。あとは、上の関数群の中身を実際に作成するだけです。



●ユーザーアプリケーションルーチンの例

メニューの「構成品」「新規作成」「Cソース」で新しいソースを作ります。その中に
実際のアプリケーションの処理を記述します。

・白い立方体を3D描画する例
-----------------------------------------------------------------------------
#include	"galib.h"

//頂点リスト
static GaVertex	_vcube[]= {
{	DV(-5), DV( 5), DV(-5),  DV( 0), DV( 1), DV( 0), DV(0),DV(0)	},
{	DV( 5), DV( 5), DV(-5),  DV( 0), DV( 0), DV(-1), DV(0),DV(0)	},
{	DV(-5), DV(-5), DV(-5),  DV( 0), DV( 0), DV(-1), DV(0),DV(0)	},
{	DV( 5), DV(-5), DV(-5),  DV( 1), DV( 0), DV( 0), DV(0),DV(0)	},

{	DV(-5), DV( 5), DV( 5),  DV( 0), DV( 0), DV( 1), DV(0),DV(0)	},
{	DV( 5), DV( 5), DV( 5),  DV( 0), DV( 0), DV( 1), DV(0),DV(0)	},
{	DV(-5), DV(-5), DV( 5),  DV(-1), DV( 0), DV( 0), DV(0),DV(0)	},
{	DV( 5), DV(-5), DV( 5),  DV( 0), DV(-1), DV( 0), DV(0),DV(0)	},
};

//インデックスリスト
static unsigned short	_icube[]= {
		2, 0, 1,
		2, 1, 3,
		4, 6, 7,
		4, 7, 5,
		6, 4, 0,
		6, 0, 2,
		3, 1, 5,
		3, 5, 7,
		0, 4, 5,
		0, 5, 1,
		7, 6, 2,
		7, 2, 3,
};

static GaModel	_Cube= { 8, 36, _vcube, _icube };

void
AppInit()
{
	//スプライトライブラリの初期化
	GaSpriteInit( 32 );
}

void
AppQuit()
{
	//スプライトライブラリの開放
	GaSpriteQuit();
}

void
AppMove()
{
}

void
AppDraw()
{
	GaMatrix	*matp;

	//フレームバッファのクリア
	GaClear( RGBA_MAKE(0,0,0,0) );

	//スプライトバッファのクリア
	GaSpriteClear();

	//マトリクススタックの初期化
	GaMatrixStackClean();

	//3Dマトリクス演算部
	matp= GaMatrixGet();		//スタック参照
	GaMatIdentity( matp );		//単位行列に初期化
	GaMatTranslation( matp, DV(0), DV(0), DV(300) ); //平行移動

	//スプライト登録
	GaSpriteQuick(
		matp,
		&_Cube,
		RGBA_MAKE(255,255,255,255),
		NULL,
		GA_RENDER_STATE_FLAT|GA_RENDER_STATE_LIGHTING
	);

	//登録したスプライトの描画
	GaSpriteDraw();

	//画面に描画
	GaDraw();
}
-----------------------------------------------------------------------------



●システムインターフェースについて

 galib は、SZAB とのリンクのために、4つのインターフェースを用意しています。
システムから適宜これらの関数が呼び出されることで、GA 3D Engine は動作してい
ます。

void	GaInit( WINDOWHD wp )
-----------------------------------------------------------------------------
	ライブラリの初期化を行います。galib を使うときは最初に必ず実行してお
	かなければなりません。
-----------------------------------------------------------------------------

void	GaSetAppFunction( void (*init)(),
			void (*quit)(), void (*move)(), void (*draw)() )
-----------------------------------------------------------------------------
	メインループから呼び出される、4つのユーザーアプリケーション関数を登
	録します。GaExecMainLoop() より先に登録しておく必要があります。
-----------------------------------------------------------------------------

void	GaExecMainLoop( MESSAGE *Message )
-----------------------------------------------------------------------------
	galib のメインループ(メッセージループ)を呼び出します。一度呼び出すと
	内部で独自のイベントループを形成するため、終了するまで戻ってきません。
	内部で必要に応じてユーザーアプリケーション関数を呼び出します。
-----------------------------------------------------------------------------

void	GaQuit()
-----------------------------------------------------------------------------
	ライブラリの終了処理を行います。アプリケーション終了時に呼び出さなけ
	ればなりません。
-----------------------------------------------------------------------------



●ユーザーアプリケーション関数について

アプリケーションは、必ず以下の 4つのアプリケーションルーチンを用意しなければ
なりません。

void	AppInit()
-----------------------------------------------------------------------------
	初期化処理を記述します。一番最初に一度呼び出されます。ゲームの初期化、
	テクスチャロード、各種ライブラリの初期化などを行います。
-----------------------------------------------------------------------------

void	AppQuit()
-----------------------------------------------------------------------------
	終了時に呼び出されます。テクスチャやワークメモリの開放は忘れずに行う
	ようにしてください。
-----------------------------------------------------------------------------

void	AppDraw()
-----------------------------------------------------------------------------
	毎フレーム呼び出されます。この中で1フレーム分の描画を行います。
-----------------------------------------------------------------------------

void	AppMove()
-----------------------------------------------------------------------------
	イベント発生時に呼び出されます。ペン入力など、システムの各種メッセー
	ジをフックすることができます。
-----------------------------------------------------------------------------

ユーザーアプリケーション関数は、必ずしも上記の名前でなくても構いません。



●コンパイラ/リンカオプション設定について補足

・コンパイラオプティマイズ

SZAB で新規プロジェクトを作成した場合、デフォルトではコンパイラのオプティマ
イズが無効になっています。オプティマイズを有功にするには、「コンパイラ/リン
カオプション」の設定画面から、「コンパイラオプション」で COPTFLAGS に「-O」
を追加してください。

・C++コメント

ライブラリのヘッダやサンプルには、C++ コメント「//〜」が多用されています。
そのため、galib を使う場合コンパイラオプションの CFLAGS に「-Xslashcomment」
が必須となります。SZAB を新規プロジェクトで作成した場合はデフォルトでこのオ
プションがついています。



●付属のサンプルプログラムを動かすには

 C:\GALIB\SAMPLE の下にはいくつかのサンプルプログラムが収められています。これ
らのプログラムは、実際にコンパイルして実行することができます。

(1) SZAB を起動し、メニューの「プロジェクト」から「開く」を選択します。
(2) C:\GALIB\SAMPLE の下から動かしたいサンプルのフォルダを選びます。
(3) Project の下の TUT1.prj を選択して「開く」を押します。

あとはビルドを行い、デバッガ等から起動することが可能です。一部のプログラムは、
実行時にデータを必要とします。appmain.c 等のソースにコメントが書いてあります
ので一度参照しておいてください。

サンプルプログラムは、アプリケーション識別子として TUT1 を使用しています。こ
れは SZAB 開発キットでチュートリアル用に予約されているものです。



2000/01/15 作成

小笠原博之 oga@art.udn.ne.jp
http://www.vector.co.jp/authors/VA004474/