com.jme3.bullet.collision.shapes

Class CollisionShape

java.lang.Object

com.jme3.bullet.NativePhysicsObject

com.jme3.bullet.collision.shapes.CollisionShape

All Implemented Interfaces:

java.lang.Comparable<NativePhysicsObject>

Direct Known Subclasses:

CompoundCollisionShape, ConvexShape, EmptyShape, GImpactCollisionShape, HeightfieldCollisionShape, MeshCollisionShape, PlaneCollisionShape

public abstract class CollisionShape
extends NativePhysicsObject

The abstract base class for collision shapes based on Bullet's btCollisionShape.

Subclasses include ConvexShape and MeshCollisionShape. As suggested in the Bullet manual, a single collision shape can be shared among multiple collision objects.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	enableContactFilter copy of the contact-filter enable flag
static java.util.logging.Logger	logger message logger for this class
protected float	margin copy of collision margin (in physics-space units, >0, default=0.04)
protected Vector3f	scale copy of the scale factors, one for each local axis

Fields inherited from class com.jme3.bullet.NativePhysicsObject

loggerN

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	CollisionShape() Instantiate a collision shape with no tracker and no assigned native object.

Method Summary

Modifier and Type	Method and Description
Vector3f	aabbCenter(Vector3f storeResult) Return the center of the shape's axis-aligned bounding box in local coordinates.
BoundingBox	boundingBox(Vector3f translation, Matrix3f rotation, BoundingBox storeResult) Calculate an axis-aligned bounding box with the specified translation and rotation applied.
BoundingBox	boundingBox(Vector3f translation, Quaternion rotation, BoundingBox storeResult) Calculate an axis-aligned bounding box with the specified translation and rotation applied.
boolean	canScale(Vector3f scale) Test whether the specified scale factors can be applied to the shape.
boolean	canSplit() Test whether the shape can be split by an arbitrary plane.
static float	getDefaultMargin() Return the default margin for new shapes that are neither capsules nor spheres.
float	getMargin() Return the collision margin for this shape.
Vector3f	getScale(Vector3f storeResult) Copy the scale factors.
Vec3d	getScaleDp(Vec3d storeResult) Copy the scale factors.
int	getShapeType() Return the encoded type of the shape.
protected static int	getShapeType(long shapeId) Return the type of this shape.
boolean	isConcave() Test whether the shape has concave type.
boolean	isContactFilterEnabled() Test whether contact filtering is enabled for this shape.
boolean	isConvex() Test whether the shape has convex type.
boolean	isInfinite() Test whether the shape's type is infinite.
boolean	isNonMoving() Test whether the shape can be applied to a dynamic rigid body.
boolean	isPolyhedral() Test whether this shape is convex and defined by polygons.
float	maxRadius() Estimate how far the scaled shape extends from its center, including margin.
protected float	nativeMargin() Return the native collision margin of this shape.
protected void	recalculateAabb() Recalculate this shape's bounding box if necessary.
float	scaledVolume() Estimate the volume of this shape, including scale and margin.
void	setContactFilterEnabled(boolean setting) Enable/disable contact filtering for this shape.
static void	setDefaultMargin(float margin) Alter the default margin for new shapes that are neither capsules nor spheres.
void	setMargin(float margin) Alter the collision margin of this shape.
protected void	setNativeId(long shapeId) Initialize the native ID.
void	setScale(float factor) Alter the scale of this shape to a uniform factor.
void	setScale(Vector3f scale) Alter the scale of this shape.
void	setUserIndex(int index) Alter the primary user index.
void	setUserIndex2(int index) Alter the secondary user index.
CollisionShape	toSplittableShape() Approximate this shape with a splittable shape.
java.lang.String	toString() Represent this CollisionShape as a String.
protected void	updateScale() Synchronize the copied scale factors with the btCollisionShape.
int	userIndex() Return the primary user index (native field: m_userIndex).
int	userIndex2() Return the secondary user index (native field: m_userIndex2).

Methods inherited from class com.jme3.bullet.NativePhysicsObject

compareTo, countTrackers, dumpTrackers, equals, freeUnusedObjects, hasAssignedNativeObject, hashCode, nativeId, reassignNativeId, setNativeIdNotTracked, unassignNativeObject

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

logger

public static final java.util.logging.Logger logger

message logger for this class

enableContactFilter

protected boolean enableContactFilter

copy of the contact-filter enable flag

margin

protected float margin

copy of collision margin (in physics-space units, >0, default=0.04)

scale

protected Vector3f scale

copy of the scale factors, one for each local axis

Constructor Detail

CollisionShape

protected CollisionShape()

Instantiate a collision shape with no tracker and no assigned native object.

This no-arg constructor was made explicit to avoid javadoc warnings from JDK 18+.

Method Detail

aabbCenter

public Vector3f aabbCenter(Vector3f storeResult)

Return the center of the shape's axis-aligned bounding box in local coordinates.

Parameters:

storeResult - storage for the result (modified if not null)

Returns:

a location in the local coordinate system (either storeResult or a new vector)

boundingBox

public BoundingBox boundingBox(Vector3f translation,
                               Matrix3f rotation,
                               BoundingBox storeResult)

Calculate an axis-aligned bounding box with the specified translation and rotation applied. Rotation is applied first. Collision margin is included.

Parameters:

translation - the translation to apply (not null, unaffected)

rotation - the rotation to apply (not null, unaffected)

storeResult - storage for the result (modified if not null)

Returns:

a bounding box (either storeResult or a new instance, not null)

boundingBox

public BoundingBox boundingBox(Vector3f translation,
                               Quaternion rotation,
                               BoundingBox storeResult)

Calculate an axis-aligned bounding box with the specified translation and rotation applied. Rotation is applied first. Collision margin is included.

Parameters:

translation - the translation to apply (not null, unaffected)

rotation - the rotation to apply (not null, unaffected)

storeResult - storage for the result (modified if not null)

Returns:

a bounding box (either storeResult or a new instance, not null)

canScale

public boolean canScale(Vector3f scale)

Test whether the specified scale factors can be applied to the shape. Subclasses that restrict scaling should override this method.

Parameters:

scale - the desired scale factor for each local axis (may be null, unaffected)

Returns:

true if applicable, otherwise false

canSplit

public boolean canSplit()

Test whether the shape can be split by an arbitrary plane. Meant to be overridden.

Returns:

true if splittable, false otherwise

getDefaultMargin

public static float getDefaultMargin()

Return the default margin for new shapes that are neither capsules nor spheres.

Returns:

the margin thickness (in physics-space units, >0)

getMargin

public float getMargin()

Return the collision margin for this shape.

Returns:

the margin thickness (in physics-space units, ≥0)

getScale

public Vector3f getScale(Vector3f storeResult)

Copy the scale factors.

Parameters:

storeResult - storage for the result (modified if not null)

Returns:

the scale factor for each local axis (either storeResult or a new vector, not null, no negative component)

getScaleDp

public Vec3d getScaleDp(Vec3d storeResult)

Copy the scale factors.

Parameters:

storeResult - storage for the result (modified if not null)

Returns:

the scale factor for each local axis (either storeResult or a new vector, not null, no negative component)

getShapeType

public int getShapeType()

Return the encoded type of the shape.

Returns:

the type code (from Bullet's enum BroadphaseNativeTypes)

isConcave

public boolean isConcave()

Test whether the shape has concave type. In Bullet, "concave" is a property of types of shapes. Specific instances of those types might actually be "convex" in the mathematical sense of the word.

The only concave types are the empty, gimpact, heightfield, mesh, and plane shapes. Note that compound shapes are neither concave nor convex.

Returns:

true if concave type, false otherwise

isContactFilterEnabled

public boolean isContactFilterEnabled()

Test whether contact filtering is enabled for this shape. Contact filtering is implemented only for HeightfieldCollisionShape and MeshCollisionShapes.

Returns:

true if enabled, otherwise false

isConvex

public boolean isConvex()

Test whether the shape has convex type. In Bullet, "convex" is a property of types of shapes. Specific instances of non-convex types might still be "convex" in the mathematical sense of the word.

Convex types include the box2d, box, capsule, cone, convex2d, cylinder, hull, multi-sphere, simplex, and sphere shapes. Note that compound shapes are neither concave nor convex.

Returns:

true if convex type, false otherwise

isInfinite

public boolean isInfinite()

Test whether the shape's type is infinite. PlaneCollisionShape is the only type of shape that's infinite.

Returns:

true if infinite, false otherwise

isNonMoving

public boolean isNonMoving()

Test whether the shape can be applied to a dynamic rigid body. The only non-moving shapes are the empty, heightfield, mesh, and plane shapes.

Returns:

true if non-moving, false otherwise

isPolyhedral

public boolean isPolyhedral()

Test whether this shape is convex and defined by polygons. The only polyhedral shapes are the box, hull, and simplex shapes.

Returns:

true if polyhedral, false otherwise

maxRadius

public float maxRadius()

Estimate how far the scaled shape extends from its center, including margin.

Returns:

a distance estimate (in physics-space units, ≥0, may be infinite)

scaledVolume

public float scaledVolume()

Estimate the volume of this shape, including scale and margin. Meant to be overridden.

Returns:

the volume (in physics-space units cubed, ≥0)

setContactFilterEnabled

public void setContactFilterEnabled(boolean setting)

Enable/disable contact filtering for this shape.

Parameters:

setting - the desired setting (default=false)

setDefaultMargin

public static void setDefaultMargin(float margin)

Alter the default margin for new shapes that are neither capsules nor spheres. From Bullet manual:
It is best not to modify the default collision margin, and if you do use a positive value: zero margin might introduce problems.

Parameters:

margin - the desired margin thickness (in physics-space units, >0, default=0.04)

setMargin

public void setMargin(float margin)

Alter the collision margin of this shape. CAUTION: Margin is applied differently, depending on the type of shape. Generally the collision margin expands the object, creating a gap.

From Bullet manual:
It is best not to modify the default collision margin, and if you do use a positive value: zero margin might introduce problems.

Note that if the shape is shared (between collision objects and/or compound shapes) changes can have unintended consequences.

Parameters:

margin - the desired margin thickness (in physics-space units, >0, default=0.04)

setScale

public void setScale(float factor)

Alter the scale of this shape to a uniform factor. CAUTION: Not all shapes can be scaled.

Note that if the shape is shared (between collision objects and/or compound shapes) changes can have unintended consequences.

Parameters:

factor - the desired scale factor for all axes (≥0, default=1)

setScale

public void setScale(Vector3f scale)

Alter the scale of this shape. CAUTION: Not all shapes can be scaled arbitrarily.

Note that if the shape is shared (between collision objects and/or compound shapes) changes can have unintended consequences.

Parameters:

scale - the desired scale factor for each local axis (not null, no negative component, unaffected, default=(1,1,1))

setUserIndex

public void setUserIndex(int index)

Alter the primary user index. Applications may use this parameter for any purpose (native field: m_userIndex).

Parameters:

index - the desired value (default=-1)

setUserIndex2

public void setUserIndex2(int index)

Alter the secondary user index. Applications may use this parameter for any purpose (native field: m_userIndex2).

Parameters:

index - the desired value (default=-1)

toSplittableShape

public CollisionShape toSplittableShape()

Approximate this shape with a splittable shape. Meant to be overridden.

Returns:

a new splittable shape

userIndex

public int userIndex()

Return the primary user index (native field: m_userIndex).

Returns:

the value

userIndex2

public int userIndex2()

Return the secondary user index (native field: m_userIndex2).

Returns:

the value

getShapeType

protected static final int getShapeType(long shapeId)

Return the type of this shape.

Parameters:

shapeId - the ID of the btCollisionShape (not zero)

Returns:

the type value (from Bullet's enum BroadphaseNativeTypes)

nativeMargin

protected final float nativeMargin()

Return the native collision margin of this shape.

Returns:

the margin thickness (in physics-space units, ≥0)

recalculateAabb

protected void recalculateAabb()

Recalculate this shape's bounding box if necessary. Meant to be overridden.

updateScale

protected void updateScale()

Synchronize the copied scale factors with the btCollisionShape.

setNativeId

protected void setNativeId(long shapeId)

Initialize the native ID.

Overrides:

setNativeId in class NativePhysicsObject

Parameters:

shapeId - the identifier of the btCollisionShape (not zero)

toString

public java.lang.String toString()

Represent this CollisionShape as a String.

Overrides:

toString in class NativePhysicsObject

Returns:

a descriptive string of text (not null, not empty)