# Filter Class Reference

Related Scripting Object: Filter

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. More...

`#include <xsi_filter.h>`

Inheritance diagram for Filter:

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

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

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