HeightFieldShape.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/Collision/Shape/Shape.h>
#include <Jolt/Physics/Collision/PhysicsMaterial.h>
#ifdef JPH_DEBUG_RENDERER
    #include <Jolt/Renderer/DebugRenderer.h>
#endif // JPH_DEBUG_RENDERER
 
JPH_NAMESPACE_BEGIN
 
class ConvexShape;
class CollideShapeSettings;
class TempAllocator;

namespace HeightFieldShapeConstants
{
    constexpr float                 cNoCollisionValue = FLT_MAX;

    constexpr int                   cStackSize = 128;

    constexpr uint                  cNumBitsXY = 14;
    constexpr uint                  cMaskBitsXY = (1 << cNumBitsXY) - 1;
    constexpr uint                  cLevelShift = 2 * cNumBitsXY;

    constexpr uint16                cNoCollisionValue16 = 0xffff;               
    constexpr uint16                cMaxHeightValue16 = 0xfffe;                 
};

class JPH_EXPORT HeightFieldShapeSettings final : public ShapeSettings
{
    JPH_DECLARE_SERIALIZABLE_VIRTUAL(JPH_EXPORT, HeightFieldShapeSettings)
 
public:
                                    HeightFieldShapeSettings() = default;

                                    HeightFieldShapeSettings(const float *inSamples, Vec3Arg inOffset, Vec3Arg inScale, uint32 inSampleCount, const uint8 *inMaterialIndices = nullptr, const PhysicsMaterialList &inMaterialList = PhysicsMaterialList());
 
    // See: ShapeSettings
    virtual ShapeResult             Create() const override;

    void                            DetermineMinAndMaxSample(float &outMinValue, float &outMaxValue, float &outQuantizationScale) const;

    uint32                          CalculateBitsPerSampleForError(float inMaxError) const;

    Vec3                            mOffset = Vec3::sZero();
    Vec3                            mScale = Vec3::sOne();
    uint32                          mSampleCount = 0;

    float                           mMinHeightValue = cLargeFloat;

    float                           mMaxHeightValue = -cLargeFloat;

    uint32                          mMaterialsCapacity = 0;

    uint32                          mBlockSize = 2;

    uint32                          mBitsPerSample = 8;

    Array<float>                    mHeightSamples;

    Array<uint8>                    mMaterialIndices;

    PhysicsMaterialList             mMaterials;

    float                           mActiveEdgeCosThresholdAngle = 0.996195f;   // cos(5 degrees)
};

class JPH_EXPORT HeightFieldShape final : public Shape
{
public:
    JPH_OVERRIDE_NEW_DELETE

                                    HeightFieldShape() : Shape(EShapeType::HeightField, EShapeSubType::HeightField) { }
                                    HeightFieldShape(const HeightFieldShapeSettings &inSettings, ShapeResult &outResult);
    virtual                         ~HeightFieldShape() override;

    Ref<HeightFieldShape>           Clone() const;
 
    // See Shape::MustBeStatic
    virtual bool                    MustBeStatic() const override               { return true; }

    inline uint                     GetSampleCount() const                      { return mSampleCount; }

    inline uint                     GetBlockSize() const                        { return mBlockSize; }
 
    // See Shape::GetLocalBounds
    virtual AABox                   GetLocalBounds() const override;
 
    // See Shape::GetSubShapeIDBitsRecursive
    virtual uint                    GetSubShapeIDBitsRecursive() const override { return GetSubShapeIDBits(); }
 
    // See Shape::GetInnerRadius
    virtual float                   GetInnerRadius() const override             { return 0.0f; }
 
    // See Shape::GetMassProperties
    virtual MassProperties          GetMassProperties() const override;
 
    // See Shape::GetMaterial
    virtual const PhysicsMaterial * GetMaterial(const SubShapeID &inSubShapeID) const override;

    const PhysicsMaterial *         GetMaterial(uint inX, uint inY) const;
 
    // See Shape::GetSurfaceNormal
    virtual Vec3                    GetSurfaceNormal(const SubShapeID &inSubShapeID, Vec3Arg inLocalSurfacePosition) const override;
 
    // See Shape::GetSupportingFace
    virtual void                    GetSupportingFace(const SubShapeID &inSubShapeID, Vec3Arg inDirection, Vec3Arg inScale, Mat44Arg inCenterOfMassTransform, SupportingFace &outVertices) const override;
 
    // See Shape::GetSubmergedVolume
    virtual void                    GetSubmergedVolume(Mat44Arg inCenterOfMassTransform, Vec3Arg inScale, const Plane &inSurface, float &outTotalVolume, float &outSubmergedVolume, Vec3 &outCenterOfBuoyancy JPH_IF_DEBUG_RENDERER(, RVec3Arg inBaseOffset)) const override { JPH_ASSERT(false, "Not supported"); }
 
#ifdef JPH_DEBUG_RENDERER
    // See Shape::Draw
    virtual void                    Draw(DebugRenderer *inRenderer, RMat44Arg inCenterOfMassTransform, Vec3Arg inScale, ColorArg inColor, bool inUseMaterialColors, bool inDrawWireframe) const override;
#endif // JPH_DEBUG_RENDERER
 
    // See Shape::CastRay
    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;
 
    // See: Shape::CollidePoint
    virtual void                    CollidePoint(Vec3Arg inPoint, const SubShapeIDCreator &inSubShapeIDCreator, CollidePointCollector &ioCollector, const ShapeFilter &inShapeFilter = { }) const override;
 
    // See: Shape::CollideSoftBodyVertices
    virtual void                    CollideSoftBodyVertices(Mat44Arg inCenterOfMassTransform, Vec3Arg inScale, const CollideSoftBodyVertexIterator &inVertices, uint inNumVertices, int inCollidingShapeIndex) const override;
 
    // See Shape::GetTrianglesStart
    virtual void                    GetTrianglesStart(GetTrianglesContext &ioContext, const AABox &inBox, Vec3Arg inPositionCOM, QuatArg inRotation, Vec3Arg inScale) const override;
 
    // See Shape::GetTrianglesNext
    virtual int                     GetTrianglesNext(GetTrianglesContext &ioContext, int inMaxTrianglesRequested, Float3 *outTriangleVertices, const PhysicsMaterial **outMaterials = nullptr) const override;

    Vec3                            GetPosition(uint inX, uint inY) const;

    bool                            IsNoCollision(uint inX, uint inY) const;

    bool                            ProjectOntoSurface(Vec3Arg inLocalPosition, Vec3 &outSurfacePosition, SubShapeID &outSubShapeID) const;

    void                            GetSubShapeCoordinates(const SubShapeID &inSubShapeID, uint &outX, uint &outY, uint &outTriangleIndex) const;

    float                           GetMinHeightValue() const                   { return mOffset.GetY(); }
    float                           GetMaxHeightValue() const                   { return mOffset.GetY() + mScale.GetY() * HeightFieldShapeConstants::cMaxHeightValue16; }

    void                            GetHeights(uint inX, uint inY, uint inSizeX, uint inSizeY, float *outHeights, intptr_t inHeightsStride) const;

    void                            SetHeights(uint inX, uint inY, uint inSizeX, uint inSizeY, const float *inHeights, intptr_t inHeightsStride, TempAllocator &inAllocator, float inActiveEdgeCosThresholdAngle = 0.996195f);

    const PhysicsMaterialList &     GetMaterialList() const                     { return mMaterials; }

    void                            GetMaterials(uint inX, uint inY, uint inSizeX, uint inSizeY, uint8 *outMaterials, intptr_t inMaterialsStride) const;

    bool                            SetMaterials(uint inX, uint inY, uint inSizeX, uint inSizeY, const uint8 *inMaterials, intptr_t inMaterialsStride, const PhysicsMaterialList *inMaterialList, TempAllocator &inAllocator);
 
    // See Shape
    virtual void                    SaveBinaryState(StreamOut &inStream) const override;
    virtual void                    SaveMaterialState(PhysicsMaterialList &outMaterials) const override;
    virtual void                    RestoreMaterialState(const PhysicsMaterialRefC *inMaterials, uint inNumMaterials) override;
 
    // See Shape::GetStats
    virtual Stats                   GetStats() const override;
 
    // See Shape::GetVolume
    virtual float                   GetVolume() const override                  { return 0; }
 
#ifdef JPH_DEBUG_RENDERER
    // Settings
    static bool                     sDrawTriangleOutlines;
#endif // JPH_DEBUG_RENDERER
 
    // Register shape functions with the registry
    static void                     sRegister();
 
protected:
    // See: Shape::RestoreBinaryState
    virtual void                    RestoreBinaryState(StreamIn &inStream) override;
 
private:
    class                           DecodingContext;                            
    struct                          HSGetTrianglesContext;                      

    void                            CacheValues();

    void                            AllocateBuffers();

    void                            CalculateActiveEdges(uint inX, uint inY, uint inSizeX, uint inSizeY, const float *inHeights, uint inHeightsStartX, uint inHeightsStartY, intptr_t inHeightsStride, float inHeightsScale, float inActiveEdgeCosThresholdAngle, TempAllocator &inAllocator);

    void                            CalculateActiveEdges(const HeightFieldShapeSettings &inSettings);

    void                            StoreMaterialIndices(const HeightFieldShapeSettings &inSettings);

    inline uint                     GetNumBlocks() const                        { return mSampleCount / mBlockSize; }

    static inline uint              sGetMaxLevel(uint inNumBlocks)              { return 32 - CountLeadingZeros(inNumBlocks - 1); }

    static inline void              sGetRangeBlockOffsetAndStride(uint inNumBlocks, uint inMaxLevel, uint &outRangeBlockOffset, uint &outRangeBlockStride);

    inline void                     GetBlockOffsetAndScale(uint inBlockX, uint inBlockY, uint inRangeBlockOffset, uint inRangeBlockStride, float &outBlockOffset, float &outBlockScale) const;

    inline uint8                    GetHeightSample(uint inX, uint inY) const;

    inline Vec3                     GetPosition(uint inX, uint inY, float inBlockOffset, float inBlockScale, bool &outNoCollision) const;

    uint                            GetSubShapeIDBits() const;

    inline SubShapeID               EncodeSubShapeID(const SubShapeIDCreator &inCreator, uint inX, uint inY, uint inTriangle) const;
    inline void                     DecodeSubShapeID(const SubShapeID &inSubShapeID, uint &outX, uint &outY, uint &outTriangle) const;

    inline uint8                    GetEdgeFlags(uint inX, uint inY, uint inTriangle) const;
 
    // Helper functions called by CollisionDispatch
    static void                     sCollideConvexVsHeightField(const Shape *inShape1, const Shape *inShape2, Vec3Arg inScale1, Vec3Arg inScale2, Mat44Arg inCenterOfMassTransform1, Mat44Arg inCenterOfMassTransform2, const SubShapeIDCreator &inSubShapeIDCreator1, const SubShapeIDCreator &inSubShapeIDCreator2, const CollideShapeSettings &inCollideShapeSettings, CollideShapeCollector &ioCollector, const ShapeFilter &inShapeFilter);
    static void                     sCollideSphereVsHeightField(const Shape *inShape1, const Shape *inShape2, Vec3Arg inScale1, Vec3Arg inScale2, Mat44Arg inCenterOfMassTransform1, Mat44Arg inCenterOfMassTransform2, const SubShapeIDCreator &inSubShapeIDCreator1, const SubShapeIDCreator &inSubShapeIDCreator2, const CollideShapeSettings &inCollideShapeSettings, CollideShapeCollector &ioCollector, const ShapeFilter &inShapeFilter);
    static void                     sCastConvexVsHeightField(const ShapeCast &inShapeCast, const ShapeCastSettings &inShapeCastSettings, const Shape *inShape, Vec3Arg inScale, const ShapeFilter &inShapeFilter, Mat44Arg inCenterOfMassTransform2, const SubShapeIDCreator &inSubShapeIDCreator1, const SubShapeIDCreator &inSubShapeIDCreator2, CastShapeCollector &ioCollector);
    static void                     sCastSphereVsHeightField(const ShapeCast &inShapeCast, const ShapeCastSettings &inShapeCastSettings, const Shape *inShape, Vec3Arg inScale, const ShapeFilter &inShapeFilter, Mat44Arg inCenterOfMassTransform2, const SubShapeIDCreator &inSubShapeIDCreator1, const SubShapeIDCreator &inSubShapeIDCreator2, CastShapeCollector &ioCollector);

    template <class Visitor>
    void                            WalkHeightField(Visitor &ioVisitor) const;

    struct alignas(16) RangeBlock
    {
        uint16                      mMin[4];
        uint16                      mMax[4];
    };

    inline void                     GetRangeBlock(uint inBlockX, uint inBlockY, uint inRangeBlockOffset, uint inRangeBlockStride, RangeBlock *&outBlock, uint &outIndexInBlock);

    static const uint               sGridOffsets[];

    Vec3                            mOffset = Vec3::sZero();
    Vec3                            mScale = Vec3::sOne();

    uint32                          mSampleCount = 0;                           
    uint32                          mBlockSize = 2;                             
    uint32                          mHeightSamplesSize = 0;                     
    uint32                          mRangeBlocksSize = 0;                       
    uint32                          mActiveEdgesSize = 0;                       
    uint8                           mBitsPerSample = 8;                         
    uint8                           mSampleMask = 0xff;                         
    uint16                          mMinSample = HeightFieldShapeConstants::cNoCollisionValue16; 
    uint16                          mMaxSample = HeightFieldShapeConstants::cNoCollisionValue16;
    RangeBlock *                    mRangeBlocks = nullptr;                     
    uint8 *                         mHeightSamples = nullptr;                   
    uint8 *                         mActiveEdges = nullptr;                     

    PhysicsMaterialList             mMaterials;                                 
    Array<uint8>                    mMaterialIndices;                           
    uint32                          mNumBitsPerMaterialIndex = 0;               
 
#ifdef JPH_DEBUG_RENDERER
    mutable Array<DebugRenderer::GeometryRef> mGeometry;
    mutable bool                    mCachedUseMaterialColors = false;           
#endif // JPH_DEBUG_RENDERER
};
 
JPH_NAMESPACE_END