Define GPU-resident tube spline lowering

This commit is contained in:
Meta Vens 2026-05-26 18:51:47 +01:00
commit bcea3338bd
8 changed files with 284 additions and 18 deletions

View file

@ -238,6 +238,68 @@ public readonly record struct AquariumFieldBackendPacket(
Support.HasSupport;
}
public readonly record struct AquariumFieldTubeSplineLowering(
string LoweringKey,
string ClaimKey,
string ResourceKey,
int Width,
int Height,
int StrideBytes,
int FirstColumn,
int ColumnCount,
int ColumnStride,
int RollingModulo,
int RollingOffset,
Vector3 Origin,
Vector3 AxisStep,
Vector3 ColumnStep,
float AmplitudePower,
float AmplitudeScale,
float NormalizeMin,
float NormalizeMax,
float BaseRadius,
float RadiusScale,
float Alpha,
float Feather,
string RampTexturePath,
float EmissionScale,
int CatmullRomSubdivisions)
{
public bool IsValid =>
!string.IsNullOrWhiteSpace(LoweringKey) &&
!string.IsNullOrWhiteSpace(ClaimKey) &&
!string.IsNullOrWhiteSpace(ResourceKey) &&
Width > 1 &&
Height > 0 &&
StrideBytes > 0 &&
ColumnCount > 0 &&
ColumnStride > 0 &&
NormalizeMax > NormalizeMin &&
BaseRadius > 0.0f &&
RadiusScale >= 0.0f &&
EmissionScale >= 0.0f &&
CatmullRomSubdivisions > 0;
public AquariumFieldTubeSplineLowering Normalized() => this with
{
Width = Math.Max(2, Width),
Height = Math.Max(1, Height),
StrideBytes = Math.Max(4, StrideBytes),
FirstColumn = Math.Max(0, FirstColumn),
ColumnCount = Math.Max(1, ColumnCount),
ColumnStride = Math.Max(1, ColumnStride),
RollingModulo = Math.Max(0, RollingModulo),
AmplitudePower = MathF.Max(0.0001f, AmplitudePower),
NormalizeMax = NormalizeMax <= NormalizeMin ? NormalizeMin + 1.0f : NormalizeMax,
BaseRadius = MathF.Max(0.0001f, BaseRadius),
RadiusScale = MathF.Max(0.0f, RadiusScale),
Alpha = Math.Clamp(Alpha, 0.0f, 1.0f),
Feather = MathF.Max(0.0001f, Feather),
EmissionScale = MathF.Max(0.0f, EmissionScale),
CatmullRomSubdivisions = Math.Clamp(CatmullRomSubdivisions, 1, 16),
};
}
public readonly record struct AquariumFieldResourceDeclaration(
string ResourceKey,
AquariumFieldResourceKind Kind,
@ -285,6 +347,8 @@ public sealed class AquariumFieldEvidenceFrame
public IReadOnlyList<AquariumFieldResourceDeclaration> Resources { get; init; } = [];
public IReadOnlyList<AquariumFieldTubeSplineLowering> TubeSplineLowerings { get; init; } = [];
public float AccumulationWindowSeconds { get; init; }
public float PresentationDelaySeconds { get; init; }
@ -294,7 +358,8 @@ public sealed class AquariumFieldEvidenceFrame
Claims.Count > 0 ||
Candidates.Count > 0 ||
BackendPackets.Count > 0 ||
Resources.Count > 0;
Resources.Count > 0 ||
TubeSplineLowerings.Count > 0;
}
public readonly record struct AquariumFieldEvidenceIssue(
@ -492,6 +557,25 @@ public static class AquariumFieldEvidenceValidator
}
}
foreach (var lowering in frame.TubeSplineLowerings)
{
if (!lowering.IsValid)
{
issues.Add(Error(string.IsNullOrWhiteSpace(lowering.LoweringKey) ? "tube-spline-lowering" : lowering.LoweringKey, "Tube spline lowering is missing identity, shape, normalization, or style."));
continue;
}
if (!claimKeys.Contains(lowering.ClaimKey))
{
issues.Add(Error(lowering.LoweringKey, $"Tube spline lowering references unknown claim '{lowering.ClaimKey}'."));
}
if (!resourceKeys.Contains(lowering.ResourceKey))
{
issues.Add(Error(lowering.LoweringKey, $"Tube spline lowering references unknown resource '{lowering.ResourceKey}'."));
}
}
return issues.Count == 0
? AquariumFieldEvidenceValidationReport.Empty
: new AquariumFieldEvidenceValidationReport(issues);

View file

@ -16,6 +16,7 @@ public static class AquariumFieldScriptCompiler
var domains = new List<AquariumFieldDomain>();
var claims = new List<AquariumFieldClaim>();
var candidates = new List<AquariumFieldCandidate>();
var tubeSplineLowerings = new List<AquariumFieldTubeSplineLowering>();
var resourceAliases = new Dictionary<string, AquariumFieldResourceDeclaration>(StringComparer.Ordinal);
var domainKeys = new HashSet<string>(StringComparer.Ordinal);
@ -46,6 +47,9 @@ public static class AquariumFieldScriptCompiler
case "tubeclaim":
AddTubeClaim(args, resourceAliases, domainKeys, domains, claims, candidates, lineIndex);
break;
case "tubespline":
AddTubeSpline(args, resourceAliases, domainKeys, domains, claims, candidates, tubeSplineLowerings, lineIndex);
break;
default:
throw new FormatException($"Unknown field evidence DSL command `{tokens[0]}` at line {lineIndex + 1}.");
}
@ -57,6 +61,7 @@ public static class AquariumFieldScriptCompiler
Domains = domains,
Claims = claims,
Candidates = candidates,
TubeSplineLowerings = tubeSplineLowerings,
};
var validation = AquariumFieldEvidenceValidator.Validate(frame);
if (validation.HasErrors)
@ -242,6 +247,50 @@ public static class AquariumFieldScriptCompiler
Guide: AquariumFieldGuide.Valid(confidence, Float(args, "age", 0.0f, lineIndex))));
}
private static void AddTubeSpline(
IReadOnlyDictionary<string, string> args,
IReadOnlyDictionary<string, AquariumFieldResourceDeclaration> resourceAliases,
ISet<string> domainKeys,
ICollection<AquariumFieldDomain> domains,
ICollection<AquariumFieldClaim> claims,
ICollection<AquariumFieldCandidate> candidates,
ICollection<AquariumFieldTubeSplineLowering> lowerings,
int lineIndex)
{
var id = Required(args, "id", lineIndex);
AddTubeClaim(args, resourceAliases, domainKeys, domains, claims, candidates, lineIndex);
var claimKey = $"dsl:tube:{id}";
var resourceId = Required(args, "resource", lineIndex);
var resource = resourceAliases[resourceId];
var lowering = new AquariumFieldTubeSplineLowering(
LoweringKey: $"dsl:tube-spline:{id}",
ClaimKey: claimKey,
ResourceKey: resource.ResourceKey,
Width: Int(args, "width", Math.Max(2, resource.Width), lineIndex),
Height: Int(args, "height", Math.Max(1, resource.Height), lineIndex),
StrideBytes: Int(args, "stride", Math.Max(4, resource.StrideBytes), lineIndex),
FirstColumn: Int(args, "firstColumn", 0, lineIndex),
ColumnCount: Int(args, "columns", Math.Max(1, resource.Height), lineIndex),
ColumnStride: Int(args, "columnStride", 1, lineIndex),
RollingModulo: Int(args, "rollingModulo", Math.Max(0, resource.Height), lineIndex),
RollingOffset: Int(args, "rollingOffset", 0, lineIndex),
Origin: Vec3(args, "origin", new Vector3(-0.78f, -0.52f, -0.10f), lineIndex),
AxisStep: Vec3(args, "axisStep", new Vector3(0.016f, 0.0f, 0.0f), lineIndex),
ColumnStep: Vec3(args, "columnStep", new Vector3(0.0f, 0.0f, 0.030f), lineIndex),
AmplitudePower: Float(args, "amplitudePower", 2.0f, lineIndex),
AmplitudeScale: Float(args, "amplitudeScale", 0.42f, lineIndex),
NormalizeMin: Float(args, "normalizeMin", 0.0f, lineIndex),
NormalizeMax: Float(args, "normalizeMax", 1.0f, lineIndex),
BaseRadius: Float(args, "radius", 0.012f, lineIndex),
RadiusScale: Float(args, "radiusScale", 0.030f, lineIndex),
Alpha: Float(args, "alpha", 0.92f, lineIndex),
Feather: Float(args, "feather", 0.20f, lineIndex),
RampTexturePath: StringValue(args, "ramp", ""),
EmissionScale: Float(args, "emissionScale", 10.0f, lineIndex),
CatmullRomSubdivisions: Int(args, "subdivisions", 4, lineIndex)).Normalized();
lowerings.Add(lowering);
}
private static AquariumTextureSplineFieldProgram ParseSplineField(
IReadOnlyDictionary<string, string> args,
IReadOnlyList<AquariumFieldGraphNode> surfaceNodes,

View file

@ -1,3 +1,4 @@
using SharpGen.Runtime;
using Vortice.Direct3D12;
namespace Aquarium.Engine.Render;
@ -49,9 +50,16 @@ internal sealed class D3D12FieldResourceRegistry : IDisposable
if (declaration.Kind is AquariumFieldResourceKind.StructuredBuffer or AquariumFieldResourceKind.CurvePointBuffer)
{
ResolveStructuredBuffer(device, resourceRegistry, declaration);
resolved++;
structuredBufferCount++;
if (ResolveStructuredBuffer(device, resourceRegistry, declaration))
{
resolved++;
structuredBufferCount++;
}
else
{
unsupported++;
}
continue;
}
@ -78,7 +86,7 @@ internal sealed class D3D12FieldResourceRegistry : IDisposable
liveKeys.Clear();
}
private void ResolveStructuredBuffer(
private bool ResolveStructuredBuffer(
ID3D12Device device,
D3D12ResourceRegistry resourceRegistry,
AquariumFieldResourceDeclaration declaration)
@ -94,7 +102,7 @@ internal sealed class D3D12FieldResourceRegistry : IDisposable
existing.AllowUnorderedAccess == allowUnorderedAccess &&
existing.Version == declaration.Version)
{
return;
return true;
}
var registryKey = RegistryKey(declaration.ResourceKey);
@ -104,12 +112,19 @@ internal sealed class D3D12FieldResourceRegistry : IDisposable
existing.Buffer.Dispose();
}
var buffer = new D3D12StructuredBuffer(
device,
elementCount,
strideBytes,
$"Aquarium D3D12 Field Resource {declaration.ResourceKey}",
allowUnorderedAccess);
var buffer = declaration.Residency == AquariumFieldResourceResidency.SharedGpu
? OpenSharedStructuredBuffer(device, declaration, elementCount, strideBytes)
: new D3D12StructuredBuffer(
device,
elementCount,
strideBytes,
$"Aquarium D3D12 Field Resource {declaration.ResourceKey}",
allowUnorderedAccess);
if (buffer is null)
{
return false;
}
resourceRegistry.Add(registryKey, buffer);
structuredBuffers[declaration.ResourceKey] = new StructuredBufferSlot(
@ -118,6 +133,7 @@ internal sealed class D3D12FieldResourceRegistry : IDisposable
strideBytes,
allowUnorderedAccess,
declaration.Version);
return true;
}
private int RemoveStaleStructuredBuffers(D3D12ResourceRegistry resourceRegistry, HashSet<string> currentKeys)
@ -141,6 +157,37 @@ internal sealed class D3D12FieldResourceRegistry : IDisposable
private static string RegistryKey(string resourceKey) => RegistryPrefix + resourceKey;
private static D3D12StructuredBuffer? OpenSharedStructuredBuffer(
ID3D12Device device,
AquariumFieldResourceDeclaration declaration,
int elementCount,
int strideBytes)
{
if (declaration.NativeHandle == IntPtr.Zero)
{
return null;
}
try
{
var resource = device.OpenSharedHandle<ID3D12Resource>(declaration.NativeHandle);
resource.Name = $"Aquarium D3D12 Shared Field Resource {declaration.ResourceKey}";
return new D3D12StructuredBuffer(
resource,
elementCount,
strideBytes,
ResourceStates.PixelShaderResource | ResourceStates.NonPixelShaderResource);
}
catch (SharpGenException)
{
return null;
}
catch (InvalidOperationException)
{
return null;
}
}
private sealed record StructuredBufferSlot(
D3D12StructuredBuffer Buffer,
int ElementCount,

View file

@ -24,6 +24,16 @@ internal sealed class D3D12StructuredBuffer : IDisposable
Resource.Name = name;
}
public D3D12StructuredBuffer(ID3D12Resource resource, int elementCount, int strideBytes, ResourceStates initialState)
{
ArgumentNullException.ThrowIfNull(resource);
this.elementCount = elementCount;
this.strideBytes = strideBytes;
SizeBytes = elementCount * strideBytes;
Resource = resource;
State = initialState;
}
public ID3D12Resource Resource { get; }
public int ElementCount => elementCount;

View file

@ -234,3 +234,4 @@
{"lesson":"D3D12Renderer now consumes AquariumSceneState.FieldEvidenceFrame at the renderer boundary as planning telemetry. Each frame validates field evidence, builds the conservative backend-lowering plan, and exposes counts for domains, claims, candidates, producer packets, planned packets, deferred requests, and validation issues in debug/console. It does not render these packets yet, preserving the migration order. Fensalir.sln builds cleanly and Mimir.slnx builds against the integrated path.","timestamp":"2026-05-26T15:02:00+01:00","files":["src/Aquarium.Engine/Render/D3D12Renderer.cs"],"source":"continued rendering rebuild Phase 1","topic":"renderer-field-evidence-ingest"}
{"lesson":"Field packet payload handles are now demoted behind typed resource declarations. AquariumFieldEvidenceFrame carries AquariumFieldResourceDeclaration rows; validation rejects unknown resource references; the lowering planner defers resource-backed encodings without declared GPU-visible compatible resources; AquariumFieldScriptCompiler.CompileEvidence can bind declared resources and produce planned TubeField packets. D3D12Renderer debug/console summaries now show resource counts. Visible rendering remains blocked on the D3D12 packet/resource resolver that imports or aliases structured buffers, textures, meshes, surface pages, and volumes and binds them to selected shader lowerings.","timestamp":"2026-05-26T16:42:47+01:00","files":["src/Aquarium.Engine.Contracts/Render/AquariumFieldEvidence.cs","src/Aquarium.Engine.Contracts/Render/AquariumFieldScriptCompiler.cs","src/Aquarium.Engine/Render/D3D12Renderer.cs","state/map.yaml"],"source":"continued Mimir/Fensalir field resource boundary implementation","topic":"field-resource-declarations"}
{"lesson":"The corrected Mimir/Fensalir resource boundary is in-process engine ownership, not a cross-process payload authority. D3D12Renderer now owns a D3D12FieldResourceRegistry that resolves valid AquariumFieldResourceDeclaration rows into Fensalir-owned structured/curve buffer slots, reuses unchanged slots, recreates changed shape/access/version, and retires stale slots from the renderer resource registry. Duplicate resource keys are validation errors. Visible rendering is no longer blocked on ownership resolution for structured TubeField payloads; it is blocked on shader binding selected TubeField packets to the resolved slots, with texture, mesh, surface-page, and volume resolvers still future cuts. dotnet build Fensalir.sln --no-restore passed with 0 warnings; dotnet test tests/Aquarium.Engine.Tests/Aquarium.Engine.Tests.csproj --no-restore passed with 16 tests.","timestamp":"2026-05-26T17:29:30+01:00","files":["src/Aquarium.Engine/Render/D3D12FieldResourceRegistry.cs","src/Aquarium.Engine/Render/D3D12Renderer.cs","src/Aquarium.Engine.Contracts/Render/AquariumFieldEvidence.cs","tests/Aquarium.Engine.Tests/FieldEvidenceContractTests.cs","state/map.yaml"],"source":"continued Mimir/Fensalir field resource boundary implementation","topic":"d3d12-field-resource-registry"}
{"lesson":"Rendering-relevant field buffers must be GPU-resident early and stay GPU-resident. The TubeField contract now has an explicit AquariumFieldTubeSplineLowering/DSL command for interpreting a 2D rolling Float32 buffer as Catmull-Rom XY tubes with modulo column addressing, amplitude power/normalization, radius scaling, ramp texture path, and emission scale. D3D12FieldResourceRegistry no longer creates duplicate empty buffers for SharedGpu declarations: shared structured/curve resources must import by GPU handle or remain unsupported; allocation is only for Fensalir-owned GPU-resident producer slots. Visible TubeField rendering remains blocked on shader-side expansion/binding over the GPU slot, not CPU spline tessellation. Fensalir.sln builds cleanly; Aquarium.Engine.Tests passed with 17 tests.","timestamp":"2026-05-26T18:50:34+01:00","files":["src/Aquarium.Engine.Contracts/Render/AquariumFieldEvidence.cs","src/Aquarium.Engine.Contracts/Render/AquariumFieldScriptCompiler.cs","src/Aquarium.Engine/Render/D3D12FieldResourceRegistry.cs","src/Aquarium.Engine/Render/D3D12StructuredBuffer.cs","tests/Aquarium.Engine.Tests/FieldScriptCompilerTests.cs","state/map.yaml"],"source":"user clarified GPU-resident no-copy rendering buffer invariant","topic":"gpu-resident-tubefield-dsl"}

View file

@ -65,6 +65,10 @@ invariants:
kind, GPU residency, shader access, format, shape, validity, version, and
native handle metadata. Missing, CPU-only, or backend-incompatible resources
defer lowering instead of becoming visible evidence.
- Rendering-relevant field buffers move to GPU residency as early as possible
and stay there. Fensalir must pass GPU resource handles/SRVs/UAVs between
compute and render lowerings; CPU readback or CPU tessellation is a
diagnostic-only escape hatch, not the live TubeField path.
next_actions:
- Keep origin pointed at https://github.com/GameCult/Fensalir.git.
@ -72,12 +76,14 @@ next_actions:
- Cut the rendering rebuild through explicit field-domain/field-claim
contracts before adding another backend-specific visual path.
- Extend the D3D12 field packet/resource resolver beyond its first
Fensalir-owned structured-buffer slot cut. Current contracts, DSL, and
renderer registry can validate, plan, allocate, reuse, and retire
GPU-visible structured/curve buffer resources for resource-backed
TubeField packets. Visible rendering is now blocked on binding those
resolved slots into a concrete shader lowering, then adding honest
texture, mesh, surface-page, and volume resource resolvers.
structured/curve-buffer cut. Current contracts, DSL, and renderer registry
can validate and plan resource-backed TubeField packets, import shared GPU
structured buffers by handle, and allocate Fensalir-owned GPU-resident
slots only when Fensalir is the producer. The TubeField DSL can now express
a 2D rolling float buffer as Catmull-Rom XY tubes with modulo column
addressing, amplitude power/normalization, radius, ramp texture path, and
emission scale. Visible rendering is blocked on shader-side expansion and
binding of those GPU-resident slots, not CPU conversion to spline vertices.
- Move any remaining client-only Epiphany state found here back to `E:\Projects\Aquarium-Engine`.
- Keep Mimir app/adapters out of this repo; Fensalir may expose generic sensor-fusion contracts only.
- Package contracts/host deliberately before replacing sibling source references in client repos.

View file

@ -437,6 +437,35 @@ tubeclaim id=spectrum-trail resource=spectrum domain=mimir:spectrum:asio-ch0 con
AquariumFieldGuide.Valid(0.91f, sampleAgeSeconds: 0.016f),
"mimir:resource:native-ring:asio-ch0")
],
TubeSplineLowerings =
[
new AquariumFieldTubeSplineLowering(
"tube-spline:mimir:spectrum:asio-ch0:42",
"claim:mimir:spectrum:asio-ch0:42",
"mimir:resource:native-ring:asio-ch0",
Width: 64,
Height: 8,
StrideBytes: 4,
FirstColumn: 0,
ColumnCount: 4,
ColumnStride: 1,
RollingModulo: 8,
RollingOffset: 0,
Origin: Vector3.Zero,
AxisStep: new Vector3(0.01f, 0.0f, 0.0f),
ColumnStep: new Vector3(0.0f, 0.0f, 0.02f),
AmplitudePower: 2.0f,
AmplitudeScale: 0.25f,
NormalizeMin: 0.0f,
NormalizeMax: 1.0f,
BaseRadius: 0.01f,
RadiusScale: 0.02f,
Alpha: 1.0f,
Feather: 0.2f,
RampTexturePath: @"D:\WIP4\Projects\Aetheria\Assets\Resources\Ramps\blackbody.png",
EmissionScale: 10.0f,
CatmullRomSubdivisions: 4)
],
};
}
}

View file

@ -45,4 +45,44 @@ public sealed class FieldScriptCompilerTests
Assert.Equal(0.5f, frame.LoweringPolicy.LodBias);
Assert.True(frame.UseReservoirLowering);
}
[Fact]
public void CompileEvidenceParsesTubeSplineLoweringForRollingFloatBuffers()
{
var resource = new AquariumFieldResourceDeclaration(
"mimir:resource:log-mel",
AquariumFieldResourceKind.StructuredBuffer,
AquariumFieldResourceResidency.SharedGpu,
AquariumFieldShaderAccess.ShaderResource,
"Float32",
Width: 64,
Height: 32,
DepthOrCount: 2048,
StrideBytes: 4,
ValidFromNs: 0,
ValidUntilNs: 10_000,
Version: 7,
NativeHandle: IntPtr.Zero,
NativeHandleKind: "fensalir-buffer");
var frame = AquariumFieldScriptCompiler.CompileEvidence(
"""
resource id=mel key=mimir:resource:log-mel
tubespline id=mel-field resource=mel domain=mimir:log-mel width=64 height=32 stride=4 firstColumn=3 columns=8 columnStride=1 rollingModulo=32 rollingOffset=12 amplitudePower=2 normalizeMin=0 normalizeMax=1 radius=0.01 radiusScale=0.03 ramp=D:\WIP4\Projects\Aetheria\Assets\Resources\Ramps\blackbody.png emissionScale=10 subdivisions=4
""",
new Dictionary<string, AquariumFieldResourceDeclaration>(StringComparer.Ordinal)
{
[resource.ResourceKey] = resource,
});
var lowering = Assert.Single(frame.TubeSplineLowerings);
Assert.Equal("dsl:tube:mel-field", lowering.ClaimKey);
Assert.Equal(resource.ResourceKey, lowering.ResourceKey);
Assert.Equal(64, lowering.Width);
Assert.Equal(32, lowering.Height);
Assert.Equal(12, lowering.RollingOffset);
Assert.Equal(2.0f, lowering.AmplitudePower);
Assert.Equal(10.0f, lowering.EmissionScale);
Assert.Equal(@"D:\WIP4\Projects\Aetheria\Assets\Resources\Ramps\blackbody.png", lowering.RampTexturePath);
}
}