Detailed Description

The Filter object represents an instance of a Softimage filter. Filters are used by Softimage interactive tools and OM objects for validating the use of a set of objects in a given context. Softimage already defines a set of native filters available to users and can be extended with custom filter objects.

Custom filters are defined with a plug-in which can be either compiled or scripted as described in cus_addons Distributing Customized Items for the detailed workflow.

Like native filters, custom filters can also be used with other base filter functions defined in the SDK such as SIFilter, X3DObjectCollection.Filter, etc.

Since:: 4.0

Example:: Demonstrates how to work with filters in Softimage

        #include <xsi_application.h>
        #include <xsi_filter.h>
        #include <xsi_model.h>

        using namespace XSI;

        // Helper functions for logging filter operations results
        static TestFilter( const CString& in_strFilter, const CRef& in_ref )
        {
            Application app;
            Filter filter = app.GetFilters().GetItem( in_strFilter );

            bool bApplicable = filter.IsApplicable(in_ref);
            bool bMatch = filter.Match(in_ref);

            app.LogMessage( L"*** Filter: " + filter.GetName() );
            app.LogMessage( L"   Target: " + SIObject(in_ref).GetName() );
            app.LogMessage( L"   Applicable: " + CValue(bApplicable).GetAsText() );
            app.LogMessage( L"   Match: " + CValue(bMatch).GetAsText() );
        }

        static TestFilter( const CString& in_strFilter, const CString& in_strTest, const CRefArray& in_array )
        {
            Application app;
            Filter filter = app.GetFilters().GetItem( in_strFilter );

            bool bApplicable = filter.IsApplicable(in_array);
            bool bMatch = filter.Match(in_array);
            CRefArray subArray = filter.Subset(in_array);

            app.LogMessage( L"*** Filter: " + filter.GetName() );
            app.LogMessage( L"   Target: " + in_strTest + L" count: " + CValue((LONG)in_array.GetCount()).GetAsText() );
            app.LogMessage( L"   Applicable: " + CValue(bApplicable).GetAsText() );
            app.LogMessage( L"   Match: " + CValue(bMatch).GetAsText() );
            app.LogMessage( L"   Subset: " + CValue(subArray.GetCount()).GetAsText() );
        }

        // Display all filters defined in Softimage
        Application app;

        CRefArray filterArray = app.GetFilters();

        for (LONG i=0; i<filterArray.GetCount(); i++)
        {
            Filter filter(filterArray[i]);
            app.LogMessage( filter.GetName() );
        }

        // Sample filter tests
        Model root = app.GetActiveSceneRoot();

        X3DObject sphere;
        root.AddGeometry( L"Sphere", L"MeshSurface", L"", sphere );

        TestFilter( L"Object", root );
        TestFilter( L"PolygonMesh", sphere );

        CRefArray array(root.GetChildren());
        CString strTest(root.GetName() + L" children");
        TestFilter( L"Object", strTest, array );
        TestFilter( L"Light", strTest, array );
        TestFilter( L"Camera", strTest, array );
        TestFilter( L"PolygonMesh", strTest, array );

        array = root.GetProperties();
        strTest = root.GetName() + L" properties";
        TestFilter( L"Object", strTest, array );
        TestFilter( L"Light", strTest, array );

#include <xsi_filter.h>

Inheritance diagram for Filter:

[legend]

List of all members.

Public Member Functions
	Filter ()
	~Filter ()
	Filter (const CRef &in_ref)
	Filter (const Filter &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Filter &	operator= (const Filter &in_obj)
Filter &	operator= (const CRef &in_ref)
bool	Match (const CRef &in_obj) const
bool	Match (const CRefArray &in_array) const
bool	IsApplicable (const CRef &in_obj) const
bool	IsApplicable (const CRefArray &in_array) const
CRefArray	Subset (const CRefArray &in_array) const

Constructor & Destructor Documentation

Filter ( )

Default constructor.

~Filter ( )

Default destructor.

Filter ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

Filter ( const Filter & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID class type.

Returns:: true if the class is compatible, false otherwise.

Reimplemented from SIObject.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:: The class type.

Reimplemented from SIObject.

Filter& operator= ( const Filter & in_obj )

Creates an object from another object. The new object is set to empty if the input object is not compatible.

Parameters:

in_obj constant class object.

Returns:: The new Filter object.

Filter& operator= ( const CRef & in_ref )

Creates an object from a reference object. The new object is set to empty if the input reference object is not compatible.

Parameters:

in_ref constant class object.

Returns:: The new Filter object.

Reimplemented from SIObject.

bool Match ( const CRef & in_obj ) const

Returns true if the input object meets the filter requirements.

Parameters:

in_obj The object to filter.

Returns:: true if it matches or false otherwise.

bool Match ( const CRefArray & in_array ) const

Returns true if each object in the array matches the filter requirements. This is similar to the other Filter::Match function.

Parameters:

in_array Array of objects to filter.

Returns:: true if all objects in the array match the filter or false otherwise.

bool IsApplicable ( const CRef & in_obj ) const

Returns true if the filter is compatible with an input object. This function is used to quickly determine whether a filter can be used on a given type of object.

Parameters:

in_obj Object to test.

Returns:: true if the input object is applicable or false otherwise.

bool IsApplicable ( const CRefArray & in_array ) const

Returns true if the filter is compatible with each object of the input array. This function is similar to the other Filter::IsApplicable function and is used to quickly determine whether a filter can be used on a given type of object.

Parameters:

in_array Array of objects to filter.

Returns:: true if all objects in the array match the filter or false otherwise.

CRefArray Subset ( const CRefArray & in_array ) const

Returns an array of objects built from the input array. All objects matching the filter requirements are returned through the output array.

Parameters:

in_array Array of objects to filter in order to build the subset.

Returns:: Array of objects that match the filter criterias.

The documentation for this class was generated from the following file:

xsi_filter.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation