Public Member Functions
Model Class Reference

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: CreateModel, SICreateModel, etc.

You can also import or export models (including referenced models) with a series of commands: ImportModel, ExportModel, 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() );

#include <xsi_model.h>

Inheritance diagram for Model:
Inheritance graph
[legend]

List of all members.

Public Member Functions

  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

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

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
siClassID the class type.

Reimplemented from 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 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: