World

Functions
ODE_API dWorldID	dWorldCreate (void)
	Create a new, empty world and return its ID number.
ODE_API void	dWorldDestroy (dWorldID world)
	Destroy a world and everything in it.
ODE_API void	dWorldSetGravity (dWorldID, dReal x, dReal y, dReal z)
	Set the world's global gravity vector.
ODE_API void	dWorldGetGravity (dWorldID, dVector3 gravity)
	Get the gravity vector for a given world.
ODE_API void	dWorldSetERP (dWorldID, dReal erp)
	Set the global ERP value, that controls how much error correction is performed in each time step.
ODE_API dReal	dWorldGetERP (dWorldID)
	Get the error reduction parameter.
ODE_API void	dWorldSetCFM (dWorldID, dReal cfm)
	Set the global CFM (constraint force mixing) value.
ODE_API dReal	dWorldGetCFM (dWorldID)
	Get the constraint force mixing value.
ODE_API void	dWorldStep (dWorldID, dReal stepsize)
	Step the world.
ODE_API void	dWorldImpulseToForce (dWorldID, dReal stepsize, dReal ix, dReal iy, dReal iz, dVector3 force)
	Converts an impulse to a force.
ODE_API void	dWorldQuickStep (dWorldID w, dReal stepsize)
	Step the world.
ODE_API void	dWorldSetQuickStepNumIterations (dWorldID, int num)
	Set the number of iterations that the QuickStep method performs per step.
ODE_API int	dWorldGetQuickStepNumIterations (dWorldID)
	Get the number of iterations that the QuickStep method performs per step.
ODE_API void	dWorldSetQuickStepW (dWorldID, dReal over_relaxation)
	Set the SOR over-relaxation parameter.
ODE_API dReal	dWorldGetQuickStepW (dWorldID)
	Get the SOR over-relaxation parameter.
ODE_API void	dWorldSetContactMaxCorrectingVel (dWorldID, dReal vel)
	Set the maximum correcting velocity that contacts are allowed to generate.
ODE_API dReal	dWorldGetContactMaxCorrectingVel (dWorldID)
	Get the maximum correcting velocity that contacts are allowed to generated.
ODE_API void	dWorldSetContactSurfaceLayer (dWorldID, dReal depth)
	Set the depth of the surface layer around all geometry objects.
ODE_API dReal	dWorldGetContactSurfaceLayer (dWorldID)
	Get the depth of the surface layer around all geometry objects.
ODE_API void	dWorldStepFast1 (dWorldID, dReal stepsize, int maxiterations)
	Step the world using the StepFast1 algorithm.

---

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

ODE_API dWorldID dWorldCreate

(

void

)

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

Returns:

an identifier

ODE_API 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:

world

the identifier for the world the be destroyed.

ODE_API dReal dWorldGetCFM

(

dWorldID

)

Get the constraint force mixing value.

Returns:

CFM value

ODE_API dReal dWorldGetContactSurfaceLayer

(

dWorldID

)

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

Returns:

the depth

ODE_API dReal dWorldGetERP

(

dWorldID

)

Get the error reduction parameter.

Returns:

ERP value

ODE_API int dWorldGetQuickStepNumIterations

(

dWorldID

)

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

Returns:

nr of iterations

ODE_API dReal dWorldGetQuickStepW

(

dWorldID

)

Get the SOR over-relaxation parameter.

Returns:

the over-relaxation setting

ODE_API 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.

ODE_API void dWorldQuickStep	(	dWorldID	w,
		dReal	stepsize
	)

Step the world.

Remarks:

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.

ODE_API void dWorldSetCFM	(	dWorldID	,
		dReal	cfm
	)

Set the global CFM (constraint force mixing) value.

Parameters:

cfm

Typical 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.

ODE_API void dWorldSetContactMaxCorrectingVel	(	dWorldID	,
		dReal	vel
	)

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

Parameters:

vel

The default value is infinity (i.e. no limit).

Remarks:

Reducing this value can help prevent "popping" of deeply embedded objects.

ODE_API 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:

depth

The 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.

ODE_API void dWorldSetERP	(	dWorldID	,
		dReal	erp
	)

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

Parameters:

	dWorldID	the identifier of the world.
	erp	Typical values are in the range 0.1--0.8. The default is 0.2.

ODE_API 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).

ODE_API 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:

num

The default is 20 iterations.

ODE_API void dWorldSetQuickStepW	(	dWorldID	,
		dReal	over_relaxation
	)

Set the SOR over-relaxation parameter.

Parameters:

over_relaxation

value to use by SOR

ODE_API void dWorldStep	(	dWorldID	,
		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.

Parameters:

stepsize

The number of seconds that the simulation has to advance.

ODE_API void dWorldStepFast1	(	dWorldID	,
		dReal	stepsize,
		int	maxiterations
	)

Step the world using the StepFast1 algorithm.

Parameters:

	stepsize	the nr of seconds to advance the simulation.
	maxiterations	The number of iterations to perform.

---