ビューポートでレンダーパスをコントロールするスクリプトフラグメントおよびフラグメントグラフを記述する

はじめに

Maya のビューポートは、次の 2 つの異なるタイプの一連のフラグメント(XML 形式でシリアル化されたスクリプト)を利用します。

シェードフラグメントは、XML 形式の入力および出力定義と共に、コードフラグメントをリアルタイムシェーディング言語(GLSL、HLSL、または Cg)でラップします。このようなフラグメントはネストされたシェードフラグメントグラフに接続され、最終的に、GPU によって実行される最終的なシェーダにコンパイルされます。
スクリプトフラグメントは、一連の必須のスクリプトコマンドを定義します。これらのコマンドは、実行時に Maya によって解釈され、最終的に GPU 状態が変更されたり、描画が呼び出されたりします。スクリプトフラグメントは、上位のコントロールフローを決定するネストされたスクリプトフラグメントグラフに接続することもできます。

Maya をインストールすると、一連のスクリプトフラグメントおよびフラグメントグラフの XML ファイルがインストールフォルダの bin/ScriptFragment サブフォルダに格納されます。

Maya 2020 以前のリリースでは、default.xml は、ビューティパス(シーンとポストエフェクトパスを含むが、シャドウマップとさまざまな UI パスおよび HUD パスは除く)の既定の実装を定義するトップレベルのフラグメントグラフでした。このグラフによって、Maya_3d_Renderer.xml などのさまざまなフラグメントとフラグメントグラフが接続され、そこから、HoldOutPasses.xml や Maya_PostEffects.xml などのフラグメントグラフ、さらに mayaUIDrawPass.xml や Maya_SSAO.xml などのフラグメントとフラグメントグラフが順に接続されました(以下同様)。これらのグラフで参照されるフラグメントの一部は、ハードコードされた C++ プロシージャフラグメントとして実装されます。

Maya の新しいバージョンでも、default.xml およびそのディペンデンシーは Maya に付属していますが、既定のビューティパスの実装は再設計されていて、単一のスクリプトフラグメントグラフで示されることはなくなりました。

MRenderOverride プラグインでは、ビューティパスは MSceneRender 操作で表されます。MSceneRender を構築する場合は、次のように、fragmentName パラメータを使用して、既定の Maya ビューティパスの実装をオーバーライドするカスタムのスクリプトフラグメントまたはフラグメントグラフの名前を指定することができます。

class FragmentRenderOverride(omr.MRenderOverride):

    def __init__(self, name):
        self.operatioIndex = 0
        self.operations =  [omr.MSceneRender("myRendererSameAsMaya", fragmentName=“customBeauty”),
                           omr.MHUDRender(),
                           omr.MPresentTarget("present")]

カスタムフラグメントを作成するときに、bin/ScriptFragment フォルダに含まれている XML ファイルをリファレンスとして使用できますが、Maya の破損を防ぐために、このフォルダ内のファイルを直接変更することはお勧めしません。

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>
```

ビューポートでレンダー パスをコントロールするスクリプト フラグメントおよびフラグメント グラフを記述する