Package com.jme3.bullet.collision.shapes

Class CollisionShape

java.lang.Object
com.jme3.bullet.NativePhysicsObject
com.jme3.bullet.collision.shapes.CollisionShape
All Implemented Interfaces:
com.jme3.export.Savable, com.jme3.util.clone.JmeCloneable, Cloneable, Comparable<NativePhysicsObject>
Direct Known Subclasses:
CompoundCollisionShape, ConvexShape, EmptyShape, GImpactCollisionShape, HeightfieldCollisionShape, MeshCollisionShape, PlaneCollisionShape
public abstract class CollisionShape extends NativePhysicsObject implements com.jme3.util.clone.JmeCloneable, com.jme3.export.Savable
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
    Description
    protected boolean
    enableContactFilter
    copy of the contact-filter enable flag
    static final Logger
    logger
    message logger for this class
    protected float
    margin
    copy of collision margin (in physics-space units, >0, default=0.04)
    protected com.jme3.math.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
    Description
    protected
    CollisionShape()
    Instantiate a collision shape with no tracker and no assigned native object.

  • Method Summary

    Modifier and Type
    Method
    Description
    com.jme3.math.Vector3f
    aabbCenter(com.jme3.math.Vector3f storeResult)
    Return the center of the shape's axis-aligned bounding box in local coordinates.
    float
    aabbScaledVolume()
    Calculate a quick upper bound for the scaled volume of a shape, based on its axis-aligned bounding box.
    com.jme3.bounding.BoundingBox
    boundingBox(com.jme3.math.Vector3f translation, com.jme3.math.Matrix3f rotation, com.jme3.bounding.BoundingBox storeResult)
    Calculate an axis-aligned bounding box with the specified translation and rotation applied.
    com.jme3.bounding.BoundingBox
    boundingBox(com.jme3.math.Vector3f translation, com.jme3.math.Quaternion rotation, com.jme3.bounding.BoundingBox storeResult)
    Calculate an axis-aligned bounding box with the specified translation and rotation applied.
    boolean
    canScale(com.jme3.math.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.
    void
    cloneFields(com.jme3.util.clone.Cloner cloner, Object original)
    Callback from Cloner to convert this shallow-cloned shape into a deep-cloned one, using the specified Cloner and original to resolve copied fields.
    protected final void
    copyShapeProperties(CollisionShape old)
    Copy common properties from another CollisionShape.
    static float
    getDefaultMargin()
    Return the default margin for new shapes that are neither capsules nor spheres.
    float
    getMargin()
    Return the (copied) collision margin of the shape.
    com.jme3.math.Vector3f
    getScale(com.jme3.math.Vector3f storeResult)
    Copy the scale factors.
    com.simsilica.mathd.Vec3d
    getScaleDp(com.simsilica.mathd.Vec3d storeResult)
    Copy the scale factors.
    int
    getShapeType()
    Return the encoded type of the shape.
    protected static final 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.
    CollisionShape
    jmeClone()
    Create a shallow clone for the JME cloner.
    float
    maxRadius()
    Estimate how far the scaled shape extends from its center, including margin.
    protected final float
    nativeMargin()
    Return the native collision margin of this shape.
    void
    read(com.jme3.export.JmeImporter importer)
    De-serialize the shape from the specified importer, for example when loading from a J3O file.
    protected final void
    readShapeProperties(com.jme3.export.InputCapsule capsule)
    Read common properties from an InputCapsule.
    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(com.jme3.math.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.
    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).
    void
    write(com.jme3.export.JmeExporter exporter)
    Serialize this shape to the specified exporter, for example when saving to a J3O file.

    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 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 com.jme3.math.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 com.jme3.math.Vector3f aabbCenter(com.jme3.math.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)

    • aabbScaledVolume

      public float aabbScaledVolume()
      Calculate a quick upper bound for the scaled volume of a shape, based on its axis-aligned bounding box. Collision margin is included.
      Returns:
      the volume (in scaled shape units cubed, ≥0)

    • boundingBox

      public com.jme3.bounding.BoundingBox boundingBox(com.jme3.math.Vector3f translation, com.jme3.math.Matrix3f rotation, com.jme3.bounding.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 com.jme3.bounding.BoundingBox boundingBox(com.jme3.math.Vector3f translation, com.jme3.math.Quaternion rotation, com.jme3.bounding.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(com.jme3.math.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 com.jme3.math.Vector3f getScale(com.jme3.math.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 com.simsilica.mathd.Vec3d getScaleDp(com.simsilica.mathd.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(com.jme3.math.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

    • copyShapeProperties

      protected final void copyShapeProperties(CollisionShape old)
      Copy common properties from another CollisionShape. Used during cloning.
      Parameters:
      old - the instance to copy from (not null, unaffected)

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

    • readShapeProperties

      protected final void readShapeProperties(com.jme3.export.InputCapsule capsule) throws IOException
      Read common properties from an InputCapsule.
      Parameters:
      capsule - the input capsule (not null, modified)
      Throws:
      IOException - from the importer

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

    • cloneFields

      public void cloneFields(com.jme3.util.clone.Cloner cloner, Object original)
      Callback from Cloner to convert this shallow-cloned shape into a deep-cloned one, using the specified Cloner and original to resolve copied fields.
      Specified by:
      cloneFields in interface com.jme3.util.clone.JmeCloneable
      Parameters:
      cloner - the Cloner that's cloning this shape (not null)
      original - the instance from which this shape was shallow-cloned (unused)

    • jmeClone

      public CollisionShape jmeClone()
      Create a shallow clone for the JME cloner.
      Specified by:
      jmeClone in interface com.jme3.util.clone.JmeCloneable
      Returns:
      a new instance

    • read

      public void read(com.jme3.export.JmeImporter importer) throws IOException
      De-serialize the shape from the specified importer, for example when loading from a J3O file.
      Specified by:
      read in interface com.jme3.export.Savable
      Parameters:
      importer - (not null)
      Throws:
      IOException - from the importer

    • write

      public void write(com.jme3.export.JmeExporter exporter) throws IOException
      Serialize this shape to the specified exporter, for example when saving to a J3O file.
      Specified by:
      write in interface com.jme3.export.Savable
      Parameters:
      exporter - (not null)
      Throws:
      IOException - from the exporter

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