The physics simulator class. More...

#include <VR3PhysicsSimulator.h>

Collaboration diagram for VR3PhysicsSimulator:

Classes
struct	MapElement
	An element in the hash registered object map. More...
Public Member Functions
Constructor and Destructor
	VR3PhysicsSimulator (int mode=VR3PHYSIM_AUTOMATIC, int solveriter=VR3PHYSIM_DEF_ITERNUM, float timestep=VR3PHYSIM_DEF_TIMESTEP, int maxsteps=VR3PHYSIM_DEF_MAXSTEPS)
	Physics simulator constructor.
	~VR3PhysicsSimulator ()
	Physics simulator destructor.
Scene Parameters Management
void	SetGravity (NxReal gx, NxReal gy, NxReal gz)
	Sets the new gravity vector (default is (0.0,-9.81,0.0))
Movement Constraint Management Functions
A joint is a movement constraint that exists between two objects, some different types of joints are supported by the VR3Lib engine that removes different degrees of freedom. Joints may be added or removed during simulation, all of them will be deleted when the simulation ends. A joint can only be added once the simulation has been prepared, the user may store an ID of the joint (returned by the adding function) in order to delete the joint afterwards. A joint ID will only be valid until the simulation is ended. Please note that joint may only be added between dynamic or kinematic objects. Static objects cannot be jointed with other objects. Some of the functions below take a single object input, in this situation we have that the provided object is jointed with the world (an implict static object, that is, its anchor is pinned to a global position).
int	AddFixedJoint (const VR3Obj o1, const VR3Obj o2)
	Adds a fixed joint.
int	AddFixedJoint (const VR3Obj *o)
	Adds a fixed joint.
int	AddDistanceJoint (const VR3Obj o1, const VR3Obj o2, NxReal mindist, NxReal maxdist, bool collide)
	Adds a distance joint.
int	AddDistanceJoint (const VR3Obj *o, NxReal pointX, NxReal pointY, NxReal pointZ, NxReal mindist, NxReal maxdist)
	Adds a distance joint.
int	AddRevoluteJoint (const VR3Obj o1, const VR3Obj o2, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal axisX, NxReal axisY, NxReal axisZ, bool collide)
	Adds a revolute joint.
int	AddRevoluteJoint (const VR3Obj *o, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal axisX, NxReal axisY, NxReal axisZ)
	Adds a revolute joint.
int	AddSphericalJoint (const VR3Obj o1, const VR3Obj o2, NxReal anchorX, NxReal anchorY, NxReal anchorZ, bool collide)
	Adds a spherical joint.
int	AddSphericalJoint (const VR3Obj *o, NxReal anchorX, NxReal anchorY, NxReal anchorZ)
	Adds a spherical joint.
int	AddPrismaticJoint (const VR3Obj o1, const VR3Obj o2, NxReal axisX, NxReal axisY, NxReal axisZ, bool collide)
	Adds a prismatic joint.
int	AddPrismaticJoint (const VR3Obj *o, NxReal axisX, NxReal axisY, NxReal axisZ)
	Adds a prismatic joint.
int	AddCylindricalJoint (const VR3Obj o1, const VR3Obj o2, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal axisX, NxReal axisY, NxReal axisZ, bool collide)
	Adds a cylindrical joint.
int	AddCylindricalJoint (const VR3Obj *o, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal axisX, NxReal axisY, NxReal axisZ)
	Adds a cylindrical joint.
int	AddPulleyJoint (const VR3Obj o1, const VR3Obj o2, NxReal p1X, NxReal p1Y, NxReal p1Z, NxReal p2X, NxReal p2Y, NxReal p2Z, NxReal stiffness, NxReal ratio, bool collide)
	Adds a pulley joint.
int	AddPointInPlaneJoint (const VR3Obj o1, const VR3Obj o2, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal normX, NxReal normY, NxReal normZ, bool collide)
	Adds a point in a plane joint.
int	AddPointInPlaneJoint (const VR3Obj *o, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal normX, NxReal normY, NxReal normZ)
	Adds a point in a plane joint.
int	AddPointOnLineJoint (const VR3Obj o1, const VR3Obj o2, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal lineX, NxReal lineY, NxReal lineZ, bool collide)
	Adds a point on line joint.
int	AddPointOnLineJoint (const VR3Obj *o, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal lineX, NxReal lineY, NxReal lineZ)
	Adds a point on line joint.
int	AddGenericJoint (const VR3Obj o1, const VR3Obj o2, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal xaxisX, NxReal xaxisY, NxReal xaxisZ, NxReal yaxisX, NxReal yaxisY, NxReal yaxisZ, bool xtrans, bool ytrans, bool ztrans, bool xrot, bool yrot, bool zrot, bool collide)
	Adds a generic joint.
int	AddGenericJoint (const VR3Obj *o, NxReal anchorX, NxReal anchorY, NxReal anchorZ, NxReal xaxisX, NxReal xaxisY, NxReal xaxisZ, NxReal yaxisX, NxReal yaxisY, NxReal yaxisZ, bool xtrans, bool ytrans, bool ztrans, bool xrot, bool yrot, bool zrot)
	Adds a generic joint.
void	DeleteJoint (int jointID)
	Deletes a joint that is being simulated.
Force and Torque Application Functions
Apart from the implicit gravity force and the joints-related forces, the user may add forces and torques to the objects, forces may be applied at the center of mass or at a different specified point to the object (therefore inducing a torque). By default, forces are assumed to be in newtons and torques are assumed to be in newton meters. If the user considers distances in physical mesh files not misured in meters or mass not measured in kilograms, these derived units will change accordingly and the user will have to provide corrected numerical values. By default a force or a torque will be only applied for a single simulation cycle (the following one with respect to this call): if the user desires a constant force to be applied to an object, she will have to apply the force at each simulation cycle, just after finishing the object drawing. This is done because usually the forces and torques applied by the user will change depending on the situation. These function may also be used to apply a linear velocity or angular velocity independently from the mass (constant velocity or angular velocity). These functions may be called only after the simulation has been successfully prepared.
void	ObjAddForce (const VR3Obj *obj, NxReal dx, NxReal dy, NxReal dz, NxReal mag)
	Adds the specified force at the center of mass.
void	ObjAddForce (const VR3Obj *obj, NxReal px, NxReal py, NxReal pz, NxReal dx, NxReal dy, NxReal dz, NxReal mag)
	Adds the specified force at a given global point.
void	ObjAddTorque (const VR3Obj *obj, NxReal dx, NxReal dy, NxReal dz, NxReal mag)
	Adds a torque.
Position and Orientation
Simulated objects may be explicitly moved or rotated using these functions, this is useful for kinematic and dynamic objects while not allowed at all for static objects. Please note that calling these function on a kinematic actor is the preferred and only way to make it moving. Calling these functions on dynamic actor is instead discouraged because dynamic objects should not be moved by the user but just simulated in PhysX and therefore this type of movement will not take collisions into account (this does not happen for kinematic objects). These functions may be called only after the simulation has been successfully prepared. Using PhysX the parameters used to update kinematic objects position may be set just once for each simulation cycle. Writing more than once to those location will result in target position and orientation overwriting. Therefore, there is no native support to rotation and translation operation combination. We have to store all the desired transformations in a single location as a full transformation matrix and then pass it to PhysX in a single step before the begin of the next simulation cycle. The user will have to encapsulate all movement operations in a ObjBeginMove()...ObjEndMove() block, when the end of the block is reached, all trasnformations will be pushed to PhysX. A ObjBeginMove()...ObjEndMove() block is relative to a specific object; nevertheless, it is possible to open only a single block at a time and before another block can be opened the previous one must be closed (an error will be notified to the user otherways). All obj movement functions called inside the ObjBeginMove()...ObjBeginEnd() block refer to the object activated in the ObjBeginMove() call. When combining multiple movement operations, the order in which they will be applied is the order in which the functions are called.
void	ObjBeginMove (const VR3Obj *obj)
	Begin a movement operation block.
void	ObjTranslate (NxReal x, NxReal y, NxReal z)
	Translates the object with the given vector.
void	ObjRotate (NxReal ax, NxReal ay, NxReal az)
	Rotates the object around its center.
void	ObjRotate (NxReal cx, NxReal cy, NxReal cz, NxReal ax, NxReal ay, NxReal az)
	Rotates the object around a given point.
void	ObjRestore ()
	Resets the object position and orientation.
void	ObjEndMove ()
	Begin a movement operation block.
Simulation Parameter Setting
void	ObjSetMass (const VR3Obj *obj, NxReal mass)
	Sets the mass of the given object.
void	ObjSetLinearVelocity (const VR3Obj *obj, NxReal dx, NxReal dy, NxReal dz, NxReal vel)
	Sets the linear velocity of the object.
void	ObjSetAngularVelocity (const VR3Obj *obj, NxReal dx, NxReal dy, NxReal dz, NxReal avel)
	Sets the linear velocity of the object.
void	ObjSetLinearDamping (const VR3Obj *obj, NxReal damping)
	Sets the linear damping for the object.
void	ObjSetAngularDamping (const VR3Obj *obj, NxReal adamping)
	Sets the angular damping for the object.
void	ObjSetMaxAngularVelocity (const VR3Obj *obj, NxReal maxavel)
	Sets the maximum angular velocity for the object.
void	ObjSetStaticFriction (const VR3Obj *obj, NxReal sfri)
	Sets the static friction of the given object.
void	ObjSetDynamicFriction (const VR3Obj *obj, NxReal dfri)
	Sets the dynamic friction of the given object.
void	ObjSetBounciness (const VR3Obj *obj, NxReal bou)
	Sets the bounciness of the given object.
void	ObjSetSkinWidth (const VR3Obj *obj, NxReal swidth=-1.0f)
	Sets the skin width used for simulation of the given object.
void	ObjAffectedByGravity (const VR3Obj *obj, bool flag)
	Establishes if the object is affected by gravity.
void	ObjCollide (const VR3Obj *obj, bool flag)
	Establishes if the object may collide with other objects.
Simulation Data Extraction
int	ObjGetType (const VR3Obj *obj)
	Gets the simulation type for a specific object.
void	ObjGetCenterOfMassPos (const VR3Obj obj, NxReal pos)
	Gets the position of the center of mass in world coordinates.
NxReal	ObjGetMass (const VR3Obj *obj)
	Retrieves the mass of the given object.
void	ObjGetInertiaTensor (const VR3Obj obj, NxReal tens)
	Gets the global space inertia tensor.
void	ObjGetLinearVelocity (const VR3Obj obj, NxReal vel)
	Gets the linear velocity of the actor.
void	ObjGetAngularVelocity (const VR3Obj obj, NxReal avel)
	Gets the angular velocity of the actor.
void	ObjGetPointVelocity (const VR3Obj obj, NxReal x, NxReal y, NxReal z, NxReal vel)
	Gets the velocity of a point.
void	ObjGetLinearMomentum (const VR3Obj obj, NxReal mom)
	Gets the linear momentum of an actor.
void	ObjGetAngularMomentum (const VR3Obj obj, NxReal amom)
	Gets the angular momentum of an actor.
NxReal	ObjGetKineticEnergy (const VR3Obj *obj)
	Gets the kinetic energy of the object.
NxReal	ObjGetStaticFriction (const VR3Obj *obj)
	Gets the static friction of the given object.
NxReal	ObjGetDynamicFriction (const VR3Obj *obj)
	Gets the dynamic friction of the given object.
NxReal	ObjGetBounciness (const VR3Obj *obj)
	Gets the bounciness of the given object.
NxReal	ObjGetSkinWidth (const VR3Obj *obj)
	Gets the skin width used for simulation of the given object.
Point Transformation Functions
void	ObjLocalToWorld (const VR3Obj obj, const GLfloat inpoint, GLfloat *outpoint)
	Brings a point from obj-space coordinates to world coordinates.
bool	ObjPointInBBox (const VR3Obj *obj, NxReal x, NxReal y, NxReal z)
	Checks if a point is inside the object's bounding box.
Simulation Management Functions
void	PrepareSimulation ()
	Prepares the simulation.
void	StartSimulation ()
	Starts the simulation.
void	HaltSimulation ()
	Halts the simulation.
void	ResetSimulation ()
	Resets the simulation.
void	EndSimulation ()
	Ends the simulation.
Timer Management Functions
void	ResetTimer ()
	Resets the timer.
NxReal	GetElapsedTime ()
	Gets the elapsed time since the last time this function was called.
Private Member Functions
	VR3PhysicsSimulator (const VR3PhysicsSimulator &)
	Disable default copy constructor.
VR3PhysicsSimulator &	operator= (const VR3PhysicsSimulator &)
	Disable default assignment operator.
Actors Cooking Functions
void	CookStaticActor (const VR3Obj obj, MapElement elem)
	Prepares a static actor cooking a triangle mesh.
void	CookNonStaticActor (const VR3Obj obj, MapElement elem)
	Prepares a non-static actor cooking a convex mesh compound.
Results Fetching Functions
void	CollectResults ()
	Collects the results of the simulation.
bool	GetModelMat (const VR3Obj obj, GLfloat modelmat)
	Retrieves the modeling matrix resulting from the physX simulation.
Private Attributes
int	m_mode
	Physics simulator mode.
bool	m_prepared
	Flag stating if this physics simulator has been prepared for simulation.
bool	m_simulating
	Flag stating if this physics simulator is simulating or not.
int	m_solveriter
	Number of solver iterations to perform for rigid bodies.
std::set< const VR3Obj * >	m_objects
	Set of registered objects.
std::set< VR3PhyMesh * >	m_phymeshes
	Set of physical meshes requested in the simulator life.
std::unordered_map< const VR3Obj *, MapElement >	m_simobjects
	Set of currently simulated objects.
std::map< int, void * >	m_joints
	Set of currently simulated joints.
void *	m_SDK
	PhysX SDK pointer.
void *	m_scene
	PhysX scene pointer.
void *	m_cookinterface
	PhysX cooking interface.
long long	m_freq
	High-resolution timer frequency.
long long	m_previoustime
	High-resolution timer last recorded value.
const VR3Obj *	m_movobj
	Active object for a ObjBeginMove()...ObjEndMove() block.
void *	m_movmat
	Total transformation matrix to send to PhysX at the end of the block.
Static Private Attributes
static VR3PhysicsSimulator *	ms_activesimulator
	Pointer to the currently active VR3PhysicsSimulator object.
Friends
class	VR3Obj
	Friend class VR3Obj to access the private AutoSimulateObject() method.
class	VR3Scene
	Friend class VR3Scene to access the CollectResults() method.
Object Registration Functions
void	AutoSimulateObject (const VR3Obj *obj, bool simulate)
	Registers a new object (auto-called)
void	SimulateObject (const VR3Obj *obj, bool simulate)
	Registers a new object (user-called)
Active Physics Simulator Management
static VR3PhysicsSimulator *	GetActiveSimulator ()
	Gets the currently active VR3PhysicsSimulator object.
void	Activate ()
	Activates the current physics simulator.
void	Deactivate ()
	Deactivates the current controller.
bool	IsSimulating ()
	Retrieves the simulation status.
bool	HasBeenPrepared ()
	Retrieves the simulation preparation.

Detailed Description

The physics simulator class.

This class is used as an interface to the Nvidia PhysX simulation software that handles physics simulation in the VR3Scene.

In the current implementation, a physics simulator only handles rigid body simulation performed on the CPU (software simulation). In the current PhysX implementation (SDK version 2.8.4 at the time of writing) rigid body simulation may only happen on the CPU. It is possible to create hardware accelerated rigid body simulations only on a PPU, but on a PhysX-enabled GPU it will fall back to software simulation.

Note that the Nvidia PhysX SDK in the latest versions is only available for Windows platforms. This is the only component in the VR3Lib which is strongly platform-specific. When the VR3Lib is built under a non-Windows system, the physics simulation subsystem will be automatically disabled.

Also note that in the PhysX SDK 2.8.4 rigid bodies in a hardware compartment will not be able to interact with cloth, soft bodies and fluids in other compartments.

In order to have cloth and fluids interacting with rigid bodies, in the current PhysX implementation rigid bodies must lie in the so called PhysX master scene (and therefore be simulated on the CPU).

Therefore, the user should be aware that our rigid body physical simulation is completely CPU-powered (using PhysX multithreaded engine).

Also note that in PhysX SDK 2.8.4, some dinamic libraries are to be distributed with the VR3Lib executable. We'll not include hardware simulation - related dlls because useless at this time but future extensions may need them to be added.

Future extensions of the VR3Lib may add support for hardware-simulated soft bodies, cloth and fluids.

As the VR3ShadowController class, even a VR3PhysicsSimulator object must be instantiated in order to take advantage of the built in PhysX-powered physics simulation module. A physics simulator may be configured as:

automatic physics simulator
manual physics simulator

If the simulator is configured as manual, the user will have to manually add all objects (and their relationships) to the simulator before starting the simulation. If the user creates an automatic simulator, all objects will be automatically added to the PhysX scene with their parental relationships.

In case an automatic physics simulator is created, the user should build it before starting the scene objects creation and manipulation. All created VR3Obj objects will be automatically registered with the simulator as soon as a mesh (AAM obj) is assigned to them (and therefore a physical AAM obj is). Also note that the AAM physical obj (physical mesh) used for physical simulation will always be the one associated with the first LOD in the VR3Obj object (VR3Obj::m_meshes[0]). The user may create and pass a new VR3PhyMesh in order to bind the object with a different physical representation.

The VR3PhyMeshManager static module is used to avoid multiple VR3PhyMesh instantiation for the same physical mesh.

A physical mesh object represents an object as a physical entity (not scaled, moved to its position or rotated) and many objects may refer to the same VR3PhyMesh as their physical model.

A VR3PhyMesh always has a type that describes the sort of simulation the VR3PhyMesh is designed for (read from the mesh file):

VR3PHYMESH_DYNAMIC Full PhysX simulation, the object is affected by gravity and collisions, it may be moved where desired by the user and forces may be applied to it.
VR3PHYMESH_STATIC The objects associated with a static VR3PhyMesh are designed to be static, not moved by the user and unaffected by forces. Even if allowed, by the PhysX SDK, movement actors built from this type of physical mesh is forbidden because they are not designed to be moved.
VR3PHYMESH_KINEMATIC This can be seen as a dynamic object unaffected by forces, gravity and collisions. Kinematic objects may be moved by the user as if they had an infinite mass. This type of actor will push away any dynamic object encountered, but will not collide with static actors.

When the scene VR3Obj objects have been created (and eventually added manually to the VR3PhysicsSimulator object if configured as manual), the object is prepared for simulation by calling the PrepareSimulation() method. This function will build the actors used for the simulation. In the PrepareSimulation() method we also have all the mesh cooking activity; therefore, this method is really time-consuming. Simulation may start by calling the VR3PhysicsSimulator::StartSimulation() method at the end of the application initialization. When the StartSimulation() method is called before preparing for the simulation, the PrepareSimulation() method will also be automatically called. Simulation may be paused by calling the StopSimulation() method, and resumed with a new call to StartSimulation().

Simulation is ended by calling the EndSimulation() method. This usually happens on program shutdown and will also release all actors in the scene. Simulation may be initialized again by calling the PrepareSimulation() method, this will reset all objects to their initial positions and orientations (specified with the VR3Obj methods).

Notice that some rules apply to avoid potentially dangerous situations:

Once the simulation has been prepared, added or removed objects (even if automatically) won't affect simulation: new objects won't be simulated and old objects will keep being simulated, until a new PrepareSimulation() is issued
The active simulator is the only one that can have a physics simulation running.

We use an instantiated object and not a static one for physics management in order to allow the user to create multiple PhysX scene by using multiple VR3PhysicsSimulato objects. Usually, just one object of this type will be created for a VR3Lib application.

The convention we use for units is the following: numerical data are treated as if they were meters for lengths and space positions, kilograms for mass and seconds for time. This also means that any particular derived quantity (such as a force) has a unit derived from our basic units (e.g. kg * m/(s*s) for forces). A proof of this is that the default gravity acceleration points towards -Y with magnitude 9.8 (N). Of course this is a convention, the user may assume distances read from a AAM file to be in centimeters or mass to be misured in g instead of kg, this will change all derived quantities' units and the user will have to set the gravity and any force accordingly. Also note that when objects are scaled, their mass is scaled accordingly. This mass scaling behaviour may not be the desired one, in this case the user may always explicitly set the mass at will after PrepareSimulation() has been called.

Objects to be physically simulated as rigid bodies are registered with the simulator either manually or automatically depending on the simulator mode. In automatic mode, all objects created and having a non-null mesh will be registered with the simulator. In manual mode, the user will have to specify the single objects that are to be simulated.

Regarding parental relationships, initial positions, rotation and scaling for physical actors will depend on their parents as usual. No direct motion relationships will be present between a parent and its children. To obtain some sort of movement constraints between parent and children the user will have to establish joints between objects using the provided Add*Joint() functions. When drawing, physically simulated object will always obtain all their position, rotation and scaling information from this simulation engine. They will pass this matrix to their children, so they can use it in case of not physically simulated objects. If the child (receiving the parent's transformation matrix) is physically simulated, it will simply ignore the received matrix during rendering. Therefore, if the parent is registered with the simulator but the child is not, it will simply follow the parent's movements. If the children is registered with the simulator but the parent is not, its initial position, orientation and scale will be the same as in the non-simulated case, but then the object will evolve without regard to its non-simulated parent.

Using the VR3PhysicsSimulator, the user may specify which type of constraint exists between two objects. The parental relationship in this context only serves as a cascaded rendering feature (just draw the first object of the tree).

The currently active VR3PhysicsSimulator object is the simulator used when automatically registering and deregistering objects and is the simulator used to extract position and orientation informations for a given object.

During physics simulation, the presence of a pivot point in the simulated object different from the origin is completely ignored. Nevertheless, pivot points may be used before calling the PrepareSimulation function in order to obtain the correct objects initial position.

Definition at line 205 of file VR3PhysicsSimulator.h.

Constructor & Destructor Documentation

VR3PhysicsSimulator::VR3PhysicsSimulator ( const VR3PhysicsSimulator & ) [private]

Disable default copy constructor.

VR3PhysicsSimulator::VR3PhysicsSimulator	(	int	mode = `VR3PHYSIM_AUTOMATIC`,
		int	solveriter = `VR3PHYSIM_DEF_ITERNUM`,
		float	timestep = `VR3PHYSIM_DEF_TIMESTEP`,
		int	maxsteps = `VR3PHYSIM_DEF_MAXSTEPS`
	)

Physics simulator constructor.

Builds a new physics simulator with an empty registered objects set. This constructor also makes this simulator object the active one and stores the specified mode. The solver iteration number parameters allows the user to specify the number of solver iteration PhysX should perform. Note that a high value of solver iterations will improve simulation stability but will negatively affect the frame rate. Use a high iteration number if you see oscillations in your simulations, the number of iterations must be a number between 1 and 255 (its default value is VR3PHYSIM_DEF_ITERNUM). The timestep and the maxsteps may be specified in order to fine-tune the simulation, please refer to the VR3PHYSIM_DEF_TIMESTEP and VR3PHYSIM_DEF_MAXSTEPS documentation for more information.

Parameters:

[in]	mode	Physics simulator mode, one of: VR3PHYSIM_AUTOMATIC VR3PHYSIM_MANUAL
[in]	solveriter	Number of iteration the PhysX rigid body solver will have to perform when simulating rigid bodies
[in]	timestep	The timestep to use while simulating
[in]	maxsteps	The maximum number of steps in a single simulation cycle

VR3PhysicsSimulator::~VR3PhysicsSimulator ( )

Physics simulator destructor.

Destroys the physics simulator and the whole PhysX scene associated with it. It is also used to realease all reference to physical meshes collected during its life time.

Member Function Documentation

void VR3PhysicsSimulator::Activate ( )

Activates the current physics simulator.

Sets this simulator as the active one, possibly overwriting other controllers. If the currently active simulator is still simulating, simulation is stopped and this is made the active simulator.

int VR3PhysicsSimulator::AddCylindricalJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	axisX,
		NxReal	axisY,
		NxReal	axisZ,
		bool	collide
	)

Adds a cylindrical joint.

A cylindrical joint permits both relative translational and rotational movement between two bodies along a single axis (i.e., the bodies are allowed to both slide and twist along the axis of the joint). This type of joint removes 4 degrees of freedom, mantaining a single relative rotation and translation axis.

Parameters:

[in]	o1,o2	Objects jointed
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (the axis runs through the anchor)
[in]	axisX,axisY,axisZ	Allowed relative translation and rotation axis (world coordinates)
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddCylindricalJoint	(	const VR3Obj *	o,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	axisX,
		NxReal	axisY,
		NxReal	axisZ
	)

Adds a cylindrical joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. A cylindrical joint is established between the object and the world.

Parameters:

[in]	o	Object to joint with the word
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (the axis runs through the anchor)
[in]	axisX,axisY,axisZ	Allowed relative translation and rotation axis (world coordinates)

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddDistanceJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	mindist,
		NxReal	maxdist,
		bool	collide
	)

Adds a distance joint.

This type of joint tries to mantain a certain distance between the two objects, the user may specify a minimum and a maximum distance to be mantained. With this type of joint collision detection between the two objects is always disabled. The distance is misured from the center of mass of the two actors. Note that the point we are measuring distance from is located on the second actor and moves with it, this is important when dealing with kinematic objects.

Parameters:

[in]	o1,o2	Objects jointed
[in]	mindist,maxdist	Minimum and maximum distance to mantain
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 on failure)

int VR3PhysicsSimulator::AddDistanceJoint	(	const VR3Obj *	o,
		NxReal	pointX,
		NxReal	pointY,
		NxReal	pointZ,
		NxReal	mindist,
		NxReal	maxdist
	)

Adds a distance joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Used to mantain a certain distance between an object and a world fixed point.

Parameters:

[in]	o	Object to joint with the word
[in]	pointX,pointY,pointZ	World point jointed with the object
[in]	mindist,maxdist	Minimum and maximum distance to mantain

Returns:: The resulting joint id (-1 on failure)

int VR3PhysicsSimulator::AddFixedJoint ( const VR3Obj * o )

Adds a fixed joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. The object is frozen in its position even if not static (the joint may be removed to free the object).

Parameters:

[in] o Object to joint with the word

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddFixedJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2
	)

Adds a fixed joint.

This type of joint blocks relative movement of the two objects, they will act as a single object and always move together. Collision detection between the two objects in this case is disabled.

Parameters:

[in] o1,o2 Objects jointed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddGenericJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	xaxisX,
		NxReal	xaxisY,
		NxReal	xaxisZ,
		NxReal	yaxisX,
		NxReal	yaxisY,
		NxReal	yaxisZ,
		bool	xtrans,
		bool	ytrans,
		bool	ztrans,
		bool	xrot,
		bool	yrot,
		bool	zrot,
		bool	collide
	)

Adds a generic joint.

A generic joint is a joint which may be configured to remove 0 to 6 degrees of freedom, a joint must be thought as being characterized by 3 orthonormal axes (X, Y and Z). Rotation around one of those axis may be allowed or deny, and the same holds for translation along one of those axes. The user specifies the global orientations of the X and Y axes when calling this function, Z will be computed as X cross product Y.

With generic joints, any type of joint above may be built. Nevertheless, it is recommended not to use generic joints when their flexibility is not necessary. This is due to generic joints intrinsic simulation instability in PhysX.

Parameters:

[in]	o1,o2	Objects jointed
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (center of the joint where the 3 axes meet)
[in]	xaxisX,xaxisY,xaxisZ	X axis components (world space coordinates)
[in]	yaxisX,yaxisY,yaxisZ	Y axis components (world space coordinates)
[in]	xtrans,ytrans,ztrans	Translation allowed along axes flags
[in]	xrot,yrot,zrot	Rotation allowed arown axes flags
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddGenericJoint	(	const VR3Obj *	o,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	xaxisX,
		NxReal	xaxisY,
		NxReal	xaxisZ,
		NxReal	yaxisX,
		NxReal	yaxisY,
		NxReal	yaxisZ,
		bool	xtrans,
		bool	ytrans,
		bool	ztrans,
		bool	xrot,
		bool	yrot,
		bool	zrot
	)

Adds a generic joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. A point on line joint is established between the object and the world.

Parameters:

[in]	o	Object to joint with the word
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (center of the joint where the 3 axes meet)
[in]	xaxisX,xaxisY,xaxisZ	X axis components (world space coordinates)
[in]	yaxisX,yaxisY,yaxisZ	Y axis components (world space coordinates)
[in]	xtrans,ytrans,ztrans	Translation allowed along axes flags
[in]	xrot,yrot,zrot	Rotation allowed arown axes flags

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddPointInPlaneJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	normX,
		NxReal	normY,
		NxReal	normZ,
		bool	collide
	)

Adds a point in a plane joint.

A point in plane joint constrains a point on one actor to only move inside a plane attached to another actor. The point attached to the plane is defined by the anchor point. The joint's axis specifies the plane normal. This effectively removes just the translational DOF ortogonal to the plane. This function and the other ones may be used with kinematic objects, but in this case the behaviour will not be the intended one if the second object is the kinematic one (this is because the plane is attached to the first object and moves with it).

Parameters:

[in]	o1,o2	Objects jointed
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (the plane runs through the anchor)
[in]	normX,normY,normZ	The plane normal
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddPointInPlaneJoint	(	const VR3Obj *	o,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	normX,
		NxReal	normY,
		NxReal	normZ
	)

Adds a point in a plane joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. A point in plane joint is established between the object and the world (the plane is fixed and attached to the world).

Parameters:

[in]	o	Object to joint with the word
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (the plane runs through the anchor)
[in]	normX,normY,normZ	The plane normal

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddPointOnLineJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	lineX,
		NxReal	lineY,
		NxReal	lineZ,
		bool	collide
	)

Adds a point on line joint.

A point on line joint constrains a point on one actor to only move along a line attached to another actor. The point attached to the line is the anchor point for the joint. The line through this point is specified by its direction (axis) vector. The line is attached to the first object and moves as he moves.

Parameters:

[in]	o1,o2	Objects jointed
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (the line runs through the anchor)
[in]	lineX,lineY,lineZ	The line to follow
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddPointOnLineJoint	(	const VR3Obj *	o,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	lineX,
		NxReal	lineY,
		NxReal	lineZ
	)

Adds a point on line joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. A point on line joint is established between the object and the world (the line is fixed and attached to the world).

Parameters:

[in]	o	Object to joint with the word
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (the line runs through the anchor)
[in]	lineX,lineY,lineZ	The line to follow

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddPrismaticJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	axisX,
		NxReal	axisY,
		NxReal	axisZ,
		bool	collide
	)

Adds a prismatic joint.

A prismatic joint removes 5 degrees of freedom, only mantaining a single relative translational one. The axis specified is used to understand which single translational DOF is mantained.

Parameters:

[in]	o1,o2	Objects jointed
[in]	axisX,axisY,axisZ	Allowed relative translation axis (world coordinates)
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddPrismaticJoint	(	const VR3Obj *	o,
		NxReal	axisX,
		NxReal	axisY,
		NxReal	axisZ
	)

Adds a prismatic joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. A prismatic joint is established between the object and the world.

Parameters:

[in]	o	Object to joint with the word
[in]	axisX,axisY,axisZ	Allowed translation axis (world coordinates)

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddPulleyJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	p1X,
		NxReal	p1Y,
		NxReal	p1Z,
		NxReal	p2X,
		NxReal	p2Y,
		NxReal	p2Z,
		NxReal	stiffness,
		NxReal	ratio,
		bool	collide
	)

Adds a pulley joint.

This joint can be viewed as a rope connecting two rigid bodies, just as in the case of a Distance joint. This time the rope does not follow the shortest path, instead it runs through two pulley points (that can eventually be the same). The rope is attached to the center of mass of the two actors.

Parameters:

[in]	o1,o2	Objects jointed
[in]	p1X,p1Y,p1Z	World space position of the first pulley point
[in]	p2X,p2Y,p2Z	World space position of the second pulley point
[in]	stiffness	Stiffness of the constraint (between 0 and 1, 1 is the stiffest)
[in]	ratio	Transmission ratio of the rope (how much of the force applied by o1 end is transmitted at the other, to o2).
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddRevoluteJoint	(	const VR3Obj *	o,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	axisX,
		NxReal	axisY,
		NxReal	axisZ
	)

Adds a revolute joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. A revolute joint is established between the object and the world.

Parameters:

[in]	o	Object to joint with the word
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (the axis runs through the anchor)
[in]	axisX,axisY,axisZ	Allowed relative rotation axis (world coordinates)

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddRevoluteJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		NxReal	axisX,
		NxReal	axisY,
		NxReal	axisZ,
		bool	collide
	)

Adds a revolute joint.

A revolute joint removes all but a single rotational degree of freedom from two objects. The axis along which the two bodies may rotate is specified with a point and a direction vector. In theory, the point along the direction vector does not matter, but in practice, it should be near the area where the bodies are closest to improve simulation stability. This function also allows an angular spring and some angular limits to be specified for the joint.

Parameters:

[in]	o1,o2	Objects jointed
[in]	anchorX,anchorY,anchorZ	World space position of the anchor (the axis runs through the anchor)
[in]	axisX,axisY,axisZ	Allowed relative rotation axis (world coordinates)
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddSphericalJoint	(	const VR3Obj *	o1,
		const VR3Obj *	o2,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ,
		bool	collide
	)

Adds a spherical joint.

A spherical joint removes the three translational degrees of freedom, allowing relative rotation around any axis.

Parameters:

[in]	o1,o2	Objects jointed
[in]	anchorX,anchorY,anchorZ	World space position of the anchor
[in]	collide	Boolean flag stating if collision between the two objects is allowed

Returns:: The resulting joint id (-1 and warning on failure)

int VR3PhysicsSimulator::AddSphericalJoint	(	const VR3Obj *	o,
		NxReal	anchorX,
		NxReal	anchorY,
		NxReal	anchorZ
	)

Adds a spherical joint.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. A spherical joint is established between the object and the world.

Parameters:

[in]	o	Object to joint with the word
[in]	anchorX,anchorY,anchorZ	World space position of the anchor

Returns:: The resulting joint id (-1 and warning on failure)

void VR3PhysicsSimulator::AutoSimulateObject	(	const VR3Obj *	obj,
		bool	simulate
	)		`[private]`

Registers a new object (auto-called)

This function cannot be directly called by the user, instead is automatically called by the objects to keep the registered objects set updated in automatic physics simulators. If the simulate input parameter is true the object is registered for simulation, if false the object is deregistered for simulation. If this function is called on a manual physics simulator, it has no effect.

Parameters:

[in]	obj	The object we have to register or deregister
[in]	simulate	true if the object is to be registered, false otherways

void VR3PhysicsSimulator::CollectResults ( ) [private]

Collects the results of the simulation.

In PhysX, simulation happens in a separate thread working of local variables, when the simulation has finished buffers are swapped to access the updated actor data. If not paused, the simulation is again lunched and the simulating thread starts working again. Updated actor data is accessed during object rendering and not at this time.

NOTE: In case the physics simulation is so complex that rendering procedes faster than the simulation thread, we won't wait for the simulation to terminate and check again on the following frame. Physically complex scenes may not result in an accurate simulation, but will not cause the frame rate to drop to low values.

void VR3PhysicsSimulator::CookNonStaticActor	(	const VR3Obj *	obj,
		MapElement *	elem
	)		`[private]`

Prepares a non-static actor cooking a convex mesh compound.

For kinematic and dynamic actors, PhysX is not capable of simulating arbitrary triangle meshes as physical models. To allow arbitrary shapes to be simulated, a dynamic or kinematic actor is represented by a compound of convex meshes. The convex decomposition of the geometric mesh happens off-line and the result is read by the VR3Lib from the AAM file.

Parameters:

[in]	obj	Object whose actor is being created
[in,out]	elem	Map element in the high-speed simulating objects map where to write the actor address and where all physical mesh data is stored

void VR3PhysicsSimulator::CookStaticActor	(	const VR3Obj *	obj,
		MapElement *	elem
	)		`[private]`

Prepares a static actor cooking a triangle mesh.

Static actors are simulated through PhysX using generic triangle meshes, this is not possible for dynamic or kinematic actors. The mesh is cooked using the physical mesh data and a new actor is added to the PhysX scene using an initial position and rotation.

Parameters:

[in]	obj	Object whose actor is being created
[in,out]	elem	Map element in the high-speed simulating objects map where to write the actor address and where all physical mesh data is stored

void VR3PhysicsSimulator::Deactivate ( )

Deactivates the current controller.

If this simulator is the currently active physics simulator, it is deactivated and the active simulator is set tu NULL. Notice that if this simulator is still simulating when deactivated, simulation is stopped.

void VR3PhysicsSimulator::DeleteJoint ( int jointID )

Deletes a joint that is being simulated.

A joint is deleted and the simulation procedes without the movement constraint specified by the joint. The deleted joint is identified by the id that is returned at joint creation time.

Parameters:

[in] jointID the id of the joint to delete

void VR3PhysicsSimulator::EndSimulation ( )

Ends the simulation.

This method is used to terminate the simulation, releasing all resources acquired during simulation preparation and clearing the simulating objects map. If this function is called when the simulation is running, the simulation is obviously halted.

static VR3PhysicsSimulator* VR3PhysicsSimulator::GetActiveSimulator ( ) [inline, static]

Gets the currently active VR3PhysicsSimulator object.

This static method gets the currently physics simulator, notice that just one simulator may be active at any given time.

Returns:: The active physics simulator

Definition at line 367 of file VR3PhysicsSimulator.h.

NxReal VR3PhysicsSimulator::GetElapsedTime ( )

Gets the elapsed time since the last time this function was called.

To accomplish physics simulation, a high-resolution timer is needed in order to set the time to simulate from frame to frame. This function is used to get the elapsed time in seconds since the last GetElapsedTime() function call. The counter must have been already initialized and the first GetElapsedTime() call will return the elapsed time since the ResetTime() call.

Returns:: Elapsed time since last call (in seconds)

bool VR3PhysicsSimulator::GetModelMat	(	const VR3Obj *	obj,
		GLfloat *	modelmat
	)		`[private]`

Retrieves the modeling matrix resulting from the physX simulation.

This function is used during object rendering to retrieve the modeling matrix resulting from the PhysX simulation for a given VR3Obj object (associated with an actor). The matrix is returned in the given buffer. This function returns false if no modeling matrix for the given object could be found, this happens if the object is not in the currently simulated set.

Parameters:

[in]	obj	The VR3Obj we are drawing
[out]	modelmat	Resulting modeling matrix

Returns:: true if a modeling matrix could be found, false otherways

void VR3PhysicsSimulator::HaltSimulation ( )

Halts the simulation.

This method is used to pause the simulation without releasing all resources acquired during simulation preparation.

bool VR3PhysicsSimulator::HasBeenPrepared ( ) [inline]

Retrieves the simulation preparation.

This function may be used to discover if the simulation has already been prepared (and therefore the registered objects set is stuck).

Returns:: true if simulation is ready, false otherways

Definition at line 401 of file VR3PhysicsSimulator.h.

bool VR3PhysicsSimulator::IsSimulating ( ) [inline]

Retrieves the simulation status.

This function may be used to discover is the simulation is currently running or not.

Returns:: true if simulation is running, false otherways

Definition at line 392 of file VR3PhysicsSimulator.h.

void VR3PhysicsSimulator::ObjAddForce	(	const VR3Obj *	obj,
		NxReal	dx,
		NxReal	dy,
		NxReal	dz,
		NxReal	mag
	)

Adds the specified force at the center of mass.

A force vector is applied to the provided object for one simulation cycle, this force is applied at the center of mass and therefore will not introduce a torque. The provided vector, usually a force, may change its meaning depending on the last parameter. Only dynamic objects are valid as input argument. Because the provided direction will not be normalized in this function, the caller may use vector components directly with a magnitude of 1.0.

Parameters:

[in]	obj	The object the force must be applied to
[in]	dx,dy,dz	Force direction components
[in]	mag	Magnitude of the applied force

void VR3PhysicsSimulator::ObjAddForce	(	const VR3Obj *	obj,
		NxReal	px,
		NxReal	py,
		NxReal	pz,
		NxReal	dx,
		NxReal	dy,
		NxReal	dz,
		NxReal	mag
	)

Adds the specified force at a given global point.

A force vector is applied to the provided object for one simulation cycle, this force is applied at the given point in global coordinates (even if this point is not part of the rigid body). Only dynamic objects are valid as input argument. Because the provided direction will not be normalized in this function, the caller may use vector components directly with a magnitude of 1.0.

Parameters:

[in]	obj	The object the force must be applied to
[in]	px,py,pz	Point the force is applied to
[in]	dx,dy,dz	Force direction components
[in]	mag	Magnitude of the applied force

void VR3PhysicsSimulator::ObjAddTorque	(	const VR3Obj *	obj,
		NxReal	dx,
		NxReal	dy,
		NxReal	dz,
		NxReal	mag
	)

Adds a torque.

A torque is applied to the provided object for one simulation cycle, the torque is specified using the direction vector (the convential direction of the torque vector in physics) and the magnitude. Only dynamic objects are valid as input argument. Because the provided direction will not be normalized in this function, the caller may use vector components directly with a magnitude of 1.0.

Parameters:

[in]	obj	The object the force must be applied to
[in]	dx,dy,dz	Torque direction components
[in]	mag	Magnitude of the applied torque

void VR3PhysicsSimulator::ObjAffectedByGravity	(	const VR3Obj *	obj,
		bool	flag
	)

Establishes if the object is affected by gravity.

This function must be called on dynamic actors only.

Parameters:

[in]	obj	The target object
[in]	flag	true if the object must be affected by gravity, false otherways

void VR3PhysicsSimulator::ObjBeginMove ( const VR3Obj * obj )

Begin a movement operation block.

A call to this function is effectively necessary only if multiple movement operations need to be combined in a single simulation cycle. It will initialize the movement matrix for the object.

Parameters:

[in] obj The object to move in the subsequent calls

void VR3PhysicsSimulator::ObjCollide	(	const VR3Obj *	obj,
		bool	flag
	)

Establishes if the object may collide with other objects.

Parameters:

[in]	obj	The target object
[in]	flag	true if the object must collide with others, false otherways

void VR3PhysicsSimulator::ObjEndMove ( )

Begin a movement operation block.

A call to this function is effectively necessary only if multiple movement operations need to be combined in a single simulation cycle. It will commit to PhysX the new updated movement matrix.

void VR3PhysicsSimulator::ObjGetAngularMomentum	(	const VR3Obj *	obj,
		NxReal *	amom
	)

Gets the angular momentum of an actor.

This momentum is given by the angular velocity times the global space inertia tensor. Only appliable to dynamic objects.

Parameters:

[in]	obj	The target object
[out]	amom	The resulting angular momentum

void VR3PhysicsSimulator::ObjGetAngularVelocity	(	const VR3Obj *	obj,
		NxReal *	avel
	)

Gets the angular velocity of the actor.

When applied to kinematic objects, the velocity may be non-zero only if the new position and orientation have been already set.

Parameters:

[in]	obj	The target object
[out]	avel	the resulting angular velocity

NxReal VR3PhysicsSimulator::ObjGetBounciness ( const VR3Obj * obj )

Gets the bounciness of the given object.

Parameters:

[in] obj The target object

Returns:: The bounciness coefficient (a negative value and a warning in case the object is not found)

void VR3PhysicsSimulator::ObjGetCenterOfMassPos	(	const VR3Obj *	obj,
		NxReal *	pos
	)

Gets the position of the center of mass in world coordinates.

This function may be called only on non-static actors.

Parameters:

[in]	obj	The target object
[out]	pos	The returned mass center position

NxReal VR3PhysicsSimulator::ObjGetDynamicFriction ( const VR3Obj * obj )

Gets the dynamic friction of the given object.

Parameters:

[in] obj The target object

Returns:: The dynamic friction (a negative value and a warning in case the object is not found)

void VR3PhysicsSimulator::ObjGetInertiaTensor	(	const VR3Obj *	obj,
		NxReal *	tens
	)

Gets the global space inertia tensor.

This function retrieves the moment of inertia or inertia tensor of the object with respect to the global reference frame. The tensor is returned in a provided 9-components float vector that is a 3x3 row-major matrix. This function should be called only on dynamic objects.

Parameters:

[in]	obj	The target object
[out]	tens	The resulting inertia tensor

NxReal VR3PhysicsSimulator::ObjGetKineticEnergy ( const VR3Obj * obj )

Gets the kinetic energy of the object.

The total kinetic energy (translational and rotational) of the actor is returned. This function is only appliable to dynamic objects.

Parameters:

[in] obj The target object

Returns:: The resulting kinetic energy (a negative value and a warning if the operation failed)

void VR3PhysicsSimulator::ObjGetLinearMomentum	(	const VR3Obj *	obj,
		NxReal *	mom
	)

Gets the linear momentum of an actor.

This momentum is given by the velocity times the mass, is returned in a 3-component array. Only appliable to dynamic objects.

Parameters:

[in]	obj	The target object
[out]	mom	The resulting linear momentum

void VR3PhysicsSimulator::ObjGetLinearVelocity	(	const VR3Obj *	obj,
		NxReal *	vel
	)

Gets the linear velocity of the actor.

When applied to kinematic objects, the velocity may be non-zero only if the new position and orientation have been already set. This function should be called only on non-static objects.

Parameters:

[in]	obj	The target object
[out]	vel	the resulting velocity of the center of mass

NxReal VR3PhysicsSimulator::ObjGetMass ( const VR3Obj * obj )

Retrieves the mass of the given object.

The mass parameter read from the mesh file is scaled depending on the scaling factors applied to the object, this is done as if the object were made of the same material on the entire volume. This function shall be called only on a dynamic object, if called on a non-dynamic object the returned value will be 0.0.

Parameters:

[in] obj The target object

Returns:: The object mass (a negative value and a warning if the operation fails)

void VR3PhysicsSimulator::ObjGetPointVelocity	(	const VR3Obj *	obj,
		NxReal	x,
		NxReal	y,
		NxReal	z,
		NxReal *	vel
	)

Gets the velocity of a point.

Gets the volocity of the specified point as if it were attached to the object and moving with it. When applied to kinematic objects, the velocity may be non-zero only if the new position and orientation have been already set.

Parameters:

[in]	obj	The target object
[in]	x,y,z	Point position
[out]	vel	The resulting velocity

NxReal VR3PhysicsSimulator::ObjGetSkinWidth ( const VR3Obj * obj )

Gets the skin width used for simulation of the given object.

The skin width is a fundamental parameter in PhysX simulation, it affects simulation stability and realism. It is automatically set based on the object size, but may be changed using ObjSetSkinWidth().

Parameters:

[in] obj The target object

Returns:: The skin width (a negative value and a warning in case the object is not found)

NxReal VR3PhysicsSimulator::ObjGetStaticFriction ( const VR3Obj * obj )

Gets the static friction of the given object.

Parameters:

[in] obj The target object

Returns:: The static friction (a negative value and a warning in case the object is not found)

int VR3PhysicsSimulator::ObjGetType ( const VR3Obj * obj )

Gets the simulation type for a specific object.

These functions may be called only after the simulation has been successfully prepared. This function may be called on any objects and retrieves the type of the physically simulated objects (static, dynamic or kinematic). The operation may fail without program termination, in such case the value -1 is returned.

Parameters:

[in] obj The target object

Returns:

pos Type of the simulated object:

void VR3PhysicsSimulator::ObjLocalToWorld	(	const VR3Obj *	obj,
		const GLfloat *	inpoint,
		GLfloat *	outpoint
	)

Brings a point from obj-space coordinates to world coordinates.

When using physically simulated objects, all transformation-related functions available in VR3Obj become useless during simulation. All those functions operate on initial transformations of the object before the beginning of the simulation. This is done to encapsulate all physical simulation related functionalities in this single simulator object (an object of type VR3PhysicsSimulator). This function may be called to figure out the position of an object space point into the world (compute its world position). This function works as VR3Obj::LocalToWorld() in case of simulation. Note that inpoint may equal outpoint.

Parameters:

[in]	obj	The target object
[in]	inpoint	Point in object coordinates
[out]	outpoint	Computed world space position

bool VR3PhysicsSimulator::ObjPointInBBox	(	const VR3Obj *	obj,
		NxReal	x,
		NxReal	y,
		NxReal	z
	)

Checks if a point is inside the object's bounding box.

When using physically simulated objects, all transformation-related functions available in VR3Obj become useless during simulation. All those functions operate on initial transformations of the object before the beginning of the simulation. This is done to encapsulate all physical simulation related functionalities in this single simulator object (an object of type VR3PhysicsSimulator). Because of this, we must provide a new function the user may call in order to figure out if a point belongs to the bounding box of the physically simulated object. This function works as VR3Obj::PointInBBox() in case of simulation.

Parameters:

[in]	obj	The target object
[in]	x,y,z	Position of the point in the world space

Returns:: true if the point is inside the bbox, false otherways

void VR3PhysicsSimulator::ObjRestore ( )

Resets the object position and orientation.

This function is used to restore initial settings for position and orientation of an object. The position and rotation restored is the one the object had just after the PrepareSimulation() call. This may be thought as a transformation just like the other movement calls and it may be part of a ObjBeginMove()...ObjEndMove() block.

void VR3PhysicsSimulator::ObjRotate	(	NxReal	ax,
		NxReal	ay,
		NxReal	az
	)

Rotates the object around its center.

This function is used to rotate the object around the center of its bounding box. This will be used in practice to change the object orientation without moving it. The rotation is expressed using three angles that are combined using the Yaw Pitch Roll convention (first ax degrees around the global axis X, then ay degrees around the global axis Y and then az degrees around the global axis Z).

Parameters:

[in] ax,ay,az Rotation angles in degrees

void VR3PhysicsSimulator::ObjRotate	(	NxReal	cx,
		NxReal	cy,
		NxReal	cz,
		NxReal	ax,
		NxReal	ay,
		NxReal	az
	)

Rotates the object around a given point.

This function is used to rotate the object around a given rotation center. The rotation is expressed using three angles that are combined using the Yaw Pitch Roll convention (first ax degrees around the global axis X, then ay degrees around the global axis Y and then az degrees around the global axis Z).

Parameters:

[in]	cx,cy,cz	The center coordinates
[in]	ax,ay,az	Rotation angles in degrees

void VR3PhysicsSimulator::ObjSetAngularDamping	(	const VR3Obj *	obj,
		NxReal	adamping
	)

Sets the angular damping for the object.

The angular damping is what tends to reduce the angular velocity of an object in absence of any other factor. By default there is an angular damping of 0.05, but the user may change it if necessary. The object must be dynamic. By default the angular damping is thought as measured in N*m*s, that is, a viscous angular damping coefficient.

Parameters:

[in]	obj	The target object
[in]	adamping	The new angular damping

void VR3PhysicsSimulator::ObjSetAngularVelocity	(	const VR3Obj *	obj,
		NxReal	dx,
		NxReal	dy,
		NxReal	dz,
		NxReal	avel
	)

Sets the linear velocity of the object.

This function is used to set the angular velocity of the object independently to all forces acting on it. If the user continuously sets the angular velocity, some forces acting on the object will not have any effect. This function should be called only on dynamic objects. The desired velocity will not always be obtained because during simulation other effects are taken into account. Because the provided direction will not be normalized in this function, the caller may use vector components directly with a magnitude of 1.0.

Parameters:

[in]	obj	The target object
[in]	dx,dy,dz	velocity direction components
[in]	avel	The new velocity

void VR3PhysicsSimulator::ObjSetBounciness	(	const VR3Obj *	obj,
		NxReal	bou
	)

Sets the bounciness of the given object.

The bounciness parameter read from the mesh file is lost.

Parameters:

[in]	obj	The target object
[in]	bou	The new bounciness coefficient

void VR3PhysicsSimulator::ObjSetDynamicFriction	(	const VR3Obj *	obj,
		NxReal	dfri
	)

Sets the dynamic friction of the given object.

The dynamic friction parameter read from the mesh file is lost.

Parameters:

[in]	obj	The target object
[in]	dfri	The new dynamic friction

void VR3PhysicsSimulator::ObjSetLinearDamping	(	const VR3Obj *	obj,
		NxReal	damping
	)

Sets the linear damping for the object.

The linear damping is what tends to reduce the linear velocity of an object in absence of any other factor. By default there is no linear damping, but the user may add it if necessary. The object must be dynamic. By default the linear damping is thought as measured in N*s/m, that is, a viscous damping coefficient.

Parameters:

[in]	obj	The target object
[in]	damping	The new linear damping

void VR3PhysicsSimulator::ObjSetLinearVelocity	(	const VR3Obj *	obj,
		NxReal	dx,
		NxReal	dy,
		NxReal	dz,
		NxReal	vel
	)

Sets the linear velocity of the object.

This function is used to set the velocity of the object independently to all forces acting on it. If the user continuously sets the velocity, some forces acting on the object may not have any effect. This function should be called only on dynamic objects. The desired velocity will not always be obtained because during simulation other effects are taken into account. Because the provided direction will not be normalized in this function, the caller may use vector components directly with a magnitude of 1.0.

Parameters:

[in]	obj	The target object
[in]	dx,dy,dz	velocity direction components
[in]	vel	The new velocity

void VR3PhysicsSimulator::ObjSetMass	(	const VR3Obj *	obj,
		NxReal	mass
	)

Sets the mass of the given object.

These functions may be called only after the simulation has been successfully prepared. The mass parameter read from the mesh file is lost and the new mass is distributed on the object body depending on the shapes attached to id. This function should be called only on dynamic objects.

Parameters:

[in]	obj	The target object
[in]	mass	The new mass

void VR3PhysicsSimulator::ObjSetMaxAngularVelocity	(	const VR3Obj *	obj,
		NxReal	maxavel
	)

Sets the maximum angular velocity for the object.

By default the maximum angular velocity is limited to 7 rad/s, to increase this limit, the user may change it for each particular actor. The object must be non-static.

Parameters:

[in]	obj	The target object
[in]	maxavel	The new maximum angular velocity

void VR3PhysicsSimulator::ObjSetSkinWidth	(	const VR3Obj *	obj,
		NxReal	swidth = `-1.0f`
	)

Sets the skin width used for simulation of the given object.

The skin width is a fundamental parameter in PhysX simulation, it affects simulation stability and realism. The default the skin width is computed using the bounding box size as a clue: the bigger the object, the higher the skin width. The default skin width will usually result in realistic and stable simulations, but the user may want to change it depending on the situation. The skin width value represents the amount of permitted inter penetration between objects, two objects will interpenetrate by the sum of their skin widths. If a negative value is provided as swidth, the default value will be restored based on the bounding box. A very small skin width value should be avoided because it may lead to simulation instability.

Parameters:

[in]	obj	The target object
[in]	swidth	The new skin width

void VR3PhysicsSimulator::ObjSetStaticFriction	(	const VR3Obj *	obj,
		NxReal	sfri
	)

Sets the static friction of the given object.

The static friction parameter read from the mesh file is lost.

Parameters:

[in]	obj	The target object
[in]	sfri	The new static friction

void VR3PhysicsSimulator::ObjTranslate	(	NxReal	x,
		NxReal	y,
		NxReal	z
	)

Translates the object with the given vector.

This function simply translates the object, making it move. The translation is performed in a single simulation cycle (if possible) and if results in a very high speed, collisions may pass undetected. It is recommended to call this function with small displacement vectors.

Parameters:

[in] x,y,z Translation vector component

VR3PhysicsSimulator& VR3PhysicsSimulator::operator= ( const VR3PhysicsSimulator & ) [private]

Disable default assignment operator.

void VR3PhysicsSimulator::PrepareSimulation ( )

Prepares the simulation.

This function must be called after all desired objects have been registered with the simulator, it will get the simulator ready for simulation. It procedes in two (simultaneous) steps:

The registered objects are moved in the simulating fast-access objects map
For each of those objects, the convex mesh compound or triangle mesh is cooked from the data in the corresponding VR3PhyMesh object (newly loaded if not already available). An actor is then created for each object.

This function will fail with error if the simulator is already in the prepared state. Usually this function will be called just once at the end of the application initialization. It is very time-consuming. The simulating objects map (from where the simulation results are extracted) will not change until a new PrepareSimulation() call.

void VR3PhysicsSimulator::ResetSimulation ( )

Resets the simulation.

This method is used to reset all objects to their original position and orientation stored during the PrepareSimulation() call. All resources acquired during the simulation preparation are retained.

void VR3PhysicsSimulator::ResetTimer ( )

Resets the timer.

To accomplish physics simulation, a high-resolution timer is needed in order to set the time to simulate from frame to frame. This function is used to reset the high-resolution timer.

void VR3PhysicsSimulator::SetGravity	(	NxReal	gx,
		NxReal	gy,
		NxReal	gz
	)

Sets the new gravity vector (default is (0.0,-9.81,0.0))

This function is used to obtain a different gravity direction and intensity from the default one.

void VR3PhysicsSimulator::SimulateObject	(	const VR3Obj *	obj,
		bool	simulate
	)

Registers a new object (user-called)

This function is directly called by the user when working with a manual physics simulator. An error will arise if this function is called on an automatic physics simulator. If the simulate input parameter is true the object is registered for simulation, if false the object is deregistered for simulation.

Parameters:

[in]	obj	The object we have to register or deregister
[in]	simulate	true if the object is to be registered, false otherways

void VR3PhysicsSimulator::StartSimulation ( )

Starts the simulation.

After PrepareSimulation() has been called, simulation is ready to start and this method is used for that purpose. If the start simulation method is called on a non-prepared physics simulator, a PrepareSimulation() call will be issued.