CRef Class Reference
 
 
 
CRef Class Reference

This reference page is linked to from the following overview topics: Softimage 2014, Components of a Custom Display Host, Common Build Problems.


#include <xsi_ref.h>


Class Description

This class is used to reference Softimage objects. Each instance of an CRef maintains a link with only one single object at a time, it cannot refer to multiple objects. CRef has no base or derived class hierarchy and only contains methods for accessing the type of the underlying Softimage object.

CRef provides the core of the RTTI system to determine if an object is of a specific type; for example, to ensure that the compatibility between the reference and a given API class is valid by checking it against the siClassID enum. CRef instances are typically attached to API classes for manipulating Softimage objects.

A CRef object can be converted to its corresponding Softimage Object Model interface, and the resulting object can be used with the Softimage object model. The inverse is also possible: you can create a CRef object from an existing Softimage object model interface. See the XSI::ConvertObject function for more details.

See also:
CRefArray, CBase
Example:
Demonstrates how to use the work with CRefs
                using namespace XSI;

                // Forward declaration
                void GetSomeObjects( CRefArray& io_array, const Application& in_app );


                Application app;

                CRefArray array;
                GetSomeObjects( array, app );

                // Find all X3DObjects in the scene and add them to the ref array
                CStringArray emptyArray;
                Model root( app.GetActiveSceneRoot() );

                array += root.FindChildren( L"", L"", emptyArray, true );

                // Add grid's parameters to ref array
                X3DObject grid;
                root.AddGeometry( L"Grid", L"MeshSurface", L"", grid );

                array += grid.GetParameters();

                for (LONG i=0; i<array.GetCount(); ++i )
                {
                        app.LogMessage(L"");

                        CRef ref(array[i]);
                        app.LogMessage( CString(L">>Reference object class type: ") + ref.GetClassIDName() );

                        if ( ref.IsA( siSIObjectID ) )
                        {
                                SIObject siobj(ref);
                                app.LogMessage( CString(L"\tObject name: ") + siobj.GetName() );
                        }

                        if ( ref.IsA( siX3DObjectID ) )
                        {
                                X3DObject xobj(ref);
                                app.LogMessage( CString(L"\tNumber of children : ") +
                                                                CValue(xobj.GetChildren().GetCount()).GetAsText() );
                        }

                        if ( ref.IsA( siParameterID ) )
                        {
                                Parameter param(ref);
                                app.LogMessage( CString(L"\tParameter's value : ") +
                                                                param.GetValue().GetAsText() );
                        }
                }


                // Fills an array with CRef objects
                void GetSomeObjects( CRefArray& io_array, const Application& in_app )
                {
                        X3DObject myCube;
                        X3DObject myCone;
                        Material myPhong;

                        Model root = in_app.GetActiveSceneRoot();

                        root.AddGeometry( L"Cube", L"MeshSurface", L"", myCube );
                        root.AddGeometry( L"Cone", L"MeshSurface", L"", myCone );
                        myCone.AddMaterial(     L"Phong", false, L"", myPhong );

                        // Add CRef items to the input array
                        io_array.Add( myCube.GetActivePrimitive().GetRef() );
                        io_array.Add( myCone.GetActivePrimitive().GetRef() );
                        io_array.Add( myPhong.GetRef() );
                }

List of all members.

Public Member Functions

  CRef ()
  CRef (const CRef &in_xsiRef)
  ~CRef ()
siClassID  GetClassID () const
bool  IsA (siClassID in_classID) const
CString  GetClassIDName () const
bool  IsValid () const
  operator bool () const
bool  operator== (const CRef &in_ref) const
bool  operator!= (const CRef &in_ref) const
CRef operator= (const CRef &in_ref)
CStatus  Set (const CString &in_str)
CString  GetAsText () const
bool  operator< (const CRef &in_ref) const
bool  operator> (const CRef &in_ref) const

Constructor & Destructor Documentation

CRef ( )

Default constructor.

CRef ( const CRef in_xsiRef )

Construct a CRef object from another CRef object.

Parameters:
in_xsiRef constant reference object.
~CRef ( )

Destructor.


Member Function Documentation

siClassID GetClassID ( ) const

Returns the type of the object being referenced.

Returns:
The class type.
bool IsA ( siClassID  in_classID ) const

Returns true if a given class type is compatible with the underlying reference object.

Parameters:
in_classID Class type (the siClassID enum).
Returns:
true if the class is compatible, false otherwise.
CString GetClassIDName ( ) const

Returns the type of the referenced object in text format.

Returns:
The text string.
bool IsValid ( ) const

Returns true if the referenced object is valid or false otherwise.

Returns:
true if valid, false otherwise.
operator bool ( ) const

Bool converter operator that returns true if the object is valid or false otherwise.

Returns:
true if object is valid; false if not valid.
Since:
4.0
bool operator== ( const CRef in_ref ) const

Equality operator

Parameters:
in_ref Reference object to compare.
Returns:
true if both CRef objects are identical, false otherwise.
bool operator!= ( const CRef in_ref ) const

Inequality operator

Parameters:
in_ref Reference object to compare.
Returns:
true if objects are not identical, false otherwise.
CRef& operator= ( const CRef in_ref )

Assigns a CRef object to this one.

Parameters:
in_ref A source Reference object
Returns:
A new reference object.
CStatus Set ( const CString in_str )

Sets CRef from an object's string path. Returns CStatus::Fail if the object's path is invalid.

Tip:
This is the C++ API equivalent of Dictionary.GetObject
Parameters:
in_str String path to object for example, "Model.null.kine.local.posx"
Returns:
CStatus::OK success
CStatus::InvalidArgument string is empty or contains invalid object path.
CStatus::Fail failure
CString GetAsText ( ) const

Returns the object's path as a string.

Returns:
The object's path.
bool operator< ( const CRef in_ref ) const

Less-than operator. Performs a case-sensitive comparison with a specified CRef object to determine if this CRef is lexicographically less than the specified CRef. The comparison is done with CRef::GetAsText. This is useful for sorting operations with stl maps.

Parameters:
in_ref CRef we want to test.
Returns:
true if this CRef is less than the specified CRef, false otherwise.
Since:
7.5
bool operator> ( const CRef in_ref ) const

Greater-than operator. Performs a case-sensitive comparison with a specified CRef object to determine if this CRef is lexicographically greater than the specified CRef. The comparison is done with CRef::GetAsText.

Parameters:
in_ref CRef we want to test.
Returns:
true if this CRef is greater than the specified CRef, false otherwise.
Since:
7.5

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