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:

[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
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

SimulationEnvironment ( )

Default constructor.

~SimulationEnvironment ( )

Default destructor.

SimulationEnvironment ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

SimulationEnvironment ( const SimulationEnvironment & 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:: 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.