パラメータ定義を追加する

 
 
 

ShaderParamDefContainer または ShaderParamDefContainer へのパラメータ定義の追加はすべてのパラメータ データ タイプで似ています。配列パラメータの場合は、ShaderParamDefContainer.AddArrayParamDef または ShaderParamDefContainer::AddArrayParamDef メソッドを、その他の場合は ShaderParamDefContainer.AddParamDef または ShaderParamDefContainer::AddParamDef メソッドを使用します。

これらのメソッドでは名前とデータ タイプを指定できますが、特別なオブジェクトShaderParamDefOptions または ShaderParamDefOptions で渡す必要があります。このオブジェクトは新しいパラメータ定義をさらに定義します。 このオブジェクトでは、パラメータ定義の表示名、機能(テクスチャ設定可能、アニメート可能、インスペクト可能)、使用するデフォルト値、有効な値の範囲などを指定できます。 インスタンスを作成するには、XSIFactory.CreateShaderParamDefOptions または XSIFactory::CreateShaderParamDefOptions メソッドを呼び出し、パラメータ定義のために Add メソッドを呼び出す前にその値を設定することができます。

同じオプションは何度も使用できるため、必要に応じて Add メソッドを呼び出す前に必要な変更を加えるだけで済みます。 たとえば、テクスチャ設定可能なパラメータのみを作成する場合で、表示名、デフォルト値、または値の範囲は指定する必要がない場合は、Add メソッドの各呼び出しで同じオブジェクトを使用できます。 また、1 つまたは複数のオプションを変更し、残りのオプションはそのままにしたり、新しくそのオブジェクトのインスタンスを取得して値をリセットすることもできます。 ShaderParamDefOptions または ShaderParamDefOptions も、リファレンスおよびプロパティ ルックアップ データ タイプのフィルター適用、およびカスタム パラメータの作成の上で役立ちます。

単純なパラメータ定義データ タイプの追加に関わる原則は、構造、プロパティ ルックアップ、リファレンスなどのより複雑なタイプにも適用されます。ただし、追加の対策がいくつかあるため、以下のセクションで説明します。

単純なパラメータ定義を追加するには、

ShaderParamDefContainer.AddParamDef または ShaderParamDefContainer::AddParamDef メソッドを呼び出す前に、シェーダ パラメータ定義オプションを設定します。この例では、ShaderParamDefOptions.SetLongName または ShaderParamDefOptions::SetLongName メソッドを使用して UI に表示される名前を設定し、ShaderParamDefOptions.SetTexturable または ShaderParamDefOptions::SetTexturable メソッドを使用してこのパラメータをレンダ ツリーに接続します。

// Set up an RGBA color data type
var oPDefOptions = XSIFactory.CreateShaderParamDefOptions();
oPDefOptions.SetLongName("sweet");		// this becomes the port name in the UI
oPDefOptions.SetTexturable(true);		// display as a node in render tree

// You need to set up the options before you can add the param def
var oInputParamsContainer = oShaderDef.InputParamDefs;
oInputParamsContainer.AddParamDef("simple", siShaderDataTypeColor4, oPDefOptions);

// Change only the UI name, and keep the rest of the settings
oPDefOptions.SetLongName("salty");
oInputParamsContainer.AddParamDef("simple2", siShaderDataTypeColor4, oPDefOptions)

// A similar parameter, this time appearing only as a parameter on the PPGLayout
oPDefOptions.SetTexturable(false);		// display in associated property page only
oPDefOptions.SetInspectable(true);
oInputParamsContainer.AddParamDef("torque", siShaderDataTypeScalar, oPDefOptions);

# etc.
注:

テクスチャ空間 ID やリファレンス コントロールなどの複雑なタイプをさらに追加する方法については、「パラメータ定義の UI コントロールを調整する」を参照してください。

配列パラメータ定義を追加するには

配列パラメータ定義の追加は、同じデータ オブジェクトを 1 つ追加する場合と同じです。 ShaderParamDefContainer.AddArrayParamDef または ShaderParamDefContainer::AddArrayParamDefメソッドは、ShaderArrayParamDef または ShaderArrayParamDef オブジェクトを返します。

// Add an array of gradients
oParamDefOptions = XSIFactory.CreateShaderParamDefOptions();
oParamDefOptions.SetTexturable(true);// connectable port
oInputParams.AddArrayParamDef("train", siShaderDataTypeGradient, oParamDefOptions);

このコードをそのまま使用すると、シェーダは空の配列で初期化され、以下のようになります。

ただし、配列パラメータ定義は以下のようないくつかの方法で調整することができます。

構造パラメータ定義を追加するには

Add メソッドを呼び出すとき、ShaderStructParamDef または ShaderStructParamDef オブジェクトである返される値を取得する必要があります。この特殊パラメータ定義は、ShaderStructParamDef.SubParamDefs または ShaderStructParamDef::GetSubParamDefs メンバを実装し、ShaderParamDefContainer または ShaderParamDefContainer へのアクセスを提供します。このコンテナから、Add メソッドを使用してサブパラメータ定義を追加できます。

// This example of a struct builds the "si_default" input structure for the 
// Bionic Volume (Fast Volume Effects) shader implemented as a plug-in
var oParamDefOpts = XSIFactory.CreateShaderParamDefOptions();
oParamDefOpts.SetTexturable(false);

// Add the structure type parameter to the shader definition
var oInParamDefs = oShaderDef.InputParamDefs;
var oStructParamDef = oInParamDefs.AddParamDef("si_default", siShaderDataTypeStructure, oParamDefOpts);

// Get the structure parameter container and start adding sub-parameter definitions
var oSubParamDefs = oStructParamDef.SubParamDefs;
oParamDefOpts = XSIFactory.CreateShaderParamDefOptions();

// "start"
oParamDefOpts.SetTexturable(false);
oParamDefOpts.SetDefaultValue(5.0);
oSubParamDefs.AddParamDef("start", siShaderDataTypeScalar, oParamDefOpts);

// "stop"
oParamDefOpts.SetDefaultValue(100.0);
oSubParamDefs.AddParamDef("stop", siShaderDataTypeScalar, oParamDefOpts);

// "rate"
oParamDefOpts.SetDefaultValue(1.0);
oSubParamDefs.AddParamDef("rate", siShaderDataTypeScalar, oParamDefOpts);

// "transmit"
oParamDefOpts.SetDefaultValue(0.5);
oSubParamDefs.AddParamDef("transmit", siShaderDataTypeColor4, oParamDefOpts);

// "lightrays"
oParamDefOpts.SetDefaultValue(false);
oSubParamDefs.AddParamDef("lightrays", siShaderDataTypeBoolean, oParamDefOpts);

プロパティ ルックアップ パラメータ定義(CAV、テクスチャ マップ、法線など)を追加するには

プロパティ タイプ パラメータ定義では、ウェイト マップ、テクスチャ マップ、法線、および頂点カラーのプロパティ ルックアップ ウィジットが提供されます。 フィルタを適用して特定のプロパティのウィジットを取得できます。

// Apply the Color-At-Vertices filter to the parameter definition options
var oParamDefOptions = XSIFactory.CreateShaderParamDefOptions();
oParamDefOptions.SetTexturable(false);								// PPGLayout only
oParamDefOptions.SetAttribute(siPropertyFilterAttribute, siCAVPropertyFilter);

// Add the "VertexColor" parameter definition to the input list as a property look-up type
var oInputParams = oShaderDef.InputParamDefs;
oInputParams.AddParamDef("VertexColor", siShaderDataTypeProperty, oParamDefOptions);

リファレンス パラメータ定義を追加するには

リファレンス タイプ パラメータ定義には、ユーザがシーンでエレメントを選択するためのウィジットがあります。 filter を適用して選択できる項目の種類を制限することができます。

// Apply the Cameras filter to the parameter definition options to make sure 
// that the user can only pick cameras
var oParamDefOptions = XSIFactory.CreateShaderParamDefOptions();
oParamDefOptions.SetTexturable(false);									// PPGLayout only
oParamDefOptions.SetInspectable(true);
oParamDefOptions.SetAttribute(siReferenceFilterAttribute, siCameraReferenceFilter);

// Add the reference parameter to the list of input parameter definitions
var oInputParams = oShaderDef.InputParamDefs;
oInputParams.AddParamDef("reference", siShaderDataTypeReference, oParamDefOptions);

特別情報: ライトマップ(カスタム)の出力パラメータ定義を追加するには

mental ray ライトマップ シェーダファミリのシェーダ定義は、常に出力パラメータをカスタム タイプとして定義し、特別な属性をパラメータ定義オプションに設定しライトマップであることを示します。

// Set the custom attribute to mrLmap on the options before adding them
var oParamDefOpts = XSIFactory.CreateShaderParamDefOptions();
oParamDefOpts.SetAttribute(siCustomTypeNameAttribute, siMentalRayLightmapPortType);

// Then add the new method to the output parameters container
var oOutParamDefs = oShaderDef.OutputParamDefs;
oOutParamDefs.AddParamDef("out", siShaderDataTypeCustom, oParamDefOpts);