WaterRippleSimulation

Remarks

[35 § D12](../../docs/plan/35-water.md#d12-ripples-are-a-sliding-window-height-field-and-they-are-displacement-not-geometry), the device half. WaterRipples is the CPU reference and the thing a test measures against; this is what a frame actually runs, and WaterRippleSeamTests is what holds the two together.

⚠ The seam's tolerance is stated in metres and is not exact-to-the-float, and that asymmetry is the design rather than a concession. The closed-form wave sum in Surface.rvn is held exactly, because a rollback re-asks it at a time it never simulated — it is an expression, and two evaluations of one expression agree. A height field's state is its history: there is no expression to compare, only a trajectory, and two trajectories that begin together diverge at whatever rate the arithmetic differs. Which is why the ripple contribution is a separate argument to WaterEvaluator and the network path passes none at all.

⚠ Height and rate in one texture's rg, not two pairs. Two ping-pongs is four textures and two chances for one to be advanced without the other — which is a simulation reading this step's height with last step's rate, and it is stable, so it does not announce itself.

⚠ § B5: glBindImageTexture is ⬜ in the GL backend, so the shader carries a Compute permutation and its off variant is the same arithmetic writing a colour target. Compute is what a host sets from the backend it opened.

Fields and properties (13)

• public const int MaxInjections

  How many disturbances one step applies, which is the shader's array length.

• public const int GroupSize

  How many texels a compute group covers along each axis — the shader's own.

• public WaterRippleSettings Settings

  The window, the rate and the budget.

• public Vector2 Origin

  Where the window's low corner is, on the ground plane.

• public int StepsPerFrame

  How many steps one submit may record, which is how long the descriptor ring is.

• public bool Compute

  Whether this backend can write a storage image at all — § B5.

• public int Injections

  How many disturbances this step has taken.

• public int Overflowed

  And how many it had to refuse. ⚠ Non-zero is a wake some hulls do not make.

• public long StepCount

  How many steps have been dispatched.

• public TextureHandle Field

  The texture a consumer samples — the one the last step wrote.

• public bool HasHistory

  Whether anything has been written yet.

• public int ReadbackBytes

  How many bytes a readback of the whole field is.

• public TextureDescription Description

  What each of the two textures is.

Methods (10)

• public WaterRippleSimulation(IGraphicsDevice device, in WaterRippleSettings settings, Vector2 origin = default(Vector2), bool readable = false)

  Creates the pair and its state.

• public bool Inject(Vector2 position, float radius, float amount)

  Queues a disturbance for the next step.

• public int Apply(WaterDisturbances queue)

  Injects every disturbance a step produced.

• public void MoveTo(Vector2 origin)

  Moves the window's low corner. ⚠ The contents do not move with it.

• public void Clear(RenderGraph graph)

  Declares a pass that clears the field, so the first read is defined.

• public bool Record(RenderGraph graph, EffectSystem effects, ComputePipelineCache pipelines, float deltaTime)

  Declares this step's dispatch.

• public void RecordReadback(ICommandList commands, BufferHandle into)

  Copies the field back to the host, for a fixture that measures the seam.

• public void Advance()

  Swaps the pair, so this step's result becomes the next one's input.

• public RipplesConstants Describe(float deltaTime)

  The uniform block one step needs, filled from the settings and this step's queue.

• public void Dispose()

  Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Used by (1)

• WaterRippleSeamTestsVixen.Graphics.Golden.Tests