引数の追加

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)

現在のフレーム番号とフレームレートを取得するには、次のようなコードを使用します。

// [ JScript ]
oArgs.AddWithHandler("currentFrame","Frame");
oArgs.AddWithHandler("frameRate","FrameRate");

現在選択されているオブジェクトのマークパラメータを取得するには、次のようなコードを使用します。

// [ JScript ]
// All marked parameters, both animatable and non-animatable
oArgs.AddWithHandler("Arg5","MarkedParameters");

// Only the animatable marked parameters
oArgs.AddWithHandler("Arg0","AnimatableParameters");

C++ コマンドへの引数の追加

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