-------------------------------------------------------------------------------
===============================================================================
	F3DEX2 マイクロコード (F3DEX Level2) ドキュメント
	
					Release 2.08
					Jan  5, 1999.
					Copyright (C) 1999, Nintendo.
					任天堂株式会社開発第 3 部    安本吉孝
===============================================================================
-------------------------------------------------------------------------------
目次
	1. F3DEX2 マイクロコードの特徴
	2. F3DEX2 の使用についての詳細
	3. 付録
	4. 変更履歴

-------------------------------------------------------------------------------
1. F3DEX2 マイクロコードの特徴

  F3DEX2 マイクロコードは, 従来よりリリースしておりました F3DEX マイク
ロコードを再構成し RSP の計算速度を高速にしたマイクロコードです. 

  以下の特徴があります.

	o GBI 命令セットは F3DEX と互換性がある(一部 GBI を除く).
	o RSP の処理の高速化が可能.
	o FIFO 形式だけでなく XBUS 形式もサポート.


-------------------------------------------------------------------------------
2. F3DEX2 の使用についての詳細

● GBI の互換性

  F3DEX2 シリーズで使用する GBI は Fast3D/F3DEX シリーズのものとソース
レベルでの互換性を有しています. Fast3D/F3DEX で作成されたコードは, 再
コンパイルによって F3DEX2 で使用可能となります. バイナリレベルでの互換
性はないのでご注意ください.

具体的には, コンパイル時にマクロ F3DEX_GBI_2 を定義する必要があります.

C コンパイラ(cc/gcc)のオプションに -DF3DEX_GBI_2 を追加するか, ソース
ファイルの ultra64.h の include 文の前に define 文を以下のように追加し
てください.

|
|#define	F3DEX_GBI_2
|#include	<ultra64.h>
|

また以下の GBI はサポートしておりません.

  g[s]SPInsertMatrix()


● F3DEX2, F3DEX2.NoN, F3DEX2.Rej, F3DLX2.Rej, L3DEX2 のサポート

  F3DEX でサポートしていた F3DLX / F3DLX.NoN (F3DEX のサブピクセル計算
省略版) および F3DLP.Rej (F3DLX.Rej のテクスチャ補正省略版) のサポート
は無くなりました. この理由は F3DEX マイクロコードの最適化の結果, サブ
ピクセル計算やテクスチャ補正処理を省くことによるメリットがほぼ無くなっ
てしまったことによります. よってこれらのマイクロコードをお使いの方は以
下のような置き換えを行なってください. またマイクロコードの対応について
の詳しい情報は 付録 A にあります.

	gspF3DLX.fifo.o     を使用 ----> gspF3DEX2.fifo.o     を使う
	gspF3DLX.NoN.fifo.o を使用 ----> gspF3DEX2.NoN.fifo.o を使う
	gspF3DLP.Rej.fifo.o を使用 ----> gspF3DLX2.Rej.fifo.o または
	                                 gspF3DEX2.Rej.fifo.o を使う

  また F3DLX2.Rej のサブピクセル計算版の F3DEX2.Rej を新たにサポートし
ました. これは F3DEX2 と違い Clipping を行わず Rejection 処理を行ない
ますが頂点キャッシュが 64 個あり, 処理速度は F3DEX2 より速く,
F3DLX2.Rej より遅くなっています. また得られる画質は F3DEX2 と同等なの
で, 状況に応じて F3DLX2.Rej と F3DEX2.Rej を使い分けるとよいでしょう.


● S2DEX2 のサポート

  スプライトマイクロコードとして S2DEX のかわりに S2DEX2 を用意しまし
た. F3DEX2 シリーズと gSPLoadUcode による自己ロードをしたいときにはこ
れをご使用下さい.

	gspS2DEX.fifo.o を使用 ----> gspS2DEX2.fifo.o を使う

  S2DEX2 マイクロコードは S2DEX と全く性能は変わっていません. F3DEX2 
シリーズと相互にロードできるだけですので, F3DEX2 と混在して使用しない
限りは S2DEX をお使いになられても問題ありません.

  S2DEX2 では F3DEX2 と同様に XBUS 版をサポートしていますが, S2DEX で
サポートしていたデバグ用のマイクロコードである S2DEX_d マイクロコード
は S2DEX2 ではサポートしていません. ご了承ください.

  S2DEX2 マイクロコードの使用法は F3DEX2 と同様で以下のようにします.

	o マクロ F3DEX_GBI_2 をコンパイルオプションで定義するか define 文
	  で ultra64.h の include 文の前に定義する.
	o ヘッダファイル PR/gs2dex.h を ultra64.h の include 文以降に
	  include する.

	define 文を使用したときの例
	|
	|#define	F3DEX_GBI_2
	|#include	<ultra64.h>
	|#include	<PR/gs2dex.h>
	|


● RSP 計算速度の向上

  F3DEX シリーズと比べると F3DEX2 シリーズは 5 〜 70% もの処理時間軽減
が可能です. F3DEX から F3DEX2 への置換が最も軽減効果が大きいため, この
変更によって劇的に RSP の計算速度が改善する可能性があります. また 
F3DLX.Rej から F3DLX2.Rej への置換による軽減効果は F3DEX の時ほど大き
くはありませんが, それでも 5 〜 15% ぐらいありますので試してみる価値は
あるでしょう.


● XBUS マイクロコードのサポート

  グラフィクスマイクロコードは最終的には GBI コマンド列から RDP コマン
ド列を生成し RDP へ送ることによって描画を行うことになります. この RDP 
コマンド列の RDP への送信手法として XBUS 方式, FIFO 方式, DRAM(DUMP)方
式の 3 手法があります.

  FIFO 方式は RDP コマンドを RDRAM 上に FIFO バッファとして展開し RDP 
へ送るものです. これは F3DEX シリーズではこの方式のみがサポートされて
います.

  次に XBUS 方式は RDP コマンドを RSP と RDP を直接繋いでいる内部バス
(XBUS)を通じて RDP へ送るものです. このため FIFO と違い RDRAM を使用し
ません. 現在のライブラリに付随しているサンプルプログラムはこのマイクロ
コードを使用しているものが多数を占めています.

  DRAM(DUMP) 方式は RDP コマンドを RDRAM 上にだた展開するだけのもので
あり, RDP への送信開始処理は CPU がする必要があります. これは RDRAM の
使用量が余りに多いため実用的ではありません.

  歴史的には最初のマイクロコードである Fast3D (F3DEX の元になったバー
ジョン) マイクロコードシリーズには 3 つの手法それぞれに対応するマイク
ロコードがありました. しかし, F3DEX は頂点キャッシュを 16 から 32 に増
やすために XBUS 方式のときに RDP コマンドの送信に使用される内部バッファ
を頂点キャッシュ領域に使用したため, XBUS マイクロコードのサポートが出
来なくなりました. また FIFO マイクロコードと異なり XBUS マイクロコード
は Audio マイクロコードの動作中に RDP に描画処理をさせることが出来ない
ため全体的なパフォーマンスが上がらないため, XBUS のサポートを断念して
いました.

  今回, F3DEX2 シリーズのリリースにあたってこの内部バッファの使用法を
最適化することで, F3DEX シリーズと同じ数の頂点キャッシュを保ったままで
XBUS 方式のマイクロコードをサポートすることができるようになりました.

  XBUS バージョンのマイクロコードで RDP コマンドの送信に使用するの内部
バッファのサイズは通常の FIFO マイクロコードよりも小さいため (約 
1KBytes) RDP の描画処理に時間がかかるような大きな OBJECT を連続して描
画すると内部バッファが一杯になり, RSP は内部バッファが空くまで停止する
ことになります. これがボトルネックとなり RSP の演算処理が遅くなること
も有り得ます. また前記のように RSP での Audio 処理と RDP の描画処理を
並列に行なうこともできません. しかしながら FIFO よりも RDRAM に対する 
I/O が少ないため(約 1/2) RDRAM のバスの競合による CPU/RDP の速度低下に
対する有効な手段となる可能性があります. XBUS マイクロコードを使用され
る場合はいろいろな組み合わせを試してみてください.

  今まで Fast3D の XBUS マイクロコードを使用していたため, F3DEX を使用
できなかった方も, F3DEX2 マイクロコードに乗り換えられることをお勧めし
ます.  マイクロコードの対応についての情報は 付録 A の新旧マイクロコー
ド対応表を参照してください.


● Flat Shading ポリゴンに対する Fog 処理

  Flat Shading 処理されたポリゴン (G_SHADING_SMOOTH=OFF で描画) に対し
て Fog 処理を行なうことができるようになりました.


● CLIPRATIO のデフォルト値の変更

  Fast3D/F3DEX においての CLIPBOX のサイズを指定する CLIPRATIO のデフォ
ルト値が1 から 2 になりました.


● FIFO バッファの最低必要サイズの増大

  FIFO マイクロコードにおける FIFO バッファ (OSTask 構造体における 
output_buff) の最低必要サイズが大きくなりました. gspF3DEX で 0x300
Bytes だったものが

		gspF3DEX2(.NoN) で 0x410 Bytes 
		gspF3DEX2.Rej   で 0x600 Bytes 
		gspF3DLX2.Rej   で 0x600 Bytes 
		gspL3DEX2       で 0x540 Bytes
		gspS2DEX2	で 0x800 Bytes

となりました. もし複数のマイクロコードで FIFO バッファを共用する場合は, 
最も必要サイズが大きいマイクロコードに合わせる必要があります.
また XBUS マイクロコードには FIFO バッファは必要ありません.


● マイクロコードの自己ロード処理の変更

  マイクロコードを自己ロードしたときに, 幾つかのパラメータを保持するよ
うにしました. 保持するパラメータは以下の通りです.

  o DisplayList スタック
  o マトリクススタック
  o ModelView  マトリクス
  o Projection マトリクス
  o セグメントテーブル
  o Scissor Box の範囲
  o SetOtherMode パラメータ
  o PerspNormalize の値
  o ViewPort パラメータ

これ以外の GeometryMode や Light, 頂点キャッシュは保存されません.  ま
た Model および Projection マトリクスは保持されますが, MP マトリクスは
保持されませんので, 再度 M または P マトリクスのどちらか一方をロードし
MP マトリクスを再構成する必要があります.

  またこれらの変更に伴い, 以前の F3DEX/S2DEX マイクロコードとの自己ロー
ドが出来なくなっています. F3DEX2 シリーズ間および F3DEX2 と S2DEX2 マ
イクロコード間でのみ自己ロードが可能です.

  FIFO のマイクロコードと XBUS マイクロコード間でも自己ロードが可能と
なっています.


● F3DLX2.Rej の頂点ロードが一度に 64 個まで行なえるようになった.

  旧版の F3DLX.Rej では頂点キャッシュの数が 64 個になっていましたが,一
度にロードできる頂点の数は 32 個までという制限がありました. そのため 
64 頂点分のデータをロードするためには 2 つの gSPVertex 命令を発行する
必要がありました. 今回リリースする F3DLX2.Rej ではその制限が無くなり,
1 つの gSPVertex 命令で 1 〜 64 頂点分のデータを一度にロードできるよう
になりました. これは F3DEX2.Rej も同様です.


● F3DLX2.Rej の CULL_FRONT サポート

  旧版の F3DLX.Rej では CULL_FRONT/CULL_BOTH をサポートしていませんで
したが, F3DLX2.Rej では双方をサポートしました. F3DEX2.Rej でも当然
CULL_FRONT/CULL_BOTH はサポートしています.


● gSPForceMatrix の GBI 数の変更

  gSPForceMatrix は Fast3D/F3DEX シリーズでは, 4 つの GBI の複合コマン
ドでしたが, F3DEX2 シリーズでは 2 つの GBI の複合コマンドに変更されま
した. この点に依存しているソースコードは変更が必要です. 以下の例を参考
にしてください.

  <例> 修正の必要なコード

	Gfx *gp = glist;	----->	Gfx *gp = glist;
	gSPForceMatrix(gp, mptr);	gSPForceMatrix(gp, mptr);
	gp += 4;			gp += 2;
	     ~~~                             ~~~
  <例> 修正の不要なコード

	Gfx *gp = glist;
	gSPForceMatrix(gp++, mptr);


● Line マイクロコードにおける FillRectangle/TextureRectangle との共存

  Line マイクロコードを使用して Line を描画した後に再度 Scissor Box を
指定しないと FillRectangle/TextureRectangle が正常に描画できないことが
あるという点を L3DEX2 では修正しました. これにより LoadUCode によって 
L3DEX2 -> F3DEX2 というように切替えた場合でも ScissorBox の再設定なし
に描画可能となりました.


● Debug 用マイクロコード F3DEX2d.

  F3DEX2d マイクロコードは F3DEX2 を使用ているアプリケーションの 
RSP/RDP の Debug を補助するためのマイクロコードです. F3DEX2 と互換性が
あり Debug 時に F3DEX2 と置き換えて使用します.

  F3DEX2d には以下の機能があります.

   + RSP の暴走などの場合において, 最後に処理をしようとした Display List の
     物理アドレスを調べる.
   + RDP のパイプラインの Sync 処理を自動で行なう.

  この機能のため F3DEX2 と比べて処理は遅くなっています.

  マイクロコードのエントリの extern 定義をしているファイル ucode_debug.h を
include します.

	|
	|#include  <ucode_debug.h>
	|

, マクロ DEBUG_DL_PTR() を使用することで最後に処理しようとした(暴走時)また
は現在処理中(正常起動中)の Display List の物理アドレスを取得することができ
ます. 

	|
	|	u32	dl_adrs;
	|
	|	dl_adrs = DEBUG_DL_PTR();
	|

  ただし, マイクロコードが完全に暴走状態にあった場合, この物理アドレス
データの保存場所を破壊する可能性もあるので 100% 取得できることは保証で
きません. しかしながら通常は有益な情報を返すことが期待できます.


-------------------------------------------------------------------------------
3. 付録

[A] 新旧マイクロコード対応表

	------------------------------------------------------
	  (旧)Fast3D/F3DEX シリーズ	(新)F3DEX2 シリーズ	
	------------------------------------------------------
	<FIFO>
  	  gspFast3D.fifo.o
	  gspF3DEX.fifo.o      		gspF3DEX2.fifo.o
	  gspF3DLX.fifo.o
	<XBUS>
	  gspFast3D.o			gspF3DEX2.xbus.o
	------------------------------------------------------
	<FIFO>
	  gspF3DNoN.fifo.o
	  gspF3DEX.NoN.fifo.o		gspF3DEX2.NoN.fifo.o
	  gspF3DLX.NoN.fifo.o
	<XBUS>
	  gspF3DNoN.o			gspF3DEX2.NoN.xbus.o
	------------------------------------------------------
	<FIFO>
	  gspF3DLP.Rej.fifo.o
	  gspF3DLX.Rej.fifo.o		gspF3DLX2.Rej.fifo.o 
					gspF3DEX2.Rej.fifo.o 
	<XBUS>
	  対応なし			gspF3DLX2.Rej.fifo.o 
					gspF3DEX2.Rej.fifo.o 
	------------------------------------------------------
	<FIFO>
	  gspLine3D.fifo.o
	  gspL3DEX.fifo.o		gspL3DEX2.fifo.o
	<XBUS>
	  gspLine3D.o			gspL3DEX2.xbus.o
	------------------------------------------------------

	------------------------------------------------------
	<FIFO>
	  gspS2DEX.fifo.o		gspS2DEX2.fifo.o
	  gspS2DEX_d.fifo.o		サポートなし
	<XBUS>
	  対応なし			gspS2DEX2.xbus.o 
	------------------------------------------------------

-------------------------------------------------------------------------------
[B] 各マイクロコードの説明

	gspF3DEX2.fifo.o/gspF3DEX2.xbus.o
		頂点キャッシュ数 32
		サブピクセル計算あり
		クリッピングあり
		
	gspF3DEX2.NoN.fifo.o/gspF3DEX2.NoN.xbus.o
		頂点キャッシュ数 32
		サブピクセル計算あり
		NearPlane 以外の平面によるクリッピングあり
		
	gspF3DEX2.Rej.fifo.o/gspF3DEX2.Rej.xbus.o
		頂点キャッシュ数 64
		サブピクセル計算あり
		リジェクション処理
		(3 角形の一部分が CLIPBOX 外なら 3 角形全体の描画を止める)

	gspF3DLX2.Rej.fifo.o/gspF3DLX2.Rej.xbus.o
		頂点キャッシュ数 64
		サブピクセル計算なし
		リジェクション処理
		(3 角形の一部分が CLIPBOX 外なら 3 角形全体の描画を止める)

	gspL3DEX2.fifo.o/gspL3DEX2.xbus.o
		ラインマイクロコード
		頂点キャッシュ数 32
		サブピクセル計算あり
		クリッピングあり

	gspS2DEX2.fifo.o/gspS2DEX2.xbus.o
		スプライトマイクロコード

-------------------------------------------------------------------------------
4. 変更履歴

03/26/98:
    Release 2.00
	* 正式リリース

03/30/98:
    Release 2.01
	* F3DEX2.Rej を追加, F3DLX2.Rej の若干の高速化

04/16/98:
    Release 2.02 (patchNg980423 版)
	* gSPForceMatrix の GBI 数の変更/Line マイクロコードにおける 
	  FillRectangle/TextureRectangle との共存についての情報の追加
	* 空のスタックに対し gSPPopMatrix 処理をしたときに暴走するのを
	  修正し, スタックが空の時は gSPPopMatrix を無視するようにした.
	* gSPLoadUcodeL で F3DEX2 シリーズと相互ロードが可能な S2DEX2
	  マイクロコードをパッケージに追加し, それに関する説明を追加した.
	* S2DEX 1.06 において gSPBgRectCopy 命令で幅の狭いフレームに対
	  する描画処理が正常に機能しなかったことの修正.
	* Flat Shading を使用したときにクリッピング処理が起きると Flat
	  Shading の色が不定になることの修正.
	* gSPLightColor で LIGHT_1 以外の指定がおかしかったことの修正.

04/23/98:
    Release 2.03
	* gSPBranchLessZ* 命令が正常に動作しないことの修正.
	* ライトを 3 個以上使用したときにカラーが正しくでないことの修正.

05/20/98:
    Release 2.04
	* 128 で正規化された法線ベクトルが設定された頂点を含む３角形の
	  ライティング計算が正常に行われない場合があることの修正.

05/28/98:
    Release 2.04 (patchNg980610 版)
	* G_TEXTURE_ENABLE を無効にするために gbi.h を変更.
	* マイクロコードは 05/20/98 版から変更なし

06/15/98:
    Release 2.05
	* G_TEXTURE_GEN_LINEAR の動作を修正.
	* F3DEX2.NoN で視点の手前から NearPlane の間に描画されるポリゴンの
	  Z 座標値が定義範囲を超えることの修正.
	* クリッピング処理によってクリップされた結果多角形に変換されたポリ
	  ゴンを描画したときの結果を F3DEX シリーズのそれとなるべく等しくな
	  るように描画方法を変更.

07/29/98:
    Release 2.06
	* F3DEX2.NoN における NearClip 処理の不都合を修正.

10/04/98:
    Release 2.07
	* F3DEX2, F3DEX2.NoN, F3DEX2.Rej において隣接したポリゴンの境界に小
	  さな穴が開くことがあるのを修正.

01/05/99:
    Release 2.08
	* 一部のマイクロコードを起動した直後に F3DEX2 を起動した場合に, 
	  レジスタの初期化に失敗する可能性があるのを修正.
	* Debug 用マイクロコードの追加. 本ドキュメントの 2 章に関連項目
	  を追加.

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