graphics_vk_internal.h

#pragma once

#include "subsystems/graphics/graphics.h"
#include "subsystems/graphics/graphics_vk_spirv.h"

#include "util/types.h"

/*
 * DuetOS — Vulkan ICD internal interface.
 *
 * Cross-TU surface used to split the Vulkan ICD across more
 * than one TU.  Today: graphics_vk.cpp (entry-point
 * implementations + storage definitions) and
 * graphics_vk_selftest.cpp (boot self-test).  The header is
 * sized for arbitrary further splits — every per-kind handle
 * pool, every record struct, every shared helper and every
 * counter is declared here so a follow-on slice can carve out
 * graphics_vk_commands.cpp / _wsi.cpp / _misc.cpp without
 * further header churn.
 *
 * Discipline:
 *   - Types + constants live here as inline definitions.
 *   - Helpers small enough to inline (Pool primitives + handle
 *     range maths) live here as inline functions.
 *   - Per-kind handle storage lives here as `extern` decls;
 *     the storage is defined exactly once in graphics_vk.cpp.
 *   - Counters likewise — `extern` here, defined in
 *     graphics_vk.cpp.
 *
 * Not part of the public Vulkan ICD surface.  Userland code
 * never includes this file.
 */

namespace duetos::subsystems::graphics::internal
{

// -------------------------------------------------------------------
// Pool primitive + per-kind base ranges.
// -------------------------------------------------------------------
//
// Every Vk* type has its own handle pool: a fixed-size bitmap
// of live slots plus a per-kind base.  A handle is `base + slot`.
// Capacity is sized for the canonical self-test path plus a
// comfortable headroom; this is a v0 ICD, not a benchmark.

inline constexpr u32 kPoolCapacity = 32;

struct Pool
{
    u32 live = 0;
    u32 created = 0;
    u32 destroyed = 0;
    u32 used_bitmap = 0; // bit N = slot N live
};

inline bool PoolAlloc(Pool& p, u32* slot_out)
{
    for (u32 i = 0; i < kPoolCapacity; ++i)
    {
        const u32 bit = 1u << i;
        if ((p.used_bitmap & bit) == 0u)
        {
            p.used_bitmap |= bit;
            ++p.live;
            ++p.created;
            *slot_out = i;
            return true;
        }
    }
    return false;
}

inline bool PoolFree(Pool& p, u32 slot)
{
    if (slot >= kPoolCapacity)
        return false;
    const u32 bit = 1u << slot;
    if ((p.used_bitmap & bit) == 0u)
        return false;
    p.used_bitmap &= ~bit;
    --p.live;
    ++p.destroyed;
    return true;
}

inline bool PoolIsLive(const Pool& p, u32 slot)
{
    if (slot >= kPoolCapacity)
        return false;
    return (p.used_bitmap & (1u << slot)) != 0u;
}

inline constexpr u64 kInstanceBase = 0x1'0000;
inline constexpr u64 kPhysDevBase = 0x2'0000;
inline constexpr u64 kDeviceBase = 0x3'0000;
inline constexpr u64 kQueueBase = 0x4'0000;
inline constexpr u64 kCmdPoolBase = 0x5'0000;
inline constexpr u64 kCmdBufBase = 0x6'0000;
inline constexpr u64 kShaderBase = 0x7'0000;
inline constexpr u64 kPipelineLayoutBase = 0x8'0000;
inline constexpr u64 kPipelineBase = 0x9'0000;
inline constexpr u64 kRenderPassBase = 0xA'0000;
inline constexpr u64 kFramebufferBase = 0xB'0000;
inline constexpr u64 kImageBase = 0xC'0000;
inline constexpr u64 kImageViewBase = 0xD'0000;
inline constexpr u64 kBufferBase = 0xE'0000;
inline constexpr u64 kMemoryBase = 0xF'0000;
inline constexpr u64 kFenceBase = 0x10'0000;
inline constexpr u64 kSemaphoreBase = 0x11'0000;
inline constexpr u64 kDescSetLayoutBase = 0x12'0000;
inline constexpr u64 kDescPoolBase = 0x13'0000;
inline constexpr u64 kDescSetBase = 0x14'0000;
inline constexpr u64 kSurfaceBase = 0x15'0000;
inline constexpr u64 kSwapchainBase = 0x16'0000;
inline constexpr u64 kSamplerBase = 0x17'0000;
inline constexpr u64 kEventBase = 0x18'0000;
inline constexpr u64 kPipelineCacheBase = 0x19'0000;
inline constexpr u64 kQueryPoolBase = 0x1A'0000;

inline bool HandleInRange(u64 h, u64 base)
{
    return h >= base && h < base + kPoolCapacity;
}
inline u32 SlotOf(u64 h, u64 base)
{
    return static_cast<u32>(h - base);
}
inline u64 HandleFor(u64 base, u32 slot)
{
    return base + slot;
}

// -------------------------------------------------------------------
// Per-kind record types.
// -------------------------------------------------------------------

struct ImageRecord
{
    VkExtent3D extent;
    u32 flags;
    // DuetOS-internal format id. Maps to the same numbering as
    // VkGetPhysicalDeviceFormatProperties:
    //   0 = B8G8R8A8_UNORM (default), 1 = R8G8B8A8_UNORM,
    //   2 = R8_UNORM,       3 = R8G8_UNORM,
    //   4 = R16_UNORM,      5 = R32G32B32A32_SFLOAT.
    // Drives texel-byte-stride + per-channel unpack/pack at sample
    // and storage-image read/write time. Defaults to 0 for any
    // legacy caller that goes through `VkCreateImage` without a
    // format param.
    u32 format;
    bool memory_bound;
    // Direct pointer into the bound DeviceMemory's host_ptr (when
    // the memory is HOST_VISIBLE). Set by `VkBindImageMemory`; the
    // texture-sample path reads through it to fetch texels.
    // nullptr when no memory has been bound or the memory type
    // isn't host-visible.
    void* backing;
};

/// Bytes consumed per texel for each recognised DuetOS-internal
/// format id. Drives offset arithmetic in the storage-image path.
/// Returns 4 (BGRA8 stride) for any unknown format so a bogus id
/// can't divide-by-zero or wander past the backing.
u32 BytesPerTexelForFormat(u32 format);

struct ShaderRecord
{
    u64 byte_size;
    ShaderModuleInfo info;
    // Owning copy of the SPIR-V word stream (we keep our own
    // copy so the caller's pointer can go out of scope after
    // VkCreateShaderModule). Allocated via mm::KMalloc; freed by
    // VkDestroyShaderModule.
    u32* code_copy;
    u64 code_word_count;
    // Parsed program — also owned, lazily allocated when the
    // module is first bound to a pipeline that the rasterizer
    // can execute. nullptr if the module's structure doesn't
    // pass the v1 parser, in which case the rasterizer falls
    // back to the fixed-function path.
    spirv::Program* spirv_program;
};

struct BufferRecord
{
    u64 size;
    bool memory_bound;
    void* backing;
    u64 backing_offset;
    VkDeviceMemory bound_memory;
};

struct ImageViewRecord
{
    VkImage image;
};

struct FramebufferRecord
{
    VkImageView attachment;
};

struct DeviceMemoryRecord
{
    u64 size;
    void* host_ptr;
    u32 type_index;
    bool host_visible;
    u32 map_count;
};

enum class CmdOp : u8
{
    None = 0,
    BeginRenderPass = 1,
    EndRenderPass = 2,
    BindPipeline = 3,
    ClearColorImage = 4,
    Draw = 5,
    DrawIndexed = 6,
    SetViewport = 7,
    SetScissor = 8,
    BindVertexBuffer = 9,
    BindIndexBuffer = 10,
    CopyBuffer = 11,
    FillBuffer = 12,
    PipelineBarrier = 13,
    PushConstants = 14,
    Dispatch = 15,
    CopyBufferToImage = 16,
    SetEvent = 17,
    ResetEvent = 18,
    WaitEvents = 19,
    BeginQuery = 20,
    EndQuery = 21,
    ResetQueryPool = 22,
    WriteTimestamp = 23,
    CopyImage = 24,
    BlitImage = 25,
    CopyImageToBuffer = 26,
    ResolveImage = 27,
    UpdateBuffer = 28,
    ClearAttachments = 29,
    ClearDepthStencilImage = 30,
    BeginRendering = 31,
    EndRendering = 32,
    SetLineWidth = 33,
    SetDepthBias = 34,
    SetBlendConstants = 35,
    SetDepthBounds = 36,
    SetStencilState = 37,
    BeginDebugLabel = 38,
    EndDebugLabel = 39,
    InsertDebugLabel = 40,
    PushDescriptor = 41,
    ExecuteCommands = 42,
    DrawIndirect = 43,
    DrawIndexedIndirect = 44,
    DispatchIndirect = 45,
    SetCullMode = 46,
    SetFrontFace = 47,
    SetPrimitiveTopology = 48,
    SetDepthTestEnable = 49,
    SetDepthWriteEnable = 50,
    SetDepthCompareOp = 51,
    SetStencilTestEnable = 52,
    SetStencilOp = 53,
    SetDepthBoundsTestEnable = 54,
    SetViewportWithCount = 55,
    SetScissorWithCount = 56,
    BindVertexBuffers2 = 57,
    NextSubpass = 58,
    CopyQueryPoolResults = 59,
    BeginQueryIndexed = 60,
    EndQueryIndexed = 61,
    SetEvent2 = 62,
    ResetEvent2 = 63,
    WaitEvents2 = 64,
    PipelineBarrier2 = 65,
    SetVertexFormatDuet = 66, // DuetOS extension: rasterizer vertex layout (0 = v0, 1 = v1)
    BindDescriptorSets = 67,  // Records the first bound descriptor set so the rasterizer hook can
                              // walk its bindings + call spirv::BindDescriptor per draw.
};

struct CmdRecord
{
    CmdOp op;
    VkImage image;
    VkRenderPass render_pass;
    VkFramebuffer framebuffer;
    VkRect2D area;
    VkClearColorValue color;
    VkPipelineBindPoint bind_point;
    VkPipeline pipeline;
    u32 vertex_count;
    u32 instance_count;
    u32 first_vertex;
    u32 first_instance;
    u32 index_count;
    u32 first_index;
    i32 vertex_offset;
    VkBuffer index_buffer;
    u64 index_offset;
    VkIndexType index_type;
    VkBuffer vertex_buffer;
    u64 vertex_offset_bytes;
    u32 vertex_binding;
    VkBuffer src_buffer;
    VkBuffer dst_buffer;
    u64 src_offset;
    u64 dst_offset;
    u64 region_size;
    u32 fill_pattern;
    u32 push_offset;
    u32 push_size;
    u8 push_data[kMaxPushConstantBytes];
    u32 dispatch_x;
    u32 dispatch_y;
    u32 dispatch_z;
    VkEvent event;
    VkQueryPool query_pool;
    u32 query_first;
    u32 query_count;
    u32 query_index;
    u32 region_width;
    u32 region_height;
    VkImage src_image;
    VkRect2D src_rect;
    VkRect2D dst_rect;
    VkFilter blit_filter;
    u32 depth_bits;
    u32 stencil;
    u32 attachment_count;
    u32 rect_count;
    VkCommandBuffer secondary_cb;
    VkDescriptorSet descriptor_set; // first set on the BindDescriptorSets op
};

inline constexpr u32 kCmdTapeCapacity = 32;

enum class CbState : u8
{
    Initial = 0,
    Recording = 1,
    Executable = 2,
};

struct CmdBufferRecord
{
    CbState state;
    bool is_secondary;
    u32 op_count;
    CmdRecord ops[kCmdTapeCapacity];
};

/// Per-pipeline record. Today only tracks the bound shader
/// handles so the rasterizer can find the SPIR-V Program at
/// replay time. Future extensions: vertex input bindings,
/// rasterization state, blend state — each layer lands here
/// as it becomes meaningful.
struct PipelineRecord
{
    VkShaderModule vertex_shader;   // 0 if none (compute pipeline)
    VkShaderModule fragment_shader; // 0 if none (compute pipeline)
    VkShaderModule compute_shader;  // 0 if graphics
    // Vertex input description (set by VkSetVertexInputDuet).
    // When attribute_count > 0 the shader-rasterizer uses these
    // tuples to fetch each VS Input; otherwise it falls back to
    // the canonical 16-byte-per-Location layout.
    u32 vertex_binding_count;
    u32 vertex_attribute_count;
    VkVertexBindingDuet vertex_bindings[kMaxVertexBindings];
    VkVertexAttributeDuet vertex_attributes[kMaxVertexAttributes];
};

struct DescriptorSetLayoutRecord
{
    u32 binding_count;
    VkDescriptorSetLayoutBinding bindings[kMaxDescriptorBindings];
};

struct DescriptorPoolRecord
{
    u32 max_sets;
    u32 sets_allocated;
};

/// Per-binding entry inside a DescriptorSetRecord. Captures the
/// type the binding was declared with + the resource handle the
/// caller pinned via VkUpdateDescriptorSet (an image / image-view
/// for sampled / storage types; a buffer for uniform / storage
/// buffer types).
struct DescriptorBinding
{
    u32 type;           // VkDescriptorType (Sampler / SampledImage / UniformBuffer / ...)
    u64 handle;         // VkImage / VkImageView / VkBuffer handle, or 0
    u64 sampler_handle; // For CombinedImageSampler: the VkSampler whose addressing
                        // mode + filter the executor honours at OpImageSample time.
                        // For Sampler bindings: the sampler handle itself (handle==0).
                        // 0 means "no sampler specified — fall back to default".
};

struct DescriptorSetRecord
{
    VkDescriptorPool pool;
    VkDescriptorSetLayout layout;
    u32 writes;
    // Per-binding state. v0 supports up to kMaxDescriptorBindings
    // bindings per set; the shader-rasterizer hook walks this on
    // each draw to populate the SPIR-V Program's descriptor table.
    DescriptorBinding bindings[kMaxDescriptorBindings];
};

struct SwapchainRecord
{
    VkSurfaceKHR surface;
    VkExtent2D extent;
    u32 image_count;
    u32 next_image;
    u32 acquired_index;
    bool image_acquired;
    VkImage images[kMaxSwapchainImages];
};

struct EventRecord
{
    bool signalled;
};

struct PipelineCacheRecord
{
    u64 stored_size;
};

/// Per-sampler record. v0 captures the VkSamplerCreateInfo fields
/// the SPIR-V executor's OpImageSample path actually consults —
/// the three per-axis address modes and the mag/min filters.
/// `border_color` is fixed to 0 (transparent black) because the v0
/// VkSamplerCreateInfo doesn't expose a borderColor field yet; a
/// follow-on slice can plumb it through when callers need
/// per-sampler border tints.
struct SamplerRecord
{
    u8 address_mode_u; // VkSamplerAddressMode cast to u8
    u8 address_mode_v;
    u8 address_mode_w;
    u8 mag_filter; // VkFilter::Nearest = 0, Linear = 1
    u8 min_filter;
};

/// Per-fence state. `signalled` flips true when the submit that
/// the fence rides on completes; flips false on VkResetFences.
/// `VkWaitForFences` consults the bit. v0 submits are synchronous
/// so the bit is set at VkQueueSubmit return time — no blocking
/// path is needed today, but the structural backing is in place
/// for a real-GPU back-end to set it asynchronously.
struct FenceRecord
{
    bool signalled;
};

/// Per-semaphore state. Binary semaphores: `signalled` flips true
/// on a queue-side signal (e.g. VkQueueSubmit's signal-semaphore
/// list), flips false on a queue-side wait that consumes it. The
/// signal/wait surface for VkQueueSubmit grows in a follow-on
/// slice; v0 captures the bit so VkAcquireNextImageKHR /
/// VkQueuePresentKHR can interact with it once the WSI side
/// passes real semaphores through.
struct SemaphoreRecord
{
    bool signalled;
};

inline constexpr u32 kMaxQueriesPerPool = 16;
struct QueryPoolRecord
{
    VkQueryType type;
    u32 query_count;
    u64 results[kMaxQueriesPerPool];
    bool available[kMaxQueriesPerPool];
};

struct PhysicalDeviceRecord
{
    u32 gpu_index;
    u32 owning_instance_slot; ///< Slot in g_instance_pool that allocated this phys; freed on VkDestroyInstance.
};

struct QueueRecord
{
    u32 owning_device_slot; ///< Slot in g_device_pool that vkGetDeviceQueue allocated from; freed on VkDestroyDevice.
};

// -------------------------------------------------------------------
// Per-kind storage.  Defined exactly once in graphics_vk.cpp.
// -------------------------------------------------------------------

extern Pool g_instance_pool;
extern Pool g_phys_pool;
extern Pool g_device_pool;
extern Pool g_queue_pool;
extern Pool g_cmdpool_pool;
extern Pool g_cmdbuf_pool;
extern Pool g_shader_pool;
extern Pool g_pipelinelayout_pool;
extern Pool g_pipeline_pool;
extern Pool g_renderpass_pool;
extern Pool g_framebuffer_pool;
extern Pool g_image_pool;
extern Pool g_imageview_pool;
extern Pool g_buffer_pool;
extern Pool g_memory_pool;
extern Pool g_fence_pool;
extern Pool g_semaphore_pool;
extern Pool g_desc_set_layout_pool;
extern Pool g_desc_pool_pool;
extern Pool g_desc_set_pool;
extern Pool g_surface_pool;
extern Pool g_swapchain_pool;
extern Pool g_sampler_pool;
extern Pool g_event_pool;
extern Pool g_pipeline_cache_pool;
extern Pool g_query_pool_pool;

extern ImageRecord g_image_data[kPoolCapacity];
extern ShaderRecord g_shader_data[kPoolCapacity];
extern BufferRecord g_buffer_data[kPoolCapacity];
extern ImageViewRecord g_imageview_data[kPoolCapacity];
extern FramebufferRecord g_framebuffer_data[kPoolCapacity];
extern DeviceMemoryRecord g_memory_data[kPoolCapacity];
extern CmdBufferRecord g_cmdbuf_data[kPoolCapacity];
extern DescriptorSetLayoutRecord g_desc_set_layout_data[kPoolCapacity];
extern DescriptorPoolRecord g_desc_pool_data[kPoolCapacity];
extern DescriptorSetRecord g_desc_set_data[kPoolCapacity];
extern SwapchainRecord g_swapchain_data[kPoolCapacity];
extern EventRecord g_event_data[kPoolCapacity];
extern PipelineCacheRecord g_pipeline_cache_data[kPoolCapacity];
extern QueryPoolRecord g_query_pool_data[kPoolCapacity];
extern PhysicalDeviceRecord g_phys_data[kPoolCapacity];
extern QueueRecord g_queue_data[kPoolCapacity];
extern PipelineRecord g_pipeline_data[kPoolCapacity];
extern SamplerRecord g_sampler_data[kPoolCapacity];
extern FenceRecord g_fence_data[kPoolCapacity];
extern SemaphoreRecord g_semaphore_data[kPoolCapacity];

// -------------------------------------------------------------------
// Aggregate counters.
// -------------------------------------------------------------------

extern u32 g_queue_submits;
extern u32 g_command_recorded;
extern u32 g_command_replayed;
extern u32 g_clear_pixels_painted;
extern u32 g_invalid_spirv_rejections;
extern u32 g_descriptor_writes;
extern u32 g_swapchain_acquires;
extern u32 g_swapchain_presents;
extern u32 g_spirv_modules_parsed;
extern u32 g_spirv_entry_points_seen;
extern u32 g_spirv_capabilities_seen;
extern u32 g_spirv_decorations_seen;
extern u32 g_spirv_execution_modes_seen;
extern u32 g_buffer_copy_bytes;
extern u32 g_buffer_fill_bytes;
extern u32 g_push_constant_writes;
extern u32 g_pipeline_barriers;
extern u32 g_dispatches;
extern u32 g_queries_executed;
extern u32 g_memory_maps;
extern u32 g_image_upload_pixels;
extern u32 g_dynamic_renderings;
extern u32 g_debug_labels;
extern u32 g_secondary_executes;
extern u32 g_secondary_ops_replayed;
extern u32 g_push_descriptor_writes;
extern u32 g_triangles_drawn;
// Pixels written by clear replay against an image-backed
// (host-visible, non-scanout) render target — the D3D11→Vulkan
// back-buffer path. Scanout clears tick g_clear_pixels_painted
// instead.
extern u32 g_image_clear_pixels;

// SPIR-V interpreter counters. Bump in graphics_vk_spirv_exec.cpp
// (per ExecuteEntryPoint call + per step) and in
// graphics_vk_shaderraster.cpp (per draw routed through shaders).
extern u32 g_spirv_programs_built;         // VkCreateShaderModule that produced a parseable Program
extern u32 g_spirv_program_build_failures; // VkCreateShaderModule that rejected at the v1 parser
extern u32 g_spirv_entry_point_executions; // total ExecuteEntryPoint successes
extern u32 g_spirv_step_budget_exhausted;  // ExecuteEntryPoint runs that hit kStepBudget
extern u32 g_shader_raster_draws_painted;  // ShaderRasterizeDraw calls that actually painted
extern u32 g_shader_raster_draws_skipped;  // ShaderRasterizeDraw calls that fell back to fixed-function

// -------------------------------------------------------------------
// Shared helper functions.
// -------------------------------------------------------------------

u32 ColorToRgb(const VkClearColorValue& c);
/// Paint a clear against `image`. Scanout-backed images fill the
/// live framebuffer (bumps g_clear_pixels_painted); non-scanout
/// images with host-visible BGRA8 backing fill the backing words
/// with the packed 0xAARRGGBB color (bumps g_image_clear_pixels).
/// Anything else is a silent no-op.
void PaintClear(VkImage image, VkClearColorValue color);
VkResult AppendOp(VkCommandBuffer cb, const CmdRecord& op);
void ReplayCommandBuffer(VkCommandBuffer cb);

/// State the replay walker hands the rasterizer for each Draw /
/// DrawIndexed dispatch. Carries every bound resource the v1
/// rasterizer cares about — render target, vertex buffer, index
/// buffer, scissor rect, topology, vertex-format hint, depth-test
/// state, and the framebuffer extent (snapshotted at submit time
/// so the rasterizer doesn't keep calling into
/// `display_info::Query()` per pixel).
struct RasterState
{
    VkImage rt_image;
    VkBuffer vertex_buffer;
    u64 vertex_offset;
    VkBuffer index_buffer;
    u64 index_offset;
    VkIndexType index_type;
    bool has_index_buffer;
    bool has_scissor;
    VkRect2D scissor;
    u32 topology;      // Vulkan-spec VkPrimitiveTopology value (0..5 supported; 0/1/2 = point/line/line-strip;
                       // 3/4/5 = triangle list/strip/fan)
    u32 vertex_format; // 0 = v0 (8 bytes, no Z); 1 = v1 (12 bytes, with i16 Z + reserved)
    u32 depth_compare; // VkCompareOp: 0=Never, 1=Less, 2=Equal, 3=LessOrEqual, 4=Greater, 5=NotEqual, 6=GtEq, 7=Always
    bool depth_test;   // SetDepthTestEnable
    bool depth_write;  // SetDepthWriteEnable
    u32 cull_mode;     // VkCullModeFlagBits: 0=None, 1=Front, 2=Back, 3=Both
    u32 front_face;    // VkFrontFace: 0=CounterClockwise, 1=Clockwise
    u32 fb_w;
    u32 fb_h;
    VkPipeline bound_pipeline;            // pipeline handle bound at the last `BindPipeline` op (0 if none)
    VkDescriptorSet bound_descriptor_set; // first set bound at the last `BindDescriptorSets` op (0 if none)
    // Multi-binding vertex buffers. binding N's buffer + offset
    // sit in slots[N]. v0 supports 4 bindings; legacy
    // single-binding callers use slot 0 (the existing
    // vertex_buffer / vertex_offset fields above mirror slots[0]
    // for back-compat).
    static constexpr u32 kMaxVbBindings = 4;
    VkBuffer vb_per_binding[kMaxVbBindings];
    u64 vb_offset_per_binding[kMaxVbBindings];
};

/// Look up the cached SPIR-V Program of a shader handle (returns
/// nullptr if the shader hasn't been loaded, the handle is bad,
/// or the Program parse failed at module-create time).
spirv::Program* ShaderProgram(VkShaderModule shader);

/// Look up the (vs, fs) shader handles bound to a pipeline.
/// Both can be 0 (compute pipeline / unknown).
struct PipelineShaders
{
    VkShaderModule vs;
    VkShaderModule fs;
};
PipelineShaders PipelineShaderHandles(VkPipeline pipe);

/// Look up the (width, height, depth) of an image referenced by
/// a VkImage or VkImageView handle (the same kinds
/// `SampleImageRgba8` accepts). Writes width to out_w, height to
/// out_h, depth to out_d (3D images aren't supported in v0;
/// depth is always 1). Returns true on success, false when the
/// handle doesn't resolve to a live image. Used by the SPIR-V
/// executor's `OpImageQuerySize` / `OpImageQuerySizeLod`
/// handlers so a shader that asks `textureSize(tex, 0)` gets
/// the correct dimensions.
bool QueryImageSize(u64 resource_handle, u32* out_w, u32* out_h, u32* out_d);

/// Sampler addressing modes — passed to SampleImageRgba8 to
/// control what happens at the [0, 1] UV boundary. Values match
/// `VkSamplerAddressMode` (graphics.h) so we can cast without a
/// remap table.
enum class SamplerAddressMode : u8
{
    Repeat = 0,         // UV wraps modulo 1.0 (Sf32 fract)
    MirroredRepeat = 1, // UV wraps modulo 2.0 with reflection
    ClampToEdge = 2,    // texel at the edge is replicated for out-of-range UV
    ClampToBorder = 3,  // out-of-range UV returns the sampler's border colour;
                        // v0 always uses transparent black (0,0,0,0).
};

/// Sample a 2D RGBA8 texel from an image bound via descriptor.
/// `resource_handle` is a VkImage or VkImageView handle as
/// returned by `spirv::LookupDescriptor`; both kinds resolve
/// to the underlying image. u_bits / v_bits are Sf32 bit
/// patterns (raw float values; the addressing mode determines
/// how out-of-range UV gets folded). `mode` selects between
/// clamp-to-edge / repeat / mirrored-repeat. Filtering is
/// bilinear (the v0 sampler doesn't expose a separate
/// Vk_SAMPLER_FILTER_NEAREST option yet). Returns the packed
/// BGRA8 word (0xAARRGGBB). Returns 0xFF000000 (opaque black)
/// on any lookup failure — caller treats it as a fallback.
/// Sample a 2D RGBA8 texel from an image bound via descriptor.
/// `resource_handle` is a VkImage or VkImageView handle as
/// returned by `spirv::LookupDescriptor`; both kinds resolve
/// to the underlying image. u_bits / v_bits are Sf32 bit
/// patterns (raw float values; the addressing mode determines
/// how out-of-range UV gets folded). `mode_u` selects the U-axis
/// addressing mode; `mode_v` selects the V-axis mode (defaults
/// to the same as U for legacy callers that don't care about the
/// asymmetric case). Filtering is bilinear (the v0 sampler
/// doesn't expose a separate Vk_SAMPLER_FILTER_NEAREST option
/// yet). Returns the packed BGRA8 word (0xAARRGGBB). Returns
/// 0xFF000000 (opaque black) on any lookup failure — caller
/// treats it as a fallback.
/// `filter`: 0 = Nearest (single-texel fetch, no blend),
/// 1 = Linear (bilinear blend). Default is Linear because the
/// pre-decouple executor always blended; callers that want
/// nearest-neighbour sample a VkSampler whose `magFilter` is
/// `VkFilter::Nearest` and the executor passes 0 here.
u32 SampleImageRgba8(u64 resource_handle, u32 u_bits, u32 v_bits,
                     SamplerAddressMode mode_u = SamplerAddressMode::ClampToEdge,
                     SamplerAddressMode mode_v = SamplerAddressMode::ClampToEdge, u8 filter = 1u);

/// Look up the address-mode-U recorded by VkCreateSampler against
/// a VkSampler handle. Returns `ClampToEdge` for handle == 0 or
/// an unrecognised handle so a binding without a sampler still
/// produces a defined result.
SamplerAddressMode SamplerAddressModeFor(u64 sampler_handle);

/// V-axis counterpart of `SamplerAddressModeFor`. v0's
/// `SamplerRecord` captures all three axes at VkCreateSampler
/// time; the executor reads U + V independently so a sampler with
/// `(REPEAT, CLAMP_TO_EDGE)` produces tileable-X clamped-Y output
/// (the right shape for a scrolling-strip background pattern).
SamplerAddressMode SamplerAddressModeVFor(u64 sampler_handle);

/// Return the magnification filter recorded by VkCreateSampler.
/// 0 = Nearest (single-texel fetch, no blend), 1 = Linear
/// (bilinear, the existing path). Used by `SampleImageRgba8` to
/// pick the per-pixel sample shape. Falls back to Linear (1) for
/// handle == 0 / unknown so a binding without a sampler keeps
/// the previous filtered behaviour.
u8 SamplerMagFilterFor(u64 sampler_handle);

/// Unfiltered, integer-coordinate BGRA8 texel fetch from an
/// image bound via descriptor. Used by the SPIR-V executor's
/// OpImageFetch / OpImageRead path. Returns 0x00000000
/// (transparent black) on any lookup failure; caller is
/// responsible for the bounds check (so a deliberate
/// out-of-bounds is distinguishable from a failed lookup at the
/// call site). Bit layout: 0xAARRGGBB.
u32 FetchTexelBgra8(u64 resource_handle, u32 x, u32 y);

/// Unfiltered, integer-coordinate BGRA8 texel store to an image
/// bound via descriptor. Used by the SPIR-V executor's
/// OpImageWrite path. Silently no-ops on lookup failure or
/// out-of-bounds coordinate. Bit layout of `argb`: 0xAARRGGBB.
void WriteTexelBgra8(u64 resource_handle, u32 x, u32 y, u32 argb);

/// Format-aware unfiltered texel fetch. Writes four Sf32 bit
/// patterns to `out[4]` — (R, G, B, A) in linear [0, 1] for UNORM
/// formats; raw f32 for SFLOAT. Out-of-bounds coordinates produce
/// (0, 0, 0, 1) per the Vulkan spec for sampler-less reads.
/// Backing-format-dispatched: reads bytes_per_texel from the bound
/// image's `format` field and unpacks accordingly.
void FetchTexel(u64 resource_handle, u32 x, u32 y, u32 out_components[4]);

/// Format-aware unfiltered texel store. Reads four Sf32 bit
/// patterns from `in[4]` — (R, G, B, A) clamped to [0, 1] for
/// UNORM formats; raw f32 for SFLOAT. Out-of-bounds coordinates
/// drop the write silently per the Vulkan spec. Backing-format-
/// dispatched: packs into the bytes_per_texel layout the image's
/// `format` declares.
void WriteTexel(u64 resource_handle, u32 x, u32 y, const u32 in_components[4]);

/// Binary-semaphore signal / consume / poll. Used by VkQueueSubmit
/// (signal after CB replay) and VkAcquireNextImageKHR /
/// VkQueuePresentKHR (signal-then-consume across the swapchain
/// boundary). Returns false on a 0 or unrecognised handle. The
/// consume path returns the pre-consume bit so the caller can tell
/// "had to wait" from "was already signalled".
bool SignalSemaphoreInternal(VkSemaphore sem);
bool ConsumeSemaphoreInternal(VkSemaphore sem);
bool SemaphoreIsSignalled(VkSemaphore sem);

/// Run the SPIR-V shader-based rasterizer for the current draw.
/// Returns true if the shader path actually painted (in which
/// case the caller skips the fixed-function fallback). Returns
/// false if the pipeline doesn't carry interpretable SPIR-V
/// programs OR the input layout doesn't match the supported v1
/// shape — caller falls back to RasterizeDuetDraw.
bool ShaderRasterizeDraw(const RasterState& st, u32 first_vertex, u32 vertex_count);
bool ShaderRasterizeDrawIndexed(const RasterState& st, u32 first_index, u32 index_count, i32 vertex_offset);

/// Dispatch a compute shader. Looks up the bound compute
/// pipeline's CS Program, reads its OpExecutionMode LocalSize
/// (defaults 1,1,1), and runs the entry point once per (workgroup
/// × local invocation) tuple — total invocations =
/// `group_count_xyz * local_size_xyz`. gl_WorkGroupID,
/// gl_LocalInvocationID, gl_GlobalInvocationID, gl_NumWorkgroups,
/// and gl_LocalInvocationIndex are written to the matching Input
/// builtins before each execution.
///
/// Returns true if the bound pipeline carried an interpretable
/// compute shader and at least one invocation ran. Returns false
/// for graphics-only pipelines or when no shader is bound — the
/// caller treats false as "no-op dispatch" (the cmd-buffer
/// counter still bumps).
///
/// Per-dispatch budget cap (kMaxInvocationsPerDispatch) bounds
/// pathological 1024×1024×1024 dispatches; the CPU interpreter
/// would otherwise saturate for minutes.
bool ShaderDispatchCompute(const RasterState& st, u32 group_count_x, u32 group_count_y, u32 group_count_z);

/// Lazy-allocated shared software depth buffer.
///
/// Storage: 16-bit unorm depth, `width * height * 2` bytes, one
/// entry per pixel. Lazily allocated by `DepthSurfaceGetOrAlloc`
/// on the first Z-test draw and sized to the live framebuffer
/// extent. Cleared to `0xFFFF` (far) on alloc.
struct DepthSurface
{
    u16* data;
    u32 w;
    u32 h;
};

/// Get or lazy-alloc the shared depth surface. Returns `nullptr`
/// when the framebuffer is unavailable or the alloc fails — the
/// caller treats that as "depth test off" and falls back to
/// non-depth rasterization.
DepthSurface* DepthSurfaceGetOrAlloc();

/// Clear the depth surface to `value` (0..65535). No-op if not
/// allocated.
void DepthSurfaceClear(u16 value);

/// Free the surface (used by the boot self-test teardown).
void DepthSurfaceFree();

/// Non-indexed draw: walk the vertex buffer in topology order.
void RasterizeDuetDraw(const RasterState& st, u32 first_vertex, u32 vertex_count);

/// Indexed draw: walk the index buffer, dereferencing each
/// `index + vertex_offset` into the vertex buffer.
void RasterizeDuetDrawIndexed(const RasterState& st, u32 first_index, u32 index_count, i32 vertex_offset);

/// Legacy entry point used by older sites + tests. Internally
/// builds a RasterState with `topology = TriangleList` and the
/// live framebuffer extent, then calls `RasterizeDuetDraw`.
void RasterizeDuetTriangles(VkImage rt_image, VkBuffer vertex_buffer, u64 vb_offset, u32 first_vertex,
                            u32 vertex_count);

// One-shot logging dedupe across the ICD.  Each entry-point id
// gets a single boot-log line the first time it's reached;
// subsequent calls are silent.  Storage (the seen-bitmap) lives
// in graphics_vk.cpp.
enum EpId
{
    EpCreateInstance,
    EpEnumeratePhysicalDevices,
    EpCreateDevice,
    EpQueueSubmit,
    EpCreateShaderModule,
    EpCreateGraphicsPipeline,
    EpCreateImage,
    EpClearColorImage,
    EpCount
};
void LogOnce(EpId id, const char* name);

// ----- counter accessors used by the boot self-test ----------------
//
// Same shape as before the header expanded — the selftest TU
// sticks to function-call accessors so it doesn't depend on the
// exact storage layout.

u32 DynamicRenderingsCount();
u32 SecondaryExecutesCount();
u32 SecondaryOpsReplayedCount();
u32 PushDescriptorWritesCount();
u32 InvalidSpirvRejectionsCount();
u32 CommandRecordedCount();
u32 CommandReplayedCount();
u32 SpirvModulesParsedCount();
u32 SpirvEntryPointsSeenCount();
u32 SpirvCapabilitiesSeenCount();
u32 TrianglesDrawnCount();
u32 ImageClearPixelsCount();

// ----- leak check ---------------------------------------------------

bool LeakCheckHandlePools();

} // namespace duetos::subsystems::graphics::internal