Skip to content

Interactive 2D wave optics simulator. Turn any image into a refractive scene, add sources, watch waves refract, diffract and interfere. Probes, intensity maps, video export.

C#

The GPU's frames land by DMA in page-locked snapshots on a transfer queue; the store touches its blocks on four cores

Alexander Graef2dbb47637ea7
diff --git a/CLAUDE.md b/CLAUDE.md
index d200359..6eb3946 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -128,7 +128,15 @@ FrameStore: native memory up to the budget, the rest in a temp file (%LOCALAPPDA
method is in `library_check`); a version-1 file loads as
Reflective, a version-2 file without a damping edge with none (its default then; files are version 3 since 2026-10-22), an
import as Reflective with his band; one driver thread at a time, no locking; the kernels over the grid and the captures run in explicit 32 × 8 work groups over a global size rounded up to whole groups (2026-10-27, Jeroen's report: left to the driver, the group had to divide the grid, and a prime width, 1789 for a 1725 px canvas with the rim, got groups one cell wide, 13–19× slower on the RTX 2080; every candidate shape from 16 × 16 to 256 × 1 measured the same); captures
- deliver planes in the spec's `FrameShape` (halves or palette index bytes, the GPU converting on the card);
+ deliver planes in the spec's `FrameShape` (halves or palette index bytes, the GPU converting on the card) into snapshots
+ the engine made (`IWaveEngine.CreateSnapshot`, 2026-11-03, the user's choice): the GPU's planes are page-locked host
+ memory (`CL_MEM_ALLOC_HOST_PTR`, mapped for the engine's life, released with it, a later read throws), so the capture's
+ read is a DMA the stepping thread does not wait for, on a transfer queue of its own so it overlaps the next steps (two
+ staging sets in turn, the capture kernel waiting for the read that last left its set, the read for the kernel, each
+ queue flushed before the other waits on its event, as the spec requires; 1.9 → 1.3 ms a full-HD frame on the card); a
+ .NET-pinned array is pageable to the driver, which drained the queue and copied on the stepping thread inside the
+ "non-blocking" enqueue, 2.9 of a full-HD frame's 2.96 ms (the old note blamed the single queue: a second queue alone
+ changed nothing). The scratch runner's snapshots stay ordinary, since a result outlives its engine;
`Reset`, `SetEmitters`, `SetProbes`. Numerics are Jeroen's (dx = dt = 1, leapfrog, 9-point or 4th-order
Laplacian, soft sources, EMA intensity; a scene pixel with red 0 is a mirror, n = 1000, his V0.30 rule,
2026-10-18), verified CPU = GPU by the harness; seeds from `Pcg32` make CPU = GPU
@@ -143,7 +151,10 @@ FrameStore: native memory up to the budget, the rest in a temp file (%LOCALAPPDA
Simulation > RAM cache size (Auto or a share); the
outgoing run's frames count as reclaimed and the new store waits for their release. No memory mapping, no OS
cache reliance (both wrote at disk speed). Disposed on the thread pool. Full HD, 2500 steps, both planes: 10.4 GB
- in 16-bit, half in 8-bit.
+ in 16-bit, half in 8-bit. The producer touches a fresh block's pages on up to four cores (2026-11-03: Windows zeroes
+ pages at 5 GB/s for one thread, 1.7 ms a full-HD block, which had been the writer's clock); the writer's copy into the
+ block stays one plain `CopyTo`, the clock of a 16-bit run in RAM, since every parallel copy slowed the card's DMA by more
+ than it gained (see Numbers). **Do not resurrect**: a parallel or dedicated-thread copy in `FrameStore.Write`.
- **Reduced preview** (View menu): resolution 1/2/4, frames 1/2/4 (the timeline never changes), samples 16-bit or
**8-bit palette index, the default**: the stored samples at the palette's 255 colours and the captured brightness,
half the store; 16-bit keeps the brightness turnable after a run and shows every level of the gradient. In 8-bit a
@@ -409,8 +420,22 @@ FrameStore: native memory up to the budget, the rest in a temp file (%LOCALAPPDA
## Numbers (workstation: 10-core Xeon without AVX2, RTX 2080, 64 GB)
-GPU step at 1080p 0.25–0.5 ms, CPU 6–14 ms; OpenCL build 0.3 s; a full-HD run of 2500 steps 5.4 s in RAM, bound by
-the GPU readback. Renderer per 2880×1080 layer on ten cores (2026-10-23, a table lookup per pixel): 16-bit 0.5 ms,
+GPU step at 1080p 0.25–0.5 ms, CPU 6–14 ms; OpenCL build 0.3 s; a full-HD frame's capture (both planes as halves, 8.3 MB)
+0.9 ms on top of its two steps since the page-locked snapshots (2026-11-03; 2.1 ms before, the stepping thread blocked in
+the driver's copy; `bench 1920 1080`: 1.50 → 0.65 ms a step with captures every 2 steps at 4th order, the DMA on its own
+queue), the DMA itself 0.63 ms at 13 GB/s. In the app the default project's run (2500 steps, 1250 frames, 16-bit, both
+planes, 9.7 GiB) takes 2.7 s (2026-11-03; 3.2 before the transfer queue, about 4 before the page-locked snapshots): the card
+needs about 1.3 ms a frame, the writer 1.6 ms for its copy of a frame into the store on one core (6.8 GB/s) and is the
+clock, the stepping thread parked 1.8 ms a frame for a free snapshot. Measured on the way and settled: the capture's reads
+are flushed at once (NVIDIA holds a small batch back until a blocking call; the writer's wait had been starting the DMA,
+0.8 ms a frame); the store's producer touches a fresh block's pages on four cores (Windows zeroes pages at 5 GB/s for one
+thread, 1.7 ms a full-HD block, which had been the writer's clock before the copy was; 0.6 on four, eight gain nothing);
+every faster copy lost in a run though 0.35 ms on four cores in isolation (torn out, three variants measured in the app):
+chunks on the thread pool queued behind the presenter's rendering rows; two or four dedicated threads, at normal or
+above-normal priority, copied faster but the writer's wait for the card rose by more, the memory bus being shared with
+the DMA, the producer's page zeroing and the presenter — the frame's way into memory is bandwidth-bound on this DDR3
+Xeon, and the plain copy at 6.8 GB/s leaves the DMA its share. Renderer per 2880×1080 layer on ten cores (2026-10-23, a
+table lookup per pixel): 16-bit 0.5 ms,
8-bit 0.6; a half table built in 0.4 ms; the screen path from 1920×1080 to 914×514 1.4 ms, dithered 1.5. Presenter for
Example 7 (2880×1080 in a 458×172 picture, both layers, playing): 16-bit 7.3–8.5 ms a frame, dithered 7.7–9.1, 8-bit
10–11 (its bitmaps are canvas-sized). Presenter about 7 ms a frame quiet, 20 during a run. JPEG 1080p at 4:4:4: WIC 26 ms a frame
@@ -422,7 +447,7 @@ numbers: no GPU JPEG, no OpenCL colouring at presentation, no `Vector256`, no Di
## Harnesses
-`library_check` (100+ checks: engines, store, renderer, half tables, screen path, schemes, probes, scratch, reduced preview, importer, export, parts, group move, open edges, work groups on a prime grid, ranges, XOR gate, zone plate, gate port follower, history, clipboard, the project file's DTD, the first start's tiers).
+`library_check` (100+ checks: engines, store, renderer, half tables, screen path, schemes, probes, scratch, reduced preview, importer, export, parts, group move, open edges, work groups on a prime grid, ranges, XOR gate, zone plate, gate port follower, history, clipboard, the project file's DTD, the first start's tiers, the engine's page-locked snapshots).
UI, all on `Common.ps1`, with their check counts: `PreviewCheck` 43, `RunCheck` 71, `LanguageCheck` 11,
`ProbeGraphCheck` 39, `ImportCheck` 10, `ExportCheck` 44, `PreviewQualityCheck` 35, `SceneImageCheck` 8,
`ColorPickerCheck` 13, `KeyboardCheck` 13, `AboutCheck` 18, `SelectionCheck` 10. Test projects `tiny*.wdproj` sit beside them. The
@@ -464,12 +489,11 @@ never reworded per file.
## Open items
-README and a documentation file (he writes them); release (single-file publish, portable archive, signed installer,
-curated examples from Jeroen, his program as preserved assets, repository rename); an integer
-upscale in exports; HEVC; the start-up stall (log milestones first); the GPU readback (a second OpenCL queue);
+README and a documentation file (he writes them); an integer
+upscale in exports; HEVC;
automatic quality lowering when a run would spill (undecided); dropping the 9-point Laplacian (undecided);
**optical parts**: the open points at the end of `OpticalParts.md` (a `PartCheck.ps1` harness, example projects,
-the menu versus buttons, Bragg thicknesses in pixels, where examples live) wait for the user.
+Bragg thicknesses in pixels) wait for the user.
**Unsolved: clicks on the intensity picture selected nothing** (2026-10-22, seen once, not reproduced). In
Jeroen's `logical_elements_example.wdproj` (git history up to 02d0e2d; Example 18 is its curated form), after several
diff --git a/OpticalParts.md b/OpticalParts.md
index de417fe..a492a95 100644
--- a/OpticalParts.md
+++ b/OpticalParts.md
@@ -231,7 +231,6 @@ the check's small canvas, +6 % in a wide one).
- A `PartCheck.ps1` harness (add a part by keys, edit a value, the run goes stale and re-runs, the handle moves with
the arrows) and example projects for Jeroen (a lens, a cavity, a bent fibre); the planned stage 3.
-- The "+ Part" menu as the way to choose a kind, against a button per kind (decided in practice, never confirmed).
- Bragg thicknesses in pixels as typed, without an automatic quarter-wave from a source's wavelength.
- Where example projects live: settled (2026-10-29/31): the curated set in `Examples/`, embedded in the app; Jeroen's
originals are out of the repository (git history up to 02d0e2d), the four the import checks read sit in
diff --git a/WaveDudeNext/Engine/FrameSnapshot.cs b/WaveDudeNext/Engine/FrameSnapshot.cs
index 5c4af37..7bd6be3 100644
--- a/WaveDudeNext/Engine/FrameSnapshot.cs
+++ b/WaveDudeNext/Engine/FrameSnapshot.cs
@@ -15,6 +15,7 @@
// version. It is distributed WITHOUT ANY WARRANTY. See the LICENSE.md file or
// <https://www.gnu.org/licenses/>.
+using System.Buffers;
using System.Runtime.InteropServices;
namespace WaveDudeNext.Engine;
@@ -24,20 +25,36 @@ namespace WaveDudeNext.Engine;
/// planes of a <see cref="FrameShape"/> (<see cref="Width"/> × <see cref="Height"/> samples row-major, the
/// engine's padding stripped, the canvas shrunk by the shape's divisor, each sample a <see cref="Half"/> or a
/// palette index byte). Filled by <see cref="IWaveEngine.CaptureFrame"/> and complete after
-/// <see cref="IWaveEngine.AwaitFrame"/>; the arrays live on the pinned object heap so the GPU can copy into
-/// them asynchronously. Reusable: a pool of two or three lets a run convert and store one frame while the
-/// engine computes the next. Not thread-safe; one owner at a time.
+/// <see cref="IWaveEngine.AwaitFrame"/>. The planes never move: an ordinary snapshot's (the constructors) are arrays
+/// on the pinned object heap; one made by <see cref="IWaveEngine.CreateSnapshot"/> may lie in memory the engine owns
+/// (the GPU engine's page-locked host memory, which the card fills by DMA while the stepping thread goes on,
+/// 2026-11-03), released with the engine, after which the planes throw. Reusable: a pool of two or three lets a run
+/// convert and store one frame while the engine computes the next. Not thread-safe; one owner at a time.
/// </summary>
public sealed class FrameSnapshot
{
+ private readonly Memory<byte> _field;
+ private readonly Memory<byte> _intensity;
+ private readonly IntPtr _fieldAddress;
+ private readonly IntPtr _intensityAddress;
+ private bool _released;
+
+ /// <summary>An ordinary snapshot: its planes are pinned arrays of this process, alive as long as the snapshot.</summary>
/// <param name="shape">What to capture: the canvas, the shrinking, the format and the brightness baked into an index frame.</param>
/// <param name="withIntensity">Whether to allocate the intensity plane.</param>
public FrameSnapshot(FrameShape shape, bool withIntensity)
{
Shape = shape.Validate();
int bytes = checked((int)shape.PlaneBytes);
- FieldBytes = GC.AllocateArray<byte>(bytes, pinned: true);
- IntensityBytes = withIntensity ? GC.AllocateArray<byte>(bytes, pinned: true) : null;
+ byte[] field = GC.AllocateArray<byte>(bytes, pinned: true);
+ _field = field;
+ _fieldAddress = Marshal.UnsafeAddrOfPinnedArrayElement(field, 0);
+ if (withIntensity)
+ {
+ byte[] intensity = GC.AllocateArray<byte>(bytes, pinned: true);
+ _intensity = intensity;
+ _intensityAddress = Marshal.UnsafeAddrOfPinnedArrayElement(intensity, 0);
+ }
}
/// <summary>A full-quality snapshot of a canvas: every cell as a <see cref="Half"/>.</summary>
@@ -49,6 +66,24 @@ public sealed class FrameSnapshot
{
}
+ /// <summary>
+ /// A snapshot over planes an engine owns (<see cref="IWaveEngine.CreateSnapshot"/>): <paramref name="field"/> and
+ /// <paramref name="intensity"/> (<see cref="IntPtr.Zero"/> for none) each address <see cref="FrameShape.PlaneBytes"/>
+ /// bytes that stay put until the engine calls <see cref="Release"/>.
+ /// </summary>
+ internal FrameSnapshot(FrameShape shape, IntPtr field, IntPtr intensity)
+ {
+ Shape = shape.Validate();
+ int bytes = checked((int)shape.PlaneBytes);
+ _fieldAddress = field;
+ _field = new PlaneMemoryManager(field, bytes).Memory;
+ _intensityAddress = intensity;
+ if (intensity != IntPtr.Zero)
+ {
+ _intensity = new PlaneMemoryManager(intensity, bytes).Memory;
+ }
+ }
+
/// <summary>The frame's geometry and format; the engine captures accordingly.</summary>
public FrameShape Shape { get; }
@@ -59,10 +94,15 @@ public sealed class FrameSnapshot
public int Height => Shape.Height;
/// <summary>The field plane's bytes (<see cref="FrameShape.PlaneBytes"/>); valid after <see cref="IWaveEngine.AwaitFrame"/>.</summary>
- public byte[] FieldBytes { get; }
+ /// <exception cref="ObjectDisposedException">The engine that owned the planes has been disposed.</exception>
+ public Span<byte> FieldBytes => FieldMemory.Span;
+
+ /// <summary>The intensity plane's bytes, or empty when the snapshot was created without one (<see cref="HasIntensityPlane"/>).</summary>
+ /// <exception cref="ObjectDisposedException">The engine that owned the planes has been disposed.</exception>
+ public Span<byte> IntensityBytes => IntensityMemory.Span;
- /// <summary>The intensity plane's bytes, or null when the snapshot was created without one.</summary>
- public byte[]? IntensityBytes { get; }
+ /// <summary>Whether the snapshot has an intensity plane at all; <see cref="HasIntensity"/> says whether the last capture filled it.</summary>
+ public bool HasIntensityPlane => _intensityAddress != IntPtr.Zero;
/// <summary>The field plane as <see cref="Half"/> values; only for a <see cref="FrameFormat.Half"/> shape.</summary>
/// <exception cref="InvalidOperationException">The shape's samples are not halves.</exception>
@@ -70,7 +110,7 @@ public sealed class FrameSnapshot
/// <summary>The intensity plane as <see cref="Half"/> values; only for a <see cref="FrameFormat.Half"/> shape with an intensity plane.</summary>
/// <exception cref="InvalidOperationException">The shape's samples are not halves, or there is no intensity plane.</exception>
- public Span<Half> Intensity => Halves(IntensityBytes ?? throw new InvalidOperationException("The snapshot has no intensity plane."));
+ public Span<Half> Intensity => Halves(HasIntensityPlane ? IntensityBytes : throw new InvalidOperationException("The snapshot has no intensity plane."));
/// <summary>Whether the last capture filled <see cref="IntensityBytes"/> (the engine may have been asked for the field only).</summary>
public bool HasIntensity { get; internal set; }
@@ -96,15 +136,52 @@ public sealed class FrameSnapshot
/// <summary>Whether <see cref="FieldFloats"/> (and <see cref="IntensityFloats"/> when <see cref="HasIntensity"/>) hold a capture not yet converted.</summary>
internal bool PendingConversion { get; set; }
- /// <summary>Address of a plane's first byte, stable because the arrays are pinned.</summary>
- internal static IntPtr AddressOf(byte[] plane) => Marshal.UnsafeAddrOfPinnedArrayElement(plane, 0);
+ /// <summary>The field plane as <see cref="Memory{T}"/>, for the CPU engine's row-parallel conversion (<see cref="FrameConversion.Convert"/>).</summary>
+ internal Memory<byte> FieldMemory => Alive(_field);
+
+ /// <summary>The intensity plane as <see cref="Memory{T}"/> (empty without one); see <see cref="FieldMemory"/>.</summary>
+ internal Memory<byte> IntensityMemory => Alive(_intensity);
+
+ /// <summary>Address of the field plane's first byte, stable (pinned or page-locked), for the GPU engine's DMA reads.</summary>
+ internal IntPtr FieldAddress => Alive(_fieldAddress);
+
+ /// <summary>Address of the intensity plane's first byte, or <see cref="IntPtr.Zero"/> without one; see <see cref="FieldAddress"/>.</summary>
+ internal IntPtr IntensityAddress => Alive(_intensityAddress);
- private Span<Half> Halves(byte[] plane)
+ /// <summary>Bytes per plane (<see cref="FrameShape.PlaneBytes"/>).</summary>
+ internal int PlaneBytes => (int)Shape.PlaneBytes;
+
+ /// <summary>Called by the engine that owns the planes when it releases them: every later access throws.</summary>
+ internal void Release() => _released = true;
+
+ private T Alive<T>(T value) => _released ? throw new ObjectDisposedException(nameof(FrameSnapshot), "The engine that owned the snapshot's planes has been disposed.") : value;
+
+ private Span<Half> Halves(Span<byte> plane)
{
if (Shape.Format != FrameFormat.Half)
{
throw new InvalidOperationException("The snapshot's samples are palette indices, not halves.");
}
- return MemoryMarshal.Cast<byte, Half>(plane.AsSpan());
+ return MemoryMarshal.Cast<byte, Half>(plane);
+ }
+
+ /// <summary>A <see cref="Memory{T}"/> over an engine-owned plane; the memory is the engine's, so disposing frees nothing.</summary>
+ private sealed unsafe class PlaneMemoryManager(IntPtr address, int length) : MemoryManager<byte>
+ {
+ /// <inheritdoc/>
+ public override Span<byte> GetSpan() => new((void*)address, length);
+
+ /// <inheritdoc/>
+ public override MemoryHandle Pin(int elementIndex = 0) => new((byte*)address + elementIndex);
+
+ /// <inheritdoc/>
+ public override void Unpin()
+ {
+ }
+
+ /// <inheritdoc/>
+ protected override void Dispose(bool disposing)
+ {
+ }
}
}
diff --git a/WaveDudeNext/Engine/GpuWaveSimulator.cs b/WaveDudeNext/Engine/GpuWaveSimulator.cs
index 1eae737..04ffea4 100644
--- a/WaveDudeNext/Engine/GpuWaveSimulator.cs
+++ b/WaveDudeNext/Engine/GpuWaveSimulator.cs
@@ -71,8 +71,10 @@ namespace WaveDudeNext.Engine;
/// "previous field"; every kernel that reads the field exists twice (index 0/1) with the buffers bound in
/// opposite order, so a step merely picks the kernel for <see cref="_current"/> instead of re-binding
/// arguments. The kernels over the grid and the captures run in explicit work groups, the global size rounded up
-/// to whole groups (see <see cref="WorkGroup2D"/> for why). Kernel launches are asynchronous; uploads and
-/// read-backs are blocking. Every OpenCL handle
+/// to whole groups (see <see cref="WorkGroup2D"/> for why). Kernel launches are asynchronous; uploads and the float
+/// read-backs are blocking; a capture's reads are DMA transfers into the page-locked planes of a snapshot made by
+/// <see cref="CreateSnapshot"/>, on a transfer queue of their own so they overlap the steps that follow (two staging
+/// sets in turn, ordered by events; <see cref="EnqueueCapture"/>), awaited later (<see cref="AwaitFrame"/>). Every OpenCL handle
/// created here is registered in <see cref="_scene"/> (the simulation program, kernels and buffers) or
/// <see cref="_probes"/> (everything <see cref="SetProbes"/> creates) and released by <see cref="Dispose"/>,
/// by the constructor when building fails, or — for the probe set — when probes are installed again. The
@@ -220,6 +222,39 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
SetProbes(null);
}
+ /// <summary>
+ /// A snapshot whose planes are page-locked host memory of this context (<c>CL_MEM_ALLOC_HOST_PTR</c> buffers, mapped
+ /// for the engine's life), so <see cref="CaptureFrame"/>'s reads are DMA transfers the stepping thread does not wait
+ /// for: into an ordinary snapshot's arrays, pageable to the driver, the "non-blocking" read drained the queue and
+ /// copied on the calling thread, 2.9 of a full-HD frame's 2.96 ms (2026-11-03). Released with the engine, after which
+ /// the snapshot's planes throw.
+ /// </summary>
+ public FrameSnapshot CreateSnapshot(FrameShape shape, bool withIntensity)
+ {
+ long bytes = shape.Validate().PlaneBytes;
+ IntPtr field = MapHostBuffer(bytes);
+ IntPtr intensity = withIntensity ? MapHostBuffer(bytes) : IntPtr.Zero;
+ var snapshot = new FrameSnapshot(shape, field, intensity);
+ _hostSnapshots.Add(snapshot);
+ return snapshot;
+ }
+
+ /// <summary>A page-locked host buffer of <paramref name="bytes"/>, mapped for reading and writing; the handle and the mapping go into <see cref="_hostPlanes"/> for <see cref="ReleaseAll"/>.</summary>
+ private IntPtr MapHostBuffer(long bytes)
+ {
+ int err = 0;
+ IntPtr buffer = OpenClApi.clCreateBuffer(_context, OpenClApi.MemReadWrite | OpenClApi.MemAllocHostPtr, new IntPtr(bytes), IntPtr.Zero, ref err);
+ OpenClApi.Check(err, "clCreateBuffer (page-locked plane)");
+ IntPtr mapped = OpenClApi.clEnqueueMapBuffer(_queue, buffer, 1U, OpenClApi.MapReadWrite, IntPtr.Zero, new IntPtr(bytes), 0U, IntPtr.Zero, IntPtr.Zero, ref err);
+ if (err != 0)
+ {
+ Quietly(() => OpenClApi.clReleaseMemObject(buffer));
+ OpenClApi.Check(err, "clEnqueueMapBuffer (page-locked plane)");
+ }
+ _hostPlanes.Add((buffer, mapped));
+ return mapped;
+ }
+
/// <inheritdoc/>
public void CaptureFrame(FrameSnapshot snapshot, bool needIntensity)
{
@@ -232,12 +267,15 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
{
throw new InvalidOperationException("The snapshot has a capture in flight; await it first.");
}
- if (_stagingField == IntPtr.Zero)
+ if (_stagingField[0] == IntPtr.Zero)
{
// lazily: most engines never capture (the harness, the probes-only paths). The staging planes have room
// for any shape: a plane is at most the whole canvas as halves
- _stagingField = CreateBuffer((long)_canvasWidth * _canvasHeight * 2, _scene);
- _stagingIntensity = _track ? CreateBuffer((long)_canvasWidth * _canvasHeight * 2, _scene) : IntPtr.Zero;
+ for (int set = 0; set < 2; set++)
+ {
+ _stagingField[set] = CreateBuffer((long)_canvasWidth * _canvasHeight * 2, _scene);
+ _stagingIntensity[set] = _track ? CreateBuffer((long)_canvasWidth * _canvasHeight * 2, _scene) : IntPtr.Zero;
+ }
_captureHalfKernel = CreateKernel(_scene, _scene.Program, "capture_half");
_captureIndexKernel = CreateKernel(_scene, _scene.Program, "capture_index");
_captureLocal = WorkGroup2D(_captureHalfKernel, _captureIndexKernel);
@@ -264,20 +302,36 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
}
}
snapshot.EventCount = 0;
- EnqueueCapture(_field[_current], _stagingField, snapshot.FieldBytes, snapshot, false);
- snapshot.HasIntensity = needIntensity && _track && snapshot.IntensityBytes != null;
+ int stagingSet = _stagingSet;
+ _stagingSet = 1 - stagingSet;
+ EnqueueCapture(_field[_current], stagingSet, snapshot.FieldAddress, snapshot, false);
+ snapshot.HasIntensity = needIntensity && _track && snapshot.HasIntensityPlane;
if (snapshot.HasIntensity)
{
- EnqueueCapture(_intensityOutBuffer, _stagingIntensity, snapshot.IntensityBytes!, snapshot, true);
+ EnqueueCapture(_intensityOutBuffer, stagingSet, snapshot.IntensityAddress, snapshot, true);
}
- // the reads flush the queue once they run; nothing piles up behind them
+ // submitted now, for two reasons: the next capture's kernel waits for these reads, which the spec allows only
+ // once their queue is flushed; and NVIDIA's driver holds a small batch back until a blocking call, so with the
+ // run's stepping thread parked for a free snapshot the writer's wait had been starting the DMA instead of finding
+ // it done (2026-11-03: one DMA time a frame, 0.8 ms at full HD)
+ OpenClApi.Check(OpenClApi.clFlush(_transferQueue), "clFlush (transfer)");
+ // everything is submitted, and the run's pool bounds how far the host gets ahead of the card, so the periodic
+ // finish of AdvanceOneStep is not needed here (it had drained the card every 16 steps and cost 0.17 ms a step, 2026-11-03)
_sinceFinish = 0;
}
- /// <summary>Shrinks and converts a padded float buffer to a plane of the snapshot's shape on the card and enqueues its non-blocking read into the pinned plane.</summary>
- private void EnqueueCapture(IntPtr source, IntPtr staging, byte[] plane, FrameSnapshot snapshot, bool intensity)
+ /// <summary>
+ /// Shrinks and converts a padded float buffer to a plane of the snapshot's shape on the card (staging set
+ /// <paramref name="set"/>) and enqueues its read into the plane at <paramref name="plane"/>
+ /// (<see cref="FrameSnapshot.PlaneBytes"/> bytes, pinned or page-locked) on <see cref="_transferQueue"/>, so the DMA
+ /// overlaps the steps that follow on <see cref="_queue"/>: the capture kernel waits for the read that last left its
+ /// staging set (two captures ago), the read waits for the kernel, and each queue is flushed before the other waits
+ /// on its event, as the spec requires (2026-11-03: 1.9 → 1.4 ms a full-HD frame on the card).
+ /// </summary>
+ private void EnqueueCapture(IntPtr source, int set, IntPtr plane, FrameSnapshot snapshot, bool intensity)
{
FrameShape shape = snapshot.Shape;
+ IntPtr staging = (intensity ? _stagingIntensity : _stagingField)[set];
IntPtr kernel = shape.Format == FrameFormat.Half ? _captureHalfKernel : _captureIndexKernel;
SetMem(kernel, 0U, source);
SetMem(kernel, 1U, staging);
@@ -291,9 +345,22 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
{
SetInt(kernel, 9U, intensity && shape.IntensityRoot ? 1 : 0);
}
- Enqueue(kernel, _captureGrid!, _captureLocal, "capture");
- OpenClApi.Check(OpenClApi.clEnqueueReadBufferPtr(_queue, staging, 0U, IntPtr.Zero, new IntPtr(plane.Length), FrameSnapshot.AddressOf(plane), 0U, IntPtr.Zero, out IntPtr evt), "clEnqueueReadBuffer (capture)");
- snapshot.Events[snapshot.EventCount++] = evt;
+ int planeIndex = intensity ? 1 : 0;
+ IntPtr busy = _stagingBusy[set][planeIndex];
+ IntPtr[]? afterRead = busy != IntPtr.Zero ? [busy] : null;
+ OpenClApi.Check(OpenClApi.clEnqueueNDRangeKernelAfter(_queue, kernel, (uint)_captureGrid!.Length, null, _captureGrid, _captureLocal, (uint)(afterRead?.Length ?? 0), afterRead, out IntPtr captured), "clEnqueueNDRangeKernel (capture)");
+ if (busy != IntPtr.Zero)
+ {
+ Quietly(() => OpenClApi.clReleaseEvent(busy));
+ _stagingBusy[set][planeIndex] = IntPtr.Zero;
+ }
+ OpenClApi.Check(OpenClApi.clFlush(_queue), "clFlush (capture)");
+ OpenClApi.Check(OpenClApi.clEnqueueReadBufferPtrAfter(_transferQueue, staging, 0U, IntPtr.Zero, new IntPtr(snapshot.PlaneBytes), plane, 1U, [captured], out IntPtr read), "clEnqueueReadBuffer (capture)");
+ Quietly(() => OpenClApi.clReleaseEvent(captured));
+ // the snapshot's owner releases its reference in AwaitFrame; the staging set keeps one until the next capture into it
+ OpenClApi.Check(OpenClApi.clRetainEvent(read), "clRetainEvent (capture)");
+ _stagingBusy[set][planeIndex] = read;
+ snapshot.Events[snapshot.EventCount++] = read;
}
/// <inheritdoc/>
@@ -346,6 +413,8 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
OpenClApi.Check(err, "clCreateContext");
_queue = OpenClApi.clCreateCommandQueue(_context, _device.DeviceId, 0UL, ref err);
OpenClApi.Check(err, "clCreateCommandQueue");
+ _transferQueue = OpenClApi.clCreateCommandQueue(_context, _device.DeviceId, 0UL, ref err);
+ OpenClApi.Check(err, "clCreateCommandQueue (transfer)");
_scene.Program = BuildProgram(KernelSource(use4thOrderLaplacian), "the program for the GPU");
// the scene, with a border of one cell like the CPU engine (padded layout)
@@ -1547,6 +1616,41 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
// if this fails the driver is gone or in trouble; release what can be released
Quietly(() => OpenClApi.clFinish(_queue));
}
+ if (_transferQueue != IntPtr.Zero)
+ {
+ Quietly(() => OpenClApi.clFinish(_transferQueue));
+ }
+ foreach (IntPtr[] set in _stagingBusy)
+ {
+ for (int p = 0; p < set.Length; p++)
+ {
+ if (set[p] != IntPtr.Zero)
+ {
+ IntPtr evt = set[p];
+ Quietly(() => OpenClApi.clReleaseEvent(evt));
+ set[p] = IntPtr.Zero;
+ }
+ }
+ }
+ // the snapshots' planes: told first, so a late reader throws instead of reading freed memory
+ foreach (FrameSnapshot snapshot in _hostSnapshots)
+ {
+ snapshot.Release();
+ }
+ _hostSnapshots.Clear();
+ if (_queue != IntPtr.Zero)
+ {
+ foreach ((IntPtr buffer, IntPtr mapped) in _hostPlanes)
+ {
+ Quietly(() => OpenClApi.clEnqueueUnmapMemObject(_queue, buffer, mapped, 0U, IntPtr.Zero, IntPtr.Zero));
+ }
+ Quietly(() => OpenClApi.clFinish(_queue));
+ }
+ foreach ((IntPtr buffer, _) in _hostPlanes)
+ {
+ Quietly(() => OpenClApi.clReleaseMemObject(buffer));
+ }
+ _hostPlanes.Clear();
_probes.Release();
if (_probeProgram != IntPtr.Zero)
{
@@ -1555,6 +1659,11 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
}
_emitters.Release();
_scene.Release();
+ if (_transferQueue != IntPtr.Zero)
+ {
+ Quietly(() => OpenClApi.clReleaseCommandQueue(_transferQueue));
+ _transferQueue = IntPtr.Zero;
+ }
if (_queue != IntPtr.Zero)
{
Quietly(() => OpenClApi.clReleaseCommandQueue(_queue));
@@ -1618,6 +1727,12 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
/// <summary>Steps enqueued between two <c>clFinish</c> calls in <see cref="AdvanceOneStep"/>.</summary>
private const int FinishInterval = 16;
+ /// <summary>The page-locked host buffers behind the snapshots of <see cref="CreateSnapshot"/>, each with its mapping; unmapped and released by <see cref="ReleaseAll"/>.</summary>
+ private readonly List<(IntPtr Buffer, IntPtr Mapped)> _hostPlanes = [];
+
+ /// <summary>The snapshots of <see cref="CreateSnapshot"/>, told by <see cref="ReleaseAll"/> that their planes are gone.</summary>
+ private readonly List<FrameSnapshot> _hostSnapshots = [];
+
/// <summary>Rows (steps) the probe history buffer holds before it must be read back to the host.</summary>
private const int ProbeRows = 2048;
@@ -1682,12 +1797,18 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
private IntPtr _intensityBuffer;
private IntPtr _intensityStage1Buffer;
- /// <summary>Planes the capture kernels write for <see cref="CaptureFrame"/>; created on first use, sized for any shape.</summary>
- private IntPtr _stagingField;
- private IntPtr _stagingIntensity;
+ /// <summary>Two sets of planes the capture kernels write for <see cref="CaptureFrame"/>, taken in turn so a capture never waits for the previous capture's read; created on first use, sized for any shape.</summary>
+ private readonly IntPtr[] _stagingField = new IntPtr[2];
+ private readonly IntPtr[] _stagingIntensity = new IntPtr[2];
private IntPtr _captureHalfKernel;
private IntPtr _captureIndexKernel;
+ /// <summary>The staging set the next capture writes (0 or 1).</summary>
+ private int _stagingSet;
+
+ /// <summary>Per staging set and plane (0 the field, 1 the intensity): the retained event of the read that last left the set, which the next capture into the set waits for; released there or by <see cref="ReleaseAll"/>.</summary>
+ private readonly IntPtr[][] _stagingBusy = [new IntPtr[2], new IntPtr[2]];
+
/// <summary>The shape the capture kernels' geometry arguments are set for, and the matching global work size.</summary>
private FrameShape? _captureShape;
private IntPtr[]? _captureGrid;
@@ -1701,9 +1822,12 @@ public sealed class GpuWaveSimulator : IWaveEngine, IDisposable
/// <summary>OpenCL context on the chosen device; released last in <see cref="ReleaseAll"/>.</summary>
private IntPtr _context;
- /// <summary>In-order command queue; every launch and transfer goes through it.</summary>
+ /// <summary>In-order command queue; every launch and the blocking transfers go through it, the captures' reads through <see cref="_transferQueue"/>.</summary>
private IntPtr _queue;
+ /// <summary>In-order queue for the captures' reads (<see cref="EnqueueCapture"/>): on a queue of their own the DMA transfers overlap the steps on <see cref="_queue"/>, ordered against them by events.</summary>
+ private IntPtr _transferQueue;
+
/// <summary>Simulation program (<c>wave_step</c>, <c>apply_sources</c>, <c>apply_object_sources</c>) with its kernels and scene buffers.</summary>
private readonly Resources _scene = new Resources();
diff --git a/WaveDudeNext/Engine/IWaveEngine.cs b/WaveDudeNext/Engine/IWaveEngine.cs
index f7cfae2..9868c71 100644
--- a/WaveDudeNext/Engine/IWaveEngine.cs
+++ b/WaveDudeNext/Engine/IWaveEngine.cs
@@ -69,13 +69,27 @@ public interface IWaveEngine
/// </summary>
void PrepareFrame(bool needField, bool needIntensity);
+ /// <summary>
+ /// A snapshot for <see cref="CaptureFrame"/> in the memory this engine fills fastest. The GPU engine's planes are
+ /// page-locked host memory (<c>CL_MEM_ALLOC_HOST_PTR</c> buffers, kept mapped) the card writes by DMA while the
+ /// stepping thread goes on; into an ordinary snapshot's arrays, pageable to the driver, its "non-blocking" read
+ /// drains the queue and copies on the calling thread (2.96 against 1.91 ms a full-HD frame, both planes as halves,
+ /// RTX 2080, 2026-11-03). The CPU engine returns an ordinary snapshot. Engine-owned planes are released with the
+ /// engine and throw afterwards, so a snapshot that outlives its engine, the scratch runner's result, is made with
+ /// the constructor instead.
+ /// </summary>
+ /// <param name="shape">The capture's geometry and format; its canvas must be this engine's.</param>
+ /// <param name="withIntensity">Whether the snapshot gets an intensity plane.</param>
+ FrameSnapshot CreateSnapshot(FrameShape shape, bool withIntensity);
+
/// <summary>
/// Copies the newest field (and the intensity when asked and tracked) into <paramref name="snapshot"/> as
/// planes of its <see cref="FrameShape"/>: the padding stripped, the canvas shrunk by the shape's divisor,
/// the samples as halves or palette indices (<see cref="FrameConversion"/> is the reference). The CPU engine
/// copies the floats now and converts in <see cref="AwaitFrame"/>; the GPU engine converts on the card and
- /// enqueues the reads without waiting, so the driver can keep stepping while they land. The snapshot must not
- /// be touched until <see cref="AwaitFrame"/> returned, and a capture must be awaited before the engine is disposed.
+ /// enqueues the reads without waiting, so the driver can keep stepping while they land into a snapshot of
+ /// <see cref="CreateSnapshot"/> (an ordinary snapshot's read stalls the stepping thread for the copy). The snapshot
+ /// must not be touched until <see cref="AwaitFrame"/> returned, and a capture must be awaited before the engine is disposed.
/// </summary>
/// <param name="snapshot">A snapshot whose shape has this engine's canvas; its planes receive the data.</param>
/// <param name="needIntensity">Also copy the intensity (needs tracking and a snapshot with an intensity plane).</param>
diff --git a/WaveDudeNext/Engine/OpenClApi.cs b/WaveDudeNext/Engine/OpenClApi.cs
index 3f4dcc9..c6ce6a7 100644
--- a/WaveDudeNext/Engine/OpenClApi.cs
+++ b/WaveDudeNext/Engine/OpenClApi.cs
@@ -112,6 +112,18 @@ internal static class OpenClApi
[DllImport("OpenCL", CharSet = CharSet.Ansi, EntryPoint = "clEnqueueReadBuffer", ExactSpelling = true, SetLastError = true)]
internal static extern int clEnqueueReadBufferPtr(IntPtr queue, IntPtr buffer, uint blocking, IntPtr offset, IntPtr size, IntPtr ptr, uint numEvents, IntPtr waitList, out IntPtr evt);
+ /// <summary>clEnqueueReadBuffer into pinned or page-locked memory at <paramref name="ptr"/> after the events in <paramref name="waitList"/> (<paramref name="numEvents"/> of them, from any queue of the context, each flushed from its own); non-blocking when <paramref name="blocking"/> is 0; <paramref name="evt"/> receives the read's event.</summary>
+ [DllImport("OpenCL", CharSet = CharSet.Ansi, EntryPoint = "clEnqueueReadBuffer", ExactSpelling = true, SetLastError = true)]
+ internal static extern int clEnqueueReadBufferPtrAfter(IntPtr queue, IntPtr buffer, uint blocking, IntPtr offset, IntPtr size, IntPtr ptr, uint numEvents, IntPtr[] waitList, out IntPtr evt);
+
+ /// <summary>clEnqueueMapBuffer: maps <paramref name="size"/> bytes of a buffer from <paramref name="offset"/> into host memory and returns the pointer; <paramref name="blocking"/> 1 waits for the mapping. A buffer created with <see cref="MemAllocHostPtr"/> maps to the page-locked memory it lives in, so the pointer takes DMA transfers (<see cref="clEnqueueReadBufferPtr"/>) for as long as the mapping stays. End it with <see cref="clEnqueueUnmapMemObject"/>.</summary>
+ [DllImport("OpenCL", CharSet = CharSet.Ansi, ExactSpelling = true, SetLastError = true)]
+ internal static extern IntPtr clEnqueueMapBuffer(IntPtr queue, IntPtr buffer, uint blocking, ulong mapFlags, IntPtr offset, IntPtr size, uint numEvents, IntPtr waitList, IntPtr evt, ref int errcode);
+
+ /// <summary>clEnqueueUnmapMemObject: ends a mapping made by <see cref="clEnqueueMapBuffer"/>; complete once the queue has run it (<see cref="clFinish"/>).</summary>
+ [DllImport("OpenCL", CharSet = CharSet.Ansi, ExactSpelling = true, SetLastError = true)]
+ internal static extern int clEnqueueUnmapMemObject(IntPtr queue, IntPtr memObj, IntPtr mappedPtr, uint numEvents, IntPtr waitList, IntPtr evt);
+
/// <summary>clWaitForEvents: blocks until every event in <paramref name="events"/> has completed.</summary>
[DllImport("OpenCL", CharSet = CharSet.Ansi, ExactSpelling = true, SetLastError = true)]
internal static extern int clWaitForEvents(uint numEvents, IntPtr[] events);
@@ -120,10 +132,22 @@ internal static class OpenClApi
[DllImport("OpenCL", CharSet = CharSet.Ansi, ExactSpelling = true, SetLastError = true)]
internal static extern int clReleaseEvent(IntPtr evt);
+ /// <summary>clRetainEvent: adds a reference to an event, for a second owner that releases it on its own.</summary>
+ [DllImport("OpenCL", CharSet = CharSet.Ansi, ExactSpelling = true, SetLastError = true)]
+ internal static extern int clRetainEvent(IntPtr evt);
+
+ /// <summary>clEnqueueNDRangeKernel that waits for the events in <paramref name="waitList"/> (<paramref name="numEvents"/> of them, from any queue of the context, each flushed from its own; null for none) and returns the launch's event in <paramref name="evt"/>; otherwise as <see cref="clEnqueueNDRangeKernel"/>.</summary>
+ [DllImport("OpenCL", CharSet = CharSet.Ansi, EntryPoint = "clEnqueueNDRangeKernel", ExactSpelling = true, SetLastError = true)]
+ internal static extern int clEnqueueNDRangeKernelAfter(IntPtr queue, IntPtr kernel, uint workDim, IntPtr[]? globalOffset, IntPtr[] globalSize, IntPtr[]? localSize, uint numEvents, IntPtr[]? waitList, out IntPtr evt);
+
/// <summary>clEnqueueNDRangeKernel: launches the kernel over a <paramref name="workDim"/>-dimensional range; <paramref name="localSize"/> null lets the driver pick the work-group size, which then has to divide <paramref name="globalSize"/> exactly.</summary>
[DllImport("OpenCL", CharSet = CharSet.Ansi, ExactSpelling = true, SetLastError = true)]
internal static extern int clEnqueueNDRangeKernel(IntPtr queue, IntPtr kernel, uint workDim, IntPtr[]? globalOffset, IntPtr[] globalSize, IntPtr[]? localSize, uint numEvents, IntPtr waitList, IntPtr evt);
+ /// <summary>clFlush: submits every command queued so far to the device without waiting; a driver may otherwise hold a small batch back until a blocking call.</summary>
+ [DllImport("OpenCL", CharSet = CharSet.Ansi, ExactSpelling = true, SetLastError = true)]
+ internal static extern int clFlush(IntPtr queue);
+
/// <summary>clFinish: blocks until every command queued so far has completed.</summary>
[DllImport("OpenCL", CharSet = CharSet.Ansi, ExactSpelling = true, SetLastError = true)]
internal static extern int clFinish(IntPtr queue);
@@ -365,6 +389,12 @@ internal static class OpenClApi
/// <summary>CL_MEM_READ_WRITE (1 &lt;&lt; 0) buffer flag.</summary>
internal const ulong MemReadWrite = 1UL;
+ /// <summary>CL_MEM_ALLOC_HOST_PTR (1 &lt;&lt; 4) buffer flag: the buffer lives in host memory the driver page-locks, so copies between it and the card are DMA transfers.</summary>
+ internal const ulong MemAllocHostPtr = 16UL;
+
+ /// <summary>CL_MAP_READ | CL_MAP_WRITE (1 &lt;&lt; 0 | 1 &lt;&lt; 1): <see cref="clEnqueueMapBuffer"/> flags for a mapping the host both reads and writes.</summary>
+ internal const ulong MapReadWrite = 3UL;
+
/// <summary>CL_CONTEXT_PLATFORM (0x1084): property key for the platform in <see cref="clCreateContext"/>.</summary>
internal const int ContextPlatformProperty = 0x1084;
diff --git a/WaveDudeNext/Engine/WaveSimulator.cs b/WaveDudeNext/Engine/WaveSimulator.cs
index a97ff61..f67e17a 100644
--- a/WaveDudeNext/Engine/WaveSimulator.cs
+++ b/WaveDudeNext/Engine/WaveSimulator.cs
@@ -236,6 +236,9 @@ public sealed class WaveSimulator : IWaveEngine, IDisposable
SetProbes(null);
}
+ /// <summary>An ordinary snapshot (pinned arrays): the CPU converts into it on the awaiting thread, and no memory is faster for that.</summary>
+ public FrameSnapshot CreateSnapshot(FrameShape shape, bool withIntensity) => new(shape, withIntensity);
+
/// <summary>
/// Copies the interior of the current buffers into the snapshot's float staging (a plain memory copy, so the
/// stepping thread loses little); <see cref="AwaitFrame"/> converts to <see cref="Half"/> on the thread that awaits.
@@ -249,7 +252,7 @@ public sealed class WaveSimulator : IWaveEngine, IDisposable
int cells = _canvasWidth * _canvasHeight;
snapshot.FieldFloats ??= new float[cells];
CopyInterior(_u, snapshot.FieldFloats);
- snapshot.HasIntensity = needIntensity && _intensityOut != null && snapshot.IntensityBytes != null;
+ snapshot.HasIntensity = needIntensity && _intensityOut != null && snapshot.HasIntensityPlane;
if (snapshot.HasIntensity)
{
snapshot.IntensityFloats ??= new float[cells];
@@ -267,10 +270,10 @@ public sealed class WaveSimulator : IWaveEngine, IDisposable
}
snapshot.PendingConversion = false;
// the shape's shrinking and format (FrameConversion), on the awaiting thread
- FrameConversion.Convert(snapshot.FieldFloats!, 0, _canvasWidth, snapshot.Shape, false, snapshot.FieldBytes);
+ FrameConversion.Convert(snapshot.FieldFloats!, 0, _canvasWidth, snapshot.Shape, false, snapshot.FieldMemory);
if (snapshot.HasIntensity)
{
- FrameConversion.Convert(snapshot.IntensityFloats!, 0, _canvasWidth, snapshot.Shape, true, snapshot.IntensityBytes!);
+ FrameConversion.Convert(snapshot.IntensityFloats!, 0, _canvasWidth, snapshot.Shape, true, snapshot.IntensityMemory);
}
}
diff --git a/WaveDudeNext/Runs/FrameStore.cs b/WaveDudeNext/Runs/FrameStore.cs
index ee4edcc..c4aad0f 100644
--- a/WaveDudeNext/Runs/FrameStore.cs
+++ b/WaveDudeNext/Runs/FrameStore.cs
@@ -117,7 +117,7 @@ public sealed unsafe class FrameStore : IFrameSource, IDisposable
/// <summary>
/// The background producer of memory blocks: allocates one per frame of the memory tier, touches every page
- /// so the writer never takes a page fault, and queues it, at most <see cref="PrepareDepth"/> ahead. Allocates
+ /// so the writer never takes a page fault (<see cref="TouchPages"/>), and queues it, at most <see cref="PrepareDepth"/> ahead. Allocates
/// nothing before the memory the budget counts on is released (<see cref="_memoryReleased"/>, the outgoing run's
/// store; 2026-10-16: the budget had counted it as free while the old store still held it, a race of tens of
/// milliseconds that a machine at its commit limit lost). Ends when every block is made, the store is disposed,
@@ -154,11 +154,7 @@ public sealed unsafe class FrameStore : IFrameSource, IDisposable
{
break;
}
- byte* bytes = (byte*)block;
- for (long offset = 0; offset < FrameBytes; offset += PageSize)
- {
- bytes[offset] = 0;
- }
+ TouchPages((IntPtr)block, FrameBytes);
try
{
_prepared.Add((IntPtr)block, token);
@@ -373,6 +369,11 @@ public sealed unsafe class FrameStore : IFrameSource, IDisposable
}
else
{
+ // one plain copy, 1.2 ms for a full-HD frame on one core, and the clock of a 16-bit run in RAM against the card's
+ // 1.3 ms a frame. Every faster copy lost in a run (2026-11-03, measured in the app): chunks on the thread pool
+ // queued behind the presenter's rendering rows; two or four dedicated threads, at normal or above-normal
+ // priority, copied faster but slowed the card's DMA into host memory by more than they gained, the memory bus
+ // being shared with it, the producer's page zeroing and the presenter
if (Has(FrameLayer.Field))
{
field[..length].CopyTo(Plane(memory, FrameLayer.Field));
@@ -412,7 +413,7 @@ public sealed unsafe class FrameStore : IFrameSource, IDisposable
{
throw new ArgumentException("The snapshot does not match the store's size or format.", nameof(snapshot));
}
- Write(frame, snapshot.FieldBytes, snapshot.HasIntensity ? snapshot.IntensityBytes : null);
+ Write(frame, snapshot.FieldBytes, snapshot.HasIntensity ? snapshot.IntensityBytes : Span<byte>.Empty);
}
/// <summary>Reads one plane as <see cref="Half"/> values; the store's samples must be halves (<see cref="Format"/>). See <see cref="CopyLayer(int, FrameLayer, Span{byte})"/>.</summary>
@@ -535,6 +536,37 @@ public sealed unsafe class FrameStore : IFrameSource, IDisposable
private Span<byte> Plane(void* frameMemory, FrameLayer layer) =>
new((byte*)frameMemory + PlaneIndex(layer) * PlaneBytes, (int)PlaneBytes);
+ /// <summary>
+ /// Writes one byte per page of a fresh block, so the writer never takes a page fault, on up to four cores: Windows
+ /// hands out and zeroes the pages at 5 GB/s for one thread, 1.7 ms for a full-HD frame's block, which had been the
+ /// clock of a run that fits RAM ahead of the writer's copy (2026-11-03); four threads make it 0.6 ms, eight gain
+ /// nothing more. A block under four megabytes is touched on the calling thread.
+ /// </summary>
+ private static void TouchPages(IntPtr block, long bytes)
+ {
+ long pages = (bytes + PageSize - 1) / PageSize;
+ int threads = bytes < 4L << 20 ? 1 : Math.Min(Environment.ProcessorCount, 4);
+ if (threads < 2)
+ {
+ byte* single = (byte*)block;
+ for (long page = 0; page < pages; page++)
+ {
+ single[page * PageSize] = 0;
+ }
+ return;
+ }
+ long perThread = (pages + threads - 1) / threads;
+ Parallel.For(0, threads, new ParallelOptions { MaxDegreeOfParallelism = threads }, t =>
+ {
+ byte* bytes = (byte*)block;
+ long last = Math.Min(pages, (t + 1) * perThread);
+ for (long page = t * perThread; page < last; page++)
+ {
+ bytes[page * PageSize] = 0;
+ }
+ });
+ }
+
/// <summary>The <see cref="Half"/> overloads only apply to a store of halves.</summary>
/// <exception cref="InvalidOperationException">The store's samples are palette indices.</exception>
private void RequireHalves()
diff --git a/WaveDudeNext/Runs/IFrameSource.cs b/WaveDudeNext/Runs/IFrameSource.cs
index fc320a2..d7173b8 100644
--- a/WaveDudeNext/Runs/IFrameSource.cs
+++ b/WaveDudeNext/Runs/IFrameSource.cs
@@ -91,12 +91,11 @@ public sealed class SnapshotFrameSource(FrameSnapshot snapshot) : IFrameSource
/// <inheritdoc/>
public bool CopyLayer(int frame, FrameLayer layer, Span<byte> destination)
{
- byte[]? plane = layer == FrameLayer.Field ? Snapshot.FieldBytes : Snapshot.HasIntensity ? Snapshot.IntensityBytes : null;
- if (plane == null)
+ if (layer != FrameLayer.Field && !Snapshot.HasIntensity)
{
return false;
}
- plane.AsSpan().CopyTo(destination);
+ (layer == FrameLayer.Field ? Snapshot.FieldBytes : Snapshot.IntensityBytes).CopyTo(destination);
return true;
}
diff --git a/WaveDudeNext/Runs/ScratchRunner.cs b/WaveDudeNext/Runs/ScratchRunner.cs
index 3e56c44..34c042a 100644
--- a/WaveDudeNext/Runs/ScratchRunner.cs
+++ b/WaveDudeNext/Runs/ScratchRunner.cs
@@ -237,8 +237,9 @@ public sealed class ScratchRunner : IDisposable
int index = _nextSnapshot;
_nextSnapshot = (index + 1) % _snapshots.Length;
FrameSnapshot? snapshot = _snapshots[index];
- if (snapshot == null || snapshot.Shape != spec.Shape || (spec.TrackIntensity && snapshot.IntensityBytes == null))
+ if (snapshot == null || snapshot.Shape != spec.Shape || (spec.TrackIntensity && !snapshot.HasIntensityPlane))
{
+ // ordinary snapshots, not the engine's: the result handed out outlives the engine, which a scene edit replaces
snapshot = _snapshots[index] = new FrameSnapshot(spec.Shape, spec.TrackIntensity);
}
return snapshot;
diff --git a/WaveDudeNext/Runs/SimulationRun.cs b/WaveDudeNext/Runs/SimulationRun.cs
index bbc0126..d3bb248 100644
--- a/WaveDudeNext/Runs/SimulationRun.cs
+++ b/WaveDudeNext/Runs/SimulationRun.cs
@@ -33,8 +33,8 @@ namespace WaveDudeNext.Runs;
/// and the store allow, and the preview plays from the store at its own speed.
/// </summary>
/// <remarks>
-/// Threads: the worker owns the engine's stepping; it captures frames (on the GPU an asynchronous read into a
-/// pinned snapshot) and hands them to the writer task, which awaits the capture, writes the store and returns
+/// Threads: the worker owns the engine's stepping; it captures frames (on the GPU a DMA read into a snapshot the engine
+/// made in page-locked memory) and hands them to the writer task, which awaits the capture, writes the store and returns
/// the snapshot to a small pool, so converting and storing one frame overlaps computing the next. Every public
/// property and event is set or raised through the <see cref="SynchronizationContext"/> given to the constructor
/// (the WPF dispatcher), so they can be bound directly; with a null context they run on the worker (for
@@ -280,7 +280,8 @@ public sealed class SimulationRun : INotifyPropertyChanged, IDisposable
var pool = new BlockingCollection<FrameSnapshot>();
for (int i = 0; i < SnapshotPoolSize; i++)
{
- pool.Add(new FrameSnapshot(Spec.Shape, trackIntensity));
+ // the engine's own snapshots: page-locked on the GPU, so its reads are DMA the stepping thread does not wait for (2026-11-03)
+ pool.Add(engine.CreateSnapshot(Spec.Shape, trackIntensity));
}
var pending = new BlockingCollection<FrameSnapshot>();
IWaveEngine captured = engine;
diff --git a/_tools/library_check/Program.cs b/_tools/library_check/Program.cs
index 8b2b8e2..8d28a29 100644
--- a/_tools/library_check/Program.cs
+++ b/_tools/library_check/Program.cs
@@ -897,7 +897,8 @@ internal static class Program
}
double withReadback = clock.Elapsed.TotalMilliseconds / steps;
// the run's pattern: capture into a pool of snapshots, await one frame late
- var snapshots = new[] { new FrameSnapshot(engine.Width, engine.Height, true), new FrameSnapshot(engine.Width, engine.Height, true), new FrameSnapshot(engine.Width, engine.Height, true) };
+ FrameShape full = FrameShape.Full(engine.Width, engine.Height);
+ var snapshots = new[] { engine.CreateSnapshot(full, true), engine.CreateSnapshot(full, true), engine.CreateSnapshot(full, true) };
int next = 0;
clock.Restart();
for (int i = 0; i < steps; i++)
@@ -1023,8 +1024,8 @@ internal static class Program
{
continue;
}
- var a = new FrameSnapshot(W, H, true);
- var b = new FrameSnapshot(W, H, true);
+ var a = engine.CreateSnapshot(FrameShape.Full(W, H), true);
+ var b = engine.CreateSnapshot(FrameShape.Full(W, H), true);
Run(engine, 100);
engine.CaptureFrame(a, true);
// keep stepping before awaiting: the capture must still show step 100
@@ -1059,7 +1060,27 @@ internal static class Program
engine.CaptureFrame(a, false);
engine.AwaitFrame(a);
Check(MaxDiff(at100, engine.Stride, W, H, a.Field) < tolerance, name + ": emitters restored, original field again");
+ // the engine's own snapshot (page-locked host memory on the GPU, 2026-11-03) and an ordinary one capture the same
+ // bytes; the engine's planes go with the engine, an ordinary one's stay
+ var plain = new FrameSnapshot(FrameShape.Full(W, H), true);
+ engine.CaptureFrame(a, true);
+ engine.CaptureFrame(plain, true);
+ engine.AwaitFrame(a);
+ engine.AwaitFrame(plain);
+ Check(a.HasIntensity && a.FieldBytes.SequenceEqual(plain.FieldBytes) && a.IntensityBytes.SequenceEqual(plain.IntensityBytes),
+ name + ": the engine's snapshot and an ordinary one capture the same bytes");
(engine as IDisposable)?.Dispose();
+ bool gone = false;
+ try
+ {
+ _ = a.FieldBytes.Length;
+ }
+ catch (ObjectDisposedException)
+ {
+ gone = true;
+ }
+ Check(gone == (engine is GpuWaveSimulator) && plain.FieldBytes.Length == FrameShape.Full(W, H).PlaneBytes,
+ name + ": " + (gone ? "the engine's snapshot is released with the engine" : "the snapshot outlives the engine") + ", an ordinary one stays readable");
}
}
@@ -1395,8 +1416,8 @@ internal static class Program
FrameShape full = FrameShape.Full(cw, ch);
FrameShape index = full with { Format = FrameFormat.Index, FieldBrightness = 30f, IntensityBrightness = 5f };
int origin = (rim + 1) * cpu.Stride + rim + 1;
- var halves = new FrameSnapshot(full, true);
- var indices = new FrameSnapshot(index, true);
+ var halves = gpu.CreateSnapshot(full, true);
+ var indices = gpu.CreateSnapshot(index, true);
gpu.CaptureFrame(halves, true);
gpu.CaptureFrame(indices, true);
gpu.AwaitFrame(halves);
@@ -1418,7 +1439,7 @@ internal static class Program
for (int i = 0; i < cw * ch; i++)
{
fieldOff += Math.Abs(indexField[i] - indices.FieldBytes[i]) > 1 ? 1 : 0;
- intenOff += Math.Abs(indexInten[i] - indices.IntensityBytes![i]) > 1 ? 1 : 0;
+ intenOff += Math.Abs(indexInten[i] - indices.IntensityBytes[i]) > 1 ? 1 : 0;
}
Check(fieldOff == 0 && intenOff == 0, "the 8-bit capture of the prime canvas is within a palette step of the CPU's, field and intensity (" + fieldOff + " / " + intenOff + " cells off)");
}
@@ -1686,7 +1707,11 @@ internal static class Program
big.CopyLayer(frame, FrameLayer.Intensity, plane);
}
double readMs = clock.Elapsed.TotalMilliseconds;
- Check(plane[0] == (Half)bigIntensity[(bigW + 2) + 1] && plane[bigW * bigH - 1] == (Half)bigIntensity[bigH * (bigW + 2) + bigW], "big store reads back what was written");
+ // every sample of both planes of the last frame: the copier's chunks (2026-11-03) must join up exactly
+ big.CopyLayer(bigFrames - 1, FrameLayer.Field, plane);
+ bool fieldSame = plane.AsSpan().SequenceEqual(bigFieldHalf);
+ big.CopyLayer(bigFrames - 1, FrameLayer.Intensity, plane);
+ Check(fieldSame && plane.AsSpan().SequenceEqual(bigIntensityHalf), "big store reads back what was written, every sample of both planes");
clock.Restart();
big.Dispose();
double disposeMs = clock.Elapsed.TotalMilliseconds;
@@ -1825,10 +1850,10 @@ internal static class Program
var expectedInten = new byte[shape.PlaneBytes];
FrameConversion.Convert(field, stride + 1, stride, shape, false, expectedField);
FrameConversion.Convert(inten, stride + 1, stride, shape, true, expectedInten);
- var snapshot = new FrameSnapshot(shape, true);
+ var snapshot = cpu.CreateSnapshot(shape, true);
cpu.CaptureFrame(snapshot, true);
cpu.AwaitFrame(snapshot);
- Check(snapshot.HasIntensity && snapshot.FieldBytes.AsSpan().SequenceEqual(expectedField) && snapshot.IntensityBytes!.AsSpan().SequenceEqual(expectedInten),
+ Check(snapshot.HasIntensity && snapshot.FieldBytes.SequenceEqual(expectedField) && snapshot.IntensityBytes.SequenceEqual(expectedInten),
$"CPU capture of 1/{shape.Divisor} {shape.Format}{(shape.IntensityRoot ? "" : ", the intensity as I")} equals the reference conversion");
}
// the GPU's: halves within the tolerance, indices exact where the card's square root rounds correctly (within one elsewhere)
@@ -1851,7 +1876,7 @@ internal static class Program
var expectedInten = new byte[shape.PlaneBytes];
FrameConversion.Convert(gpuField, stride + 1, stride, shape, false, expectedField);
FrameConversion.Convert(gpuInten, stride + 1, stride, shape, true, expectedInten);
- var snapshot = new FrameSnapshot(shape, true);
+ var snapshot = gpu.CreateSnapshot(shape, true);
gpu.CaptureFrame(snapshot, true);
gpu.AwaitFrame(snapshot);
int worstIndex = 0;
@@ -1860,7 +1885,7 @@ internal static class Program
{
for (int i = 0; i < expectedField.Length; i++)
{
- worstIndex = Math.Max(worstIndex, Math.Max(Math.Abs(snapshot.FieldBytes[i] - expectedField[i]), Math.Abs(snapshot.IntensityBytes![i] - expectedInten[i])));
+ worstIndex = Math.Max(worstIndex, Math.Max(Math.Abs(snapshot.FieldBytes[i] - expectedField[i]), Math.Abs(snapshot.IntensityBytes[i] - expectedInten[i])));
}
}
else
@@ -2002,7 +2027,7 @@ internal static class Program
arrived.Set();
};
scratch.Request(spec, 98);
- Check(arrived.Wait(30000) && result is { Snapshot: not null, Frame: 98 } && result.Snapshot.Shape == spec.Shape && result.Snapshot.FieldBytes.AsSpan().SequenceEqual(expected.FieldBytes),
+ Check(arrived.Wait(30000) && result is { Snapshot: not null, Frame: 98 } && result.Snapshot.Shape == spec.Shape && result.Snapshot.FieldBytes.SequenceEqual(expected.FieldBytes),
"a scratch frame 98 in that quality has the spec's shape and the stored bytes (the scratch always computes the exact timeline frame)");
}
run.Dispose();