namespace AcDream.App.Rendering.Gpu;

/// <summary>
/// Records draw work inside one <see cref="GpuPassDescription"/>. Disposing the
/// encoder closes the pass.
///
/// The surface is deliberately small: it is exactly what acdream's twelve
/// renderers do, expressed the way Vulkan wants it. Everything that Vulkan bakes
/// into a pipeline (blend, depth compare, alpha-to-coverage, topology) is absent
/// here by design — those live in <see cref="GpuPipelineDescription"/>. Only the
/// state core Vulkan 1.3 makes dynamic is settable per draw.
/// </summary>
internal interface IGpuPassEncoder : IDisposable
{
    /// <summary>The pass this encoder is recording into.</summary>
    GpuPassDescription Pass { get; }

    /// <summary>Binds the shader program and all baked fixed state.</summary>
    void BindPipeline(IGpuPipeline pipeline);

    /// <summary>
    /// Binds a storage buffer range to a <see cref="GpuBindingModel"/> storage
    /// binding. Ranges come straight from <see cref="GpuRingAllocation"/> for
    /// per-frame data, or from a long-lived buffer for persistent data.
    /// </summary>
    void BindStorageBuffer(uint binding, IGpuBuffer buffer, uint offsetBytes, uint sizeBytes);

    /// <summary>Binds a uniform buffer range — currently only the SceneLighting block.</summary>
    void BindUniformBuffer(uint binding, IGpuBuffer buffer, uint offsetBytes, uint sizeBytes);

    /// <summary>
    /// Binds one vertex source into <paramref name="binding"/> of the pipeline's
    /// <see cref="GpuVertexLayout"/>.
    ///
    /// <para>Slice V6l added the binding index. Layouts written before it declare
    /// exactly one interleaved vertex-rate binding 0, so every existing call site
    /// passes 0; the particle pipelines add a second, per-instance binding.</para>
    /// </summary>
    void BindVertexBuffer(uint binding, IGpuBuffer buffer, uint offsetBytes);

    /// <summary>Binds the index source.</summary>
    void BindIndexBuffer(IGpuBuffer buffer, uint offsetBytes, GpuIndexType indexType);

    /// <summary>Writes the shared push-constant block. Survives pipeline changes within a pass.</summary>
    void SetPushConstants(in GpuPushConstants constants);

    /// <summary>
    /// Sets the drawable rectangle. Callers always pass GL-convention coordinates
    /// (origin bottom-left); the Vulkan backend converts by emitting a negative
    /// viewport height, so no renderer performs a Y flip itself.
    /// </summary>
    void SetViewport(int x, int y, int width, int height);

    /// <summary>Sets the scissor rectangle in the same convention as <see cref="SetViewport"/>.</summary>
    void SetScissor(int x, int y, int width, int height);

    /// <summary>Dynamic cull override — how the world dispatcher draws double-sided geometry.</summary>
    void SetCullMode(GpuCullMode cullMode);

    /// <summary>Dynamic winding override, in GL convention. The Vulkan backend applies its own inversion.</summary>
    void SetFrontFace(GpuFrontFace frontFace);

    /// <summary>Dynamic depth-write override — how the translucent pass stops occluding later draws.</summary>
    void SetDepthWrite(bool enabled);

    /// <summary>
    /// Dynamic stencil override: compare, the three outcome ops, reference and
    /// both masks. Meaningful only inside a pipeline whose
    /// <see cref="GpuPipelineDescription.StencilTest"/> is set.
    ///
    /// <para>Slice V6l. #117's portal punch changes every one of these between
    /// its stencil-marking pass and its far-Z punch pass, and core Vulkan 1.3
    /// makes all of them dynamic, so they belong here rather than in a second
    /// pipeline object.</para>
    /// </summary>
    void SetStencil(in GpuStencilState stencil);

    /// <summary>Draws indexed geometry directly, without an indirect buffer.</summary>
    void DrawIndexed(uint indexCount, uint instanceCount, uint firstIndex, int vertexOffset, uint firstInstance);

    /// <summary>Draws non-indexed geometry — the retained UI's batched sprite/glyph quads.</summary>
    void Draw(uint vertexCount, uint instanceCount, uint firstVertex, uint firstInstance);

    /// <summary>
    /// The production draw call: one submission covering <paramref name="drawCount"/>
    /// commands read from <paramref name="commands"/>. Each command's draw index is
    /// visible to the shader as <c>gl_DrawID</c>, offset by
    /// <see cref="GpuPushConstants.DrawIdOffset"/>.
    /// </summary>
    void MultiDrawIndexedIndirect(IGpuBuffer commands, uint offsetBytes, uint drawCount, uint strideBytes);

    /// <summary>
    /// Opens a GPU timing scope whose result becomes readable through
    /// <see cref="IGpuTimerPool.TryResolve"/> once this frame retires. Returns a
    /// no-op disposable when the backend cannot measure GPU time.
    /// </summary>
    IDisposable BeginTimerScope(string scopeName);
}