com.jme3.bullet

Class PhysicsSpace

java.lang.Object

com.jme3.bullet.PhysicsSpace

public class PhysicsSpace
extends java.lang.Object

A jbullet-jme physics space with its own btDynamicsWorld.

Author:

normenhansen

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PhysicsSpace.BroadphaseType Enumerate the available acceleration structures for broadphase collision detection.

Field Summary

Fields

Modifier and Type	Field and Description
static int	AXIS_X index of the X axis
static int	AXIS_Y index of the Y axis
static int	AXIS_Z index of the Z axis

Constructor Summary

Constructors

Constructor and Description
PhysicsSpace() Instantiate a PhysicsSpace.
PhysicsSpace(PhysicsSpace.BroadphaseType broadphaseType) Instantiate a PhysicsSpace.
PhysicsSpace(com.jme3.math.Vector3f worldMin, com.jme3.math.Vector3f worldMax) Instantiate a PhysicsSpace.
PhysicsSpace(com.jme3.math.Vector3f worldMin, com.jme3.math.Vector3f worldMax, PhysicsSpace.BroadphaseType broadphaseType) Instantiate a PhysicsSpace.

Method Summary

Modifier and Type	Method and Description
void	add(java.lang.Object obj) Add the specified object to this space.
void	addAll(com.jme3.scene.Spatial spatial) Add all collision objects and joints in the specified subtree of the scene graph to this space (e.g.
void	addCollisionGroupListener(PhysicsCollisionGroupListener listener, int collisionGroup) Register the specified collision-group listener with the specified collision group of this space.
void	addCollisionListener(PhysicsCollisionListener listener) Register the specified collision listener with this space.
void	addCollisionObject(PhysicsCollisionObject obj) Add the specified collision object to this space.
void	addTickListener(PhysicsTickListener listener) Register the specified tick listener with this space.
void	create() Must be invoked on the designated physics thread.
void	destroy() Destroy this space so that a new one can be instantiated.
void	distributeEvents() Distribute each collision event to all listeners.
<V> java.util.concurrent.Future<V>	enqueue(java.util.concurrent.Callable<V> callable) Invoke the specified callable during the next physics tick.
static <V> java.util.concurrent.Future<V>	enqueueOnThisThread(java.util.concurrent.Callable<V> callable) Enqueue a callable on the currently executing thread.
protected void	finalize() Finalize this physics space just before it is destroyed.
float	getAccuracy() Read the accuracy (time step) of the physics simulation.
PhysicsSpace.BroadphaseType	getBroadphaseType() Read the type of acceleration structure used.
java.util.Collection<PhysicsCharacter>	getCharacterList() Copy the list of physics characters that have been added to this space and not yet removed.
java.util.Collection<PhysicsGhostObject>	getGhostObjectList() Copy the list of ghost objects that have been added to this space and not yet removed.
com.jme3.math.Vector3f	getGravity(com.jme3.math.Vector3f gravity) Copy the gravitational acceleration acting on newly-added bodies.
java.util.Collection<PhysicsJoint>	getJointList() Copy the list of physics joints that have been added to this space and not yet removed.
static PhysicsSpace	getPhysicsSpace() Access the PhysicsSpace running on this thread.
int	GetRayTestFlags() Reads m_flags used in ray tests.
java.util.Collection<PhysicsRigidBody>	getRigidBodyList() Copy the list of rigid bodies that have been added to this space and not yet removed.
int	getSolverNumIterations() Read the number of iterations used by the contact-and-constraint solver.
long	getSpaceId() // * used internally //
java.util.Collection<PhysicsVehicle>	getVehicleList() Copy the list of physics vehicles that have been added to this space and not yet removed.
com.jme3.math.Vector3f	getWorldMax() Access the maximum coordinate values for this space.
com.jme3.math.Vector3f	getWorldMin() Access the minimum coordinate values for this space.
static void	initNativePhysics()
void	rayTest_native(com.jme3.math.Vector3f from, com.jme3.math.Vector3f to, long physicsSpaceId, java.util.List<PhysicsRayTestResult> results, int flags)
java.util.List<PhysicsRayTestResult>	rayTest(com.jme3.math.Vector3f from, com.jme3.math.Vector3f to) Perform a ray-collision test and return the results as a list of PhysicsRayTestResults sorted by ascending hitFraction.
java.util.List<PhysicsRayTestResult>	rayTest(com.jme3.math.Vector3f from, com.jme3.math.Vector3f to, java.util.List<PhysicsRayTestResult> results) Perform a ray-collision test and return the results as a list of PhysicsRayTestResults sorted by ascending hitFraction.
java.util.List<PhysicsRayTestResult>	rayTestRaw(com.jme3.math.Vector3f from, com.jme3.math.Vector3f to) Perform a ray-collision test and return the results as a list of PhysicsRayTestResults in arbitrary order.
java.util.List<PhysicsRayTestResult>	rayTestRaw(com.jme3.math.Vector3f from, com.jme3.math.Vector3f to, java.util.List<PhysicsRayTestResult> results) Perform a ray-collision test and return the results as a list of PhysicsRayTestResults in arbitrary order.
void	remove(java.lang.Object obj) Remove the specified object from this space.
void	removeAll(com.jme3.scene.Spatial spatial) Remove all physics controls and joints in the specified subtree of the scene graph from the physics space (e.g.
void	removeCollisionGroupListener(int collisionGroup) De-register the specified collision-group listener.
void	removeCollisionListener(PhysicsCollisionListener listener) De-register the specified collision listener.
void	removeCollisionObject(PhysicsCollisionObject obj) Remove the specified collision object from this space.
void	removeTickListener(PhysicsTickListener listener) De-register the specified tick listener.
void	setAccuracy(float accuracy) Alter the accuracy (time step) of the physics simulation.
void	setBroadphaseType(PhysicsSpace.BroadphaseType broadphaseType) Alter the type of acceleration structure used.
void	setGravity(com.jme3.math.Vector3f gravity) Alter the gravitational acceleration acting on newly-added bodies.
static void	setLocalThreadPhysicsSpace(PhysicsSpace space) Used internally
void	setMaxSubSteps(int steps) Alter the maximum number of physics steps per frame.
void	SetRayTestFlags(int flags) Alters the m_flags used in ray tests.
void	setSolverNumIterations(int numIterations) Alter the number of iterations used by the contact-and-constraint solver.
void	setWorldMax(com.jme3.math.Vector3f worldMax) only applies for AXIS_SWEEP broadphase
void	setWorldMin(com.jme3.math.Vector3f worldMin) Alter the minimum coordinate values for this space.
void	sweepTest_native(long shape, com.jme3.math.Transform from, com.jme3.math.Transform to, long physicsSpaceId, java.util.List<PhysicsSweepTestResult> results, float allowedCcdPenetration)
java.util.List<PhysicsSweepTestResult>	sweepTest(CollisionShape shape, com.jme3.math.Transform start, com.jme3.math.Transform end) Perform a sweep-collision test and return the results as a new list.
java.util.List<PhysicsSweepTestResult>	sweepTest(CollisionShape shape, com.jme3.math.Transform start, com.jme3.math.Transform end, java.util.List<PhysicsSweepTestResult> results) Perform a sweep-collision test and store the results in an existing list.
java.util.List<PhysicsSweepTestResult>	sweepTest(CollisionShape shape, com.jme3.math.Transform start, com.jme3.math.Transform end, java.util.List<PhysicsSweepTestResult> results, float allowedCcdPenetration) Perform a sweep-collision test and store the results in an existing list.
void	update(float time) Update this space.
void	update(float time, int maxSteps) Simulate for the specified time interval, using no more than the specified number of steps.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AXIS_X

public static final int AXIS_X

index of the X axis

See Also:

Constant Field Values

AXIS_Y

public static final int AXIS_Y

index of the Y axis

See Also:

Constant Field Values

AXIS_Z

public static final int AXIS_Z

index of the Z axis

See Also:

Constant Field Values

Constructor Detail

PhysicsSpace

public PhysicsSpace()

Instantiate a PhysicsSpace. Must be invoked on the designated physics thread.

PhysicsSpace

public PhysicsSpace(PhysicsSpace.BroadphaseType broadphaseType)

Instantiate a PhysicsSpace. Must be invoked on the designated physics thread.

PhysicsSpace

public PhysicsSpace(com.jme3.math.Vector3f worldMin,
                    com.jme3.math.Vector3f worldMax)

Instantiate a PhysicsSpace. Must be invoked on the designated physics thread.

PhysicsSpace

public PhysicsSpace(com.jme3.math.Vector3f worldMin,
                    com.jme3.math.Vector3f worldMax,
                    PhysicsSpace.BroadphaseType broadphaseType)

Instantiate a PhysicsSpace. Must be invoked on the designated physics thread.

Parameters:

worldMin - the desired minimum coordinates values (not null, unaffected, default=-10k,-10k,-10k)

worldMax - the desired minimum coordinates values (not null, unaffected, default=10k,10k,10k)

broadphaseType - which broadphase collision-detection algorithm to use (not null)

Method Detail

getPhysicsSpace

public static PhysicsSpace getPhysicsSpace()

Access the PhysicsSpace running on this thread. For parallel physics, this can be invoked from the OpenGL thread.

Returns:

the PhysicsSpace running on this thread

setLocalThreadPhysicsSpace

public static void setLocalThreadPhysicsSpace(PhysicsSpace space)

Used internally

Parameters:

space - which physics space to simulate on this thread

create

public void create()

Must be invoked on the designated physics thread.

update

public void update(float time)

Update this space. Invoked (by the Bullet app state) once per frame while the app state is attached and enabled.

Parameters:

time - time-per-frame multiplied by speed (in seconds, ≥0)

update

public void update(float time,
                   int maxSteps)

Simulate for the specified time interval, using no more than the specified number of steps.

Parameters:

time - the time interval (in seconds, ≥0)

maxSteps - the maximum number of steps (≥1)

distributeEvents

public void distributeEvents()

Distribute each collision event to all listeners.

enqueueOnThisThread

public static <V> java.util.concurrent.Future<V> enqueueOnThisThread(java.util.concurrent.Callable<V> callable)

Enqueue a callable on the currently executing thread.

Type Parameters:

V - the task's result type

Parameters:

callable - the task to be executed

Returns:

a new task (not null)

enqueue

public <V> java.util.concurrent.Future<V> enqueue(java.util.concurrent.Callable<V> callable)

Invoke the specified callable during the next physics tick. This is useful for applying forces.

Type Parameters:

V - the return type of the callable

Parameters:

callable - which callable to invoke

Returns:

Future object

add

public void add(java.lang.Object obj)

Add the specified object to this space.

Parameters:

obj - the PhysicsControl, Spatial-with-PhysicsControl, PhysicsCollisionObject, or PhysicsJoint to add (not null, modified)

addCollisionObject

public void addCollisionObject(PhysicsCollisionObject obj)

Add the specified collision object to this space.

Parameters:

obj - the PhysicsCollisionObject to add (not null, modified)

remove

public void remove(java.lang.Object obj)

Remove the specified object from this space.

Parameters:

obj - the PhysicsCollisionObject to add, or null (modified)

removeCollisionObject

public void removeCollisionObject(PhysicsCollisionObject obj)

Remove the specified collision object from this space.

Parameters:

obj - the PhysicsControl or Spatial with PhysicsControl to remove

addAll

public void addAll(com.jme3.scene.Spatial spatial)

Add all collision objects and joints in the specified subtree of the scene graph to this space (e.g. after loading from disk). Note: recursive!

Parameters:

spatial - the root of the subtree (not null)

removeAll

public void removeAll(com.jme3.scene.Spatial spatial)

Remove all physics controls and joints in the specified subtree of the scene graph from the physics space (e.g. before saving to disk) Note: recursive!

Parameters:

spatial - the root of the subtree (not null)

getRigidBodyList

public java.util.Collection<PhysicsRigidBody> getRigidBodyList()

Copy the list of rigid bodies that have been added to this space and not yet removed.

Returns:

a new list (not null)

getGhostObjectList

public java.util.Collection<PhysicsGhostObject> getGhostObjectList()

Copy the list of ghost objects that have been added to this space and not yet removed.

Returns:

a new list (not null)

getCharacterList

public java.util.Collection<PhysicsCharacter> getCharacterList()

Copy the list of physics characters that have been added to this space and not yet removed.

Returns:

a new list (not null)

getJointList

public java.util.Collection<PhysicsJoint> getJointList()

Copy the list of physics joints that have been added to this space and not yet removed.

Returns:

a new list (not null)

getVehicleList

public java.util.Collection<PhysicsVehicle> getVehicleList()

Copy the list of physics vehicles that have been added to this space and not yet removed.

Returns:

a new list (not null)

setGravity

public void setGravity(com.jme3.math.Vector3f gravity)

Alter the gravitational acceleration acting on newly-added bodies.

Whenever a rigid body is added to a space, the body's gravity gets set to that of the space. Thus it makes sense to set the space's vector before adding any bodies to the space.

Parameters:

gravity - the desired acceleration vector (not null, unaffected)

getGravity

public com.jme3.math.Vector3f getGravity(com.jme3.math.Vector3f gravity)

Copy the gravitational acceleration acting on newly-added bodies.

Parameters:

gravity - storage for the result (not null, modified)

Returns:

acceleration (in the vector provided)

addTickListener

public void addTickListener(PhysicsTickListener listener)

Register the specified tick listener with this space.

Tick listeners are notified before and after each physics step. A physics step is not necessarily the same as a frame; it is more influenced by the accuracy of the physics space.

Parameters:

listener - the listener to register (not null)

See Also:

setAccuracy(float)

removeTickListener

public void removeTickListener(PhysicsTickListener listener)

De-register the specified tick listener.

Parameters:

listener - the listener to de-register (not null)

See Also:

addTickListener(com.jme3.bullet.PhysicsTickListener)

addCollisionListener

public void addCollisionListener(PhysicsCollisionListener listener)

Register the specified collision listener with this space.

Collision listeners are notified when collisions occur in the space.

Parameters:

listener - the listener to register (not null, alias created)

removeCollisionListener

public void removeCollisionListener(PhysicsCollisionListener listener)

De-register the specified collision listener.

Parameters:

listener - the listener to de-register (not null)

See Also:

addCollisionListener(com.jme3.bullet.collision.PhysicsCollisionListener)

addCollisionGroupListener

public void addCollisionGroupListener(PhysicsCollisionGroupListener listener,
                                      int collisionGroup)

Register the specified collision-group listener with the specified collision group of this space.

Such a listener can disable collisions when they occur. There can be only one listener per collision group per space.

Parameters:

listener - the listener to register (not null)

collisionGroup - which group it should listen for (bit mask with exactly one bit set)

removeCollisionGroupListener

public void removeCollisionGroupListener(int collisionGroup)

De-register the specified collision-group listener.

Parameters:

collisionGroup - the group of the listener to de-register (bit mask with exactly one bit set)

See Also:

addCollisionGroupListener(com.jme3.bullet.collision.PhysicsCollisionGroupListener, int)

rayTest

public java.util.List<PhysicsRayTestResult> rayTest(com.jme3.math.Vector3f from,
                                                    com.jme3.math.Vector3f to)

Perform a ray-collision test and return the results as a list of PhysicsRayTestResults sorted by ascending hitFraction.

Parameters:

from - the starting location (physics-space coordinates, not null, unaffected)

to - the ending location (in physics-space coordinates, not null, unaffected)

Returns:

a new list of results (not null)

rayTestRaw

public java.util.List<PhysicsRayTestResult> rayTestRaw(com.jme3.math.Vector3f from,
                                                       com.jme3.math.Vector3f to)

Perform a ray-collision test and return the results as a list of PhysicsRayTestResults in arbitrary order.

Parameters:

from - the starting location (in physics-space coordinates, not null, unaffected)

to - the ending location (in physics-space coordinates, not null, unaffected)

Returns:

a new list of results (not null)

SetRayTestFlags

public void SetRayTestFlags(int flags)

Alters the m_flags used in ray tests. see https://code.google.com/p/bullet/source/browse/trunk/src/BulletCollision/NarrowPhaseCollision/btRaycastCallback.h for possible options. Defaults to using the faster, approximate raytest.

Parameters:

flags - the desired flags, ORed together (default=0x4)

GetRayTestFlags

public int GetRayTestFlags()

Reads m_flags used in ray tests. see https://code.google.com/p/bullet/source/browse/trunk/src/BulletCollision/NarrowPhaseCollision/btRaycastCallback.h for possible options.

Returns:

which flags are used

rayTest

public java.util.List<PhysicsRayTestResult> rayTest(com.jme3.math.Vector3f from,
                                                    com.jme3.math.Vector3f to,
                                                    java.util.List<PhysicsRayTestResult> results)

Perform a ray-collision test and return the results as a list of PhysicsRayTestResults sorted by ascending hitFraction.

Parameters:

from - coordinates of the starting location (in physics space, not null, unaffected)

to - coordinates of the ending location (in physics space, not null, unaffected)

results - the list to hold results (not null, modified)

Returns:

results

rayTestRaw

public java.util.List<PhysicsRayTestResult> rayTestRaw(com.jme3.math.Vector3f from,
                                                       com.jme3.math.Vector3f to,
                                                       java.util.List<PhysicsRayTestResult> results)

Perform a ray-collision test and return the results as a list of PhysicsRayTestResults in arbitrary order.

Parameters:

from - coordinates of the starting location (in physics space, not null, unaffected)

to - coordinates of the ending location (in physics space, not null, unaffected)

results - the list to hold results (not null, modified)

Returns:

results

rayTest_native

public void rayTest_native(com.jme3.math.Vector3f from,
                           com.jme3.math.Vector3f to,
                           long physicsSpaceId,
                           java.util.List<PhysicsRayTestResult> results,
                           int flags)

sweepTest

public java.util.List<PhysicsSweepTestResult> sweepTest(CollisionShape shape,
                                                        com.jme3.math.Transform start,
                                                        com.jme3.math.Transform end)

Perform a sweep-collision test and return the results as a new list.

The starting and ending locations must be at least 0.4f physics-space units apart.

A sweep test will miss a collision if it starts inside an object and sweeps away from the object's center.

Parameters:

shape - the shape to sweep (not null)

start - the starting physics-space transform (not null)

end - the ending physics-space transform (not null)

Returns:

a new list of results

sweepTest

public java.util.List<PhysicsSweepTestResult> sweepTest(CollisionShape shape,
                                                        com.jme3.math.Transform start,
                                                        com.jme3.math.Transform end,
                                                        java.util.List<PhysicsSweepTestResult> results)

Perform a sweep-collision test and store the results in an existing list.

The starting and ending locations must be at least 0.4f physics-space units apart.

A sweep test will miss a collision if it starts inside an object and sweeps away from the object's center.

Parameters:

shape - the shape to sweep (not null)

start - the starting physics-space transform (not null)

end - the ending physics-space transform (not null)

results - the list to hold results (not null, modified)

Returns:

results

sweepTest_native

public void sweepTest_native(long shape,
                             com.jme3.math.Transform from,
                             com.jme3.math.Transform to,
                             long physicsSpaceId,
                             java.util.List<PhysicsSweepTestResult> results,
                             float allowedCcdPenetration)

sweepTest

public java.util.List<PhysicsSweepTestResult> sweepTest(CollisionShape shape,
                                                        com.jme3.math.Transform start,
                                                        com.jme3.math.Transform end,
                                                        java.util.List<PhysicsSweepTestResult> results,
                                                        float allowedCcdPenetration)

Perform a sweep-collision test and store the results in an existing list.

The starting and ending locations must be at least 0.4f physics-space units apart.

A sweep test will miss a collision if it starts inside an object and sweeps away from the object's center.

Parameters:

shape - the shape to sweep (not null)

start - the starting physics-space transform (not null)

end - the ending physics-space transform (not null)

results - the list to hold results (not null, modified)

allowedCcdPenetration - true→allow, false→disallow

Returns:

results

destroy

public void destroy()

Destroy this space so that a new one can be instantiated.

getSpaceId

public long getSpaceId()

// * used internally //

Returns:

the dynamicsWorld //

getBroadphaseType

public PhysicsSpace.BroadphaseType getBroadphaseType()

Read the type of acceleration structure used.

Returns:

an enum value (not null)

setBroadphaseType

public void setBroadphaseType(PhysicsSpace.BroadphaseType broadphaseType)

Alter the type of acceleration structure used.

Parameters:

broadphaseType - the desired algorithm (not null)

setMaxSubSteps

public void setMaxSubSteps(int steps)

Alter the maximum number of physics steps per frame.

Extra physics steps help maintain determinism when the render fps drops below 1/accuracy. For example a value of 2 can compensate for frame rates as low as 30fps, assuming the physics has an accuracy of 1/60 sec.

Setting this value too high can depress the frame rate.

Parameters:

steps - the desired maximum number of steps per frame (≥1, default=4)

getAccuracy

public float getAccuracy()

Read the accuracy (time step) of the physics simulation.

Returns:

the timestep (in seconds, >0)

setAccuracy

public void setAccuracy(float accuracy)

Alter the accuracy (time step) of the physics simulation.

In general, the smaller the time step, the more accurate (and compute-intensive) the simulation will be. Bullet works best with a time step of no more than 1/60 second.

Parameters:

accuracy - the desired time step (in seconds, >0, default=1/60)

getWorldMin

public com.jme3.math.Vector3f getWorldMin()

Access the minimum coordinate values for this space.

Returns:

the pre-existing vector

setWorldMin

public void setWorldMin(com.jme3.math.Vector3f worldMin)

Alter the minimum coordinate values for this space. (only affects AXIS_SWEEP broadphase algorithms)

Parameters:

worldMin - the desired minimum coordinate values (not null, unaffected)

getWorldMax

public com.jme3.math.Vector3f getWorldMax()

Access the maximum coordinate values for this space.

Returns:

the pre-existing vector (not null)

setWorldMax

public void setWorldMax(com.jme3.math.Vector3f worldMax)

only applies for AXIS_SWEEP broadphase

Parameters:

worldMax -

setSolverNumIterations

public void setSolverNumIterations(int numIterations)

Alter the number of iterations used by the contact-and-constraint solver.

Use 4 for low quality, 20 for high quality.

Parameters:

numIterations - the desired number of iterations (≥1, default=10)

getSolverNumIterations

public int getSolverNumIterations()

Read the number of iterations used by the contact-and-constraint solver.

Returns:

the number of iterations used

initNativePhysics

public static void initNativePhysics()

finalize

protected void finalize()
                 throws java.lang.Throwable

Finalize this physics space just before it is destroyed. Should be invoked only by a subclass or by the garbage collector.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - ignored by the garbage collector