acdream/src/AcDream.App/Rendering/Gpu/IGpuFrame.cs

using System.Runtime.InteropServices;

namespace AcDream.App.Rendering.Gpu;

/// <summary>
/// A slice of the current frame's upload ring: the buffer to bind, the byte
/// offset to bind it at, and CPU-writable memory to fill.
///
/// This type replaces every per-frame <c>BufferSubData</c> in the renderers, and
/// it is the reason the Vulkan backend costs less CPU than GL. Today a renderer
/// writes its instance/batch/indirect data into a managed array and then hands
/// that array to the driver, which validates it, copies it, and tracks a renamed
/// backing store. With a ring allocation the renderer writes ONCE, directly into
/// memory the GPU will read — the upload stops existing as a separate step.
///
/// It is a <c>ref struct</c> on purpose: the memory is only valid until the frame
/// that produced it retires, so the compiler prevents storing it in a field.
/// </summary>
internal readonly ref struct GpuRingAllocation
{
    public GpuRingAllocation(IGpuBuffer buffer, uint offsetBytes, Span<byte> data)
    {
        Buffer = buffer;
        OffsetBytes = offsetBytes;
        Data = data;
    }

    /// <summary>The ring buffer to bind. Backends may hand out many allocations from one buffer.</summary>
    public IGpuBuffer Buffer { get; }

    /// <summary>Byte offset of this allocation, already aligned for its <see cref="GpuRingUsage"/>.</summary>
    public uint OffsetBytes { get; }

    /// <summary>CPU-writable memory for this allocation. Valid until the owning frame retires.</summary>
    public Span<byte> Data { get; }

    public bool IsEmpty => Data.IsEmpty;

    /// <summary>Reinterprets the allocation as a typed span so callers write structs, not bytes.</summary>
    public Span<T> AsSpan<T>() where T : unmanaged => MemoryMarshal.Cast<byte, T>(Data);
}

/// <summary>
/// One frame's recording context. Obtained from <see cref="IGpuDevice.BeginFrame"/>
/// and closed by <see cref="End"/>, which submits the recorded work and presents.
///
/// The frame owns the ring: allocations are recycled once the GPU has finished the
/// frame that made them, which is exactly the bound
/// <c>GpuFrameFlightController</c> already enforces with GL fences and which the
/// Vulkan backend expresses with a single timeline semaphore.
/// </summary>
internal interface IGpuFrame : IDisposable
{
    /// <summary>Frames-in-flight slot index this frame occupies.</summary>
    int SlotIndex { get; }

    /// <summary>Monotonic frame serial. Matches the retirement-ledger key used for resource release.</summary>
    long Serial { get; }

    /// <summary>
    /// Reserves <paramref name="byteCount"/> bytes of CPU-writable ring memory,
    /// aligned as <paramref name="usage"/> requires. Throws if the request exceeds
    /// the ring's per-frame capacity — silently truncating a draw's data would
    /// corrupt the frame invisibly.
    /// </summary>
    GpuRingAllocation AllocateRing(int byteCount, GpuRingUsage usage);

    /// <summary>
    /// Opens a rendering pass. The returned encoder must be disposed before the
    /// next pass begins; nesting is not supported and no acdream pass needs it.
    /// </summary>
    IGpuPassEncoder BeginPass(GpuPassDescription description);

    /// <summary>
    /// Submits the frame and presents it. Idempotent with <see cref="IDisposable.Dispose"/>
    /// so a failed frame still closes its slot rather than stalling the ring.
    /// </summary>
    void End();
}