Shape.h

Go to the documentation of this file.

// Jolt Physics Library (https://github.com/jrouwe/JoltPhysics)
// SPDX-FileCopyrightText: 2021 Jorrit Rouwe
// SPDX-License-Identifier: MIT
 
#pragma once
 
#include <Jolt/Physics/Body/MassProperties.h>
#include <Jolt/Physics/Collision/BackFaceMode.h>
#include <Jolt/Physics/Collision/CollisionCollector.h>
#include <Jolt/Physics/Collision/ShapeFilter.h>
#include <Jolt/Geometry/AABox.h>
#include <Jolt/Core/Reference.h>
#include <Jolt/Core/Color.h>
#include <Jolt/Core/Result.h>
#include <Jolt/Core/NonCopyable.h>
#include <Jolt/Core/UnorderedSetFwd.h>
#include <Jolt/Core/ObjectToIDMap.h>
#include <Jolt/ObjectStream/SerializableObject.h>
 
JPH_NAMESPACE_BEGIN
 
struct RayCast;
class RayCastSettings;
struct ShapeCast;
class ShapeCastSettings;
class RayCastResult;
class ShapeCastResult;
class CollidePointResult;
class CollideShapeResult;
class SubShapeIDCreator;
class SubShapeID;
class PhysicsMaterial;
class TransformedShape;
class Plane;
class CollideSoftBodyVertexIterator;
class Shape;
class StreamOut;
class StreamIn;
#ifdef JPH_DEBUG_RENDERER
class DebugRenderer;
#endif // JPH_DEBUG_RENDERER
 
using CastRayCollector = CollisionCollector<RayCastResult, CollisionCollectorTraitsCastRay>;
using CastShapeCollector = CollisionCollector<ShapeCastResult, CollisionCollectorTraitsCastShape>;
using CollidePointCollector = CollisionCollector<CollidePointResult, CollisionCollectorTraitsCollidePoint>;
using CollideShapeCollector = CollisionCollector<CollideShapeResult, CollisionCollectorTraitsCollideShape>;
using TransformedShapeCollector = CollisionCollector<TransformedShape, CollisionCollectorTraitsCollideShape>;
 
using ShapeRefC = RefConst<Shape>;
using ShapeList = Array<ShapeRefC>;
using PhysicsMaterialRefC = RefConst<PhysicsMaterial>;
using PhysicsMaterialList = Array<PhysicsMaterialRefC>;

enum class EShapeType : uint8
{
    Convex,                         
    Compound,                       
    Decorated,                      
    Mesh,                           
    HeightField,                    
    SoftBody,                       
 
    // User defined shapes
    User1,
    User2,
    User3,
    User4,
 
    Plane,                          
    Empty,                          
};

enum class EShapeSubType : uint8
{
    // Convex shapes
    Sphere,
    Box,
    Triangle,
    Capsule,
    TaperedCapsule,
    Cylinder,
    ConvexHull,
 
    // Compound shapes
    StaticCompound,
    MutableCompound,
 
    // Decorated shapes
    RotatedTranslated,
    Scaled,
    OffsetCenterOfMass,
 
    // Other shapes
    Mesh,
    HeightField,
    SoftBody,
 
    // User defined shapes
    User1,
    User2,
    User3,
    User4,
    User5,
    User6,
    User7,
    User8,
 
    // User defined convex shapes
    UserConvex1,
    UserConvex2,
    UserConvex3,
    UserConvex4,
    UserConvex5,
    UserConvex6,
    UserConvex7,
    UserConvex8,
 
    // Other shapes
    Plane,
    TaperedCylinder,
    Empty,
};
 
// Sets of shape sub types
static constexpr EShapeSubType sAllSubShapeTypes[] = { EShapeSubType::Sphere, EShapeSubType::Box, EShapeSubType::Triangle, EShapeSubType::Capsule, EShapeSubType::TaperedCapsule, EShapeSubType::Cylinder, EShapeSubType::ConvexHull, EShapeSubType::StaticCompound, EShapeSubType::MutableCompound, EShapeSubType::RotatedTranslated, EShapeSubType::Scaled, EShapeSubType::OffsetCenterOfMass, EShapeSubType::Mesh, EShapeSubType::HeightField, EShapeSubType::SoftBody, EShapeSubType::User1, EShapeSubType::User2, EShapeSubType::User3, EShapeSubType::User4, EShapeSubType::User5, EShapeSubType::User6, EShapeSubType::User7, EShapeSubType::User8, EShapeSubType::UserConvex1, EShapeSubType::UserConvex2, EShapeSubType::UserConvex3, EShapeSubType::UserConvex4, EShapeSubType::UserConvex5, EShapeSubType::UserConvex6, EShapeSubType::UserConvex7, EShapeSubType::UserConvex8, EShapeSubType::Plane, EShapeSubType::TaperedCylinder, EShapeSubType::Empty };
static constexpr EShapeSubType sConvexSubShapeTypes[] = { EShapeSubType::Sphere, EShapeSubType::Box, EShapeSubType::Triangle, EShapeSubType::Capsule, EShapeSubType::TaperedCapsule, EShapeSubType::Cylinder, EShapeSubType::ConvexHull, EShapeSubType::TaperedCylinder, EShapeSubType::UserConvex1, EShapeSubType::UserConvex2, EShapeSubType::UserConvex3, EShapeSubType::UserConvex4, EShapeSubType::UserConvex5, EShapeSubType::UserConvex6, EShapeSubType::UserConvex7, EShapeSubType::UserConvex8 };
static constexpr EShapeSubType sCompoundSubShapeTypes[] = { EShapeSubType::StaticCompound, EShapeSubType::MutableCompound };
static constexpr EShapeSubType sDecoratorSubShapeTypes[] = { EShapeSubType::RotatedTranslated, EShapeSubType::Scaled, EShapeSubType::OffsetCenterOfMass };

static constexpr uint NumSubShapeTypes = uint(std::size(sAllSubShapeTypes));

static constexpr const char *sSubShapeTypeNames[] = { "Sphere", "Box", "Triangle", "Capsule", "TaperedCapsule", "Cylinder", "ConvexHull", "StaticCompound", "MutableCompound", "RotatedTranslated", "Scaled", "OffsetCenterOfMass", "Mesh", "HeightField", "SoftBody", "User1", "User2", "User3", "User4", "User5", "User6", "User7", "User8", "UserConvex1", "UserConvex2", "UserConvex3", "UserConvex4", "UserConvex5", "UserConvex6", "UserConvex7", "UserConvex8", "Plane", "TaperedCylinder", "Empty" };
static_assert(std::size(sSubShapeTypeNames) == NumSubShapeTypes);

class JPH_EXPORT ShapeSettings : public SerializableObject, public RefTarget<ShapeSettings>
{
    JPH_DECLARE_SERIALIZABLE_ABSTRACT(JPH_EXPORT, ShapeSettings)
 
public:
    using ShapeResult = Result<Ref<Shape>>;

    virtual ShapeResult             Create() const = 0;

    void                            ClearCachedResult()                                                 { mCachedResult.Clear(); }

    uint64                          mUserData = 0;
 
protected:
    mutable ShapeResult             mCachedResult;
};

class JPH_EXPORT ShapeFunctions
{
public:
    Shape *                         (*mConstruct)() = nullptr;

    Color                           mColor = Color::sBlack;

    static inline ShapeFunctions &  sGet(EShapeSubType inSubType)                                       { return sRegistry[int(inSubType)]; }
 
private:
    static ShapeFunctions           sRegistry[NumSubShapeTypes];
};

class JPH_EXPORT Shape : public RefTarget<Shape>, public NonCopyable
{
public:
    JPH_OVERRIDE_NEW_DELETE
 
    using ShapeResult = ShapeSettings::ShapeResult;

                                    Shape(EShapeType inType, EShapeSubType inSubType) : mShapeType(inType), mShapeSubType(inSubType) { }
                                    Shape(EShapeType inType, EShapeSubType inSubType, const ShapeSettings &inSettings, [[maybe_unused]] ShapeResult &outResult) : mUserData(inSettings.mUserData), mShapeType(inType), mShapeSubType(inSubType) { }

    virtual                         ~Shape() = default;

    inline EShapeType               GetType() const                                                     { return mShapeType; }
    inline EShapeSubType            GetSubType() const                                                  { return mShapeSubType; }

    uint64                          GetUserData() const                                                 { return mUserData; }
    void                            SetUserData(uint64 inUserData)                                      { mUserData = inUserData; }

    virtual bool                    MustBeStatic() const                                                { return false; }

    virtual Vec3                    GetCenterOfMass() const                                             { return Vec3::sZero(); }

    virtual AABox                   GetLocalBounds() const = 0;

    virtual uint                    GetSubShapeIDBitsRecursive() const = 0;

    virtual AABox                   GetWorldSpaceBounds(Mat44Arg inCenterOfMassTransform, Vec3Arg inScale) const { return GetLocalBounds().Scaled(inScale).Transformed(inCenterOfMassTransform); }

    AABox                           GetWorldSpaceBounds(DMat44Arg inCenterOfMassTransform, Vec3Arg inScale) const
    {
        // Use single precision version using the rotation only
        AABox bounds = GetWorldSpaceBounds(inCenterOfMassTransform.GetRotation(), inScale);
 
        // Apply translation
        bounds.Translate(inCenterOfMassTransform.GetTranslation());
 
        return bounds;
    }

    virtual float                   GetInnerRadius() const = 0;

    virtual MassProperties          GetMassProperties() const = 0;

    virtual const Shape *           GetLeafShape([[maybe_unused]] const SubShapeID &inSubShapeID, SubShapeID &outRemainder) const;

    virtual const PhysicsMaterial * GetMaterial(const SubShapeID &inSubShapeID) const = 0;

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

    using SupportingFace = StaticArray<Vec3, 32>;

    virtual void                    GetSupportingFace([[maybe_unused]] const SubShapeID &inSubShapeID, [[maybe_unused]] Vec3Arg inDirection, [[maybe_unused]] Vec3Arg inScale, [[maybe_unused]] Mat44Arg inCenterOfMassTransform, [[maybe_unused]] SupportingFace &outVertices) const { /* Nothing */ }

    virtual uint64                  GetSubShapeUserData([[maybe_unused]] const SubShapeID &inSubShapeID) const          { return mUserData; }

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

#ifdef JPH_DEBUG_RENDERER
#endif
    virtual void                    GetSubmergedVolume(Mat44Arg inCenterOfMassTransform, Vec3Arg inScale, const Plane &inSurface, float &outTotalVolume, float &outSubmergedVolume, Vec3 &outCenterOfBuoyancy
#ifdef JPH_DEBUG_RENDERER // Not using JPH_IF_DEBUG_RENDERER for Doxygen
        , RVec3Arg inBaseOffset
#endif
        ) const = 0;
 
#ifdef JPH_DEBUG_RENDERER
    virtual void                    Draw(DebugRenderer *inRenderer, RMat44Arg inCenterOfMassTransform, Vec3Arg inScale, ColorArg inColor, bool inUseMaterialColors, bool inDrawWireframe) const = 0;

    virtual void                    DrawGetSupportFunction([[maybe_unused]] DebugRenderer *inRenderer, [[maybe_unused]] RMat44Arg inCenterOfMassTransform, [[maybe_unused]] Vec3Arg inScale, [[maybe_unused]] ColorArg inColor, [[maybe_unused]] bool inDrawSupportDirection) const { /* Only implemented for convex shapes */ }

    virtual void                    DrawGetSupportingFace([[maybe_unused]] DebugRenderer *inRenderer, [[maybe_unused]] RMat44Arg inCenterOfMassTransform, [[maybe_unused]] Vec3Arg inScale) const { /* Only implemented for convex shapes */ }
#endif // JPH_DEBUG_RENDERER

    virtual bool                    CastRay(const RayCast &inRay, const SubShapeIDCreator &inSubShapeIDCreator, RayCastResult &ioHit) const = 0;

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

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

    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;

    struct alignas(16)              GetTrianglesContext { uint8 mData[4288]; };

    static constexpr int            cGetTrianglesMinTrianglesRequested = 32;

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

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


    virtual void                    SaveBinaryState(StreamOut &inStream) const;

    static ShapeResult              sRestoreFromBinaryState(StreamIn &inStream);

    virtual void                    SaveMaterialState([[maybe_unused]] PhysicsMaterialList &outMaterials) const         { /* By default do nothing */ }

    virtual void                    RestoreMaterialState([[maybe_unused]] const PhysicsMaterialRefC *inMaterials, [[maybe_unused]] uint inNumMaterials) { JPH_ASSERT(inNumMaterials == 0); }

    virtual void                    SaveSubShapeState([[maybe_unused]] ShapeList &outSubShapes) const                   { /* By default do nothing */ }

    virtual void                    RestoreSubShapeState([[maybe_unused]] const ShapeRefC *inSubShapes, [[maybe_unused]] uint inNumShapes) { JPH_ASSERT(inNumShapes == 0); }
 
    using ShapeToIDMap = StreamUtils::ObjectToIDMap<Shape>;
    using IDToShapeMap = StreamUtils::IDToObjectMap<Shape>;
    using MaterialToIDMap = StreamUtils::ObjectToIDMap<PhysicsMaterial>;
    using IDToMaterialMap = StreamUtils::IDToObjectMap<PhysicsMaterial>;

    void                            SaveWithChildren(StreamOut &inStream, ShapeToIDMap &ioShapeMap, MaterialToIDMap &ioMaterialMap) const;

    static ShapeResult              sRestoreWithChildren(StreamIn &inStream, IDToShapeMap &ioShapeMap, IDToMaterialMap &ioMaterialMap);


    struct Stats
    {
                                    Stats(size_t inSizeBytes, uint inNumTriangles) : mSizeBytes(inSizeBytes), mNumTriangles(inNumTriangles) { }
 
        size_t                      mSizeBytes;             
        uint                        mNumTriangles;          
    };

    virtual Stats                   GetStats() const = 0;
 
    using VisitedShapes = UnorderedSet<const Shape *>;

    virtual Stats                   GetStatsRecursive(VisitedShapes &ioVisitedShapes) const;

    virtual float                   GetVolume() const = 0;

    virtual bool                    IsValidScale(Vec3Arg inScale) const;

    virtual Vec3                    MakeScaleValid(Vec3Arg inScale) const;
 
#ifdef JPH_DEBUG_RENDERER
    static bool                     sDrawSubmergedVolumes;
#endif // JPH_DEBUG_RENDERER
 
protected:
    virtual void                    RestoreBinaryState(StreamIn &inStream);

    static void                     sCollidePointUsingRayCast(const Shape &inShape, Vec3Arg inPoint, const SubShapeIDCreator &inSubShapeIDCreator, CollidePointCollector &ioCollector, const ShapeFilter &inShapeFilter);
 
private:
    uint64                          mUserData = 0;
    EShapeType                      mShapeType;
    EShapeSubType                   mShapeSubType;
};
 
JPH_NAMESPACE_END