---

McdDtBridge.h File Reference

The Mcd integration to the MathEngine Dynamics Toolkit. More...

#include "McdFrame.h"
#include "Mdt.h"

Typedefs
typedef struct _McdDtBridge	McdDtBridge
	Handles communication between the Mcd and Mdt packages. More...
typedef McdDtBridge*	McdDtBridgeID
	References to MathEngine objects are made using "ID" tokens instead of explicit pointers.
typedef unsigned int (*	McdDtBridgeContactCB )(MdtContactID, McdContact *, McdIntersectResult *)
	Contact callback function signature. More...
typedef void (*	McdDtBridgeActiveTouchCB )(McdModelPair *pair, McdIntersectResult*result, MdtContactID*firstContactPointer)
	Colliding model callback for moving models. More...
typedef void (*	McdDtBridgeInactiveTouchCB )(McdModelPair *, MdtContactID*)
	Colliding model callback for models that are not moving. More...
Functions
void	McdDtBridgeInit ( int materialIDMaxCount )
	Initialises the McdDtBridge component. More...
void	McdDtBridgeTerm ( )
	Shuts down the McdDtBridge component. More...
void	McdDtBridgeReallocateContactProperties ( )
	Re-allocate the contact property table. More...
McdDtBridgeID	McdDtBridgeCreate ( )
	Create an McdDtBridge object. More...
void	McdDtBridgeDestroy ( McdDtBridgeID h )
	Puts the McdDtBridge back in its pool.
unsigned int	McdDtBridgeSetPairListMaxCount ( McdDtBridgeID h, int count )
	Sets the size of an internal buffer to the maximum number of McdModel pairs to be handled at one time, including new, current, and old nearby pairs. More...
int	McdDtBridgeGetPairListMaxCount ( McdDtBridgeID h )
	Returns the size of the internal buffer of McdModel pairs.
void	McdDtBridgeSetContactCB ( int materialID1, int materialID2, McdDtBridgeContactCB cb )
	Sets the callback function to be called whenever objects of the specified material IDs collide. More...
McdDtBridgeContactCB	McdDtBridgeGetContactCB ( int materialID1, int materialID2 )
	Returns the contact callback corresponding to the pair of material IDs.
void	McdDtBridgeSetBody ( McdDtBridgeID h, McdModelID cm, MdtBodyID b )
	Associates body b with collision model cm. More...
MdtBodyID	McdDtBridgeGetBody ( McdModelID cm )
	Returns the physical body associated with a collision model.
int	McdDtBridgeGetResponseID ( McdDtBridgeID h )
	Returns the ResponseID associated with Kea bodies in this instance of the bridge.
void	McdDtBridgeSetRelativeTransformToBodyPtr ( McdModelID cm, MeMatrix4 relativeTM, MeMatrix4 compoundTM )
	Defines a transform "offset" between the coordinate system of cm and that of its associated MdtBody. More...
MeMatrix4*	McdDtBridgeGetRelativeTransformToBodyPtr ( McdModelID cm )
	Returns a pointer to the relative transform set in McdDtBridgeSetRelativeTransformToBodyPtr. More...
void	McdDtBridgeUpdateModelTransformFromBody ( McdDtBridgeID, McdModelID )
	Called every time a model is updated (or a space containing a model), but it can also be explicitly called by the user. More...
void	McdDtBridgeUpdateBodyTransformFromModel ( McdDtBridgeID, McdModelID )
	Updates the transform of the MdtBody associated with cm. More...
int	McdDtBridgeGetUsedContactsCount ( McdDtBridgeID h )
	Returns the number of physical contacts currently in use.
void	McdDtBridgeUpdateAllFreezeFlags ( McdSpaceID space )
	freezes-in-space all McdModels in space, based on the IsAlive() property of the corresponding MdtBody.
void	McdDtBridgeSetActiveTouchCB ( int materialID1, int materialID2, McdDtBridgeActiveTouchCB cb )
	This contact will be called on a pairwise, rather than contactwise, basis for pairs involving a moving McdModel.
McdDtBridgeActiveTouchCB	McdDtBridgeGetActiveTouchCB ( int materialID1, int materialID2 )
	See McdDtBridgeSetActiveTouchCB.
void	McdDtBridgeSetInactiveTouchCB ( int materialID1, int materialID2, McdDtBridgeInactiveTouchCB cb )
	This contact will be called on a pairwise, rather than contactwise, basis for McdModels at rest.
McdDtBridgeInactiveTouchCB	McdDtBridgeGetInactiveTouchCB ( int materialID1, int materialID2 )
	See McdDtBridgeSetInactiveTouchCB.
void	McdDtBridgeSetMaterialID ( McdModelID cm, int materialID )
	Sets the Material which is used to determine the contact parameters (such as physical contact info) between this model and another of a given material ID.
int	McdDtBridgeGetMaterialID ( McdModelID cm )
	Returns the Material ID of a model.
int	McdDtBridgeGetNewMaterialID ()
	Returns a new material ID.
int	McdDtBridgeGetDefaultMaterialID ()
	This is the material ID assigned to objects upon their creation.
int	McdDtBridgeGetMaterialIDMaxCount ()
	Returns present material ID max count.
void	McdDtBridgeSetContactParams ( int materialID1, int materialID2, MdtBclContactParams *params )
	Copies the data pointed to by params into a table keyed on materialID, to be copied into the generated MdtContact objects.
MdtBclContactParams*	McdDtBridgeGetContactParams ( int materialID1, int materialID2 )
	Returns a pointer to the data structure corresponding to the pair of material IDs. More...

---

Detailed Description

The Mcd integration to the MathEngine Dynamics Toolkit.

---

Typedef Documentation

typedef struct _McdDtBridge McdDtBridge

Handles communication between the Mcd and Mdt packages.

McdModel objects are associated with MdtBody objects via McdDtBridgeSetBody. When the McdDtBridge receives a list of McdModelPair's representing potential or actual collisions, it generates MdtContact objects so that appropriate collision response occurs in the next call to MdtWorldStep. A callback provides users with a means of modifying the generated MdtContact objects before they are used.

The McdDtBridge also updates the McdModel transforms according to the motion of the associated MdtBody's.

If both associated MdtBody's are disabled ( as determined by MdtBodyIsEnabled), or if one MdtBody is disabled and the other's McdModel is frozen ( as determined by McdModelIsFrozenInSpace ), then an important optimization takes place, in which MdtContact's generated in the previous time step can be re-used without further computation.

If only one of the two McdModel's in the McdModelPair are associated with a MdtBody, a "one-sided" MdtContact is generated ( one of the MdtBody fields is set to NULL). Note that in this case the McdModel that is not associated with an MdtBody will not benefit from the automatic "disabled" status detection: If this McdModel is in a non-moving state, you must inform the system manually by using McdModelFreezeInSpace. This is typical of static "environment" models such as terrains, for which there is usually no associated MdtBody.

See also:

McdDtBridgeSetBody() McdBodyFreezeInSpace MdtBodyIsEnabled

typedef void (* McdDtBridgeActiveTouchCB)(McdModelPair *pair, McdIntersectResult*result, MdtContactID*firstContactPointer)

Colliding model callback for moving models.

The user may specify a callback of the above signature, to modify physical contacts before physics has a chance to use them. The specified function gets called for each colliding pair of which at least one body is considered moving (either not Frozen or with a correcponding MdtBody that is enabled). The first parameter identifies the pair of intersecting models. The second is the geometric contact data which was used to generate the physical contact associated with this pair of McdModels. The last parameter is a pointer to the MdtContactID of the first MdtContact forming the list of physical contacts. Use MdtContactGetNext to walk through the list. MdtContacts can be disabled. They can also be destroyed provided that the remaining contacts still form a linked list.

typedef unsigned int (* McdDtBridgeContactCB)(MdtContactID, McdContact *, McdIntersectResult *)

Contact callback function signature.

This callback is deprecated. Use McdDtBridgeActiveTouchCB instead. The user may specify a callback of the above signature, to modify physical contacts before physics has a chance to use them. The first parameter is the physical contact, the second is the geometric contact data which was used to generate the physical contact. The third parameter identifies the pair of intersecting models. If the return value is 0, the contact will not be generated. This function is obsoleted by McdDtBridgeActiveTouchCB.

typedef void (* McdDtBridgeInactiveTouchCB)(McdModelPair *, MdtContactID*)

Colliding model callback for models that are not moving.

The user may specify a callback of the above signature, to inspect physical contacts associated with a pair of McdModels at rest. The specified function gets called whenever the function the McdDtBridgeActiveTouch callback would not be called. The first parameter identifies the pair of intersecting models. The second parameter is a pointer to the MdtContactID of the first MdtContact forming the list of physical contacts. Use MdtContactGetNext to walk through the list. Modifying the contact list may cause undefined behaviour.

---

Function Documentation

McdDtBridgeID McdDtBridgeCreate ( )

Create an McdDtBridge object.

• contactPoolSize: Size of the pool of MdtContact objects used by the McdDtBridge contact generation.

Creates a new response module and activates automatic MdtContact generation for Models on which McdDtBridgeSetBody has been called.

• materialIDMaxCount: number of materialIDs that will be used by the bridge.

If a model with an associated body comes in contact with a model without a body, a one-sided MdtContact is generated (one with one body set to NULL). The bridge looks at whether the body is enabled (MdtBodyIsEnabled) and whether the model is frozen in space (McdBodyFreezeInSpace) to determine if the corresponding object is moving. If one of these is true for two objects in contact, new contacts will not be generated and ones from the previous timestep reused for efficiency. For models with no bodies attached, only the frozen status is checked. Therefore it will be much more efficient if static objects such as terrains which do not need associated bodies are set as frozen by calling McdBodyFreezeInSpace.

See also:

McdDtBridgeSetBody() McdBodyFreezeInSpace MdtBodyIsEnabled

MdtBclContactParams * McdDtBridgeGetContactParams ( int materialID1, int materialID2 )

Returns a pointer to the data structure corresponding to the pair of material IDs.

Values in this structure are set in McdDtBridgeSetContactParams.

MeMatrix4 * McdDtBridgeGetRelativeTransformToBodyPtr ( McdModelID cm )

Returns a pointer to the relative transform set in McdDtBridgeSetRelativeTransformToBodyPtr.

See also:

McdDtBridgeSetRelativeTransformToBodyPtr() , McdModelGetTransformPtr()

void McdDtBridgeInit ( int materialIDMaxCount )

Initialises the McdDtBridge component.

Must be called before using any other McdDtBridge calls.

• materialIDMaxCount sets the size of the material table used by all McdDtBridge instances.

void McdDtBridgeReallocateContactProperties ( )

Re-allocate the contact property table.

Upon initialization with McdDtBridgeInit(), a contact property table is allocated to match the present number of materials in the Mcd framework. If you allocate more material IDs in the framework AFTER McdDtBridgeInit(), then you must call this function to re-allocate the table. Allocates memory.

void McdDtBridgeSetBody ( McdDtBridgeID h, McdModelID cm, MdtBodyID b )

Associates body b with collision model cm.

More than one collision model may be associated with a body. Sets the transformation matrix pointer of the model equal to the b's transformation matrix.

void McdDtBridgeSetContactCB ( int materialID1, int materialID2, McdDtBridgeContactCB cb )

Sets the callback function to be called whenever objects of the specified material IDs collide.

Can be null. Callback may modify contact data, and the contact is eliminated completely if the callback returns 0.

unsigned int McdDtBridgeSetPairListMaxCount ( McdDtBridgeID h, int count )

Sets the size of an internal buffer to the maximum number of McdModel pairs to be handled at one time, including new, current, and old nearby pairs.

Setting this to a small number will not cause any pairs to be lost but may cause a small performance penalty.

void McdDtBridgeSetRelativeTransformToBodyPtr ( McdModelID cm, MeMatrix4 relativeTM, MeMatrix4 compoundTM )

Defines a transform "offset" between the coordinate system of cm and that of its associated MdtBody.

By default ( if this call is not used) the McdModel shares the associated MdtBody's coordinate system, having no distinct transform pointer of its own. To define an offset between the two requires both the allocation of relativeTM, a relative transform describing the offset value, and compoundTM, the allocation of a distinct transform for the McdModel itself.

Each time step, the associated MdtBody's transform is compounded by relativeTM, and the result is written to compoundTM. If relativeTM is NULL, then no compounding occurs.

Parameters:

relativeTM	: the relative transform between the two coordinate systems. Allocated by user.
compoundTM	: The transform representing the "final value" of the McdModel's coordinate system. Subsequent calls to McdModelGetTransformPtr(..) now return compoundTM. Allocated by user.

See also:

McdModelGetTransformPtr()

void McdDtBridgeTerm ( )

Shuts down the McdDtBridge component.

Any McdDtBridge calls made after this point result in undefined behaviour.

void McdDtBridgeUpdateBodyTransformFromModel ( McdDtBridgeID b, McdModelID cm )

Updates the transform of the MdtBody associated with cm.

Takes into account any possible relative transform set in McdDtBridgeSetRelativeTransformToBodyPtr().

void McdDtBridgeUpdateModelTransformFromBody ( McdDtBridgeID b, McdModelID cm )

Called every time a model is updated (or a space containing a model), but it can also be explicitly called by the user.

It performs the transform concatenation described in McdDtBridgeSetRelativeTransformToBodyPtr().

See also:

McdDtBridgeSetRelativeTransformToBodyPtr()

---