Base class for all convex shapes. Defines a virtual interface. More...

#include <ConvexShape.h>

Inheritance diagram for ConvexShape:

Classes
class	CSGetTrianglesContext

class	Support
	Function that provides an interface for GJK. More...

class	SupportBuffer
	Buffer to hold a Support object, used to avoid dynamic memory allocations. More...

Public Types
enum class	ESupportMode { ExcludeConvexRadius , IncludeConvexRadius , Default }
	How the GetSupport function should behave. More...

Public Types inherited from Shape
using	ShapeResult = ShapeSettings::ShapeResult

using	SupportingFace = StaticArray< Vec3, 32 >
	Type definition for a supporting face.

using	VisitedShapes = UnorderedSet< const Shape * >

using	ShapeToIDMap = StreamUtils::ObjectToIDMap< Shape >

using	IDToShapeMap = StreamUtils::IDToObjectMap< Shape >

using	MaterialToIDMap = StreamUtils::ObjectToIDMap< PhysicsMaterial >

using	IDToMaterialMap = StreamUtils::IDToObjectMap< PhysicsMaterial >

Public Member Functions
JPH_OVERRIDE_NEW_DELETE	ConvexShape (EShapeSubType inSubType)
	Constructor.

	ConvexShape (EShapeSubType inSubType, const ConvexShapeSettings &inSettings, ShapeResult &outResult)

	ConvexShape (EShapeSubType inSubType, const PhysicsMaterial *inMaterial)

virtual uint	GetSubShapeIDBitsRecursive () const override
	Get the max number of sub shape ID bits that are needed to be able to address any leaf shape in this shape. Used mainly for checking that it is smaller or equal than SubShapeID::MaxBits.

virtual const PhysicsMaterial *	GetMaterial (const SubShapeID &inSubShapeID) const override
	Get the material assigned to a particular sub shape ID.

virtual bool	CastRay (const RayCast &inRay, const SubShapeIDCreator &inSubShapeIDCreator, RayCastResult &ioHit) const override

virtual void	CastRay (const RayCast &inRay, const RayCastSettings &inRayCastSettings, const SubShapeIDCreator &inSubShapeIDCreator, CastRayCollector &ioCollector, const ShapeFilter &inShapeFilter={ }) const override

virtual void	CollidePoint (Vec3Arg inPoint, const SubShapeIDCreator &inSubShapeIDCreator, CollidePointCollector &ioCollector, const ShapeFilter &inShapeFilter={ }) const override

virtual void	GetTrianglesStart (GetTrianglesContext &ioContext, const AABox &inBox, Vec3Arg inPositionCOM, QuatArg inRotation, Vec3Arg inScale) const override

virtual int	GetTrianglesNext (GetTrianglesContext &ioContext, int inMaxTrianglesRequested, Float3 outTriangleVertices, const PhysicsMaterial *outMaterials=nullptr) const override

virtual void	GetSubmergedVolume (Mat44Arg inCenterOfMassTransform, Vec3Arg inScale, const Plane &inSurface, float &outTotalVolume, float &outSubmergedVolume, Vec3 &outCenterOfBuoyancy JPH_IF_DEBUG_RENDERER(, RVec3Arg inBaseOffset)) const override

virtual const Support *	GetSupportFunction (ESupportMode inMode, SupportBuffer &inBuffer, Vec3Arg inScale) const =0

void	SetMaterial (const PhysicsMaterial *inMaterial)
	Material of the shape.

const PhysicsMaterial *	GetMaterial () const

void	SetDensity (float inDensity)
	Set density of the shape (kg / m^3)

float	GetDensity () const
	Get density of the shape (kg / m^3)

virtual void	DrawGetSupportFunction (DebugRenderer *inRenderer, RMat44Arg inCenterOfMassTransform, Vec3Arg inScale, ColorArg inColor, bool inDrawSupportDirection) const override
	Draw the results of the GetSupportFunction with the convex radius added back on to show any errors introduced by this process (only relevant for convex shapes)

virtual void	DrawGetSupportingFace (DebugRenderer *inRenderer, RMat44Arg inCenterOfMassTransform, Vec3Arg inScale) const override
	Draw the results of the GetSupportingFace function to show any errors introduced by this process (only relevant for convex shapes)

virtual void	SaveBinaryState (StreamOut &inStream) const override
	Saves the contents of the shape in binary form to inStream.

virtual void	SaveMaterialState (PhysicsMaterialList &outMaterials) const override

virtual void	RestoreMaterialState (const PhysicsMaterialRefC *inMaterials, uint inNumMaterials) override
	Restore the material references after calling sRestoreFromBinaryState. Note that the exact same materials need to be provided in the same order as returned by SaveMaterialState.

Public Member Functions inherited from Shape
	Shape (EShapeType inType, EShapeSubType inSubType)
	Constructor.

	Shape (EShapeType inType, EShapeSubType inSubType, const ShapeSettings &inSettings, ShapeResult &outResult)

virtual	~Shape ()=default
	Destructor.

EShapeType	GetType () const
	Get type.

EShapeSubType	GetSubType () const

uint64	GetUserData () const
	User data (to be used freely by the application)

void	SetUserData (uint64 inUserData)

virtual bool	MustBeStatic () const
	Check if this shape can only be used to create a static body or if it can also be dynamic/kinematic.

virtual Vec3	GetCenterOfMass () const
	All shapes are centered around their center of mass. This function returns the center of mass position that needs to be applied to transform the shape to where it was created.

virtual AABox	GetLocalBounds () const =0
	Get local bounding box including convex radius, this box is centered around the center of mass rather than the world transform.

virtual AABox	GetWorldSpaceBounds (Mat44Arg inCenterOfMassTransform, Vec3Arg inScale) const

AABox	GetWorldSpaceBounds (DMat44Arg inCenterOfMassTransform, Vec3Arg inScale) const
	Get world space bounds including convex radius.

virtual float	GetInnerRadius () const =0

virtual MassProperties	GetMassProperties () const =0
	Calculate the mass and inertia of this shape.

virtual const Shape *	GetLeafShape (const SubShapeID &inSubShapeID, SubShapeID &outRemainder) const

virtual Vec3	GetSurfaceNormal (const SubShapeID &inSubShapeID, Vec3Arg inLocalSurfacePosition) const =0

virtual void	GetSupportingFace (const SubShapeID &inSubShapeID, Vec3Arg inDirection, Vec3Arg inScale, Mat44Arg inCenterOfMassTransform, SupportingFace &outVertices) const

virtual uint64	GetSubShapeUserData (const SubShapeID &inSubShapeID) const
	Get the user data of a particular sub shape ID. Corresponds with the value stored in Shape::GetUserData of the leaf shape pointed to by inSubShapeID.

virtual TransformedShape	GetSubShapeTransformedShape (const SubShapeID &inSubShapeID, Vec3Arg inPositionCOM, QuatArg inRotation, Vec3Arg inScale, SubShapeID &outRemainder) const

virtual void	GetSubmergedVolume (Mat44Arg inCenterOfMassTransform, Vec3Arg inScale, const Plane &inSurface, float &outTotalVolume, float &outSubmergedVolume, Vec3 &outCenterOfBuoyancy, RVec3Arg inBaseOffset) const =0

virtual void	Draw (DebugRenderer *inRenderer, RMat44Arg inCenterOfMassTransform, Vec3Arg inScale, ColorArg inColor, bool inUseMaterialColors, bool inDrawWireframe) const =0
	Draw the shape at a particular location with a particular color (debugging purposes)

virtual void	CollideSoftBodyVertices (Mat44Arg inCenterOfMassTransform, Vec3Arg inScale, const CollideSoftBodyVertexIterator &inVertices, uint inNumVertices, int inCollidingShapeIndex) const =0

virtual void	CollectTransformedShapes (const AABox &inBox, Vec3Arg inPositionCOM, QuatArg inRotation, Vec3Arg inScale, const SubShapeIDCreator &inSubShapeIDCreator, TransformedShapeCollector &ioCollector, const ShapeFilter &inShapeFilter) const

virtual void	TransformShape (Mat44Arg inCenterOfMassTransform, TransformedShapeCollector &ioCollector) const

ShapeResult	ScaleShape (Vec3Arg inScale) const

virtual Stats	GetStats () const =0
	Get stats of this shape. Use for logging / data collection purposes only. Does not add values from child shapes, use GetStatsRecursive for this.

virtual Stats	GetStatsRecursive (VisitedShapes &ioVisitedShapes) const
	Volume of this shape (m^3). Note that for compound shapes the volume may be incorrect since child shapes can overlap which is not accounted for.

virtual float	GetVolume () const =0

virtual bool	IsValidScale (Vec3Arg inScale) const

virtual Vec3	MakeScaleValid (Vec3Arg inScale) const

virtual void	SaveMaterialState (PhysicsMaterialList &outMaterials) const
	Outputs the material references that this shape has to outMaterials.

virtual void	SaveSubShapeState (ShapeList &outSubShapes) const
	Outputs the shape references that this shape has to outSubShapes.

virtual void	RestoreSubShapeState (const ShapeRefC *inSubShapes, uint inNumShapes)
	Restore the shape references after calling sRestoreFromBinaryState. Note that the exact same shapes need to be provided in the same order as returned by SaveSubShapeState.

void	SaveWithChildren (StreamOut &inStream, ShapeToIDMap &ioShapeMap, MaterialToIDMap &ioMaterialMap) const
	Save this shape, all its children and its materials. Pass in an empty map in ioShapeMap / ioMaterialMap or reuse the same map while saving multiple shapes to the same stream in order to avoid writing duplicates.

Public Member Functions inherited from RefTarget< Shape >
	RefTarget ()=default
	Constructor.

	RefTarget (const RefTarget &)

	~RefTarget ()
	assert no one is referencing us

void	SetEmbedded () const

RefTarget &	operator= (const RefTarget &)
	Assignment operator.

uint32	GetRefCount () const
	Get current refcount of this object.

void	AddRef () const
	Add or release a reference to this object.

void	Release () const

Public Member Functions inherited from NonCopyable
	NonCopyable ()=default

	NonCopyable (const NonCopyable &)=delete

void	operator= (const NonCopyable &)=delete

Static Public Member Functions
static void	sRegister ()

Static Public Member Functions inherited from Shape
static ShapeResult	sRestoreFromBinaryState (StreamIn &inStream)
	Creates a Shape of the correct type and restores its contents from the binary stream inStream.

static ShapeResult	sRestoreWithChildren (StreamIn &inStream, IDToShapeMap &ioShapeMap, IDToMaterialMap &ioMaterialMap)
	Restore a shape, all its children and materials. Pass in an empty map in ioShapeMap / ioMaterialMap or reuse the same map while reading multiple shapes from the same stream in order to restore duplicates.

Static Public Member Functions inherited from RefTarget< Shape >
static int	sInternalGetRefCountOffset ()
	INTERNAL HELPER FUNCTION USED BY SERIALIZATION.

Protected Member Functions
virtual void	RestoreBinaryState (StreamIn &inStream) override
	This function should not be called directly, it is used by sRestoreFromBinaryState.

Static Protected Attributes
static const StaticArray< Vec3, 384 >	sUnitSphereTriangles
	Vertex list that forms a unit sphere.

Static Protected Attributes inherited from RefTarget< Shape >
static constexpr uint32	cEmbedded
	A large value that gets added to the refcount to mark the object as embedded.

Additional Inherited Members
Static Public Attributes inherited from Shape
static constexpr int	cGetTrianglesMinTrianglesRequested = 32
	This is the minimum amount of triangles that should be requested through GetTrianglesNext.

static bool	sDrawSubmergedVolumes = false
	Debug helper which draws the intersection between water and the shapes, the center of buoyancy and the submerged volume.

Static Protected Member Functions inherited from Shape
static void	sCollidePointUsingRayCast (const Shape &inShape, Vec3Arg inPoint, const SubShapeIDCreator &inSubShapeIDCreator, CollidePointCollector &ioCollector, const ShapeFilter &inShapeFilter)
	A fallback version of CollidePoint that uses a ray cast and counts the number of hits to determine if the point is inside the shape. Odd number of hits means inside, even number of hits means outside.

Protected Attributes inherited from RefTarget< Shape >
atomic< uint32 >	mRefCount
	Current reference count.

Detailed Description

Base class for all convex shapes. Defines a virtual interface.

Member Enumeration Documentation

◆ ESupportMode

enum class ConvexShape::ESupportMode

strong

How the GetSupport function should behave.

Enumerator
ExcludeConvexRadius	Return the shape excluding the convex radius, Support::GetConvexRadius will return the convex radius if there is one, but adding this radius may not result in the most accurate/efficient representation of shapes with sharp edges.
IncludeConvexRadius	Return the shape including the convex radius, Support::GetSupport includes the convex radius if there is one, Support::GetConvexRadius will return 0.
Default	Use both Support::GetSupport add Support::GetConvexRadius to get a support point that matches the original shape as accurately/efficiently as possible.

Constructor & Destructor Documentation

◆ ConvexShape() [1/3]

JPH_OVERRIDE_NEW_DELETE ConvexShape::ConvexShape ( EShapeSubType inSubType )

inlineexplicit

Constructor.

◆ ConvexShape() [2/3]

ConvexShape::ConvexShape	(	EShapeSubType	inSubType,
		const ConvexShapeSettings &	inSettings,
		ShapeResult &	outResult
	)

inline

◆ ConvexShape() [3/3]

ConvexShape::ConvexShape	(	EShapeSubType	inSubType,
		const PhysicsMaterial *	inMaterial
	)

inline

Member Function Documentation

◆ CastRay() [1/2]

void ConvexShape::CastRay	(	const RayCast &	inRay,
		const RayCastSettings &	inRayCastSettings,
		const SubShapeIDCreator &	inSubShapeIDCreator,
		CastRayCollector &	ioCollector,
		const ShapeFilter &	inShapeFilter = `{ }`
	)		const

overridevirtual

Cast a ray against this shape. Allows returning multiple hits through ioCollector. Note that this version is more flexible but also slightly slower than the CastRay function that returns only a single hit. If you want the surface normal of the hit use GetSurfaceNormal(collected sub shape ID, inRay.GetPointOnRay(collected faction)).

Implements Shape.

Reimplemented in BoxShape, CapsuleShape, ConvexHullShape, CylinderShape, SphereShape, and TriangleShape.

◆ CastRay() [2/2]

bool ConvexShape::CastRay	(	const RayCast &	inRay,
		const SubShapeIDCreator &	inSubShapeIDCreator,
		RayCastResult &	ioHit
	)		const

overridevirtual

Cast a ray against this shape, returns true if it finds a hit closer than ioHit.mFraction and updates that fraction. Otherwise ioHit is left untouched and the function returns false. Note that the ray should be relative to the center of mass of this shape (i.e. subtract Shape::GetCenterOfMass() from RayCast::mOrigin if you want to cast against the shape in the space it was created). Convex objects will be treated as solid (meaning if the ray starts inside, you'll get a hit fraction of 0) and back face hits against triangles are returned. If you want the surface normal of the hit use GetSurfaceNormal(ioHit.mSubShapeID2, inRay.GetPointOnRay(ioHit.mFraction)).

Implements Shape.

Reimplemented in BoxShape, CapsuleShape, CapsuleShape, ConvexHullShape, CylinderShape, CylinderShape, SphereShape, and TriangleShape.

◆ CollidePoint()

void ConvexShape::CollidePoint	(	Vec3Arg	inPoint,
		const SubShapeIDCreator &	inSubShapeIDCreator,
		CollidePointCollector &	ioCollector,
		const ShapeFilter &	inShapeFilter = `{ }`
	)		const

overridevirtual

Check if inPoint is inside this shape. For this tests all shapes are treated as if they were solid. Note that inPoint should be relative to the center of mass of this shape (i.e. subtract Shape::GetCenterOfMass() from inPoint if you want to test against the shape in the space it was created). For a mesh shape, this test will only provide sensible information if the mesh is a closed manifold. For each shape that collides, ioCollector will receive a hit.

Implements Shape.

Reimplemented in BoxShape, CapsuleShape, ConvexHullShape, CylinderShape, SphereShape, TaperedCylinderShape, and TriangleShape.

◆ DrawGetSupportFunction()

void ConvexShape::DrawGetSupportFunction	(	DebugRenderer *	inRenderer,
		RMat44Arg	inCenterOfMassTransform,
		Vec3Arg	inScale,
		ColorArg	inColor,
		bool	inDrawSupportDirection
	)		const

overridevirtual

Draw the results of the GetSupportFunction with the convex radius added back on to show any errors introduced by this process (only relevant for convex shapes)

Reimplemented from Shape.

◆ DrawGetSupportingFace()

void ConvexShape::DrawGetSupportingFace	(	DebugRenderer *	inRenderer,
		RMat44Arg	inCenterOfMassTransform,
		Vec3Arg	inScale
	)		const

overridevirtual

Draw the results of the GetSupportingFace function to show any errors introduced by this process (only relevant for convex shapes)

Reimplemented from Shape.

◆ GetDensity()

float ConvexShape::GetDensity ( ) const

inline

Get density of the shape (kg / m^3)

◆ GetMaterial() [1/2]

const PhysicsMaterial * ConvexShape::GetMaterial ( ) const

inline

◆ GetMaterial() [2/2]

virtual const PhysicsMaterial * ConvexShape::GetMaterial ( const SubShapeID & inSubShapeID ) const

inlineoverridevirtual

Get the material assigned to a particular sub shape ID.

Implements Shape.

◆ GetSubmergedVolume()

void ConvexShape::GetSubmergedVolume	(	Mat44Arg	inCenterOfMassTransform,
		Vec3Arg	inScale,
		const Plane &	inSurface,
		float &	outTotalVolume,
		float &	outSubmergedVolume,
		Vec3 &outCenterOfBuoyancy	JPH_IF_DEBUG_RENDERER, RVec3Arg inBaseOffset
	)		const

overridevirtual

Reimplemented in ConvexHullShape, SphereShape, and TriangleShape.

◆ GetSubShapeIDBitsRecursive()

virtual uint ConvexShape::GetSubShapeIDBitsRecursive ( ) const

inlineoverridevirtual

Get the max number of sub shape ID bits that are needed to be able to address any leaf shape in this shape. Used mainly for checking that it is smaller or equal than SubShapeID::MaxBits.

Implements Shape.

◆ GetSupportFunction()

virtual const Support * ConvexShape::GetSupportFunction	(	ESupportMode	inMode,
		SupportBuffer &	inBuffer,
		Vec3Arg	inScale
	)		const

pure virtual

Returns an object that provides the GetSupport function for this shape. inMode determines if this support function includes or excludes the convex radius. of the values returned by the GetSupport function. This improves numerical accuracy of the results. inScale scales this shape in local space.

Implemented in BoxShape, CapsuleShape, ConvexHullShape, CylinderShape, SphereShape, TaperedCapsuleShape, TaperedCylinderShape, and TriangleShape.

◆ GetTrianglesNext()

int ConvexShape::GetTrianglesNext	(	GetTrianglesContext &	ioContext,
		int	inMaxTrianglesRequested,
		Float3 *	outTriangleVertices,
		const PhysicsMaterial **	outMaterials = `nullptr`
	)		const

overridevirtual

Call this repeatedly to get all triangles in the box. outTriangleVertices should be large enough to hold 3 * inMaxTriangleRequested entries. outMaterials (if it is not null) should contain inMaxTrianglesRequested entries. The function returns the amount of triangles that it found (which will be <= inMaxTrianglesRequested), or 0 if there are no more triangles. Note that the function can return a value < inMaxTrianglesRequested and still have more triangles to process (triangles can be returned in blocks). Note that the function may return triangles outside of the requested box, only coarse culling is performed on the returned triangles.

Implements Shape.

Reimplemented in BoxShape, CapsuleShape, ConvexHullShape, CylinderShape, SphereShape, TaperedCylinderShape, and TriangleShape.

◆ GetTrianglesStart()

void ConvexShape::GetTrianglesStart	(	GetTrianglesContext &	ioContext,
		const AABox &	inBox,
		Vec3Arg	inPositionCOM,
		QuatArg	inRotation,
		Vec3Arg	inScale
	)		const

overridevirtual

To start iterating over triangles, call this function first. ioContext is a temporary buffer and should remain untouched until the last call to GetTrianglesNext. inBox is the world space bounding in which you want to get the triangles. inPositionCOM/inRotation/inScale describes the transform of this shape. To get the actual triangles call GetTrianglesNext.

Implements Shape.

Reimplemented in BoxShape, CapsuleShape, ConvexHullShape, CylinderShape, SphereShape, TaperedCylinderShape, and TriangleShape.

◆ RestoreBinaryState()

void ConvexShape::RestoreBinaryState ( StreamIn & inStream )

overrideprotectedvirtual

This function should not be called directly, it is used by sRestoreFromBinaryState.

Reimplemented from Shape.

Reimplemented in BoxShape, CapsuleShape, ConvexHullShape, CylinderShape, SphereShape, TaperedCapsuleShape, TaperedCylinderShape, and TriangleShape.

◆ RestoreMaterialState()

void ConvexShape::RestoreMaterialState	(	const PhysicsMaterialRefC *	inMaterials,
		uint	inNumMaterials
	)

overridevirtual

Restore the material references after calling sRestoreFromBinaryState. Note that the exact same materials need to be provided in the same order as returned by SaveMaterialState.

Reimplemented from Shape.

◆ SaveBinaryState()

void ConvexShape::SaveBinaryState ( StreamOut & inStream ) const

overridevirtual

Saves the contents of the shape in binary form to inStream.

Reimplemented from Shape.

Reimplemented in BoxShape, CapsuleShape, ConvexHullShape, CylinderShape, SphereShape, TaperedCapsuleShape, TaperedCylinderShape, and TriangleShape.

◆ SaveMaterialState()

void ConvexShape::SaveMaterialState ( PhysicsMaterialList & outMaterials ) const

overridevirtual

◆ SetDensity()

void ConvexShape::SetDensity ( float inDensity )

inline

Set density of the shape (kg / m^3)

◆ SetMaterial()

void ConvexShape::SetMaterial ( const PhysicsMaterial * inMaterial )

inline

Material of the shape.

◆ sRegister()

void ConvexShape::sRegister ( )

static

Member Data Documentation

◆ sUnitSphereTriangles

const StaticArray< Vec3, 384 > ConvexShape::sUnitSphereTriangles

staticprotected

Initial value:

= []() {
    const int level = 2;
 
    StaticArray<Vec3, 384> verts;
    GetTrianglesContextVertexList::sCreateHalfUnitSphereTop(verts, level);
    GetTrianglesContextVertexList::sCreateHalfUnitSphereBottom(verts, level);
    return verts;
}()

Vertex list that forms a unit sphere.

The documentation for this class was generated from the following files:

Jolt/Physics/Collision/Shape/ConvexShape.h
Jolt/Physics/Collision/Shape/ConvexShape.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ESupportMode

Constructor & Destructor Documentation

◆ ConvexShape() [1/3]

◆ ConvexShape() [2/3]

◆ ConvexShape() [3/3]

Member Function Documentation

◆ CastRay() [1/2]

◆ CastRay() [2/2]

◆ CollidePoint()

◆ DrawGetSupportFunction()

◆ DrawGetSupportingFace()

◆ GetDensity()

◆ GetMaterial() [1/2]

◆ GetMaterial() [2/2]

◆ GetSubmergedVolume()

◆ GetSubShapeIDBitsRecursive()

◆ GetSupportFunction()

◆ GetTrianglesNext()

◆ GetTrianglesStart()

◆ RestoreBinaryState()

◆ RestoreMaterialState()

◆ SaveBinaryState()

◆ SaveMaterialState()

◆ SetDensity()

◆ SetMaterial()

◆ sRegister()

Member Data Documentation

◆ sUnitSphereTriangles