diff --git a/docs/temporal-spatial-evidence-reservoir.md b/docs/temporal-spatial-evidence-reservoir.md index 9bad62c..c0e9979 100644 --- a/docs/temporal-spatial-evidence-reservoir.md +++ b/docs/temporal-spatial-evidence-reservoir.md @@ -124,12 +124,18 @@ Built: frames scheduled update nodes as weighted reservoir candidates with a per-frame reservoir snapshot for debug and tests. It is the candidate source, not the full temporal/spatial reuse pass. +- `FractalProbeSample` is the first typed fractal SDF/detail sample shape for + the ReSTIR/GRIS path. It carries domain key, node key, local center, bound + radius, target contribution, source PDF, material delta, and payload handle. + `FractalProbeReuseValidator` currently proves domain lineage and local-shift + compatibility; renderer-facing camera, disocclusion, material, and visibility + checks still need to be added before temporal/spatial reuse is complete. Not built yet: - GPU reservoir buffers; -- temporal reprojection validation for fractal/SDF reservoirs; -- spatial neighbor reuse for fractal/SDF reservoirs; +- camera/disocclusion/material validation for fractal/SDF reservoirs; +- spatial neighbor reuse across screen tiles and cube-sphere neighbor domains; - GRIS-style domain shift mappings for nested `.aquageo` domains; - TAA guide-buffer weaving of reservoir confidence, age, and domain validity; - SSD/RAM residency queues driven by reservoir contribution estimates. diff --git a/research/rendering/fractal-brush-implementation-roadmap.md b/research/rendering/fractal-brush-implementation-roadmap.md index 2d975ae..77bcc12 100644 --- a/research/rendering/fractal-brush-implementation-roadmap.md +++ b/research/rendering/fractal-brush-implementation-roadmap.md @@ -335,10 +335,12 @@ Tasks: and feeds the next resource plan. - [x] Convert contribution-cache refresh into a candidate generator that submits weighted candidates to the resampled-importance core. -- [ ] Add fractal SDF probe candidate records: domain key, local frame, bound, +- [x] Add fractal SDF probe candidate records: domain key, local frame, bound, projected contribution target, source PDF, payload handle, and material delta. - [ ] Add temporal reuse validation: camera motion, domain ancestry, local-frame - error, bounds, and disocclusion/material compatibility. + error, bounds, and disocclusion/material compatibility. Domain ancestry and + local-shift checks exist; camera/disocclusion/material validation still need + renderer inputs. - [ ] Add spatial reuse validation across screen tiles and cube-sphere neighbor domains. - [ ] Feed reservoir confidence, selected target, candidate count, sample age, @@ -360,8 +362,8 @@ Tests: - near-threshold nodes keep nonzero update probability; - stale wrong score recovers after observations; - fixed camera path converges within tolerance; -- temporal reuse rejects mismatched domain ancestry; -- spatial reuse rejects invalid local-frame shifts; +- [x] temporal reuse rejects mismatched domain ancestry; +- [x] spatial reuse rejects invalid local-frame shifts; - TAA history confidence drops when reservoir validity changes; - update cost respects budget. diff --git a/src/Aquarium.Engine.Fractal/Lod/FractalProbeSample.cs b/src/Aquarium.Engine.Fractal/Lod/FractalProbeSample.cs new file mode 100644 index 0000000..640cb9b --- /dev/null +++ b/src/Aquarium.Engine.Fractal/Lod/FractalProbeSample.cs @@ -0,0 +1,94 @@ +using System.Numerics; +using Aquarium.Engine.Fractal.Grammar; +using Aquarium.Engine.Fractal.Temporal; + +namespace Aquarium.Engine.Fractal.Lod; + +public readonly record struct FractalProbeSample( + AquariumFractalKey DomainKey, + AquariumFractalKey NodeKey, + Vector3 LocalCenter, + float BoundRadius, + float TargetContribution, + float SourcePdf, + float MaterialDelta, + int PayloadHandle) +{ + public ResampledImportanceCandidate ToReservoirCandidate() + { + return new ResampledImportanceCandidate( + this, + MathF.Max(TargetContribution, 0.0f), + MathF.Max(SourcePdf, 1.0e-6f)); + } +} + +public enum FractalProbeReuseRejection +{ + None, + UnknownDomain, + DifferentLineage, + ExcessiveLocalShift, + InvalidBounds, +} + +public readonly record struct FractalProbeReuseResult( + bool CanReuse, + FractalProbeReuseRejection Rejection, + float LocalShift); + +public static class FractalProbeReuseValidator +{ + public static FractalProbeReuseResult Validate( + FractalProbeSample source, + FractalProbeSample target, + FractalDomainGraph domains, + float maxLocalShift) + { + ArgumentNullException.ThrowIfNull(domains); + if (maxLocalShift < 0.0f) + { + throw new ArgumentOutOfRangeException(nameof(maxLocalShift), maxLocalShift, "Maximum local shift must not be negative."); + } + + if (!float.IsFinite(source.BoundRadius) || !float.IsFinite(target.BoundRadius) || source.BoundRadius <= 0.0f || target.BoundRadius <= 0.0f) + { + return new FractalProbeReuseResult(false, FractalProbeReuseRejection.InvalidBounds, 0.0f); + } + + if (!domains.Contains(source.DomainKey) || !domains.Contains(target.DomainKey)) + { + return new FractalProbeReuseResult(false, FractalProbeReuseRejection.UnknownDomain, 0.0f); + } + + if (!ShareLineage(source.DomainKey, target.DomainKey, domains)) + { + return new FractalProbeReuseResult(false, FractalProbeReuseRejection.DifferentLineage, 0.0f); + } + + var localShift = Vector3.Distance(source.LocalCenter, target.LocalCenter); + var allowedShift = MathF.Min(maxLocalShift, source.BoundRadius + target.BoundRadius); + if (!float.IsFinite(localShift) || localShift > allowedShift) + { + return new FractalProbeReuseResult(false, FractalProbeReuseRejection.ExcessiveLocalShift, localShift); + } + + return new FractalProbeReuseResult(true, FractalProbeReuseRejection.None, localShift); + } + + private static bool ShareLineage(AquariumFractalKey sourceDomain, AquariumFractalKey targetDomain, FractalDomainGraph domains) + { + var sourcePath = domains.GetPath(sourceDomain).Select(domain => domain.Key).ToArray(); + var targetPath = domains.GetPath(targetDomain).Select(domain => domain.Key).ToArray(); + var shorterLength = Math.Min(sourcePath.Length, targetPath.Length); + for (var index = 0; index < shorterLength; index++) + { + if (!sourcePath[index].Equals(targetPath[index])) + { + return false; + } + } + + return shorterLength == sourcePath.Length || shorterLength == targetPath.Length; + } +} diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 0c8d3fb..48ba60f 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -160,3 +160,4 @@ {"timestamp":"2026-05-19T16:27:00+01:00","topic":"zyphos-fractal-domain-debug-mode","lesson":"Render debug mode 11 now exposes a client fractal-domain view. Zyphos colors cube faces, draws an 8x8 tile grid, and overlays authored brush material influence so face/tile/material packet mapping can be inspected from the renderer instead of inferred from final beauty shading.","files":["src/Aquarium.Engine.Contracts/GraphicsSettings.cs","src/Aquarium.Engine/Render/D3D12Renderer.cs","src/Aquarium.Zyphos/Shaders/D3D12ZyphosPlanet.hlsl","research/rendering/fractal-brush-implementation-roadmap.md"],"source":"roadmap called for face/tile/LOD/cache debug modes; this is the first renderer-visible face/tile/material influence slice"} {"timestamp":"2026-05-19T17:35:00+01:00","topic":"restir-reservoir-core","lesson":"The previous stable-key temporal smoother was not ReSTIR. Aquarium now treats `ResampledImportanceReservoir` as the RIS/ReSTIR math authority: selected sample, target value, weight sum, represented candidate count, merge, and contribution weight. `TemporalSpatialEvidenceReservoir` is a stable resolved-track layer, while fractal contribution scoring should become a candidate generator feeding reservoir resampling with temporal/spatial/domain validation and TAA guide-buffer integration.","files":["src/Aquarium.Engine.Fractal/Temporal/ResampledImportanceCandidate.cs","src/Aquarium.Engine.Fractal/Temporal/ResampledImportanceReservoir.cs","tests/Aquarium.Engine.Fractal.Tests/ResampledImportanceReservoirTests.cs","docs/temporal-spatial-evidence-reservoir.md","research/rendering/fractal-brush-implementation-roadmap.md","state/map.yaml","state/memory.json"],"source":"user corrected the architecture toward NVIDIA ReSTIR/GRIS rather than invented spatiotemporal reservoir sampling"} {"timestamp":"2026-05-19T18:03:00+01:00","topic":"fractal-contribution-candidates","lesson":"FractalContributionCache now frames scheduled update nodes as weighted `ResampledImportanceReservoir` candidates and exposes a per-frame reservoir snapshot for debug/tests. This is the handoff from heuristic LOD scoring into reservoir evidence; temporal/spatial reuse and domain shift validation still need to be built explicitly before calling the fractal path ReSTIR-complete.","files":["src/Aquarium.Engine.Fractal/Lod/FractalContributionCandidate.cs","src/Aquarium.Engine.Fractal/Lod/FractalContributionCache.cs","tests/Aquarium.Engine.Fractal.Tests/FractalContributionCacheTests.cs","docs/temporal-spatial-evidence-reservoir.md","research/rendering/fractal-brush-implementation-roadmap.md","state/memory.json"],"source":"continued Perfect Machine work after adding the ReSTIR-style reservoir core"} +{"timestamp":"2026-05-19T18:24:00+01:00","topic":"fractal-probe-reservoir-samples","lesson":"Fractal SDF/detail reservoir candidates now have a typed probe sample: domain key, node key, local center, bound radius, target contribution, source PDF, material delta, and payload handle. `FractalProbeReuseValidator` rejects unknown domains, sibling-domain reuse, invalid bounds, and excessive local shift. This starts the GRIS-style domain-shift boundary; renderer inputs for camera motion, disocclusion, material compatibility, and visibility still need to be wired before reuse is complete.","files":["src/Aquarium.Engine.Fractal/Lod/FractalProbeSample.cs","tests/Aquarium.Engine.Fractal.Tests/FractalProbeSampleTests.cs","docs/temporal-spatial-evidence-reservoir.md","research/rendering/fractal-brush-implementation-roadmap.md"],"source":"continued Perfect Machine work after connecting fractal contribution updates to reservoir candidates"} diff --git a/state/memory.json b/state/memory.json index fc574ed..fe35a9c 100644 --- a/state/memory.json +++ b/state/memory.json @@ -90,6 +90,7 @@ "Zyphos traced planet geometry may sample only a hard-budgeted top-influence subset of authored fractal brush packets in `sdfDistance`; the current proven budget is four brushes after sorting selected packets by abs(amplitude)*max(radius). A 12-brush distance loop was tested and rejected because it pushed the live frame to about 33 ms; the four-brush loop returns the live view to about 16.4 ms while full packet richness remains available to post-hit material/detail.", "Temporal resolve has a cache-facing detail lane: SdfSurface.temporalDetail writes through scene-control.z into history-control.z, and D3D12Post reduces history confidence when current and previous temporal detail disagree. Use this lane for stochastic fractal/cache stability signals, not as geometry authority.", "FractalContributionCache is the live cache loop: each frame builds a resource plan from current summaries and cached states, stochastically observes only budgeted update nodes, stores mean/variance/confidence/sample age through FractalContributionEstimator, frames scheduled updates as weighted ResampledImportanceReservoir candidates, and lets backend packet compilation stay cached by selected-cut key. It is a candidate source, not the whole temporal/spatial reuse pass. Do not replace this with a static plan cache that stops learning after the first camera bucket.", + "FractalProbeSample is the typed reservoir sample shape for fractal SDF/detail reuse: domain key, node key, local center, bound radius, target contribution, source PDF, material delta, and payload handle. Reuse must pass domain lineage and local-shift validation now, and later camera motion, disocclusion, material compatibility, and visibility validation before it is allowed into temporal/spatial reuse.", "Zyphos camera distance limits belong to the selected spatial domain, not one global planetary clamp. Leaf/pebble domains must be able to zoom below whole-body distances, and the parent star must be a visible SDF body when it is also the primary light source.", "The consolidated fractal brush architecture lives in research/rendering/fractal-brush-architecture-plan.md. Its pipeline is client intent -> domain roots -> semantic IFS brush grammar -> ownership tree -> node summaries -> contribution cache/residency scheduler -> backend packets -> renderer passes -> debug/evidence. Its credibility depends on module boundaries and tests: contracts, pure CPU fractal core, D3D12 backend, client adapters, mock payload/probe/random/clock seams, shader parity tests, and deterministic performance fixtures.", "The actionable fractal brush roadmap lives in research/rendering/fractal-brush-implementation-roadmap.md. Start with the first work packet: add Aquarium.Engine.Fractal and tests, cube-face/tile key types, identity and tangent projection candidates, an area distortion sampler, face-edge tests, and a projection report before touching recursive detail." diff --git a/tests/Aquarium.Engine.Fractal.Tests/FractalProbeSampleTests.cs b/tests/Aquarium.Engine.Fractal.Tests/FractalProbeSampleTests.cs new file mode 100644 index 0000000..7a921c8 --- /dev/null +++ b/tests/Aquarium.Engine.Fractal.Tests/FractalProbeSampleTests.cs @@ -0,0 +1,101 @@ +using System.Numerics; +using Aquarium.Engine.Fractal; +using Aquarium.Engine.Fractal.Grammar; +using Aquarium.Engine.Fractal.Lod; + +namespace Aquarium.Engine.Fractal.Tests; + +public sealed class FractalProbeSampleTests +{ + [Fact] + public void ProbeSampleBuildsReservoirCandidateFromTargetAndSourcePdf() + { + var sample = Probe("zyphos/surface", Vector3.Zero, target: 4.0f, sourcePdf: 0.5f); + + var candidate = sample.ToReservoirCandidate(); + + Assert.Equal(sample, candidate.Sample); + Assert.Equal(4.0f, candidate.Target); + Assert.Equal(0.5f, candidate.SourcePdf); + Assert.Equal(8.0f, candidate.ImportanceWeight); + } + + [Fact] + public void ReuseValidatorAllowsSameLineageWithinLocalShiftBound() + { + var graph = DomainGraph(); + var source = Probe("zyphos/surface", Vector3.Zero); + var target = Probe("zyphos/surface/forest", new Vector3(0.25f, 0.0f, 0.0f)); + + var result = FractalProbeReuseValidator.Validate(source, target, graph, maxLocalShift: 0.5f); + + Assert.True(result.CanReuse); + Assert.Equal(FractalProbeReuseRejection.None, result.Rejection); + Assert.InRange(result.LocalShift, 0.24f, 0.26f); + } + + [Fact] + public void ReuseValidatorRejectsSiblingPlanetDomains() + { + var graph = DomainGraph(); + var source = Probe("zyphos/surface", Vector3.Zero); + var target = Probe("umbros/surface", Vector3.Zero); + + var result = FractalProbeReuseValidator.Validate(source, target, graph, maxLocalShift: 1.0f); + + Assert.False(result.CanReuse); + Assert.Equal(FractalProbeReuseRejection.DifferentLineage, result.Rejection); + } + + [Fact] + public void ReuseValidatorRejectsExcessiveLocalShift() + { + var graph = DomainGraph(); + var source = Probe("zyphos/surface", Vector3.Zero); + var target = Probe("zyphos/surface", new Vector3(2.0f, 0.0f, 0.0f)); + + var result = FractalProbeReuseValidator.Validate(source, target, graph, maxLocalShift: 0.5f); + + Assert.False(result.CanReuse); + Assert.Equal(FractalProbeReuseRejection.ExcessiveLocalShift, result.Rejection); + } + + private static FractalProbeSample Probe( + string domainKey, + Vector3 localCenter, + float target = 1.0f, + float sourcePdf = 1.0f) + { + return new FractalProbeSample( + new AquariumFractalKey(domainKey), + new AquariumFractalKey($"{domainKey}/node"), + localCenter, + BoundRadius: 0.5f, + TargetContribution: target, + SourcePdf: sourcePdf, + MaterialDelta: 0.25f, + PayloadHandle: 7); + } + + private static FractalDomainGraph DomainGraph() + { + return new FractalDomainGraph([ + Domain("solar", AquariumFractalDomainKind.Solar, parent: null), + Domain("zyphos", AquariumFractalDomainKind.Planetary, "solar"), + Domain("zyphos/surface", AquariumFractalDomainKind.Surface2D, "zyphos"), + Domain("zyphos/surface/forest", AquariumFractalDomainKind.Surface2D, "zyphos/surface"), + Domain("umbros", AquariumFractalDomainKind.Planetary, "solar"), + Domain("umbros/surface", AquariumFractalDomainKind.Surface2D, "umbros"), + ]); + } + + private static AquariumFractalDomain Domain(string key, AquariumFractalDomainKind kind, string? parent) + { + return new AquariumFractalDomain( + new AquariumFractalKey(key), + kind, + parent is null ? default : new AquariumFractalKey(parent), + Vector4.Zero, + Vector4.Zero); + } +}