feat(render): Campaign V slice V6l commit 1 - particles draw on Vulkan

Contract amendment 1 of three, and V4e's content behind it. Plan section 5.5.16
recorded that both particle pipelines draw with per-instance VERTEX attributes
and that the pinned contract could express instanced DRAWING but not instanced
vertex INPUT: one stride, no divisor, one buffer at VertexInputRate.VERTEX. That
is what stopped V4e. This takes the reviewed option (i) - a second vertex
binding with a per-instance rate.

The amendment. GpuVertexLayout grows a per-binding notion (binding index,
stride, input rate) and GpuVertexAttribute names the binding it is fed from,
defaulting to 0; IGpuPassEncoder.BindVertexBuffer takes a binding index. Every
layout written before this slice keeps its exact meaning through
GpuVertexLayout.Interleaved, which is one vertex-rate binding 0 - and
GpuContractTests asserts that as a requirement rather than trusting it. Both
backends carry the rate natively and at no cost: VK_VERTEX_INPUT_RATE_INSTANCE
on the pipeline, glVertexAttribDivisor recorded once into the pipeline's VAO
where it survives every later attribute rebind.

GpuVertexFormat.UInt1 comes with it, and is necessary to it: particle.vert
declares `layout(location = 6) in uint aTextureIndex` and the amendment's whole
premise is that no shader is edited. Same kind-distinction UByte4UInt was added
for at V4d - GL needs glVertexAttribIPointer, Vulkan needs R32_UINT, and the
float path would reinterpret the value's bits rather than approximate them.

Options (ii) and (iii) were rejected on the record: all ten storage bindings are
spoken for and reusing binding 0 would have the GL particle draw clobber
WbDrawDispatcher's instance array mid-frame (section 5.5.8's hazard in its GL
form); CPU-expanding instances is 5x billboard bandwidth and does not scale to
mesh particles at all.

The arm. ParticleRenderer.Rhi.cs is a SECOND arm per section 5.5.6, not a
replacement - every GL statement in the sibling file is the one it always
issued. Five pipelines replace the imperative glBlendFunc switch (two billboard
blends, three mesh blends) because core Vulkan 1.3 does not make blend dynamic.
The per-flight VAO/VBO pool disappears because every ring allocation inside a
frame is already distinct memory that lives until the frame retires. The
binding-9 table is not bound at all - the device owns the table and the encoder
binds set 2. The pass is BORROWED from IWorldPassScope. Depth tests but does not
write, compare is Less and alpha-to-coverage is off, which is the ambient GL
state particles have always drawn under rather than a choice. Everything above
the submission seam - emitter iteration, retail distance ordering, the
deferred-alpha handoff, billboard axis construction, blend resolution - is the
same CPU code on both arms.

The first Vulkan particle frame threw rather than drew, which is the second
defect of the compiles-clean class this slice found by running:
TextureCache.AcquireParticleTexture is bindless-only, so the standalone particle
texture cache did not exist on a backend without GL. It exists on both arms now.
Everything about it that matters - sharing equivalent surfaces between emitter
owners, the bounded unowned LRU, retirement behind the frame-flight fence - is
already backend-neutral; only how one entry is created and destroyed differs,
which is what IStandaloneBindlessTextureBackend is for. The RHI arm creates the
image through IGpuDevice.CreateTexture with a real sampler and releases the
table slot before the image, which is the GL arm's order and for the same
reason. The composite cache stays GL-only: it serves entity appearance, not
particles.

The durability fix V6k earned. That slice found the sky declaring a 32-byte
stride against a 36-byte AcDream.Core.Terrain.Vertex - the record carries a
TerrainLayer no sky attribute names - and noted that every .Rhi.cs arm restates
a CPU record's footprint from memory while only sky had a test.
RhiVertexLayoutStrideTests is that test for the rest: world mesh, terrain, sky,
retained-UI sprite, debug line, and both particle bindings, each asserted
against the record or the producer's own float count, plus two sweeps over all
seven for attributes that reach past their stride or name an undeclared binding.
Four private layouts became internal to be assertable; nothing else about them
moved.

Gates. Release build green. App tests 4,121/3 skips (4,109 baseline plus three
contract tests and nine layout tests); complete Release suite 9,184/5. Strict GL
offline pixel gate against 08ffe141: 3.20e-05, 18 differing pixels of 563,200,
inside the documented 9-31 band. GL connected -Runs 3: 3/3 RENDERED on the
desktop witness and 3/3 on the client capture. One offline Vulkan run with
VK_LAYER_KHRONOS_validation proven inserted by the loader: zero validation
errors, zero warnings, a captured world frame that still draws terrain,
blending, roads, water, statics, scenery, sky and the complete retained UI.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/AcDream.App/Rendering/Gpu/GpuPipelineDescription.cs

@@ -28,24 +28,135 @@ internal enum GpuVertexFormat
     /// it would be garbage.
     /// </summary>
     UByte4UInt,
+
+    /// <summary>
+    /// One unsigned 32-bit integer — a shader <c>uint</c> input.
+    ///
+    /// <para>Added at slice V6l with the instanced-vertex-input amendment, and
+    /// necessary to it: <c>particle.vert</c> declares
+    /// <c>layout(location = 6) in uint aTextureIndex</c>, the per-instance
+    /// texture-table slot, and the amendment's premise is that no shader is
+    /// edited. Same kind-distinction as <see cref="UByte4UInt"/> — GL needs
+    /// <c>glVertexAttribIPointer</c> and Vulkan needs <c>R32_UINT</c>; the float
+    /// path would deliver the value's bits reinterpreted rather than a scaled
+    /// approximation of it.</para>
+    /// </summary>
+    UInt1,
 }
 
-/// <summary>One vertex attribute, matching a <c>layout(location = N) in</c> declaration.</summary>
+/// <summary>
+/// How often a vertex binding advances.
+///
+/// <para>Added at slice V6l. Both particle pipelines draw with PER-INSTANCE
+/// vertex attributes — <c>particle</c> at locations 2–6 (centre, two sheet axes,
+/// colour, texture slot) and <c>particle_mesh</c> at 3–7 (a <c>mat4</c> model and
+/// a colour) — and the V0 contract could express instanced DRAWING but not
+/// instanced vertex INPUT, which blocked V4e (plan §5.5.16). Both backends carry
+/// this natively and at no cost: <c>VK_VERTEX_INPUT_RATE_INSTANCE</c> and
+/// <c>glVertexAttribDivisor</c>.</para>
+/// </summary>
+internal enum GpuVertexInputRate
+{
+    /// <summary>The binding advances once per vertex — the default for every layout written before V6l.</summary>
+    Vertex,
+
+    /// <summary>The binding advances once per instance (GL divisor 1).</summary>
+    Instance,
+}
+
+/// <summary>
+/// One bound vertex buffer's shape: which binding index it occupies, how many
+/// bytes one element occupies, and how often it advances.
+///
+/// <para>Slice V6l. Before it, a layout had exactly one stride and one implicit
+/// binding 0 at vertex rate; that is now the <see cref="GpuVertexLayout.Interleaved"/>
+/// case rather than the only case.</para>
+/// </summary>
+internal readonly record struct GpuVertexBinding(
+    uint Binding,
+    uint StrideBytes,
+    GpuVertexInputRate InputRate = GpuVertexInputRate.Vertex);
+
+/// <summary>
+/// One vertex attribute, matching a <c>layout(location = N) in</c> declaration.
+/// <paramref name="Binding"/> names which <see cref="GpuVertexBinding"/> supplies
+/// it and defaults to 0, so every layout written before slice V6l keeps its
+/// meaning unchanged.
+/// </summary>
 internal readonly record struct GpuVertexAttribute(
     uint Location,
     GpuVertexFormat Format,
-    uint OffsetBytes);
+    uint OffsetBytes,
+    uint Binding = 0);
 
-/// <summary>Interleaved vertex layout for a single bound vertex buffer.</summary>
-internal sealed record GpuVertexLayout(uint StrideBytes, ImmutableArray<GpuVertexAttribute> Attributes)
+/// <summary>
+/// Vertex input layout: the bound buffers and the attributes they feed.
+///
+/// <para>Slice V6l grew this from one stride to a list of bindings. The overwhelmingly
+/// common case is still one interleaved vertex-rate buffer, which
+/// <see cref="Interleaved"/> spells in one line and which every layout in the
+/// tree before V6l uses.</para>
+/// </summary>
+internal sealed record GpuVertexLayout(
+    ImmutableArray<GpuVertexBinding> Bindings,
+    ImmutableArray<GpuVertexAttribute> Attributes)
 {
+    /// <summary>
+    /// One interleaved vertex-rate buffer at binding 0 — the shape of every
+    /// layout the campaign wrote before slice V6l.
+    /// </summary>
+    public static GpuVertexLayout Interleaved(
+        uint strideBytes,
+        ImmutableArray<GpuVertexAttribute> attributes) =>
+        new(
+            [new GpuVertexBinding(0, strideBytes, GpuVertexInputRate.Vertex)],
+            attributes);
+
+    /// <summary>
+    /// Stride of binding 0. Kept because it is what an interleaved layout means
+    /// and what every single-binding consumer asks for; multi-binding consumers
+    /// use <see cref="StrideOf"/>.
+    /// </summary>
+    public uint StrideBytes =>
+        Bindings.IsDefaultOrEmpty ? 0u : Bindings[0].StrideBytes;
+
+    /// <summary>Stride of <paramref name="binding"/>, or a composition error if it is not declared.</summary>
+    public uint StrideOf(uint binding)
+    {
+        foreach (GpuVertexBinding candidate in Bindings)
+        {
+            if (candidate.Binding == binding)
+                return candidate.StrideBytes;
+        }
+
+        throw new ArgumentOutOfRangeException(
+            nameof(binding),
+            binding,
+            "The vertex layout declares no such binding.");
+    }
+
+    /// <summary>How often <paramref name="binding"/> advances.</summary>
+    public GpuVertexInputRate InputRateOf(uint binding)
+    {
+        foreach (GpuVertexBinding candidate in Bindings)
+        {
+            if (candidate.Binding == binding)
+                return candidate.InputRate;
+        }
+
+        throw new ArgumentOutOfRangeException(
+            nameof(binding),
+            binding,
+            "The vertex layout declares no such binding.");
+    }
+
     /// <summary>
     /// The world mesh vertex shared by <c>mesh_modern</c>, EnvCells, and terrain:
     /// position, normal, texcoord — 32 bytes, matching the format
     /// <c>ObjectMeshManager</c> packs into <c>GlobalMeshBuffer</c>.
     /// </summary>
-    public static GpuVertexLayout WorldMesh { get; } = new(
-        StrideBytes: 32,
+    public static GpuVertexLayout WorldMesh { get; } = Interleaved(
+        strideBytes: 32,
         [
             new GpuVertexAttribute(0, GpuVertexFormat.Float3, 0),
             new GpuVertexAttribute(1, GpuVertexFormat.Float3, 12),
@@ -53,7 +164,7 @@ internal sealed record GpuVertexLayout(uint StrideBytes, ImmutableArray<GpuVerte
         ]);
 
     /// <summary>Empty layout for pipelines whose vertices come entirely from storage buffers.</summary>
-    public static GpuVertexLayout None { get; } = new(0, []);
+    public static GpuVertexLayout None { get; } = new([], []);
 }
 
 /// <summary>