XSI::Model Class Reference

The Model object represents any Softimage model node, including referenced models, and even the Scene Root. Softimage models act as a container for objects (usually hierarchies of objects) and many of their properties. Models are a type of X3DObject and as such can be positioned in space. A model can contain objects, Groups, or other models. More...

#include <xsi_model.h>

Inheritance diagram for XSI::Model::

XSI::X3DObject XSI::SceneItem XSI::ProjectItem XSI::SIObject XSI::CBase List of all members.

Public Methods

 Model ()
 ~Model ()
 Model (const CRef &in_ref)
 Model (const Model &in_obj)
bool IsA (siClassID in_ClassID) const
siClassID GetClassID () const
Model & operator= (const Model &in_obj)
Model & operator= (const CRef &in_ref)
CRefArray GetGroups () const
CRefArray GetSources () const
CStatus AddGroup (const CRefArray &in_members, const CString &in_name, bool in_branch, Group &io_group)
Mixer GetMixer () const
bool HasMixer () const
ActionSource AddActionSource (const CString &in_name=CString())
Mixer AddMixer ()
CRefArray GetExternalFiles () const
XSI::siModelKind GetModelKind () const
Model GetInstanceMaster () const
CSIObjectRefArray FindObjects (const XSI::siClassID &in_nClsID) const
CSIObjectRefArray FindObjects (const CString &in_sCLSID) const

Detailed Description

The Model object represents any Softimage model node, including referenced models, and even the Scene Root. Softimage models act as a container for objects (usually hierarchies of objects) and many of their properties. Models are a type of X3DObject and as such can be positioned in space. A model can contain objects, Groups, or other models.

The Scene Root can be accessed using Application::GetActiveSceneRoot. In addition, any ProjectItem or Parameter can return a reference to the model in which it lives via the ProjectItem::GetModel and Parameter::GetModel functions.

You can also get list of all models under a given model by using X3DObject::GetModels (a Model is a specialized kind of X3DObject). Therefore, if you use GetModels on the Scene Root recursively, it returns all models in the active scene.

To create a new model, use X3DObject::AddModel, which also returns a Model object. There are also a few scripting commands which create model nodes as well: @xlink@ CreateModel, @xlink@ SICreateModel, etc.

You can also import or export models (including referenced models) with a series of commands: @xlink@ ImportModel, @xlink@ ExportModel, @xlink@ ImportRefModels, etc. When a referenced model is instantiated in the scene, changes to that model are tracked by the Delta system as of v6.0.

See also:
Group
Example:
Demonstrates how to work with groups in a model
        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        Null myNull;
        root.AddNull( L"MyNull", myNull );

        CRefArray groupMembersRef;
        groupMembersRef.Add(myNull);

        Group myGroup;
        root.AddGroup(groupMembersRef, L"MyGroup",false, myGroup);

        app.LogMessage( CString(L"The group: ") + myGroup.GetFullName() );


Constructor & Destructor Documentation

Model  
 

Default constructor.

~Model  
 

Default destructor.

Model const CRef   in_ref
 

Constructor.

Parameters:
in_ref  constant reference object.

Model const Model &    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:
bool true if the class is compatible, false otherwise.

Reimplemented from XSI::X3DObject.

siClassID GetClassID   const [virtual]
 

Returns the type of the API class.

Returns:
siClassID the class type.

Reimplemented from XSI::X3DObject.

Model& operator= const Model &    in_obj
 

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

Parameters:
in_obj  constant class object.
Returns:
Model& New Model object.

Model& operator= const CRef   in_ref
 

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

Parameters:
in_ref  constant class object.
Returns:
Model& New Model object.

Reimplemented from XSI::X3DObject.

CRefArray GetGroups   const
 

Returns an array of references to all Group objects in the model.

Returns:
CRefArray array of references to Group objects in the model.

CRefArray GetSources   const
 

Returns an array of references to all Source objects in the model. Currently, the only sources available to the model are of type ActionSource, which is a specialized kind of Source object.

Audio and Image sources (which are basically references to audio and image files) are all stored under the Scene container (see Scene::GetExternalFiles).

Note:
Prior to v6.0, Model sources were also available using this property as a way to manage changes to reference models; however, this functionality is now provided by the Delta system.
Returns:
CRefArray array of references to data source objects in the model.
Example:
Demonstrates how to find all sources in the scene by using the Model.Sources property on every model returned from the X3DObject.Models property, given this structure:
           Scene_Root (Model)
               |- Herb (Model)
               |    |- Mixer (animation clip on null.posx)
               |    |- null  (null.size = FCurve)
               |
               |- Jesse (Model)
               |    |- Mixer (animation clips on null.scly,null.sclz,null.rotz)
               |    |- null
               |
               |- Sally (Model)
                    |- Mixer (audio clip)
                    |- grid (image on its texture projection)

        using namespace XSI;

        // Forward declarations
        CString GetRelativePath( Parameter& in_param );
        void MakeNewFCrvSource( Null& in_null );
        CRefArray FindSourcesUnderModel( Model& in_model );

        Application app;

        // NewScene command
        CValueArray cargs; CValue oarg;
        cargs.Add( L"" ); cargs.Add( false );
        app.ExecuteCommand( L"NewScene", cargs, oarg );
        cargs.Clear(); oarg.Clear();

        // Get the SceneRoot
        Model root = app.GetActiveSceneRoot();

        // Create a new model and add a null
        Model m; root.AddModel( CRefArray(), L"MyModel", m );
        Null n; m.AddNull( L"MyNull", n );

        // Add an fcurve ActionSource based on the new null
        MakeNewFCrvSource( n );

        // Find sources under the SceneRoot
        FindSourcesUnderModel( root );

        // Look under any other models
        CRefArray mdls = root.GetModels();
        for ( LONG i=0; i<mdls.GetCount(); ++i ) {
            Model m( mdls[i] );
            FindSourcesUnderModel( m );
        }


        // Expected results:
        //INFO : No sources found on Scene_Root
        //INFO : Sources.MyModel.StoredFcvAction is a ActionSource


        CRefArray FindSourcesUnderModel( Model& in_model )
        {
            Application app;
            CRefArray foundsrcs = in_model.GetSources();

           // Loop through the collection of sources found under this model to print the
           // name and add its name to the result string
           if ( foundsrcs.GetCount() > LONG(0) ) {
               for ( LONG i=0; i<foundsrcs.GetCount(); ++i ) {
                  Source src( foundsrcs[i] );
                  app.LogMessage( src.GetFullName() + L" is a " + src.GetClassIDName() );
               }
           } else {
               app.LogMessage( L"No sources found on " + in_model.GetFullName() );
           }

           return foundsrcs;
        }


        // Function to remove the name of the model from the FullName of the specified parameter.
        // This is necessary when setting up a source that will later be used to instantiate a
        // clip when the parameter lives under a model other than the Scene_Root.
        CString GetRelativePath( Parameter& in_param )
        {
            Model mdl = in_param.GetModel();
            CString mdlname = mdl.GetFullName();
            if ( mdlname.IsEqualNoCase(L"Scene_Root") ) {
                return in_param.GetFullName();
            } else {
                CString tmp = in_param.GetFullName();
                CString lookfor = mdlname + L".";
                CString foundsofar = L"";
                CString relpath = L"";
                for ( ULONG i=0; i<tmp.Length(); ++i ) {
                    if ( foundsofar.IsEqualNoCase(lookfor) ) {
                        relpath += tmp[i];
                    } else {
                        foundsofar += tmp[i];
                    }
                }
                return relpath;
            }
        }

        // Create a simple (fcurve) actionsource based on a null's position
        void MakeNewFCrvSource( Null& in_null )
        {
            Application app;
            Model mdl = in_null.GetModel();

            CTimeArray time; time.Add( CTime(1.000) ); time.Add( CTime(50.000) ); time.Add( CTime(100.000) );
            CValueArray vals;

            // X
            Parameter posx = in_null.GetParameter( L"posx" ); CString rposx = GetRelativePath(posx);
            FCurve fcx; posx.AddFCurve( siStandardFCurve, fcx );
            vals.Add( CValue(-8.153) ); vals.Add( CValue(0.197) ); vals.Add( CValue(9.413) );
            fcx.SetKeys( time, vals ); vals.Clear();

            // Y
            Parameter posy = in_null.GetParameter( L"posy" ); CString rposy = GetRelativePath(posy);
            FCurve fcy; posy.AddFCurve( siStandardFCurve, fcy );
            vals.Add( CValue(7.015) ); vals.Add( CValue(-1.92) ); vals.Add( CValue(7.015) );
            fcy.SetKeys( time, vals ); vals.Clear();

            // Z
            Parameter posz = in_null.GetParameter( L"posz" ); CString rposz = GetRelativePath(posz);
            FCurve fcz; posz.AddFCurve( siStandardFCurve, fcz );
            vals.Add( CValue(-0.702) ); vals.Add( CValue(0.192) ); vals.Add( CValue(-0.702) );
            fcz.SetKeys( time, vals );

            // Build an action with the fcurves as source items
            ActionSource src = mdl.AddActionSource( L"StoredFcvAction" );
            src.AddSourceItem( rposx, fcx, true );
            src.AddSourceItem( rposy, fcy, true );
            src.AddSourceItem( rposz, fcz, true );
        }

CStatus AddGroup const CRefArray   in_members,
const CString   in_name,
bool    in_branch,
Group   io_group
 

Creates a group in the model and adds objects to the group.

Parameters:
in_members  array of reference to members to add to the group.
in_name  name of the group.
in_branch  Add new members as branch members
io_group  Group that was added.
Returns:
CStatus::OK success CStatus::Fail failure

Mixer GetMixer   const
 

Returns the active Mixer if there is one. If not, this method returns an invalid Mixer object. You can check its validity by using the CBase::IsValid method.

Returns:
Mixer
Since:
4.0

bool HasMixer   const
 

Returns true if there is a mixer nested directly under the model, false otherwise.

Returns:
bool true if there's an active Mixer for this Model.
Since:
4.0

ActionSource AddActionSource const CString   in_name = CString()
 

Adds an empty action source. In order to fill the ActionSource you must use ActionSource::AddSourceItem.

Parameters:
in_name  Name of the new action source
Returns:
ActionSource the newly created ActionSource object
See also:
ActionSource::AddSourceItem, AnimationSourceItem, AnimationSourceItem::SetAsStatic
Since:
4.0
Example:
See the AnimationSourceItem page for an example of how to create an empty ActionSource, populate it and then change the source.

Mixer AddMixer  
 

Adds an empty Mixer object. If the current model does not have a mixer, this function fails and returns an invalid Mixer object.

Returns:
Mixer the newly created Mixer object
Since:
4.0

CRefArray GetExternalFiles   const
 

Returns the external file list for the model.

Returns:
Array of FileReference objects.
Since:
5.0

XSI::siModelKind GetModelKind   const
 

Returns the type of model. The type can be one of regular, referenced, or instance.

Returns:
The siModelKind type of model.
Since:
6.0

Model GetInstanceMaster   const
 

Returns the master model of this model, if this model is an instance. To check whether this model is an instance model, use Model::GetModelKind to query for the type.

Returns:
The master Model of this instance model (if applicable).
See also:
siModelKind
Since:
7.0

CSIObjectRefArray FindObjects const XSI::siClassID   in_nClsID const
 

Returns all objects found in this model that match a class identifier. These identifiers are documented but can also be discovered by inspecting Softimage objects with the SDK Explorer. The supported class identifierss are the following:

Parameters:
in_nClassID  An object class id as defined in XSI::siClassID.
Returns:
CSIObjectRefArray Array of objects.
See also:
Application::FindObjects
Since:
9.5 (2011)
Example:
        using namespace XSI;
        Application app;

        // Returns all 3d objects in the scene as X3DObjects objects
        Application app;
        CSIObjectRefArray objArray = app.GetActiveSceneRoot().FindObjects( siX3DObjectID );
        for ( LONG i=0; i<objArray.GetCount(); i++ )
        {
            app.LogMessage( "X3DObject: " + objArray[i].GetFullName() );
        }

        // Returns all lights found in model 'A' as Light 3D objects.
        Model modelA = app.GetActiveSceneRoot().GetModels().GetItem( "A" );
        objArray = modelA.FindObjects( siLightID );
        for ( LONG i=0; i<objArray.GetCount(); i++ )
        {
            app.LogMessage( "Lights: " + objArray[i].GetFullName() );
        }

CSIObjectRefArray FindObjects const CString   in_sCLSID const
 

Returns all objects found in this model that match a Softimage object CLSID. Object CLSID are not documented but can be discovered with XSIUtils.DataRepository or by inspecting Softimage objects with the SDK Explorer.

Parameters:
in_sCLSID  An object CLSID.
Returns:
CSIObjectRefArray Array of objects.
See also:
Application::FindObjects
Since:
9.5 (2011)
Example:
        using namespace XSI;
        Application app;
        
        // Find all lights in model 'A'
        Model modelA = app.GetActiveSceneRoot().GetModels().GetItem( "A" );
        CSIObjectRefArray lights = modelA.FindObjects( "{F3705C30-5204-11D0-8298-00A0243E366B}" );

        for ( LONG i=0; i< lights.GetCount(); i++ )
        {
            app.LogMessage( "Light: " + lights[i].GetFullName() );
        }


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