eve::fluids::VolumeFluid类 参考

CPU position-based free-volume fluid with a bounded spatial grid. @ownership Owns all particle state; no external objects or callbacks are retained. @thread All methods are simulation-thread affine; concurrent access is forbidden. @reentrancy No callbacks are invoked. Renderers consume copied particle positions. 更多...

#include <VolumeFluid.h>

Public 成员函数
	~VolumeFluid ()
	VolumeFluid (const VolumeFluid &)=delete
VolumeFluid &	operator= (const VolumeFluid &)=delete
Result< void >	emit (std::span< const VolumeFluidParticle > particles)
	Atomically admits particles; rejects nonfinite, out-of-container or over-capacity input.
Result< void >	configureParticleEvents (unsigned capacity)
	Enables a bounded Fluid3DEmitter lifecycle-event queue or disables it with zero capacity.
VolumeFluidParticleEventBatch	drainParticleEvents ()
	Drains owning emission/removal snapshots and the overflow count.
Result< void >	step (float seconds, unsigned substeps=4)
	Advances by an injected duration in (0,1/30] seconds with 1..32 substeps.
Result< void >	setParticleWinds (std::span< const glm::vec3 > winds)
	Replaces one-step per-particle wind velocities used by atmospheric drag.
Result< void >	setParticleExternalForces (std::span< const glm::vec3 > forces)
	Replaces one-step world-space forces in newtons, one per current particle.
Result< void >	accumulateWindZones (std::span< const VolumeFluidWindZone > zones, float fixedTimeSeconds)
	Accumulates a bounded batch of Fluid3D-style force zones into pending wind.
Result< void >	accumulateExternalForceZones (std::span< const VolumeFluidWindZone > zones, float fixedTimeSeconds)
	Accumulates Fluid3D external-force zones into the pending one-step force array.
Result< void >	stepWithThermalContacts (float seconds, unsigned substeps, std::span< const VolumeFluidThermalRule > rules)
	Advances and applies bounded contact transfer to user channels, once per particle/rule.
Result< void >	stepWithColliders (float seconds, unsigned substeps, std::span< const VolumeFluidCollider > colliders, std::span< const VolumeFluidThermalRule > rules={})
	Atomically updates collider samples and advances; failed steps restore prior samples and particles.
std::vector< VolumeFluidParticle >	particles () const
	Returns an owning snapshot, independent of subsequent mutation or destruction.
std::span< const VolumeFluidParticle >	particleView () const
	Borrows the current dense particle pool without copying it.
size_t	particleCount () const
	Returns the live count without allocating or copying particle state.
size_t	availableCapacity () const
	Returns unused pool capacity in constant time without allocating.
float	spacing () const
	Returns the rest lattice spacing without copying state.
Result< void >	setGravity (glm::vec3 gravity)
	Replaces world-space gravity for subsequent fixed steps.
glm::vec3	gravity () const
	Returns current world-space gravity in constant time.
float	copyRenderData (std::vector< glm::vec3 > &positions, std::vector< glm::vec4 > &colors) const
	Copies positions/colors into caller-owned reusable buffers and returns rest spacing.
Result< void >	copyInterpolatedPositions (float alpha, std::vector< glm::vec3 > &positions) const
	Copies presentation positions interpolated between the last successful fixed-step endpoints.
Result< float >	copyInterpolatedRenderData (float alpha, std::vector< glm::vec3 > &positions, std::vector< glm::vec4 > &colors) const
	Fuses interpolated positions and colors into one allocation-reusing renderer pass.
float	copySurfaceRenderData (std::vector< glm::vec3 > &positions, std::vector< glm::vec4 > &colors, std::vector< glm::vec3 > &radii, std::vector< glm::vec4 > &orientations) const
	Copies position, color and oriented-ellipsoid shape data in one renderer-facing pass.
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
	Fuses interpolated positions, colors and ellipsoid shape into one renderer pass.
size_t	copyPhaseRenderData (VolumeFluidPhase phase, std::vector< glm::vec3 > &positions, std::vector< glm::vec4 > &colors, size_t maxParticles) const
	Copies a bounded prefix of one material phase for render-only consumers.
Result< void >	setColliders (std::span< const VolumeFluidCollider > colliders)
	Atomically replaces owned obstacle samples; rejects invalid geometry and duplicate labels.
Result< void >	setSdfColliders (std::span< const VolumeFluidSdfCollider > colliders)
	Atomically replaces at most 16 owned mesh/SDF colliders; total samples are bounded to 4M.
Result< void >	setHeightFieldColliders (std::span< const VolumeFluidHeightFieldCollider > colliders)
	Atomically replaces owned Fluid3D-compatible regular height-field colliders.
Result< unsigned >	bindStaticParticles (std::span< const unsigned > particleIndices, unsigned colliderLabel, bool constrainOrientation=false)
	Binds a particle group to an existing analytic collider in its current local frame.
Result< unsigned >	bindDynamicParticles (std::span< const unsigned > particleIndices, unsigned colliderLabel, float compliance, float breakThreshold, bool constrainOrientation=false)
	Installs Fluid3D-style compliant dynamic pins for a particle group.
Result< unsigned >	unbindStaticParticles (std::span< const unsigned > particleIndices)
	Removes anchors for the supplied unique current indices, returning the number removed atomically.
Result< void >	setStitches (std::span< const VolumeFluidStitch > stitches)
	Atomically replaces Fluid3DStitcher-compatible zero-distance constraints.
Result< void >	updateSdfColliderPoses (std::span< const VolumeFluidSdfPose > poses)
	Atomically updates transforms of existing owned SDF colliders without copying distance samples.
std::vector< VolumeFluidContact >	contacts () const
	Returns owning events from the last completed step; no borrowed world pointers are stored.
std::span< const VolumeFluidAttachmentReaction >	attachmentReactions () const
	Borrows attachment-constraint reactions from the last completed step.
Result< std::vector< VolumeFluidParticle > >	overlap (glm::vec3 center, float radius) const
	Queries a sphere, returning particle values; invalid query input returns a diagnostic.
Result< std::vector< VolumeFluidParticle > >	overlapBox (glm::vec3 center, glm::vec3 halfExtent, glm::vec4 rotation) const
	Queries particle centers inside an oriented box, including its boundary.
Result< std::vector< VolumeFluidRayHit > >	raycast (glm::vec3 origin, glm::vec3 direction, float maxDistance, unsigned maxHits=64, unsigned phaseMask=0x0f) const
	Raycasts native oriented-ellipsoid particles and returns nearest hits first.
Result< std::vector< VolumeFluidDistanceHit > >	querySphere (glm::vec3 center, float radius, float contactOffset, float maxDistance, unsigned maxHits=64, unsigned phaseMask=0x0f, unsigned collisionFilter=0xffffffffu) const
	Returns nearest signed distances between a sphere and particle surfaces.
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
	Returns nearest signed distances between an oriented box and particle surfaces.
Result< std::vector< VolumeFluidQueryHit > >	queryBatch (std::span< const VolumeFluidQueryShape > queries, unsigned maxHitsPerQuery=64) const
	Evaluates a bounded mixed batch of sphere, box and ray queries.
Result< std::vector< unsigned > >	applyQueryColors (std::span< const VolumeFluidQueryShape > queries, std::span< const glm::vec4 > overlapColors, glm::vec4 baseColor, unsigned maxHitsPerQuery=4096)
	Applies an Fluid3D OverlapTest-style base color and per-query overlap colors atomically.
Result< std::vector< unsigned > >	applyQueryColorsPreservingOutside (std::span< const VolumeFluidQueryShape > queries, std::span< const glm::vec4 > overlapColors, unsigned maxHitsPerQuery=4096)
	Applies per-query colors to overlapping particles while preserving all other colors.
Result< std::vector< VolumeFluidSimplexHit > >	querySimplexes (std::span< const VolumeFluidQueryShape > queries, unsigned maxHitsPerQuery=64) const
	Queries point/edge/triangle simplexes and returns Fluid3D-compatible barycentric results.
Result< void >	setSimplexes (std::span< const VolumeFluidSimplex > simplexes)
	Atomically replaces point/edge/triangle topology over current particle indices.
Result< void >	paint (glm::vec3 center, float radius, const VolumeFluidMaterial &material)
	Atomically changes the material of particles in a sphere (supports melting/solidifying).
Result< void >	applyMaterialChannels (std::span< const VolumeFluidViscosityColorKey > colorKeys={})
	Atomically maps user data x/y to material viscosity/cohesion for all particles.
Result< void >	applySolidColor (glm::vec4 color)
	Assigns a linear RGBA color to all current solid particles in place.
Result< void >	applyVelocityColors (float sensibility)
	Applies Fluid3D ColorFromVelocity RGB mapping to all particles in place.
Result< void >	applyActorGroupColors ()
	Applies Fluid3D's 26-color alphabet by actorGroup modulo 26.
Result< void >	applyDataColors (unsigned channel, std::span< const VolumeFluidColorKey > gradient)
	Colors particles by one normalized application-data channel.
Result< void >	applyRandomColors (std::span< const VolumeFluidColorKey > gradient, uint32_t seed)
	Applies a deterministic Fluid3D ColorRandomizer-style gradient sample to every particle.
Result< void >	addRandomVelocity (float intensity, uint32_t seed)
	Applies one deterministic random velocity impulse to the whole actor.
Result< void >	teleportActor (glm::vec3 currentPosition, glm::vec4 currentRotation, glm::vec3 targetPosition, glm::vec4 targetRotation)
	Teleports the whole fluid actor between explicit world poses.
Result< VolumeFluidMassProperties >	actorMassProperties (unsigned actorGroup) const
	Computes mass and world-space center for one actor group.
Result< void >	setActorFilterCategory (unsigned actorGroup, unsigned category)
	Applies Fluid3D SetFilterCategory to all particles in one actor group.
Result< void >	setActorCollisionFilter (unsigned actorGroup, unsigned collisionFilter)
	Applies Fluid3DEmitter.Filter to every live particle in one actor group.
Result< void >	updateActorMaterial (unsigned actorGroup, const VolumeFluidParticle &prototype)
	Applies Fluid3DEmitter::UpdateParticleMaterial to one live actor group.
Result< void >	setActorSelfCollisions (unsigned actorGroup, bool enabled)
	Applies Fluid3DEmitter::SetSelfCollisions to all live particles in one actor group.
Result< unsigned >	killActorParticles (unsigned actorGroup)
	Implements Fluid3DEmitter::KillAll for one actor in a shared solver.
Result< unsigned >	actorParticleCount (unsigned actorGroup) const
	Counts current live particles for one Fluid3D-compatible actor group.
Result< void >	killActorParticle (unsigned actorGroup, unsigned actorParticleIndex)
	Removes one particle by its actor-local active index, matching Fluid3DEmitter::KillParticle.
Result< void >	applyParticleDrag (unsigned particleIndex, glm::vec3 targetPosition, float stiffness, float damping, float seconds)
	Applies one fixed-step Fluid3DParticleDragger spring response.
Result< unsigned >	grabContactParticles (unsigned colliderLabel, glm::vec3 position, glm::vec4 rotation, float distanceThreshold=.01f)
	Freezes current contacts for one Fluid3DContactGrabber-compatible collider.
Result< unsigned >	updateGrabbedParticles (unsigned colliderLabel, glm::vec3 position, glm::vec4 rotation)
	Moves all particles owned by one contact grabber to a new world pose.
Result< unsigned >	releaseGrabbedParticles (unsigned colliderLabel)
	Releases one grabber label and restores normal particle dynamics.
Result< std::vector< VolumeFluidFieldSample > >	sampleField (std::span< const glm::vec3 > positions) const
	Samples the current liquid/gas field at up to 65536 finite world positions.
Result< std::vector< VolumeFluidGridCell > >	debugParticleGrid (unsigned maxCells=65536) const
	Returns occupied particle-grid cells for explicit debug visualization.
Result< std::vector< VolumeFluidParticleFrame > >	debugParticleFrames (unsigned actorGroup, float size=1.f, unsigned maxParticles=65536) const
	Returns particle-local XYZ rays for one actor group.
Result< std::vector< VolumeFluidParticleInstance > >	particleInstances (unsigned actorGroup, glm::vec3 instanceScale=glm::vec3(1.f), float alpha=1.f, unsigned maxInstances=65536) const
	Copies one actor group's interpolated mesh instances for batched particle rendering.
Result< std::vector< VolumeFluidParticleInstance > >	particleImpostors (unsigned actorGroup, float radiusScale, glm::vec4 tint=glm::vec4(1.f), float alpha=1.f, unsigned maxInstances=65536) const
	Copies one actor group's Fluid3DParticleRenderer-style anisotropic impostor instances.
Result< void >	copyParticleImpostors (unsigned actorGroup, float radiusScale, glm::vec4 tint, float alpha, unsigned maxInstances, std::vector< VolumeFluidParticleInstance > &instances) const
	Writes Fluid3DParticleRenderer-style instances into caller-owned reusable storage.
Result< VolumeFluidSdfSlice >	debugSdfSlice (unsigned colliderLabel, VolumeFluidSdfSliceAxis axis, float slice=.25f, float maxDistance=.5f, unsigned maxSamples=65536) const
	Samples one owned SDF collider slice for Fluid3DDistanceFieldRenderer-style diagnostics.
VolumeFluidSnapshot	snapshot () const
	Returns complete owning state; scratch grids and last-step contacts are derived and omitted.
Result< void >	restore (const VolumeFluidSnapshot &snapshot)
	Validates a complete candidate before replacing state; failures preserve the current solver.
void	clear ()
	Removes all live particles; settings remain unchanged.
Result< void >	killParticle (unsigned particleIndex)
	Removes one live particle and returns its slot to the bounded pool.

静态 Public 成员函数
static Result< std::unique_ptr< VolumeFluid > >	create (const VolumeFluidSettings &settings)
	Validates settings before allocating an owning solver; errors publish no state.

友元
class	VolumeFluidFoam
class	VolumeFluidDiffuse

详细描述

CPU position-based free-volume fluid with a bounded spatial grid. @ownership Owns all particle state; no external objects or callbacks are retained. @thread All methods are simulation-thread affine; concurrent access is forbidden. @reentrancy No callbacks are invoked. Renderers consume copied particle positions.

Fixed input ordering and timesteps are repeatable on the same build; cross-platform float results are tolerance-bounded, not bit-exact. No RNG is used. Liquid/gas sampling uses a half-spacing separation regularizer to resolve coincident zero-gradient particles; granular contacts use full spacing.

在文件 VolumeFluid.h 第 517 行定义.

构造及析构函数说明

~VolumeFluid()

eve::fluids::VolumeFluid::~VolumeFluid ( )

default

VolumeFluid()

eve::fluids::VolumeFluid::VolumeFluid ( const VolumeFluid &  )

delete

成员函数说明

accumulateExternalForceZones()

Result< void > eve::fluids::VolumeFluid::accumulateExternalForceZones	(	std::span< const VolumeFluidWindZone >	zones,
		float	fixedTimeSeconds
	)

Accumulates Fluid3D external-force zones into the pending one-step force array.

Geometry, turbulence and work budgets match accumulateWindZones(), while values are interpreted as newtons and converted by each particle's inverse rest mass during step.

在文件 VolumeFluid.cpp 第 112 行定义.

accumulateWindZones()

Result< void > eve::fluids::VolumeFluid::accumulateWindZones	(	std::span< const VolumeFluidWindZone >	zones,
		float	fixedTimeSeconds
	)

Accumulates a bounded batch of Fluid3D-style force zones into pending wind.

参数

zones	Borrowed ambient/spherical zones; at most 64, validated before mutation.
fixedTimeSeconds	Injected non-negative fixed simulation time for turbulence.

Simulation-thread only. Ambient forces are precombined and spherical zones share one particle traversal, capped at four million particle-zone candidates. Turbulence multiplies deterministic coherent noise in [0,1]. Results add to pending setParticleWinds values, survive failure, and clear after a successful step. Empty input is a no-op. No zone or callback is retained and snapshots omit the result.

在文件 VolumeFluid.cpp 第 108 行定义.

actorMassProperties()

Result< VolumeFluidMassProperties > eve::fluids::VolumeFluid::actorMassProperties

(

unsigned

actorGroup

)

const

Computes mass and world-space center for one actor group.

参数

actorGroup

Fluid3D-compatible actor group in [0, 0x00ffffff].

返回

Owning summary, or NotFound when the group has no live particles.

This is the data used by the package ActorCOMTransform helper. It is an explicit allocation-free O(particle count) query and does not run during fixed stepping or rendering. Particle rest mass is spacing cubed times density.

在文件 VolumeFluidTools.cpp 第 210 行定义.

引用了 count, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::InvalidArgument, eve::fluids::VolumeFluidMassProperties::mass, eve::NotFound, properties , 以及 eve::Result< T >::success().

actorParticleCount()

Result< unsigned > eve::fluids::VolumeFluid::actorParticleCount

(

unsigned

actorGroup

)

const

Counts current live particles for one Fluid3D-compatible actor group.

参数

actorGroup

Stable actor group in [0,0x00ffffff].

返回

Live count, including zero when the actor currently has no particles.

Simulation-thread only. Performs one allocation-free read-only scan and does not compute mass properties, invoke callbacks or perform GPU work.

在文件 VolumeFluid.cpp 第 853 行定义.

被这些函数引用 eve::fluids::VolumeFluidEmitter::advance(), eve::fluids::VolumeFluidEmitter::advanceBurst(), eve::fluids::VolumeFluidJetEmitter::advanceMoving(), eve::fluids::VolumeFluidEmitter::emitParticle() , 以及 eve::fluids::emitVolumeFluidBurst().

addRandomVelocity()

Result< void > eve::fluids::VolumeFluid::addRandomVelocity	(	float	intensity,
		uint32_t	seed
	)

Applies one deterministic random velocity impulse to the whole actor.

参数

intensity	Velocity-change magnitude in [0,100] metres per second.
seed	Named deterministic random stream seed; no global RNG is touched.

Matches the package AddRandomVelocity behavior: all particles receive the same unit-sphere direction times intensity. Validation and the resulting 100 m/s particle-speed bound are checked before mutation. Linear-time, allocation-free, simulation-thread affine; no callbacks or GPU work.

在文件 VolumeFluidTools.cpp 第 164 行定义.

引用了 phi, range, seed, eve::Result< T >::success() , 以及 z.

applyActorGroupColors()

Result< void > eve::fluids::VolumeFluid::applyActorGroupColors

(

)

Applies Fluid3D's 26-color alphabet by actorGroup modulo 26.

Explicit linear-time, allocation-free and simulation-thread affine. Only owned particle colors change; no callbacks, GPU work or retained binding.

在文件 VolumeFluidTools.cpp 第 90 行定义.

引用了 eve::Result< T >::success().

applyDataColors()

Result< void > eve::fluids::VolumeFluid::applyDataColors	(	unsigned	channel,
		std::span< const VolumeFluidColorKey >	gradient
	)

Colors particles by one normalized application-data channel.

参数

channel	data component index in [0,3].
gradient	Borrowed 2..32 key gradient with strictly increasing [0,1] coordinates.

Values clamp to endpoint colors. Validation completes before the allocation-free linear-time mutation. Simulation-thread affine; no callbacks or GPU work.

在文件 VolumeFluidTools.cpp 第 152 行定义.

引用了 eve::Result< T >::success().

applyMaterialChannels()

Result< void > eve::fluids::VolumeFluid::applyMaterialChannels

(

std::span< const VolumeFluidViscosityColorKey >

colorKeys = {}

)

Atomically maps user data x/y to material viscosity/cohesion for all particles.

返回

Failure without mutation if any x is outside [0,100] or y outside [0,10].

Explicit simulation-thread operation; data remains unchanged. Retains no references, invokes no callbacks, and does not create an automatic binding. Optional 2..32 strictly ordered color keys are borrowed for this call only. Empty keys preserve colors. Otherwise colors use the pre-update viscosity, linearly interpolate RGBA and clamp outside the key range, then channels update material parameters. This matches the reference sample's update order. Invalid keys or channels leave all particles unchanged. No allocation, retained bindings, callbacks or simulation-time advancement occurs.

在文件 VolumeFluidTools.cpp 第 37 行定义.

引用了 key, previous, range, eve::Result< T >::success(), t , 以及 value.

applyParticleDrag()

Result< void > eve::fluids::VolumeFluid::applyParticleDrag	(	unsigned	particleIndex,
		glm::vec3	targetPosition,
		float	stiffness,
		float	damping,
		float	seconds
	)

Applies one fixed-step Fluid3DParticleDragger spring response.

参数

particleIndex	Current dense particle index, usually selected by raycast().
targetPosition	Finite world-space drag target.
stiffness	Spring acceleration coefficient in [0,10000].
damping	Velocity damping coefficient in [0,10000].
seconds	Injected fixed-step duration in (0,1/30].

Updates one velocity using semi-implicit spring acceleration. The operation is allocation-free O(1), invokes no callback, performs no GPU work, and fails before mutation if the resulting speed would exceed 1000 m/s.

在文件 VolumeFluidTools.cpp 第 295 行定义.

引用了 finite, range , 以及 eve::Result< T >::success().

applyQueryColors()

Result< std::vector< unsigned > > eve::fluids::VolumeFluid::applyQueryColors	(	std::span< const VolumeFluidQueryShape >	queries,
		std::span< const glm::vec4 >	overlapColors,
		glm::vec4	baseColor,
		unsigned	maxHitsPerQuery = 4096
	)

Applies an Fluid3D OverlapTest-style base color and per-query overlap colors atomically.

参数

queries	Borrowed sphere, box or ray descriptions in priority order; at most 256.
overlapColors	One finite linear RGBA color per query. Later queries win on overlap.
baseColor	Finite linear RGBA assigned to particles outside every retained overlap.
maxHitsPerQuery	Per-query overlap/result bound in [1,4096].

返回

Owning overlap counts in query order, or failure without changing any particle color.

Only hits with negative signed distance are triggers. Query validation, reciprocal filtering and the four-million candidate budget are shared with queryBatch. Returned particle copies are discarded before mutation. Simulation-thread affine; no callbacks or GPU work.

在文件 VolumeFluidColliders.cpp 第 579 行定义.

引用了 color, counts, eve::Diagnostic::error(), hit, eve::InvalidArgument , 以及 range.

applyQueryColorsPreservingOutside()

Result< std::vector< unsigned > > eve::fluids::VolumeFluid::applyQueryColorsPreservingOutside	(	std::span< const VolumeFluidQueryShape >	queries,
		std::span< const glm::vec4 >	overlapColors,
		unsigned	maxHitsPerQuery = 4096
	)

Applies per-query colors to overlapping particles while preserving all other colors.

参数

queries	Borrowed sphere, box or ray descriptions in priority order; at most 256.
overlapColors	One finite linear RGBA color per query. Later queries win on overlap.
maxHitsPerQuery	Per-query overlap/result bound in [1,4096].

返回

Owning overlap counts in query order, or failure without changing any particle color.

This is the persistent-color variant used by contact/trigger colorizers. It shares queryBatch validation and budgets, mutates only negative-distance hits after the full query succeeds, retains no references, invokes no callbacks and performs no GPU work.

在文件 VolumeFluidColliders.cpp 第 604 行定义.

引用了 color, counts, eve::Diagnostic::error(), hit, eve::InvalidArgument , 以及 range.

applyRandomColors()

Result< void > eve::fluids::VolumeFluid::applyRandomColors	(	std::span< const VolumeFluidColorKey >	gradient,
		uint32_t	seed
	)

Applies a deterministic Fluid3D ColorRandomizer-style gradient sample to every particle.

参数

gradient	Borrowed validated 2..32 key gradient.
seed	Named deterministic random stream seed.

Explicit allocation-free linear-time mutation; no global RNG or retained state.

在文件 VolumeFluidTools.cpp 第 158 行定义.

引用了 seed , 以及 eve::Result< T >::success().

applySolidColor()

Result< void > eve::fluids::VolumeFluid::applySolidColor

(

glm::vec4

color

)

Assigns a linear RGBA color to all current solid particles in place.

参数

color

Finite components in [0,1]; invalid input fails before mutation.

Explicit simulation-thread operation, O(particle count), no allocation or callbacks. Includes attached and world-fixed solids; other phases and all non-color state are unchanged. No style binding is retained. Call after a step to color newly frozen particles; melting does not restore a previous color. The resulting colors are owned by particles and included in existing snapshots.

在文件 VolumeFluidTools.cpp 第 72 行定义.

引用了 color, range, eve::fluids::Solid , 以及 eve::Result< T >::success().

applyVelocityColors()

Result< void > eve::fluids::VolumeFluid::applyVelocityColors

(

float

sensibility

)

Applies Fluid3D ColorFromVelocity RGB mapping to all particles in place.

参数

sensibility

Positive velocity component magnitude mapped to either color extreme.

Each RGB channel is clamp(velocity/sensibility,-1,1)*0.5+0.5; alpha becomes one. Explicit linear-time, allocation-free, simulation-thread affine. Invalid sensitivity fails before mutation; no callbacks, GPU work or retained binding.

在文件 VolumeFluidTools.cpp 第 81 行定义.

引用了 range , 以及 eve::Result< T >::success().

attachmentReactions()

std::span< const VolumeFluidAttachmentReaction > eve::fluids::VolumeFluid::attachmentReactions

(

)

const

Borrows attachment-constraint reactions from the last completed step.

Simulation-thread only. The span is invalidated by the next mutating solver call or solver destruction. Reactions include prescribed linear inertia and the attached particle's gravity load, ellipsoid angular inertia, and neighbor pressure, cohesion and viscosity transfer; contact impulses remain available separately through contacts().

在文件 VolumeFluidColliders.cpp 第 293 行定义.

被这些函数引用 eve::fluids::VolumeFluidCoupling::step().

availableCapacity()

size_t eve::fluids::VolumeFluid::availableCapacity

(

)

const

Returns unused pool capacity in constant time without allocating.

在文件 VolumeFluid.cpp 第 641 行定义.

被这些函数引用 eve::fluids::VolumeFluidEmitter::advance(), eve::fluids::VolumeFluidEmitter::advanceBurst(), eve::fluids::VolumeFluidJetEmitter::advanceMoving() , 以及 eve::fluids::VolumeFluidEmitter::emitParticle().

bindDynamicParticles()

Result< unsigned > eve::fluids::VolumeFluid::bindDynamicParticles	(	std::span< const unsigned >	particleIndices,
		unsigned	colliderLabel,
		float	compliance,
		float	breakThreshold,
		bool	constrainOrientation = false
	)

Installs Fluid3D-style compliant dynamic pins for a particle group.

参数

compliance	Finite compliance in [0,1000000]; zero creates a rigid dynamic pin.
breakThreshold	Finite force threshold in (0,1e12] newtons.

Dynamic particles retain mass and participate in the solver. Constraint work is linear in anchor count and reactions are reported through attachmentReactions().

在文件 VolumeFluidColliders.cpp 第 53 行定义.

bindStaticParticles()

Result< unsigned > eve::fluids::VolumeFluid::bindStaticParticles	(	std::span< const unsigned >	particleIndices,
		unsigned	colliderLabel,
		bool	constrainOrientation = false
	)

Binds a particle group to an existing analytic collider in its current local frame.

参数

particleIndices	Borrowed current pool indices; copied into sparse owned anchors.
colliderLabel	Existing analytic collider label used as the attachment target.
constrainOrientation	Also drive particle orientation from the target rotation.

返回

Number of installed anchors, or failure before any mutation.

Simulation-thread only. Indices must be unique and currently unattached. The target position is enforced without changing particle phase or material. No callback or external pointer is retained; removal of the collider detaches the group.

在文件 VolumeFluidColliders.cpp 第 48 行定义.

clear()

void eve::fluids::VolumeFluid::clear

(

)

Removes all live particles; settings remain unchanged.

在文件 VolumeFluid.cpp 第 732 行定义.

configureParticleEvents()

Result< void > eve::fluids::VolumeFluid::configureParticleEvents

(

unsigned

capacity

)

Enables a bounded Fluid3DEmitter lifecycle-event queue or disables it with zero capacity.

参数

capacity

Maximum pending events in [0,65536].

Simulation-thread only. Configuration clears pending events and the overflow counter, and reserves storage before publishing the new capacity. Disabled emission/removal adds no allocations, callbacks, locks or GPU work.

在文件 VolumeFluid.cpp 第 59 行定义.

引用了 capacity.

contacts()

std::vector< VolumeFluidContact > eve::fluids::VolumeFluid::contacts

(

)

const

Returns owning events from the last completed step; no borrowed world pointers are stored.

在文件 VolumeFluidColliders.cpp 第 291 行定义.

被这些函数引用 eve::fluids::exposeVolumeFluidType() , 以及 eve::fluids::VolumeFluidCoupling::step().

copyInterpolatedPositions()

Result< void > eve::fluids::VolumeFluid::copyInterpolatedPositions	(	float	alpha,
		std::vector< glm::vec3 > &	positions
	)		const

Copies presentation positions interpolated between the last successful fixed-step endpoints.

参数

alpha	Finite fraction in [0,1]; zero selects the step start and one the current state.
positions	Destination resized to the live count while retaining existing capacity.

返回

Success, or invalid argument without changing the destination.

Previous positions are transient derived state. Emission and restore initialize them, removal compacts them with particles, teleport resets them, and a failed step preserves them. Simulation-thread affine; no callbacks or GPU work.

在文件 VolumeFluid.cpp 第 649 行定义.

引用了 positions.

copyInterpolatedRenderData()

Result< float > eve::fluids::VolumeFluid::copyInterpolatedRenderData	(	float	alpha,
		std::vector< glm::vec3 > &	positions,
		std::vector< glm::vec4 > &	colors
	)		const

Fuses interpolated positions and colors into one allocation-reusing renderer pass.

在文件 VolumeFluid.cpp 第 655 行定义.

引用了 colors, positions , 以及 status.

copyInterpolatedSurfaceRenderData()

Result< float > eve::fluids::VolumeFluid::copyInterpolatedSurfaceRenderData	(	float	alpha,
		std::vector< glm::vec3 > &	positions,
		std::vector< glm::vec4 > &	colors,
		std::vector< glm::vec3 > &	radii,
		std::vector< glm::vec4 > &	orientations
	)		const

Fuses interpolated positions, colors and ellipsoid shape into one renderer pass.

参数

alpha

Finite fixed-step interpolation fraction in [0,1].

返回

Solver spacing, or invalid argument before changing any destination.

All outputs retain capacity; no state, callback or GPU work is involved.

在文件 VolumeFluid.cpp 第 695 行定义.

引用了 colors, count, positions, radii , 以及 status.

copyParticleImpostors()

Result< void > eve::fluids::VolumeFluid::copyParticleImpostors	(	unsigned	actorGroup,
		float	radiusScale,
		glm::vec4	tint,
		float	alpha,
		unsigned	maxInstances,
		std::vector< VolumeFluidParticleInstance > &	instances
	)		const

Writes Fluid3DParticleRenderer-style instances into caller-owned reusable storage.

参数

actorGroup	Fluid3D-compatible actor group in [0,0x00ffffff].
radiusScale	Positive finite scalar applied to every principal particle radius.
tint	Finite linear RGBA multiplier in [0,1].
alpha	Finite fixed-step position interpolation fraction in [0,1].
maxInstances	Positive complete-output budget capped at one million.
instances	Destination replaced only after validation and complete-size budgeting.

返回

Success, or failure leaving instances unchanged.

Existing destination capacity is retained, so a warmed render loop performs no allocation. Simulation-thread affine; the solver and destination are borrowed for this call only.

在文件 VolumeFluidTools.cpp 第 557 行定义.

引用了 code, count, eve::Diagnostic::error(), eve::Result< T >::failure(), finite, index, instances, eve::InvalidArgument, message, eve::NotFound, range, eve::Result< T >::success() , 以及 tint.

被这些函数引用 particleImpostors() , 以及 eve::fluids::VolumeFluidShadowCaster::update().

copyPhaseRenderData()

size_t eve::fluids::VolumeFluid::copyPhaseRenderData	(	VolumeFluidPhase	phase,
		std::vector< glm::vec3 > &	positions,
		std::vector< glm::vec4 > &	colors,
		size_t	maxParticles
	)		const

Copies a bounded prefix of one material phase for render-only consumers.

参数

phase	Material phase to select.
positions	Replaced with up to maxParticles selected positions.
colors	Replaced with the corresponding particle colors.
maxParticles	Maximum number of particles copied.

返回

Total selected particle count, including particles beyond maxParticles.

Read-only and simulation-thread affine. Output vectors are owned by the caller.

在文件 VolumeFluid.cpp 第 715 行定义.

引用了 colors, phase , 以及 positions.

copyRenderData()

float eve::fluids::VolumeFluid::copyRenderData	(	std::vector< glm::vec3 > &	positions,
		std::vector< glm::vec4 > &	colors
	)		const

Copies positions/colors into caller-owned reusable buffers and returns rest spacing.

Simulation-thread only; retains no references to either output buffer.

在文件 VolumeFluid.cpp 第 670 行定义.

引用了 colors , 以及 positions.

copySurfaceRenderData()

float eve::fluids::VolumeFluid::copySurfaceRenderData	(	std::vector< glm::vec3 > &	positions,
		std::vector< glm::vec4 > &	colors,
		std::vector< glm::vec3 > &	radii,
		std::vector< glm::vec4 > &	orientations
	)		const

Copies position, color and oriented-ellipsoid shape data in one renderer-facing pass.

参数

positions	Owning destination resized to the current particle count.
colors	Owning destination resized to the current particle count.
radii	Principal world-space ellipsoid radii, parallel to positions.
orientations	Unit particle orientations in XYZW order, parallel to positions.

返回

Solver spacing in metres.

Read-only and allocation-reusing: existing destination capacity is retained. The four arrays are a coherent snapshot from this call and no simulator pointer is retained. Render-thread affinity is inherited from the caller; do not race this method with step/emit.

在文件 VolumeFluid.cpp 第 679 行定义.

引用了 colors, count, positions , 以及 radii.

create()

Result< std::unique_ptr< VolumeFluid > > eve::fluids::VolumeFluid::create ( const VolumeFluidSettings &  settings )

static

Validates settings before allocating an owning solver; errors publish no state.

在文件 VolumeFluid.cpp 第 7 行定义.

引用了 cells, finite, s , 以及 valid.

被这些函数引用 eve::fluids::VolumeFluidCoupling::attach(), eve::fluids::decodeVolumeFluid(), eve::fluids::exposeVolumeFluidFactory() , 以及 restore().

debugParticleFrames()

Result< std::vector< VolumeFluidParticleFrame > > eve::fluids::VolumeFluid::debugParticleFrames	(	unsigned	actorGroup,
		float	size = 1.f,
		unsigned	maxParticles = 65536
	)		const

Returns particle-local XYZ rays for one actor group.

参数

actorGroup	Fluid3D-compatible actor group in [0,0x00ffffff].
size	Finite ray length in (0,100] world units.
maxParticles	Positive result budget capped at one million.

Explicit simulation-thread query. It scans current particles once, allocates only the bounded owning result and performs no fixed-step, GPU, upload or rendering work.

在文件 VolumeFluidTools.cpp 第 495 行定义.

引用了 code, count, eve::Diagnostic::error(), eve::InvalidArgument, message, eve::NotFound, p, range, rotation , 以及 size.

debugParticleGrid()

Result< std::vector< VolumeFluidGridCell > > eve::fluids::VolumeFluid::debugParticleGrid

(

unsigned

maxCells = 65536

)

const

Returns occupied particle-grid cells for explicit debug visualization.

参数

maxCells

Maximum complete result size in [1,1000000].

返回

Owning cells in stable linear-grid order, or failure without partial output.

The query sorts one capacity-reserved index per live particle and does not scan empty grid cells. It runs only when called and adds no work, allocation, renderer state or GPU operation to normal simulation frames.

在文件 VolumeFluidTools.cpp 第 459 行定义.

引用了 cell, cells, center, end, eve::Diagnostic::error(), indices, eve::InvalidArgument, occupied, x, y , 以及 z.

debugSdfSlice()

Result< VolumeFluidSdfSlice > eve::fluids::VolumeFluid::debugSdfSlice	(	unsigned	colliderLabel,
		VolumeFluidSdfSliceAxis	axis,
		float	slice = .25f,
		float	maxDistance = .5f,
		unsigned	maxSamples = 65536
	)		const

Samples one owned SDF collider slice for Fluid3DDistanceFieldRenderer-style diagnostics.

参数

colliderLabel	Stable SDF collider label.
axis	Local slice-normal axis.
slice	Finite normalized location in [0,1] across the selected local axis.
maxDistance	Positive symmetric distance range mapped to [0,1].
maxSamples	Positive complete-output budget capped at one million.

返回

Owning row-major values and a world-space sample lattice, or failure without partial output.

Explicit simulation-thread query. It allocates and samples only when called and adds no fixed-step traversal, callback, GPU dispatch, upload or surface reconstruction work.

在文件 VolumeFluidTools.cpp 第 583 行定义.

引用了 code, eve::Diagnostic::error(), eve::Result< T >::failure(), found, height, eve::InvalidArgument, local, message, eve::NotFound, output, range, rotation, eve::Result< T >::success(), width, eve::fluids::VolumeFluidSdfSlice::width, x, eve::fluids::X, y , 以及 eve::fluids::Y.

drainParticleEvents()

VolumeFluidParticleEventBatch eve::fluids::VolumeFluid::drainParticleEvents

(

)

Drains owning emission/removal snapshots and the overflow count.

Simulation-thread only. The explicit drain allocates its returned owning vector; the configured hot path retains its reservation and never invokes scripts.

在文件 VolumeFluid.cpp 第 69 行定义.

引用了 eve::fluids::VolumeFluidParticleEventBatch::dropped , 以及 eve::fluids::VolumeFluidParticleEventBatch::events.

emit()

Result< void > eve::fluids::VolumeFluid::emit

(

std::span< const VolumeFluidParticle >

particles

)

Atomically admits particles; rejects nonfinite, out-of-container or over-capacity input.

在文件 VolumeFluid.cpp 第 24 行定义.

引用了 finite, first, input, p , 以及 range.

被这些函数引用 eve::fluids::VolumeFluidJetEmitter::advanceMoving().

grabContactParticles()

Result< unsigned > eve::fluids::VolumeFluid::grabContactParticles	(	unsigned	colliderLabel,
		glm::vec3	position,
		glm::vec4	rotation,
		float	distanceThreshold = .01f
	)

Freezes current contacts for one Fluid3DContactGrabber-compatible collider.

参数

colliderLabel	Existing analytic, SDF or height-field collider label.
position	Current grabber world position.
rotation	Current unit grabber world rotation in XYZW order.
distanceThreshold	Maximum signed contact distance in [0,0.1] metres.

返回

Number of particles captured from the latest successful contact set.

Replaces the label's previous capture atomically. Captured particles retain local coordinates, contribute as zero-inverse-mass neighbors, and do not integrate until released. One particle may belong to only one grabber. Simulation-thread affine; bounded by current contacts and particle count.

在文件 VolumeFluidTools.cpp 第 308 行定义.

引用了 count, eve::Diagnostic::error(), eve::Result< T >::failure(), finite, eve::InvalidArgument, local, message, position, q, range, rotation, eve::fluids::Solid , 以及 eve::Result< T >::success().

gravity()

glm::vec3 eve::fluids::VolumeFluid::gravity

(

)

const

Returns current world-space gravity in constant time.

在文件 VolumeFluid.cpp 第 648 行定义.

killActorParticle()

Result< void > eve::fluids::VolumeFluid::killActorParticle	(	unsigned	actorGroup,
		unsigned	actorParticleIndex
	)

Removes one particle by its actor-local active index, matching Fluid3DEmitter::KillParticle.

Simulation-thread only. Performs one allocation-free dense scan, then uses the canonical atomic compaction/remapping path. Invalid groups or stale actor indices preserve state.

在文件 VolumeFluid.cpp 第 862 行定义.

killActorParticles()

Result< unsigned > eve::fluids::VolumeFluid::killActorParticles

(

unsigned

actorGroup

)

Implements Fluid3DEmitter::KillAll for one actor in a shared solver.

参数

actorGroup

Stable actor group in [0,0x00ffffff].

返回

Number of particles returned to the pool; NotFound if none are live.

Compacts particles once, remaps surviving attachments/stitches/simplexes, and clears derived contacts/reactions. Reuses solver index scratch, invokes no callbacks and performs no GPU work. Invalid or missing groups do not mutate state.

在文件 VolumeFluid.cpp 第 788 行定义.

引用了 removed.

killParticle()

Result< void > eve::fluids::VolumeFluid::killParticle

(

unsigned

particleIndex

)

Removes one live particle and returns its slot to the bounded pool.

参数

particleIndex

Current dense particle index.

返回

Success, or invalid argument without mutation when the index is stale.

Simulation-thread only. Later indices shift down by one; attachments and unaffected simplex indices are remapped, while simplexes containing the removed particle are dropped. Pending per-particle winds remain aligned. Last-step contacts and attachment reactions are invalidated. No callbacks.

在文件 VolumeFluid.cpp 第 753 行定义.

operator=()

VolumeFluid & eve::fluids::VolumeFluid::operator= ( const VolumeFluid &  )

delete

overlap()

Result< std::vector< VolumeFluidParticle > > eve::fluids::VolumeFluid::overlap	(	glm::vec3	center,
		float	radius
	)		const

Queries a sphere, returning particle values; invalid query input returns a diagnostic.

在文件 VolumeFluidColliders.cpp 第 297 行定义.

引用了 center, eve::Diagnostic::error(), finite, eve::InvalidArgument, p, radius , 以及 range.

overlapBox()

Result< std::vector< VolumeFluidParticle > > eve::fluids::VolumeFluid::overlapBox	(	glm::vec3	center,
		glm::vec3	halfExtent,
		glm::vec4	rotation
	)		const

Queries particle centers inside an oriented box, including its boundary.

参数

center	World-space center in meters.
halfExtent	Nonnegative half sizes, each at most 10000 meters.
rotation	Unit quaternion in XYZW order; norm-squared tolerance is 0.001.

返回

Owning particle values in pool order, or an invalid-argument diagnostic.

Simulation-thread only; O(particle count), no retained references or callbacks.

在文件 VolumeFluidColliders.cpp 第 307 行定义.

引用了 center, eve::Diagnostic::error(), finite, halfExtent, eve::InvalidArgument, local , 以及 rotation.

paint()

Result< void > eve::fluids::VolumeFluid::paint	(	glm::vec3	center,
		float	radius,
		const VolumeFluidMaterial &	material
	)

Atomically changes the material of particles in a sphere (supports melting/solidifying).

在文件 VolumeFluidTools.cpp 第 20 行定义.

引用了 a, center, finite, material, p, radius, range, eve::fluids::Solid , 以及 eve::Result< T >::success().

particleCount()

size_t eve::fluids::VolumeFluid::particleCount

(

)

const

Returns the live count without allocating or copying particle state.

在文件 VolumeFluid.cpp 第 640 行定义.

particleImpostors()

Result< std::vector< VolumeFluidParticleInstance > > eve::fluids::VolumeFluid::particleImpostors	(	unsigned	actorGroup,
		float	radiusScale,
		glm::vec4	tint = glm::vec4(1.f),
		float	alpha = 1.f,
		unsigned	maxInstances = 65536
	)		const

Copies one actor group's Fluid3DParticleRenderer-style anisotropic impostor instances.

参数

actorGroup	Fluid3D-compatible actor group in [0,0x00ffffff].
radiusScale	Positive finite scalar applied to every principal particle radius.
tint	Finite linear RGBA multiplier in [0,1], multiplied with each particle color.
alpha	Finite fixed-step position interpolation fraction in [0,1].
maxInstances	Positive complete-output budget capped at one million.

返回

Owning stable-order instance rows, or failure without partial output.

Explicit render-thread preparation. It preserves the solver's anisotropy and orientation, scans particles twice only when called, and emits one row per particle for caller-owned batched drawing. It does not expand particles into CPU quad vertices or submit GPU/render work.

在文件 VolumeFluidTools.cpp 第 548 行定义.

引用了 copyParticleImpostors(), instances , 以及 tint.

particleInstances()

Result< std::vector< VolumeFluidParticleInstance > > eve::fluids::VolumeFluid::particleInstances	(	unsigned	actorGroup,
		glm::vec3	instanceScale = glm::vec3(1.f),
		float	alpha = 1.f,
		unsigned	maxInstances = 65536
	)		const

Copies one actor group's interpolated mesh instances for batched particle rendering.

参数

actorGroup	Fluid3D-compatible actor group in [0,0x00ffffff].
instanceScale	Positive finite component-wise scale multiplier.
alpha	Finite fixed-step position interpolation fraction in [0,1].
maxInstances	Positive complete-output budget capped at one million.

返回

Owning stable-order instance rows, or failure without partial output.

Explicit render-thread preparation. It scans particles twice only when called, allocates one bounded output and performs no draw, GPU dispatch or texture upload.

在文件 VolumeFluidTools.cpp 第 520 行定义.

引用了 code, count, eve::Diagnostic::error(), finite, index, instances, eve::InvalidArgument, message, eve::NotFound , 以及 range.

particles()

std::vector< VolumeFluidParticle > eve::fluids::VolumeFluid::particles

(

)

const

Returns an owning snapshot, independent of subsequent mutation or destruction.

在文件 VolumeFluid.cpp 第 622 行定义.

被这些函数引用 restore().

particleView()

std::span< const VolumeFluidParticle > eve::fluids::VolumeFluid::particleView

(

)

const

Borrows the current dense particle pool without copying it.

返回

Read-only contiguous view in current pool order. @ownership The solver owns every element; callers must not retain the view. @lifetime Valid only until the next non-const solver call or solver destruction. @thread Simulation-thread only; no concurrent mutation or callbacks.

Constant-time and allocation-free. Intended for bounded native hot-path scans; scripting continues to receive owning snapshots.

在文件 VolumeFluid.cpp 第 623 行定义.

queryBatch()

Result< std::vector< VolumeFluidQueryHit > > eve::fluids::VolumeFluid::queryBatch	(	std::span< const VolumeFluidQueryShape >	queries,
		unsigned	maxHitsPerQuery = 64
	)		const

Evaluates a bounded mixed batch of sphere, box and ray queries.

参数

queries	Borrowed descriptions in result-group order; at most 256.
maxHitsPerQuery	Per-query nearest-hit bound in [1,4096].

返回

Owning hits grouped by query index, then distance and particle index.

Uses Fluid3D QueryShape meanings: sphere radius is size.x, box size is full local extent, and ray center/size are segment endpoints. The entire batch is validated before scanning. At most 65536 particles and four million query-particle candidate checks are accepted. Failure returns no partial output and does not mutate simulation state. Simulation-thread affine; invokes no callbacks and retains no references. Indices become stale after particle mutation. Particle hits use owned oriented ellipsoid radii.

在文件 VolumeFluidColliders.cpp 第 482 行定义.

引用了 a, b, eve::fluids::Box, direction, distance, eve::Diagnostic::error(), finite, hit, eve::InvalidArgument, message, normal, output, queryBox(), querySphere(), range, eve::fluids::Ray, eve::fluids::Sphere , 以及 eve::Result< T >::value().

queryBox()

Result< std::vector< VolumeFluidDistanceHit > > eve::fluids::VolumeFluid::queryBox	(	glm::vec3	center,
		glm::vec3	halfExtent,
		glm::vec4	rotation,
		float	contactOffset,
		float	maxDistance,
		unsigned	maxHits = 64,
		unsigned	phaseMask = 0x0f,
		unsigned	collisionFilter = 0xffffffffu
	)		const

Returns nearest signed distances between an oriented box and particle surfaces.

参数

center	World-space box center.
halfExtent	Finite nonnegative local half sizes, each at most 10000 meters.
rotation	Unit quaternion in XYZW order; norm-squared tolerance is 0.001.
contactOffset	Nonnegative outward expansion in [0,10000] meters.
maxDistance	Maximum positive separation in [0,10000]; overlaps always qualify.
maxHits	Output bound in [1,4096]; smallest signed distances are retained.
phaseMask	Bits 0..3 select Liquid, Gas, Granular and Solid; other bits fail.

Query points lie on the contact-offset-expanded box surface. Inside points choose the nearest face with deterministic X/Y/Z tie order. Particles use their oriented ellipsoid radius along the contact normal. At most 65536 live particles are accepted, bounding O(N log maxHits) work. Simulation-thread affine; owns outputs, invokes no callbacks, retains no references and does not mutate state.

在文件 VolumeFluidColliders.cpp 第 418 行定义.

引用了 a, b, center, distance, eve::Diagnostic::error(), finite, halfExtent, hit, eve::InvalidArgument, local, message, normal, phase, range , 以及 rotation.

被这些函数引用 queryBatch().

querySimplexes()

Result< std::vector< VolumeFluidSimplexHit > > eve::fluids::VolumeFluid::querySimplexes	(	std::span< const VolumeFluidQueryShape >	queries,
		unsigned	maxHitsPerQuery = 64
	)		const

Queries point/edge/triangle simplexes and returns Fluid3D-compatible barycentric results.

参数

queries	Borrowed query descriptions, at most 256.
maxHitsPerQuery	Per-query output bound in [1,4096].

Empty explicit topology means one point simplex per particle. Work is rejected above four million query-simplex candidates. Results own their values; indices become stale after particle or topology mutation. Simulation-thread affine; no callbacks.

在文件 VolumeFluidColliders.cpp 第 628 行定义.

querySphere()

Result< std::vector< VolumeFluidDistanceHit > > eve::fluids::VolumeFluid::querySphere	(	glm::vec3	center,
		float	radius,
		float	contactOffset,
		float	maxDistance,
		unsigned	maxHits = 64,
		unsigned	phaseMask = 0x0f,
		unsigned	collisionFilter = 0xffffffffu
	)		const

Returns nearest signed distances between a sphere and particle surfaces.

参数

center	Finite world-space query center.
radius	Query radius in [0,10000] meters.
contactOffset	Nonnegative expansion in [0,10000] meters.
maxDistance	Maximum positive separation in [0,10000]; overlaps always qualify.
maxHits	Output bound in [1,4096]; smallest signed distances are retained.
phaseMask	Bits 0..3 select Liquid, Gas, Granular and Solid; other bits fail.

Particles use their oriented ellipsoid radii. At most 65536 live particles are accepted, bounding O(N log maxHits) work. Ties use current pool index. Simulation-thread affine; owns outputs, invokes no callbacks, retains no references and does not mutate simulation state. Indices become stale on mutation.

在文件 VolumeFluidColliders.cpp 第 370 行定义.

引用了 a, b, center, distance, eve::Diagnostic::error(), finite, hit, eve::InvalidArgument, message, normal, offset, phase, radius , 以及 range.

被这些函数引用 queryBatch().

raycast()

Result< std::vector< VolumeFluidRayHit > > eve::fluids::VolumeFluid::raycast	(	glm::vec3	origin,
		glm::vec3	direction,
		float	maxDistance,
		unsigned	maxHits = 64,
		unsigned	phaseMask = 0x0f
	)		const

Raycasts native oriented-ellipsoid particles and returns nearest hits first.

参数

origin	Finite world-space ray origin.
direction	Finite nonzero direction; normalized internally.
maxDistance	Finite segment length in [0,10000] meters.
maxHits	Output bound in [1,4096]. The nearest hits are retained.
phaseMask	Bits 0..3 select Liquid, Gas, Granular and Solid; other bits fail.

返回

Owning hits, or failure without simulation mutation.

Transforms the ray into each selected particle's unit-sphere frame. An origin inside a particle reports distance zero. At most 65536 live particles are accepted per query to bound O(N log maxHits) work. Ties use pool index for repeatability. Simulation-thread affine; no callbacks or retained references. Indices become stale after any particle mutation.

在文件 VolumeFluidColliders.cpp 第 324 行定义.

引用了 a, b, direction, distance, eve::Diagnostic::error(), finite, hit, eve::InvalidArgument, message, normal, origin, phase, point , 以及 range.

releaseGrabbedParticles()

Result< unsigned > eve::fluids::VolumeFluid::releaseGrabbedParticles

(

unsigned

colliderLabel

)

Releases one grabber label and restores normal particle dynamics.

返回

Released particle count. Missing labels are a successful zero count.

在文件 VolumeFluidTools.cpp 第 385 行定义.

引用了 count, label , 以及 eve::Result< T >::success().

restore()

Result< void > eve::fluids::VolumeFluid::restore

(

const VolumeFluidSnapshot &

snapshot

)

Validates a complete candidate before replacing state; failures preserve the current solver.

在文件 VolumeFluidTools.cpp 第 642 行定义.

引用了 a, eve::fluids::VolumeFluidSnapshot::attachments, c, eve::fluids::VolumeFluidSnapshot::colliders, create(), eve::Result< T >::failure(), finite, eve::fluids::VolumeFluidSnapshot::heightFieldColliders, eve::fluids::VolumeFluidSnapshot::particles, particles(), range, eve::fluids::VolumeFluidSnapshot::schema, eve::fluids::VolumeFluidSnapshot::sdfColliders, eve::fluids::VolumeFluidSnapshot::settings, eve::fluids::VolumeFluidSnapshot::simplexes, snapshot(), eve::fluids::VolumeFluidSnapshot::stitches, eve::Result< T >::success(), topology , 以及 eve::fluids::VolumeFluidSnapshot::version.

被这些函数引用 eve::fluids_editing::VolumeFluidRuntimeApplier::apply().

sampleField()

Result< std::vector< VolumeFluidFieldSample > > eve::fluids::VolumeFluid::sampleField

(

std::span< const glm::vec3 >

positions

)

const

Samples the current liquid/gas field at up to 65536 finite world positions.

Simulation-thread only; positions are borrowed for this call, output owns one sample per input in the same order. No callbacks or time advancement. Rebuilds derived spatial scratch to account for emission/lifetime/restore. Empty support returns zero fields. Solids and granular particles do not contribute.

返回

Complete samples, or failure without observable mutation for invalid input or more than 4000000 candidate particle visits. No partial batch is returned.

在文件 VolumeFluidTools.cpp 第 395 行定义.

引用了 positions.

setActorCollisionFilter()

Result< void > eve::fluids::VolumeFluid::setActorCollisionFilter	(	unsigned	actorGroup,
		unsigned	collisionFilter
	)

Applies Fluid3DEmitter.Filter to every live particle in one actor group.

参数

actorGroup	Stable actor group in [0,0x00ffffff].
collisionFilter	Packed category/mask value; both 16-bit halves must be nonzero.

Replaces the complete packed filter for matching particles. This is an explicit allocation-free linear scan; missing groups and invalid input fail before mutation and the operation performs no solver or GPU work.

在文件 VolumeFluidTools.cpp 第 247 行定义.

引用了 eve::Diagnostic::error(), eve::Result< T >::failure(), eve::NotFound , 以及 eve::Result< T >::success().

setActorFilterCategory()

Result< void > eve::fluids::VolumeFluid::setActorFilterCategory	(	unsigned	actorGroup,
		unsigned	category
	)

Applies Fluid3D SetFilterCategory to all particles in one actor group.

参数

actorGroup	Stable actor group in [0,0x00ffffff].
category	Collision category index in [0,15].

Replaces each matching filter's low 16-bit category with one bit while preserving its high 16-bit mask. Explicit allocation-free linear scan; missing groups and invalid input fail without mutation or GPU work.

在文件 VolumeFluidTools.cpp 第 234 行定义.

引用了 category, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::NotFound , 以及 eve::Result< T >::success().

setActorSelfCollisions()

Result< void > eve::fluids::VolumeFluid::setActorSelfCollisions	(	unsigned	actorGroup,
		bool	enabled
	)

Applies Fluid3DEmitter::SetSelfCollisions to all live particles in one actor group.

参数

actorGroup	Stable actor group in [0,0x00ffffff].
enabled	Whether same-group pairs may generate particle contacts.

Actor existence is checked before one allocation-free linear mutation; missing groups fail without state changes or GPU work.

在文件 VolumeFluidTools.cpp 第 284 行定义.

引用了 enabled, eve::Diagnostic::error(), eve::Result< T >::failure(), eve::NotFound , 以及 eve::Result< T >::success().

setColliders()

Result< void > eve::fluids::VolumeFluid::setColliders

(

std::span< const VolumeFluidCollider >

colliders

)

Atomically replaces owned obstacle samples; rejects invalid geometry and duplicate labels.

Collider labels identify successive poses. Removing a label detaches its solids at their current position; later label reuse does not reattach them. Changing a pose takes effect on the next step. Turning solidify off affects future contacts only; paint to a non-solid phase explicitly melts and detaches. At most four million live particle/collider candidates are accepted.

在文件 VolumeFluidColliders.cpp 第 4 行定义.

引用了 a, eve::fluids::Box, c, eve::fluids::Capsule, finite, input, label, range, eve::fluids::Sphere, eve::Result< T >::success() , 以及 terrain.

setGravity()

Result< void > eve::fluids::VolumeFluid::setGravity

(

glm::vec3

gravity

)

Replaces world-space gravity for subsequent fixed steps.

参数

gravity

Finite acceleration with magnitude at most 1000 m/s^2.

返回

Success, or invalid argument without changing solver settings.

Native particles already use world-space coordinates, so this is the package WorldSpaceGravity behavior without retaining a Transform. Constant-time, simulation-thread affine, and adds no particle traversal, callback or GPU work.

在文件 VolumeFluid.cpp 第 643 行定义.

引用了 finite , 以及 gravity.

setHeightFieldColliders()

Result< void > eve::fluids::VolumeFluid::setHeightFieldColliders

(

std::span< const VolumeFluidHeightFieldCollider >

colliders

)

Atomically replaces owned Fluid3D-compatible regular height-field colliders.

参数

colliders

Borrowed descriptions copied before publication; each grid is row-major X-fastest.

返回

Success, or a structured validation error without changing current colliders.

At most 16 grids and four million total samples are accepted. Each particle samples only its local cell's two triangles, so work is linear in particle-count times height-field-count. Simulation-thread only; no callback or external pointer is retained.

在文件 VolumeFluidColliders.cpp 第 205 行定义.

引用了 c, finite, h, input, label , 以及 eve::Result< T >::success().

setParticleExternalForces()

Result< void > eve::fluids::VolumeFluid::setParticleExternalForces

(

std::span< const glm::vec3 >

forces

)

Replaces one-step world-space forces in newtons, one per current particle.

A nonempty span must match the dense pool and contain finite vectors of at most 1000 N. Forces survive failed steps, clear after a successful whole step, and are absent from snapshots. The inactive path is compile-time specialized out of particle integration.

在文件 VolumeFluid.cpp 第 95 行定义.

setParticleWinds()

Result< void > eve::fluids::VolumeFluid::setParticleWinds

(

std::span< const glm::vec3 >

winds

)

Replaces one-step per-particle wind velocities used by atmospheric drag.

Simulation-thread only. A nonempty borrowed span must match the current particle count and contain finite velocities of at most 1000 m/s. Values are copied, survive a failed step, and clear after the next successful whole step. An empty span clears pending wind. Wind is transient and absent from snapshots.

在文件 VolumeFluid.cpp 第 82 行定义.

setSdfColliders()

Result< void > eve::fluids::VolumeFluid::setSdfColliders

(

std::span< const VolumeFluidSdfCollider >

colliders

)

Atomically replaces at most 16 owned mesh/SDF colliders; total samples are bounded to 4M.

在文件 VolumeFluidColliders.cpp 第 152 行定义.

引用了 c, finite, input, label, local, maximum, minimum, range, rotation, eve::Result< T >::success(), terrain, value , 以及 world.

setSimplexes()

Result< void > eve::fluids::VolumeFluid::setSimplexes

(

std::span< const VolumeFluidSimplex >

simplexes

)

Atomically replaces point/edge/triangle topology over current particle indices.

At most 65536 simplexes. Empty restores implicit point topology. New emissions remain addressable as implicit points only when topology is empty; explicit topology is otherwise unchanged. Lifetime removal remaps surviving indices and drops affected simplexes.

在文件 VolumeFluidTools.cpp 第 4 行定义.

引用了 eve::Result< T >::success().

setStitches()

Result< void > eve::fluids::VolumeFluid::setStitches

(

std::span< const VolumeFluidStitch >

stitches

)

Atomically replaces Fluid3DStitcher-compatible zero-distance constraints.

参数

stitches

Borrowed pairs copied after complete validation; at most 65536.

Indices in each pair must be distinct and no unordered pair may repeat. Compliance is finite in [0,1000000]. Constraints respect particle mass and fixed attachment/grabber state, persist in snapshots and remap on particle removal. Empty input clears all stitches.

在文件 VolumeFluidColliders.cpp 第 132 行定义.

引用了 a, b, range , 以及 eve::Result< T >::success().

snapshot()

VolumeFluidSnapshot eve::fluids::VolumeFluid::snapshot

(

)

const

Returns complete owning state; scratch grids and last-step contacts are derived and omitted.

在文件 VolumeFluidTools.cpp 第 629 行定义.

被这些函数引用 eve::fluids_editing::VolumeFluidRuntimeApplier::apply(), eve::fluids::captureVolumeFluidEmitterCheckpoint(), eve::fluids::captureVolumeFluidEmitterCheckpoint() , 以及 restore().

spacing()

float eve::fluids::VolumeFluid::spacing

(

)

const

Returns the rest lattice spacing without copying state.

在文件 VolumeFluid.cpp 第 642 行定义.

被这些函数引用 eve::fluids::VolumeFluidJetEmitter::advanceMoving().

step()

Result< void > eve::fluids::VolumeFluid::step	(	float	seconds,
		unsigned	substeps = 4
	)

Advances by an injected duration in (0,1/30] seconds with 1..32 substeps.

Rejects invalid input before mutation. Each substep must be <=1/120 s. Numerical failure restores the complete pre-step particle state. Analytic/SDF colliders use their sampled linear and angular velocities to back-extrapolate each substep pose without copying SDF samples. Attached solids follow the latest collider pose with linear substep interpolation. Out-of-bounds targets, linear speeds above 100 m/s or angular speeds above 1000 rad/s fail atomically. After substeps, attached solids on solidifying colliders propagate to touching movable particles within 1.001 times spacing. A wave's new solids do not seed until the next call; competing sources choose the smallest collider label.

在文件 VolumeFluid.cpp 第 78 行定义.

stepWithColliders()

Result< void > eve::fluids::VolumeFluid::stepWithColliders	(	float	seconds,
		unsigned	substeps,
		std::span< const VolumeFluidCollider >	colliders,
		std::span< const VolumeFluidThermalRule >	rules = {}
	)

Atomically updates collider samples and advances; failed steps restore prior samples and particles.

在文件 VolumeFluid.cpp 第 624 行定义.

被这些函数引用 eve::fluids::VolumeFluidCoupling::step().

stepWithThermalContacts()

Result< void > eve::fluids::VolumeFluid::stepWithThermalContacts	(	float	seconds,
		unsigned	substeps,
		std::span< const VolumeFluidThermalRule >	rules
	)

Advances and applies bounded contact transfer to user channels, once per particle/rule.

Simulation-thread only; at most 1024 uniquely labelled rules referring to current colliders. Rates must be finite in [-1000000,1000000]. Bounds lie within viscosity [0,100] and cohesion [0,10]. Rules are borrowed only for this call; no callbacks or persistent bindings are created. Transfer precedes lifetime removal. Call applyMaterialChannels explicitly to update materials for the next step.

返回

Invalid rules/dt fail before mutation; numerical failure restores state.

在文件 VolumeFluid.cpp 第 183 行定义.

引用了 a, angle, angularVelocity, b, c, distance, end, EV_PROFILE_MODULE, finite, found, index, inertia, length, local, maximum, minimum, p, pose, q, r, radii, range, rotation, start, target , 以及 world.

teleportActor()

Result< void > eve::fluids::VolumeFluid::teleportActor	(	glm::vec3	currentPosition,
		glm::vec4	currentRotation,
		glm::vec3	targetPosition,
		glm::vec4	targetRotation
	)

Teleports the whole fluid actor between explicit world poses.

参数

currentPosition	Current actor origin in world space.
currentRotation	Current unit actor rotation in XYZW order.
targetPosition	Target actor origin in world space.
targetRotation	Target unit actor rotation in XYZW order.

Applies targetRotation*inverse(currentRotation) to particle positions and orientations, then clears linear/angular velocity like Fluid3DActor::Teleport. All transformed particles are checked against solver bounds before mutation. Attachments and simplex indices remain owned and valid; derived contacts and reaction output are cleared. Allocation-free linear-time simulation operation.

在文件 VolumeFluidTools.cpp 第 177 行定义.

引用了 finite, from, position, rotation, eve::Result< T >::success() , 以及 to.

unbindStaticParticles()

Result< unsigned > eve::fluids::VolumeFluid::unbindStaticParticles

(

std::span< const unsigned >

particleIndices

)

Removes anchors for the supplied unique current indices, returning the number removed atomically.

在文件 VolumeFluidColliders.cpp 第 110 行定义.

引用了 eve::Diagnostic::error() , 以及 eve::InvalidArgument.

updateActorMaterial()

Result< void > eve::fluids::VolumeFluid::updateActorMaterial	(	unsigned	actorGroup,
		const VolumeFluidParticle &	prototype
	)

Applies Fluid3DEmitter::UpdateParticleMaterial to one live actor group.

参数

actorGroup	Stable actor group in [0,0x00ffffff].
prototype	Borrowed emitter prototype supplying material, data, radii, collision filter and self-collision state; motion, pose, color and life are ignored.

The complete prototype subset and actor existence are validated before one allocation-free linear mutation. Automatic zero radii resolve to spacing/2. No callback, fixed-step traversal or GPU work is installed.

在文件 VolumeFluidTools.cpp 第 259 行定义.

引用了 eve::fluids::VolumeFluidParticle::collisionFilter, eve::fluids::VolumeFluidParticle::data, eve::Diagnostic::error(), eve::Result< T >::failure(), finite, eve::fluids::VolumeFluidParticle::material, eve::NotFound, eve::fluids::VolumeFluidParticle::radii, radii, eve::fluids::VolumeFluidParticle::selfCollide , 以及 eve::Result< T >::success().

updateGrabbedParticles()

Result< unsigned > eve::fluids::VolumeFluid::updateGrabbedParticles	(	unsigned	colliderLabel,
		glm::vec3	position,
		glm::vec4	rotation
	)

Moves all particles owned by one contact grabber to a new world pose.

返回

Updated particle count; out-of-bounds poses fail before mutation.

Allocation-free after first capture and performs no solver step, callback or GPU work. The caller supplies the authoritative fixed-step pose.

在文件 VolumeFluidTools.cpp 第 356 行定义.

引用了 count, eve::Diagnostic::error(), eve::Result< T >::failure(), finite, eve::InvalidArgument, message, position, q, rotation, eve::Result< T >::success() , 以及 target.

updateSdfColliderPoses()

Result< void > eve::fluids::VolumeFluid::updateSdfColliderPoses

(

std::span< const VolumeFluidSdfPose >

poses

)

Atomically updates transforms of existing owned SDF colliders without copying distance samples.

Simulation-thread only. Each stable label must exist exactly once in the input. Position, unit XYZW rotation, uniform scale and surface velocities are validated before mutation. Inverted fields must still cover solver bounds after the update. Omitted labels retain their current pose. No callbacks or borrowed input are retained.

在文件 VolumeFluidColliders.cpp 第 242 行定义.

引用了 finite, found, index, indices, label, local, maximum, minimum, pose, range, rotation, eve::Result< T >::success() , 以及 world.

友元及相关函数文档

VolumeFluidDiffuse

friend class VolumeFluidDiffuse

friend

在文件 VolumeFluid.h 第 1130 行定义.

VolumeFluidFoam

friend class VolumeFluidFoam

friend

在文件 VolumeFluid.h 第 1129 行定义.

---

该类的文档由以下文件生成:

• src/modules/fluids/VolumeFluid.h
• src/modules/fluids/VolumeFluid.cpp
• src/modules/fluids/VolumeFluidColliders.cpp
• src/modules/fluids/VolumeFluidTools.cpp