Rope3D.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "physics/backend/SimulationBackend.h"
 
#include <cstdint>
#include <vector>
 
namespace eve::physics {
 
class DistanceField3D;
class World3D;
 
enum class RopeTopologyChange { Changed, Unchanged };
 
struct RopeColliderId {
    std::uint64_t          value = 0;
    [[nodiscard]] explicit operator bool() const { return value != 0; }
    friend bool            operator==(RopeColliderId, RopeColliderId) = default;
};
 
enum class RopeColliderChange { Changed, Unchanged };
 
class EVENGINE_API_DOMAINS Rope3D final : public ISimulationBackend {
public:
    struct Vec3 {
        float x = 0.f, y = 0.f, z = 0.f;
    };
    Rope3D(int particleCount, float startX, float startY, float startZ, float endX, float endY, float endZ);
 
    void update(float dt);
 
    [[nodiscard("check the rope step outcome")]]
    eve::Result<void> step(const eve::SimulationStep& step, const SimulationSettings& settings) override;
    [[nodiscard]] SimulationObservation observation() const noexcept override { return observation_; }
    [[nodiscard]] SimulationBackendKind kind() const noexcept override { return SimulationBackendKind::Cpu; }
    [[nodiscard]] SimulationDeterminism determinism() const noexcept override {
        return SimulationDeterminism::ToleranceBounded;
    }
    [[nodiscard("check rope observation restore")]]
    eve::Result<void> restoreObservation(const SimulationObservation& observation) override;
 
    void                setGravity(float x, float y, float z);
    [[nodiscard]] float getGravityX() const { return gravity_.x; }
    [[nodiscard]] float getGravityY() const { return gravity_.y; }
    [[nodiscard]] float getGravityZ() const { return gravity_.z; }
 
    void                setStretchCompliance(float compliance);
    [[nodiscard]] float getStretchCompliance() const noexcept { return stretchCompliance_; }
    void               setDistanceConstraintsEnabled(bool enabled) { distanceConstraintsEnabled_ = enabled; }
    [[nodiscard]] bool getDistanceConstraintsEnabled() const { return distanceConstraintsEnabled_; }
    void                setBendCompliance(float compliance);
    [[nodiscard]] float getBendCompliance() const noexcept { return bendCompliance_; }
    void               setBendConstraintsEnabled(bool enabled) { bendConstraintsEnabled_ = enabled; }
    [[nodiscard]] bool getBendConstraintsEnabled() const { return bendConstraintsEnabled_; }
    void                setMaxBending(float fraction);
    [[nodiscard]] float getMaxBending() const { return maxBending_; }
    void                setPlasticity(float yield, float creep);
    [[nodiscard]] float getPlasticYield() const { return plasticYield_; }
    [[nodiscard]] float getPlasticCreep() const { return plasticCreep_; }
    [[nodiscard]] float getBendPlasticity(int bendIndex) const;
    void                setMaxCompression(float fraction);
    [[nodiscard]] float getMaxCompression() const noexcept { return maxCompression_; }
    void                setDamping(float damping);
    [[nodiscard]] float getDamping() const { return damping_; }
    void                setParticleMass(float mass);
    [[nodiscard]] float getParticleMass() const { return particleMass_; }
    void                setRadius(float radius);
    [[nodiscard]] float getRadius() const { return radius_; }
    void               setSelfCollision(bool enabled) { selfCollision_ = enabled; }
    [[nodiscard]] bool getSelfCollision() const { return selfCollision_; }
 
    void setBounds(float x, float y, float z, float width, float height, float depth);
    void clearBounds() { hasBounds_ = false; }
    void                setCollisionFriction(float friction);
    [[nodiscard]] float getCollisionFriction() const { return collisionFriction_; }
    [[nodiscard("retain the collider id")]]
    eve::Result<RopeColliderId> addSphereCollider(float x, float y, float z, float radius);
    [[nodiscard("retain the collider id")]]
    eve::Result<RopeColliderId> addPlaneCollider(float x, float y, float z, float nx, float ny, float nz);
    [[nodiscard("check collider update")]]
    eve::Result<RopeColliderChange> moveSphereCollider(RopeColliderId id, float x, float y, float z);
    [[nodiscard("check collider removal")]]
    eve::Result<RopeColliderChange> removeCollider(RopeColliderId id);
    void clearColliders() { colliders_.clear(); }
    void setCollideWorld(World3D* world) { world_ = world; }
    [[nodiscard]] World3D* getCollideWorld() const { return world_; }
    void setCollideSdf(DistanceField3D* field) { sdf_ = field; }
    [[nodiscard]] DistanceField3D* getCollideSdf() const { return sdf_; }
    void setContinuousCollision(bool enabled) { continuousCollision_ = enabled; }
    [[nodiscard]] bool getContinuousCollision() const { return continuousCollision_; }
    void setCollisionRestitution(float restitution);
    [[nodiscard]] float getCollisionRestitution() const { return collisionRestitution_; }
 
    [[nodiscard("check whether the attachment changed")]]
    eve::Result<RopeTopologyChange> pin(int particleIndex);
    [[nodiscard("check whether the attachment changed")]]
    eve::Result<RopeTopologyChange> attach(int particleIndex, float x, float y, float z);
    [[nodiscard("check the attachment target update")]]
    eve::Result<RopeTopologyChange> moveAttachment(int particleIndex, float x, float y, float z);
    [[nodiscard("check whether the attachment changed")]]
    eve::Result<RopeTopologyChange> detach(int particleIndex);
    [[nodiscard]] bool              isAttached(int particleIndex) const;
 
    void applyForce(float x, float y, float z);
    [[nodiscard("check the requested rope length")]]
    eve::Result<RopeTopologyChange> setRestLength(float length);
    [[nodiscard("check cursor topology change")]]
    eve::Result<RopeTopologyChange> changeLength(float length, float particleSpacing, bool fromEnd = true);
    [[nodiscard]] float             getRestLength() const;
    [[nodiscard]] float             calculateLength() const;
 
    [[nodiscard("check the topology change")]]
    eve::Result<RopeTopologyChange> cut(int elementIndex);
    [[nodiscard("check the topology change")]]
    eve::Result<RopeTopologyChange> repair(int elementIndex);
    [[nodiscard]] bool              isElementActive(int elementIndex) const;
    [[nodiscard]] float             getElementForce(int elementIndex) const;
    [[nodiscard("check the element tearing material update")]]
    eve::Result<RopeTopologyChange> setElementTearResistance(int elementIndex, float multiplier);
 
    void setTearing(float resistance, int maxTearsPerStep);
    void disableTearing() { tearingEnabled_ = false; }
    [[nodiscard]] std::uint64_t getTopologyRevision() const { return topologyRevision_; }
    [[nodiscard]] int getLastTornElementCount() const { return static_cast<int>(lastTornElements_.size()); }
    [[nodiscard]] int getLastTornElement(int eventIndex) const;
 
    [[nodiscard]] int   getParticleCount() const { return static_cast<int>(particles_.size()); }
    [[nodiscard]] int   getElementCount() const { return static_cast<int>(elements_.size()); }
    [[nodiscard]] float getParticleX(int index) const;
    [[nodiscard]] float getParticleY(int index) const;
    [[nodiscard]] float getParticleZ(int index) const;
    [[nodiscard]] float getParticleVelocityX(int index, float dt) const;
    [[nodiscard]] float getParticleVelocityY(int index, float dt) const;
    [[nodiscard]] float getParticleVelocityZ(int index, float dt) const;
    [[nodiscard]] float getSampleX(float mu) const;
    [[nodiscard]] float getSampleY(float mu) const;
    [[nodiscard]] float getSampleZ(float mu) const;
    [[nodiscard]] float getSampleTangentX(float mu) const;
    [[nodiscard]] float getSampleTangentY(float mu) const;
    [[nodiscard]] float getSampleTangentZ(float mu) const;
 
private:
    struct Particle {
        Vec3 position;
        Vec3 previous;
        Vec3 attachment;
        bool attached = false;
    };
    struct Element {
        int   a              = 0;
        int   b              = 0;
        float restLength     = 0.f;
        float lambda         = 0.f;
        float force          = 0.f;
        float tearResistance = 1.f;
        bool  active         = true;
    };
    enum class ColliderKind { Sphere, Plane };
    struct Collider {
        RopeColliderId id;
        ColliderKind   kind = ColliderKind::Sphere;
        Vec3           position{};
        Vec3           normal{};
        float          radius = 0.f;
    };
 
    [[nodiscard]] bool validParticle(int index) const noexcept;
    [[nodiscard]] bool validElement(int index) const noexcept;
    void               integrate(float dt);
    void               solveStretch(float dt);
    void               solveBend(float dt);
    void               updatePlasticity(float dt);
    void               solveSelfCollision();
    void               collideBounds();
    void               solveExternalCollisions();
    void               collideBorrowedSurfaces(float dt);
    void               applyAttachments();
    void               applyTearing();
    void               syncBendState();
    [[nodiscard]] Vec3 samplePosition(float mu) const;
    [[nodiscard]] Vec3 sampleTangent(float mu) const;
 
    std::vector<Particle> particles_;
    std::vector<Element>  elements_;
    Vec3                  gravity_{0.f, -9.81f, 0.f};
    Vec3                  force_{};
    float                 stretchCompliance_          = 0.f;
    bool                  distanceConstraintsEnabled_ = true;
    float                 bendCompliance_             = 0.002f;
    bool                  bendConstraintsEnabled_     = true;
    float                 maxBending_                 = 0.025f;
    float                 plasticYield_               = 0.f;
    float                 plasticCreep_               = 0.f;
    std::vector<float>    bendPlasticity_;
    float                 maxCompression_ = 0.f;
    float                 damping_        = 0.01f;
    float                 particleMass_   = 0.1f;
    float                 radius_         = 0.04f;
    bool                  selfCollision_  = true;
    bool                  hasBounds_      = false;
    Vec3                  boundsMin_{};
    Vec3                  boundsMax_{};
    float                 collisionFriction_ = 0.f;
    std::uint64_t         nextColliderId_    = 1;
    std::vector<Collider> colliders_;
    World3D*              world_                = nullptr;
    DistanceField3D*      sdf_                  = nullptr;
    bool                  continuousCollision_  = true;
    float                 collisionRestitution_ = 0.f;
    bool                  tearingEnabled_       = false;
    float                 tearResistance_       = 1000.f;
    int                   maxTearsPerStep_      = 1;
    std::uint64_t         topologyRevision_     = 0;
    std::vector<int>      lastTornElements_;
    SimulationObservation observation_{};
};
 
}  // namespace eve::physics