Add fractal probe reservoir samples
This commit is contained in:
parent
ddcac6dd49
commit
c68a0e656e
6 changed files with 211 additions and 6 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
94
src/Aquarium.Engine.Fractal/Lod/FractalProbeSample.cs
Normal file
94
src/Aquarium.Engine.Fractal/Lod/FractalProbeSample.cs
Normal 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;
|
||||
}
|
||||
}
|
||||
|
|
@ -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"}
|
||||
|
|
|
|||
|
|
@ -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."
|
||||
|
|
|
|||
101
tests/Aquarium.Engine.Fractal.Tests/FractalProbeSampleTests.cs
Normal file
101
tests/Aquarium.Engine.Fractal.Tests/FractalProbeSampleTests.cs
Normal 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);
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue