Public Member Functions
SimulationEnvironment Class Reference

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

#include <xsi_simulationenvironment.h>

Inheritance diagram for SimulationEnvironment:
Inheritance graph
[legend]

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
SimulationEnvironmentoperator= (const SimulationEnvironment &in_obj)
SimulationEnvironmentoperator= (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_refconstant reference object.

Copy constructor.

Parameters:
in_objconstant 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_ClassIDclass 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_objconstant 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_refconstant 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_modelthe 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: