パラメータ定義の追加

 
 
 

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);

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

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

// 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);