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#

Two-tier frame store: frames in memory up to a budget, a file only for the rest

Alexander Graef1d7318eb09e1
diff --git a/CLAUDE.md b/CLAUDE.md
index 210e222..b3b3835 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -509,21 +509,28 @@ FrameStore (temporary file in %LOCALAPPDATA%\WaveDude\cache, DeleteOnClose, pre-
- **Frames vs. steps**: a frame is recorded after step `i` when `i % VisualizeEvery == 0`, so frame
k shows the state after 0-based step `k × VisualizeEvery` (what the readout's `step` prints);
`RunSpec.FrameCount = ceil(Steps / VisualizeEvery)`, the same as `FrameCountConverter`.
-- **FrameStore**: 64-byte header (`WDFS`, version, width, height, layers, every, capacity) then
- fixed-size frames, planes in `FrameLayer` order, only those present (`RunSpec.Layers`: field
- always; intensity when the intensity preview or export is on or a probe needs it). The worker
- writes in order (`RandomAccess.Write` of a vectorised Half staging buffer) and publishes `Count`;
- readers use `CopyLayer` (`RandomAccess.Read`; safe against a concurrent `Dispose`, which waits for
- readers). **Not memory-mapped, on purpose** (2026-10-09): the first version mapped the file and
- touching 16 MB of fresh pages per frame cost 14-20 ms per frame on the writer and about as much
- on the reader, and unmapping flushed every dirty page to disk (a minute-long freeze on the second
- run and on closing, for a 10 GB file about to be deleted). Size: a 1920×1080 run of 2500 steps at
- `VisualizeEvery` 2 with both planes is **10.4 GB** on disk (`FrameStore.SizeOf`;
- `FrameCache.CheckSpace` refuses with the number when the drive lacks it); the file is marked
- `Temporary` so the cache manager keeps it in RAM while it can. It is deleted on dispose/exit/crash
- (`DeleteOnClose`); `FrameCache.Sweep` at start-up removes leftovers; the window disposes a store
- on the thread pool, never on the UI thread, and `Dispose` closes the file outside the store's lock
- (deleting 10 GB takes a second; a reader gets false instead of waiting). When a run is replaced the
+- **FrameStore, two tiers** (2026-10-14): the first frames of a run, as many as the memory budget holds
+ (`RamFrames`), live in native memory (`NativeMemory.Alloc` per frame, one block of all planes); the
+ rest go to a temporary file created only when the run does not fit (`FirstSpilledFrame`, `HasFile`),
+ pre-sized for the spilled frames, 64-byte header (`WDFS`, version 2, width, height, layers, every,
+ capacity, first frame in the file) then fixed-size frames, planes in `FrameLayer` order, only those
+ present (`RunSpec.Layers`: field always; intensity when the intensity preview or export is on or a
+ probe needs it). The budget is `FrameMemory.Budget(percent)`: the user's share of the physical RAM
+ (Simulation > Frames kept in memory: a quarter, half, three quarters; setting `FrameMemoryPercent`,
+ default 50) capped by what `GlobalMemoryStatusEx` says is free now minus a 2 GB margin, so a run never
+ pushes the machine into its page file; the window logs frames in memory and on disk with the run start,
+ and `FrameCache.CheckSpace` is only asked for the spilled part. An allocation that fails after all (the
+ commit limit) sends that frame and the rest to the file, noted once. The worker writes in order and
+ publishes `Count`; readers use `CopyLayer` (a memory copy, or `RandomAccess.Read`; safe against a
+ concurrent `Dispose`, which frees the memory under the lock and closes the file outside it).
+ **Why not the OS cache or a memory mapping** (2026-10-09 and 2026-10-14): both keep dirty pages only up
+ to the memory manager's own allowance and then write at disk speed whatever `FILE_ATTRIBUTE_TEMPORARY`
+ says (the 10.4 GB full-HD run took 14 s against the drive with 40 GB of RAM free, and the user's drive
+ was thrashed on every automatic re-run); a mapping also cost 14-20 ms per frame in page faults on both
+ sides and flushed everything on unmap (a minute-long freeze). Size: a 1920×1080 run of 2500 steps at
+ `VisualizeEvery` 2 with both planes is **10.4 GB**, in RAM here. The file is deleted on
+ dispose/exit/crash (`DeleteOnClose`); `FrameCache.Sweep` at start-up removes leftovers; the window
+ disposes a store on the thread pool, never on the UI thread. When a run is replaced the
window drops `Run` before clearing the stale flag, so the preview never falls back to the old store
for a moment (that showed the old frame for a second after every edit, 2026-10-09).
- **Numbers (RTX 2080, 64 GB RAM, SATA SSD RAID, Debug build, 2026-10-09)**, from
@@ -533,12 +540,14 @@ FrameStore (temporary file in %LOCALAPPDATA%\WaveDude\cache, DeleteOnClose, pre-
| pure stepping | 0.25 ms | 0.5 ms | 6 ms |
| with pipelined half captures every 2 steps | 1.3 ms | 1.6 ms | 13 ms |
| GPU engine build (OpenCL compile) | 230–300 ms | | CPU build 10 ms |
- The stored full-HD run (2500 steps, 1250 frames, 10.4 GB) still takes **14 s**: the stepping thread
- waits for free snapshots because the writer stores at ~11 ms per frame, which is the disk. Windows
- throttles a process whose dirty cache pages outrun the drive, so a store larger than the cache's
- allowance runs at disk speed whatever the code does (a 1 GB store writes at 600–1100 MB/s). The
- fix, if wanted: a RAM-first store with an explicit budget that spills to the file in the
- background (64 GB here would hold the whole run), or fewer bytes (`VisualizeEvery`, resolution).
+ The stored full-HD run (2500 steps, 1250 frames, 10.4 GB) took **14 s** while the store was a file:
+ the stepping thread waited for free snapshots because the writer stored at ~11 ms per frame, which
+ was the disk (Windows throttles a process whose dirty cache pages outrun the drive). Since the
+ two-tier store (2026-10-14) the same run takes **5.4 s** in RAM: 0.17 s stepping, 1.8 ms per frame
+ storing (a memory copy into a block the store's producer allocated and touched ahead of the writer;
+ the harness writes a 1 GB store at 1.4 ms per frame, 6 GB/s), and the rest is the stepping thread
+ waiting for free snapshots, i.e. the GPU readback of ~4 ms per capture on the in-order queue. The next
+ bottleneck is that readback (a second OpenCL queue, below), not the store.
A second OpenCL queue would overlap the 4 ms readback with compute (today an in-order queue
serialises them). The presenter costs ~22 ms per presented frame, so playback at 60 fps skips
frames at 1080p (the clock stays correct; only the newest request is rendered).
@@ -549,7 +558,8 @@ FrameStore (temporary file in %LOCALAPPDATA%\WaveDude\cache, DeleteOnClose, pre-
at least 50 steps; a request with no measurement yet always computes). Frames early in the run are proportionally cheaper (frame 0: 90 ms including
the capture and the UI round trip).
- Known limits: the probe signal lane under the timeline is not drawn yet (the graph boxes are, 2026-10-14);
- export is not wired; `OpenClApi` imports `"OpenCL"` (resolves to `OpenCL.dll` here, `libOpenCL.so` elsewhere).
+ `OpenClApi` imports `"OpenCL"` (resolves to `OpenCL.dll` here, `libOpenCL.so` elsewhere); the library is
+ compiled with `AllowUnsafeBlocks` for the MP4 writer's buffer copy.
The library is compiled with `<Optimize>true</Optimize>` in every configuration (2026-10-10): a
Debug build of it ran the CPU engine's stencil loop at 33 ms per full-HD step instead of 14, which
made the CPU preview unusable from the app. Flip it locally to step through engine code. The
@@ -740,24 +750,10 @@ PreviewCheck 12 s, LanguageCheck 17 s, `library_check` about 20 s). The next ses
traces (`ProbeGraph.ComputeRanges` and its binning can be reused), and the box in exports (the layout is
renderer-neutral; a `DrawingVisual` rendered into the frame would do). Author's point 7, second half.
-**Export (nothing wired).**
-- Frames: `FrameStore.CopyLayer(frame, layer, Span<Half>)` of a run (finished, or after
- `Run.Completion`), rendered with `FrameRenderer.RenderField/RenderIntensity` and the layer's LUT
- (`ColorSchemeCatalog.LutFor(project, name, blackLevel)`, brightness), then, per layer and only when
- `DisplayLayer.OverlayInExport`, `GlowingEdges.BlendAdditive` with the layer's `OverlayGain` (the
- author bakes the outline additively; the preview only composites it). Range:
- `Display.ExportFrom/ExportTo` in **steps** (0 = start/end), one frame per `VisualizeEvery` steps.
- Which outputs: `DisplayLayer.Export`. Encoder settings: `Video.Fps`, `Video.Quality`.
-- Writers: none in the library yet; the legacy `Wave_Dude_2D/MfVideoWriter.cs` (+ `IMF*Native`,
- Media Foundation SinkWriter, .mp4) and `AviMjpegWriter.cs` (MJPEG fallback, spec-exact, see
- `_tools/avi_check`) compile anywhere and were listed as movable as-is; stills can use WPF's
- `PngBitmapEncoder` on the rendered `int[]`. The author names exports with a running number
- (`_0001`, one above the highest in the folder) and stores them next to the project; the user told
- him output goes relative to the project file (the folder of `Filename`; an unsaved project must be
- saved first, like `RunErrorUnsavedImagePath`).
-- Needs: a progress item (status text only today), cancellation, a menu entry (Simulation or File),
- and a decision whether export needs a finished run (simplest: export the frames that exist).
- Author's point 10.
+**Export (done 2026-10-14, see "Export" in the WPF shell list).** Formats, menus, run-first, probe boxes,
+progress and cancel are in, and the still of the shown frame; `library_check -- export` and `ExportCheck.ps1`
+cover them. Left: probe data as CSV (series per step, profiles per frame), an integer upscale for small
+canvases, HEVC (Media Foundation has it on some machines). Author's point 10.
**Also open, smaller.** A colour picker dialog for stops (hex only now; WinForms `ColorDialog` needs `UseWindowsForms`);
offer `ColorScheme.Simplify` in the editor; renaming a project scheme does not update the layers that
@@ -774,11 +770,11 @@ pan (roadmap); Help > About has no content; dock pane titles are not exposed to
4. ~~**Make the engine loop `Task`-based**~~ (`SimulationRun`, 2026-10-09).
5. **WPF UI** in `WaveDude.WPF`: the preview shows a live run and replays it from the frame store
(done 2026-10-09); editors, colour schemes, scene image and outline, languages (done 2026-10-14,
- see the handoff section); probe graph boxes (done 2026-10-14). Next, in this order of value: the
- **probe signal lane**, **export from the store** (video and stills, rendered with the current display settings, the
- export range, the outline when opted in), a progress bar.
- Store: a RAM-first frame store with a budget and background spill (see the numbers above),
- so a run is compute-bound instead of disk-bound.
+ see the handoff section); probe graph boxes and export from the store (done 2026-10-14). Next, in this
+ order of value: the **probe signal lane**, probe data as CSV, a progress bar for runs (the busy indicator
+ exists for exports and scratch frames).
+ Store: ~~a RAM-first frame store with a budget~~ (done 2026-10-14, two tiers, no background spill
+ needed: the file takes the tail of a run that does not fit).
Timeline, agreed 2026-10-09 (the scrub bar, in/out range, transport keys and the available-frames
shading are done; these stay inside the preview pane, below the pictures):
- **Event tracks** under the bar, one row per source and probe on the same time axis: a source
diff --git a/WaveDude.WPF/Commands/SimulationCommands.cs b/WaveDude.WPF/Commands/SimulationCommands.cs
index 0407744..53df7f1 100644
--- a/WaveDude.WPF/Commands/SimulationCommands.cs
+++ b/WaveDude.WPF/Commands/SimulationCommands.cs
@@ -19,6 +19,9 @@ public static class SimulationCommands
/// <summary>Makes sure the frames are coming: starts a run (keeping the preview's position) when there is none or it is stale; no gesture, the preview's Play issues it.</summary>
public static readonly RoutedUICommand EnsureRun = new("Run if needed", nameof(EnsureRun), typeof(SimulationCommands));
+ /// <summary>Sets the share of the memory a run's frames may take (the parameter: a percentage as text); the Simulation menu's choices.</summary>
+ public static readonly RoutedUICommand SetFrameMemory = new("Frames kept in memory", nameof(SetFrameMemory), typeof(SimulationCommands));
+
/// <summary>Stops the run; the frames computed so far stay in the preview. Shift+F5, or Escape (the usual "stop what you are doing" key, and reachable without a modifier).</summary>
public static readonly RoutedUICommand Stop = new("Stop", nameof(Stop), typeof(SimulationCommands),
[new KeyGesture(Key.F5, ModifierKeys.Shift), new KeyGesture(Key.Escape)]);
diff --git a/WaveDude.WPF/Converters/IntEqualsConverter.cs b/WaveDude.WPF/Converters/IntEqualsConverter.cs
new file mode 100644
index 0000000..42c555b
--- /dev/null
+++ b/WaveDude.WPF/Converters/IntEqualsConverter.cs
@@ -0,0 +1,15 @@
+using System.Globalization;
+using System.Windows.Data;
+
+namespace WaveDude.WPF.Converters;
+
+/// <summary>Whether an integer equals the converter parameter (a number as text): checks a menu item that stands for one value of a setting.</summary>
+public sealed class IntEqualsConverter : IValueConverter
+{
+ /// <inheritdoc/>
+ public object Convert(object? value, Type targetType, object? parameter, CultureInfo culture) =>
+ value is int number && parameter is string text && int.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out int wanted) && number == wanted;
+
+ /// <inheritdoc/>
+ public object ConvertBack(object? value, Type targetType, object? parameter, CultureInfo culture) => Binding.DoNothing;
+}
diff --git a/WaveDude.WPF/MainWindow.Simulation.cs b/WaveDude.WPF/MainWindow.Simulation.cs
index 81ba10a..85a398b 100644
--- a/WaveDude.WPF/MainWindow.Simulation.cs
+++ b/WaveDude.WPF/MainWindow.Simulation.cs
@@ -52,9 +52,16 @@ public partial class MainWindow
Logger.Info("Running on the CPU: 'Use the GPU' is off in the Simulation menu");
}
RunSpec spec = RunSpec.Create(Project, LoadSceneImage(), Settings.Default.UseGpu);
- FrameCache.CheckSpace(FrameStore.SizeOf(spec.Width, spec.Height, spec.Layers, spec.FrameCount));
+ // the frames stay in memory up to the budget (the user's share of the RAM, capped by what is free now); only
+ // the rest needs room on the cache drive (2026-10-14)
+ long budget = FrameMemory.Budget(Settings.Default.FrameMemoryPercent);
+ int ramFrames = Math.Min(spec.FrameCount, FrameStore.FramesInBudget(spec.Width, spec.Height, spec.Layers, budget));
+ if (ramFrames < spec.FrameCount)
+ {
+ FrameCache.CheckSpace(FrameStore.SizeOf(spec.Width, spec.Height, spec.Layers, spec.FrameCount - ramFrames));
+ }
DiscardRun();
- FrameStore store = FrameStore.Create(FrameCache.NewPath(), spec.Width, spec.Height, spec.Layers, spec.FrameCount, spec.VisualizeEvery);
+ FrameStore store = FrameStore.Create(FrameCache.NewPath(), spec.Width, spec.Height, spec.Layers, spec.FrameCount, spec.VisualizeEvery, budget);
var run = new SimulationRun(spec, store, SynchronizationContext.Current, automatic);
run.PropertyChanged += (_, args) =>
{
@@ -64,8 +71,8 @@ public partial class MainWindow
}
};
run.Finished += (_, _) => OnRunFinished();
- Logger.Info("{Kind} started: {Steps} steps, {Frames} frames of {Width}×{Height}; edits made from now on do not affect it",
- automatic ? "Re-run" : "Run", spec.Steps, spec.FrameCount, spec.Width, spec.Height);
+ Logger.Info("{Kind} started: {Steps} steps, {Frames} frames of {Width}×{Height}, {RamFrames} in memory ({RamBytes}) and {DiskFrames} on disk; edits made from now on do not affect it",
+ automatic ? "Re-run" : "Run", spec.Steps, spec.FrameCount, spec.Width, spec.Height, store.RamFrames, FrameMemory.Gigabytes(store.RamBytes), spec.FrameCount - store.RamFrames);
IsRunStale = false;
IsProbesStale = false;
Run = run;
diff --git a/WaveDude.WPF/MainWindow.xaml b/WaveDude.WPF/MainWindow.xaml
index 3ed0c59..a345be7 100644
--- a/WaveDude.WPF/MainWindow.xaml
+++ b/WaveDude.WPF/MainWindow.xaml
@@ -23,6 +23,7 @@
<Window.Resources>
<converters:EqualityConverter x:Key="Equality" />
+ <converters:IntEqualsConverter x:Key="IntEquals" />
<converters:TitleConverter x:Key="TitleConverter" />
<converters:RunStatusConverter x:Key="RunStatus" />
@@ -109,6 +110,7 @@
<CommandBinding Command="{x:Static commands:SimulationCommands.TogglePause}" CanExecute="CanControlRun" Executed="OnTogglePause" />
<CommandBinding Command="{x:Static commands:SimulationCommands.Stop}" CanExecute="CanControlRun" Executed="OnStop" />
<CommandBinding Command="{x:Static commands:SimulationCommands.EnsureRun}" Executed="OnEnsureRun" />
+ <CommandBinding Command="{x:Static commands:SimulationCommands.SetFrameMemory}" Executed="OnSetFrameMemory" />
<!-- project structure; handlers in MainWindow.Project.cs -->
<CommandBinding Command="{x:Static commands:ProjectCommands.AddSource}" Executed="OnAddSource" />
@@ -180,6 +182,18 @@
<MenuItem Header="{DynamicResource MenuSimulationAutoRerun}" IsCheckable="True"
IsChecked="{Binding Source={x:Static p:Settings.Default}, Path=AutoRerun, Mode=TwoWay}"
AutomationProperties.AutomationId="MenuAutoRerun" />
+ <!-- the share of the RAM a run's frames may take before the rest goes to disk (2026-10-14); a run never takes more than what is free -->
+ <MenuItem Header="{DynamicResource MenuSimulationFrameMemory}" AutomationProperties.AutomationId="MenuFrameMemory">
+ <MenuItem Header="{DynamicResource MenuSimulationFrameMemory25}" Command="{x:Static commands:SimulationCommands.SetFrameMemory}" CommandParameter="25"
+ IsChecked="{Binding Source={x:Static p:Settings.Default}, Path=FrameMemoryPercent, Converter={StaticResource IntEquals}, ConverterParameter=25, Mode=OneWay}"
+ AutomationProperties.AutomationId="MenuFrameMemory25" />
+ <MenuItem Header="{DynamicResource MenuSimulationFrameMemory50}" Command="{x:Static commands:SimulationCommands.SetFrameMemory}" CommandParameter="50"
+ IsChecked="{Binding Source={x:Static p:Settings.Default}, Path=FrameMemoryPercent, Converter={StaticResource IntEquals}, ConverterParameter=50, Mode=OneWay}"
+ AutomationProperties.AutomationId="MenuFrameMemory50" />
+ <MenuItem Header="{DynamicResource MenuSimulationFrameMemory75}" Command="{x:Static commands:SimulationCommands.SetFrameMemory}" CommandParameter="75"
+ IsChecked="{Binding Source={x:Static p:Settings.Default}, Path=FrameMemoryPercent, Converter={StaticResource IntEquals}, ConverterParameter=75, Mode=OneWay}"
+ AutomationProperties.AutomationId="MenuFrameMemory75" />
+ </MenuItem>
</MenuItem>
<MenuItem Header="{DynamicResource MenuHelp}">
<MenuItem Header="{DynamicResource MenuHelpAbout}" />
diff --git a/WaveDude.WPF/MainWindow.xaml.cs b/WaveDude.WPF/MainWindow.xaml.cs
index c5556c5..de4b2c9 100644
--- a/WaveDude.WPF/MainWindow.xaml.cs
+++ b/WaveDude.WPF/MainWindow.xaml.cs
@@ -8,6 +8,7 @@ using System.Windows.Shell;
using Microsoft.Win32;
using NLog;
using WaveDude.Model;
+using WaveDude.Runs;
using WaveDude.Rendering;
using WaveDude.WPF.Docking;
using WaveDude.WPF.Localization;
@@ -75,6 +76,10 @@ public partial class MainWindow : Window
{
Logger.Info(Settings.Default.UseGpu ? "Use the GPU switched on (Simulation menu)" : "Use the GPU switched off (Simulation menu): runs use the CPU from now on");
}
+ else if (args.PropertyName == nameof(Settings.FrameMemoryPercent))
+ {
+ Logger.Info("Frames kept in memory: {Percent} % of the RAM, {Budget} right now (Simulation menu)", Settings.Default.FrameMemoryPercent, FrameMemory.Gigabytes(FrameMemory.Budget(Settings.Default.FrameMemoryPercent)));
+ }
};
Closing += (_, _) =>
{
@@ -245,6 +250,16 @@ public partial class MainWindow : Window
private void ShowError(string message, Exception ex) =>
MessageBox.Show(this, $"{message}\n{ex.Message}", (string)FindResource("Title"), MessageBoxButton.OK, MessageBoxImage.Error);
+ /// <summary>Simulation > Frames kept in memory: the chosen share of the RAM, applied to the next run.</summary>
+ private void OnSetFrameMemory(object sender, ExecutedRoutedEventArgs e)
+ {
+ if (e.Parameter is string text && int.TryParse(text, System.Globalization.NumberStyles.Integer, System.Globalization.CultureInfo.InvariantCulture, out int percent))
+ {
+ Settings.Default.FrameMemoryPercent = percent;
+ SaveSettings();
+ }
+ }
+
private void OnFileNew(object sender, ExecutedRoutedEventArgs e)
{
DiscardRun();
diff --git a/WaveDude.WPF/Properties/Settings.Designer.cs b/WaveDude.WPF/Properties/Settings.Designer.cs
index dc948fc..c55fd1d 100644
--- a/WaveDude.WPF/Properties/Settings.Designer.cs
+++ b/WaveDude.WPF/Properties/Settings.Designer.cs
@@ -176,5 +176,17 @@ namespace WaveDude.WPF.Properties {
this["UseGpu"] = value;
}
}
+ [global::System.Configuration.UserScopedSettingAttribute()]
+ [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
+ [global::System.Configuration.DefaultSettingValueAttribute("50")]
+ public int FrameMemoryPercent {
+ get {
+ return ((int)(this["FrameMemoryPercent"]));
+ }
+ set {
+ this["FrameMemoryPercent"] = value;
+ }
+ }
+
}
}
diff --git a/WaveDude.WPF/Properties/Settings.settings b/WaveDude.WPF/Properties/Settings.settings
index 94dc94a..8817555 100644
--- a/WaveDude.WPF/Properties/Settings.settings
+++ b/WaveDude.WPF/Properties/Settings.settings
@@ -41,5 +41,8 @@
<Setting Name="UseGpu" Type="System.Boolean" Scope="User">
<Value Profile="(Default)">True</Value>
</Setting>
+ <Setting Name="FrameMemoryPercent" Type="System.Int32" Scope="User">
+ <Value Profile="(Default)">50</Value>
+ </Setting>
</Settings>
</SettingsFile>
diff --git a/WaveDude.WPF/Strings/Strings.DE.xaml b/WaveDude.WPF/Strings/Strings.DE.xaml
index 81aea30..12cb1b1 100644
--- a/WaveDude.WPF/Strings/Strings.DE.xaml
+++ b/WaveDude.WPF/Strings/Strings.DE.xaml
@@ -26,6 +26,10 @@
<s:String x:Key="MenuSimulationStop">S_topp</s:String>
<s:String x:Key="MenuSimulationUseGpu">_GPU verwenden (OpenCL)</s:String>
<s:String x:Key="MenuSimulationAutoRerun">Nach Änderungen _automatisch neu starten</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory">Bilder im Arbeits_speicher</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory25">Ein _Viertel des RAM</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory50">Die _Hälfte des RAM</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory75">_Drei Viertel des RAM</s:String>
<s:String x:Key="MenuHelp">_Hilfe</s:String>
<s:String x:Key="MenuHelpAbout">_Über Wave Dude</s:String>
diff --git a/WaveDude.WPF/Strings/Strings.EN.xaml b/WaveDude.WPF/Strings/Strings.EN.xaml
index aedf8e4..e0509c8 100644
--- a/WaveDude.WPF/Strings/Strings.EN.xaml
+++ b/WaveDude.WPF/Strings/Strings.EN.xaml
@@ -26,6 +26,10 @@
<s:String x:Key="MenuSimulationStop">S_top</s:String>
<s:String x:Key="MenuSimulationUseGpu">Use the _GPU (OpenCL)</s:String>
<s:String x:Key="MenuSimulationAutoRerun">Re-run _automatically after edits</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory">Frames kept in _memory</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory25">A _quarter of the RAM</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory50">_Half of the RAM</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory75">_Three quarters of the RAM</s:String>
<s:String x:Key="MenuHelp">_Help</s:String>
<s:String x:Key="MenuHelpAbout">_About Wave Dude</s:String>
diff --git a/WaveDude.WPF/Strings/Strings.FR.xaml b/WaveDude.WPF/Strings/Strings.FR.xaml
index bcbd316..3e8d843 100644
--- a/WaveDude.WPF/Strings/Strings.FR.xaml
+++ b/WaveDude.WPF/Strings/Strings.FR.xaml
@@ -26,6 +26,10 @@
<s:String x:Key="MenuSimulationStop">_Arrêter</s:String>
<s:String x:Key="MenuSimulationUseGpu">Utiliser le _GPU (OpenCL)</s:String>
<s:String x:Key="MenuSimulationAutoRerun">Relancer a_utomatiquement après une modification</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory">Images gardées en _mémoire</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory25">Un _quart de la RAM</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory50">La _moitié de la RAM</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory75">_Trois quarts de la RAM</s:String>
<s:String x:Key="MenuHelp">_Aide</s:String>
<s:String x:Key="MenuHelpAbout">À _propos de Wave Dude</s:String>
diff --git a/WaveDude.WPF/Strings/Strings.NL.xaml b/WaveDude.WPF/Strings/Strings.NL.xaml
index 72137eb..0a73411 100644
--- a/WaveDude.WPF/Strings/Strings.NL.xaml
+++ b/WaveDude.WPF/Strings/Strings.NL.xaml
@@ -26,6 +26,10 @@
<s:String x:Key="MenuSimulationStop">S_toppen</s:String>
<s:String x:Key="MenuSimulationUseGpu">_GPU gebruiken (OpenCL)</s:String>
<s:String x:Key="MenuSimulationAutoRerun">Na bewerkingen _automatisch opnieuw starten</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory">Beelden in het ge_heugen</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory25">Een _kwart van het RAM</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory50">De _helft van het RAM</s:String>
+ <s:String x:Key="MenuSimulationFrameMemory75">_Driekwart van het RAM</s:String>
<s:String x:Key="MenuHelp">_Help</s:String>
<s:String x:Key="MenuHelpAbout">_Over Wave Dude</s:String>
diff --git a/WaveDude/Runs/FrameMemory.cs b/WaveDude/Runs/FrameMemory.cs
new file mode 100644
index 0000000..59fda21
--- /dev/null
+++ b/WaveDude/Runs/FrameMemory.cs
@@ -0,0 +1,81 @@
+using System.Runtime.InteropServices;
+
+namespace WaveDude.Runs;
+
+/// <summary>
+/// How much memory a run's frames may take before the rest goes to disk (2026-10-14). The budget is decided
+/// when a run starts, from what the machine has to spare at that moment: a share of the physical memory (the
+/// user's setting), but never more than what is available now minus a margin for the rest of the application
+/// and the system, so a run never pushes the machine into its page file. Windows answers through
+/// <c>GlobalMemoryStatusEx</c>; elsewhere the runtime's view of the total serves, with half of it taken as
+/// available. Thread-free.
+/// </summary>
+public static class FrameMemory
+{
+ /// <summary>Share of the physical memory a run may take when the user has not chosen one.</summary>
+ public const int DefaultPercent = 50;
+
+ /// <summary>Memory left untouched below what is available: the application, the engines' own buffers and the system need room too.</summary>
+ public const long Margin = 2L << 30;
+
+ /// <summary>Bytes of physical memory in the machine.</summary>
+ public static long PhysicalBytes()
+ {
+ if (OperatingSystem.IsWindows() && TryStatus(out MemoryStatus status))
+ {
+ return (long)Math.Min(status.TotalPhys, long.MaxValue);
+ }
+ return GC.GetGCMemoryInfo().TotalAvailableMemoryBytes;
+ }
+
+ /// <summary>Bytes of physical memory free right now (the standby cache counts as free, as Windows reports it).</summary>
+ public static long AvailableBytes()
+ {
+ if (OperatingSystem.IsWindows() && TryStatus(out MemoryStatus status))
+ {
+ return (long)Math.Min(status.AvailPhys, long.MaxValue);
+ }
+ return PhysicalBytes() / 2;
+ }
+
+ /// <summary>
+ /// The frame budget for a run started now: <paramref name="percentOfPhysical"/> of the physical memory, capped
+ /// at what is available minus <see cref="Margin"/>; never negative.
+ /// </summary>
+ /// <param name="percentOfPhysical">The user's share, 0 to 100 (clamped).</param>
+ public static long Budget(int percentOfPhysical)
+ {
+ double share = Math.Clamp(percentOfPhysical, 0, 100) / 100.0;
+ long byShare = (long)(PhysicalBytes() * share);
+ long byAvailable = AvailableBytes() - Margin;
+ return Math.Max(0, Math.Min(byShare, byAvailable));
+ }
+
+ /// <summary>A byte count as gigabytes with one decimal, for log lines.</summary>
+ public static string Gigabytes(long bytes) => (bytes / (double)(1L << 30)).ToString("0.0", System.Globalization.CultureInfo.CurrentCulture) + " GB";
+
+ private static bool TryStatus(out MemoryStatus status)
+ {
+ status = new MemoryStatus { Length = (uint)Marshal.SizeOf<MemoryStatus>() };
+ return GlobalMemoryStatusEx(ref status);
+ }
+
+ /// <summary>The <c>MEMORYSTATUSEX</c> structure of <c>kernel32</c>.</summary>
+ [StructLayout(LayoutKind.Sequential)]
+ private struct MemoryStatus
+ {
+ public uint Length;
+ public uint MemoryLoad;
+ public ulong TotalPhys;
+ public ulong AvailPhys;
+ public ulong TotalPageFile;
+ public ulong AvailPageFile;
+ public ulong TotalVirtual;
+ public ulong AvailVirtual;
+ public ulong AvailExtendedVirtual;
+ }
+
+ [DllImport("kernel32.dll", SetLastError = true)]
+ [return: MarshalAs(UnmanagedType.Bool)]
+ private static extern bool GlobalMemoryStatusEx(ref MemoryStatus buffer);
+}
diff --git a/WaveDude/Runs/FrameStore.cs b/WaveDude/Runs/FrameStore.cs
index 398486e..5b003ec 100644
--- a/WaveDude/Runs/FrameStore.cs
+++ b/WaveDude/Runs/FrameStore.cs
@@ -1,44 +1,71 @@
+using System.Collections.Concurrent;
using System.Numerics.Tensors;
using System.Runtime.InteropServices;
using Microsoft.Win32.SafeHandles;
+using NLog;
namespace WaveDude.Runs;
/// <summary>
-/// The frames of one run: a file holding, per frame, one <see cref="Half"/> plane per layer
-/// (<see cref="Layers"/>), <see cref="Width"/> × <see cref="Height"/> values row-major with the engine's
-/// padding stripped. The file is pre-sized for <see cref="Capacity"/> frames and marked temporary, so the
-/// operating system's cache keeps recent frames in memory and spills the rest to disk; it is deleted when
-/// the store is disposed (or the process ends, <see cref="FileOptions.DeleteOnClose"/>).
+/// The frames of one run: per frame one <see cref="Half"/> plane per layer (<see cref="Layers"/>),
+/// <see cref="Width"/> × <see cref="Height"/> values row-major with the engine's padding stripped. Two tiers
+/// (2026-10-14): the first frames of the run, as many as the memory budget given at creation holds
+/// (<see cref="RamFrames"/>), live in native memory; the rest go to a temporary file that is created only when
+/// a run does not fit. A run that fits never touches the disk, so it is bound by the engine and not by the
+/// drive; a run that does not fit is disk-bound for its tail only. The file is pre-sized for the frames it
+/// will hold, marked temporary, and deleted when the store is disposed or the process ends
+/// (<see cref="FileOptions.DeleteOnClose"/>).
/// </summary>
/// <remarks>
-/// Threads: the run's worker is the only writer (<see cref="Write(int, ReadOnlySpan{Half}, ReadOnlySpan{Half})"/>, frames in order); any thread may read
-/// frames below <see cref="Count"/>, which is published after the frame's bytes. Reads and writes are
-/// positional (<see cref="RandomAccess"/>) and run concurrently; <see cref="Dispose"/> waits for them.
-/// Access goes through the cache manager rather than a memory mapping on purpose: touching 16 MB of fresh
-/// mapped pages per frame cost more than the frame's conversion, on both the writer and the reader side,
-/// and unmapping flushed the whole file to disk before its deletion.
-/// Layout: a <see cref="HeaderSize"/>-byte header ("WDFS", version, width, height, layers, visualize-every,
-/// capacity), then <see cref="Capacity"/> × <see cref="FrameBytes"/>; within a frame the planes follow the
-/// order of <see cref="FrameLayer"/>, only those present.
+/// Why not the operating system's cache or a memory mapping: both keep dirty pages in memory only up to
+/// the memory manager's own allowance and then write at disk speed whatever the file's attributes say
+/// (a 10 GB full-HD run took 14 s against the drive with 40 GB of memory free), and a mapping paid a page
+/// fault per fresh page and flushed everything on unmap. The budget is ours, decided from what is free when
+/// the run starts (<see cref="FrameMemory.Budget"/>), so the machine is never pushed into its page file.
+/// Threads: the run's worker is the only writer (<see cref="Write(int, ReadOnlySpan{Half}, ReadOnlySpan{Half})"/>,
+/// frames in order); any thread may read frames below <see cref="Count"/>, which is published after the
+/// frame's bytes. Reads and writes run concurrently; <see cref="Dispose"/> waits for them, frees the memory
+/// under the lock (quick) and closes the file outside it (deleting a large file can take a second).
+/// A background task allocates the memory blocks a few frames ahead of the writer and touches every page of
+/// them (<see cref="PrepareBlocks"/>): a fresh block costs a page fault per 4 KB on first touch, 8 to 14 ms
+/// for a full-HD frame, which would make the writer slower than the engine; prepared, a frame is a plain copy.
+/// File layout: a <see cref="HeaderSize"/>-byte header ("WDFS", version, width, height, layers,
+/// visualize-every, capacity, first frame in the file), then one <see cref="FrameBytes"/> record per spilled
+/// frame; within a frame the planes follow the order of <see cref="FrameLayer"/>, only those present.
/// </remarks>
-public sealed class FrameStore : IFrameSource, IDisposable
+public sealed unsafe class FrameStore : IFrameSource, IDisposable
{
+ private static readonly ILogger Logger = LogManager.GetCurrentClassLogger();
+
/// <summary>Size of the file header in bytes.</summary>
public const int HeaderSize = 64;
private const uint Magic = 0x53464457; // "WDFS" as little-endian bytes
- private const int Version = 1;
+ private const int Version = 2;
+
+ /// <summary>Value of <see cref="_firstSpilled"/> while no frame goes to the file.</summary>
+ private const int NoSpill = int.MaxValue;
+
+ /// <summary>Memory blocks allocated and touched ahead of the writer.</summary>
+ private const int PrepareDepth = 4;
+
+ /// <summary>Page size assumed when touching a fresh block.</summary>
+ private const int PageSize = 4096;
private readonly ReaderWriterLockSlim _lifetime = new();
- private readonly FileStream _file;
- private readonly SafeFileHandle _handle;
+ private readonly IntPtr[] _ram;
+ private readonly BlockingCollection<IntPtr> _prepared = new(PrepareDepth);
+ private readonly CancellationTokenSource _prepareCancel = new();
+ private readonly Task _preparer;
private readonly Half[] _staging;
private Half[]? _staging2;
+ private FileStream? _file;
+ private SafeFileHandle? _handle;
+ private volatile int _firstSpilled = NoSpill;
private int _count;
private bool _disposed;
- private FrameStore(string path, int width, int height, FrameLayers layers, int capacity, int visualizeEvery)
+ private FrameStore(string path, int width, int height, FrameLayers layers, int capacity, int visualizeEvery, long ramBudget)
{
ArgumentOutOfRangeException.ThrowIfLessThan(width, 1);
ArgumentOutOfRangeException.ThrowIfLessThan(height, 1);
@@ -55,62 +82,103 @@ public sealed class FrameStore : IFrameSource, IDisposable
Capacity = capacity;
VisualizeEvery = visualizeEvery;
LayerCount = (Has(FrameLayer.Field) ? 1 : 0) + (Has(FrameLayer.Intensity) ? 1 : 0);
+ RamFrames = Math.Min(capacity, FramesInBudget(width, height, layers, ramBudget));
+ _ram = new IntPtr[RamFrames];
_staging = new Half[width * height];
- _file = new FileStream(path, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None, 1, FileOptions.DeleteOnClose);
+ if (RamFrames < capacity)
+ {
+ // the run will not fit: the file for the rest is made now, so a lack of disk space shows at the start
+ _firstSpilled = RamFrames;
+ CreateFile(RamFrames);
+ }
+ _preparer = RamFrames > 0 ? Task.Run(PrepareBlocks) : Task.CompletedTask;
+ }
+
+ /// <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. Ends when
+ /// every block is made, the store is disposed, or an allocation fails (the commit limit), after which the
+ /// writer spills the remaining frames to the file.
+ /// </summary>
+ private void PrepareBlocks()
+ {
+ CancellationToken token = _prepareCancel.Token;
try
{
- // a temporary file: the cache manager keeps its pages in memory while it can instead of writing
- // them out eagerly; the data is read back from the cache and the file is deleted in the end
- try
- {
- File.SetAttributes(path, FileAttributes.Temporary | FileAttributes.NotContentIndexed);
- }
- catch (IOException)
+ for (int i = 0; i < RamFrames && !token.IsCancellationRequested; i++)
{
- // a hint only
- }
- catch (UnauthorizedAccessException)
- {
- // a hint only
+ void* block;
+ try
+ {
+ block = NativeMemory.Alloc((nuint)FrameBytes);
+ }
+ catch (OutOfMemoryException)
+ {
+ break;
+ }
+ byte* bytes = (byte*)block;
+ for (long offset = 0; offset < FrameBytes; offset += PageSize)
+ {
+ bytes[offset] = 0;
+ }
+ try
+ {
+ _prepared.Add((IntPtr)block, token);
+ }
+ catch (OperationCanceledException)
+ {
+ NativeMemory.Free(block);
+ break;
+ }
}
- _file.SetLength(TotalBytes);
- _handle = _file.SafeFileHandle;
- Span<byte> header = stackalloc byte[HeaderSize];
- BitConverter.TryWriteBytes(header, Magic);
- BitConverter.TryWriteBytes(header[4..], Version);
- BitConverter.TryWriteBytes(header[8..], width);
- BitConverter.TryWriteBytes(header[12..], height);
- BitConverter.TryWriteBytes(header[16..], (int)layers);
- BitConverter.TryWriteBytes(header[20..], visualizeEvery);
- BitConverter.TryWriteBytes(header[24..], capacity);
- RandomAccess.Write(_handle, header, 0);
}
- catch
+ finally
{
- _file.Dispose();
- throw;
+ _prepared.CompleteAdding();
+ }
+ }
+
+ /// <summary>The next prepared block for a frame of the memory tier, waiting for the producer; false when it ended (the memory is exhausted).</summary>
+ private bool TryTakeBlock(out void* block)
+ {
+ if (_prepared.TryTake(out IntPtr pointer, Timeout.Infinite))
+ {
+ block = (void*)pointer;
+ return true;
}
+ block = null;
+ return false;
}
- /// <summary>Creates the file at <paramref name="path"/> (which must not exist) sized for the whole run.</summary>
- /// <param name="path">File path, normally from <see cref="FrameCache.NewPath"/>.</param>
+ /// <summary>
+ /// Creates a store for a run of <paramref name="capacity"/> frames: in memory up to <paramref name="ramBudget"/>
+ /// bytes, the rest in the file at <paramref name="path"/> (which must not exist; it is only created when needed).
+ /// </summary>
+ /// <param name="path">File path for the spilled frames, normally from <see cref="FrameCache.NewPath"/>.</param>
/// <param name="width">Frame width in pixels.</param>
/// <param name="height">Frame height in pixels.</param>
/// <param name="layers">The planes every frame holds; at least one.</param>
/// <param name="capacity">Number of frames the run produces (<see cref="RunSpec.FrameCount"/>).</param>
/// <param name="visualizeEvery">Steps per frame, kept for <see cref="StepOf"/>.</param>
+ /// <param name="ramBudget">Bytes of memory the frames may take; null takes <see cref="FrameMemory.Budget"/> at the default share.</param>
/// <exception cref="IOException">The file cannot be created or sized (for instance no disk space).</exception>
- public static FrameStore Create(string path, int width, int height, FrameLayers layers, int capacity, int visualizeEvery) =>
- new(path, width, height, layers, capacity, visualizeEvery);
+ public static FrameStore Create(string path, int width, int height, FrameLayers layers, int capacity, int visualizeEvery, long? ramBudget = null) =>
+ new(path, width, height, layers, capacity, visualizeEvery, ramBudget ?? FrameMemory.Budget(FrameMemory.DefaultPercent));
+
+ /// <summary>Bytes a file holding <paramref name="capacity"/> frames of these dimensions takes, for <see cref="FrameCache.CheckSpace"/> (the spilled part of a run).</summary>
+ public static long SizeOf(int width, int height, FrameLayers layers, int capacity) => HeaderSize + (long)capacity * FrameBytesOf(width, height, layers);
+
+ /// <summary>How many frames of these dimensions fit into <paramref name="budget"/> bytes of memory.</summary>
+ public static int FramesInBudget(int width, int height, FrameLayers layers, long budget) =>
+ (int)Math.Clamp(Math.Max(0, budget) / FrameBytesOf(width, height, layers), 0, int.MaxValue);
- /// <summary>Bytes the file of a store with these dimensions takes, for <see cref="FrameCache.CheckSpace"/>.</summary>
- public static long SizeOf(int width, int height, FrameLayers layers, int capacity)
+ private static long FrameBytesOf(int width, int height, FrameLayers layers)
{
int layerCount = ((layers & FrameLayers.Field) != 0 ? 1 : 0) + ((layers & FrameLayers.Intensity) != 0 ? 1 : 0);
- return HeaderSize + (long)capacity * layerCount * width * height * 2;
+ return (long)layerCount * width * height * 2;
}
- /// <summary>Full path of the backing file.</summary>
+ /// <summary>Full path of the file for the spilled frames; it exists only once a frame went there (<see cref="HasFile"/>).</summary>
public string Path { get; }
/// <summary>Frame width in pixels.</summary>
@@ -125,23 +193,44 @@ public sealed class FrameStore : IFrameSource, IDisposable
/// <summary>Number of planes per frame.</summary>
public int LayerCount { get; }
- /// <summary>Number of frames the file has room for.</summary>
+ /// <summary>Number of frames the store has room for.</summary>
public int Capacity { get; }
/// <summary>Steps per frame: frame k shows the state after step k × this.</summary>
public int VisualizeEvery { get; }
+ /// <summary>Frames the memory budget holds, the first ones of the run; the rest go to the file.</summary>
+ public int RamFrames { get; }
+
+ /// <summary>Index of the first frame kept in the file; <see cref="Capacity"/> when every frame fits in memory. Falls below <see cref="RamFrames"/> only when an allocation failed.</summary>
+ public int FirstSpilledFrame => Math.Min(_firstSpilled, Capacity);
+
/// <summary>Frames written so far; frames 0..Count-1 may be read from any thread.</summary>
public int Count => Volatile.Read(ref _count);
+ /// <summary>Frames written so far that live in memory.</summary>
+ public int FramesInMemory => Math.Min(Count, FirstSpilledFrame);
+
+ /// <summary>Frames written so far that live in the file.</summary>
+ public int FramesOnDisk => Math.Max(0, Count - FirstSpilledFrame);
+
+ /// <summary>Whether the file for spilled frames exists.</summary>
+ public bool HasFile => _file != null;
+
/// <summary>Bytes of one plane: <see cref="Width"/> × <see cref="Height"/> × 2.</summary>
public long PlaneBytes => (long)Width * Height * 2;
/// <summary>Bytes of one frame: <see cref="PlaneBytes"/> × <see cref="LayerCount"/>.</summary>
public long FrameBytes => PlaneBytes * LayerCount;
- /// <summary>Size of the whole file.</summary>
- public long TotalBytes => HeaderSize + Capacity * FrameBytes;
+ /// <summary>Bytes all frames of the run take once written, memory and file together (without the file header).</summary>
+ public long TotalBytes => Capacity * FrameBytes;
+
+ /// <summary>Bytes the memory tier takes once its frames are written.</summary>
+ public long RamBytes => FirstSpilledFrame * FrameBytes;
+
+ /// <summary>Size of the file, 0 while there is none.</summary>
+ public long FileBytes => _file == null ? 0 : HeaderSize + (Capacity - FirstSpilledFrame) * FrameBytes;
/// <summary>Whether frames hold the given plane.</summary>
public bool Has(FrameLayer layer) => (Layers & (FrameLayers)(1 << (int)layer)) != 0;
@@ -181,8 +270,10 @@ public sealed class FrameStore : IFrameSource, IDisposable
/// <summary>
/// Stores the next frame from <see cref="Half"/> planes in the store's own layout (what
- /// <see cref="Engine.IWaveEngine.CaptureFrame"/> produces), one positional write per plane. Any thread, but
- /// only one writer at a time; frames must arrive in order.
+ /// <see cref="Engine.IWaveEngine.CaptureFrame"/> produces): a copy into memory while the budget lasts, one
+ /// positional write per plane into the file beyond it. Any thread, but only one writer at a time; frames
+ /// must arrive in order. When the memory for a frame within the budget cannot be had after all (the
+ /// commit limit of the machine), that frame and every later one go to the file instead, noted once.
/// </summary>
/// <param name="frame">Index of the frame; must equal <see cref="Count"/>.</param>
/// <param name="field">Field plane, <see cref="Width"/> × <see cref="Height"/> values.</param>
@@ -201,21 +292,43 @@ public sealed class FrameStore : IFrameSource, IDisposable
{
throw new ArgumentOutOfRangeException(nameof(frame), frame, "Frames must be written in order and within the capacity.");
}
- if (Has(FrameLayer.Field))
+ if (Has(FrameLayer.Field) && field.Length < length)
+ {
+ throw new ArgumentOutOfRangeException(nameof(field), "The field plane is too short.");
+ }
+ if (Has(FrameLayer.Intensity) && intensity.Length < length)
{
- if (field.Length < length)
+ throw new ArgumentNullException(nameof(intensity), "The store has an intensity plane; the intensity is missing or too short.");
+ }
+ if (frame < _firstSpilled)
+ {
+ if (!TryTakeBlock(out void* memory))
+ {
+ Spill(frame);
+ }
+ else
{
- throw new ArgumentOutOfRangeException(nameof(field), "The field plane is too short.");
+ if (Has(FrameLayer.Field))
+ {
+ field[..length].CopyTo(Plane(memory, FrameLayer.Field));
+ }
+ if (Has(FrameLayer.Intensity))
+ {
+ intensity[..length].CopyTo(Plane(memory, FrameLayer.Intensity));
+ }
+ _ram[frame] = (IntPtr)memory;
}
- RandomAccess.Write(_handle, MemoryMarshal.AsBytes(field[..length]), PlaneOffset(frame, FrameLayer.Field));
}
- if (Has(FrameLayer.Intensity))
+ if (frame >= _firstSpilled)
{
- if (intensity.Length < length)
+ if (Has(FrameLayer.Field))
{
- throw new ArgumentNullException(nameof(intensity), "The store has an intensity plane; the intensity is missing or too short.");
+ RandomAccess.Write(_handle!, MemoryMarshal.AsBytes(field[..length]), PlaneOffset(frame, FrameLayer.Field));
+ }
+ if (Has(FrameLayer.Intensity))
+ {
+ RandomAccess.Write(_handle!, MemoryMarshal.AsBytes(intensity[..length]), PlaneOffset(frame, FrameLayer.Intensity));
}
- RandomAccess.Write(_handle, MemoryMarshal.AsBytes(intensity[..length]), PlaneOffset(frame, FrameLayer.Intensity));
}
Volatile.Write(ref _count, frame + 1);
}
@@ -239,8 +352,8 @@ public sealed class FrameStore : IFrameSource, IDisposable
/// <summary>
/// Reads one plane of a stored frame into <paramref name="destination"/> (at least <see cref="Width"/> ×
- /// <see cref="Height"/> values). Safe against a concurrent <see cref="Dispose"/>; returns false instead of
- /// reading when the store is already disposed.
+ /// <see cref="Height"/> values), from memory or from the file. Safe against a concurrent <see cref="Dispose"/>;
+ /// returns false instead of reading when the store is already disposed.
/// </summary>
/// <param name="frame">Frame index below <see cref="Count"/>.</param>
/// <param name="layer">A plane the store holds.</param>
@@ -268,11 +381,16 @@ public sealed class FrameStore : IFrameSource, IDisposable
{
throw new ArgumentOutOfRangeException(nameof(layer), layer, "The store has no such plane.");
}
+ if (frame < _firstSpilled)
+ {
+ Plane((void*)_ram[frame], layer).CopyTo(destination);
+ return true;
+ }
Span<byte> bytes = MemoryMarshal.AsBytes(destination[..length]);
long offset = PlaneOffset(frame, layer);
while (bytes.Length > 0)
{
- int read = RandomAccess.Read(_handle, bytes, offset);
+ int read = RandomAccess.Read(_handle!, bytes, offset);
if (read <= 0)
{
throw new IOException("The frame store file ended early.");
@@ -294,10 +412,10 @@ public sealed class FrameStore : IFrameSource, IDisposable
}
/// <summary>
- /// Closes the file, which deletes it. Marks the store disposed under the lock (so no new read or write
- /// starts) but closes the file outside it: deleting a 10 GB file can take a second, and a reader must not
- /// wait for that. A read or write in flight ends with <see cref="ObjectDisposedException"/>, which
- /// <see cref="CopyLayer"/> turns into false.
+ /// Frees the memory tier and closes the file, which deletes it. Marks the store disposed and frees the frames
+ /// under the lock (so no read or write starts on freed memory) but closes the file outside it: deleting a
+ /// large file can take a second, and a reader must not wait for that. A file read or write in flight ends
+ /// with <see cref="ObjectDisposedException"/>, which <see cref="CopyLayer"/> turns into false.
/// </summary>
public void Dispose()
{
@@ -309,19 +427,112 @@ public sealed class FrameStore : IFrameSource, IDisposable
return;
}
_disposed = true;
+ _prepareCancel.Cancel();
+ for (int i = 0; i < _ram.Length; i++)
+ {
+ if (_ram[i] != IntPtr.Zero)
+ {
+ NativeMemory.Free((void*)_ram[i]);
+ _ram[i] = IntPtr.Zero;
+ }
+ }
}
finally
{
_lifetime.ExitWriteLock();
}
- _file.Dispose();
+ _file?.Dispose();
+ // the producer ends at its next check; the blocks it queued (and any it adds before noticing) are freed here
+ try
+ {
+ _preparer.Wait(TimeSpan.FromSeconds(5));
+ }
+ catch (AggregateException)
+ {
+ // cancelled
+ }
+ while (_prepared.TryTake(out IntPtr block))
+ {
+ NativeMemory.Free((void*)block);
+ }
+ _prepareCancel.Dispose();
+ }
+
+ /// <summary>A plane of a frame kept in memory, as a span over the native block.</summary>
+ private Span<Half> Plane(void* frameMemory, FrameLayer layer) =>
+ new((byte*)frameMemory + PlaneIndex(layer) * PlaneBytes, Width * Height);
+
+ /// <summary>Byte offset of a plane in the file; the file holds the frames from <see cref="_firstSpilled"/> on.</summary>
+ private long PlaneOffset(int frame, FrameLayer layer) =>
+ HeaderSize + (frame - _firstSpilled) * FrameBytes + PlaneIndex(layer) * PlaneBytes;
+
+ /// <summary>Position of a plane within a frame: planes follow the <see cref="FrameLayer"/> order, only those present.</summary>
+ private int PlaneIndex(FrameLayer layer) => layer == FrameLayer.Intensity && Has(FrameLayer.Field) ? 1 : 0;
+
+ /// <summary>
+ /// The memory for frame <paramref name="frame"/> could not be had: from here on every frame goes to the file,
+ /// which is created now if the run was expected to fit, or enlarged to take the extra frames otherwise
+ /// (nothing has been written to it yet, since frames arrive in order).
+ /// </summary>
+ private void Spill(int frame)
+ {
+ Logger.Warn("No memory for frame {Frame} ({Bytes} per frame): the remaining {Rest} frames go to disk", frame, FrameBytes, Capacity - frame);
+ _firstSpilled = frame;
+ if (_file == null)
+ {
+ CreateFile(frame);
+ }
+ else
+ {
+ _file.SetLength(HeaderSize + (Capacity - frame) * FrameBytes);
+ WriteHeader(frame);
+ }
}
- /// <summary>Byte offset of a plane; planes follow the <see cref="FrameLayer"/> order, only those present.</summary>
- private long PlaneOffset(int frame, FrameLayer layer)
+ /// <summary>Creates the pre-sized temporary file for the frames from <paramref name="firstFrame"/> on.</summary>
+ private void CreateFile(int firstFrame)
{
- int planeIndex = layer == FrameLayer.Intensity && Has(FrameLayer.Field) ? 1 : 0;
- return HeaderSize + frame * FrameBytes + planeIndex * PlaneBytes;
+ _file = new FileStream(Path, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None, 1, FileOptions.DeleteOnClose);
+ try
+ {
+ // a temporary file: the cache manager keeps its pages in memory while it can instead of writing
+ // them out eagerly (a hint only); the file is deleted in the end
+ try
+ {
+ File.SetAttributes(Path, FileAttributes.Temporary | FileAttributes.NotContentIndexed);
+ }
+ catch (IOException)
+ {
+ // a hint only
+ }
+ catch (UnauthorizedAccessException)
+ {
+ // a hint only
+ }
+ _file.SetLength(HeaderSize + (Capacity - firstFrame) * FrameBytes);
+ _handle = _file.SafeFileHandle;
+ WriteHeader(firstFrame);
+ }
+ catch
+ {
+ _file.Dispose();
+ _file = null;
+ _handle = null;
+ throw;
+ }
}
+ private void WriteHeader(int firstFrame)
+ {
+ Span<byte> header = stackalloc byte[HeaderSize];
+ BitConverter.TryWriteBytes(header, Magic);
+ BitConverter.TryWriteBytes(header[4..], Version);
+ BitConverter.TryWriteBytes(header[8..], Width);
+ BitConverter.TryWriteBytes(header[12..], Height);
+ BitConverter.TryWriteBytes(header[16..], (int)Layers);
+ BitConverter.TryWriteBytes(header[20..], VisualizeEvery);
+ BitConverter.TryWriteBytes(header[24..], Capacity);
+ BitConverter.TryWriteBytes(header[28..], firstFrame);
+ RandomAccess.Write(_handle!, header, 0);
+ }
}
diff --git a/WaveDude/WaveDude.csproj b/WaveDude/WaveDude.csproj
index 5d09cf4..005d4dd 100644
--- a/WaveDude/WaveDude.csproj
+++ b/WaveDude/WaveDude.csproj
@@ -9,6 +9,8 @@
<!-- optimised in every configuration: the engines' stencil loops run five times slower unoptimised, which
makes the CPU engine unusable from a Debug build of the app; set to false locally to step through them -->
<Optimize>true</Optimize>
+ <!-- the MP4 writer copies a frame into a Media Foundation buffer through its raw pointer -->
+ <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
</PropertyGroup>
<!-- the shipped colour schemes are part of the binary; the repo's ColorSchemeList folder is their source -->
diff --git a/_tools/library_check/Program.cs b/_tools/library_check/Program.cs
index d08db16..e6760e0 100644
--- a/_tools/library_check/Program.cs
+++ b/_tools/library_check/Program.cs
@@ -1,5 +1,6 @@
using System.Globalization;
using System.Diagnostics;
+using System.Numerics.Tensors;
using NLog;
using WaveDude.Engine;
using WaveDude.Model;
@@ -475,9 +476,9 @@ internal static class Program
Console.WriteLine("--- frame store");
string path = Path.Combine(Path.GetTempPath(), "library_check-" + Guid.NewGuid().ToString("N") + FrameCache.Extension);
var cpu = new WaveSimulator(scene, new EngineOptions(1.0, 1.0, true, false, 10.0, 1.0), Sources());
- using (var store = FrameStore.Create(path, scene.Width, scene.Height, FrameLayers.Field | FrameLayers.Intensity, 3, 2))
+ using (var store = FrameStore.Create(path, scene.Width, scene.Height, FrameLayers.Field | FrameLayers.Intensity, 3, 2, ramBudget: 0))
{
- Check(File.Exists(path) && new FileInfo(path).Length == store.TotalBytes, "file created and pre-sized (" + store.TotalBytes + " bytes)");
+ Check(store.RamFrames == 0 && store.HasFile && File.Exists(path) && new FileInfo(path).Length == store.FileBytes && store.FileBytes == FrameStore.HeaderSize + 3 * store.FrameBytes, "no budget: the file is created at once and pre-sized (" + store.FileBytes + " bytes)");
Check(store.Count == 0 && store.LayerCount == 2 && store.Has(FrameLayer.Intensity) && store.StepOf(2) == 4, "empty store reports its layout");
int written = 0;
store.FrameWritten += n => written = n;
@@ -533,6 +534,50 @@ internal static class Program
}
Check(!File.Exists(path), "file deleted on dispose");
Check(FrameStore.SizeOf(1920, 1080, FrameLayers.Field | FrameLayers.Intensity, 1250) == 64 + 1250L * 2 * 1920 * 1080 * 2, "SizeOf matches the layout");
+ Check(FrameStore.FramesInBudget(1920, 1080, FrameLayers.Field | FrameLayers.Intensity, 1L << 30) == 129 && FrameStore.FramesInBudget(64, 48, FrameLayers.Field, 0) == 0, "FramesInBudget: 129 full-HD frames of both planes per GB");
+
+ // the two tiers: a budget for two of five frames; the first two stay in memory, the other three go to the file
+ path = Path.Combine(Path.GetTempPath(), "library_check-tiers-" + Guid.NewGuid().ToString("N") + FrameCache.Extension);
+ using (var store = FrameStore.Create(path, scene.Width, scene.Height, FrameLayers.Field | FrameLayers.Intensity, 5, 2, ramBudget: 2L * 2 * scene.Width * scene.Height * 2))
+ {
+ Check(store.RamFrames == 2 && store.FirstSpilledFrame == 2 && store.HasFile && new FileInfo(path).Length == FrameStore.HeaderSize + 3 * store.FrameBytes, "budget for two frames: the file is sized for the other three");
+ float[][] fields = new float[5][];
+ for (int frame = 0; frame < 5; frame++)
+ {
+ Run(cpu, 2);
+ fields[frame] = (float[])cpu.FieldData.Clone();
+ store.Write(frame, cpu.FieldData, cpu.IntensityData, cpu.Stride);
+ }
+ Check(store.Count == 5 && store.FramesInMemory == 2 && store.FramesOnDisk == 3 && store.RamBytes == 2 * store.FrameBytes, "five frames: two in memory, three on disk");
+ bool same = true;
+ var copy = new Half[scene.Width * scene.Height];
+ for (int frame = 0; frame < 5 && same; frame++)
+ {
+ same = store.CopyLayer(frame, FrameLayer.Field, copy);
+ for (int y = 0; y < scene.Height && same; y++)
+ {
+ for (int x = 0; x < scene.Width; x++)
+ {
+ if (copy[y * scene.Width + x] != (Half)fields[frame][(y + 1) * cpu.Stride + x + 1])
+ {
+ same = false;
+ break;
+ }
+ }
+ }
+ }
+ Check(same, "every frame reads back from its tier");
+ }
+ Check(!File.Exists(path), "tiered store: file deleted on dispose");
+ // a run that fits never touches the disk
+ path = Path.Combine(Path.GetTempPath(), "library_check-ram-" + Guid.NewGuid().ToString("N") + FrameCache.Extension);
+ using (var store = FrameStore.Create(path, scene.Width, scene.Height, FrameLayers.Field, 3, 1, ramBudget: 1L << 30))
+ {
+ store.Write(0, cpu.FieldData, null, cpu.Stride);
+ Check(store.RamFrames == 3 && !store.HasFile && !File.Exists(path) && store.FileBytes == 0 && store.FirstSpilledFrame == 3, "a run within the budget creates no file");
+ }
+ Check(FrameMemory.PhysicalBytes() > 1L << 30 && FrameMemory.AvailableBytes() <= FrameMemory.PhysicalBytes() && FrameMemory.Budget(50) <= FrameMemory.PhysicalBytes() / 2 && FrameMemory.Budget(0) == 0,
+ "memory: " + FrameMemory.Gigabytes(FrameMemory.PhysicalBytes()) + " physical, " + FrameMemory.Gigabytes(FrameMemory.AvailableBytes()) + " available, budget at 50 % " + FrameMemory.Gigabytes(FrameMemory.Budget(50)));
// a full-HD store of 1 GB: the writes must run at memory speed and the dispose must not flush the
// dirty pages to disk (the file is deleted anyway; this used to take a minute for a 10 GB run)
@@ -545,11 +590,19 @@ internal static class Program
bigField[i] = (i % 97) / 97f - 0.5f;
bigIntensity[i] = (i % 89) / 89f;
}
+ // written the way the run does it: Half planes already converted (the engine's captures), no conversion in the store
+ var bigFieldHalf = new Half[bigW * bigH];
+ var bigIntensityHalf = new Half[bigW * bigH];
+ for (int y = 0; y < bigH; y++)
+ {
+ TensorPrimitives.ConvertToHalf(bigField.AsSpan((y + 1) * (bigW + 2) + 1, bigW), bigFieldHalf.AsSpan(y * bigW, bigW));
+ TensorPrimitives.ConvertToHalf(bigIntensity.AsSpan((y + 1) * (bigW + 2) + 1, bigW), bigIntensityHalf.AsSpan(y * bigW, bigW));
+ }
var clock = Stopwatch.StartNew();
var big = FrameStore.Create(path, bigW, bigH, FrameLayers.Field | FrameLayers.Intensity, bigFrames, 1);
for (int frame = 0; frame < bigFrames; frame++)
{
- big.Write(frame, bigField, bigIntensity, bigW + 2);
+ big.Write(frame, bigFieldHalf, bigIntensityHalf);
}
double writeMs = clock.Elapsed.TotalMilliseconds;
clock.Restart();
@@ -564,7 +617,7 @@ internal static class Program
clock.Restart();
big.Dispose();
double disposeMs = clock.Elapsed.TotalMilliseconds;
- Console.WriteLine($" 1 GB store: {writeMs:0} ms writing ({big.TotalBytes / writeMs / 1000:0} MB/s, {writeMs / bigFrames:0.0} ms/frame), {readMs:0} ms reading ({readMs / bigFrames:0.0} ms/frame), {disposeMs:0} ms dispose");
+ Console.WriteLine($" 1 GB store in memory ({big.FramesInMemory} of {bigFrames} frames): {writeMs:0} ms writing ({big.TotalBytes / writeMs / 1000:0} MB/s, {writeMs / bigFrames:0.0} ms/frame), {readMs:0} ms reading ({readMs / bigFrames:0.0} ms/frame), {disposeMs:0} ms dispose");
Check(!File.Exists(path), "big store deleted on dispose");
Check(disposeMs < 1500, "disposing a 1 GB store does not flush it to disk (" + disposeMs.ToString("0") + " ms)");
}