ODE  0.13.1
 All Data Structures Functions Variables Typedefs Enumerations Groups
Collision Detection

Modules

 Sphere Class
 
 Box Class
 

Data Structures

struct  dContactGeom
 Describe the contact point between two geoms. More...
 

Typedefs

typedef dReal dHeightfieldGetHeight (void *p_user_data, int x, int z)
 Callback prototype. More...
 
typedef void dNearCallback (void *data, dGeomID o1, dGeomID o2)
 User callback for geom-geom collision testing. More...
 
typedef struct dContactGeom dContactGeom
 Describe the contact point between two geoms. More...
 

Functions

void dGeomDestroy (dGeomID geom)
 Destroy a geom, removing it from any space. More...
 
void dGeomSetData (dGeomID geom, void *data)
 Set the user-defined data pointer stored in the geom. More...
 
void * dGeomGetData (dGeomID geom)
 Get the user-defined data pointer stored in the geom. More...
 
void dGeomSetBody (dGeomID geom, dBodyID body)
 Set the body associated with a placeable geom. More...
 
dBodyID dGeomGetBody (dGeomID geom)
 Get the body associated with a placeable geom. More...
 
void dGeomSetPosition (dGeomID geom, dReal x, dReal y, dReal z)
 Set the position vector of a placeable geom. More...
 
void dGeomSetRotation (dGeomID geom, const dMatrix3 R)
 Set the rotation matrix of a placeable geom. More...
 
void dGeomSetQuaternion (dGeomID geom, const dQuaternion Q)
 Set the rotation of a placeable geom. More...
 
const dReal * dGeomGetPosition (dGeomID geom)
 Get the position vector of a placeable geom. More...
 
void dGeomCopyPosition (dGeomID geom, dVector3 pos)
 Copy the position of a geom into a vector. More...
 
const dReal * dGeomGetRotation (dGeomID geom)
 Get the rotation matrix of a placeable geom. More...
 
void dGeomCopyRotation (dGeomID geom, dMatrix3 R)
 Get the rotation matrix of a placeable geom. More...
 
void dGeomGetQuaternion (dGeomID geom, dQuaternion result)
 Get the rotation quaternion of a placeable geom. More...
 
void dGeomGetAABB (dGeomID geom, dReal aabb[6])
 Return the axis-aligned bounding box. More...
 
int dGeomIsSpace (dGeomID geom)
 Determing if a geom is a space. More...
 
dSpaceID dGeomGetSpace (dGeomID)
 Query for the space containing a particular geom. More...
 
int dGeomGetClass (dGeomID geom)
 Given a geom, this returns its class. More...
 
void dGeomSetCategoryBits (dGeomID geom, unsigned long bits)
 Set the "category" bitfield for the given geom. More...
 
void dGeomSetCollideBits (dGeomID geom, unsigned long bits)
 Set the "collide" bitfield for the given geom. More...
 
unsigned long dGeomGetCategoryBits (dGeomID)
 Get the "category" bitfield for the given geom. More...
 
unsigned long dGeomGetCollideBits (dGeomID)
 Get the "collide" bitfield for the given geom. More...
 
void dGeomEnable (dGeomID geom)
 Enable a geom. More...
 
void dGeomDisable (dGeomID geom)
 Disable a geom. More...
 
int dGeomIsEnabled (dGeomID geom)
 Check to see if a geom is enabled. More...
 
int dGeomLowLevelControl (dGeomID geom, int controlClass, int controlCode, void *dataValue, int *dataSize)
 Execute low level control operation for geometry. More...
 
void dGeomGetRelPointPos (dGeomID geom, dReal px, dReal py, dReal pz, dVector3 result)
 Get world position of a relative point on geom. More...
 
void dGeomGetPosRelPoint (dGeomID geom, dReal px, dReal py, dReal pz, dVector3 result)
 takes a point in global coordinates and returns the point's position in geom-relative coordinates. More...
 
void dGeomVectorToWorld (dGeomID geom, dReal px, dReal py, dReal pz, dVector3 result)
 Convert from geom-local to world coordinates. More...
 
void dGeomVectorFromWorld (dGeomID geom, dReal px, dReal py, dReal pz, dVector3 result)
 Convert from world to geom-local coordinates. More...
 
void dGeomSetOffsetPosition (dGeomID geom, dReal x, dReal y, dReal z)
 Set the local offset position of a geom from its body. More...
 
void dGeomSetOffsetRotation (dGeomID geom, const dMatrix3 R)
 Set the local offset rotation matrix of a geom from its body. More...
 
void dGeomSetOffsetQuaternion (dGeomID geom, const dQuaternion Q)
 Set the local offset rotation of a geom from its body. More...
 
void dGeomSetOffsetWorldPosition (dGeomID geom, dReal x, dReal y, dReal z)
 Set the offset position of a geom from its body. More...
 
void dGeomSetOffsetWorldRotation (dGeomID geom, const dMatrix3 R)
 Set the offset rotation of a geom from its body. More...
 
void dGeomSetOffsetWorldQuaternion (dGeomID geom, const dQuaternion)
 Set the offset rotation of a geom from its body. More...
 
void dGeomClearOffset (dGeomID geom)
 Clear any offset from the geom. More...
 
int dGeomIsOffset (dGeomID geom)
 Check to see whether the geom has an offset. More...
 
const dReal * dGeomGetOffsetPosition (dGeomID geom)
 Get the offset position vector of a geom. More...
 
void dGeomCopyOffsetPosition (dGeomID geom, dVector3 pos)
 Copy the offset position vector of a geom. More...
 
const dReal * dGeomGetOffsetRotation (dGeomID geom)
 Get the offset rotation matrix of a geom. More...
 
void dGeomCopyOffsetRotation (dGeomID geom, dMatrix3 R)
 Copy the offset rotation matrix of a geom. More...
 
void dGeomGetOffsetQuaternion (dGeomID geom, dQuaternion result)
 Get the offset rotation quaternion of a geom. More...
 
int dCollide (dGeomID o1, dGeomID o2, int flags, dContactGeom *contact, int skip)
 Given two geoms o1 and o2 that potentially intersect, generate contact information for them. More...
 
void dSpaceCollide (dSpaceID space, void *data, dNearCallback *callback)
 Determines which pairs of geoms in a space may potentially intersect, and calls the callback function for each candidate pair. More...
 
void dSpaceCollide2 (dGeomID space1, dGeomID space2, void *data, dNearCallback *callback)
 Determines which geoms from one space may potentially intersect with geoms from another space, and calls the callback function for each candidate pair. More...
 
dGeomID dCreateHeightfield (dSpaceID space, dHeightfieldDataID data, int bPlaceable)
 Creates a heightfield geom. More...
 
dHeightfieldDataID dGeomHeightfieldDataCreate (void)
 Creates a new empty dHeightfieldDataID. More...
 
void dGeomHeightfieldDataDestroy (dHeightfieldDataID d)
 Destroys a dHeightfieldDataID. More...
 
void dGeomHeightfieldDataBuildCallback (dHeightfieldDataID d, void *pUserData, dHeightfieldGetHeight *pCallback, dReal width, dReal depth, int widthSamples, int depthSamples, dReal scale, dReal offset, dReal thickness, int bWrap)
 Configures a dHeightfieldDataID to use a callback to retrieve height data. More...
 
void dGeomHeightfieldDataBuildByte (dHeightfieldDataID d, const unsigned char *pHeightData, int bCopyHeightData, dReal width, dReal depth, int widthSamples, int depthSamples, dReal scale, dReal offset, dReal thickness, int bWrap)
 Configures a dHeightfieldDataID to use height data in byte format. More...
 
void dGeomHeightfieldDataBuildShort (dHeightfieldDataID d, const short *pHeightData, int bCopyHeightData, dReal width, dReal depth, int widthSamples, int depthSamples, dReal scale, dReal offset, dReal thickness, int bWrap)
 Configures a dHeightfieldDataID to use height data in short format. More...
 
void dGeomHeightfieldDataBuildSingle (dHeightfieldDataID d, const float *pHeightData, int bCopyHeightData, dReal width, dReal depth, int widthSamples, int depthSamples, dReal scale, dReal offset, dReal thickness, int bWrap)
 Configures a dHeightfieldDataID to use height data in single precision floating point format. More...
 
void dGeomHeightfieldDataBuildDouble (dHeightfieldDataID d, const double *pHeightData, int bCopyHeightData, dReal width, dReal depth, int widthSamples, int depthSamples, dReal scale, dReal offset, dReal thickness, int bWrap)
 Configures a dHeightfieldDataID to use height data in double precision floating point format. More...
 
void dGeomHeightfieldDataSetBounds (dHeightfieldDataID d, dReal minHeight, dReal maxHeight)
 Manually set the minimum and maximum height bounds. More...
 
void dGeomHeightfieldSetHeightfieldData (dGeomID g, dHeightfieldDataID d)
 Assigns a dHeightfieldDataID to a heightfield geom. More...
 
dHeightfieldDataID dGeomHeightfieldGetHeightfieldData (dGeomID g)
 Gets the dHeightfieldDataID bound to a heightfield geom. More...
 
void dSetColliderOverride (int i, int j, dColliderFn *fn)
 Sets a custom collider function for two geom classes. More...
 
void dSpaceSetSublevel (dSpaceID space, int sublevel)
 Sets sublevel value for a space. More...
 
int dSpaceGetSublevel (dSpaceID space)
 Gets sublevel value of a space. More...
 
void dSpaceSetManualCleanup (dSpaceID space, int mode)
 Sets manual cleanup flag for a space. More...
 
int dSpaceGetManualCleanup (dSpaceID space)
 Get manual cleanup flag of a space. More...
 
int dSpaceGetClass (dSpaceID space)
 Given a space, this returns its class. More...
 

Detailed Description

ODE has two main components: a dynamics simulation engine and a collision detection engine. The collision engine is given information about the shape of each body. At each time step it figures out which bodies touch each other and passes the resulting contact point information to the user. The user in turn creates contact joints between bodies.

Using ODE's collision detection is optional - an alternative collision detection system can be used as long as it can supply the right kinds of contact information.

Typedef Documentation

typedef struct dContactGeom dContactGeom

Describe the contact point between two geoms.

If two bodies touch, or if a body touches a static feature in its environment, the contact is represented by one or more "contact points", described by dContactGeom.

The convention is that if body 1 is moved along the normal vector by a distance depth (or equivalently if body 2 is moved the same distance in the opposite direction) then the contact depth will be reduced to zero. This means that the normal vector points "in" to body 1.

typedef dReal dHeightfieldGetHeight(void *p_user_data, int x, int z)

Callback prototype.

Used by the callback heightfield data type to sample a height for a given cell position.

Parameters
p_user_dataUser data specified when creating the dHeightfieldDataID
xThe index of a sample in the local x axis. It is a value in the range zero to ( nWidthSamples - 1 ).
xThe index of a sample in the local z axis. It is a value in the range zero to ( nDepthSamples - 1 ).
Returns
The sample height which is then scaled and offset using the values specified when the heightfield data was created.
typedef void dNearCallback(void *data, dGeomID o1, dGeomID o2)

User callback for geom-geom collision testing.

Parameters
dataThe user data object, as passed to dSpaceCollide.
o1The first geom being tested.
o2The second geom being test.
Remarks
The callback function can call dCollide on o1 and o2 to generate contact points between each pair. Then these contact points may be added to the simulation as contact joints. The user's callback function can of course chose not to call dCollide for any pair, e.g. if the user decides that those pairs should not interact.

Function Documentation

int dCollide ( dGeomID  o1,
dGeomID  o2,
int  flags,
dContactGeom contact,
int  skip 
)

Given two geoms o1 and o2 that potentially intersect, generate contact information for them.

Internally, this just calls the correct class-specific collision functions for o1 and o2.

Parameters
o1The first geom to test.
o2The second geom to test.
flagsThe flags specify how contacts should be generated if the geoms touch. The lower 16 bits of flags is an integer that specifies the maximum number of contact points to generate. You must ask for at least one contact. Additionally, following bits may be set: CONTACTS_UNIMPORTANT – just generate any contacts (skip contact refining). All other bits in flags must be set to zero. In the future the other bits may be used to select from different contact generation strategies.
contactPoints to an array of dContactGeom structures. The array must be able to hold at least the maximum number of contacts. These dContactGeom structures may be embedded within larger structures in the array – the skip parameter is the byte offset from one dContactGeom to the next in the array. If skip is sizeof(dContactGeom) then contact points to a normal (C-style) array. It is an error for skip to be smaller than sizeof(dContactGeom).
Returns
If the geoms intersect, this function returns the number of contact points generated (and updates the contact array), otherwise it returns 0 (and the contact array is not touched).
Remarks
If a space is passed as o1 or o2 then this function will collide all objects contained in o1 with all objects contained in o2, and return the resulting contact points. This method for colliding spaces with geoms (or spaces with spaces) provides no user control over the individual collisions. To get that control, use dSpaceCollide or dSpaceCollide2 instead.
If o1 and o2 are the same geom then this function will do nothing and return 0. Technically speaking an object intersects with itself, but it is not useful to find contact points in this case.
This function does not care if o1 and o2 are in the same space or not (or indeed if they are in any space at all).
dGeomID dCreateHeightfield ( dSpaceID  space,
dHeightfieldDataID  data,
int  bPlaceable 
)

Creates a heightfield geom.

Uses the information in the given dHeightfieldDataID to construct a geom representing a heightfield in a collision space.

Parameters
spaceThe space to add the geom to.
dataThe dHeightfieldDataID created by dGeomHeightfieldDataCreate and setup by dGeomHeightfieldDataBuildCallback, dGeomHeightfieldDataBuildByte, dGeomHeightfieldDataBuildShort or dGeomHeightfieldDataBuildFloat.
bPlaceableIf non-zero this geom can be transformed in the world using the usual functions such as dGeomSetPosition and dGeomSetRotation. If the geom is not set as placeable, then it uses a fixed orientation where the global y axis represents the dynamic 'height' of the heightfield.
Returns
A geom id to reference this geom in other calls.
void dGeomClearOffset ( dGeomID  geom)

Clear any offset from the geom.

If the geom has an offset, it is eliminated and the geom is repositioned at the body's position. If the geom has no offset, this function does nothing. This is more efficient than calling dGeomSetOffsetPosition(zero) and dGeomSetOffsetRotation(identiy), because this function actually eliminates the offset, rather than leaving it as the identity transform.

Parameters
geomthe geom to have its offset destroyed.
void dGeomCopyOffsetPosition ( dGeomID  geom,
dVector3  pos 
)

Copy the offset position vector of a geom.

Returns the positional offset of the geom in local coordinates. If the geom has no offset, this function returns the zero vector.

Parameters
geomthe geom to query.
posreturns the offset position
void dGeomCopyOffsetRotation ( dGeomID  geom,
dMatrix3  R 
)

Copy the offset rotation matrix of a geom.

Returns the rotational offset of the geom in local coordinates. If the geom has no offset, this function returns the identity matrix.

Parameters
geomthe geom to query.
Rreturns the rotation matrix.
void dGeomCopyPosition ( dGeomID  geom,
dVector3  pos 
)

Copy the position of a geom into a vector.

Parameters
geomthe geom to query
posa copy of the geom position
See Also
dGeomGetPosition
void dGeomCopyRotation ( dGeomID  geom,
dMatrix3  R 
)

Get the rotation matrix of a placeable geom.

If the geom is attached to a body, the body's rotation will be returned.

Calling this function on a non-placeable geom results in a runtime error in the debug build of ODE.

Parameters
geomthe geom to query.
Ra copy of the geom rotation
See Also
dGeomGetRotation
void dGeomDestroy ( dGeomID  geom)

Destroy a geom, removing it from any space.

Destroy a geom, removing it from any space it is in first. This one function destroys a geom of any type, but to create a geom you must call a creation function for that type.

When a space is destroyed, if its cleanup mode is 1 (the default) then all the geoms in that space are automatically destroyed as well.

Parameters
geomthe geom to be destroyed.
void dGeomDisable ( dGeomID  geom)

Disable a geom.

Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2, although they can still be members of a space. New geoms are created in the enabled state.

Parameters
geomthe geom to disable
See Also
dGeomDisable
dGeomIsEnabled
void dGeomEnable ( dGeomID  geom)

Enable a geom.

Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2, although they can still be members of a space. New geoms are created in the enabled state.

Parameters
geomthe geom to enable
See Also
dGeomDisable
dGeomIsEnabled
void dGeomGetAABB ( dGeomID  geom,
dReal  aabb[6] 
)

Return the axis-aligned bounding box.

Return in aabb an axis aligned bounding box that surrounds the given geom. The aabb array has elements (minx, maxx, miny, maxy, minz, maxz). If the geom is a space, a bounding box that surrounds all contained geoms is returned.

This function may return a pre-computed cached bounding box, if it can determine that the geom has not moved since the last time the bounding box was computed.

Parameters
geomthe geom to query
aabbthe returned bounding box
dBodyID dGeomGetBody ( dGeomID  geom)

Get the body associated with a placeable geom.

Parameters
geomthe geom to query.
See Also
dGeomSetBody
unsigned long dGeomGetCategoryBits ( dGeomID  )

Get the "category" bitfield for the given geom.

Parameters
geomthe geom to set
bitsthe new bitfield value
See Also
dGeomSetCategoryBits
int dGeomGetClass ( dGeomID  geom)

Given a geom, this returns its class.

The ODE classes are:

  • dSphereClass
  • dBoxClass
  • dCylinderClass
  • dPlaneClass
  • dRayClass
  • dConvexClass
  • dGeomTransformClass
  • dTriMeshClass
  • dSimpleSpaceClass
  • dHashSpaceClass
  • dQuadTreeSpaceClass
  • dFirstUserClass
  • dLastUserClass

User-defined class will return their own number.

Parameters
geomthe geom to query
Returns
The geom class ID.
unsigned long dGeomGetCollideBits ( dGeomID  )

Get the "collide" bitfield for the given geom.

Parameters
geomthe geom to set
bitsthe new bitfield value
See Also
dGeomSetCollideBits
void* dGeomGetData ( dGeomID  geom)

Get the user-defined data pointer stored in the geom.

Parameters
geomthe geom containing the data
const dReal* dGeomGetOffsetPosition ( dGeomID  geom)

Get the offset position vector of a geom.

Returns the positional offset of the geom in local coordinates. If the geom has no offset, this function returns the zero vector.

Parameters
geomthe geom to query.
Returns
A pointer to the geom's offset vector.
Remarks
The returned value is a pointer to the geom's internal data structure. It is valid until any changes are made to the geom.
void dGeomGetOffsetQuaternion ( dGeomID  geom,
dQuaternion  result 
)

Get the offset rotation quaternion of a geom.

Returns the rotation offset of the geom as a quaternion. If the geom has no offset, the identity quaternion is returned.

Parameters
geomthe geom to query.
resulta copy of the rotation quaternion.
const dReal* dGeomGetOffsetRotation ( dGeomID  geom)

Get the offset rotation matrix of a geom.

Returns the rotational offset of the geom in local coordinates. If the geom has no offset, this function returns the identity matrix.

Parameters
geomthe geom to query.
Returns
A pointer to the geom's offset rotation matrix.
Remarks
The returned value is a pointer to the geom's internal data structure. It is valid until any changes are made to the geom.
const dReal* dGeomGetPosition ( dGeomID  geom)

Get the position vector of a placeable geom.

If the geom is attached to a body, the body's position will be returned.

Calling this function on a non-placeable geom results in a runtime error in the debug build of ODE.

Parameters
geomthe geom to query.
Returns
A pointer to the geom's position vector.
Remarks
The returned value is a pointer to the geom's internal data structure. It is valid until any changes are made to the geom.
See Also
dBodyGetPosition
void dGeomGetPosRelPoint ( dGeomID  geom,
dReal  px,
dReal  py,
dReal  pz,
dVector3  result 
)

takes a point in global coordinates and returns the point's position in geom-relative coordinates.

Calling this function on a non-placeable geom results in the same point being returned.

Remarks
This is the inverse of dGeomGetRelPointPos()
Parameters
resultwill contain the result.
void dGeomGetQuaternion ( dGeomID  geom,
dQuaternion  result 
)

Get the rotation quaternion of a placeable geom.

If the geom is attached to a body, the body's quaternion will be returned.

Calling this function on a non-placeable geom results in a runtime error in the debug build of ODE.

Parameters
geomthe geom to query.
resulta copy of the rotation quaternion.
See Also
dBodyGetQuaternion
void dGeomGetRelPointPos ( dGeomID  geom,
dReal  px,
dReal  py,
dReal  pz,
dVector3  result 
)

Get world position of a relative point on geom.

Calling this function on a non-placeable geom results in the same point being returned.

Parameters
resultwill contain the result.
const dReal* dGeomGetRotation ( dGeomID  geom)

Get the rotation matrix of a placeable geom.

If the geom is attached to a body, the body's rotation will be returned.

Calling this function on a non-placeable geom results in a runtime error in the debug build of ODE.

Parameters
geomthe geom to query.
Returns
A pointer to the geom's rotation matrix.
Remarks
The returned value is a pointer to the geom's internal data structure. It is valid until any changes are made to the geom.
See Also
dBodyGetRotation
dSpaceID dGeomGetSpace ( dGeomID  )

Query for the space containing a particular geom.

Parameters
geomthe geom to query
Returns
The space that contains the geom, or NULL if the geom is not contained by a space.
void dGeomHeightfieldDataBuildByte ( dHeightfieldDataID  d,
const unsigned char *  pHeightData,
int  bCopyHeightData,
dReal  width,
dReal  depth,
int  widthSamples,
int  depthSamples,
dReal  scale,
dReal  offset,
dReal  thickness,
int  bWrap 
)

Configures a dHeightfieldDataID to use height data in byte format.

Before a dHeightfieldDataID can be used by a geom it must be configured to specify the format of the height data. This call specifies that the heightfield data is stored as a rectangular array of bytes (8 bit unsigned) representing the height at each sample point.

Parameters
dA new dHeightfieldDataID created by dGeomHeightfieldDataCreate
pHeightDataA pointer to the height data.
bCopyHeightDataWhen non-zero the height data is copied to an internal store. When zero the height data is accessed by reference and so must persist throughout the lifetime of the heightfield.
widthSpecifies the total 'width' of the heightfield along the geom's local x axis.
depthSpecifies the total 'depth' of the heightfield along the geom's local z axis.
widthSamplesSpecifies the number of vertices to sample along the width of the heightfield. Each vertex has a corresponding height value which forms the overall shape. Naturally this value must be at least two or more.
depthSamplesSpecifies the number of vertices to sample along the depth of the heightfield.
scaleA uniform scale applied to all raw height data.
offsetAn offset applied to the scaled height data.
thicknessA value subtracted from the lowest height value which in effect adds an additional cuboid to the base of the heightfield. This is used to prevent geoms from looping under the desired terrain and not registering as a collision. Note that the thickness is not affected by the scale or offset parameters.
bWrapIf non-zero the heightfield will infinitely tile in both directions along the local x and z axes. If zero the heightfield is bounded from zero to width in the local x axis, and zero to depth in the local z axis.
void dGeomHeightfieldDataBuildCallback ( dHeightfieldDataID  d,
void *  pUserData,
dHeightfieldGetHeight pCallback,
dReal  width,
dReal  depth,
int  widthSamples,
int  depthSamples,
dReal  scale,
dReal  offset,
dReal  thickness,
int  bWrap 
)

Configures a dHeightfieldDataID to use a callback to retrieve height data.

Before a dHeightfieldDataID can be used by a geom it must be configured to specify the format of the height data. This call specifies that the heightfield data is computed by the user and it should use the given callback when determining the height of a given element of it's shape.

Parameters
dA new dHeightfieldDataID created by dGeomHeightfieldDataCreate
widthSpecifies the total 'width' of the heightfield along the geom's local x axis.
depthSpecifies the total 'depth' of the heightfield along the geom's local z axis.
widthSamplesSpecifies the number of vertices to sample along the width of the heightfield. Each vertex has a corresponding height value which forms the overall shape. Naturally this value must be at least two or more.
depthSamplesSpecifies the number of vertices to sample along the depth of the heightfield.
scaleA uniform scale applied to all raw height data.
offsetAn offset applied to the scaled height data.
thicknessA value subtracted from the lowest height value which in effect adds an additional cuboid to the base of the heightfield. This is used to prevent geoms from looping under the desired terrain and not registering as a collision. Note that the thickness is not affected by the scale or offset parameters.
bWrapIf non-zero the heightfield will infinitely tile in both directions along the local x and z axes. If zero the heightfield is bounded from zero to width in the local x axis, and zero to depth in the local z axis.
void dGeomHeightfieldDataBuildDouble ( dHeightfieldDataID  d,
const double *  pHeightData,
int  bCopyHeightData,
dReal  width,
dReal  depth,
int  widthSamples,
int  depthSamples,
dReal  scale,
dReal  offset,
dReal  thickness,
int  bWrap 
)

Configures a dHeightfieldDataID to use height data in double precision floating point format.

Before a dHeightfieldDataID can be used by a geom it must be configured to specify the format of the height data. This call specifies that the heightfield data is stored as a rectangular array of double precision floats representing the height at each sample point.

Parameters
dA new dHeightfieldDataID created by dGeomHeightfieldDataCreate
pHeightDataA pointer to the height data.
bCopyHeightDataWhen non-zero the height data is copied to an internal store. When zero the height data is accessed by reference and so must persist throughout the lifetime of the heightfield.
widthSpecifies the total 'width' of the heightfield along the geom's local x axis.
depthSpecifies the total 'depth' of the heightfield along the geom's local z axis.
widthSamplesSpecifies the number of vertices to sample along the width of the heightfield. Each vertex has a corresponding height value which forms the overall shape. Naturally this value must be at least two or more.
depthSamplesSpecifies the number of vertices to sample along the depth of the heightfield.
scaleA uniform scale applied to all raw height data.
offsetAn offset applied to the scaled height data.
thicknessA value subtracted from the lowest height value which in effect adds an additional cuboid to the base of the heightfield. This is used to prevent geoms from looping under the desired terrain and not registering as a collision. Note that the thickness is not affected by the scale or offset parameters.
bWrapIf non-zero the heightfield will infinitely tile in both directions along the local x and z axes. If zero the heightfield is bounded from zero to width in the local x axis, and zero to depth in the local z axis.
void dGeomHeightfieldDataBuildShort ( dHeightfieldDataID  d,
const short *  pHeightData,
int  bCopyHeightData,
dReal  width,
dReal  depth,
int  widthSamples,
int  depthSamples,
dReal  scale,
dReal  offset,
dReal  thickness,
int  bWrap 
)

Configures a dHeightfieldDataID to use height data in short format.

Before a dHeightfieldDataID can be used by a geom it must be configured to specify the format of the height data. This call specifies that the heightfield data is stored as a rectangular array of shorts (16 bit signed) representing the height at each sample point.

Parameters
dA new dHeightfieldDataID created by dGeomHeightfieldDataCreate
pHeightDataA pointer to the height data.
bCopyHeightDataWhen non-zero the height data is copied to an internal store. When zero the height data is accessed by reference and so must persist throughout the lifetime of the heightfield.
widthSpecifies the total 'width' of the heightfield along the geom's local x axis.
depthSpecifies the total 'depth' of the heightfield along the geom's local z axis.
widthSamplesSpecifies the number of vertices to sample along the width of the heightfield. Each vertex has a corresponding height value which forms the overall shape. Naturally this value must be at least two or more.
depthSamplesSpecifies the number of vertices to sample along the depth of the heightfield.
scaleA uniform scale applied to all raw height data.
offsetAn offset applied to the scaled height data.
thicknessA value subtracted from the lowest height value which in effect adds an additional cuboid to the base of the heightfield. This is used to prevent geoms from looping under the desired terrain and not registering as a collision. Note that the thickness is not affected by the scale or offset parameters.
bWrapIf non-zero the heightfield will infinitely tile in both directions along the local x and z axes. If zero the heightfield is bounded from zero to width in the local x axis, and zero to depth in the local z axis.
void dGeomHeightfieldDataBuildSingle ( dHeightfieldDataID  d,
const float *  pHeightData,
int  bCopyHeightData,
dReal  width,
dReal  depth,
int  widthSamples,
int  depthSamples,
dReal  scale,
dReal  offset,
dReal  thickness,
int  bWrap 
)

Configures a dHeightfieldDataID to use height data in single precision floating point format.

Before a dHeightfieldDataID can be used by a geom it must be configured to specify the format of the height data. This call specifies that the heightfield data is stored as a rectangular array of single precision floats representing the height at each sample point.

Parameters
dA new dHeightfieldDataID created by dGeomHeightfieldDataCreate
pHeightDataA pointer to the height data.
bCopyHeightDataWhen non-zero the height data is copied to an internal store. When zero the height data is accessed by reference and so must persist throughout the lifetime of the heightfield.
widthSpecifies the total 'width' of the heightfield along the geom's local x axis.
depthSpecifies the total 'depth' of the heightfield along the geom's local z axis.
widthSamplesSpecifies the number of vertices to sample along the width of the heightfield. Each vertex has a corresponding height value which forms the overall shape. Naturally this value must be at least two or more.
depthSamplesSpecifies the number of vertices to sample along the depth of the heightfield.
scaleA uniform scale applied to all raw height data.
offsetAn offset applied to the scaled height data.
thicknessA value subtracted from the lowest height value which in effect adds an additional cuboid to the base of the heightfield. This is used to prevent geoms from looping under the desired terrain and not registering as a collision. Note that the thickness is not affected by the scale or offset parameters.
bWrapIf non-zero the heightfield will infinitely tile in both directions along the local x and z axes. If zero the heightfield is bounded from zero to width in the local x axis, and zero to depth in the local z axis.
dHeightfieldDataID dGeomHeightfieldDataCreate ( void  )

Creates a new empty dHeightfieldDataID.

Allocates a new dHeightfieldDataID and returns it. You must call dGeomHeightfieldDataDestroy to destroy it after the geom has been removed. The dHeightfieldDataID value is used when specifying a data format type.

Returns
A dHeightfieldDataID for use with dGeomHeightfieldDataBuildCallback, dGeomHeightfieldDataBuildByte, dGeomHeightfieldDataBuildShort or dGeomHeightfieldDataBuildFloat.
void dGeomHeightfieldDataDestroy ( dHeightfieldDataID  d)

Destroys a dHeightfieldDataID.

Deallocates a given dHeightfieldDataID and all managed resources.

Parameters
dA dHeightfieldDataID created by dGeomHeightfieldDataCreate
void dGeomHeightfieldDataSetBounds ( dHeightfieldDataID  d,
dReal  minHeight,
dReal  maxHeight 
)

Manually set the minimum and maximum height bounds.

This call allows you to set explicit min / max values after initial creation typically for callback heightfields which default to +/- infinity, or those whose data has changed. This must be set prior to binding with a geom, as the the AABB is not recomputed after it's first generation.

Remarks
The minimum and maximum values are used to compute the AABB for the heightfield which is used for early rejection of collisions. A close fit will yield a more efficient collision check.
Parameters
dA dHeightfieldDataID created by dGeomHeightfieldDataCreate
min_heightThe new minimum height value. Scale, offset and thickness is then applied.
max_heightThe new maximum height value. Scale and offset is then applied.
dHeightfieldDataID dGeomHeightfieldGetHeightfieldData ( dGeomID  g)

Gets the dHeightfieldDataID bound to a heightfield geom.

Returns the dHeightfieldDataID associated with a heightfield geom.

Parameters
gA geom created by dCreateHeightfield
Returns
The dHeightfieldDataID which may be NULL if none was assigned.
void dGeomHeightfieldSetHeightfieldData ( dGeomID  g,
dHeightfieldDataID  d 
)

Assigns a dHeightfieldDataID to a heightfield geom.

Associates the given dHeightfieldDataID with a heightfield geom. This is done without affecting the GEOM_PLACEABLE flag.

Parameters
gA geom created by dCreateHeightfield
dA dHeightfieldDataID created by dGeomHeightfieldDataCreate
int dGeomIsEnabled ( dGeomID  geom)

Check to see if a geom is enabled.

Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2, although they can still be members of a space. New geoms are created in the enabled state.

Parameters
geomthe geom to query
Returns
Non-zero if the geom is enabled, zero otherwise.
See Also
dGeomDisable
dGeomIsEnabled
int dGeomIsOffset ( dGeomID  geom)

Check to see whether the geom has an offset.

This function will return non-zero if the offset has been created. Note that there is a difference between a geom with no offset, and a geom with an offset that is the identity transform. In the latter case, although the observed behaviour is identical, there is a unnecessary computation involved because the geom will be applying the transform whenever it needs to recalculate its world position.

Parameters
geomthe geom to query.
Returns
Non-zero if the geom has an offset, zero otherwise.
int dGeomIsSpace ( dGeomID  geom)

Determing if a geom is a space.

Parameters
geomthe geom to query
Returns
Non-zero if the geom is a space, zero otherwise.
int dGeomLowLevelControl ( dGeomID  geom,
int  controlClass,
int  controlCode,
void *  dataValue,
int *  dataSize 
)

Execute low level control operation for geometry.

The variable the dataSize points to must be initialized before the call. If the size does not match the one expected for the control class/code function changes it to the size expected and returns failure. This implies the function can be called with NULL data and zero size to test if control class/code is supported and obtain required data size for it.

dGeomCommonAnyControlCode applies to any control class and returns success if at least one control code is available for the given class with given geom.

Currently there are the folliwing control classes supported:

  • dGeomColliderControlClass

For dGeomColliderControlClass there are the following codes available:

  • dGeomColliderSetMergeSphereContactsControlCode (arg of type int, dGeomColliderMergeContactsValue_*)
  • dGeomColliderGetMergeSphereContactsControlCode (arg of type int, dGeomColliderMergeContactsValue_*)
Parameters
geomthe geom to control
controlClassthe control class
controlCodethe control code for the class
dataValuethe control argument pointer
dataSizethe control argument size provided or expected
Returns
Boolean execution status
void dGeomSetBody ( dGeomID  geom,
dBodyID  body 
)

Set the body associated with a placeable geom.

Setting a body on a geom automatically combines the position vector and rotation matrix of the body and geom, so that setting the position or orientation of one will set the value for both objects. Setting a body ID of zero gives the geom its own position and rotation, independent from any body. If the geom was previously connected to a body then its new independent position/rotation is set to the current position/rotation of the body.

Calling these functions on a non-placeable geom results in a runtime error in the debug build of ODE.

Parameters
geomthe geom to connect
bodythe body to attach to the geom
void dGeomSetCategoryBits ( dGeomID  geom,
unsigned long  bits 
)

Set the "category" bitfield for the given geom.

The category bitfield is used by spaces to govern which geoms will interact with each other. The bitfield is guaranteed to be at least 32 bits wide. The default category values for newly created geoms have all bits set.

Parameters
geomthe geom to set
bitsthe new bitfield value
void dGeomSetCollideBits ( dGeomID  geom,
unsigned long  bits 
)

Set the "collide" bitfield for the given geom.

The collide bitfield is used by spaces to govern which geoms will interact with each other. The bitfield is guaranteed to be at least 32 bits wide. The default category values for newly created geoms have all bits set.

Parameters
geomthe geom to set
bitsthe new bitfield value
void dGeomSetData ( dGeomID  geom,
void *  data 
)

Set the user-defined data pointer stored in the geom.

Parameters
geomthe geom to hold the data
datathe data pointer to be stored
void dGeomSetOffsetPosition ( dGeomID  geom,
dReal  x,
dReal  y,
dReal  z 
)

Set the local offset position of a geom from its body.

Sets the geom's positional offset in local coordinates. After this call, the geom will be at a new position determined from the body's position and the offset. The geom must be attached to a body. If the geom did not have an offset, it is automatically created.

Parameters
geomthe geom to set.
xthe new X coordinate.
ythe new Y coordinate.
zthe new Z coordinate.
void dGeomSetOffsetQuaternion ( dGeomID  geom,
const dQuaternion  Q 
)

Set the local offset rotation of a geom from its body.

Sets the geom's rotational offset in local coordinates. After this call, the geom will be at a new position determined from the body's position and the offset. The geom must be attached to a body. If the geom did not have an offset, it is automatically created.

Parameters
geomthe geom to set.
Qthe new rotation.
void dGeomSetOffsetRotation ( dGeomID  geom,
const dMatrix3  R 
)

Set the local offset rotation matrix of a geom from its body.

Sets the geom's rotational offset in local coordinates. After this call, the geom will be at a new position determined from the body's position and the offset. The geom must be attached to a body. If the geom did not have an offset, it is automatically created.

Parameters
geomthe geom to set.
Rthe new rotation matrix.
void dGeomSetOffsetWorldPosition ( dGeomID  geom,
dReal  x,
dReal  y,
dReal  z 
)

Set the offset position of a geom from its body.

Sets the geom's positional offset to move it to the new world coordinates. After this call, the geom will be at the world position passed in, and the offset will be the difference from the current body position. The geom must be attached to a body. If the geom did not have an offset, it is automatically created.

Parameters
geomthe geom to set.
xthe new X coordinate.
ythe new Y coordinate.
zthe new Z coordinate.
void dGeomSetOffsetWorldQuaternion ( dGeomID  geom,
const dQuaternion   
)

Set the offset rotation of a geom from its body.

Sets the geom's rotational offset to orient it to the new world rotation matrix. After this call, the geom will be at the world orientation passed in, and the offset will be the difference from the current body orientation. The geom must be attached to a body. If the geom did not have an offset, it is automatically created.

Parameters
geomthe geom to set.
Qthe new rotation.
void dGeomSetOffsetWorldRotation ( dGeomID  geom,
const dMatrix3  R 
)

Set the offset rotation of a geom from its body.

Sets the geom's rotational offset to orient it to the new world rotation matrix. After this call, the geom will be at the world orientation passed in, and the offset will be the difference from the current body orientation. The geom must be attached to a body. If the geom did not have an offset, it is automatically created.

Parameters
geomthe geom to set.
Rthe new rotation matrix.
void dGeomSetPosition ( dGeomID  geom,
dReal  x,
dReal  y,
dReal  z 
)

Set the position vector of a placeable geom.

If the geom is attached to a body, the body's position will also be changed. Calling this function on a non-placeable geom results in a runtime error in the debug build of ODE.

Parameters
geomthe geom to set.
xthe new X coordinate.
ythe new Y coordinate.
zthe new Z coordinate.
See Also
dBodySetPosition
void dGeomSetQuaternion ( dGeomID  geom,
const dQuaternion  Q 
)

Set the rotation of a placeable geom.

If the geom is attached to a body, the body's rotation will also be changed.

Calling this function on a non-placeable geom results in a runtime error in the debug build of ODE.

Parameters
geomthe geom to set.
Qthe new rotation.
See Also
dBodySetQuaternion
void dGeomSetRotation ( dGeomID  geom,
const dMatrix3  R 
)

Set the rotation matrix of a placeable geom.

If the geom is attached to a body, the body's rotation will also be changed. Calling this function on a non-placeable geom results in a runtime error in the debug build of ODE.

Parameters
geomthe geom to set.
Rthe new rotation matrix.
See Also
dBodySetRotation
void dGeomVectorFromWorld ( dGeomID  geom,
dReal  px,
dReal  py,
dReal  pz,
dVector3  result 
)

Convert from world to geom-local coordinates.

Calling this function on a non-placeable geom results in the same vector being returned.

Parameters
resultwill contain the result.
void dGeomVectorToWorld ( dGeomID  geom,
dReal  px,
dReal  py,
dReal  pz,
dVector3  result 
)

Convert from geom-local to world coordinates.

Calling this function on a non-placeable geom results in the same vector being returned.

Parameters
resultwill contain the result.
void dSetColliderOverride ( int  i,
int  j,
dColliderFn *  fn 
)

Sets a custom collider function for two geom classes.

Parameters
iThe first geom class handled by this collider
jThe second geom class handled by this collider
fnThe collider function to use to determine collisions.
void dSpaceCollide ( dSpaceID  space,
void *  data,
dNearCallback callback 
)

Determines which pairs of geoms in a space may potentially intersect, and calls the callback function for each candidate pair.

Parameters
spaceThe space to test.
dataPassed from dSpaceCollide directly to the callback function. Its meaning is user defined. The o1 and o2 arguments are the geoms that may be near each other.
callbackA callback function is of type dNearCallback.
Remarks
Other spaces that are contained within the colliding space are not treated specially, i.e. they are not recursed into. The callback function may be passed these contained spaces as one or both geom arguments.
dSpaceCollide() is guaranteed to pass all intersecting geom pairs to the callback function, but may also pass close but non-intersecting pairs. The number of these calls depends on the internal algorithms used by the space. Thus you should not expect that dCollide will return contacts for every pair passed to the callback.
See Also
dSpaceCollide2
void dSpaceCollide2 ( dGeomID  space1,
dGeomID  space2,
void *  data,
dNearCallback callback 
)

Determines which geoms from one space may potentially intersect with geoms from another space, and calls the callback function for each candidate pair.

Parameters
space1The first space to test.
space2The second space to test.
dataPassed from dSpaceCollide directly to the callback function. Its meaning is user defined. The o1 and o2 arguments are the geoms that may be near each other.
callbackA callback function is of type dNearCallback.
Remarks
This function can also test a single non-space geom against a space. This function is useful when there is a collision hierarchy, i.e. when there are spaces that contain other spaces.
Other spaces that are contained within the colliding space are not treated specially, i.e. they are not recursed into. The callback function may be passed these contained spaces as one or both geom arguments.
Sublevel value of space affects how the spaces are iterated. Both spaces are recursed only if their sublevels match. Otherwise, only the space with greater sublevel is recursed and the one with lesser sublevel is used as a geom itself.
dSpaceCollide2() is guaranteed to pass all intersecting geom pairs to the callback function, but may also pass close but non-intersecting pairs. The number of these calls depends on the internal algorithms used by the space. Thus you should not expect that dCollide will return contacts for every pair passed to the callback.
See Also
dSpaceCollide
dSpaceSetSublevel
int dSpaceGetClass ( dSpaceID  space)

Given a space, this returns its class.

The ODE classes are:

  • dSimpleSpaceClass
  • dHashSpaceClass
  • dSweepAndPruneSpaceClass
  • dQuadTreeSpaceClass
  • dFirstUserClass
  • dLastUserClass

The class id not defined by the user should be between dFirstSpaceClass and dLastSpaceClass.

User-defined class will return their own number.

Parameters
spacethe space to query
Returns
The space class ID.
int dSpaceGetManualCleanup ( dSpaceID  space)

Get manual cleanup flag of a space.

Manual cleanup flag marks a space space as eligible for manual thread data cleanup. See dSpaceSetManualCleanup for more details.

Parameters
spacethe space to query
Returns
1 for manual cleanup mode and 0 for default cleanup mode of the space
See Also
dSpaceSetManualCleanup
dInitODE2
int dSpaceGetSublevel ( dSpaceID  space)

Gets sublevel value of a space.

Sublevel affects how the space is handled in dSpaceCollide2 when it is collided with another space. See dSpaceSetSublevel for more details.

Parameters
spacethe space to query
Returns
the sublevel value of the space
See Also
dSpaceSetSublevel
dSpaceCollide2
void dSpaceSetManualCleanup ( dSpaceID  space,
int  mode 
)

Sets manual cleanup flag for a space.

Manual cleanup flag marks a space as eligible for manual thread data cleanup. This function should be called for every space object right after creation in case if ODE has been initialized with dInitFlagManualThreadCleanup flag.

Failure to set manual cleanup flag for a space may lead to some resources remaining leaked until the program exit.

Parameters
spacethe space to modify
mode1 for manual cleanup mode and 0 for default cleanup mode
See Also
dSpaceGetManualCleanup
dInitODE2
void dSpaceSetSublevel ( dSpaceID  space,
int  sublevel 
)

Sets sublevel value for a space.

Sublevel affects how the space is handled in dSpaceCollide2 when it is collided with another space. If sublevels of both spaces match, the function iterates geometries of both spaces and collides them with each other. If sublevel of one space is greater than the sublevel of another one, only the geometries of the space with greater sublevel are iterated, another space is passed into collision callback as a geometry itself. By default all the spaces are assigned zero sublevel.

Note
The space sublevel IS NOT automatically updated when one space is inserted into another or removed from one. It is a client's responsibility to update sublevel value if necessary.
Parameters
spacethe space to modify
sublevelthe sublevel value to be assigned
See Also
dSpaceGetSublevel
dSpaceCollide2