org.odejava
Class World

java.lang.Object
  extended by org.odejava.World

public class World
extends Object

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.

Usage Notes

Odejava supports only single world for now. Support for multiple worlds is added later. Only latest created World class will be used on Odejava. Create this class only once!

The default value for contact surface thickness is zero. This can cause floating point accuracy problems and result in visible jitter of the objects. It is recommended that a small value of around 0.001 be set to avoid this problem.

Unimplemented

Created 16.12.2003 (dd.mm.yyyy)

Author:
Jani Laakso E-mail: jani.laakso@itmill.com see http://odejava.dev.java.net

Field Summary
protected  List<Body> bodyList
           
protected  Map<String,Body> bodyMap
           
protected  boolean deleted
          Flag indicating that this world has been requested to be deleted.
 
Constructor Summary
World()
          Create a new, empty world.
 
Method Summary
protected  void addBody(Body body)
          Internal method to add the given body to the World.
 boolean containsBody(String name)
          Returns true if the space contains a Body with the given name.
 void delete()
          Request deletion of this world.
 void deleteBody(Body body)
          Removes the Body from this world and deletes it using Body.delete() .
 Body findGeomBody(Geom geom)
          Returns the Geom's parent Body, or null if it doesn't have a parent.
 float getAngularVelocityDisableThreshold()
          Get the threshold for angular velocity at which a body will be automatically disabled.
 int getAutoEnableDepthSF1()
           
 List<Body> getBodies()
          Returns a list of bodies that are in this World
 Body getBody(String name)
          Get body by name.
 float getConstantForceMix()
          Get the amount of the constant force mix parameter currently set for positions between the two stops.
 float getContactSurfaceThickness()
          Get the currently set value of the world's contact surface layer thickness.
 float getErrorReductionParameter()
          Get the amount of the error reduction parameter currently set.
 org.openmali.vecmath2.Vector3f getGravity()
          Get the gravity vector for the world.
 void getGravity(float[] val)
          Get the vector for the current gravity and place it in the user-provided array.
 org.openmali.vecmath2.Vector3f getGravity(org.openmali.vecmath2.Vector3f val)
          Get the vector for the current gravity and place it in the user-provided data structure.
 org.odejava.ode.SWIGTYPE_p_dWorldID getId()
           
 float getLinearVelocityDisableThreshold()
          Get the threshold for linear velocity at which a body will be automatically disabled.
 float getMaxCorrectionVelocity()
          Get the current maximum correction velocity used during cpntacts.
 int getStepDisableThreshold()
          Get the threshold for the number of steps at which a body will be automatically disabled.
 int getStepInteractions()
           
 float getStepSize()
           
 float getTimeDisableThreshold()
          Get the threshold for the evaluation time at which a body will be automatically disabled.
 boolean isAutoDisablingBodies()
          Check to see the current state of the auto disable functionality.
 void quickStep()
          Step uses ODE's dWorldQuickStep with the predefined step size and number of iterations.
 void quickStep(float stepTime)
          Step uses ODE's dWorldQuickStep with the passed in step size.
protected  void removeBody(Body body)
          Internal method to remove the given body from the World.
 void renameBody(String oldName, String newName)
          Updates the bodymap to reflect a name change of a body
 void setAngularVelocityDisableThreshold(float vel)
          Set the threshold for the angular velocity that will cause a body to be disabled.
 void setAutoDisableBodies(boolean state)
          Control whether the world should allow auto-disable of bodies.
 void setAutoEnableDepthSF1(int autoEnableDepth)
           
 void setConstantForceMix(float force)
          Set the amount of constant force to mix into the system when the bodies are not at a stop.
 void setContactSurfaceThickness(float depth)
          Set the contact surface layer thickness around all geometry objects.
 void setErrorReductionParameter(float erp)
          Set the amount of error reduction.
 void setGravity(float x, float y, float z)
          Set the gravity vector to be applied to this world
 void setGravity(org.openmali.vecmath2.Vector3f gravity)
          Set the gravity vector to be applied to this world
 void setLinearVelocityDisableThreshold(float vel)
          Set the threshold for the linear velocity that will cause a body to be disabled.
 void setMaxCorrectionVelocity(float vel)
          Set the maximum correction velocity that is allowed during a contact.
 void setStepDisableThreshold(int steps)
          Set the number of evaluation steps before an umoving body is disabled.
 void setStepInteractions(int stepInteractions)
          Number of interactions, higher gives better accuracy but lower speed in case of many simultaneous collisions.
 void setStepSize(float stepSize)
          Step size, higher decreases accuracy but gives more speed.
 void setTimeDisableThreshold(float time)
          Set the total amount of evaluation time an umoving body is disabled.
 void step()
          Step uses ODE's dWorldStep with the predefined step size
 void step(float stepTime)
          Step uses ODE's dWorldStep with the passed in step size.
 void stepFast()
          StepFast uses ODE's dWorldStepFast1.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

bodyList

protected List<Body> bodyList

bodyMap

protected Map<String,Body> bodyMap

deleted

protected boolean deleted
Flag indicating that this world has been requested to be deleted. After this is set to true, none of the methods should allow further calls to ODE as the values are invalid, and may well cause a crash of the library or other strange error.

Constructor Detail

World

public World()
Create a new, empty world. StepSize is initialised to 0.05 seconds and 10 iterations per step.

Method Detail

setGravity

public void setGravity(float x,
                       float y,
                       float z)
Set the gravity vector to be applied to this world

Parameters:
x - The x component of the gravity vector
y - The y component of the gravity vector
z - The z component of the gravity vector

setGravity

public final void setGravity(org.openmali.vecmath2.Vector3f gravity)
Set the gravity vector to be applied to this world

Parameters:
gravity - The gravity vector

getGravity

public org.openmali.vecmath2.Vector3f getGravity()
Get the gravity vector for the world. A new vector instance will be created for each request. This is identical to calling getGravity(null).


getGravity

public org.openmali.vecmath2.Vector3f getGravity(org.openmali.vecmath2.Vector3f val)
Get the vector for the current gravity and place it in the user-provided data structure. If the user-provided data structure is null, then a new instance is created and returned, otherwise the user provided structure is used as the return value.

Parameters:
val - An object to place the values into or null
Returns:
Either the val parameter or a new object

getGravity

public void getGravity(float[] val)
Get the vector for the current gravity and place it in the user-provided array. The array provided must be at least length 3.

Parameters:
val - The array to copy the value into

getId

public final org.odejava.ode.SWIGTYPE_p_dWorldID getId()

stepFast

public void stepFast()
StepFast uses ODE's dWorldStepFast1.


step

public void step()
Step uses ODE's dWorldStep with the predefined step size


step

public void step(float stepTime)
Step uses ODE's dWorldStep with the passed in step size. This is would be better to be used in variable-framerate systems where the step size is not known ahead of time.

Parameters:
stepTime - The time to use for this increment, in seconds

quickStep

public void quickStep()
Step uses ODE's dWorldQuickStep with the predefined step size and number of iterations.


quickStep

public void quickStep(float stepTime)
Step uses ODE's dWorldQuickStep with the passed in step size. This is would be better to be used in variable-framerate systems where the step size is not known ahead of time.

Parameters:
stepTime - The time to use for this increment, in seconds

delete

public void delete()
Request deletion of this world. Any further calls to this world instance after this has been called will be met with an error.


getStepInteractions

public int getStepInteractions()
Returns:
Returns the stepInteractions.

setStepInteractions

public void setStepInteractions(int stepInteractions)
Number of interactions, higher gives better accuracy but lower speed in case of many simultaneous collisions.

Parameters:
stepInteractions - The stepInteractions to set.

getStepSize

public float getStepSize()
Returns:
Returns the stepSize.

setStepSize

public void setStepSize(float stepSize)
Step size, higher decreases accuracy but gives more speed.

Parameters:
stepSize - The stepSize to set, in seconds

addBody

protected void addBody(Body body)
Internal method to add the given body to the World. This is done automatically in the constructor of the Body.

Parameters:
body - the Body to add

removeBody

protected void removeBody(Body body)
Internal method to remove the given body from the World. This is done automatically in the delete() method of the Body.

Parameters:
body - the Body to remove

getBodies

public List<Body> getBodies()
Returns a list of bodies that are in this World

Returns:
a list of bodies that are in this World

getBody

public Body getBody(String name)
Get body by name. If the name is not known then this will return null.

Parameters:
name - The name to look up the body by
Returns:
The body object corresponding to the name, or null if none

renameBody

public void renameBody(String oldName,
                       String newName)
Updates the bodymap to reflect a name change of a body

Parameters:
oldName - the old body name
newName - the new body name

containsBody

public boolean containsBody(String name)
Returns true if the space contains a Body with the given name.

Parameters:
name - the name of the Body
Returns:
true if the space contains a Body with the given name.

deleteBody

public void deleteBody(Body body)
Removes the Body from this world and deletes it using Body.delete() .

Throws:
IllegalArgumentException - if the given Body does not exist in this World.
See Also:
Body.delete()

findGeomBody

public Body findGeomBody(Geom geom)
Returns the Geom's parent Body, or null if it doesn't have a parent. This is an O(1) operation as all Bodies must be checked and may execulte slowly.

Parameters:
geom - The Geom whos parent Body will be seeked
Returns:
the Geom's parent Body, or null if it doesn't have a parent.

setAutoEnableDepthSF1

public void setAutoEnableDepthSF1(int autoEnableDepth)

getAutoEnableDepthSF1

public int getAutoEnableDepthSF1()

setContactSurfaceThickness

public void setContactSurfaceThickness(float depth)
Set the contact surface layer thickness around all geometry objects. Contacts are allowed to sink into the surface layer up to the given depth before coming to rest.

The value provided should be non-negative.

Parameters:
depth - The depth value to allow

getContactSurfaceThickness

public float getContactSurfaceThickness()
Get the currently set value of the world's contact surface layer thickness.

Returns:
A non-negative value representing the thickness

setAutoDisableBodies

public void setAutoDisableBodies(boolean state)
Control whether the world should allow auto-disable of bodies. A value of true will enable the auto disable ability. Whether individual bodies are disabled or not depends on the settings of the individual thresholds (which can be set by other methods).

Parameters:
state - True to enable auto disabling of bodies, false to disable

isAutoDisablingBodies

public boolean isAutoDisablingBodies()
Check to see the current state of the auto disable functionality.

Returns:
true if the auto-disable mode is on, false otherwise

setLinearVelocityDisableThreshold

public void setLinearVelocityDisableThreshold(float vel)
Set the threshold for the linear velocity that will cause a body to be disabled. Once the velocity falls below this value, the body will be subject to being disabled. The threshold is only used if the auto disable capability is enabled.

Parameters:
vel - The speed below which the body is disabled

getLinearVelocityDisableThreshold

public float getLinearVelocityDisableThreshold()
Get the threshold for linear velocity at which a body will be automatically disabled.

Returns:
The current threshold value

setAngularVelocityDisableThreshold

public void setAngularVelocityDisableThreshold(float vel)
Set the threshold for the angular velocity that will cause a body to be disabled. Once the velocity falls below this value, the body will be subject to being disabled. The threshold is only used if the auto disable capability is enabled.

Parameters:
vel - The speed below which the body is disabled

getAngularVelocityDisableThreshold

public float getAngularVelocityDisableThreshold()
Get the threshold for angular velocity at which a body will be automatically disabled.

Returns:
The current threshold value

setStepDisableThreshold

public void setStepDisableThreshold(int steps)
Set the number of evaluation steps before an umoving body is disabled. If the body has not moved in this number of steps, it is automatically disabled. This setting is only used if the auto disable capabilities is enabled. If the number of steps is negative or zero, bodies cannot be disabled using this way.

Parameters:
steps - The number of evaluation steps to use or negative to disable

getStepDisableThreshold

public int getStepDisableThreshold()
Get the threshold for the number of steps at which a body will be automatically disabled.

Returns:
The current threshold value

setTimeDisableThreshold

public void setTimeDisableThreshold(float time)
Set the total amount of evaluation time an umoving body is disabled. If the body has not moved in this time, it is automatically disabled. This setting is only used if the auto disable capabilities is enabled. If the time is negative or zero, bodies cannot be disabled using this way.

Parameters:
time - The amount of time in seconds or negative to disable

getTimeDisableThreshold

public float getTimeDisableThreshold()
Get the threshold for the evaluation time at which a body will be automatically disabled.

Returns:
The current threshold value

setConstantForceMix

public void setConstantForceMix(float force)
Set the amount of constant force to mix into the system when the bodies are not at a stop. This value has no effect when the bodies are at one of the two stops.

Parameters:
force - The amount of force to use

getConstantForceMix

public float getConstantForceMix()
Get the amount of the constant force mix parameter currently set for positions between the two stops.

Returns:
The current constant force mix

setErrorReductionParameter

public void setErrorReductionParameter(float erp)
Set the amount of error reduction. This value should be between 0 and 1. 0 is no reduction at all, 1 is full correction in a single step.

Parameters:
erp - The amount of error reduction to use

getErrorReductionParameter

public float getErrorReductionParameter()
Get the amount of the error reduction parameter currently set. This value will be between 0 and 1. 0 is no bounce at all, 1 is full bounce.

Returns:
A value between 0 and 1

setMaxCorrectionVelocity

public void setMaxCorrectionVelocity(float vel)
Set the maximum correction velocity that is allowed during a contact. The default value is infinite, meaning deeply embedded objects will pop instantly back to the surface. Although negative values are allowed, this will force the objects to further embed themselves, which is not a good thing.

Parameters:
vel - The speed at which objects should correct contact problems

getMaxCorrectionVelocity

public float getMaxCorrectionVelocity()
Get the current maximum correction velocity used during cpntacts. The default value is Float.POSITIVE_INFINITY.

Returns:
The correction velocity set. No range limits