


2D 表示系仕様


							Aug. 7, 2000 Ver.0.8
							Sep.27, 2000 Ver.0.9.5
							Oct.17, 2000 Ver.0.9.6
							Dec. 4, 2000 Ver.0.9.7
							Mar.13, 2001 Ver.0.9.8
							Mar.29, 2001 Ver.0.9.9
							Apl. 9, 2001 Ver.0.9.10
							Apl.10, 2001 Ver.0.9.11
							May 21, 2001 Ver.0.9.12
							Jun 13, 2001 Ver.0.9.13
							吉良 理人



  本ドキュメントは、メタルギアソリッド2 (以下 MGS2) のプログラムで使用されて
いる、2D 表示系システムの仕様について述べたものである。


---------------------------------------------------------------------------

* Index


1.0  表示系概要

  1.1  実装形態
  1.2  座標系
  1.3  オブジェクトの階層化


2.0  2D オブジェクト機能説明

  2.1  オブジェクト種別

    2.1.1  仮想オブジェクト(Empty)
    2.1.2  点(Point)
    2.1.3  線分(Line)
    2.1.4  折れ線(LineStrip)
    2.1.5  長方形(Box)
    2.1.6  サイズ指定矩形ビットマップ(Sprite)
    2.1.7  対角指定矩形ビットマップ(Zoom Sprite)
    2.1.8  回転ビットマップ(Spin Sprite)
    2.1.9  任意4頂点指定ビットマップ(Poly)
    2.1.10 三角形ビットマップ(Triangle)


3.0  使用の上での手順

  3.1  オブジェクトの生成
  3.2  オブジェクトの設定
  3.3  オブジェクトの表示開始
  3.4  オブジェクトの操作
  3.5  オブジェクトの破棄


4.0  2D オブジェクトモジュールリファレンス

  4.1  データ型

    4.1.1  SPR_FIX                   固定小数点数値
    4.1.2  SPR_COLOR		     RGBA値
    4.1.3  SPR_TEX		     テクスチャ情報
    4.1.4  SPR_ID		     2D オブジェクト種別 ID
    4.1.5  SPR_PRI		     プライオリティ値
    4.1.6  SPR_POS		     座標
    4.1.7  SPR_RECT		     領域
    4.1.8  SPR_HEADER		     2D オブジェクト管理ヘッダ情報
    4.1.9  SPR_HEADER_EX	     2D オブジェクト管理ヘッダ拡張情報
    4.1.10 SPR_EMPTY		     仮想オブジェクト
    4.1.11 SPR_POINT		     点
    4.1.12 SPR_LINE		     線分
    4.1.13 SPR_LINESTRIP	     折れ線
    4.1.14 SPR_BOX		     長方形
    4.1.15 SPR_SPRITE		     サイズ指定矩形ビットマップ
    4.1.16 SPR_ZOOM		     対角指定ビットマップ
    4.1.17 SPR_SPIN		     回転ビットマップ
    4.1.18 SPR_POLY                  任意4頂点ビットマップ
    4.1.19 SPR_TRIANGLE		     三角形ビットマップ
    4.1.20 SPR_OBJ                   2Dオブジェクトプリミティブ管理構造体



  4.2  マクロ

    4.2.1  SPR_FIXED                 座標値用固定小数点数値変換マクロ
    4.2.2  SPR_FLAG_*                表示属性
    4.2.3  SPR_SHOW                  2Dオブジェクト表示許可
    4.2.4  SPR_HIDE                  2Dオブジェクト表示禁止
    4.2.5  SPR_PIX_X / SPR_PIX_Y     物理ピクセル座標から対比座表値への変換
    4.2.6  SPR_PIX_X / SPR_PIX_Y     対比座標値から物理ピクセル座標値への変換

  4.3  プログラムインタフェース

    4.3.1  SPR_Init2D_ObjectDriver()       2Dオブジェクトドライバ初期化
    4.3.2  SPR_Create_2D_Object()          2Dオブジェクト生成
    4.3.3  SPR_Destroy_2D_Object()         2Dオブジェクト破棄
    4.3.4  SPR_LoadTexture()               テクスチャデータのロード
    4.3.5  SPR_KillTexture()               テクスチャデータの開放
    4.3.6  SPR_ObjSetTexture()             テクスチャの設定
    4.3.7  SPR_SetColor*()                 点/線分/長方形の色指定
    4.3.8  SPR_SetPos*()                   表示座標指定
    4.3.9  SPR_SetSize*()                  表示サイズ指定
    4.3.10 SPR_SetCenterSpin()             回転中心指定
    4.3.11 SPR_SetRollSpin()               回転角指定
    4.3.12 SPR_SetLineStripVertexNumber()  折れ線頂点数指定
    4.3.13 SPR_SetPriority()               プライオリティ設定
    4.3.14 SPR_DuplicateTree()		   オブジェクトツリー複製


    
---------------------------------------------------------------------------

1.0  表示系概要

  3D のゲームにおいても、ユーザインタフェースを中心としたかなりの部分で
  必要とされる機能が、従来の 2D ゲームでも用いられてきた表示系である。

  本モジュールは 2D 表示系を必要とするプログラムモジュールに対して、
  統一された 2D 表示のプログラムインタフェースを提供するものである。



  1.1  実装形態

    本モジュールは、他のプログラムモジュール同様、MGS2 プログラムシステムの
    Actor として実装される。

    本モジュールを使用するためのヘッダファイルが提供され、この中で何種類かの
    2Dオブジェクトをあらわす構造体が定義されている。

    構造体は、その 2D オブジェクトに必要とされる、論理的な最低限の情報のみを
    もち、DMAパケット領域等の物理的情報は含まない。ただし、実際に DMA パケット
    領域を指すポインタは保持している。

    モジュールによって提供される関数を呼ぶことで、ユーザが要求した型の 2D 
    オブジェクトの構造体および、対応する DMA パケットが生成される。

    モジュール側ではこのようにして作成された DMA パケット領域の内容を、
    登録されているユーザ側構造体の内容を監視し、毎フレーム更新することで、
    実際の描画を行う。

    この構成により、ユーザは登録済の構造体領域の内容を変更するだけで
    2D 表示の操作を行うことができ、その際に DMA パケットの加工等を行うコードを
    書く工数を軽減できる。


	構成:

		     ユーザ側
		プログラムモジュール
			|
			|操作
			v
		+--------------+(反映) +-------------------------+
		|論理情報構造体|- - - >|対応するDMAパケット構造体|--> DMAPACK
		+--------------+       +-------------------------+
			^				^
		   監視	|   +------------------------+	|加工
	    (毎フレーム)+---|2Dオブジェクトモジュール|--+(毎フレーム)
			    +------------------------+



  1.2  座標系

    ゲームを移植する際や、動作環境が変更された際に問題となるのが、画面解像度の
    相違である。PlayStation2 の場合だけ見ても、NTSC と PAL では縦方向の解像度
    が異なり、物理的な座標値を変更なく動かした場合に見掛け上の位置が変わって
    しまう。

    この問題を解決するために、本モジュールでは、以下のような仮想座表系を
    用いている。

                 0      --->x                  512.0
		0 +----------------------------+
		  |                            |
		  |                            |
		| |                            |
		| |                            |
		v |                            |
		y |                            |
		  |                            |
		  |                            |
		  |                            |
	    384.0 +----------------------------+


     表示領域左上を原点とし、右側を x の増加方向、下方向をy の増加方向
     とする。画面表示領域の最大幅、最大高をそれぞれ 512.0, 384.0 とし、
     表示座標を実数で表現する論理座標系である。

     表示に際し、2D表示モジュール内部では、この座表系として与えられた座標値を
     内部で対応する位置の物理座標に変換し、描画パケットを生成する。ユーザ側で
     環境に合わせて座標値を変更する必要はない。	
     
     当然、物理座標値と仮想座標値は異なるため、座標値と描画ピクセルは厳密な
     関係を持たなくなるが、環境の変化にかかわらず見掛け上の位置は同じになる。

     各描画チャネルの領域においては、この座標系が「2D表示座標系」として
     適用される。各チャネルの表示領域左上を原点とし、右下を(512.0, 384.0)
     として表示が行われる。つまり、チャネルに割り当てられた描画面積に伴い、
     座標値あたりの距離が変動する。



  1.3  オブジェクトの階層化

     本モジュールでは、2D オブジェクトの階層化をサポートする。
     オブジェクトの階層化によって複数の 2D オブジェクトを関連付けることで、
     一定の位置関係を持つ2Dオブジェクトの操作を簡略化することができる。

     階層化されたオブジェクトは互いに親子関係で結ばれ、親オブジェクトの表示
     属性や表示位置が、子オブジェクトに継承される。

     子オブジェクトが継承する親オブジェクトの属性は、以下の三つである。

     1: 表示座標

	子オブジェクトは、表示位置情報を親オブジェクトの基準点に対する
	相対座標で保持する。このため、親オブジェクトの表示位置が変更された
	場合でも、親子関係にあるオブジェクトの相対的な位置関係は一定である。


     2: 表示許可属性

	本モジュールは、オブジェクトの表示を個別に許可/禁止する機能を持つが、
	あるオブジェクトの表示が禁止された場合、その子孫として作成された全て
	のオブジェクトの表示が禁止される。

     3: 表示チャネル

        あるオブジェクトの子として作成されたオブジェクトに与えられた表示
	チャネル情報は意味を持たず、親オブジェクトが表示されているチャネルに
	描画される。表示チャネル情報は、親を持たない最上位のオブジェクトに
	対してのみ意味を持つ。


     これらの属性が継承されることにより、複数のオブジェクトを一つの親のもとに
     グループ化し、あたかも一つのオブジェクトであるかのように扱うことが可能で
     ある。

     

---------------------------------------------------------------------------

2.0  2D オブジェクト機能説明

     本モジュールでは、2Dオブジェクトを表示形態毎に分類し、それらに対応した
     形式で管理する。本モジュールで扱うことができる 2D オブジェクトは点、線分、
     折れ線、長方形、ビットマップ(4種)と、仮想オブジェクトを含む計9種類である。


  2.1  オブジェクト種別

       本モジュールで扱うことができる2D オブジェクトは以下の5種類になる。

    2.1.1  仮想オブジェクト(Empty)

	 このオブジェクトは一切の描画を伴わない、座標情報と表示属性のみの
	 オブジェクトである。他のオブジェクトの親オブジェクトとして定義し、
	 子として関連付けられた一連のオブジェクトの基準座標オブジェクトとして
	 使用することを想定している。


    2.1.2  点(Point)

	 任意座標に、指定された RGB 値をもつ点を描画する。


    2.1.3  線分(Line)

	 任意2点を結ぶ線分を描画する。

    2.1.4  折れ線(LineStrip)

	 複数の座標を連続して結ぶ折れ線を描画する


    2.1.5  長方形(Box)

	 指定された2点を対角として持つ長方形のラインを描画する。
	 

    2.1.6  サイズ指定矩形ビットマップ(Sprite)

	 画面座標系における任意点を左上として、指定したビットマップを画面上に
	 表示する。表示サイズを縦、横の各方向独立して指定することができる。
	 表示サイズの指定は、表示領域の幅と高さに対する係数(実数)で指定する。


    2.1.7  対角指定矩形ビットマップ(Zoom Sprite)

    	 矩形ビットマップの左上と右下の頂点座標を任意に指定できるビットマップ。


    2.1.8  回転ビットマップ(Spin Sprite)

	 矩形ビットマップの中の任意点を中心とし、指定角度だけ回転させて表示
	 する。表示位置は回転中心を配置する画面座標で指定する。
	 表示サイズの指定はサイズ指定矩形ビットマップと同じ。

	 なお、回転中心となる点は、ビットマップの外部にあっても良い。



    2.1.9  任意4頂点指定ビットマップ(Poly)

	 矩形ビットマップの4つの頂点に対応する画面座標系上における座標を任意に
	 指定し、その4頂点を結んだ4点から構成される四角形の形状にビットマップ
	 を変形させて表示する。


    2.1.10 三角形ビットマップ(Triangle)

	 矩形ビットマップの4つの頂点のうち、左上、左下、右上を結ぶことによって
	 できる三角形の画像を、任意に指定した3つの頂点に対応させた形に変形
	 させて表示する。


---------------------------------------------------------------------------

3.0  使用の上での手順

     2Dオブジェクトモジュールの使用にあたっては、

	生成 -> 設定 -> 表示開始 -> 操作 -> 破棄

     という手順を踏む必要がある。
     以下にそれらの詳細について,順を追って解説する。




  3.1  オブジェクトの生成

       この工程では、使用したい型のオブジェクトを生成する。
       具体的にはそのオブジェクトの各種パラメータや DMA パケットが格納
       されるメモリ領域を確保し、最低限の初期化と階層構造の関連付けを
       行う。

       オブジェクトの生成には、SPR_Create_2D_Object() 関数を用いる。
       戻り値として返された SPR_OBJ 共用体のポインタが指す領域が、
       オブジェクトの領域となる。

       ex.)

	    #include "sprite_2d.h"

            typedef struct {
	      GV_ACT_EX   actor;

	      SPR_OBJ   * parent;
	      SPR_OBJ	* sprite;

	      int         tex_handle;

	      float       x, y;
		      :

	    } Work;

		   :
		   :

	    static int GetResources(Work * work)
	    {

              work->parent = SPR_Create_2D_Object(SP_EMPTY, 4, NULL);
	      work->sprite = SPR_Create_2D_Object(SP_SPRITE, -1, work->parent);

	              :
	      return 0;
	    }

       第一引数には、使用するオブジェクト種別を SPR_ID 型列挙子(4.1.4)で
       指定する。第二引数には、オブジェクトを表示する描画チャネルを指定する。
       但し、親オブジェクトを持つ場合は、親オブジェクトと同じ描画チャネルに
       描画されるため、この値は意味を持たない。

       第三引数には、親オブジェクトの SPR_OBJ 共用体ポインタを指定する。
       親オブジェクトを持たないオブジェクトを生成する場合は NULL を指定する。

       上記の例では、親オブジェクトを持たない仮想オブジェクト(Empty)を
       メニュー描画チャネルに描画するように生成(work->parent)し、その子として
       サイズ指定矩形ビットマップ(Sprite)型のオブジェクト(work->sprite)を
       生成している。

       work->sprite は work->parent を親に持つので、描画チャネルは work->parent
       と同じメニュー描画チャネルとなる。



    
  3.2  オブジェクトの設定

       この工程では、生成されたオブジェクトの表示情報を設定する。いわば
       ユーザサイドでの初期化である。

       設定する内容は、座標値、RGBA値、アルファブレンディングパラメータ、
       子の拡大率、表示サイズ、テクスチャ等、表示上必要な情報の数々である。

       これらのうち、座標値と表示サイズ、RGBA 値、テクスチャには設定用の
       関数が用意されているが、他のパラメータについては構造体の内容を直接
       操作する必要がある。

       ex.) 各関数の詳細については、4章を参照のこと。
	  
	    static int GetResources(Work * work)
	    {
              work->parent = SPR_Create_2D_Object(SP_EMPTY, 4, NULL);
	      work->sprite = SPR_Create_2D_Object(SP_SPRITE, -1, work->parent);

	      /* 表示座標の設定 */
	      SPR_SetPosEmpty(work->parent. &(SPR_POS){0.0F, 0.0F});
	      SPR_SetPosSprite(work->sprite, &(SPR_POS){256.0F, 192.0F});

	      /* 表示サイズの設定 */
	      SPR_SetSizeSprite(work->sprite, 64.0F, 64.0F);

	      /* テクスチャの設定 */
	      work->tex_handle = SPR_LoadTexture(GV_StrCode("textures"));
	      SPR_ObjSetTexture(work->sprite,
				GV_StrCode("sp_tex"), work->tex_handle);

	      /* アルファブレンディングの設定 */
	      work->sprite.head.alpha = SCE_GS_SET_ALPHA(0, 1, 2, 1, 64);

			:
			:

	      return 0;
	    }


	      

  3.3  オブジェクトの表示開始

       生成直後のオブジェクトは非表示状態になっているため、表示を開始して
       やらない限り画面に表示されない。

       オブジェクトを表示状態にするには、SPR_SHOW() マクロを使用し、
       再び非表示状態に戻すには SPR_HIDE() マクロを使用する。

       ex.)

	    static int GetResources(Work * work)
	    {
              work->parent = SPR_Create_2D_Object(SP_EMPTY, 4, NULL);
	      work->sprite = SPR_Create_2D_Object(SP_SPRITE, -1, work->parent);

			   :
			   :

	      /* オブジェクトの表示開始 */
	      SPR_SHOW(work->sprite);  /* 親がまだ非表示なので表示されない */
	      SPR_SHOW(work->parent);  /* 表示開始 */

			   :
			   :
				     
	    }




       
  3.4  オブジェクトの操作

       表示されているオブジェクトのパラメータを操作することにより、
       オブジェクトの表示状態を変更することができる。

       ex.)

	    static void Act(Work * work)
	    {
	      SPR_POS pos;

	      pos.x = work->x;
	      pos.y = work->y;

	      SPR_SetPosEmpty(work->parent, &pos);

	      /* 右下にむけて動かす */
	      work->x += 0.5F;
	      work->y += 0.25F;
	    }

	    static int GetResources(Work * work)
	    {

			:

	      work->x = work->y = 0.0F;

			:

	    }




  3.5  オブジェクトの破棄

       オブジェクトが不要になったら、オブジェクトを破棄することで使用されて
       いるメモリ領域を開放しなければならない。

       オブジェクトを破棄するには、SPR_Destroy_2D_Object() 関数を使用する。
       SPR_Destroy_2D_Object() 関数は、親子関係を持ったオブジェクトを
       破棄する場合、破棄対象として指定されたオブジェクト以下に連なる
       子や孫などのオブジェクトも再帰的に破棄する。

       このため、一連の大きな木構造関係を持ったオブジェクト群を破棄する場合、
       根源となる一つのオブジェクトのみを破棄すれば良いということになる。

       ex.)
	   static void Die(Work * work)
	   {
	     /* 親を破棄すれば、その子は自動的に破棄される */
	     SPR_Destroy_2D_Object(work->parent);

	     /* work->sprite は work->parent の子なので破棄されている */
	   }


---------------------------------------------------------------------------

4.0  2D オブジェクトモジュールリファレンス

     以下では、本モジュールに含まれるマクロ、構造体、関数について解説する。

  4.1  データ型

    4.1.1  SPR_FIX                   固定小数点数値

	   typedef int SPR_FIX;

	 実体は int だが、下位 bit0～bit3 を小数部とし、bit4以上を整数部と
	 して扱う。これは GS の座標値やテクスチャの UV 値指定とおなじ仕様で
	 ある。

	 モジュールの仕様上、座標は float 型で指定するため、ユーザが直接操作
	 するケースはまずない。


    4.1.2  SPR_COLOR		     RGBA値

	   typedef struct SPR_COLOR {
	   	     unsigned char r, g, b, a;
	   } SPR_COLOR;
    
	 点や線分を描画する際の色を指定する。描画色は RGB 値とアルファ値に
	 よって指定される。


    4.1.3  SPR_TEX		     テクスチャ情報

	   typedef struct SPR_TEX {
	     SPR_FIX      u, v;   /* UV値                               */
	     SPR_FIX      w, h;   /* テクセルサイズ                     */
	     int          flags;  /* テクスチャの扱いを決めるフラグ     */
	     int          pabe;   /* PABE レジスタに転送される値        */
	     int          tri;    /* 対応する .tri のハンドル           */
	     DG_TEX     * dgtex;  /* 対応する DG_TEX 構造体へのポインタ */
	   } SPR_TEX;

	 ビットマップを使用する 2D オブジェクトで使用するテクスチャ情報。
	 通常テクスチャ情報は組み込まれた .tri ファイルからモジュールの
	 関数を用いて設定するため、この構造体の情報をユーザが操作することは
	 まずない。


    4.1.4  SPR_ID		     2D オブジェクト種別 ID

	   typedef enum {
	     SP_EMPTY,	   /* 仮想オブジェクト */
	     SP_POINT,     /* 点               */
	     SP_LINE,      /* 線分             */
	     SP_LINESTRIP, /* 折れ線           */
	     SP_BOX,       /* 長方形           */
	     SP_SPRITE,    /* サイズ指定矩形ビットマップ */
	     SP_ZOOM,      /* 対角指定矩形ビットマップ   */
	     SP_SPIN,      /* 回転ビットマップ           */
	     SP_POLY,      /* 任意四頂点ビットマップ     */
	     SP_TRIANGLE   /* 三角形ビットマップ         */
	   } SPR_ID;

	 2D オブジェクトの種別をあらわす ID値。



    4.1.5  SPR_PRI		     プライオリティ値

    	   typedef int SPR_PRI;

	 2Dオブジェクトのプライオリティ値をあらわす。

	 2Dオブジェクトは、各チャネル毎に 0～7 のプライオリティを持ち、
	 値が高い程手前に描画される。



    4.1.6  SPR_POS		     座標

	   typedef struct SPR_POS {
	     float x;
	     float y;
	   } SPR_POS;

	 2Dオブジェクト座表系における座標値をあらわす。


    4.1.7  SPR_RECT		     領域

	   typedef struct SPR_RECT {
	     SPR_POS  begin;
	     SPR_POS  end;
	   } SPR_RECT;

	 begin と end であらわされる座標を対角とする、矩形領域を表現する。




    4.1.8  SPR_HEADER		     2D オブジェクト管理ヘッダ情報

	   typedef struct SPR_HEADER {
	     struct SPR_OBJ * parent;  /* 親オブジェクト         */
	     struct SPR_OBJ * child;   /* 子オブジェクトの末端   */
	     struct SPR_OBJ * next;    /* 次の兄弟オブジェクト   */
	     struct SPR_OBJ * prev;    /* 直前の兄弟オブジェクト */

	     SPR_ID         id;     /* 2Dオブジェクト種別判別用 IDフィールド */
	     SPR_PRI        pri;    /* プライオリティ値                      */
	     int            flags;  /* 描画上の各種フラグ                    */
	     unsigned short chanl;  /*表示チャネル(root objectのみ意味を持つ)*/
	     unsigned short name;   /* オブジェクトID(表示上は特に関知しない)*/
	     unsigned long  alpha;  /* ALPHA レジスタ値                      */
	     
	     /* DMA 転送用パラメタ領域 */
	     void       * packet;
	     void       * pk[2];    /* パケット 0, 1 のポインタ              */
	     int          q_size;   /* パケットの qword サイズ               */
	     float        scale;    /* 子の座標時に対する係数                */
	   } SPR_HEADER;

	 全ての2Dオブジェクト構造体の先頭にメンバとして定義される構造体。
	 2Dオブジェクトの管理用情報を一括して扱う。この構造体単体で用いられる
	 ことは無い。

	 parent, child, next, prev は、2Dオブジェクトの階層化に用いられる
	 ポインタである。parent は親オブジェクトのポインタ、child は子オブ
	 ジェクトのリンク開始ポインタであり、このポインタで示されるオブジェクト
	 から next をたどることによって、全ての子をアクセスすることができる。
	 next と prev は、同じ親を持つ兄弟オブジェクトへのポインタとなる。
	 これら階層化ポインタは、NULL がその終端をあらわす。

	 子オブジェクトの座標は、その親となるオブジェクトにおける「基準点」の
	 絶対座標に対するオフセットとなる。

	 id によって2Dオブジェクトの種別(点、線分、etc.)が区別され、処理上の
	 振舞いを変える。

	 pri は 2D オブジェクトの表示優先順位が設定される。0～7 の値を持ち、
	 値が少ないほど先に描画される(つまり画面奥の表示になる)。この値は
	 同一描画チャネルに表示されるオブジェクト間の優先順位決定に用いられる。
	 異なるチャネルにあるオブジェクト間の優先順位は、描画チャネルの優先
	 順位に準ずる。

	 chanl は 2D オブジェクトを表示する描画チャネルの指定である。

	 flags は 2Dオブジェクト表示の際の各種属性が設定され、この属性に応じた
	 振舞の上で表示を行う。

	 dmapack と packet は、この 2D オブジェクトに対応する DMA パケットを
	 生成する Actor が使用するポインタであり、2Dオブジェクト構造体の
	 ポインタを引数として登録関数を呼ぶことで値が決定する。ユーザは
	 このポインタを操作してはならない。


    4.1.9  SPR_HEADER_EX	     2D オブジェクト管理ヘッダ拡張情報

	   typedef struct SPR_HEADER_EX {
	     SPR_HEADER      head;
	     SPR_TEX         tex;
	   } SPR_HEADER_EX;

	 ビットマップ等テクスチャを使用する 2D オブジェクトに使用される情報を
	 追加した管理ヘッダ。


    4.1.10 SPR_EMPTY		     仮想オブジェクト

           typedef struct SPR_EMPTY {
	     SPR_HEADER  head;   /* 管理データ */  
	     SPR_POS     pos;    /* 座標点     */
	   } SPR_EMPTY;

	 表示上は何も描画されない2Dオブジェクト。座標情報のみを持ち、
	 頂点色やテクスチャ等の描画情報を一切持たない。

	 階層化オブジェクトにおける、親オブジェクトとして使用するために
	 設けられている。


    4.1.11 SPR_POINT		     点

	   typedef struct SPR_POINT {
	     SPR_HEADER  head;   /* 管理情報 */
	     SPR_POS     pos;    /* 座標値   */
	     SPR_COLOR   col;    /* 色情報   */
	   } SPR_POINT;

	 pos で示される座標に、col で指定される色の点を描画する。
	 子オブジェクトに対しては、(x, y) が基準点になる。


    4.1.12 SPR_LINE		     線分

	   typedef struct SPR_LINE {
	     SPR_HEADER  head;         /* 管理情報           */
	     SPR_POS     pos[2];       /* 座標値(始点、終点) */
	     SPR_COLOR   col[2];       /* 色情報(始点、終点) */
	   } SPR_LINE;

	 pos[0] ではじまり、pos[1] で終わる線分を描画する。
	 線分の色は col[0]とcol[1] で指定され、それぞれが始点、終点に対応する。
	 実装の希望としては線分の色を始点から終点までグーロー補間したいが、
	 詳細は未定。

	 子オブジェクトに対しては、pos[0] が基準点となる。


    4.1.13 SPR_LINESTRIP	     折れ線

	   typedef struct SPR_LINESTRIP {
	     SPR_HEADER          head;   /* 管理データ           */
	     int                 pcnt;   /* 頂点の数             */

	     /* 頂点とその色のリスト */
	     struct spr_lstrip_pos {
	       SPR_POS   pos;    /* 頂点座標 */
	       SPR_COLOR col;    /* 頂点の色 */
	     } * plist;
	   } SPR_LINESTRIP;

	 plist[0].pos から plist[pcnt - 1].pos までの頂点を順に線分で結んだ
	 折れ線(LineStrip) を描画する。各頂点にはRGBA色を指定可能。

	 オブジェクト生成直後は頂点数が 0 となっており、何も描画されない。
	 API として用意された関数を呼ぶことで、オブジェクトの頂点数が決定され、
	 頂点情報領域が確保される。



    4.1.14 SPR_BOX		     長方形

	   typedef struct SPR_BOX {
	     SPR_HEADER    head;
	     SPR_RECT      rect;   /* 領域   */
	     SPR_COLOR     col;    /* 色情報 */
	   } SPR_BOX;

	  rect で与えられた領域の辺に沿って長方形を描画する。


    4.1.15 SPR_SPRITE		     サイズ指定矩形ビットマップ

	   typedef struct SPR_SPRITE {
	     SPR_HEADER_EX head;        /* 管理情報           */
	     SPR_POS       pos;         /* 左上の座標値       */
	     SPR_COLOR     col;         /* RGB 値             */
	     float         dw, dh;      /* 表示上のサイズ     */
	   } SPR_SPRITE;

	 pos で指定された座標を左上として、テクスチャとして与えられた
	 ビットマップを dw, dh で指定されたサイズにおいて表示する。

	 子オブジェクトに対しては、pos が基準点となる。

	 
    4.1.16 SPR_ZOOM		     対角指定ビットマップ

	   typedef struct SPR_ZOOM {
	     SPR_HEADER_EX head;        /* 管理情報 */
	     SPR_RECT      rect;        /* 領域     */
	     SPR_COLOR     col;		/* RGB値    */
	   } SPR_ZOOM;

	 rect で指示された矩形領域に、テクスチャとして与えられた
	 ビットマップを表示する。
	 
	 子オブジェクトに対しては、rect.begin が基準点となる。

    
    4.1.17 SPR_SPIN		     回転ビットマップ

	   typedef struct SPR_SPIN {
	     SPR_HEADER_EX head;         /* 管理情報           */
	     SPR_POS       pos;          /* 中心表示座標       */
	     SPR_POS       center;       /* 回転中心位置       */
	     SPR_COLOR     col;		/* RGB値    */
	     float         dw, dh;       /* 表示サイズ         */
	     float         spin;         /* 回転角             */
	   } SPR_SPIN;

	 ビットマップ左上を基準として center で指定された点を中心とし、
	 spin だけ回転させた画像を、その回転中心が pos に来るように
	 表示する。回転角はラジアンで指定し、回転方向は画面上において
	 時計廻りとなる。
	 
	 子オブジェクトに対しては、pos が基準点となる。



    4.1.18 SPR_POLY                  任意4頂点ビットマップ

	   typedef struct SPR_POLY {
	     SPR_HEADER_EX head;            /* 管理情報           */
	     SPR_POS       vert[4];         /* 各頂点座標         */
	     SPR_COLOR     col[4];	    /* 各頂点の RGB 値    */
	   } SPR_POLY;

	 tex で示される矩形テクスチャの4つの頂点を、vert[0]～vert[3]
	 に対応させた形状に変形させて表示する。

	 頂点の指定順は、テクスチャの左上から時計回りに割り当てられる。

		0          1
		 +--------+
		 |        |
		 |        |
		 +--------+
		3          2

	 子オブジェクトに対しては、vert[0] が基準点となる。


    4.1.19 SPR_TRIANGLE              三角形ビットマップ

	   typedef struct SPR_TRIANGLE {
	     SPR_HEADER_EX head;            /* 管理情報           */
	     SPR_POS       vert[3];         /* 各頂点座標         */
	     SPR_COLOR     col[3];	    /* 各頂点の RGB 値    */
	   } SPR_TRIANGLE;

	 tex で示される矩形テクスチャの4つの頂点に、左上の頂点を 0 番として
	 時計廻りに番号を与えたとして、その頂点 0, 1, 3 を結ぶことによって
	 できる三角形の中に含まれるテクスチャを vert[0]～vert[2] に対応させた
	 形状に変形させて表示する。



    4.1.20 SPR_OBJ                   2Dオブジェクトプリミティブ管理構造体

	   typedef union SPR_OBJ {
	     SPR_HEADER    head;      /* 管理情報       */
	     SPR_HEADER_EX ex_hd;     /* 拡張ヘッダ     */
	     SPR_EMPTY     empty;     /* 仮想           */
	     SPR_POINT     point;     /* 点             */
	     SPR_LINE      line;      /* 線分           */
	     SPR_LINESTRIP linestrip; /* 折れ線         */
	     SPR_SPRITE    sprite;    /* サイズ指定矩形 */
	     SPR_ZOOM      zoom;      /* 対角指定矩形   */
	     SPR_SPIN      spin;      /* 回転           */
	     SPR_POLY      poly;      /* 4頂点任意指定  */
	     SPR_TRIANGLE  triangle;  /* 三角形         */
	   } SPR_OBJ;


	 4.1.8～4.1.18 までに解説された2Dオブジェクトを、共通の型のポインタ
	 として扱うための構造体定義。ポインタ型を統一するための定義であるため、
	 サイズ計算等にこの構造体を用いてはならない。

	 ※ SPR_POINT等、目的に合ったものを使用すること



  4.2  マクロ

    4.2.1  SPR_FIXED                 座標値用固定小数点数値変換マクロ

	   SPR_FIXED(n)

	 n の値を、ほぼ等価な固定小数点数値(SPR_FIX型)に変換する。
	 SPR_FIX 型については、4.1.1節を参照のこと。


    4.2.2  SPR_FLAG_*                表示属性

	   SPR_FLAG_HIDDEN   非表示フラグ
	   SPR_FLAG_PRIV     特権モード表示フラグ
	   SPR_FLAG_H_REV    水平方向反転(左右反転)
	   SPR_FLAG_V_REV    垂直方向反転(上下反転)
	   SPR_FLAG_ALPHA    アルファブレンディング有効

	 spr_Prim 構造体の flags メンバに設定する属性のビット値が定義された
	 マクロ。複数の属性を同時に持たせたい場合は論理和を取ることで表現
	 できる。



    4.2.3  SPR_SHOW                  2Dオブジェクト表示許可

	   SPR_SHOW(prim)

	 prim で示されるポインタが指す2Dオブジェクトの非表示属性をクリアする。
	 この操作以後、対象の 2D オブジェクトが画面に反映されるようになる。


    4.2.4  SPR_HIDE                  2Dオブジェクト表示禁止

	   SPR_HIDE(prim)

	 prim で示されるポインタが指す2Dオブジェクトの非表示属性をセットする。
	 この操作以後、対象の 2D オブジェクトと、その子として関連付けられて
	 いるオブジェクトは画面に表示されなくなる。



    4.2.5  SPR_PIX_X / SPR_PIX_Y     物理ピクセル座標から対比座表値への変換

	   SPR_PIX_X(chanl, x)
	   SPR_PIX_Y(chanl, y)

	 chanl で指定された表示チャネル上におけるピクセル座標 x もしくは y を、
	 そのチャネルの表示領域上の対比座標値に変換する。

	 ※ このマクロを多用すると、表示環境依存になるため注意。



    4.2.6  SPR_SCALE_X / SPR_SCALE_Y 対比座標値から物理ピクセル座標値への変換

	   SPR_SCALE_X(chanl, x)
	   SPR_SCALE_Y(chanl, y)

	 chanl で指定された表示チャネル上における対比座標値 x もしくは y を、
	 そのチャネルの表示領域上のピクセル座標値に変換する。


    4.2.7  SPR_MAG                   子オブジェクト座標値係数の設定

	   SPR_MAG(prim, mag)

	 prim で指定したオブジェクトの、子以下に登録されているオブジェクトに
	 対する座標値係数を指定する。



  4.3  プログラムインタフェース

    4.3.1  SPR_Init2D_ObjectDriver()       2Dオブジェクトドライバ初期化

	   void * SPR_Init2D_ObjectDriver(void)

	 2Dオブジェクトドライバのモジュールを初期化し、プロセスを登録する。
	 この関数を実行した後でなければ、2D オブジェクトドライバの機能を
	 使用することはできない。

	 戻り値として、2Dオブジェクトドライバが使用している Work のポインタを
	 返し、このポインタを GV_DestroyActor() に渡すことにより、2Dオブジェ
	 クトドライバ自体を破棄することができる。

	 破棄された場合、2D オブジェクトドライバは、2D オブジェクトの
	 DMA転送を停止し、登録されているオブジェクト、DMAパケット等の領域
	 全てを開放する。



    4.3.2  SPR_Create_2D_Object()          2Dオブジェクト生成

	   SPR_OBJ * SPR_Create_2D_Object(SPR_ID id,
					  int chanl,
					  SPR_OBJ * parent)

		id      作成する 2D オブジェクトのタイプ
		chanl   作成する 2D オブジェクトの表示チャネル
		parent  親オブジェクトとする 2D オブジェクトのポインタ


	  指定された型の 2D オブジェクトを作成する。
	  parent に NULL が指定された場合、親を持たない最上位のオブジェクト
	  を作成する。



    4.3.3  SPR_Destroy_2D_Object()         2Dオブジェクト破棄

	   int SPR_Destroy_2D_Object(SPR_OBJ * obj)

	         obj   破棄する 2D オブジェクトのポインタ


	 指定された 2D オブジェクトを破棄し、領域を開放する。



    4.3.4  SPR_LoadTexture()               テクスチャデータのロード

	   int SPR_LoadTexture(int code)

	         code   2D オブジェクトのテクスチャとして使用する
			.tri ファイルの StrCode

	 code で指定された .tri ファイルの内容を、2D オブジェクト用の
	 テクスチャとして登録する。設定した .tri を識別するための
	 テクスチャハンドルを返す。エラーの場合は負の値を返す。

	 既に登録されているテクスチャが指定された場合は、以前に登録された
	 時と同じテクスチャハンドルを返す。



    4.3.5  SPR_KillTexture()               テクスチャデータの開放

	   int SPR_KillTexture(int handle)

	         handle  SPR_KillTexture() から返されたテクスチャハンドル


	 SPR_LoadTexture() 関数で設定されたテクスチャ登録を抹消する。
	 
	 テクスチャとしてロードする。設定した .tri を識別するための
	 テクスチャハンドルを返す。エラーの場合は負の値を返す。

	 複数回 SPR_LoadTexture() が行われたテクスチャに対して使用した
	 場合、SPR_LoadTexture() を呼び出した回数と同じ回数呼ばれるまで、
	 該当するテクスチャの登録を抹消しない。



    4.3.6  SPR_ObjSetTexture()             テクスチャの設定

	   int SPR_ObjSetTexture(SPR_OBJ * obj, int code, int handle)

	         obj    テクスチャを指定する 2D オブジェクト
		 code   使用するテクスチャの StrCode
		 handle 使用する .tri のハンドル

	 SPR_LoadTexture() でロードされた .tri に含まれる、code で指定された
	 テクスチャを prim のテクスチャとして割り当てる。
	 .tri は、SPR_LoadTexture() で返された値を handle として与えることで
	 区別する。


    4.3.7  SPR_SetColor*()                 点/線分/長方形の色指定

	   int SPR_SetColorPoint(SPR_OBJ * point, int r, int g, int b, int a)
	   int SPR_SetColorLine(SPR_OBJ * line,
				int p, int r, int g, int b, int a)
	   int SPR_SetColorLineStrip(SPR_OBJ * lstrip,								     int p, int r, int g, int b, int a)
	   int SPR_SetColorBox(SPR_OBJ * box, int r, int g, int b, int a)
	   int SPR_SetColorSprite(SPR_OBJ * sprite, int r, int g, int b, int a)
	   int SPR_SetColorZoom(SPR_OBJ * zoom, int r, int g, int b, int a)
	   int SPR_SetColorSpin(SPR_OBJ * spin, int r, int g, int b, int a)
	   int SPR_SecColorPoly(SPR_OBJ * poly,
				int p, int r, int g, int b, int a)
	   int SPR_SetColorTriangle(SPR_OBJ * triangle,
				    int p, int r, int g, int b, int a);

		 point    色を指定する点オブジェクト
		 line     色を指定したい線分オブジェクト
		 lstrip   色を指定したい折れ線オブジェクト
		 box      色を指定したい長方形オブジェクト
		 sprite	  色を指定したいサイズ指定矩形オブジェクト
		 zoom	  色を指定したい対角頂点指定オブジェクト
		 spin	  色を指定したい回転オブジェクト
		 poly	  色を指定したい任意四頂点オブジェクト
		 p        線分、折れ線、任意四頂点オブジェクトにおいて
			  色を指定したい頂点の番号(0:始点 / 1:終点)
		 r,g,b,a  RGBA値の各成分

	 各種オブジェクトの表示色を指定する。
	 サイズ指定矩形や対角指定矩形、回転、任意四頂点など、テクスチャを
	 使用できるオブジェクトの場合は、描画の際の RGB 値指定となる。



    4.3.8  SPR_SetPos*()                   表示座標指定

	   int SPR_SetPosEmpty(SPR_OBJ * empty, SPR_POS * pos)
	   int SPR_SetPosPoint(SPR_OBJ * point, SPR_POS * pos)
	   int SPR_SetPosLine(SPR_OBJ * line, SPR_POS * begin, SPR_POS *end)
	   int SPR_SetPosLineStrip(SPR_OBJ * lstrip,
				   int base, int num, SPR_POS * pos)
	   int SPR_SetPosBox(SPR_OBJ * box, SPR_RECT * rect) 
	   int SPR_SetPosSprite(SPR_OBJ * sprite, SPR_POS * pos)
	   int SPR_SetPosZoom(SPR_OBJ * zoom, SPR_RECT * rect)
	   int SPR_SetPosSpin(SPR_OBJ * spin, SPR_POS * pos)
	   int SPR_SetPosPoly(SPR_OBJ * poly, SPR_POS * pos)
	   int SPR_SetPosTriangle(SPR_OBJ * triangle, SPR_POS * pos)

	         empty    仮想オブジェクト
		 point    点オブジェクト
		 line     線分オブジェクト
		 lstrip   折れ線オブジェクト
		 sprite   サイズ指定矩形ビットマップオブジェクト
		 zoom     対角指定矩形ビットマップオブジェクト
		 spin     回転ビットマップオブジェクト
		 poly	  任意4頂点指定ビットマップオブジェクト
		 triangle 三角形ビットマップオブジェクト
 
		 pos      座標をあらわす SPR_POS のポインタ
			  ※ SPR_SetPosPoly() の場合は、頂点4つ分の
			     SPR_POS 構造体の配列を指すポインタ。

		 rect     領域をあらわす SPR_RECT のポインタ
		 begin    始点座標をあらわす SPR_POS のポインタ
		 end      終点座標をあらわす SPR_POS のポインタ

		 base     座標を指定する頂点群の最初の頂点番号
		 num      座標を指定する頂点の数


	 オブジェクトの座標を指定する。親オブジェクトを持たない最上位
	 オブジェクトは画面座標、親を持つオブジェクトは、親の基準点に対する
	 相対座標で指定する。



    4.3.9  SPR_SetSize*()                  表示サイズ指定

	   int SPR_SetSizeSprite(SPR_OBJ * sprite, float w, float h)
	   int SPR_SetSizeSpin(SPR_OBJ * spin, float w, float h)

	         sprite   サイズ指定矩形ビットマップオブジェクト
		 spin     回転ビットマップオブジェクト
		 w        表示上の幅
		 h        表示上の高さ

	 オブジェクトの画面上における表示サイズを指定する。



    4.3.10  SPR_SetCenterSpin()             回転中心指定

	   int SPR_SetCenterSpin(SPR_OBJ * spin, SPR_POS * center)

	         spin     回転ビットマップオブジェクト
		 center   回転中心とする、ビットマップ矩形左上からの
			  オフセット座標値

	 回転ビットマップオブジェクトの、回転中心を指定する。
	 回転中心は正位置状態における左上の点からの相対座標で指定し、
	 ビットマップ面の外側に配置することも可能である。



    4.3.11 SPR_SetRollSpin()               回転角指定

	   int SPR_SetRollSpin(SPR_OBJ * spin, float roll)

	         spin     回転ビットマップオブジェクト
		 roll     時計方向の回転角(単位: ラジアン)


	 回転ビットマップオブジェクトの回転角を指定する。



    4.3.12 SPR_SetLineStripVertexNumber()  折れ線頂点数指定

	   int SPR_SetLineStripVertexNumber(SPR_OBJ * lstrip, int num)

	         lstrip   折れ線オブジェクト
		 num      折れ線の頂点数

	 折れ線オブジェクトの頂点数を決定する。
	 この関数で頂点数を指定することで、頂点情報領域および DMA パケットが
	 確保される。

	 既に頂点数が決定している折れ線オブジェクトに対して用いた場合、
	 古い頂点情報領および DMA パケットは破棄され、新たに頂点情報領域および
	 DMA パケット領域が確保される。

	 その際、以前の頂点情報は新しい頂点情報領域に収まる限り保存される。
	 古い頂点数が新しい頂点数より多い場合は、はみ出した分は切り捨てられ、
	 新しい頂点数のほうが多ければ、あまりの頂点領域の内容は不定となる。


    4.3.13 SPR_SetPriority()               プライオリティ設定

	   int SPR_SetPriority(SPR_OBJ * obj, SPR_PRI pri);

	         pri     プライオリティ値

	 2D オブジェクトのプライオリティ値を設定する。

	 プライオリティ値は、pri に指定されたものの下位3bit のみが有効で、
	 残りのビットは無視される。


    4.3.14 SPR_DuplicateTree()             オブジェクトツリー複製

	   SPR_OBJ * SPR_DuplicateTree(SPR_OBJ * node);

		 node    複製するオブジェクトツリー構造の起点となるオブジェクト

	 各オブジェクトは、親子関係を持ったツリー構造を為すが、この関数を
	 用いることで、複製元となるオブジェクトから先と全く同じ構成を持った
	 枝を作ることができる。

	 複製する枝の起点となるオブジェクトを引数として渡すと、複製された枝の
	 起点として生成されたオブジェクトのポインタを返す。

	 複製された枝の各オブジェクトは、複製時点の複製元オブジェクトと全く
	 同じ属性、表示状態、座標値、テクスチャを持つ。また、登録順による
	 描画優先順位も保持される。

    
以上。
