What is a Custom Filter?

In Softimage, filters allow a user to focus on specific types of objects. For example, Softimage includes a Polygon Mesh filter that removes (filters out) everything that is not a polygon mesh. In a 3D view, filters modify the behavior of the selection tool, making it easier for users to select only the objects they want (for example, only polygon meshes, not nulls or control objects or surface meshes). In the explorer, filters remove unwanted nodes from the element tree.

A custom filter is a self-installing plug-in that implements a Match callback. The job of the Match callback is to determine whether an object should be filtered out. For example, the following example implements a 3D object filter.

// [JScript]
//------------------------------------------------------------------
// Install callback for the plug-in
//------------------------------------------------------------------
function XSILoadPlugin( oPluginRegistrar )
{
	// Give the plug-in a name
	oPluginRegistrar.Name = "MyFilters";

	// Register a filter named "MyFilter" for 3D objects
	oPluginRegistrar.RegisterFilter( "MyFilter", siFilter3DObject );

}

//------------------------------------------------------------------
// Match callback for the filter registered under the name "MyFilter"
//------------------------------------------------------------------
function MyFilter_Match( oContext )
{
	// Get the object from the Input attribute of the Context object
	var o3DObject = oContext.GetAttribute( "Input" );

	// Check if the object matches the filter conditions
	var bMatch = isa_match( o3DObject );

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

Select panel

In Softimage, custom filters appear in the list of selection filters found in the Select panel of the main command area. After a user activates a custom filter, Softimage calls the Match callback for every object the user tries to select in a 3D view (or in the object view or in the schematic view). If Match returns true, Softimage selects the object.

In views such as the Explorer (and the XSI Explorer and the SDK Explorer), custom filters appear in the search box, which has a drop-down list of filters. When a user selects the filter, Softimage calls Match for each node in the explorer and removes the nodes that do not match the filter condition. Custom filters can also provide a Subset callback to handle collections of objects, so Softimage can apply filters by firing a single callback.

You can use custom filters with commands and the object model. For example, you can use a custom filter with the SIFilter command to filter the selected objects:

var cloFilteredList = SIFilter( Application.Selection, "MyFilter" );

In the Softimage object model, custom filters are included in the Filters collection:

var oFilter = Application.Filters.Item("MyFilter");

for ( var enumerator = new Enumerator( Application.Selection ) ; !enumerator.atEnd(); enumerator.moveNext() )
{
	var o3DObject = enumerator.item();
	if ( oFilter.Match( o3DObject ) )
	{
		doSomething( o3DObject );
	}
}

Note that in the above example, a 3D object (such as an X3DObject) is passed into the Match method, not a Context object. Softimage takes care marshalling the 3D object to the Context object expected by the Match callback.

You can also see the Light Filter and Simple Filter examples that are located in the examples folder of the Softimage SDK installation directory.

 Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License