SimulationEnvironment Class Reference
 
 
 
SimulationEnvironment Class Reference

#include <xsi_simulationenvironment.h>


Class Description

The SimulationEnvironment object represents a construct which is used to define a simulation. For now SimulationEnvironment objects are used only for RigidBody simulations. A simulation environment is a set of connection containers, one for each kind of element in the simulation: the rigid body objects, the rigid body constraints and the forces.

The environment keeps track of the relationships between the objects in the simulation and determines onto which objects the dynamics operator is applied. The dynamics operator solves the simulation for all elements that are in this environment. As well, a time control determines how the simulation in this environment is played back.

An environment is created as soon as you create a RigidBody object, which you can achieve by using the CreateActiveRigidBody or CreatePassiveRigidBody commands. You can also explicitly create an environment by using the CreateEnvironment command. SimulationEnvironment objects can be retrieved using Scene::GetActiveSimulationEnvironment or Scene::GetSimulationEnvironments.

See also:
Scene::GetSimulationEnvironments, Scene::GetActiveSimulationEnvironments, SetCurrentEnvironment
Since:
4.2
Example:
Illustrates how to create a cached RigidBody simulation and apply that cache to animate the simulated objects directly without using the simulation.
                using namespace XSI;

                Application app;
                Model root = app.GetActiveSceneRoot();
                X3DObject myCone;
                root.AddGeometry( L"Cone", L"MeshSurface",L"myCone",myCone);

                Model myModel;
                root.AddModel(CRefArray(),L"myModel",myModel);

                X3DObject myGrid;
                myModel.AddGeometry( L"Grid", L"MeshSurface",L"myGrid",myGrid);

                // Move the cone
                myCone.PutParameterValue(L"posy",6.0);

                // Modify the grid
                myGrid.PutParameterValue(L"ulength",24l);
                myGrid.PutParameterValue(L"vlength",24l);
                myGrid.PutParameterValue(L"subdivu",24l);
                myGrid.PutParameterValue(L"subdivv",24l);

                // The following line creates the environment.
                CValueArray args(1);
                CValue outArg;
                args[0] = myGrid.GetRef();
                app.ExecuteCommand(L"CreatePassiveRigidBody",args,outArg);

                args[0] = myCone.GetRef();
                app.ExecuteCommand(L"CreateActiveRigidBody",args,outArg);

                args[0] = L"Gravity";
                app.ExecuteCommand(L"CreateForce",args,outArg);

                SimulationEnvironment currEnv = app.GetActiveProject().GetActiveScene().GetActiveSimulationEnvironment();
                Property simTimeControl = currEnv.GetSimulationTimeControl();

                // Turn the caching on.
                simTimeControl.PutParameterValue(L"caching",true);
                simTimeControl.PutParameterValue(L"playmode",0l);//Standard play mode.

                // Simulate
                // To make sure that all frames gets simulated
                args.Resize(0);
                for(LONG i =0 ; i < 100 ; i++)
                {
                        app.ExecuteCommand(L"NextFrame",args,outArg);
                        app.ExecuteCommand(L"Refresh",args,outArg);
                        app.LogMessage(L"Frame : " + CValue(i).GetAsText());
                }

                // Get models of the scene
                CRefArray refModels;
                refModels.Add(root);
                refModels.Add(myModel);

                ApplyCurrentEnvironmentCacheToSimulateObjectForModels(refModels);

                // The FCurve animated objects
                app.ExecuteCommand(L"PlayForwardsFromStart",args,outArg);

                // This function takes the cached simulation and copies it directly
                // on the driven objects as FCurve. It also turns off the simulation
                // so that we could
                void ApplyCurrentEnvironmentCacheToSimulateObjectForModels(CRefArray& in_models)
                {
                        Application app;

                        SimulationEnvironment currEnv = app.GetActiveProject().GetActiveScene().GetActiveSimulationEnvironment();

                        // Deactivate the simulation so that objects are driven by their
                        // animation.
                        Property simTimeControl= currEnv.GetSimulationTimeControl();
                        simTimeControl.PutParameterValue(L"Active",false);

                        for (LONG i = 0; i < in_models.GetCount();++i)
                        {
                                Model currModel = in_models[i];
                                ActionSource currCache = currEnv.FindCacheForModel(currModel);
                                CRefArray sourceItems = currCache.GetItems();

                                for(LONG j = 0; j < sourceItems.GetCount(); ++j)
                                {
                                        AnimationSourceItem currSourceItem = sourceItems[j];
                                        CString strTarget = currSourceItem.GetTarget();
                                        if(!currModel.IsEqualTo(app.GetActiveSceneRoot()))
                                        {
                                                // ActionSource keeps the relative name of an
                                                // animated parameter. We need to prepend the
                                                // model name if the model owner is not the scene
                                                // root in order to fetch the parameter.
                                                strTarget = currModel.GetName() + L"." + strTarget;
                                        }

                                        CRef tmpRef;
                                        tmpRef.Set(strTarget);

                                        Parameter targetParam(tmpRef);

                                        // The RigidBody simulation caches linear acceleration which
                                        // is not animatable. We won't be copying those values on
                                        // the global transform.
                                        if (targetParam.GetCapabilities() & siAnimatable)
                                        {
                                                FCurve cacheFCurve = currSourceItem.GetSource();
                                                CopyFCurveOnParameter(cacheFCurve, targetParam);
                                        }
                                }
                        }
                }

                // This function creates a copy of an FCurve on a parameter by
                // creating a new FCurve on the parameter and adding all keys.
                void CopyFCurveOnParameter(FCurve& in_FCurve,Parameter& in_Parameter)
                {
                        FCurve newFCurve;
                        in_Parameter.AddFCurve(siStandardFCurve,newFCurve);
                        CRefArray fcKeys = in_FCurve.GetKeys();

                        in_FCurve.BeginEdit();

                        for(LONG i = 0;i < fcKeys.GetCount();++i)
                        {
                                FCurveKey currKey(fcKeys[i]);
                                newFCurve.AddKey(currKey.GetTime(),currKey.GetValue());
                        }
                        in_FCurve.EndEdit();
                }
Inheritance diagram for SimulationEnvironment:
ProjectItem SIObject CBase

List of all members.

Public Member Functions

  SimulationEnvironment ()
  ~SimulationEnvironment ()
  SimulationEnvironment (const CRef &in_ref)
  SimulationEnvironment (const SimulationEnvironment &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
SimulationEnvironment operator= (const SimulationEnvironment &in_obj)
SimulationEnvironment operator= (const CRef &in_ref)
CRefArray  GetContainers () const
CRefArray  GetCaches () const
CRefArray  GetOperators () const
Property  GetSimulationTimeControl () const
ActionSource  FindCacheForModel (Model &in_model) const
CRefArray  GetAllRigidBodyObjects () const
LONG  GetAllRigidBodyObjectsCount () const
CRefArray  GetPatriarchRigidBodyObjects () const
LONG  GetPatriarchRigidBodyObjectsCount () const
CRefArray  GetRigidConstraintObjects () const
LONG  GetRigidConstraintObjectsCount () const
CRefArray  GetForces () const
LONG  GetForcesCount () const

Constructor & Destructor Documentation

Default constructor.

Default destructor.

SimulationEnvironment ( const CRef in_ref )

Constructor.

Parameters:
in_ref constant reference object.

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

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Reimplemented from ProjectItem.

SimulationEnvironment& operator= ( const SimulationEnvironment 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:
The new SimulationEnvironment object.
SimulationEnvironment& 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:
The new SimulationEnvironment object.

Reimplemented from ProjectItem.

CRefArray GetContainers ( ) const

Returns all containers

Since:
4.2
CRefArray GetCaches ( ) const

Returns an array of ActionSource objects which are used for the caching of the simulation (see Environments > Environment > Caches under the Scene). There is one cache for each model containing a simulation environment.

As soon as you add an object to the simulation environment a cache for the model of the object will be created. The cache will only be populated if the simulation time control caching parameter is set to true and there is a frame change.

See also:
SimulationEnvironment::FindCacheForModel
Since:
4.2
CRefArray GetOperators ( ) const

Returns all simulation operators used by this environment.

Since:
4.2
Property GetSimulationTimeControl ( ) const

Returns the simulation time control of this environment.

Since:
4.2
ActionSource FindCacheForModel ( Model in_model ) const

Returns the ActionSource which is used for caching the simulation of a given model. If there is no cache the function returns an invalid ActionSource object. You can verify the validity of an object using CBase::IsValid.

Caches are stored in the Environments > Environment > Caches folder under the Scene.

Parameters:
in_model the Model for which we want to retrieve the cache.
Since:
4.2
CRefArray GetAllRigidBodyObjects ( ) const

Returns all rigid body objects in this environment. Compound rigid bodies may consist of more than one rigid body object (for example, a cube parented under a sphere), and thus the number of rigid body objects is not the same as the number of independent rigid bodies.

Returns:
An array of references to X3DObject objects.
See also:
SimulationEnvironment::GetPatriarchRigidBodyObjects
SimulationEnvironment::GetRigidConstraintObjects
SimulationEnvironment::GetForces
Since:
6.0
LONG GetAllRigidBodyObjectsCount ( ) const

Returns the number of rigid body objects in this environment as a LONG.

Since:
6.0
CRefArray GetPatriarchRigidBodyObjects ( ) const

Returns all rigid body patriarchs in this environment. A "patriarch" is the top-most rigid body object in a rigid body. The simplest rigid bodies consist of a single X3DObject with rigid body properties; for example, a single sphere with the "bounding sphere" collision type. In that case, the patriarch is merely the one rigid body object.

A compound rigid body, however, is made up of one or more rigid body objects parented under an active rigid body. This top-most rigid body object is the patriarch, and controls such aspects of the rigid body as its center of mass and whether the entire compound rigid body is active or passive.

Returns:
An array of references to X3DObject objects.
See also:
SimulationEnvironment::GetAllRigidBodyObjects
SimulationEnvironment::GetRigidConstraintObjects
SimulationEnvironment::GetForces
Since:
6.0
LONG GetPatriarchRigidBodyObjectsCount ( ) const

Returns the number of rigid body patriarchs in this environment as a LONG. The number of patriarchs is the number of independent rigid bodies being simulated.

See also:
SimulationEnvironment::GetPatriarchRigidBodyObjects
Since:
6.0
CRefArray GetRigidConstraintObjects ( ) const

Returns all rigid body constraints in this environment.

Returns:
An array of references to X3DObject objects.
Since:
6.0
LONG GetRigidConstraintObjectsCount ( ) const

Returns the number of rigid body constraints in this environment as a LONG

See also:
SimulationEnvironment::GetRigidConstraintObjects
Since:
6.0
CRefArray GetForces ( ) const

Returns all forces in this environment.

Returns:
An array of references to X3DObject objects.
Since:
6.0
LONG GetForcesCount ( ) const

Returns the number of forces in this environment as a LONG.

See also:
SimulationEnvironment::GetForces
Since:
6.0

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