DigitalSpaces::DIPhysicsWorld Struct Reference
[Physics]

#include <Physics_World.h>

Inherits DigitalSpaces::DIObjectBase.

---

Detailed Description

Interface for a phyiscs world.

A physics world can be considered a collection of bodies, shapes and joints that can interact with each other. Objects from different worlds cannot interact with each other. For this reason, most simulations will just use a single world.

Public Member Functions
DIPhysicsBody *	CreateBody (const char *sBodyName, const char *sVisualDescription)
	Create a physics body.
DIPhysicsShape *	CreateShape (const char *sShapeName, const char *sBodyName)
	Create a physics shape.
DIPhysicsJoint *	CreateJoint (const char *sJointName, const char *sBodyName, const char *sOtherBodyName)
	Create a physics joint.
DIPhysicsBody *	FindBody (const char *sBodyName)
	Look up a physics body by name.
DIPhysicsShape *	FindShape (const char *sShapeName)
	Look up a physics shape by name.
DIPhysicsJoint *	FindJoint (const char *sJointName)
	Look up a physics joint by name.
void	DestroyBody (const char *sBodyName)
	Destroy the specified physics body.
void	DestroyShape (const char *sShapeName)
	Destroy the specified physics shape.
void	DestroyJoint (const char *sJointName)
	Destroy the specified physics joint.
void	ForEachBodyDo (DIPhysicsBodyIterator *iterator)
	Call the provided DIPhysicsBodyIterator's ProcessBody function, passing it each DIPhysicsBody.
void	SetCollisionNotify (DIPhysicsShape *shape, DIPhysicsShape *other_shape, bool enabled)
	It suggests that this function was designed to allow overriding the default interaction between two shapes, beyond the behaviour of DIPhysicsShape::SetGroup.
void	AdvanceTime (float fDelta)
	Advance the physics simulation model.
void	SetGroupCollision (unsigned char group, unsigned char other_group, bool enable)
	Control the creation of a collision when shapes from two different groups intersect.
void	GetAllBodyNames (DIStringList1 *names)
	Provide the names of all the created physics bodies.
void	GetAllShapeNames (DIStringList1 *names)
	Provide the names of all the created physics shapes.
void	GetAllJointNames (DIStringList1 *names)
	Provide the names of all the created physics joints.

---

Member Function Documentation

DIPhysicsBody* DigitalSpaces::DIPhysicsWorld::CreateBody	(	const char *	sBodyName,
		const char *	sVisualDescription
	)

Create a physics body.

The physics body will still need to be properly initialized using DIPhysicsBase::BeginSetup and DIPhysicsBase::EndSetup. This should be done immediately.

Note:

In the current implementation, if this is not done within the Heartbeat, a crash may occur.

Parameters:

sBodyName

Unique name to identify the body by. sVisualDescription This parameter is from an old implementation design, and while it is stored by the current implementation, it is not ever used. We recommend passing "". Note: IN the current implementation, passing NULL will cause a crash.

Returns:

Interface to the created body, or NULL if the body name was not unique.

DIPhysicsShape* DigitalSpaces::DIPhysicsWorld::CreateShape	(	const char *	sShapeName,
		const char *	sBodyName
	)

Create a physics shape.

The physics shape will still need to be properly initialized using DIPhysicsBase::BeginSetup and DIPhysicsBase::EndSetup. This should be done immediately.

Note:

In the current implementation, if this is not done within the Heartbeat, a crash may occur.

Parameters:

	sShapeName	Unique name to identify the shape by.
	sBodyName	The name of a body to attach this shape to. This body needs to have been previously created (by CreateBody). If the shape should not be attached to any body (and thus will not be movable), then pass NULL. If the name does not match the name of a created body, the shape will not be attached to any body, as if NULL had been passed.

Returns:

Interface to the created shape, or NULL if the shape name was not unique.

DIPhysicsJoint* DigitalSpaces::DIPhysicsWorld::CreateJoint	(	const char *	sJointName,
		const char *	sBodyName,
		const char *	sOtherBodyName
	)

Create a physics joint.

The physics joint will still need to be properly initialized using DIPhysicsBase::BeginSetup and DIPhysicsBase::EndSetup. This should be done immediately.

Note:

In the current implementation, if this is not done within the Heartbeat, a crash may occur.

Parameters:

	sJointName	Unique name to identify the joint by
	sBodyName	The name of a body to attach with this joint, or NULL if no body is required. If there is no body by this name, the result will be as if this was called with NULL.
	sOtherBodyName	The name of a body to attach with this joint, or NULL if no body is required. If there is no body by this name, the result will be as if this was called with NULL.

If you wish to create a joint that joins a body with a fixed point in space, use the name of the body for sBodyName, and NULL for sOtherBodyName.

DIPhysicsBody* DigitalSpaces::DIPhysicsWorld::FindBody

(

const char *

sBodyName

)

Look up a physics body by name.

Parameters:

sBodyName

The name associated with the physics body.

Returns:

Interface to the specified body, or NULL if not found.

DIPhysicsShape* DigitalSpaces::DIPhysicsWorld::FindShape

(

const char *

sShapeName

)

Look up a physics shape by name.

Parameters:

sBodyName

The name associated with the physics shape.

Returns:

Interface to the specified shape, or NULL if not found.

DIPhysicsJoint* DigitalSpaces::DIPhysicsWorld::FindJoint

(

const char *

sJointName

)

Look up a physics joint by name.

Parameters:

sBodyName

The name associated with the physics joint.

Returns:

Interface to the specified joint, or NULL if not found.

void DigitalSpaces::DIPhysicsWorld::DestroyBody

(

const char *

sBodyName

)

Destroy the specified physics body.

This is dangerous, as destroying a physics body invalidates any existing interfaces to it, but this cannot be tested for. Therefor if any implementation tries to access the destroyed body using a previously supplied interface, a crash will occur. Therefore you should only ever destroy a body you are sure is not used elsewhere. For example, if the physics body was created using the SceneGraph system, then destroying the body will cause a crash when the Scene Graph system attempts to access the body.

Parameters:

sBodyName

The name associated with the body you wish to destroy.

void DigitalSpaces::DIPhysicsWorld::DestroyShape

(

const char *

sShapeName

)

Destroy the specified physics shape.

This is dangerous, as destroying a physics shape invalidates any existing interfaces to it, but this cannot be tested for. Therefor if any implementation tries to access the destroyed shape using a previously supplied interface, a crash will occur. Therefore you should only ever destroy a shape you are sure is not used elsewhere. For example, if the physics shape was created using the SceneGraph system, then destroying the shape will cause a crash when the Scene Graph system attempts to access the shape.

Parameters:

sShapeName

The name associated with the shape you wish to destroy.

void DigitalSpaces::DIPhysicsWorld::DestroyJoint

(

const char *

sJointName

)

Destroy the specified physics joint.

This is dangerous, as destroying a physics joint invalidates any existing interfaces to it, but this cannot be tested for. Therefor if any implementation tries to access the destroyed joint using a previously supplied interface, a crash will occur. Therefore you should only ever destroy a joint you are sure is not used elsewhere. For example, if the physics joint was created using the SceneGraph system, then destroying the joint will cause a crash when the Scene Graph system attempts to access the joint.

Parameters:

sJointName

The name associated with the joint you wish to destroy.

void DigitalSpaces::DIPhysicsWorld::ForEachBodyDo

(

DIPhysicsBodyIterator *

iterator

)

Call the provided DIPhysicsBodyIterator's ProcessBody function, passing it each DIPhysicsBody.

Deprecated:

This was added for a particular pupose that is no longer required, and doesn't add useful functionality. Use GetAllBodyNames and FindBody instead.

void DigitalSpaces::DIPhysicsWorld::SetCollisionNotify	(	DIPhysicsShape *	shape,
		DIPhysicsShape *	other_shape,
		bool	enabled
	)

It suggests that this function was designed to allow overriding the default interaction between two shapes, beyond the behaviour of DIPhysicsShape::SetGroup.

Deprecated:

The reference implementation does nothing.

void DigitalSpaces::DIPhysicsWorld::AdvanceTime

(

float

fDelta

)

Advance the physics simulation model.

This should only be called by the Physics component implementation, from PerformHeartbeat. Calling it elsewhere will result in the physics simulation time not matching system time, and will prevent components from monitoring/controlling the physics simulation consistantly.

void DigitalSpaces::DIPhysicsWorld::SetGroupCollision	(	unsigned char	group,
		unsigned char	other_group,
		bool	enable
	)

Control the creation of a collision when shapes from two different groups intersect.

Parameters:

	group	Group identifier, from 0 to 31
	outer_group	Group identifier, from 0 to 31
	enable	Sets if collisions should be created or not

See also:

DIPhysicsShape::SetGroup

void DigitalSpaces::DIPhysicsWorld::GetAllBodyNames

(

DIStringList1 *

names

)

Provide the names of all the created physics bodies.

Parameters:

[out]

names

String List that will have the names of the created physics bodies appended to it. The List will not be cleared by the function.

void DigitalSpaces::DIPhysicsWorld::GetAllShapeNames

(

DIStringList1 *

names

)

Provide the names of all the created physics shapes.

Parameters:

[out]

names

String List that will have the names of the created physics shapes appended to it. The List will not be cleared by the function.

void DigitalSpaces::DIPhysicsWorld::GetAllJointNames

(

DIStringList1 *

names

)

Provide the names of all the created physics joints.

Parameters:

[out]

names

String List that will have the names of the created physics joints appended to it. The List will not be cleared by the function.

---

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

• PhysicsInterfaces/Physics_World.h