フィルタ コールバック

 
 
 

コールバックを 1 つ記述すれば、カスタム フィルタを実装できます。そのコールバックは必ず Match です。 すべてのフィルタは Match を実装していなければなりません。また、オプションとして追加で 2 つのコールバックを実装することが可能です(Subset および IsApplicable です)。

Match コールバック

どのフィルタ コールバック関数も同じ名前付け規則に従い、同じタイプの入力引数を取り、True または False を返します。 以下、Match コールバック関数を例に挙げて説明します。

function My3DObjectFilter_Match( oContext )
{
	// Get the 3D object from the Input attribute of the context
	var o3DObject = oContext.GetAttribute( "Input" );

	// Check if the 3D object matches some filter conditions
	var bMatch = object_isamatch( o3DObject );

	// Return true to keep the object, false to filter the object out
	return ( bMatch );
}

関数名は、フィルタ名("My3DObjectFilter")およびコールバック名("Match")から成り、各名前はアンダースコア(_)で区切られています。 フィルタ名は XSILoadPlugin で指定されます。これは、PluginRegistrar.RegisterFilter の第 1 引数です。

このコールバック関数の唯一の引数は、Context オブジェクトです。このオブジェクトの Input 属性には、フィルタ対象のエレメントが保持されています。3D オブジェクトのフィルタの場合、入力は 3D オブジェクトになります。

Match は、オブジェクトがフィルタに適合している場合は True を、適合していない場合は False を戻します。 Match が True を返した場合は、対応する 3D オブジェクトが選択されます。

Match コールバックは、プロパティ用とオブジェクト フィルタ用とでほとんど同じですが、Input 属性に含まれるオブジェクトのタイプは異なります。 たとえば、ユーザがポリゴン メッシュをクリックしたとき、プロパティ フィルタ用の Match コールバックでは Primitive が取得されるのに対し、3D オブジェクト フィルタ用では X3DObject が取得されます。

Subset コールバック

Subset コールバックは、Match コールバックに似ています。 どちらのコールバックも引数として Context オブジェクトを取り、True または False を返します。 ただし、Subset の場合、オブジェクトのコレクションを Input 属性に保持します。 コンテキストは Output 属性を持ちます。この Output 属性には、フィルタ条件に適合するオブジェクトのサブセットが、Subset によって格納されます。

Softimage でサブコンポーネントの選択をフィルタする場合は常に Match の代わりに Subset が使用されるため、Subset はサブコンポーネント フィルタ用のメイン コールバックとなっています。 サブコンポーネント フィルタ用 Subset コールバック の記述はやや面倒です。なぜなら、サブコンポーネント インデックスを処理するほか、SubComponent オブジェクトを作成または修正する必要もあるためです。 他のフィルタ タイプの場合、オブジェクトがフィルタ条件に適合したときに、コレクションにオブジェクトを追加するだけで済みます。 一例として、3D オブジェクトのサブセットをビルドする方法を、次の例に示します。

function My3DObjectFilter_Subset( oContext )
{
	// Get a new collection to hold the subset
	var cloOutput = new ActiveXObject( "XSI.Collection" );

	// Get the collection of objects to filter
	var cloInput = oContext.GetAttribute( "Input" );

	// Enumerate the objects. If an object matches, add it to the subset
	for (var enumerator = new Enumerator(cloInput) ; !enumerator.atEnd(); enumerator.moveNext())
	{
		var o3DObject = enumerator.item();
		if ( object_isamatch( o3DObject ) )
		{
			cloOutput.Add( o3DObject );
		}
	}

	// Put the subset in the Output attribute		
	oContext.SetAttribute( "Output", cloOutput );

	// Return true if the subset is non-empty
	return (cloOutput.Count > 0);
}

Subset コールバックを指定しない限り、サブセットを判別する各オブジェクトに対して呼び出されるのは Match の方です。 たとえば、次のコードは My3DObjectFilter_Subset 関数を実装しなかった場合でも機能します。

var oFilter = Application.Filters( "My3DObjectFilter" );
var cloSubset = oFilter.Subset( Application.Selection );

IsApplicable コールバック

Softimage は、サブコンポーネントのフィルタをメイン コマンド エリアのフィルタ リストに追加するかどうかを決定するために、IsApplicable コールバックを使用します。 Softimage には、サブコンポーネントのフィルタが現在の選択に適用可能かどうかを判断するためのデフォルト基準が独自に定められています(基本的に Softimage は、選択オブジェクトがサブコンポーネントを持つかどうかをチェックします)。 Softimage はデフォルト基準が満たされない場合にのみ IsApplicable コールバックを呼び出します。

その他のコールバック

また、カスタム フィルタのコールバックには、プラグインのインストール(Init)、削除(Term)、キャッシュからのロード解除(Unload)、およびキャッシュへのロード(Reload)によって起動されるものもあります。 Init および Term は、XSILoadPlugin および XSIUnloadPlugin のプラグイン項目バージョンです。 たとえば、XSILoadPlugin はプラグインがインストールまたは登録されたときに一度だけ呼び出され、Init はプラグインがインストールされた後でプラグイン項目ごとに一度だけ呼び出されます。

  • Init が呼び出されるのは、プラグインが Softimage にインストールされてカスタム フィルタが登録された後(つまり、XSILoadPlugin が返された後)です。 Init が起動するのは、たとえば次の操作を実行したときです。

    • Softimage の起動(Softimage で自己インストール プラグインがすべてロードされます)。

    • プラグイン マネージャからプラグインをロードまたは更新

    • Application.LoadPlugin の実行

  • Term が呼び出されるのは、プラグインが Softimage から除去される直前(つまり、Softimage で XSIUnloadPlugin が呼び出される前)です。 Term が起動するのは、たとえば次の操作を実行したときです。

    • Softimage の終了

    • Application.LoadPlugin の実行

    • プラグイン マネージャからプラグインをロード解除または削除

    Term コールバックが返された後に、コンテキスト内に保存されているユーザ データが解放されます。 また、ユーザ データは、Unload が返された後にも解放されます。

  • Unload は、プラグインがキャッシュからアンロードされるときに呼び出されます。

    プラグイン マネージャ([プラグイン]タブ)で、[キャッシュ済み]列のチェック マークを消去すると、プラグインがキャッシュからロード解除されます。 この操作はプラグイン(.dll/.so ファイルまたはスクリプト ファイル)をメモリからロード解除するものであり、Softimage からロード解除するわけではありません。 Plugin および PluginItem オブジェクトはまだ Softimage 内に存在しており、プラグインは依然として登録されています。

    Softimage は Unload コールバックから戻った後に、コンテキストに格納されているユーザ データを解放します。 また Softimage では、ユーザ データは Unload が返された後にもリリースされます。

  • Reload は、プラグインがキャッシュに再ロードされるときに呼び出されます。

    プラグイン マネージャ([プラグイン]タブ)で、[キャッシュ済み]列を選択(空のセルをクリック)すると、プラグインが再ロードされます。 また Reload は、カスタム フィルタがキャッシュからロード解除された後初めて参照されるときにも呼び出されます。

コールバックの典型的なシーケンスは、次のとおりです。

// Load plug-in (e.g. at startup, Softimage loads a self-installing plug-in)
XSILoadPlugin
<PluginItem>_Init
...
	// User unloads plug-in from cache
	<PluginItem>_Unload
	...
	// User runs script that uses unloaded plug-in, forcing an automatic reload
	<PluginItem>_Reload
...
// Remove plug-in (e.g., exit Softimage)
<PluginItem>_Term
XSIUnloadPlugin

ユーザがキャッシュからプラグインをロード解除すると、プラグインが参照されるたびに、Reload および Unload が呼び出されます。