Add fractal probe reservoir samples

This commit is contained in:
Meta Vens 2026-05-19 15:07:10 +01:00
commit c68a0e656e
6 changed files with 211 additions and 6 deletions

View file

@ -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.

View file

@ -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.

View file

@ -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<FractalProbeSample> ToReservoirCandidate()
{
return new ResampledImportanceCandidate<FractalProbeSample>(
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;
}
}

View file

@ -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<TSample>` 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<FractalContributionCandidate>` 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"}

View file

@ -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."

View file

@ -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);
}
}