VolumeFluid.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/Result.h"
#include "fluids/FluidSdf.h"
 
#include <array>
#include <cstdint>
#include <glm/vec3.hpp>
#include <glm/vec4.hpp>
#include <memory>
#include <span>
#include <string>
#include <vector>
 
namespace eve::fluids {
 
enum class VolumeFluidPhase : uint8_t { Liquid, Gas, Granular, Solid };
 
enum class VolumeFluidMaterialCombineMode : uint8_t { Average = 0, Minimum = 1, Multiply = 2, Maximum = 3 };
 
struct VolumeFluidMaterial {
    float density = 1000.f;
    float smoothing = 2.f;
    float viscosity = 2.f;
    float cohesion = 0.2f;
    float buoyancy = 1.f;
    float drag = 0.f;
    float atmosphericPressure = 0.f;
    float diffusion = 0.f;
    float yield = 0.f;
    float vorticity = 0.f;
    float dynamicFriction = 0.2f;
    float staticFriction = 0.2f;
    float rollingFriction = 0.f;
    bool rollingContacts = false;
    float stickiness = 0.f;
    float stickDistance = 0.f;
    VolumeFluidMaterialCombineMode frictionCombine = VolumeFluidMaterialCombineMode::Average;
    VolumeFluidMaterialCombineMode stickinessCombine = VolumeFluidMaterialCombineMode::Average;
    VolumeFluidPhase phase = VolumeFluidPhase::Liquid;
};
 
struct VolumeFluidViscosityColorKey {
    float viscosity = 0.f;
    glm::vec4 color{1.f};
};
 
struct VolumeFluidColorKey {
    float     coordinate = 0.f;
    glm::vec4 color{1.f};
};
 
struct VolumeFluidSettings {
    unsigned capacity = 8192;
    float spacing = 0.1f;
    glm::vec3 gravity{0.f, -9.81f, 0.f};
    glm::vec3 minimum{-2.f, 0.f, -1.f}, maximum{2.f, 3.f, 1.f};
    unsigned iterations = 5;
};
 
struct VolumeFluidParticle {
    glm::vec3 position{0.f};
    glm::vec3 velocity{0.f};
    glm::vec3 angularVelocity{0.f};
    glm::vec3 radii{0.f};
    glm::vec4 orientation{0.f, 0.f, 0.f, 1.f};
    VolumeFluidMaterial material;
    glm::vec4 color{0.1f, 0.5f, 0.9f, 1.f}, data{0.f};
    float life = 0.f;
    unsigned collisionFilter = 0xffff0001u;
    unsigned actorGroup = 0;
    bool selfCollide = true;
};
 
enum class VolumeFluidWindZoneType { Ambient, Spherical };
 
struct VolumeFluidWindZone {
    VolumeFluidWindZoneType type = VolumeFluidWindZoneType::Ambient;
    glm::vec3               center{0.f};
    glm::vec3               direction{0.f, 0.f, 1.f};
    float                   intensity           = 0.f;
    float                   turbulence          = 0.f;
    float                   turbulenceFrequency = 1.f;
    float                   turbulenceSeed      = 0.f;
    float                   radius              = 5.f;
    bool                    radial              = true;
};
 
enum class VolumeFluidColliderShape { Sphere, Box, Capsule };
 
struct VolumeFluidCollider {
    unsigned label = 0;
    VolumeFluidColliderShape shape = VolumeFluidColliderShape::Sphere;
    glm::vec3 center{0.f, 1.f, 0.f}, halfExtent{0.25f};
    float radius = 0.25f;
    glm::vec3 velocity{0.f};
    float friction = 0.2f;
    float staticFriction = 0.2f;
    float rollingFriction = 0.f;
    float stickiness = 0.f;
    float stickDistance = 0.f;
    VolumeFluidMaterialCombineMode frictionCombine = VolumeFluidMaterialCombineMode::Average;
    VolumeFluidMaterialCombineMode stickinessCombine = VolumeFluidMaterialCombineMode::Average;
    bool rollingContacts = false;
    bool solidify = false;
    glm::vec4 rotation{0.f, 0.f, 0.f, 1.f};
    glm::vec3 angularVelocity{0.f};
    unsigned collisionFilter = 0xffff0001u;
    bool isTrigger = false;
};
 
struct VolumeFluidSdfCollider {
    unsigned label = 0;
    MeshSdf   sdf;
    glm::vec3 position{0.f};
    glm::vec4 rotation{0.f, 0.f, 0.f, 1.f};
    float     scale = 1.f;
    bool                           inverted = false;
    glm::vec3                      velocity{0.f};
    glm::vec3                      angularVelocity{0.f};
    float                          friction          = 0.2f;
    float                          staticFriction    = 0.2f;
    float                          rollingFriction   = 0.f;
    float                          stickiness        = 0.f;
    float                          stickDistance     = 0.f;
    VolumeFluidMaterialCombineMode frictionCombine   = VolumeFluidMaterialCombineMode::Average;
    VolumeFluidMaterialCombineMode stickinessCombine = VolumeFluidMaterialCombineMode::Average;
    bool                           rollingContacts   = false;
    unsigned                       collisionFilter   = 0xffff0001u;
    bool isTrigger = false;
};
 
struct VolumeFluidHeightFieldCollider {
    unsigned label = 0;
    std::vector<float> heights;
    glm::ivec2 resolution{2, 2};
    glm::vec3 size{1.f};
    glm::vec3 position{0.f};
    glm::vec4                      rotation{0.f, 0.f, 0.f, 1.f};
    glm::vec3                      velocity{0.f};
    glm::vec3                      angularVelocity{0.f};
    float                          friction          = 0.2f;
    float                          staticFriction    = 0.2f;
    float                          rollingFriction   = 0.f;
    float                          stickiness        = 0.f;
    float                          stickDistance     = 0.f;
    VolumeFluidMaterialCombineMode frictionCombine   = VolumeFluidMaterialCombineMode::Average;
    VolumeFluidMaterialCombineMode stickinessCombine = VolumeFluidMaterialCombineMode::Average;
    bool                           rollingContacts   = false;
    unsigned                       collisionFilter   = 0xffff0001u;
    bool isTrigger = false;
};
 
struct VolumeFluidSdfPose {
    unsigned  label = 0;
    glm::vec3 position{0.f};
    glm::vec4 rotation{0.f, 0.f, 0.f, 1.f};
    float     scale = 1.f;
    glm::vec3 velocity{0.f};
    glm::vec3 angularVelocity{0.f};
};
 
enum class VolumeFluidSdfSliceAxis { X = 0, Y = 1, Z = 2 };
 
struct VolumeFluidSdfSlice {
    unsigned width = 0, height = 0;
    glm::vec3 origin{0.f};
    glm::vec3 stepX{0.f}, stepY{0.f};
    std::vector<float> values;
};
 
struct VolumeFluidContact {
    unsigned  colliderLabel = 0;
    glm::vec3 point{0.f}, normal{0.f}, impulse{0.f};
    unsigned particleIndex = 0;
    unsigned actorGroup = 0;
    float distance = 0.f;
};
 
enum class VolumeFluidContactEventType : uint8_t { Enter, Stay, Exit };
 
struct VolumeFluidContactEvent {
    VolumeFluidContactEventType type = VolumeFluidContactEventType::Enter;
    VolumeFluidContact          contact;
};
 
class EVENGINE_API_DOMAINS VolumeFluidContactTracker final {
public:
    [[nodiscard]] Result<std::vector<VolumeFluidContactEvent>> advance(std::span<const VolumeFluidContact> contacts,
                                                                       float distanceThreshold = .01f);
    void reset();
 
private:
    std::vector<VolumeFluidContact> previous_;
    std::vector<VolumeFluidContact> scratch_;
};
 
struct VolumeFluidAttachmentReaction {
    unsigned colliderLabel = 0;
    glm::vec3 point{0.f};
    glm::vec3 impulse{0.f};
    glm::vec3 angularImpulse{0.f};
};
 
struct VolumeFluidThermalRule {
    unsigned colliderLabel    = 0;
    float    rate             = 0.f;
    float    minimumViscosity = 0.05f, maximumViscosity = 10.f;
    float    minimumCohesion = 0.5f, maximumCohesion = 2.f;
};
 
struct VolumeFluidFieldSample {
    glm::vec3 velocity{0.f};
    glm::vec3 vorticity{0.f};
    float density = 0.f;
    unsigned neighborCount = 0;
};
 
struct VolumeFluidGridCell {
    glm::vec3 center{0.f};
    glm::vec3 size{0.f};
    unsigned particleCount = 0;
};
 
struct VolumeFluidParticleFrame {
    unsigned particleIndex = 0;
    glm::vec3 origin{0.f};
    glm::vec3 x{0.f}, y{0.f}, z{0.f};
};
 
struct VolumeFluidParticleInstance {
    unsigned  particleIndex = 0;
    glm::vec3 position{0.f};
    glm::vec4 orientation{0.f, 0.f, 0.f, 1.f};
    glm::vec3 scale{1.f};
    glm::vec4 color{1.f};
};
 
enum class VolumeFluidParticleEventType : uint8_t { Emitted, Killed };
 
struct VolumeFluidParticleEvent {
    VolumeFluidParticleEventType type = VolumeFluidParticleEventType::Emitted;
    unsigned particleIndex = 0;
    unsigned actorGroup = 0;
    VolumeFluidParticle particle;
};
 
struct VolumeFluidParticleEventBatch {
    std::vector<VolumeFluidParticleEvent> events;
    uint64_t dropped = 0;
};
 
struct VolumeFluidMassProperties {
    float mass = 0.f;
    glm::vec3 centerOfMass{0.f};
    unsigned particleCount = 0;
};
 
struct VolumeFluidRayHit {
    unsigned particleIndex = 0;
    float     distance = 0.f;
    glm::vec3 point{0.f};
    glm::vec3 normal{0.f, 1.f, 0.f};
    VolumeFluidParticle particle;
};
 
struct VolumeFluidDistanceHit {
    unsigned particleIndex = 0;
    float distance = 0.f;
    glm::vec3 queryPoint{0.f};
    glm::vec3 normal{0.f, 1.f, 0.f};
    VolumeFluidParticle particle;
};
 
enum class VolumeFluidQueryType : unsigned { Sphere = 0, Box = 1, Ray = 2 };
 
struct VolumeFluidQueryShape {
    VolumeFluidQueryType type = VolumeFluidQueryType::Sphere;
    glm::vec3 center{0.f};
    glm::vec3 size{0.f};
    glm::vec4 rotation{0.f, 0.f, 0.f, 1.f};
    float     contactOffset = 0.f;
    float     maxDistance   = 0.f;
    unsigned  phaseMask     = 0x0f;
    unsigned collisionFilter = 0xffff0001u;
};
 
struct VolumeFluidQueryHit {
    unsigned            queryIndex    = 0;
    unsigned            particleIndex = 0;
    float               distance      = 0.f;
    glm::vec3           queryPoint{0.f};
    glm::vec3           normal{0.f, 1.f, 0.f};
    VolumeFluidParticle particle;
};
 
struct VolumeFluidSimplex {
    std::array<unsigned, 3> particleIndices{0, 0, 0};
    unsigned                size = 1;
};
 
struct VolumeFluidSimplexHit {
    glm::vec4 simplexBary{1.f, 0.f, 0.f, 0.f};
    glm::vec3 queryPoint{0.f};
    glm::vec3 normal{0.f, 1.f, 0.f};
    float     distance = 0.f;
    unsigned simplexIndex = 0;
    unsigned queryIndex   = 0;
};
 
struct VolumeFluidAttachment {
    unsigned particleIndex = 0;
    unsigned colliderLabel = 0;
    glm::vec3 localPosition{0.f};
    glm::vec4 localOrientation{0.f, 0.f, 0.f, 1.f};
    bool constrainOrientation = true;
    bool dynamic = false;
    float compliance = 0.f;
    float breakThreshold = 1e12f;
};
 
struct VolumeFluidStitch {
    unsigned particleIndex1 = 0, particleIndex2 = 0;
    float compliance = 0.f;
};
 
struct VolumeFluidSnapshot {
    std::string                                 schema  = "eve.volume-fluid";
    unsigned                                    version = 20;
    VolumeFluidSettings                         settings;
    std::vector<VolumeFluidParticle>            particles;
    std::vector<VolumeFluidCollider>            colliders;
    std::vector<VolumeFluidSdfCollider>         sdfColliders;
    std::vector<VolumeFluidHeightFieldCollider> heightFieldColliders;
    std::vector<VolumeFluidAttachment>          attachments;
    std::vector<VolumeFluidStitch>              stitches;
    std::vector<VolumeFluidSimplex> simplexes;
};
 
class EVENGINE_API_DOMAINS VolumeFluid final {
public:
    [[nodiscard]] static Result<std::unique_ptr<VolumeFluid>> create(const VolumeFluidSettings& settings);
    ~VolumeFluid();
    VolumeFluid(const VolumeFluid&)            = delete;
    VolumeFluid& operator=(const VolumeFluid&) = delete;
 
    [[nodiscard]] Result<void> emit(std::span<const VolumeFluidParticle> particles);
    [[nodiscard]] Result<void> configureParticleEvents(unsigned capacity);
    [[nodiscard]] VolumeFluidParticleEventBatch drainParticleEvents();
    [[nodiscard]] Result<void> step(float seconds, unsigned substeps = 4);
    [[nodiscard]] Result<void> setParticleWinds(std::span<const glm::vec3> winds);
    [[nodiscard]] Result<void> setParticleExternalForces(std::span<const glm::vec3> forces);
    [[nodiscard]] Result<void> accumulateWindZones(std::span<const VolumeFluidWindZone> zones, float fixedTimeSeconds);
    [[nodiscard]] Result<void> accumulateExternalForceZones(std::span<const VolumeFluidWindZone> zones,
                                                            float                                fixedTimeSeconds);
    [[nodiscard]] Result<void> stepWithThermalContacts(float seconds, unsigned substeps,
                                                       std::span<const VolumeFluidThermalRule> rules);
    [[nodiscard]] Result<void> stepWithColliders(float seconds, unsigned substeps,
                                                 std::span<const VolumeFluidCollider>    colliders,
                                                 std::span<const VolumeFluidThermalRule> rules = {});
    [[nodiscard]] std::vector<VolumeFluidParticle> particles() const;
    [[nodiscard]] std::span<const VolumeFluidParticle> particleView() const;
    [[nodiscard]] size_t particleCount() const;
    [[nodiscard]] size_t availableCapacity() const;
    [[nodiscard]] float spacing() const;
    [[nodiscard]] Result<void> setGravity(glm::vec3 gravity);
    [[nodiscard]] glm::vec3 gravity() const;
    [[nodiscard]] float copyRenderData(std::vector<glm::vec3>& positions, std::vector<glm::vec4>& colors) const;
    [[nodiscard]] Result<void> copyInterpolatedPositions(float alpha, std::vector<glm::vec3>& positions) const;
    [[nodiscard]] Result<float> copyInterpolatedRenderData(float alpha, std::vector<glm::vec3>& positions,
                                                           std::vector<glm::vec4>& colors) const;
    [[nodiscard]] float copySurfaceRenderData(std::vector<glm::vec3>& positions, std::vector<glm::vec4>& colors,
                                              std::vector<glm::vec3>& radii,
                                              std::vector<glm::vec4>& orientations) const;
    [[nodiscard]] Result<float> copyInterpolatedSurfaceRenderData(float alpha, std::vector<glm::vec3>& positions,
                                                                  std::vector<glm::vec4>& colors,
                                                                  std::vector<glm::vec3>& radii,
                                                                  std::vector<glm::vec4>& orientations) const;
    [[nodiscard]] size_t copyPhaseRenderData(VolumeFluidPhase phase, std::vector<glm::vec3>& positions,
                                             std::vector<glm::vec4>& colors, size_t maxParticles) const;
    [[nodiscard]] Result<void> setColliders(std::span<const VolumeFluidCollider> colliders);
    [[nodiscard]] Result<void> setSdfColliders(std::span<const VolumeFluidSdfCollider> colliders);
    [[nodiscard]] Result<void> setHeightFieldColliders(std::span<const VolumeFluidHeightFieldCollider> colliders);
    [[nodiscard]] Result<unsigned> bindStaticParticles(std::span<const unsigned> particleIndices,
                                                       unsigned colliderLabel, bool constrainOrientation = false);
    [[nodiscard]] Result<unsigned> bindDynamicParticles(std::span<const unsigned> particleIndices,
                                                        unsigned colliderLabel, float compliance, float breakThreshold,
                                                        bool constrainOrientation = false);
    [[nodiscard]] Result<unsigned> unbindStaticParticles(std::span<const unsigned> particleIndices);
    [[nodiscard]] Result<void> setStitches(std::span<const VolumeFluidStitch> stitches);
    [[nodiscard]] Result<void> updateSdfColliderPoses(std::span<const VolumeFluidSdfPose> poses);
    [[nodiscard]] std::vector<VolumeFluidContact> contacts() const;
    [[nodiscard]] std::span<const VolumeFluidAttachmentReaction> attachmentReactions() const;
    [[nodiscard]] Result<std::vector<VolumeFluidParticle>> overlap(glm::vec3 center, float radius) const;
    [[nodiscard]] Result<std::vector<VolumeFluidParticle>> overlapBox(glm::vec3 center, glm::vec3 halfExtent,
                                                                      glm::vec4 rotation) const;
    [[nodiscard]] Result<std::vector<VolumeFluidRayHit>> raycast(glm::vec3 origin, glm::vec3 direction,
                                                                 float maxDistance, unsigned maxHits = 64,
                                                                 unsigned phaseMask = 0x0f) const;
    [[nodiscard]] Result<std::vector<VolumeFluidDistanceHit>> querySphere(glm::vec3 center, float radius,
                                                                          float contactOffset, float maxDistance,
                                                                          unsigned maxHits         = 64,
                                                                          unsigned phaseMask       = 0x0f,
                                                                          unsigned collisionFilter = 0xffffffffu) const;
    [[nodiscard]] Result<std::vector<VolumeFluidDistanceHit>> queryBox(glm::vec3 center, glm::vec3 halfExtent,
                                                                       glm::vec4 rotation, float contactOffset,
                                                                       float maxDistance, unsigned maxHits = 64,
                                                                       unsigned phaseMask       = 0x0f,
                                                                       unsigned collisionFilter = 0xffffffffu) const;
    [[nodiscard]] Result<std::vector<VolumeFluidQueryHit>> queryBatch(std::span<const VolumeFluidQueryShape> queries,
                                                                      unsigned maxHitsPerQuery = 64) const;
    [[nodiscard]] Result<std::vector<unsigned>> applyQueryColors(std::span<const VolumeFluidQueryShape> queries,
                                                                 std::span<const glm::vec4>             overlapColors,
                                                                 glm::vec4 baseColor, unsigned maxHitsPerQuery = 4096);
    [[nodiscard]] Result<std::vector<unsigned>> applyQueryColorsPreservingOutside(
        std::span<const VolumeFluidQueryShape> queries, std::span<const glm::vec4> overlapColors,
        unsigned maxHitsPerQuery = 4096);
    [[nodiscard]] Result<std::vector<VolumeFluidSimplexHit>> querySimplexes(
        std::span<const VolumeFluidQueryShape> queries, unsigned maxHitsPerQuery = 64) const;
    [[nodiscard]] Result<void> setSimplexes(std::span<const VolumeFluidSimplex> simplexes);
    [[nodiscard]] Result<void> paint(glm::vec3 center, float radius, const VolumeFluidMaterial& material);
    [[nodiscard]] Result<void> applyMaterialChannels(std::span<const VolumeFluidViscosityColorKey> colorKeys = {});
    [[nodiscard]] Result<void> applySolidColor(glm::vec4 color);
    [[nodiscard]] Result<void> applyVelocityColors(float sensibility);
    [[nodiscard]] Result<void> applyActorGroupColors();
    [[nodiscard]] Result<void> applyDataColors(unsigned channel, std::span<const VolumeFluidColorKey> gradient);
    [[nodiscard]] Result<void> applyRandomColors(std::span<const VolumeFluidColorKey> gradient, uint32_t seed);
    [[nodiscard]] Result<void> addRandomVelocity(float intensity, uint32_t seed);
    [[nodiscard]] Result<void> teleportActor(glm::vec3 currentPosition, glm::vec4 currentRotation,
                                             glm::vec3 targetPosition, glm::vec4 targetRotation);
    [[nodiscard]] Result<VolumeFluidMassProperties> actorMassProperties(unsigned actorGroup) const;
    [[nodiscard]] Result<void> setActorFilterCategory(unsigned actorGroup, unsigned category);
    [[nodiscard]] Result<void> setActorCollisionFilter(unsigned actorGroup, unsigned collisionFilter);
    [[nodiscard]] Result<void> updateActorMaterial(unsigned actorGroup, const VolumeFluidParticle& prototype);
    [[nodiscard]] Result<void> setActorSelfCollisions(unsigned actorGroup, bool enabled);
    [[nodiscard]] Result<unsigned> killActorParticles(unsigned actorGroup);
    [[nodiscard]] Result<unsigned> actorParticleCount(unsigned actorGroup) const;
    [[nodiscard]] Result<void> killActorParticle(unsigned actorGroup, unsigned actorParticleIndex);
    [[nodiscard]] Result<void> applyParticleDrag(unsigned particleIndex, glm::vec3 targetPosition, float stiffness,
                                                 float damping, float seconds);
    [[nodiscard]] Result<unsigned> grabContactParticles(unsigned colliderLabel, glm::vec3 position, glm::vec4 rotation,
                                                        float distanceThreshold = .01f);
    [[nodiscard]] Result<unsigned> updateGrabbedParticles(unsigned colliderLabel, glm::vec3 position,
                                                          glm::vec4 rotation);
    [[nodiscard]] Result<unsigned> releaseGrabbedParticles(unsigned colliderLabel);
    [[nodiscard]] Result<std::vector<VolumeFluidFieldSample>> sampleField(std::span<const glm::vec3> positions) const;
    [[nodiscard]] Result<std::vector<VolumeFluidGridCell>> debugParticleGrid(unsigned maxCells = 65536) const;
    [[nodiscard]] Result<std::vector<VolumeFluidParticleFrame>> debugParticleFrames(
        unsigned actorGroup, float size = 1.f, unsigned maxParticles = 65536) const;
    [[nodiscard]] Result<std::vector<VolumeFluidParticleInstance>> particleInstances(
        unsigned actorGroup, glm::vec3 instanceScale = glm::vec3(1.f), float alpha = 1.f,
        unsigned maxInstances = 65536) const;
    [[nodiscard]] Result<std::vector<VolumeFluidParticleInstance>> particleImpostors(
        unsigned actorGroup, float radiusScale, glm::vec4 tint = glm::vec4(1.f), float alpha = 1.f,
        unsigned maxInstances = 65536) const;
    [[nodiscard]] Result<void> copyParticleImpostors(unsigned actorGroup, float radiusScale, glm::vec4 tint,
                                                     float alpha, unsigned maxInstances,
                                                     std::vector<VolumeFluidParticleInstance>& instances) const;
    [[nodiscard]] Result<VolumeFluidSdfSlice> debugSdfSlice(unsigned colliderLabel, VolumeFluidSdfSliceAxis axis,
                                                            float slice = .25f, float maxDistance = .5f,
                                                            unsigned maxSamples = 65536) const;
    [[nodiscard]] VolumeFluidSnapshot snapshot() const;
    [[nodiscard]] Result<void> restore(const VolumeFluidSnapshot& snapshot);
    void clear();
    [[nodiscard]] Result<void> killParticle(unsigned particleIndex);
 
private:
    friend class VolumeFluidFoam;
    friend class VolumeFluidDiffuse;
    struct Impl;
    [[nodiscard]] Result<unsigned> bindParticles(std::span<const unsigned> particleIndices, unsigned colliderLabel,
                                                 bool constrainOrientation, bool dynamic, float compliance,
                                                 float breakThreshold);
    [[nodiscard]] Result<void> accumulateForceZones(std::span<const VolumeFluidWindZone> zones, float fixedTimeSeconds,
                                                    bool asWind);
    [[nodiscard]] glm::vec3    interpolatedPositionUnchecked(size_t particleIndex, float alpha) const;
    [[nodiscard]] Result<void> sampleFieldInto(std::span<const glm::vec3>           positions,
                                               std::vector<VolumeFluidFieldSample>& samples) const;
    explicit VolumeFluid(const VolumeFluidSettings& settings);
    std::unique_ptr<Impl> impl_;
};
 
}  // namespace eve::fluids