Filter Callbacks

Match Callbacks

All filter callback functions follow same naming convention, take the same type of input argument, and return true or false. For example, consider a Match callback function:

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

The function name is the name of the filter ("My3DObjectFilter") and the callback name ("Match"), separated by an underscore (_). The filter name is specified in XSILoadPlugin: it's the first argument to PluginRegistrar.RegisterFilter.

The only argument to the callback function is a Context object, which holds the elements to filter in its Input attribute. For a 3D object filter, the input is a 3D object.

Match returns True if the object matches the filter, and False otherwise. When Match returns True, Softimage selects the corresponding 3D object.

The Match callbacks for property and object filters are pretty much the same, except for the types of objects they get in the Input attribute. For example, when a user clicks a polygon mesh, the Match callback for a property filter gets a Primitive, while the Match callback for a 3D object filter gets an X3DObject.

Subset Callbacks

Subset callbacks are similar to Match callbacks. They take a Context object as an argument, and return true or false. However, for Subset, the Input attribute holds a collection of objects. And the context has an Output attribute where Subset puts the subset of objects that match the filter conditions.

Subset is the main callback for subcomponent filters, because Softimage always uses Subset instead of Match to filter selections of subcomponents. Writing Subset callbacks for subcomponent filters is somewhat more involved, because you have to work with subcomponent indices and either create or modify SubComponent objects. For other filters types, you simply add objects to a collection if the objects match the filter conditions. For example, the following example shows how to build a subset of 3D objects.

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

If you don't provide a Subset callback, Softimage calls Match on each object to determine the subset. For example, the following code works even if you don't implement a My3DObjectFilter_Subset function:

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

IsApplicable Callbacks

Softimage uses the IsApplicable callback to determine whether to add subcomponent filters to the filter list in the main command area. Softimage has its own default criteria for determining whether a subcomponent filter is applicable to the current selection (basically, Softimage checks if the selected objects have subcomponents). Softimage calls your IsApplicable callback only if its default criteria are satisfied.

Other Callbacks

A custom filter also has callbacks that are triggered when a plug-in is installed (Init), removed (Term), unloaded from the cache (Unload), and loaded into the cache (Reload). Init and Term are the plug-in item versions of XSILoadPlugin and XSIUnloadPlugin. For example, XSILoadPlugin is called once when a plug-in is installed and registered, and Init is called once for each plug-in item after the plug-in is installed.

• Init is called after the plug-in is installed in Softimage and the custom filter is registered (that is, after XSILoadPlugin returns). For example, Init is triggered when you:

  • Start Softimage (and Softimage loads all the self-installing plug-ins)

  • Load or update the plug-in from the Plugin Manager

  • Run Application.LoadPlugin

• Term is called just before a plug-in is removed from Softimage (that is, before Softimage calls XSIUnloadPlugin). For example, Term is triggered when you:

  • Exit Softimage

  • Run Application.UnloadPlugin

  • Unload or delete the plug-in from the Plugin Manager

  Softimage releases any user data stored in the context after the Term callback returns. Softimage also releases the user data after Unload returns.

• Unload is called when the plug-in is unloaded from the cache.

  A plug-in is unloaded from the cache when a user clears the check mark in the Cached column (Plug-ins tab) of the Plugin Manager. This unloads the plug-in (the .dll/.so file, or the script file) from memory, but does not "unload" the plug-in from Softimage. The Plugin and PluginItem objects still exist in Softimage, and the plug-in is still registered.

  Softimage releases any user data stored in the context after the Unload callback returns. Softimage also releases the user data after Term returns.

• Reload is called when the plug-in is reloaded into the cache.

  A plug-in is reloaded when a user selects Cached (clicks an empty cell in the Cached column) on the Plug-ins tab of the Plug-in Manager. Reload is also called the first time the custom filter is referenced after being unloaded from the cache.

The typical sequence of callbacks is as follows:

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

If a user unloads a plug-in from the cache, then Reload and Unload are called every time the plug-in is referenced.