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

namespace AcDream.App.Rendering.Gpu;

/// <summary>
/// A GPU buffer. Disposal does not free immediately: every backend routes the
/// physical release through the device's retirement queue so the memory outlives
/// any frame still referencing it. That is the same contract
/// <c>GpuFrameFlightController</c> already enforces for GL names today.
/// </summary>
internal interface IGpuBuffer : IDisposable
{
    string Name { get; }
    long SizeBytes { get; }
    GpuBufferUsage Usage { get; }
    GpuMemoryResidency Residency { get; }

    /// <summary>
    /// Writes <paramref name="data"/> at <paramref name="offsetBytes"/>. On a
    /// <see cref="GpuMemoryResidency.DeviceLocal"/> buffer this stages through a
    /// transfer; on a host-writable buffer it is a direct memory write. Per-frame
    /// data should not use this at all — take a ring allocation and write into it.
    /// </summary>
    void Upload(long offsetBytes, ReadOnlySpan<byte> data);

    /// <summary>
    /// Device-side copy, used by the mesh arena's grow-and-copy migration so
    /// arena growth never round-trips through system memory.
    /// </summary>
    void CopyTo(IGpuBuffer destination, long sourceOffsetBytes, long destinationOffsetBytes, long byteCount);

    /// <summary>
    /// Reads back into <paramref name="destination"/>. Only valid on
    /// <see cref="GpuMemoryResidency.HostReadable"/> buffers; diagnostics only.
    /// </summary>
    void Read(long offsetBytes, Span<byte> destination);
}

/// <summary>A sampled texture or an attachment image.</summary>
internal interface IGpuTexture : IDisposable
{
    string Name { get; }
    GpuTextureKind Kind { get; }
    GpuTextureFormat Format { get; }
    int Width { get; }
    int Height { get; }
    int LayerCount { get; }
    int MipLevelCount { get; }

    /// <summary>
    /// Uploads one mip level of one array layer. <paramref name="data"/> is raw
    /// texels for uncompressed formats and raw blocks for BC formats.
    /// </summary>
    void Upload(int mipLevel, int layer, ReadOnlySpan<byte> data);

    /// <summary>
    /// Fills mip levels 1..N-1 from level 0.
    ///
    /// Explicit rather than automatic because the two backends cannot do this the
    /// same way: GL calls <c>glGenerateMipmap</c>, while Vulkan blits uncompressed
    /// images and CANNOT blit compressed ones. For BC formats the Vulkan backend
    /// requires the caller to have supplied a CPU-built chain via
    /// <see cref="Upload"/> and this call throws — the GL path's reliance on
    /// driver-defined compressed-mip regeneration is the behaviour we are
    /// deliberately not carrying forward.
    /// </summary>
    void GenerateMipChain();
}

/// <summary>Immutable sampler state. Owned and de-duplicated by the device.</summary>
internal interface IGpuSampler : IDisposable
{
    GpuSamplerDescription Description { get; }
}

/// <summary>
/// A compiled shader program plus every piece of fixed pipeline state it draws
/// with. This is the type that replaces the imperative
/// <c>Enable/BlendFunc/DepthMask/CullFace</c> brackets scattered through the GL
/// renderers: state that Vulkan bakes at creation lives here, and only the state
/// core Vulkan 1.3 makes dynamic stays callable per draw
/// (<see cref="IGpuPassEncoder.SetCullMode"/> and friends).
/// </summary>
internal interface IGpuPipeline : IDisposable
{
    GpuPipelineDescription Description { get; }
}

/// <summary>An offscreen render target whose colour attachment is sampleable once the pass ends.</summary>
internal interface IGpuRenderTarget : IDisposable
{
    GpuRenderTargetDescription Description { get; }

    /// <summary>The colour attachment, for registering into the texture table or blitting into UI.</summary>
    IGpuTexture ColorTexture { get; }
}

/// <summary>
/// GPU-side timing. Backed by GL <c>TimeElapsed</c> queries or Vulkan timestamp
/// queries; results are only readable once the issuing frame has retired, so
/// <see cref="TryResolve"/> reports the most recent completed measurement rather
/// than blocking.
/// </summary>
internal interface IGpuTimerPool
{
    /// <summary>True when the backend can measure GPU time at all.</summary>
    bool IsSupported { get; }

    /// <summary>Milliseconds measured for <paramref name="scopeName"/> in the most recent retired frame.</summary>
    bool TryResolve(string scopeName, out double milliseconds);
}