Hair.h

Go to the documentation of this file.

// Jolt Physics Library (https://github.com/jrouwe/JoltPhysics)
// SPDX-FileCopyrightText: 2026 Jorrit Rouwe
// SPDX-License-Identifier: MIT
 
#pragma once
 
#include <Jolt/Physics/Hair/HairSettings.h>
#include <Jolt/Physics/Collision/ObjectLayer.h>
#include <Jolt/Physics/Collision/Shape/Shape.h>
#include <Jolt/Core/StridedPtr.h>
#include <Jolt/Core/NonCopyable.h>
 
JPH_NAMESPACE_BEGIN
 
class PhysicsSystem;
#ifdef JPH_DEBUG_RENDERER
class DebugRenderer;
#endif
class HairShaders;

class JPH_EXPORT Hair : public NonCopyable
{
public:
                                        Hair(const HairSettings *inSettings, RVec3Arg inPosition, QuatArg inRotation, ObjectLayer inLayer);
                                        ~Hair();

    void                                Init(ComputeSystem *inComputeSystem);

    void                                SetPosition(RVec3Arg inPosition)                { mPosition = inPosition; }
    void                                SetRotation(QuatArg inRotation)                 { mRotation = inRotation; }
    RMat44                              GetWorldTransform() const                       { return RMat44::sRotationTranslation(mRotation, mPosition); }

    const HairSettings *                GetHairSettings() const                         { return mSettings; }

    void                                OnTeleported()                                  { mTeleported = true; }

    void                                SetScalpVerticesCB(ComputeBuffer *inBuffer)     { mScalpVerticesCB = inBuffer; }

    void                                SetScalpTrianglesCB(ComputeBuffer *inBuffer)    { mScalpTrianglesCB = inBuffer; }

    void                                SetScalpToHead(Mat44Arg inMat)                  { mScalpToHead = inMat; }

    using RenderPositionsToFloat3 = std::function<void(ComputeBuffer *, Float3 *, uint)>;

    void                                OverrideRenderPositionsCB(const RenderPositionsToFloat3 &inRenderPositionsToFloat3) { JPH_ASSERT(mRenderPositionsCB == nullptr, "Must be called before Init"); mRenderPositionsOverridden = true; mRenderPositionsToFloat3 = inRenderPositionsToFloat3; }

    void                                SetRenderPositionsCB(ComputeBuffer *inBuffer)   { JPH_ASSERT(mRenderPositionsOverridden, "Must call OverrideRenderPositionsCB first"); mRenderPositionsCB = inBuffer; }

    void                                Update(float inDeltaTime, Mat44Arg inJointToHair, const Mat44 *inJointMatrices, const PhysicsSystem &inSystem, const HairShaders &inShaders, ComputeSystem *inComputeSystem, ComputeQueue *inComputeQueue);

    ComputeBuffer *                     GetScalpVerticesCB() const                      { return mScalpVerticesCB; }        
    ComputeBuffer *                     GetScalpTrianglesCB() const                     { return mScalpTrianglesCB; }       
    ComputeBuffer *                     GetPositionsCB() const                          { return mPositionsCB; }            
    ComputeBuffer *                     GetVelocitiesCB() const                         { return mVelocitiesCB; }           
    ComputeBuffer *                     GetVelocityAndDensityCB() const                 { return mVelocityAndDensityCB; }   
    ComputeBuffer *                     GetRenderPositionsCB() const                    { return mRenderPositionsCB; }      

    void                                ReadBackGPUState(ComputeQueue *inComputeQueue);

    void                                LockReadBackBuffers();
    void                                UnlockReadBackBuffers();

    const Float3 *                      GetScalpVertices() const                        { return mScalpVertices; }
    const Float3 *                      GetPositions() const                            { return mPositions; }
    const Quat *                        GetRotations() const                            { return mRotations; }
    StridedPtr<const Float3>            GetVelocities() const                           { return { (const Float3 *)&mVelocities->mVelocity, sizeof(JPH_HairVelocity) }; }
    StridedPtr<const Float3>            GetAngularVelocities() const                    { return { (const Float3 *)&mVelocities->mAngularVelocity, sizeof(JPH_HairVelocity) }; }
    const Float4 *                      GetGridVelocityAndDensity() const               { return mVelocityAndDensity; }
    const Float3 *                      GetRenderPositions() const                      { return mRenderPositions; }
 
#ifdef JPH_DEBUG_RENDERER
    enum class ERenderStrandColor
    {
        PerRenderStrand,
        PerSimulatedStrand,
        GravityFactor,
        WorldTransformInfluence,
        GridVelocityFactor,
        GlobalPose,
        SkinGlobalPose,
    };
 
    struct DrawSettings
    {
        uint                            mSimulationStrandBegin = 0;
        uint                            mSimulationStrandEnd = UINT_MAX;
 
        bool                            mDrawRods = true;                               
        bool                            mDrawUnloadedRods = false;                      
        bool                            mDrawVertexVelocity = false;                    
        bool                            mDrawAngularVelocity = false;                   
        bool                            mDrawOrientations = false;                      
        bool                            mDrawNeutralDensity = false;                    
        bool                            mDrawGridDensity = false;                       
        bool                            mDrawGridVelocity = false;                      
        bool                            mDrawSkinPoints = false;                        
        bool                            mDrawRenderStrands = false;                     
        bool                            mDrawInitialGravity = true;                     
        ERenderStrandColor              mRenderStrandColor = ERenderStrandColor::PerSimulatedStrand; 
    };

    void                                Draw(const DrawSettings &inSettings, DebugRenderer *inRenderer);
#endif // JPH_DEBUG_RENDERER
 
protected:
    using Gradient = HairSettings::Gradient;
    using GradientSampler = HairSettings::GradientSampler;
 
    // Information about a colliding shape. Is always a leaf shape, compound shapes are expanded.
    struct LeafShape
    {
                                        LeafShape() = default;
                                        LeafShape(Mat44Arg inTransform, Vec3Arg inScale, Vec3Arg inLinearVelocity, Vec3Arg inAngularVelocity, const Shape *inShape) : mTransform(inTransform), mScale(inScale), mLinearVelocity(inLinearVelocity), mAngularVelocity(inAngularVelocity), mShape(inShape) { }
 
        Mat44                           mTransform;
        Vec3                            mScale;
        Vec3                            mLinearVelocity;
        Vec3                            mAngularVelocity;
        RefConst<Shape>                 mShape;
    };
 
    // Internal context used during a simulation step
    struct UpdateContext
    {
        Mat44                           mDeltaTransform;                                // Transforms positions from the old hair transform to the new
        Quat                            mDeltaTransformQuat;                            // Rotation part of mDeltaTransform
        uint                            mNumIterations;                                 // Number of iterations to run the solver for
        bool                            mNeedsCollision;                                // If collision detection should be performed
        bool                            mNeedsGrid;                                     // If the grid should be calculated
        bool                            mGlobalPoseOnly;                                // If no simulation is needed and only the global pose needs to be applied
        bool                            mHasTransformChanged;                           // If the world transform has changed
        float                           mDeltaTime;                                     // Delta time for a sub step
        float                           mHalfDeltaTime;                                 // 0.5 * mDeltaTime
        float                           mInvDeltaTimeSq;                                // 1 / mDeltaTime^2
        float                           mTwoDivDeltaTime;                               // 2 / mDeltaTime
        float                           mTimeRatio;                                     // Ratio between sub step delta time and default sub step delta time
        Vec3                            mSubStepGravity;                                // Gravity to apply in a sub step
        Array<LeafShape>                mShapes;                                        // List of colliding shapes
    };
 
    // Calculate the UpdateContext parameters
    void                                InitializeContext(UpdateContext &outCtx, float inDeltaTime, const PhysicsSystem &inSystem);
 
    RefConst<HairSettings>              mSettings;                                      // Shared hair settings, must be kept alive during the lifetime of this hair instance
 
    RVec3                               mPrevPosition;                                  // Position at the start of the last time step
    RVec3                               mPosition;                                      // Current position in world space
    Quat                                mPrevRotation;                                  // Rotation at the start of the last time step
    Quat                                mRotation;                                      // Current rotation in world space
    bool                                mTeleported = true;                             // If the hair got teleported and should be set to the default pose
    ObjectLayer                         mLayer;                                         // Layer for the hair to collide with
 
    Mat44                               mScalpToHead = Mat44::sIdentity();              // When skipping skinning, this allow specifying a transform that transforms the scalp mesh into head space
 
    bool                                mRenderPositionsOverridden = false;             // Indicates that the render positions buffer is provided externally
    RenderPositionsToFloat3             mRenderPositionsToFloat3;                       // Function that transforms the render positions buffer to Float3 vertices for debugging purposes
 
    Ref<ComputeBuffer>                  mScalpJointMatricesCB;
    Ref<ComputeBuffer>                  mScalpVerticesCB;
    Ref<ComputeBuffer>                  mScalpTrianglesCB;
    Ref<ComputeBuffer>                  mTargetPositionsCB;                             // Target root positions determined by skinning (where we're interpolating to, eventually written to mPositionsCB)
    Ref<ComputeBuffer>                  mTargetGlobalPoseTransformsCB;                  // Target global pose transforms determined by skinning (where we're interpolating to, eventually written to mGlobalPoseTransformsCB)
    Ref<ComputeBuffer>                  mGlobalPoseTransformsCB;                        // Current global pose transforms used for skinning the hairs
    Ref<ComputeBuffer>                  mShapePlanesCB;
    Ref<ComputeBuffer>                  mShapeVerticesCB;
    Ref<ComputeBuffer>                  mShapeIndicesCB;
    Ref<ComputeBuffer>                  mCollisionPlanesCB;
    Ref<ComputeBuffer>                  mCollisionShapesCB;
    Ref<ComputeBuffer>                  mMaterialsCB;
    Ref<ComputeBuffer>                  mPreviousPositionsCB;
    Ref<ComputeBuffer>                  mPositionsCB;
    Ref<ComputeBuffer>                  mVelocitiesCB;
    Ref<ComputeBuffer>                  mVelocityAndDensityCB;
    Ref<ComputeBuffer>                  mConstantsCB;
    Array<Ref<ComputeBuffer>>           mIterationConstantsCB;
    Ref<ComputeBuffer>                  mRenderPositionsCB;
 
    // Only valid after ReadBackGPUState has been called
    Ref<ComputeBuffer>                  mScalpVerticesReadBackCB;
    Ref<ComputeBuffer>                  mPositionsReadBackCB;
    Ref<ComputeBuffer>                  mVelocitiesReadBackCB;
    Ref<ComputeBuffer>                  mVelocityAndDensityReadBackCB;
    Ref<ComputeBuffer>                  mRenderPositionsReadBackCB;
    const Float3 *                      mScalpVertices = nullptr;
    Float3 *                            mPositions = nullptr;
    Quat *                              mRotations = nullptr;
    JPH_HairVelocity *                  mVelocities = nullptr;
    const Float4 *                      mVelocityAndDensity = nullptr;
    const Float3 *                      mRenderPositions = nullptr;
};
 
JPH_NAMESPACE_END