ODE  0.13.1
 All Data Structures Functions Variables Typedefs Enumerations Groups
World

Modules

 Automatic Enabling and Disabling
 
 Damping
 

Data Structures

struct  dWorldStepReserveInfo
 Memory reservation policy descriptor structure for world stepping functions. More...
 

Functions

dWorldID dWorldCreate (void)
 Create a new, empty world and return its ID number. More...
 
void dWorldDestroy (dWorldID world)
 Destroy a world and everything in it. More...
 
void dWorldSetData (dWorldID world, void *data)
 Set the user-data pointer. More...
 
void * dWorldGetData (dWorldID world)
 Get the user-data pointer. More...
 
void dWorldSetGravity (dWorldID, dReal x, dReal y, dReal z)
 Set the world's global gravity vector. More...
 
void dWorldGetGravity (dWorldID, dVector3 gravity)
 Get the gravity vector for a given world.
 
void dWorldSetERP (dWorldID, dReal erp)
 Set the global ERP value, that controls how much error correction is performed in each time step. More...
 
dReal dWorldGetERP (dWorldID)
 Get the error reduction parameter. More...
 
void dWorldSetCFM (dWorldID, dReal cfm)
 Set the global CFM (constraint force mixing) value. More...
 
dReal dWorldGetCFM (dWorldID)
 Get the constraint force mixing value. More...
 
void dWorldSetStepIslandsProcessingMaxThreadCount (dWorldID w, unsigned count)
 Set maximum threads to be used for island stepping. More...
 
unsigned dWorldGetStepIslandsProcessingMaxThreadCount (dWorldID w)
 Get maximum threads that are allowed to be used for island stepping. More...
 
int dWorldUseSharedWorkingMemory (dWorldID w, dWorldID from_world)
 Set the world to use shared working memory along with another world. More...
 
void dWorldCleanupWorkingMemory (dWorldID w)
 Release internal working memory allocated for world. More...
 
int dWorldSetStepMemoryReservationPolicy (dWorldID w, const dWorldStepReserveInfo *policyinfo)
 Set memory reservation policy for world to be used with simulation stepping functions. More...
 
int dWorldSetStepMemoryManager (dWorldID w, const dWorldStepMemoryFunctionsInfo *memfuncs)
 Set memory manager for world to be used with simulation stepping functions. More...
 
void dWorldSetStepThreadingImplementation (dWorldID w, const dThreadingFunctionsInfo *functions_info, dThreadingImplementationID threading_impl)
 Assign threading implementation to be used for [quick]stepping the world. More...
 
int dWorldStep (dWorldID w, dReal stepsize)
 Step the world. More...
 
int dWorldQuickStep (dWorldID w, dReal stepsize)
 Quick-step the world. More...
 
void dWorldImpulseToForce (dWorldID, dReal stepsize, dReal ix, dReal iy, dReal iz, dVector3 force)
 Converts an impulse to a force. More...
 
void dWorldSetQuickStepNumIterations (dWorldID, int num)
 Set the number of iterations that the QuickStep method performs per step. More...
 
int dWorldGetQuickStepNumIterations (dWorldID)
 Get the number of iterations that the QuickStep method performs per step. More...
 
void dWorldSetQuickStepW (dWorldID, dReal over_relaxation)
 Set the SOR over-relaxation parameter. More...
 
dReal dWorldGetQuickStepW (dWorldID)
 Get the SOR over-relaxation parameter. More...
 
void dWorldSetContactMaxCorrectingVel (dWorldID, dReal vel)
 Set the maximum correcting velocity that contacts are allowed to generate. More...
 
dReal dWorldGetContactMaxCorrectingVel (dWorldID)
 Get the maximum correcting velocity that contacts are allowed to generated.
 
void dWorldSetContactSurfaceLayer (dWorldID, dReal depth)
 Set the depth of the surface layer around all geometry objects. More...
 
dReal dWorldGetContactSurfaceLayer (dWorldID)
 Get the depth of the surface layer around all geometry objects. More...
 

Detailed Description

The world object is a container for rigid bodies and joints. Objects in different worlds can not interact, for example rigid bodies from two different worlds can not collide.

All the objects in a world exist at the same point in time, thus one reason to use separate worlds is to simulate systems at different rates. Most applications will only need one world.

Function Documentation

void dWorldCleanupWorkingMemory ( dWorldID  w)

Release internal working memory allocated for world.

The worlds allocate working memory internally for simulation stepping. This function can be used to free world's internal memory cache in case if number of objects/joints in the world decreases significantly. By default, internal allocation policy is used to only increase cache size as necessary and never decrease it.

If a world shares its working memory with other worlds the cache deletion affects all the linked worlds. However the shared status itself remains intact.

The function call does affect neither memory reservation policy nor memory manager.

Parameters
wThe world to release working memory for.
See Also
dWorldUseSharedWorkingMemory
dWorldSetStepMemoryReservationPolicy
dWorldSetStepMemoryManager
dWorldID dWorldCreate ( void  )

Create a new, empty world and return its ID number.

Returns
an identifier
void dWorldDestroy ( dWorldID  world)

Destroy a world and everything in it.

This includes all bodies, and all joints that are not part of a joint group. Joints that are part of a joint group will be deactivated, and can be destroyed by calling, for example, dJointGroupEmpty().

Parameters
worldthe identifier for the world the be destroyed.
dReal dWorldGetCFM ( dWorldID  )

Get the constraint force mixing value.

Returns
CFM value
dReal dWorldGetContactSurfaceLayer ( dWorldID  )

Get the depth of the surface layer around all geometry objects.

Returns
the depth
void* dWorldGetData ( dWorldID  world)

Get the user-data pointer.

Parameters
worldthe world to set the data on
data
dReal dWorldGetERP ( dWorldID  )

Get the error reduction parameter.

Returns
ERP value
int dWorldGetQuickStepNumIterations ( dWorldID  )

Get the number of iterations that the QuickStep method performs per step.

Returns
nr of iterations
dReal dWorldGetQuickStepW ( dWorldID  )

Get the SOR over-relaxation parameter.

Returns
the over-relaxation setting
unsigned dWorldGetStepIslandsProcessingMaxThreadCount ( dWorldID  w)

Get maximum threads that are allowed to be used for island stepping.

Please read commentaries to dWorldSetStepIslandsProcessingMaxThreadCount for important information regarding the value returned.

Parameters
wThe world queried
Returns
Current thread count limit value for island stepping
See Also
dWorldSetStepIslandsProcessingMaxThreadCount
void dWorldImpulseToForce ( dWorldID  ,
dReal  stepsize,
dReal  ix,
dReal  iy,
dReal  iz,
dVector3  force 
)

Converts an impulse to a force.

Remarks
If you want to apply a linear or angular impulse to a rigid body, instead of a force or a torque, then you can use this function to convert the desired impulse into a force/torque vector before calling the BodyAdd... function. The current algorithm simply scales the impulse by 1/stepsize, where stepsize is the step size for the next step that will be taken. This function is given a dWorldID because, in the future, the force computation may depend on integrator parameters that are set as properties of the world.
int dWorldQuickStep ( dWorldID  w,
dReal  stepsize 
)

Quick-step the world.

This uses an iterative method that takes time on the order of m*N and memory on the order of m, where m is the total number of constraint rows N is the number of iterations. For large systems this is a lot faster than dWorldStep(), but it is less accurate.

QuickStep is great for stacks of objects especially when the auto-disable feature is used as well. However, it has poor accuracy for near-singular systems. Near-singular systems can occur when using high-friction contacts, motors, or certain articulated structures. For example, a robot with multiple legs sitting on the ground may be near-singular.

There are ways to help overcome QuickStep's inaccuracy problems:

  • Increase CFM.
  • Reduce the number of contacts in your system (e.g. use the minimum number of contacts for the feet of a robot or creature).
  • Don't use excessive friction in the contacts.
  • Use contact slip if appropriate
  • Avoid kinematic loops (however, kinematic loops are inevitable in legged creatures).
  • Don't use excessive motor strength. force-based motors instead of velocity-based motors.

Increasing the number of QuickStep iterations may help a little bit, but it is not going to help much if your system is really near singular.

Failure result status means that the memory allocation has failed for operation. In such a case all the objects remain in unchanged state and simulation can be retried as soon as more memory is available.

Parameters
wThe world to be stepped
stepsizeThe number of seconds that the simulation has to advance.
Returns
1 for success and 0 for failure
void dWorldSetCFM ( dWorldID  ,
dReal  cfm 
)

Set the global CFM (constraint force mixing) value.

Parameters
cfmTypical values are in the range {10^{-9}} – 1. The default is 10^-5 if single precision is being used, or 10^-10 if double precision is being used.
void dWorldSetContactMaxCorrectingVel ( dWorldID  ,
dReal  vel 
)

Set the maximum correcting velocity that contacts are allowed to generate.

Parameters
velThe default value is infinity (i.e. no limit).
Remarks
Reducing this value can help prevent "popping" of deeply embedded objects.
void dWorldSetContactSurfaceLayer ( dWorldID  ,
dReal  depth 
)

Set the depth of the surface layer around all geometry objects.

Remarks
Contacts are allowed to sink into the surface layer up to the given depth before coming to rest.
Parameters
depthThe default value is zero.
Remarks
Increasing this to some small value (e.g. 0.001) can help prevent jittering problems due to contacts being repeatedly made and broken.
void dWorldSetData ( dWorldID  world,
void *  data 
)

Set the user-data pointer.

Parameters
worldthe world to set the data on
data
void dWorldSetERP ( dWorldID  ,
dReal  erp 
)

Set the global ERP value, that controls how much error correction is performed in each time step.

Parameters
dWorldIDthe identifier of the world.
erpTypical values are in the range 0.1–0.8. The default is 0.2.
void dWorldSetGravity ( dWorldID  ,
dReal  x,
dReal  y,
dReal  z 
)

Set the world's global gravity vector.

The units are m/s^2, so Earth's gravity vector would be (0,0,-9.81), assuming that +z is up. The default is no gravity, i.e. (0,0,0).

void dWorldSetQuickStepNumIterations ( dWorldID  ,
int  num 
)

Set the number of iterations that the QuickStep method performs per step.

Remarks
More iterations will give a more accurate solution, but will take longer to compute.
Parameters
numThe default is 20 iterations.
void dWorldSetQuickStepW ( dWorldID  ,
dReal  over_relaxation 
)

Set the SOR over-relaxation parameter.

Parameters
over_relaxationvalue to use by SOR
void dWorldSetStepIslandsProcessingMaxThreadCount ( dWorldID  w,
unsigned  count 
)

Set maximum threads to be used for island stepping.

The actual number of threads that is going to be used will be the minimum of this limit and number of threads in the threading pool. By default there is no limit (dWORLDSTEP_THREADCOUNT_UNLIMITED).

Warning
WARNING! Running island stepping in multiple threads requires allocating individual stepping memory buffer for each of those threads. The size of buffers allocated is the size needed to handle the largest island in the world.

Note: Setting a limit for island stepping does not affect threading at lower levels in stepper functions. The sub-calls scheduled from them can be executed in as many threads as there are available in the pool.

Parameters
wThe world affected
countThread count limit value for island stepping
See Also
dWorldGetStepIslandsProcessingMaxThreadCount
int dWorldSetStepMemoryManager ( dWorldID  w,
const dWorldStepMemoryFunctionsInfo memfuncs 
)

Set memory manager for world to be used with simulation stepping functions.

The function allows to customize memory manager to be used for internal memory allocation during simulation for a world. By default, dAlloc/dRealloc/dFree based memory manager is used.

Passing memfuncs argument as NULL results in memory manager being reset to default one as if the world has been just created. The content of memfuncs structure is copied internally and does not need to remain valid after the call returns.

If the world uses working memory sharing, changing memory manager affects all the worlds linked together.

Failure result status means a memory allocation failure.

Parameters
wThe world to change memory reservation policy for.
memfuncsNull or a pointer to memory manager descriptor structure.
Returns
1 for success and 0 for failure.
See Also
dWorldUseSharedWorkingMemory
int dWorldSetStepMemoryReservationPolicy ( dWorldID  w,
const dWorldStepReserveInfo policyinfo 
)

Set memory reservation policy for world to be used with simulation stepping functions.

The function allows to customize reservation policy to be used for internal memory which is allocated to aid simulation for a world. By default, values of dWORLDSTEP_RESERVEFACTOR_DEFAULT and dWORLDSTEP_RESERVESIZE_DEFAULT are used.

Passing policyinfo argument as NULL results in reservation policy being reset to defaults as if the world has been just created. The content of policyinfo structure is copied internally and does not need to remain valid after the call returns.

If the world uses working memory sharing, changing memory reservation policy affects all the worlds linked together.

Failure result status means a memory allocation failure.

Parameters
wThe world to change memory reservation policy for.
policyinfoNull or a pointer to policy descriptor structure.
Returns
1 for success and 0 for failure.
See Also
dWorldUseSharedWorkingMemory
void dWorldSetStepThreadingImplementation ( dWorldID  w,
const dThreadingFunctionsInfo functions_info,
dThreadingImplementationID  threading_impl 
)

Assign threading implementation to be used for [quick]stepping the world.

Warning
It is not recommended to assign the same threading implementation to different worlds if they are going to be called in parallel. In particular this makes resources preallocation for threaded calls to lose its sense. Built-in threading implementation is likely to crash if misused this way.
Parameters
wThe world to change threading implementation for.
functions_infoPointer to threading functions structure
threading_implID of threading implementation object
int dWorldStep ( dWorldID  w,
dReal  stepsize 
)

Step the world.

This uses a "big matrix" method that takes time on the order of m^3 and memory on the order of m^2, where m is the total number of constraint rows. For large systems this will use a lot of memory and can be very slow, but this is currently the most accurate method.

Failure result status means that the memory allocation has failed for operation. In such a case all the objects remain in unchanged state and simulation can be retried as soon as more memory is available.

Parameters
wThe world to be stepped
stepsizeThe number of seconds that the simulation has to advance.
Returns
1 for success and 0 for failure
int dWorldUseSharedWorkingMemory ( dWorldID  w,
dWorldID  from_world 
)

Set the world to use shared working memory along with another world.

The worlds allocate working memory internally for simulation stepping. This memory is cached among the calls to dWordStep and dWorldQuickStep. Similarly, several worlds can be set up to share this memory caches thus reducing overall memory usage by cost of making worlds inappropriate for simultaneous simulation in multiple threads.

If null value is passed for from_world parameter the world is detached from sharing and returns to defaults for working memory, reservation policy and memory manager as if just created. This can also be used to enable use of shared memory for a world that has already had working memory allocated privately. Normally using shared memory after a world has its private working memory allocated is prohibited.

Allocation policy used can only increase world's internal reserved memory size and never decreases it. dWorldCleanupWorkingMemory can be used to release working memory for a world in case if number of objects/joint decreases significantly in it.

With sharing working memory worlds also automatically share memory reservation policy and memory manager. Thus, these parameters need to be customized for initial world to be used as sharing source only.

If worlds share working memory they must also use compatible threading implementations (i.e. it is illegal for one world to perform stepping with self-threaded implementation when the other world is assigned a multi-threaded implementation). For more information read section about threading approaches in ODE.

Failure result status means a memory allocation failure.

Parameters
wThe world to use the shared memory with.
from_worldNull or the world the shared memory is to be used from.
Returns
1 for success and 0 for failure.
See Also
dWorldCleanupWorkingMemory
dWorldSetStepMemoryReservationPolicy
dWorldSetStepMemoryManager