Init コールバックでは、カスタム コマンドに引数を追加します。 たとえば、次のInitコールバックは 2 つの引数を追加します。
Arg0 は、「Collection」という名前の引数ハンドラを使用します。 この引数ハンドラは、「Cube*,sphere*」や「*#model」などの文字列をオブジェクトのコレクションに変換し、現在の選択内容をデフォルトの引数値として提供します。
Arg1 は、ブール フラグです(デフォルトは false)。 ArgumentCollection.Add または ArgumentArray::Add メソッドでは、オプションでデータ型を指定する 4 番目のパラメータを使用できますが、Softimage は既定値からほとんどの引数のデータ型を判断することができます。
// [ JScript ] function MyCommand_Init( ctxt ) { // Get the Command object from the callback context var oCmd; oCmd = ctxt.Source; // Get the ArgumentCollection var oArgs; oArgs = oCmd.Arguments; // Arg0 is a collection of Softimage objects // By default, Softimage passes in the current selection oArgs.AddWithHandler("Arg0","Collection"); // Arg1 is a boolean flag that is false by default oArgs.Add( "Arg1", siArgumentInput, false ); return true; }
Execute コールバックにはコマンドと同じ引数があります。 コマンドに新しい引数を追加した場合、Execute コールバックのシグネチャを更新する必要があります。
// [ JScript ] function MyCommand_Execute( Arg0, Arg1 ) { // ... }
引数ハンドラとデフォルト値を使用すると、カスタム コマンドが組み込みコマンドのように動作します。
// [ JScript ] MyCommand();// same as MyCommand( Application.Selection, false ) MyCommand( null, true );// same as MyCommand( Application.Selection, true ) MyCommand( "*" );// Arg0=all objects; Arg1=false MyCommand( "#3dobject*", true );// Arg0=3d objects only, no models; Arg1=true
ブール引数、文字列引数、および数値引数を追加するには、ArgumentCollection.Add または ArgumentArray::Add メソッドを使用して、既定値を指定します。Softimage はデフォルト値からデータ型を判断できるので、Add への最後のパラメータを省略できます。
// [ JScript ] oArgs.Add( "bFlag", siArgumentInput, false ); // boolean oArgs.Add( "bFlag", siArgumentInput, false, siBool );// Same as above oArgs.Add( "sName", siArgumentInput, "Custom" );// string oArgs.Add( "nParam", siArgumentInput, 4 );// number
Softimage は、引数の型が判断できたら、引数値を指定されている型に変換しようとします。 引数の追加時にデフォルト値または引数の型を指定しない場合、コマンドは引数としてどのような型の値でも受け入れます。
// [ C++ ] XSIPLUGINCALLBACK CStatus MyCommand_Init( CRef& in_ctxt ) { Context ctxt( in_ctxt ); Command oCmd; oCmd = ctxt.GetSource(); ... ArgumentArray oArgs; oArgs = oCmd.GetArguments(); oArgs.Add(L"Arg0");// No default value return CStatus::OK; } // Arg0 can be any type of value. // JScript examples: // MyCommand( "arg" ); // MyCommand( true ); // MyCommand( 35 ); // // var a3 = new Array(10, "Hello", Date()); // MyCommand( a3 );
C++ コマンドの場合、Executeコールバックの引数値のタイプを確認する必要があります。
// [ C++ ] XSIPLUGINCALLBACK CStatus MyCommand_Execute( CRef& in_ctxt ) { Context ctxt( in_ctxt ); CValueArray args = ctxt.GetAttribute(L"Arguments"); CValue Arg0 = args[0]; if( args[0].m_t == CValue::siBool ) ... }
配列引数については、予定しているコマンドの使用方法に応じて、引数の追加方法が決定します。 コマンドを他のスクリプト言語または C++ から呼び出す場合は、Softimage で配列引数を安全な配列に変換させる必要があります。 Executeコールバックで、安全な配列を JScript 配列に変換する必要があります。
oArgs.Add( "safeArray", siArgumentInput );// safe array
コマンドを JScript コードからのみ使用する予定であれば、引数タイプとして siDispatch を指定するとパフォーマンスを向上させることができます。これにより、Softimage が入力配列を安全な配列に変換するのを防ぐことができます。
oArgs.Add( "jsArray", siArgumentInput, 0, siDispatch );// JScript array
JScript オブジェクトをコマンドに渡すには、引数の型として siDispatch を指定します(これにより、Softimage が引数を安全な配列に変換するのを防ぐことができます)。
oArgs.Add( "jsObject", siArgumentInput, 0, siDispatch ); // JScript object
例については、ArgumentCollection.Add のリファレンス ページを参照してください。
引数ハンドラを使用すると、引数としてコレクション、オブジェクト、およびマーク パラメータを取得するカスタム コマンドが簡単に記述できます。 また、引数ハンドラを使用すると、引数として現在のフレーム番号やフレーム レートを取得することもできます。
引数ハンドラは、引数値の検証を行い、「*」などの文字列をオブジェクト リストに変換して、デフォルト値を提供します。
// [ JScript ] oArgs.AddWithHandler("Arg","Collection"); // Examples MyCommand(); // Same as MyCommand( Application.Selection ); MyCommand( "cone,cube,sphere" ) MyCommand( "#model" ); // All models, incl. Scene_Root
// [ JScript ] oArgs.AddWithHandler("Arg","Collection"); // Examples MyCommand(); // Same as MyCommand( Application.Selection ); MyCommand( "sphere.pnt[1,7,8,13-15" )
// [ JScript ] oArgs.AddWithHandler( "Arg", "SingleObj" ); // Shortcut adding args with the SingleObj argument handler oArgs.AddObjectArgument( "Arg" ); // Examples MyCommand( Application.Selection.Item(0) ); MyCommand( "cone" ); MyCommand(); // Same as MyCommand(null)
C++ に引数を追加するのは、スクリプトに引数を追加する場合によく似ています。 ArgumentArray::Add で単純なタイプの引数(ブール、文字列、配列など)を追加することも、ArgumentArray::AddWithHandler で特定のハンドラを使用して引数を追加することもできます。
違うのは、C++ Add メソッドには 2 つのパラメータ(引数名とデフォルト値)しかない点です。 引数値の型を指定するためのパラメータは存在しません。
// [ C++ ] XSIPLUGINCALLBACK CStatus MyCommand_Init( CRef& in_ctxt ) { Context ctxt( in_ctxt ); Command oCmd; oCmd = ctxt.GetSource(); oCmd.EnableReturnValue(true); ArgumentArray oArgs; oArgs = oCmd.GetArguments(); // Add some simple-type args. oArgs.Add( L"bFlag", false ); // siBool oArgs.Add( L"sString", L"someString" ); // siString oArgs.Add( L"nNumber", 0l ); // siInt4 oArgs.Add( L"Float", 0.0f ); // siFloat oArgs.Add( L"Arg" ); // No default value, so can be any type // Default value is the current selection oArgs.AddWithHandler( L"cloObjects", L"Collection" ); // Default value is the all marked animatable parameters oArgs.AddWithHandler( L"Arg0", L"AnimatableParameters" ); return CStatus::OK; }