ビューポートにレンダリングするフラグメントおよびフラグメントグラフを記述する

はじめに

フラグメントは、高レベル言語におけるプロシージャまたは関数の定義のことです。フラグメントには入力および出力が挿入されていて、入力に対して何らかのプロシージャが実行され、出力が生成されるようになっています。

シェーディングフラグメントを記述するか、一連のコマンドを実行するスクリプトフラグメントを記述して、パラメータや状態の設定、さまざまなターゲットのクリア、またはさまざまなターゲットへのレンダリングを行うことができます。

その後、フラグメントをフラグメントグラフに接続できます。フラグメントグラフにコマンドは含まれていません。フラグメントグラフが行うことは、一連のフラグメントをインスタンス化して、これらの間の接続を記述することです。

1 つの .xml ファイルには 1 つのスクリプトフラグメントまたはフラグメントグラフを保存できます。

Maya をインストールすると、一連のスクリプトフラグメントおよびフラグメントグラフの xml ファイルがインストールフォルダの bin/ScriptFragment フォルダに格納されます。これらのフラグメントおよびフラグメントグラフは、ビューポート 2.0 にレンダリングする場合に使用されます。

Default.xml は、Viewport 2.0 での Maya のレンダリング方法を示すメインのフラグメントグラフです。このフラグメントグラフを実行すると、ビューポートにシーンが表示されます。

これにより、さまざまなフラグメントおよびフラグメントグラフが接続されます。たとえば、HoldOutPasses などのフラグメントグラフを接続する Maya_3d_Renderer、mayaUIDrawPass や Maya_SSAO などのフラグメントとフラグメントグラフを接続する Maya_PostEffects などです。

これらの xml ファイルは、フラグメントレンダラ用の独自のスクリプトフラグメントおよびフラグメントグラフを記述する例として使用できます。

独自のフラグメントレンダラを作成する場合は、既存の Maya フラグメントを再利用し、カスタマイズするフラグメントの xml のみを記述することができます。たとえば、独自のカスタムモーションブラーパスを作成する場合は、モーションブラーフラグメントを記述して既存の Maya フラグメントと結合することができます。

この操作を実行するには、次のような手順を実行します。

既存の Maya フラグメント/フラグメントグラフの .xml ファイルを新しいフォルダにコピーします。
カスタマイズするフラグメント/フラグメントグラフを修正して、名前を変更します。

注: bin/ScriptFragment のファイルを直接修正することはお勧めしません。誤って Maya を破損することがあります。したがって、まずフラグメントファイルを新しいフォルダにコピーすることをお勧めします。
(手順 2 で)修正したフラグメント/フラグメントグラフを指すようにメインフラグメントグラフ(default.xml)を修正し、メインフラグメントグラフに新しい名前を付けます。

プロシージャの中にはスクリプトフラグメントとして表現するのが困難なものがあり、それらは Maya によってハードコードされた C++ プロシージャフラグメントとして提供されています。C++ プロシージャフラグメントはフラグメントグラフ内のスクリプトフラグメントと結合することができます。

ヒント: Maya のレンダラを再現するには、まず次のような一連の操作を行って MRenderOverride を初期化します。
class FragmentRenderOverride(omr.MRenderOverride):

   def __init__(self, name):
       self.operatioIndex = 0
       self.operations =  [omr.MSceneRender("myRendererSameAsMaya", “default”),
                          omr.MHUDRender(),
                          omr.MPresentTarget("present")]
default は、オーバーライドされていない場合に Maya が使用するレンダーフラグメントの名前です。default.xml は Maya インストールフォルダの bin/ScriptFragment フォルダ内にあります。

default では、ビューティパスが描画され、UI、シャドウマップ、HUD など、MSceneRender の要素となるものは含まれません。

API クラスおよびインタフェース

フラグメントレンダラを作成するための API エントリポイントは次のとおりです。これらのインタフェースの使用例については、Developer Kit の viewRenderOverrideFromFragments プラグインおよび「フラグメントレンダラサンプルプラグインを作成する」を参照してください。

フラグメントマネージャにアクセスするには、MRenderer::getFragmentManager() を呼び出します。スクリプトフラグメントまたはフラグメントグラフを登録するには、MFragmentManager::addFragmentGraphFromFile() を呼び出します。
この MSceneRender コンストラクタを使用して、シーンレンダーを作成します。このコンストラクタにより、シーンのレンダリングに使用するフラグメント名を指定できます。
```
 MSceneRender (const MString &name, const MString &fragmentName)
```
MSceneRender から派生した、カスタムレンダー操作の 1 つである MRenderOperation のリストで MRenderOverride を初期化します。
MRenderer::registerOverride() を呼び出して登録します。
レンダーパラメータを取得または設定するには、次の手順を実行します。
- MSceneRender::getParameters() を呼び出して、レンダラのコントロールに使用される一連のレンダー入力パラメータである MRenderParameters のポインタを返します。
- MRenderParameters::setParameter() を呼び出して、カスタムの MSceneRender で使用されるレンダーフラグメントに値を渡します。
(オプション) MRenderScriptCallback クラスから派生して、スクリプトフラグメント .xml から登録および呼び出し可能なコールバック関数を作成します。execute() 関数を実装して、現在のレンダーグラフから MRenderParameters を取得し、スクリプトから渡された 3 つのオプション値を取得できるようにします。このメソッドを使用して目的の動作を計算し、MRenderParameters::setParameter() を呼び出し、スクリプトまたはグラフ内の接続された他のフラグメントに結果を戻します。詳細については、「スクリプトフラグメントコマンド」トピックの呼び出しコマンドについての説明を参照してください。

MRenderer::registerScriptCallback() および MRenderer::deregisterScriptCallback() インタフェースで、MRenderScriptCallback の登録または登録解除を行うことができます。登録した後に、スクリプトフラグメント .xml で Call コマンドを使用して、このコールバックを呼び出すことができます。

フラグメントおよびフラグメントグラフ XML の定義

フラグメントの各部の説明

例については maya_DepthPrePass.xml を参照してください。

すべてのフラグメントは複合要素 fragment に含まれています。

<fragment  uiName="maya_DepthPrePass" name="maya_DepthPrePass" type="sceneEffect" class="ScriptFragment" version="1.0" feature_level="30" >

name アトリビュートをフラグメントの内部名に設定します。
uiName を内部名と同じに設定したり、外部名を指定したりできます。
type アトリビュートを sceneEffect に設定します。
フラグメントの場合は、class アトリビュートは ScriptFrament に(フラグメントグラフの場合は FragmentGraph に)設定する必要があります。
リリース間の変更を識別するために version アトリビュートを設定します。通常は、この例のようにこの値を 1.0 に設定できます。
feature_level アトリビュートを、パス内で使用されるエフェクトおよび機能で必要とされる最大の機能レベルサポートに設定します。たとえば、feature_level 30 は DirectX 10 に相当します。通常、この値は、この例のように 30 に設定すれば十分です。

フラグメントの定義には次の要素も含まれています。

オプションの description 要素。description は CDATA ブロックでラップされます。

 <description>
     <![CDATA[
     depth pre-pass: make depthStencil & linear, readable opaque depth texture]]>
 </description>

必須の入力パラメータセットである properties。

<type name ="myParam"> 形式を使用します。type はパラメータのタイプ(int、float4 など)、name はパラメータの必須の名前です(セット内で一意である必要があります)。

ここには Maya で事前に定義された既知の入力である preOpaqueUIList、transparentBitmapsList、カメラ、ビューポートなども含まれます。
```
 <properties>
     <countedObject  name="preOpaqueUIList" />
     ....
 </properties>
```
入力接続を含まないパラメータの一連の初期 values

value 要素内で初期値を持つパラメータを定義するには、次の形式を使用します。
```
 <type name ="myParam" value ="…" /> 
```
value 文字列の正確な形式は、パラメータのタイプによって決まります。複数の値を指定するには、カンマ区切りリストを使用します。たとえば、「0,1,3」は int3 または float3 パラメータと一致します。

同じ名前を共有するフラグメントグラフ内のすべてのアトリビュートは、これらの値を使用して初期化されます。
```
 <values>
     <float4 name="viewport" value="0.000000,0.000000,1.000000,1.000000"  />
     ....
 </values>
```

一連の出力パラメータである outputs:

 <outputs>
     <target  name="depthOut" />
     <target  name="opaquedepthtexture" />
 </outputs>

コマンドのリストを含む実装要素。render を OGS に、language を ScriptInterpreter に設定します。

各コマンドは次の形式の単一の要素によって定義されます。
```
 <command     value="theValue" />
```
```
 <implementation render="OGS" language="ScriptInterpreter" version="0.1" >
     <scriptCommands>
         <AcquireTarget name="localZ" format="EFORMAT_R32_FLOAT" size="@finalDesc.size" relSize="1.0,1.0" msaa="0" />
         ....
     </scriptCommands>
 </implmentation>
```
使用可能なコマンドのリストについては、「スクリプトフラグメントコマンド」を参照してください。

コマンドをリストする場合は、記号 @ を使用して、値をローカル値によって設定するのではなく、パラメータから取得するように指定します。たとえば、上記のコードスニペットでは、値は finalDesc パラメータから取得されます。

フラグメントグラフの各部の定義

上記のように、さまざまなフラグメントおよびフラグメントグラフを相互に接続して単一のフラグメントグラフを形成できます。

例については Maya_PostEffects.xml を参照してください。

すべてのフラグメントは次のように複合要素 fragment_graph に含まれています。

<fragment_graph  name="Maya_PostEffects" ref="Maya_PostEffects" class="FragmentGraph" version="1.0" feature_level="0" >

ref アトリビュートをフラグメントグラフの内部名に設定します。
name アトリビュートを内部名と同じにしたり、外部名を指定したりできます。
class アトリビュートは FragmentGraph に設定する必要があります。

fragment_graph の定義には次の要素も含まれます。

Fragments

このグラフに含まれているすべてのフラグメントをリストします。リストの順番は重要ではありません。
```
 <fragments>
     <fragment_ref name="Maya_UI" ref="mayaUIDrawPass" />
     ....
 </fragments>
```
ref アトリビュートをフラグメントの内部名または既定名に設定します。つまり、XML ファイル内の fragment 要素の name アトリビュートで定義された名前に設定します。

name アトリビュートを ref アトリビュートと同じ値に設定できます。また、異なるインスタンスで使用するように別の名前に設定することもできます。このように、2 つの異なるパスで同じアトリビュートを使用する場合、そのアトリビュートに 2 つのパスで別々の接続を設定することができます。

たとえば、Maya_PostEffects.xml を参照してください。Maya_PostEffects フラグメントグラフにはグラフ Maya_SSAO が含まれています。
```
 <fragment_ref name="Maya_SSAO" ref="Maya_SSAO" />
```
その後で、Maya_SSAO.res を Maya_MotionBlur.input に接続します。
```
 <connect from="Maya_SSAO.res" to="Maya_MotionBlur.input" name="input" />
```
別のパスまたはフラグメントグラフ内で Maya_SSAO に対する別の接続を作成する場合は、次の手順を実行します。
```
 <fragment_ref name="Maya_SSAO_instance1" ref="Maya_SSAO" />
```
次のように接続します。
```
 <connect from="Maya_SSAO_instance1.res" to="Maya_MotionBlur.input" name="input" />
```
Maya_MotionBlur.input は別のフラグメントグラフで異なる入力を受け取ることができるようになりました。
接続(Connections)

フラグメント間のすべての接続を指定します。各接続要素は、1 つのプロパティ入力 to に接続された 1 つの出力 from を指定します。

入力に含めることができるのは 1 つの接続のみですが、出力には任意の数の接続を含めることができます。接続されていない入力にはセマンティックで照合されるシステム入力変数を指定するか、または API を通して微調整することができます。
```
 <connections>
     <connect from="mayaPreUIScript.output" to="Maya_UI.final" name="final" />
     ....
 </connections>
```
注: finalは、操作の最後に結果を描画するバッファを示します。
プロパティ

サブフラグメント/フラグメントグラフの名前とアトリビュート、およびこれを表すために使用する外部名を指定して、未接続のすべての入力パラメータをリストします。

たとえば、次のようになります。
```
 <properties>
     <float4  name="viewport" ref="Maya_SSAO.viewport" />
     ....
 </properties>
```
Maya_SSAO はサブフラグメントグラフです。このビューポートアトリビュートを公開するには、エイリアス viewport を使用する必要があります。

値(Values)

未接続の入力パラメータの初期値を定義します。

 <values>
     <float4 name="viewport" value="0.000000,0.000000,1.000000,1.000000"  />
     ....
 </values>

出力(Outputs)

ここで出力を指定し、一次出力を最初にリストします。
```
 <outputs>
     <target  name="output" ref="Maya_UI.output" />
 </outputs>
```

ビューポートにレンダリングするフラグメントおよびフラグメント グラフを記述する