RegisterFilter (PluginRegistrar)

Introduced

4.0

Description

Registers a custom filter in Softimage.

Scripting Syntax

    PluginRegistrar.RegisterFilter( Name, Type )

C# Syntax

    PluginItem PluginRegistrar.RegisterFilter( String in_name, siFilterType in_Type );

Parameters

Parameter | Type | Description
Name | String | The name of the custom filter to register. It should begin with a letter and contain only letters, numbers and the underscore character. The filter name is used to name the filter callback functions such as Match and Subset. For example, the Match callback for a filter named "My3DObjectFilter" is "My3DObjectFilter_Match". If a filter name contains spaces (for example, "My 3D Object Filter"), the callback function names must omit the spaces (for example, "My3DObjectFilter_Match"). The filter name also appears in the Softimage user interface, and is the name you use to reference the filter in scripting or C++ code. If the filter name contains spaces, you must replace the spaces with underscores to use the filter with scripting commands or the object model. For example, if you register a filter with the name "My Custom Filter", then to get the filter from the FiltersCollection, you need to replace the spaces with underscores: var oFilter = Application.Filters.Item( "My_Custom_Filter" );
Type | siFilterType | Type of filter to register.

Return Value

PluginItem

Examples

JScript Example

    /*-------------------------------------------------------------------
       This example shows how to register, implement and use a
       custom filter.

       README: Copy and paste the example into the script editor
       and run (F5).

       The filter will now be listed in the Scene Explorer
       filter list when the "Source/Clips" view context  is
       selected.
    -------------------------------------------------------------------*/

    function  XSILoadPlugin( in_reg )
    {
       in_reg.Author = "Softimage Co."
       in_reg.Name = "PluginRegistrar.RegisterFilter Example"

       // register the cone filter plug-in item
       in_reg.RegisterFilter( "ExRegisterFilter_ConePrimitive", siFilterObject );

       // register a command to illustrate usage
       in_reg.RegisterCommand( "ExRegisterFilterDemo", "ExRegisterFilterDemo" );

       return true;
    }

    function  ExRegisterFilter_ConePrimitive_Match( in_context )
    {
       var obj = in_context.GetAttribute("Input");
       return obj.IsKindOf( siConePrimType );
    }

    // This command shows how to use the ConePrimitive filter
    function  ExRegisterFilterDemo_Execute()
    {
       Application.LogMessage("Running ExRegisterFilterDemo");

       var filter = Application.Filters( "ExRegisterFilter_ConePrimitive" );
       Application.LogMessage( "Filter: " + filter.Name + " type=" + filter.Type );

       var sphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface", "sphere" );
       var cone = ActiveSceneRoot.AddGeometry( "Cone", "MeshSurface", "cone" );

       // log all objects that match the filter
       var eChildren = new Enumerator(ActiveSceneRoot.Children);

       for (;!eChildren.atEnd();eChildren.moveNext())
       {
           var child = eChildren.item();
           Application.LogMessage( child.name + " is a cone: " + filter.Match( child ) );
       }
    }

    //--------------------------------------------------------------------
    // Code to bootstrap example into system
    //--------------------------------------------------------------------
    function ExampleSourceCode()
    {
       return "//XSISDK Doc Example\n" +
           ExRegisterFilter_ConePrimitive_Match.toString() + "\n" +
           ExRegisterFilterDemo_Execute.toString() + "\n" +
           XSILoadPlugin.toString();
    }

    // if we are running from script editor save code to
    // examples addon folder in the user's directory.
    if (GetUserPref("ScriptingSessionActive"))
    {
       var ex_name  = "ExPluginRegistrarRegisterFilter";
       var ex_subfolder  = "Plugins";
       var ex_folder  = "XSISDKDocExamples";
       var ex_langsuffix = ".js";

       CreateAddonDirectories( InstallationPath(siUserPath), ex_folder );

       var fso = XSIFactory.CreateActiveXObject("Scripting.FileSystemObject");

       var filename = XSIUtils.BuildPath(
           InstallationPath(siUserAddonPath),
           ex_folder,
           "Application",
           ex_subfolder,
           ex_name+ex_langsuffix );

       if (!fso.FileExists(filename))
       {
           var f = fso.CreateTextFile ( filename );
           f.write( ExampleSourceCode() );
           f.close();

           Application.LoadPlugin(filename);
       }

       // run demo
       ExRegisterFilterDemo();
    }

See Also

Plugin.Items | Definition Callbacks for Filters

Autodesk Softimage v7.5