CRef Class Reference

---

Detailed 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() );
        }

#include <xsi_ref.h>

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:

• xsi_ref.h