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

using AcDream.App.Rendering.Gpu;

namespace AcDream.App.Rendering;

/// <summary>
/// Restores the frame-global rendering convention shared by frame clear and
/// exceptional world-pass rollback. The raw-GL implementation this contract
/// used to have alongside it (<c>RenderFrameGlStateController</c>) was deleted
/// at Campaign V slice V11; <see cref="NullRenderFrameGlState"/> is the only
/// implementation left.
/// </summary>
internal interface IRenderFrameGlState
{
    void RestoreFrameDefaults();
}

/// <summary>
/// Campaign V slice V6j: the small graphics surface the two world pass executors
/// touch directly, expressed once so their ordering logic — which is retail's,
/// and heavily tested — is written once for both backends.
///
/// <para>Everything else those executors do is delegation to a renderer. What is
/// left is exactly this: the clip-frame publication, <c>gl_ClipDistance</c>
/// enablement, and retail's interior depth clear. Three concerns, each of
/// which genuinely differs between GL and Vulkan, and none of which is
/// expressible on the pinned RHI contract. (S3 landing hygiene, H4: the
/// doorway scissor this used to also cover was retired at S3 chunk 4 fix
/// round 2 — see <see cref="ClearInteriorDepth"/>'s implementation doc.)</para>
/// </summary>
internal interface IWorldPassSurface
{
    /// <summary>
    /// Publishes this frame's per-cell clip-region table, and routes it to the
    /// renderers that read it.
    ///
    /// <para>S3 chunk 4 fix round 1 (K3) deleted the walk's per-frame terrain
    /// screen-space clip publish this used to also carry — its only writer
    /// was retired along with the per-outside-view-slice terrain/sky/weather
    /// clip loop — and fix round 2 (L3) deleted the terrain/sky shaders' own
    /// declaration of that clip block along with the section binder that used
    /// to re-assert it, so this contract now publishes exactly one section,
    /// the per-cell clip-region table.</para>
    ///
    /// <para>S3 landing hygiene (H2) deleted the GL-era reservation-count
    /// parameter this used to also take (how many distinct terrain clip
    /// blocks the frame would issue): the RHI arm always ignored it (a ring
    /// allocation is distinct memory by construction and lives until the
    /// frame retires), and the last GL implementation that read it
    /// (<c>GlWorldPassSurface</c>) was deleted at Campaign V slice V11 —
    /// nothing was left to size a reservation for.</para>
    /// </summary>
    void PrepareClipFrame();

    /// <summary>
    /// Enables every <c>gl_ClipDistance</c> slot.
    ///
    /// <para>Vulkan activates every element the shader declares and has no
    /// enable, so this is a no-op there — and that is safe rather than a
    /// divergence: only <c>portal_depth.vert</c> writes <c>gl_ClipDistance</c>
    /// in the world pass now (S3 landing hygiene, H4 — S3 chunk 4 fix round 2
    /// (L3) deleted the sky and terrain shaders' own declaration of the block
    /// this contract used to also publish; see <see cref="PrepareClipFrame"/>'s
    /// doc). It still writes <c>1.0</c> ("keep everything") into every slot
    /// past its active count, so a frame with no clip planes clips nothing on
    /// either backend (plan §5.5.14 item 4).</para>
    /// </summary>
    void EnableClipDistances();

    /// <summary>Disables every <c>gl_ClipDistance</c> slot. See <see cref="EnableClipDistances"/>.</summary>
    void DisableClipDistances();

    /// <summary>
    /// Retail's interior depth clear, between the landscape slice and the
    /// interior cells (<c>PView::DrawCells @ 0x005A4840</c>). Retail gates it
    /// on <c>outside_view.view_count &gt; 0</c> AND a nonzero persistent
    /// <c>portalsDrawnCount</c> (S3 chunk 2); the walk driver decides, this
    /// seam only executes.
    /// </summary>
    void ClearInteriorDepth();
}

/// <summary>
/// The clip table is a ring section published on the world pass scope, and the
/// depth clear is a scoped <c>vkCmdClearAttachments</c>. The raw-GL
/// implementation this used to sit alongside (<c>GlWorldPassSurface</c>) was
/// deleted at Campaign V slice V11.
/// </summary>
internal sealed class RhiWorldPassSurface : IWorldPassSurface
{
    private readonly IWorldPassScope _scope;
    private readonly ICurrentGpuFrameSource _frames;
    private readonly ClipFrame _clipFrame;

    public RhiWorldPassSurface(
        IWorldPassScope scope,
        ICurrentGpuFrameSource frames,
        ClipFrame clipFrame)
    {
        _scope = scope ?? throw new ArgumentNullException(nameof(scope));
        _frames = frames ?? throw new ArgumentNullException(nameof(frames));
        _clipFrame = clipFrame ?? throw new ArgumentNullException(nameof(clipFrame));
    }

    public void PrepareClipFrame()
    {
        _scope.Sections.ClipRegions = Publish(
            _clipFrame.RegionBytes,
            GpuRingUsage.Storage);
    }

    /// <summary>No-op: Vulkan activates every declared clip distance. See the interface.</summary>
    public void EnableClipDistances()
    {
    }

    /// <summary>No-op: Vulkan activates every declared clip distance. See the interface.</summary>
    public void DisableClipDistances()
    {
    }

    public void ClearInteriorDepth()
    {
        // S3 chunk 4 fix round 2 (L2): BeginScissor/EndScissor are deleted —
        // no producer of a narrowed scissor rectangle remains anywhere in the
        // walk (K4 deleted the doorway scissor that used to bracket the sky;
        // fix round 1 already deleted the terrain/weather per-slice scissor
        // loop). VulkanGpuPassEncoder's constructor sets the full-attachment
        // scissor exactly once, at pass begin (VulkanGpuPassEncoder.cs:87),
        // and nothing narrows it after that any more, so
        // vkCmdClearAttachments's own unscissored clear and every draw after
        // it already cover the whole target with no bracket needed here.
        _scope.ClearInteriorDepth();
    }

    private GpuBufferSection Publish(ReadOnlySpan<byte> data, GpuRingUsage usage)
    {
        IGpuFrame frame = _frames.CurrentFrame
            ?? throw new InvalidOperationException(
                "The world clip frame requires an open IGpuFrame (see GpuDeviceFrameLifetime).");
        // A logically empty table still reserves one slot so the bound range is
        // never zero-length — the same rule the light buffers already state.
        int byteCount = Math.Max(data.Length, ClipFrame.CellClipStrideBytes);
        GpuRingAllocation allocation = frame.AllocateRing(byteCount, usage);
        allocation.Data.Clear();
        if (!data.IsEmpty)
            data.CopyTo(allocation.Data);
        return new GpuBufferSection(
            allocation.Buffer,
            allocation.OffsetBytes,
            (uint)byteCount);
    }
}

/// <summary>
/// Campaign V slice V6j: the frame-default restore on a backend with no ambient
/// state to restore.
///
/// <para>Both executors call <see cref="IRenderFrameGlState.RestoreFrameDefaults"/>
/// when aborting a failed frame. On Vulkan every piece of state that call
/// re-establishes is either baked into a pipeline or set per draw, so there is
/// nothing to put back and saying so is more honest than composing a GL
/// controller that would have no context to talk to.</para>
/// </summary>
internal sealed class NullRenderFrameGlState : IRenderFrameGlState
{
    public static NullRenderFrameGlState Instance { get; } = new();

    private NullRenderFrameGlState()
    {
    }

    public void RestoreFrameDefaults()
    {
    }
}

/// <summary>
/// Campaign V slice V6j: the GL state reader on a backend with no GL state.
///
/// <para><c>WorldRenderDiagnostics</c> reads live GL state for explicitly enabled
/// probes only. Every snapshot below is the truthful answer for a Vulkan frame —
/// there is no ambient capability state to sample — which keeps every other
/// diagnostic the class emits (render signature, PView input, out-stage routing,
/// phantom objects) working unchanged on both backends.</para>
/// </summary>
internal sealed class NullRenderGlStateReader : IRenderGlStateReader
{
    public static NullRenderGlStateReader Instance { get; } = new();

    private NullRenderGlStateReader()
    {
    }

    public RenderGlStateSnapshot CaptureState() => default;

    public RenderGlScissorSnapshot CaptureScissor() => default;
}