acdream/src/AcDream.App/Rendering/WorldPassScope.cs

using AcDream.App.Rendering.Gpu;
using AcDream.Core.Lighting;

namespace AcDream.App.Rendering;

/// <summary>
/// A buffer range reduced to the three values a bind needs.
///
/// <para><see cref="GpuRingAllocation"/> is a <c>ref struct</c> — deliberately,
/// so nothing can outlive the frame's memory — but the buffer reference plus its
/// offset and size are ordinary values and stay valid for as long as that memory
/// does. That is what lets one writer publish a section and several renderers
/// bind it later in the same frame without recopying.</para>
/// </summary>
internal readonly record struct GpuBufferSection(
    IGpuBuffer? Buffer,
    uint OffsetBytes,
    uint SizeBytes)
{
    public bool IsValid => Buffer is not null && SizeBytes > 0;
}

/// <summary>
/// Campaign V slice V6j: the three sections GL binds frame-globally and Vulkan
/// cannot.
///
/// <para>On GL the SceneLighting UBO (set 1 binding 1), the per-cell clip regions
/// (set 0 binding 2) and the terrain clip block (set 1 binding 2) are each bound
/// once, to a global binding point, and every consumer inherits them. Vulkan has
/// no global binding points: a descriptor set is bound per draw, and a renderer
/// that binds its own buffers selects the descriptor scope those sections have to
/// land in (plan §5.5.14 item 2). So the writers PUBLISH here and each renderer
/// binds them inside the pass, after its own binds.</para>
///
/// <para>Borrowed for the frame that publishes it — the sections are ring slices
/// and die when the frame retires.</para>
/// </summary>
internal sealed class WorldFrameSections
{
    /// <summary>Set 1 binding 1 — <c>SceneLighting</c>.</summary>
    public GpuBufferSection SceneLighting { get; set; }

    /// <summary>Set 0 binding 2 — the per-cell <c>CellClip</c> table.</summary>
    public GpuBufferSection ClipRegions { get; set; }

    /// <summary>Set 1 binding 2 — <c>TerrainClip</c>.</summary>
    public GpuBufferSection TerrainClip { get; set; }

    public void Reset()
    {
        SceneLighting = default;
        ClipRegions = default;
        TerrainClip = default;
    }
}

/// <summary>
/// Campaign V slice V6j: the one render pass every world renderer records into,
/// borrowed rather than opened.
///
/// <para><b>Why they cannot each open one.</b> Under MSAA the frame's backbuffer
/// pass renders into a multisampled scratch image and RESOLVES it into the
/// swapchain image, storing <c>DONT_CARE</c> into the scratch — so a second pass
/// declaring <c>Load</c> would load undefined contents and lose everything the
/// first drew. The Vulkan backend also permits only one open pass per frame.
/// V4c's shape, where <c>WbDrawDispatcher</c> and <c>EnvCellRenderer</c> each
/// bracketed their own <c>Load</c>/<c>Store</c> pass, is therefore not available
/// on this backend (plan §5.5.12 item 5, §5.5.14 item 1).</para>
///
/// <para>So the world-scene phase opens the pass, publishes the encoder here for
/// the duration of <c>WorldSceneRenderer</c>, and every renderer borrows it.</para>
/// </summary>
internal interface IWorldPassScope
{
    /// <summary>
    /// Sample count of the pass, and therefore of every pipeline recorded into
    /// it. Vulkan requires a pipeline's <c>rasterizationSamples</c> to match the
    /// pass, and alpha-to-coverage does nothing at one sample — which is why
    /// V4c's blanket <c>SampleCount = 1</c> is not portable (plan §5.5.14 item 6).
    /// </summary>
    int SampleCount { get; }

    /// <summary>The open encoder, or null outside the world phase.</summary>
    IGpuPassEncoder? CurrentEncoder { get; }

    /// <summary>The open encoder, or a composition error if the phase is not bracketing.</summary>
    IGpuPassEncoder RequireEncoder();

    /// <summary>Colour-attachment width in pixels, for scissor and clear rectangles.</summary>
    int AttachmentWidth { get; }

    /// <summary>Colour-attachment height in pixels.</summary>
    int AttachmentHeight { get; }

    /// <summary>
    /// Retail's interior depth clear, scoped to the live pass.
    ///
    /// <para><c>RetailPViewPassExecutor</c> issues <c>glClear(GL_DEPTH_BUFFER_BIT)</c>
    /// between the landscape slice and the interior cells. Splitting the pass to
    /// get a depth load-op is exactly what the resolve forbids, so the backend
    /// records <c>vkCmdClearAttachments</c> instead — reached through here, so the
    /// pinned contract stays frozen and the backend-only verb stays inside the
    /// backend (plan §5.5.14 item 3).</para>
    /// </summary>
    void ClearInteriorDepth();

    /// <summary>The frame-global sections every renderer in this pass rebinds.</summary>
    WorldFrameSections Sections { get; }

    /// <summary>
    /// Publishes <paramref name="encoder"/> as the pass every world renderer
    /// borrows, for the duration of the returned scope.
    ///
    /// <para>Campaign V slice V6l lifted this onto the interface for the
    /// offscreen viewports. The world-scene phase is still the only publisher of
    /// the frame's backbuffer pass, but the paperdoll and creature-appraisal
    /// views open a pass of their OWN — a real render target, after the world
    /// pass has closed — and then ask <c>WbDrawDispatcher</c> to draw one entity
    /// into it. The dispatcher borrows its pass from here, so the viewport has to
    /// be able to say which pass "here" means.</para>
    ///
    /// <para>Publications do not nest: the backend permits one open pass at a
    /// time, so a nested publication could only mean two owners believe they hold
    /// the frame.</para>
    /// </summary>
    IDisposable Publish(IGpuPassEncoder encoder);
}

/// <summary>
/// Campaign V slice V6j: binds the frame-global sections inside a renderer's own
/// draw, which is the only place they can go on Vulkan.
///
/// <para>Each helper falls back to a zeroed ring slice when nothing published the
/// section. That is the same rule the GL arm already states for its own bindings
/// — bind at least one element so the shader never reads an unbound buffer —
/// applied to the three sections whose publisher runs outside the renderer.</para>
/// </summary>
internal static class WorldFrameSectionBinding
{
    internal static void BindSceneLighting(
        IGpuPassEncoder encoder,
        WorldFrameSections sections,
        IGpuFrame frame)
    {
        GpuBufferSection section = sections.SceneLighting;
        if (!section.IsValid)
        {
            section = Zeroed(
                frame,
                SceneLightingUbo.SizeInBytes,
                GpuRingUsage.Uniform);
        }

        encoder.BindUniformBuffer(
            (uint)SceneLightingUbo.BindingPoint,
            section.Buffer!,
            section.OffsetBytes,
            section.SizeBytes);
    }

    internal static void BindClipRegions(
        IGpuPassEncoder encoder,
        WorldFrameSections sections,
        IGpuFrame frame)
    {
        GpuBufferSection section = sections.ClipRegions;
        if (!section.IsValid)
        {
            // Slot 0 zeroed is retail's "no clip": count 0 means ungated.
            section = Zeroed(
                frame,
                ClipFrame.CellClipStrideBytes,
                GpuRingUsage.Storage);
        }

        encoder.BindStorageBuffer(
            GpuBindingModel.StorageClipRegions,
            section.Buffer!,
            section.OffsetBytes,
            section.SizeBytes);
    }

    internal static void BindTerrainClip(
        IGpuPassEncoder encoder,
        WorldFrameSections sections,
        IGpuFrame frame)
    {
        GpuBufferSection section = sections.TerrainClip;
        if (!section.IsValid)
        {
            section = Zeroed(
                frame,
                ClipFrame.TerrainUboBytes,
                GpuRingUsage.Uniform);
        }

        encoder.BindUniformBuffer(
            ClipFrame.TerrainClipUboBinding,
            section.Buffer!,
            section.OffsetBytes,
            section.SizeBytes);
    }

    private static GpuBufferSection Zeroed(
        IGpuFrame frame,
        int byteCount,
        GpuRingUsage usage)
    {
        GpuRingAllocation allocation = frame.AllocateRing(byteCount, usage);
        allocation.Data.Clear();
        return new GpuBufferSection(
            allocation.Buffer,
            allocation.OffsetBytes,
            (uint)byteCount);
    }
}