org.ode4j.ode
Interface DWorld

public interface DWorld

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.

Note:

The velocities are damped after the stepper function has moved the object. Otherwise the damping could introduce errors in joints. First the joint constraints are processed by the stepper (moving the body), then the damping is applied.

, The damping happens right after the moved callback is called; this way it still possible use the exact velocities the body has acquired during the step. You can even use the callback to create your own customized damping.

Nested Class Summary

static class	DWorld.DWorldStepMemoryFunctionsInfo Deprecated. Do not use ! (TZ)
static class	DWorld.DWorldStepReserveInfo Memory reservation policy descriptor structure for world stepping functions.

Field Summary

static double	dWORLDSTEP_RESERVEFACTOR_DEFAULT
static int	dWORLDSTEP_RESERVESIZE_DEFAULT

Method Summary

void	cleanupWorkingMemory() Release internal working memory allocated for world The worlds allocate working memory internally for simulation stepping.
void	destroy() Destroy a world and everything in it.
void	DESTRUCTOR()
double	getAngularDamping() Get the world's angular damping scale.
double	getAngularDampingThreshold() Get the world's angular damping threshold.
double	getAutoDisableAngularAverageThreshold() Deprecated. Not implemented in ODE.
double	getAutoDisableAngularThreshold() Get auto disable angular threshold for newly created bodies.
int	getAutoDisableAverageSamplesCount() Get auto disable sample count for newly created bodies.
boolean	getAutoDisableFlag() Get auto disable flag for newly created bodies.
double	getAutoDisableLinearAverageThreshold() Deprecated. Not implemented in ODE.
double	getAutoDisableLinearThreshold() Get auto disable linear threshold for newly created bodies.
int	getAutoDisableSteps() Get auto disable steps for newly created bodies.
double	getAutoDisableTime() Get auto disable time for newly created bodies.
double	getCFM() Get the constraint force mixing value.
double	getContactMaxCorrectingVel() Get the maximum correcting velocity that contacts are allowed to generated.
double	getContactSurfaceLayer() Get the depth of the surface layer around all geometry objects.
double	getERP() Get the error reduction parameter.
void	getGravity(DVector3 g) Get the gravity vector for a given world.
double	getLinearDamping() Get the world's linear damping scale.
double	getLinearDampingThreshold() Get the world's linear damping threshold.
double	getMaxAngularSpeed() Get the default maximum angular speed.
int	getQuickStepNumIterations() Get the number of iterations that the QuickStep method performs per step.
double	getQuickStepW() Get the SOR over-relaxation parameter.
void	impulseToForce(double stepsize, double ix, double iy, double iz, DVector3 force) Converts an impulse to a force.
boolean	quickStep(double stepsize) Quick-step the world.
void	setAngularDamping(double scale) Set the world's angular damping scale.
void	setAngularDampingThreshold(double threshold) Set the world's angular damping threshold.
void	setAutoDisableAngularAverageThreshold(double angular_average_threshold) Deprecated. Not implemented in ODE.
void	setAutoDisableAngularThreshold(double threshold) Set auto disable angular threshold for newly created bodies.
void	setAutoDisableAverageSamplesCount(int average_samples_count) Set auto disable average sample count for newly created bodies.
void	setAutoDisableFlag(boolean do_auto_disable) Set auto disable flag for newly created bodies.
void	setAutoDisableLinearAverageThreshold(double linear_average_threshold) Deprecated. Not implemented in ODE.
void	setAutoDisableLinearThreshold(double threshold) Set auto disable linear threshold for newly created bodies.
void	setAutoDisableSteps(int steps) Set auto disable steps for newly created bodies.
void	setAutoDisableTime(double time) Set auto disable time for newly created bodies.
void	setCFM(double cfm) Set the global CFM (constraint force mixing) value.
void	setContactMaxCorrectingVel(double vel) Set the maximum correcting velocity that contacts are allowed to generate.
void	setContactSurfaceLayer(double depth) Set the depth of the surface layer around all geometry objects.
void	setDamping(double linear_scale, double angular_scale) Convenience function to set body linear and angular scales.
void	setERP(double erp) Set the global ERP value, that controls how much error correction is performed in each time step.
void	setGravity(double x, double y, double z) Set the world's global gravity vector.
void	setGravity(DVector3C g) Set the world's global gravity vector.
void	setLinearDamping(double scale) Set the world's linear damping scale.
void	setLinearDampingThreshold(double threshold) Set the world's linear damping threshold.
void	setMaxAngularSpeed(double max_speed) Set the default maximum angular speed for new bodies.
void	setQuickStepNumIterations(int num) Set the number of iterations that the QuickStep method performs per step.
void	setQuickStepW(double over_relaxation) Set the SOR over-relaxation parameter
boolean	setStepMemoryManager(DWorld.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.
boolean	setStepMemoryReservationPolicy(DWorld.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.
void	step(double stepsize) Step the world.
boolean	useSharedWorkingMemory(DWorld from_world) Set the world to use shared working memory along with another world.

Field Detail

dWORLDSTEP_RESERVEFACTOR_DEFAULT

static final double dWORLDSTEP_RESERVEFACTOR_DEFAULT

See Also:

Constant Field Values

dWORLDSTEP_RESERVESIZE_DEFAULT

static final int dWORLDSTEP_RESERVESIZE_DEFAULT

See Also:

Constant Field Values

Method Detail

DESTRUCTOR

void DESTRUCTOR()

setGravity

void setGravity(double x,
                double y,
                double 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).

setGravity

void setGravity(DVector3C g)

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

getGravity

void getGravity(DVector3 g)

Get the gravity vector for a given world.

setERP

void setERP(double erp)

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

Parameters:

erp - Typical values are in the range 0.1--0.8. The default is 0.2.

getERP

double getERP()

Get the error reduction parameter.

Returns:

ERP value

setCFM

void setCFM(double cfm)

Set the global CFM (constraint force mixing) value.

Parameters:

cfm - Typical values are in the range @m{10^{-9}} -- 1. The default is 10^-5 if single precision is being used, or 10^-10 if double precision is being used.

getCFM

double getCFM()

Get the constraint force mixing value.

Returns:

CFM value

useSharedWorkingMemory

boolean useSharedWorkingMemory(DWorld 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. Failure result status means a memory allocation failure.

Parameters:

from_world - Null or the world the shared memory is to be used from.

Returns:

1 for success and 0 for failure.

See Also:

cleanupWorkingMemory(), setStepMemoryReservationPolicy(DWorldStepReserveInfo), setStepMemoryManager(DWorldStepMemoryFunctionsInfo)

cleanupWorkingMemory

void cleanupWorkingMemory()

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.

See Also:

useSharedWorkingMemory(DWorld), setStepMemoryReservationPolicy(DWorldStepReserveInfo), setStepMemoryManager(DWorldStepMemoryFunctionsInfo)

setStepMemoryReservationPolicy

boolean setStepMemoryReservationPolicy(DWorld.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:

policyinfo - Null or a pointer to policy descriptor structure.

Returns:

1 for success and 0 for failure.

See Also:

useSharedWorkingMemory(DWorld)

setStepMemoryManager

boolean setStepMemoryManager(DWorld.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:

memfuncs - Null or a pointer to memory manager descriptor structure.

Returns:

1 for success and 0 for failure.

See Also:

useSharedWorkingMemory(DWorld)

step

void step(double 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:

stepsize - The number of seconds that the simulation has to advance.

quickStep

boolean quickStep(double 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.

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

stepsize - The number of seconds that the simulation has to advance.

Returns:

1 for success and 0 for failure

impulseToForce

void impulseToForce(double stepsize,
                    double ix,
                    double iy,
                    double iz,
                    DVector3 force)

Converts an impulse to a force. 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.

setQuickStepNumIterations

void setQuickStepNumIterations(int num)

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

Parameters:

num - The default is 20 iterations.

Remark:

More iterations will give a more accurate solution, but will take longer to compute.

getQuickStepNumIterations

int getQuickStepNumIterations()

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

Returns:

nr of iterations

setQuickStepW

void setQuickStepW(double over_relaxation)

Set the SOR over-relaxation parameter

Parameters:

over_relaxation - value to use by SOR

getQuickStepW

double getQuickStepW()

Get the SOR over-relaxation parameter.

Returns:

the over-relaxation setting

setAutoDisableLinearThreshold

void setAutoDisableLinearThreshold(double threshold)

Set auto disable linear threshold for newly created bodies.

Parameters:

threshold - default is 0.01

getAutoDisableLinearThreshold

double getAutoDisableLinearThreshold()

Get auto disable linear threshold for newly created bodies.

Returns:

the threshold

setAutoDisableAngularThreshold

void setAutoDisableAngularThreshold(double threshold)

Set auto disable angular threshold for newly created bodies.

Parameters:

threshold - default is 0.01

getAutoDisableAngularThreshold

double getAutoDisableAngularThreshold()

Get auto disable angular threshold for newly created bodies.

Returns:

the threshold

getAutoDisableLinearAverageThreshold

double getAutoDisableLinearAverageThreshold()

Deprecated. Not implemented in ODE.

Get auto disable linear average threshold for newly created bodies.

Returns:

the threshold

setAutoDisableLinearAverageThreshold

void setAutoDisableLinearAverageThreshold(double linear_average_threshold)

Deprecated. Not implemented in ODE.

Set auto disable linear average threshold for newly created bodies.

Parameters:

linear_average_threshold - default is 0.01

getAutoDisableAngularAverageThreshold

double getAutoDisableAngularAverageThreshold()

Deprecated. Not implemented in ODE.

Get auto disable angular average threshold for newly created bodies.

Returns:

the threshold

setAutoDisableAngularAverageThreshold

void setAutoDisableAngularAverageThreshold(double angular_average_threshold)

Deprecated. Not implemented in ODE.

Set auto disable angular average threshold for newly created bodies.

Parameters:

angular_average_threshold - default is 0.01

getAutoDisableAverageSamplesCount

int getAutoDisableAverageSamplesCount()

Get auto disable sample count for newly created bodies.

Returns:

number of samples used

setAutoDisableAverageSamplesCount

void setAutoDisableAverageSamplesCount(int average_samples_count)

Set auto disable average sample count for newly created bodies.

Parameters:

average_samples_count - Default is 1, meaning only instantaneous velocity is used. Set to zero to disable sampling and thus prevent any body from auto-disabling.

setContactSurfaceLayer

void setContactSurfaceLayer(double depth)

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

Parameters:

depth - The default value is zero.

Remark:

Contacts are allowed to sink into the surface layer up to the given depth before coming to rest., Increasing this to some small value (e.g. 0.001) can help prevent jittering problems due to contacts being repeatedly made and broken.

getContactSurfaceLayer

double getContactSurfaceLayer()

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

Returns:

the depth

setContactMaxCorrectingVel

void setContactMaxCorrectingVel(double vel)

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

Parameters:

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

Remark:

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

getContactMaxCorrectingVel

double getContactMaxCorrectingVel()

Get the maximum correcting velocity that contacts are allowed to generated.

destroy

void destroy()

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

getAutoDisableSteps

int getAutoDisableSteps()

Get auto disable steps for newly created bodies.

Returns:

nr of steps

setAutoDisableSteps

void setAutoDisableSteps(int steps)

Set auto disable steps for newly created bodies.

Parameters:

steps - default is 10

getAutoDisableTime

double getAutoDisableTime()

Get auto disable time for newly created bodies.

Returns:

nr of seconds

setAutoDisableTime

void setAutoDisableTime(double time)

Set auto disable time for newly created bodies.

Parameters:

time - default is 0 seconds

getAutoDisableFlag

boolean getAutoDisableFlag()

Get auto disable flag for newly created bodies.

Returns:

0 or 1

setAutoDisableFlag

void setAutoDisableFlag(boolean do_auto_disable)

Set auto disable flag for newly created bodies.

Parameters:

do_auto_disable - default is false.

getLinearDampingThreshold

double getLinearDampingThreshold()

Get the world's linear damping threshold.

setLinearDampingThreshold

void setLinearDampingThreshold(double threshold)

Set the world's linear damping threshold.

Parameters:

threshold - The damping won't be applied if the linear speed is below this threshold. Default is 0.01.

getAngularDampingThreshold

double getAngularDampingThreshold()

Get the world's angular damping threshold.

setAngularDampingThreshold

void setAngularDampingThreshold(double threshold)

Set the world's angular damping threshold.

Parameters:

threshold - The damping won't be applied if the angular speed is below this threshold. Default is 0.01.

getLinearDamping

double getLinearDamping()

Get the world's linear damping scale.

setLinearDamping

void setLinearDamping(double scale)

Set the world's linear damping scale.

Parameters:

scale - The linear damping scale that is to be applied to bodies. Default is 0 (no damping). Should be in the interval [0, 1].

getAngularDamping

double getAngularDamping()

Get the world's angular damping scale.

setAngularDamping

void setAngularDamping(double scale)

Set the world's angular damping scale.

Parameters:

scale - The angular damping scale that is to be applied to bodies. Default is 0 (no damping). Should be in the interval [0, 1].

setDamping

void setDamping(double linear_scale,
                double angular_scale)

Convenience function to set body linear and angular scales.

Parameters:

linear_scale - The linear damping scale that is to be applied to bodies.

angular_scale - The angular damping scale that is to be applied to bodies.

getMaxAngularSpeed

double getMaxAngularSpeed()

Get the default maximum angular speed.

See Also:

DBody.getMaxAngularSpeed()

setMaxAngularSpeed

void setMaxAngularSpeed(double max_speed)

Set the default maximum angular speed for new bodies.

See Also:

DBody.setMaxAngularSpeed(double)