diff --git a/src/Aquarium.Engine.Contracts/Render/AquariumFieldEvidence.cs b/src/Aquarium.Engine.Contracts/Render/AquariumFieldEvidence.cs index bfe9bff..8a212c6 100644 --- a/src/Aquarium.Engine.Contracts/Render/AquariumFieldEvidence.cs +++ b/src/Aquarium.Engine.Contracts/Render/AquariumFieldEvidence.cs @@ -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 Resources { get; init; } = []; + public IReadOnlyList 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); diff --git a/src/Aquarium.Engine.Contracts/Render/AquariumFieldScriptCompiler.cs b/src/Aquarium.Engine.Contracts/Render/AquariumFieldScriptCompiler.cs index 6f126ee..0a24943 100644 --- a/src/Aquarium.Engine.Contracts/Render/AquariumFieldScriptCompiler.cs +++ b/src/Aquarium.Engine.Contracts/Render/AquariumFieldScriptCompiler.cs @@ -16,6 +16,7 @@ public static class AquariumFieldScriptCompiler var domains = new List(); var claims = new List(); var candidates = new List(); + var tubeSplineLowerings = new List(); var resourceAliases = new Dictionary(StringComparer.Ordinal); var domainKeys = new HashSet(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 args, + IReadOnlyDictionary resourceAliases, + ISet domainKeys, + ICollection domains, + ICollection claims, + ICollection candidates, + ICollection 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 args, IReadOnlyList surfaceNodes, diff --git a/src/Aquarium.Engine/Render/D3D12FieldResourceRegistry.cs b/src/Aquarium.Engine/Render/D3D12FieldResourceRegistry.cs index 05bf05b..bf767cf 100644 --- a/src/Aquarium.Engine/Render/D3D12FieldResourceRegistry.cs +++ b/src/Aquarium.Engine/Render/D3D12FieldResourceRegistry.cs @@ -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 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(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, diff --git a/src/Aquarium.Engine/Render/D3D12StructuredBuffer.cs b/src/Aquarium.Engine/Render/D3D12StructuredBuffer.cs index 9c5f5df..8f40215 100644 --- a/src/Aquarium.Engine/Render/D3D12StructuredBuffer.cs +++ b/src/Aquarium.Engine/Render/D3D12StructuredBuffer.cs @@ -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; diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 465cbdc..f8cfed6 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -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"} diff --git a/state/map.yaml b/state/map.yaml index 8986e17..92b8f61 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -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. diff --git a/tests/Aquarium.Engine.Tests/FieldEvidenceContractTests.cs b/tests/Aquarium.Engine.Tests/FieldEvidenceContractTests.cs index 997c650..dfcda82 100644 --- a/tests/Aquarium.Engine.Tests/FieldEvidenceContractTests.cs +++ b/tests/Aquarium.Engine.Tests/FieldEvidenceContractTests.cs @@ -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) + ], }; } } diff --git a/tests/Aquarium.Engine.Tests/FieldScriptCompilerTests.cs b/tests/Aquarium.Engine.Tests/FieldScriptCompilerTests.cs index b2fbbdf..4536a0a 100644 --- a/tests/Aquarium.Engine.Tests/FieldScriptCompilerTests.cs +++ b/tests/Aquarium.Engine.Tests/FieldScriptCompilerTests.cs @@ -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(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); + } }