HairSettings.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/Core/Reference.h>
#include <Jolt/Geometry/AABox.h>
#include <Jolt/Geometry/IndexedTriangle.h>
#include <Jolt/ObjectStream/SerializableObject.h>
#include <Jolt/Compute/ComputeBuffer.h>
#include <Jolt/Compute/ComputeSystem.h>
#include <Jolt/Shaders/HairStructs.h>
 
JPH_NAMESPACE_BEGIN
 
class StreamOut;
class StreamIn;

class JPH_EXPORT HairSettings : public RefTarget<HairSettings>
{
    JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, HairSettings)
 
public:
    struct JPH_EXPORT SkinWeight : public JPH_HairSkinWeight
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, SkinWeight)
    };

    struct JPH_EXPORT SkinPoint : public JPH_HairSkinPoint
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, SkinPoint)
    };
 
    static constexpr uint32 cNoInfluence = ~uint32(0);

    struct JPH_EXPORT SVertexInfluence : public JPH_HairSVertexInfluence
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, SVertexInfluence)
 
        inline          SVertexInfluence()                          { mVertexIndex = cNoInfluence; mRelativePosition = JPH_float3(0, 0, 0); mWeight = 0.0f; }
    };

    struct JPH_EXPORT RVertex
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, RVertex)
 
        Float3          mPosition { 0, 0, 0 };                      
        SVertexInfluence mInfluences[cHairNumSVertexInfluences];    
    };

    struct JPH_EXPORT SVertex
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, SVertex)
 
        
                        SVertex() = default;
        explicit        SVertex(const Float3 &inPosition, float inInvMass = 1.0f) : mPosition(inPosition), mInvMass(inInvMass) { }
 
        Float3          mPosition { 0, 0, 0 };                      
        float           mInvMass = 1.0f;                            
        float           mLength = 0.0f;                             
        float           mStrandFraction = 0.0f;                     
        Float4          mBishop { 0, 0, 0, 1.0f };                  
        Float4          mOmega0 { 0, 0, 0, 1.0f };                  
    };

    struct JPH_EXPORT RStrand
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, RStrand)
 
        
                        RStrand() = default;
                        RStrand(uint32 inStartVtx, uint32 inEndVtx) : mStartVtx(inStartVtx), mEndVtx(inEndVtx) { }
 
        uint32          VertexCount() const                         { return mEndVtx - mStartVtx; }
 
        float           MeasureLength(const Array<SVertex> &inVertices) const
        {
            float length = 0.0f;
            for (uint32 v = mStartVtx; v < mEndVtx - 1; ++v)
                length += (Vec3(inVertices[v + 1].mPosition) - Vec3(inVertices[v].mPosition)).Length();
            return length;
        }
 
        uint32          mStartVtx;
        uint32          mEndVtx;
    };

    struct JPH_EXPORT SStrand : public RStrand
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, SStrand)
 
                        SStrand() = default;
                        SStrand(uint32 inStartVtx, uint32 inEndVtx, uint32 inMaterialIndex) : RStrand(inStartVtx, inEndVtx), mMaterialIndex(inMaterialIndex) { }
 
        uint32          mMaterialIndex = 0;                         
    };

    class JPH_EXPORT Gradient
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, Gradient)
 
    public:
                        Gradient() = default;
                        Gradient(float inMin, float inMax, float inMinFraction = 0.0f, float inMaxFraction = 1.0f) : mMin(inMin), mMax(inMax), mMinFraction(inMinFraction), mMaxFraction(inMaxFraction) { }

        Gradient        MakeStepDependent(float inTimeRatio) const
        {
            auto make_dependent = [inTimeRatio](float inValue) {
                    return 1.0f - std::pow(1.0f - inValue, inTimeRatio);
                };
 
            return Gradient(make_dependent(mMin), make_dependent(mMax), mMinFraction, mMaxFraction);
        }

        void            SaveBinaryState(StreamOut &inStream) const;

        void            RestoreBinaryState(StreamIn &inStream);
 
        float           mMin = 0.0f;                                
        float           mMax = 1.0f;                                
        float           mMinFraction = 0.0f;                        
        float           mMaxFraction = 1.0f;                        
    };
 
    class GradientSampler
    {
    public:
                        GradientSampler() = default;
 
        explicit        GradientSampler(const Gradient &inGradient) :
            mMultiplier((inGradient.mMax - inGradient.mMin) / (inGradient.mMaxFraction - inGradient.mMinFraction)),
            mOffset(inGradient.mMin - inGradient.mMinFraction * mMultiplier),
            mMin(min(inGradient.mMin, inGradient.mMax)),
            mMax(max(inGradient.mMin, inGradient.mMax))
        {
        }

        inline float    Sample(float inFraction) const
        {
            return min(mMax, max(mMin, mOffset + inFraction * mMultiplier));
        }
 
        inline float    Sample(const SStrand &inStrand, uint32 inVertex) const
        {
            return Sample(float(inVertex - inStrand.mStartVtx) / float(inStrand.VertexCount() - 1));
        }

        inline Float4   ToFloat4() const
        {
            return Float4(mMultiplier, mOffset, mMin, mMax);
        }
 
    private:
        float           mMultiplier;
        float           mOffset;
        float           mMin;
        float           mMax;
    };

    struct JPH_EXPORT Material
    {
        JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, Material)
 
        
        bool            NeedsGrid() const                           { return mGridVelocityFactor.mMin != 0.0f || mGridVelocityFactor.mMax != 0.0f || mGridDensityForceFactor != 0.0f; }

        bool            GlobalPoseOnly() const                      { return !mEnableCollision && mGlobalPose.mMin == 1.0f && mGlobalPose.mMax == 1.0f; }

        float           GetBendCompliance(float inStrandFraction) const
        {
            float fraction = inStrandFraction * 3.0f;
            uint idx = min(uint(fraction), 2u);
            fraction = fraction - float(idx);
            JPH_ASSERT(fraction >= 0.0f && fraction <= 1.0f);
            float multiplier = mBendComplianceMultiplier[idx] * (1.0f - fraction) + mBendComplianceMultiplier[idx + 1] * fraction;
            return multiplier * mBendCompliance;
        }
 
        bool            mEnableCollision = true;                    
        bool            mEnableLRA = true;                          
        float           mLinearDamping = 2.0f;                      
        float           mAngularDamping = 2.0f;                     
        float           mMaxLinearVelocity = 10.0f;                 
        float           mMaxAngularVelocity = 50.0f;                
        Gradient        mGravityFactor { 0.1f, 1.0f, 0.2f, 0.8f };  
        float           mFriction = 0.2f;                           
        float           mBendCompliance = 1.0e-7f;                  
        Float4          mBendComplianceMultiplier = { 1.0f, 100.0f, 100.0f, 1.0f }; 
        float           mStretchCompliance = 1.0e-8f;               
        float           mInertiaMultiplier = 10.0f;                 
        Gradient        mHairRadius = { 0.001f, 0.001f };           
        Gradient        mWorldTransformInfluence { 0.0f, 1.0f };    
        Gradient        mGridVelocityFactor { 0.05f, 0.01f };       
        float           mGridDensityForceFactor = 0.0f;             
        Gradient        mGlobalPose { 0.01f, 0, 0.0f, 0.3f };       
        Gradient        mSkinGlobalPose { 1.0f, 0.0f, 0.0f, 0.1f }; 
        float           mSimulationStrandsFraction = 0.1f;          
        float           mGravityPreloadFactor = 0.0f;               
    };

    void                InitRenderAndSimulationStrands(const Array<SVertex> &inVertices, const Array<SStrand> &inStrands);

    static void         sResample(Array<SVertex> &ioVertices, Array<SStrand> &ioStrands, uint32 inNumVerticesPerStrand);

    void                Init(float &outMaxDistSqHairToScalp);

    void                InitCompute(ComputeSystem *inComputeSystem);

    float               GetNeutralDensity(uint32 inX, uint32 inY, uint32 inZ) const
    {
        JPH_ASSERT(inX < mGridSize.GetX() && inY < mGridSize.GetY() && inZ < mGridSize.GetZ());
        return mNeutralDensity[inX + inY * mGridSize.GetX() + inZ * mGridSize.GetX() * mGridSize.GetY()];
    }

    inline uint32       GetNumVerticesPadded() const
    {
        return uint32(mSimStrands.size()) * mMaxVerticesPerStrand;
    }

    void                PrepareForScalpSkinning(Mat44Arg inJointToHair, const Mat44 *inJointMatrices, Mat44 *outJointMatrices) const;

    void                SkinScalpVertices(Mat44Arg inJointToHair, const Mat44 *inJointMatrices, Array<Vec3> &outVertices) const;

    void                SaveBinaryState(StreamOut &inStream) const;

    void                RestoreBinaryState(StreamIn &inStream);
 
    class GridSampler
    {
    public:
        inline explicit GridSampler(const HairSettings *inSettings) :
            mGridSizeMin2(inSettings->mGridSize - UVec4::sReplicate(2)),
            mGridSizeMin1((inSettings->mGridSize - UVec4::sReplicate(1)).ToFloat()),
            mGridStride(1, inSettings->mGridSize.GetX(), inSettings->mGridSize.GetX() * inSettings->mGridSize.GetY(), 0),
            mOffset(inSettings->mSimulationBounds.mMin),
            mScale(Vec3(inSettings->mGridSize.ToFloat()) / inSettings->mSimulationBounds.GetSize())
        {
        }

        inline void     PositionToIndexAndFraction(Vec3Arg inPosition, UVec4 &outIndex, Vec3 &outFraction) const
        {
            // Get position in grid space
            Vec3 grid_pos = Vec3::sMin(Vec3::sMax(inPosition - mOffset, Vec3::sZero()) * mScale, mGridSizeMin1);
            outIndex = UVec4::sMin(Vec4(grid_pos).ToInt(), mGridSizeMin2);
            outFraction = grid_pos - Vec3(outIndex.ToFloat());
        }
 
        template <typename F>
        inline void     Sample(UVec4Arg inIndex, Vec3Arg inFraction, const F &inFunc) const
        {
            Vec3 fraction[] = { Vec3::sReplicate(1.0f) - inFraction, inFraction };
 
            // Sample the grid
            for (uint32 z = 0; z < 2; ++z)
                for (uint32 y = 0; y < 2; ++y)
                    for (uint32 x = 0; x < 2; ++x)
                    {
                        uint32 index = mGridStride.Dot(inIndex + UVec4(x, y, z, 0));
                        float combined_fraction = fraction[x].GetX() * fraction[y].GetY() * fraction[z].GetZ();
                        inFunc(index, combined_fraction);
                    }
        }
 
        template <typename F>
        inline void     Sample(Vec3Arg inPosition, const F &inFunc) const
        {
            UVec4 index;
            Vec3 fraction;
            PositionToIndexAndFraction(inPosition, index, fraction);
            Sample(index, fraction, inFunc);
        }
 
        UVec4           mGridSizeMin2;
        Vec3            mGridSizeMin1;
        UVec4           mGridStride;
        Vec3            mOffset;
        Vec3            mScale;
    };
 
    static constexpr uint32 cDefaultIterationsPerSecond = 360;
 
    Array<SVertex>      mSimVertices;                               
    Array<SStrand>      mSimStrands;                                
 
    Array<RVertex>      mRenderVertices;                            
    Array<RStrand>      mRenderStrands;                             
 
    Array<Float3>       mScalpVertices;                             
    Array<IndexedTriangleNoMaterial> mScalpTriangles;               
    Array<Mat44>        mScalpInverseBindPose;                      
    Array<SkinWeight>   mScalpSkinWeights;                          
    uint                mScalpNumSkinWeightsPerVertex = 0;          
 
    uint32              mNumIterationsPerSecond = cDefaultIterationsPerSecond;
    float               mMaxDeltaTime = 1.0f / 30.0f;               
    UVec4               mGridSize { 32, 32, 32, 0 };                
    Vec3                mSimulationBoundsPadding = Vec3::sReplicate(0.1f); 
    Vec3                mInitialGravity { 0, -9.81f, 0 };           
    Array<Material>     mMaterials;                                 
 
    // Values computed by Init
    Array<SkinPoint>    mSkinPoints;                                
    AABox               mSimulationBounds { Vec3::sZero(), 1.0f };  
    Array<float>        mNeutralDensity;                            
    float               mDensityScale = 0.0f;                       
    uint32              mMaxVerticesPerStrand = 0;                  
 
    // Compute data
    Ref<ComputeBuffer>  mScalpVerticesCB;
    Ref<ComputeBuffer>  mScalpTrianglesCB;
    Ref<ComputeBuffer>  mScalpSkinWeightsCB;
    Ref<ComputeBuffer>  mSkinPointsCB;
    Ref<ComputeBuffer>  mVerticesFixedCB;
    Ref<ComputeBuffer>  mVerticesPositionCB;
    Ref<ComputeBuffer>  mVerticesBishopCB;
    Ref<ComputeBuffer>  mVerticesOmega0CB;
    Ref<ComputeBuffer>  mVerticesLengthCB;
    Ref<ComputeBuffer>  mVerticesStrandFractionCB;
    Ref<ComputeBuffer>  mStrandVertexCountsCB;
    Ref<ComputeBuffer>  mStrandMaterialIndexCB;
    Ref<ComputeBuffer>  mNeutralDensityCB;
    Ref<ComputeBuffer>  mSVertexInfluencesCB;
};
 
JPH_NAMESPACE_END