パラメータ定義の追加

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

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

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

特定の ShaderArrayParamDef.ItemInitialValues または ShaderArrayParamDef::GetItemInitialValues が設定された特定の ShaderArrayParamDef.ItemInitialCount または ShaderArrayParamDef::PutItemInitialCount を配列に入力できます。
各項目の名前は既定では Item ですが、ShaderArrayParamDef.ItemName または ShaderArrayParamDef::PutItemName を実行できます。
ShaderArrayParamDef.ItemDef または ShaderArrayParamDef::GetItemDef への参照を取得し、特定のメンバを使用して、それを調整できます。たとえば、構造の配列の場合、多くのサブ定義を構造に追加する必要がありますが、この処理は基本ShaderStructParamDef または ShaderStructParamDef オブジェクトを介して実行できます。
ShaderArrayParamDef.StaticArray または ShaderArrayParamDef::PutStaticArray を実行できます。これにより、ユーザが項目を追加または削除できないようにします。プロパティページの[追加]ボタンと[クリア]ボタンは使用できません。

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

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