Package com.jme3.bullet.collision.shapes

Class CollisionShape

java.lang.Object
com.jme3.bullet.NativePhysicsObject
com.jme3.bullet.collision.shapes.CollisionShape
All Implemented Interfaces:
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 Details

    • logger

      public static final 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 Details

    • 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 Details

    • 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 (copied) collision margin of the 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 String toString()
      Represent this CollisionShape as a String.
      Overrides:
      toString in class NativePhysicsObject
      Returns:
      a descriptive string of text (not null, not empty)