sbgl_graphics_hal.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include "sbgl_types.h"

Include dependency graph for sbgl_graphics_hal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	sbgl_GfxTransientAllocation
	Represents a slice of a persistent GPU buffer used for transient data. More...

Typedefs
typedef struct sbgl_GfxContext	sbgl_GfxContext
	Opaque handle for the graphics backend context.

Functions
sbgl_GfxContext *	sbgl_gfx_Init (sbgl_Window *window, struct SblArena *arena, const sbgl_ResourceLimits *limits, bool enableValidation)
	Initializes the graphics backend with configurable resource limits.
void	sbgl_gfx_Shutdown (sbgl_GfxContext *ctx)
bool	sbgl_gfx_BeginFrame (sbgl_GfxContext *ctx)
	Starts a new frame, acquiring an image and starting the command buffer.
void	sbgl_gfx_EndFrame (sbgl_GfxContext *ctx)
	Submits the current frame's commands and presents the image.
void	sbgl_gfx_BeginRenderPass (sbgl_GfxContext *ctx, float r, float g, float b, float a)
	Starts a graphics rendering pass.
void	sbgl_gfx_EndRenderPass (sbgl_GfxContext *ctx)
	Ends the current graphics rendering pass.
void	sbgl_gfx_DeviceWaitIdle (sbgl_GfxContext *ctx)
sbgl_Buffer	sbgl_gfx_CreateBuffer (sbgl_GfxContext *ctx, sbgl_BufferUsage usage, size_t size, const void *data)
void	sbgl_gfx_DestroyBuffer (sbgl_GfxContext *ctx, sbgl_Buffer buffer)
void	sbgl_gfx_FillBuffer (sbgl_GfxContext *ctx, sbgl_Buffer buffer, size_t offset, size_t size, uint32_t value)
	Performs a hardware-accelerated buffer fill.
uint32_t	sbgl_gfx_GetFrameIndex (sbgl_GfxContext *ctx)
	Retrieves the current backend frame index.
void *	sbgl_gfx_MapBuffer (sbgl_GfxContext *ctx, sbgl_Buffer buffer)
void	sbgl_gfx_UnmapBuffer (sbgl_GfxContext *ctx, sbgl_Buffer buffer)
sbgl_Shader	sbgl_gfx_LoadShader (sbgl_GfxContext *ctx, sbgl_ShaderStage stage, const uint32_t *bytecode, size_t size)
void	sbgl_gfx_DestroyShader (sbgl_GfxContext *ctx, sbgl_Shader shader)
sbgl_Pipeline	sbgl_gfx_CreatePipeline (sbgl_GfxContext *ctx, const sbgl_PipelineConfig *config)
void	sbgl_gfx_DestroyPipeline (sbgl_GfxContext *ctx, sbgl_Pipeline pipeline)
sbgl_ComputePipeline	sbgl_gfx_CreateComputePipeline (sbgl_GfxContext *ctx, sbgl_Shader shader)
void	sbgl_gfx_DestroyComputePipeline (sbgl_GfxContext *ctx, sbgl_ComputePipeline pipeline)
void	sbgl_gfx_BindComputePipeline (sbgl_GfxContext *ctx, sbgl_ComputePipeline pipeline)
void	sbgl_gfx_DispatchCompute (sbgl_GfxContext *ctx, uint32_t groupCountX, uint32_t groupCountY, uint32_t groupCountZ)
void	sbgl_gfx_MemoryBarrier (sbgl_GfxContext *ctx, sbgl_BarrierType type)
void	sbgl_gfx_BindPipeline (sbgl_GfxContext *ctx, sbgl_Pipeline pipeline)
void	sbgl_gfx_BindBuffer (sbgl_GfxContext *ctx, sbgl_Buffer buffer, sbgl_BufferUsage usage)
void	sbgl_gfx_Draw (sbgl_GfxContext *ctx, uint32_t vertexCount, uint32_t firstVertex, uint32_t instanceCount)
void	sbgl_gfx_DrawIndexed (sbgl_GfxContext *ctx, uint32_t indexCount, uint32_t firstIndex, int32_t vertexOffset, uint32_t instanceCount)
void	sbgl_gfx_DrawIndirect (sbgl_GfxContext *ctx, sbgl_Buffer buffer, size_t offset, uint32_t drawCount)
	Submits a batch of draw calls stored in a GPU buffer.
sbgl_GfxTransientAllocation	sbgl_gfx_AllocateTransient (sbgl_GfxContext *ctx, size_t size, uint32_t alignment)
	Allocates a slice of GPU-visible memory for transient per-frame data.
uint64_t	sbgl_gfx_GetBufferDeviceAddress (sbgl_GfxContext *ctx, sbgl_Buffer buffer)
	Retrieves the 64-bit GPU virtual address for a buffer.
void	sbgl_gfx_DestroyBufferDeferred (sbgl_GfxContext *ctx, sbgl_Buffer buffer)
	Marks a buffer for destruction after current frames complete.
void	sbgl_gfx_PushConstants (sbgl_GfxContext *ctx, size_t size, const void *data)
float	sbgl_gfx_GetGpuTime (sbgl_GfxContext *ctx)
	Retrieves the elapsed GPU time for the previous frame in milliseconds.
int32_t	sbgl_gfx_GetLastVkResult (sbgl_GfxContext *ctx)
	Retrieves the last VkResult from the backend for error inspection.

Typedef Documentation

sbgl_GfxContext

typedef struct sbgl_GfxContext sbgl_GfxContext

Opaque handle for the graphics backend context.

Definition at line 21 of file sbgl_graphics_hal.h.

Function Documentation

sbgl_gfx_AllocateTransient()

sbgl_GfxTransientAllocation sbgl_gfx_AllocateTransient	(	sbgl_GfxContext *	ctx,
		size_t	size,
		uint32_t	alignment )

Allocates a slice of GPU-visible memory for transient per-frame data.

This memory is managed by the backend's internal per-frame ring buffers and does not require manual destruction.

Parameters

ctx	The graphics context.
size	The number of bytes to allocate.
alignment	The required byte alignment for the allocation.

Returns

A structure containing the allocation metadata and mapped pointer.

Definition at line 2040 of file sbgl_backend_vulkan.c.

                                                                                  {
  /* The system sub-allocates from the current frame's persistent buffer, respecting
     the requested alignment to ensure compatibility with Vulkan requirements. */
  uint32_t frame = ctx->currentFrame;
  uint32_t offset = ctx->transientOffsets[frame];
 
  if (alignment > 0) {
    offset = (offset + alignment - 1) & ~(alignment - 1);
  }
 
  if (offset + size > SBGL_TRANSIENT_BUFFER_SIZE) {
    fprintf(stderr, "[Vulkan] Transient buffer overflow for frame %u!\n", frame);
    return (sbgl_GfxTransientAllocation){ 0 };
  }
 
  sbgl_GfxTransientAllocation alloc = {
    .buffer = ctx->transientBuffers[frame],
    .offset = offset,
    .size = (uint32_t)size,
    .mapped = (char*)ctx->transientMapped[frame] + offset,
    .deviceAddress = sbgl_gfx_GetBufferDeviceAddress(ctx, ctx->transientBuffers[frame]) + offset
  };
 
  ctx->transientOffsets[frame] = offset + (uint32_t)size;
  return alloc;
}

sbgl_gfx_BeginFrame()

bool sbgl_gfx_BeginFrame

(

sbgl_GfxContext *

ctx

)

Starts a new frame, acquiring an image and starting the command buffer.

This must be called before any GPU commands (Compute or Graphics) are recorded.

Definition at line 1106 of file sbgl_backend_vulkan.c.

                                               {
  ctx->vk.vkWaitForFences(
    ctx->device,
    1,
    &ctx->inFlightFences[ctx->currentFrame],
    VK_TRUE,
    UINT64_MAX
  );
 
  /* The system processes the deferred destruction queue for the current frame slot,
     releasing GPU resources that are no longer in flight. */
  for (uint32_t i = 0; i < ctx->deferredCount[ctx->currentFrame]; i++) {
    sbgl_gfx_DestroyBuffer(ctx, ctx->deferredBuffers[ctx->currentFrame][i]);
  }
  ctx->deferredCount[ctx->currentFrame] = 0;
 
  /* The transient allocation offset is reset for the current frame, effectively
     recycling the GPU memory for new data while ensuring it does not overlap with
     memory currently in use by other frames in flight. */
  ctx->transientOffsets[ctx->currentFrame] = 0;
  ctx->dynamicHeap.offset[ctx->currentFrame] = 0;
 
  if (sbgl_os_WasWindowResized(ctx->window)) {
    recreate_swapchain(ctx);
  }
 
  VkResult result = ctx->vk.vkAcquireNextImageKHR(
    ctx->device,
    ctx->swapchain,
    UINT64_MAX,
    ctx->imageAvailableSemaphores[ctx->semaphoreIndex],
    VK_NULL_HANDLE,
    &ctx->currentImageIndex
  );
 
  ctx->backendResult = result;
 
  if (result == VK_ERROR_OUT_OF_DATE_KHR) {
    recreate_swapchain(ctx);
    return false;
  } else if (result != VK_SUCCESS && result != VK_SUBOPTIMAL_KHR) {
    return false;
  }
 
  ctx->vk.vkResetFences(ctx->device, 1, &ctx->inFlightFences[ctx->currentFrame]);
  ctx->vk.vkResetCommandBuffer(ctx->commandBuffers[ctx->currentFrame], 0);
  VkCommandBufferBeginInfo beginInfo = { .sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO };
  ctx->vk.vkBeginCommandBuffer(ctx->commandBuffers[ctx->currentFrame], &beginInfo);
 
  /* The system resets the query pool for the current frame to prepare for new
     timestamp recordings. */
  ctx->vk.vkCmdResetQueryPool(
    ctx->commandBuffers[ctx->currentFrame],
    ctx->queryPool,
    ctx->currentFrame * 2,
    2
  );
 
  return true;
}

sbgl_gfx_BeginRenderPass()

void sbgl_gfx_BeginRenderPass	(	sbgl_GfxContext *	ctx,
		float	r,
		float	g,
		float	b,
		float	a )

Starts a graphics rendering pass.

This must be called before any draw commands are recorded. It handles clearing the attachments if requested.

Definition at line 1167 of file sbgl_backend_vulkan.c.

                                                                                        {
  /* The system records the starting timestamp at the beginning of the graphics pass. */
  ctx->vk.vkCmdWriteTimestamp(
    ctx->commandBuffers[ctx->currentFrame],
    VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT,
    ctx->queryPool,
    ctx->currentFrame * 2
  );
 
  VkImageMemoryBarrier barriers[2] = { 0 };
  barriers[0].sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
  barriers[0].oldLayout = VK_IMAGE_LAYOUT_UNDEFINED;
  barriers[0].newLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL;
  barriers[0].image = ctx->images[ctx->currentImageIndex];
  barriers[0].subresourceRange =
    (VkImageSubresourceRange){ .aspectMask = VK_IMAGE_ASPECT_COLOR_BIT,
                   .levelCount = 1,
                   .layerCount = 1 };
  barriers[0].dstAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT;
 
  barriers[1].sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
  barriers[1].oldLayout = VK_IMAGE_LAYOUT_UNDEFINED;
  barriers[1].newLayout = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL;
  barriers[1].image = ctx->depthImage;
  barriers[1].subresourceRange =
    (VkImageSubresourceRange){ .aspectMask = VK_IMAGE_ASPECT_DEPTH_BIT,
                   .levelCount = 1,
                   .layerCount = 1 };
  barriers[1].dstAccessMask = VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT;
 
  ctx->vk.vkCmdPipelineBarrier(
    ctx->commandBuffers[ctx->currentFrame],
    VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT,
    VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT | VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT,
    0,
    0,
    NULL,
    0,
    NULL,
    2,
    barriers
  );
 
  VkRenderingAttachmentInfo colorAttachment = {
    .sType = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO,
    .imageView = ctx->imageViews[ctx->currentImageIndex],
    .imageLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
    .loadOp = VK_ATTACHMENT_LOAD_OP_CLEAR,
    .storeOp = VK_ATTACHMENT_STORE_OP_STORE,
    .clearValue = { { { r, g, b, a } } },
  };
 
  VkRenderingAttachmentInfo depthAttachment = {
    .sType = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO,
    .imageView = ctx->depthImageView,
    .imageLayout = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL,
    .loadOp = VK_ATTACHMENT_LOAD_OP_CLEAR,
    .storeOp = VK_ATTACHMENT_STORE_OP_STORE,
    .clearValue = { .depthStencil = { 1.0f, 0 } },
  };
 
  VkRenderingInfo renderingInfo = {
    .sType = VK_STRUCTURE_TYPE_RENDERING_INFO,
    .renderArea = { .extent = ctx->swapchainExtent },
    .layerCount = 1,
    .colorAttachmentCount = 1,
    .pColorAttachments = &colorAttachment,
    .pDepthAttachment = &depthAttachment,
  };
 
  ctx->vk.vkCmdBeginRendering(ctx->commandBuffers[ctx->currentFrame], &renderingInfo);
}

sbgl_gfx_BindBuffer()

void sbgl_gfx_BindBuffer	(	sbgl_GfxContext *	ctx,
		sbgl_Buffer	buffer,
		sbgl_BufferUsage	usage )

Definition at line 1971 of file sbgl_backend_vulkan.c.

                                                                                           {
  if (handle == SBGL_INVALID_HANDLE)
    return;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxBuffers || !ctx->bufferActive[index])
    return;
 
  if (usage == SBGL_BUFFER_USAGE_VERTEX) {
    VkDeviceSize offsets[] = { 0 };
    ctx->vk.vkCmdBindVertexBuffers(
      ctx->commandBuffers[ctx->currentFrame],
      0,
      1,
      &ctx->buffers[index].handle,
      offsets
    );
  } else if (usage == SBGL_BUFFER_USAGE_INDEX) {
    ctx->vk.vkCmdBindIndexBuffer(
      ctx->commandBuffers[ctx->currentFrame],
      ctx->buffers[index].handle,
      0,
      VK_INDEX_TYPE_UINT32
    );
  }
}

sbgl_gfx_BindComputePipeline()

void sbgl_gfx_BindComputePipeline	(	sbgl_GfxContext *	ctx,
		sbgl_ComputePipeline	pipeline )

Definition at line 1851 of file sbgl_backend_vulkan.c.

                                                                                     {
  /* The currently active command buffer is updated to utilize the specified compute
     pipeline for all subsequent dispatch operations. */
  if (handle == SBGL_INVALID_HANDLE) {
    ctx->boundComputePipeline = SBGL_INVALID_HANDLE;
    return;
  }
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxPipelines || !ctx->computePipelines[index].active)
    return;
 
  ctx->vk.vkCmdBindPipeline(
    ctx->commandBuffers[ctx->currentFrame],
    VK_PIPELINE_BIND_POINT_COMPUTE,
    ctx->computePipelines[index].handle
  );
  ctx->boundComputePipeline = handle;
}

sbgl_gfx_BindPipeline()

void sbgl_gfx_BindPipeline	(	sbgl_GfxContext *	ctx,
		sbgl_Pipeline	pipeline )

Definition at line 1943 of file sbgl_backend_vulkan.c.

                                                                       {
  if (handle == SBGL_INVALID_HANDLE)
    return;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxPipelines || !ctx->pipelines[index].active)
    return;
 
  ctx->vk.vkCmdBindPipeline(
    ctx->commandBuffers[ctx->currentFrame],
    VK_PIPELINE_BIND_POINT_GRAPHICS,
    ctx->pipelines[index].handle
  );
  ctx->boundPipeline = handle;
 
  VkViewport viewport = {
    .x = 0.0f,
    .y = (float)ctx->swapchainExtent.height,
    .width = (float)ctx->swapchainExtent.width,
    .height = -(float)ctx->swapchainExtent.height,
    .minDepth = 0.0f,
    .maxDepth = 1.0f,
  };
  ctx->vk.vkCmdSetViewport(ctx->commandBuffers[ctx->currentFrame], 0, 1, &viewport);
 
  VkRect2D scissor = { .offset = { 0, 0 }, .extent = ctx->swapchainExtent };
  ctx->vk.vkCmdSetScissor(ctx->commandBuffers[ctx->currentFrame], 0, 1, &scissor);
}

sbgl_gfx_CreateBuffer()

sbgl_Buffer sbgl_gfx_CreateBuffer	(	sbgl_GfxContext *	ctx,
		sbgl_BufferUsage	usage,
		size_t	size,
		const void *	data )

Definition at line 1324 of file sbgl_backend_vulkan.c.

                                                                                                   {
  /* Search for an available buffer slot in the internal tracking arrays. */
  uint32_t index = 0;
  for (; index < ctx->limits.maxBuffers; index++) {
    if (!ctx->bufferActive[index])
      break;
  }
  if (index == ctx->limits.maxBuffers)
    return SBGL_INVALID_HANDLE;
 
  /* Identify the target memory heap based on the buffer's intended usage.
     Vertex and index buffers are assigned to the static heap, while storage
     buffers utilize the managed heap for persistence. */
  SBGL_HeapType heapType = SBGL_HEAP_TYPE_MANAGED;
  if (usage & (SBGL_BUFFER_USAGE_VERTEX | SBGL_BUFFER_USAGE_INDEX)) {
    heapType = SBGL_HEAP_TYPE_STATIC;
  } else if (usage & SBGL_BUFFER_USAGE_STORAGE) {
    heapType = SBGL_HEAP_TYPE_MANAGED;
  }
 
  VkBufferCreateInfo bufferInfo = {
    .sType = VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO,
    .size = size,
    .usage = (usage & SBGL_BUFFER_USAGE_VERTEX ? VK_BUFFER_USAGE_VERTEX_BUFFER_BIT : 0) |
         (usage & SBGL_BUFFER_USAGE_INDEX ? VK_BUFFER_USAGE_INDEX_BUFFER_BIT : 0) |
         (usage & SBGL_BUFFER_USAGE_STORAGE ? VK_BUFFER_USAGE_STORAGE_BUFFER_BIT : 0) |
         (usage & SBGL_BUFFER_USAGE_INDIRECT ? VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT : 0) |
         (usage & SBGL_BUFFER_USAGE_TRANSFER_DST ? VK_BUFFER_USAGE_TRANSFER_DST_BIT : 0) |
         VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,
    .sharingMode = VK_SHARING_MODE_EXCLUSIVE,
  };
 
  SBGL_VulkanBuffer* buffer = &ctx->buffers[index];
  if (ctx->vk.vkCreateBuffer(ctx->device, &bufferInfo, NULL, &buffer->handle) != VK_SUCCESS) {
    return SBGL_INVALID_HANDLE;
  }
 
  VkMemoryRequirements memRequirements;
  ctx->vk.vkGetBufferMemoryRequirements(ctx->device, buffer->handle, &memRequirements);
 
  /* Sub-allocate the required memory range from the selected hybrid heap. */
  uint32_t offset = SBGL_INVALID_OFFSET;
  VkDeviceMemory heapMemory = VK_NULL_HANDLE;
  void* heapMappedBase = NULL;
 
  switch (heapType) {
  case SBGL_HEAP_TYPE_STATIC:
    offset = static_heap_alloc(ctx, memRequirements.size);
    heapMemory = ctx->staticHeap.memory;
    heapMappedBase = ctx->staticHeap.mapped;
    break;
  case SBGL_HEAP_TYPE_DYNAMIC:
    offset = dynamic_heap_alloc(ctx, memRequirements.size);
    heapMemory = ctx->dynamicHeap.memory;
    heapMappedBase = ctx->dynamicHeap.mapped[ctx->currentFrame];
    break;
  case SBGL_HEAP_TYPE_MANAGED:
    offset = managed_heap_alloc(ctx, memRequirements.size);
    heapMemory = ctx->managedHeap.memory;
    heapMappedBase = ctx->managedHeap.mapped;
    break;
  }
 
  if (offset == SBGL_INVALID_OFFSET) {
    ctx->vk.vkDestroyBuffer(ctx->device, buffer->handle, NULL);
    return SBGL_INVALID_HANDLE;
  }
 
  /* Bind the buffer handle to the sub-allocated memory region within the heap. */
  ctx->vk.vkBindBufferMemory(ctx->device, buffer->handle, heapMemory, offset);
 
  buffer->size = size;
  buffer->offset = offset;
  buffer->heapType = heapType;
  buffer->mapped = (char*)heapMappedBase + offset;
  ctx->bufferActive[index] = true;
 
  /* If initial data is provided, perform an immediate memory copy to the 
     persistently mapped buffer address. */
  if (data && buffer->mapped) {
    memcpy(buffer->mapped, data, size);
  }
 
  return (sbgl_Buffer)(index + 1);
}

sbgl_gfx_CreateComputePipeline()

sbgl_ComputePipeline sbgl_gfx_CreateComputePipeline	(	sbgl_GfxContext *	ctx,
		sbgl_Shader	shader )

Definition at line 1764 of file sbgl_backend_vulkan.c.

                                                                                              {
  /* The system scans the internal pipeline storage for an available slot to allocate
     the new compute pipeline state. */
  uint32_t index = 0;
  for (; index < ctx->limits.maxPipelines; index++) {
    if (!ctx->computePipelines[index].active)
      break;
  }
  if (index == ctx->limits.maxPipelines)
    return SBGL_INVALID_HANDLE;
 
  if (handle == SBGL_INVALID_HANDLE || handle > ctx->limits.maxShaders) {
    fprintf(stderr, "[Vulkan] Invalid compute shader handle\n");
    return SBGL_INVALID_HANDLE;
  }
  uint32_t shaderIndex = handle - 1;
  if (!ctx->shaders[shaderIndex].active || ctx->shaders[shaderIndex].stage != SBGL_SHADER_STAGE_COMPUTE) {
    fprintf(stderr, "[Vulkan] Invalid compute shader stage or inactive shader\n");
    return SBGL_INVALID_HANDLE;
  }
 
  VkPipelineShaderStageCreateInfo stageInfo = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO,
    .stage = VK_SHADER_STAGE_COMPUTE_BIT,
    .module = ctx->shaders[shaderIndex].module,
    .pName = "main",
  };
 
  VkPipelineLayoutCreateInfo layoutInfo = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO,
  };
 
  /* The system utilizes a standardized push constant block across both graphics
     and compute pipelines to maintain architectural consistency. */
  VkPushConstantRange pushConstantRange = {
    .stageFlags = VK_SHADER_STAGE_COMPUTE_BIT,
    .offset = 0,
    .size = SBGL_VK_PUSH_CONSTANT_SIZE,
  };
  layoutInfo.pushConstantRangeCount = 1;
  layoutInfo.pPushConstantRanges = &pushConstantRange;
 
  if (ctx->vk.vkCreatePipelineLayout(
      ctx->device,
      &layoutInfo,
      NULL,
      &ctx->computePipelines[index].layout
    ) != VK_SUCCESS) {
    return SBGL_INVALID_HANDLE;
  }
 
  VkComputePipelineCreateInfo pipelineInfo = {
    .sType = VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO,
    .stage = stageInfo,
    .layout = ctx->computePipelines[index].layout,
  };
 
  if (ctx->vk.vkCreateComputePipelines(
      ctx->device,
      VK_NULL_HANDLE,
      1,
      &pipelineInfo,
      NULL,
      &ctx->computePipelines[index].handle
    ) != VK_SUCCESS) {
    ctx->vk.vkDestroyPipelineLayout(ctx->device, ctx->computePipelines[index].layout, NULL);
    return SBGL_INVALID_HANDLE;
  }
 
  ctx->computePipelines[index].active = true;
  return (sbgl_ComputePipeline)(index + 1);
}

sbgl_gfx_CreatePipeline()

sbgl_Pipeline sbgl_gfx_CreatePipeline	(	sbgl_GfxContext *	ctx,
		const sbgl_PipelineConfig *	config )

Definition at line 1551 of file sbgl_backend_vulkan.c.

                                                                                               {
  uint32_t index = 0;
  for (; index < ctx->limits.maxPipelines; index++) {
    if (!ctx->pipelines[index].active)
      break;
  }
  if (index == ctx->limits.maxPipelines)
    return SBGL_INVALID_HANDLE;
 
  VkPipelineShaderStageCreateInfo shaderStages[2] = { 0 };
 
  // Vertex Shader
  if (config->vertexShader == SBGL_INVALID_HANDLE || config->vertexShader > ctx->limits.maxShaders) {
    fprintf(stderr, "[Vulkan] Invalid vertex shader handle\n");
    return SBGL_INVALID_HANDLE;
  }
  uint32_t vsIndex = config->vertexShader - 1;
  if (!ctx->shaders[vsIndex].active || ctx->shaders[vsIndex].stage != SBGL_SHADER_STAGE_VERTEX) {
    fprintf(stderr, "[Vulkan] Invalid vertex shader stage or inactive shader\n");
    return SBGL_INVALID_HANDLE;
  }
  shaderStages[0].sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO;
  shaderStages[0].stage = VK_SHADER_STAGE_VERTEX_BIT;
  shaderStages[0].module = ctx->shaders[vsIndex].module;
  shaderStages[0].pName = "main";
 
  // Fragment Shader
  if (config->fragmentShader == SBGL_INVALID_HANDLE || config->fragmentShader > ctx->limits.maxShaders) {
    fprintf(stderr, "[Vulkan] Invalid fragment shader handle\n");
    return SBGL_INVALID_HANDLE;
  }
  uint32_t fsIndex = config->fragmentShader - 1;
  if (!ctx->shaders[fsIndex].active || ctx->shaders[fsIndex].stage != SBGL_SHADER_STAGE_FRAGMENT) {
    fprintf(stderr, "[Vulkan] Invalid fragment shader stage or inactive shader\n");
    return SBGL_INVALID_HANDLE;
  }
  shaderStages[1].sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO;
  shaderStages[1].stage = VK_SHADER_STAGE_FRAGMENT_BIT;
  shaderStages[1].module = ctx->shaders[fsIndex].module;
  shaderStages[1].pName = "main";
 
  VkVertexInputBindingDescription bindingDescription = {
    .binding = 0,
    .stride = config->vertexLayout.stride,
    .inputRate = VK_VERTEX_INPUT_RATE_VERTEX,
  };
 
  SblArenaMark mark = sbl_arena_mark(ctx->arena);
  VkVertexInputAttributeDescription* attributeDescriptions = SBL_ARENA_PUSH_ARRAY(
    ctx->arena,
    VkVertexInputAttributeDescription,
    config->vertexLayout.attributeCount
  );
  if (!attributeDescriptions && config->vertexLayout.attributeCount > 0) {
    return SBGL_INVALID_HANDLE;
  }
  for (uint32_t i = 0; i < config->vertexLayout.attributeCount; i++) {
    attributeDescriptions[i].binding = 0;
    attributeDescriptions[i].location = config->vertexLayout.attributes[i].location;
    attributeDescriptions[i].format =
      sbgl_to_vk_format(config->vertexLayout.attributes[i].format);
    attributeDescriptions[i].offset = config->vertexLayout.attributes[i].offset;
  }
 
  VkPipelineVertexInputStateCreateInfo vertexInputInfo = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO,
    .vertexBindingDescriptionCount = 1,
    .pVertexBindingDescriptions = &bindingDescription,
    .vertexAttributeDescriptionCount = config->vertexLayout.attributeCount,
    .pVertexAttributeDescriptions = attributeDescriptions,
  };
 
  VkPipelineInputAssemblyStateCreateInfo inputAssembly = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO,
    .topology = VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,
    .primitiveRestartEnable = VK_FALSE,
  };
 
  VkPipelineViewportStateCreateInfo viewportState = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO,
    .viewportCount = 1,
    .scissorCount = 1,
  };
 
  VkPipelineRasterizationStateCreateInfo rasterizer = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO,
    .depthClampEnable = VK_FALSE,
    .rasterizerDiscardEnable = VK_FALSE,
    .polygonMode = VK_POLYGON_MODE_FILL,
    .lineWidth = 1.0f,
    .cullMode = VK_CULL_MODE_BACK_BIT,
    .frontFace = VK_FRONT_FACE_COUNTER_CLOCKWISE,
    .depthBiasEnable = VK_FALSE,
  };
 
  VkPipelineMultisampleStateCreateInfo multisampling = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO,
    .sampleShadingEnable = VK_FALSE,
    .rasterizationSamples = VK_SAMPLE_COUNT_1_BIT,
  };
 
  VkPipelineDepthStencilStateCreateInfo depthStencil = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO,
    .depthTestEnable = VK_TRUE,
    .depthWriteEnable = VK_TRUE,
    .depthCompareOp = VK_COMPARE_OP_LESS,
    .depthBoundsTestEnable = VK_FALSE,
    .stencilTestEnable = VK_FALSE,
  };
 
  VkPipelineColorBlendAttachmentState colorBlendAttachment = {
    .colorWriteMask = VK_COLOR_COMPONENT_R_BIT | VK_COLOR_COMPONENT_G_BIT |
              VK_COLOR_COMPONENT_B_BIT | VK_COLOR_COMPONENT_A_BIT,
    .blendEnable = (config->blendMode != SBGL_BLEND_MODE_NONE) ? VK_TRUE : VK_FALSE,
    .srcColorBlendFactor = (config->blendMode == SBGL_BLEND_MODE_ADDITIVE) ? VK_BLEND_FACTOR_ONE : VK_BLEND_FACTOR_SRC_ALPHA,
    .dstColorBlendFactor = (config->blendMode == SBGL_BLEND_MODE_ADDITIVE) ? VK_BLEND_FACTOR_ONE : VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA,
    .colorBlendOp = VK_BLEND_OP_ADD,
    .srcAlphaBlendFactor = VK_BLEND_FACTOR_ONE,
    .dstAlphaBlendFactor = VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA,
    .alphaBlendOp = VK_BLEND_OP_ADD,
  };
 
  VkPipelineColorBlendStateCreateInfo colorBlending = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO,
    .logicOpEnable = VK_FALSE,
    .attachmentCount = 1,
    .pAttachments = &colorBlendAttachment,
  };
 
  VkDynamicState dynamicStates[] = { VK_DYNAMIC_STATE_VIEWPORT, VK_DYNAMIC_STATE_SCISSOR };
  VkPipelineDynamicStateCreateInfo dynamicState = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO,
    .dynamicStateCount = 2,
    .pDynamicStates = dynamicStates,
  };
 
  VkPipelineLayoutCreateInfo pipelineLayoutInfo = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO,
  };
 
  VkPushConstantRange pushConstantRange = {
    .stageFlags = VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT,
    .offset = 0,
    .size = SBGL_VK_PUSH_CONSTANT_SIZE,
  };
  pipelineLayoutInfo.pushConstantRangeCount = 1;
  pipelineLayoutInfo.pPushConstantRanges = &pushConstantRange;
 
  if (ctx->vk.vkCreatePipelineLayout(
      ctx->device,
      &pipelineLayoutInfo,
      NULL,
      &ctx->pipelines[index].layout
    ) != VK_SUCCESS) {
    sbl_arena_rewind(ctx->arena, mark);
    return SBGL_INVALID_HANDLE;
  }
 
  VkPipelineRenderingCreateInfo renderingCreateInfo = {
    .sType = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO,
    .colorAttachmentCount = 1,
    .pColorAttachmentFormats = &ctx->swapchainFormat,
    .depthAttachmentFormat = ctx->depthFormat,
  };
 
  VkGraphicsPipelineCreateInfo pipelineInfo = {
    .sType = VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO,
    .pNext = &renderingCreateInfo,
    .stageCount = 2,
    .pStages = shaderStages,
    .pVertexInputState = &vertexInputInfo,
    .pInputAssemblyState = &inputAssembly,
    .pViewportState = &viewportState,
    .pRasterizationState = &rasterizer,
    .pMultisampleState = &multisampling,
    .pDepthStencilState = &depthStencil,
    .pColorBlendState = &colorBlending,
    .pDynamicState = &dynamicState,
    .layout = ctx->pipelines[index].layout,
    .renderPass = VK_NULL_HANDLE,
    .subpass = 0,
  };
 
  if (ctx->vk.vkCreateGraphicsPipelines(
      ctx->device,
      VK_NULL_HANDLE,
      1,
      &pipelineInfo,
      NULL,
      &ctx->pipelines[index].handle
    ) != VK_SUCCESS) {
    ctx->vk.vkDestroyPipelineLayout(ctx->device, ctx->pipelines[index].layout, NULL);
    sbl_arena_rewind(ctx->arena, mark);
    return SBGL_INVALID_HANDLE;
  }
 
  sbl_arena_rewind(ctx->arena, mark);
  ctx->pipelines[index].active = true;
  return (sbgl_Pipeline)(index + 1);
}

sbgl_gfx_DestroyBuffer()

void sbgl_gfx_DestroyBuffer	(	sbgl_GfxContext *	ctx,
		sbgl_Buffer	buffer )

Definition at line 1410 of file sbgl_backend_vulkan.c.

                                                                      {
  /* The system releases the GPU-side buffer handle and, if the memory was
     allocated from the managed heap, returns the range to the sub-allocator
     to mitigate memory fragmentation. Static and Dynamic allocations are
     reclaimed automatically or persist until shutdown. */
  if (handle == SBGL_INVALID_HANDLE)
    return;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxBuffers || !ctx->bufferActive[index])
    return;
 
  SBGL_VulkanBuffer* buffer = &ctx->buffers[index];
  ctx->vk.vkDestroyBuffer(ctx->device, buffer->handle, NULL);
 
  if (buffer->heapType == SBGL_HEAP_TYPE_MANAGED) {
    managed_heap_free(ctx, buffer->offset);
  }
 
  ctx->bufferActive[index] = false;
}

sbgl_gfx_DestroyBufferDeferred()

void sbgl_gfx_DestroyBufferDeferred	(	sbgl_GfxContext *	ctx,
		sbgl_Buffer	buffer )

Marks a buffer for destruction after current frames complete.

This function should be used for temporary buffers that are submitted for GPU execution in the current frame and must not be destroyed until the GPU has finished using them.

Parameters

ctx	The graphics context.
buffer	Handle to the buffer to destroy.

Definition at line 1480 of file sbgl_backend_vulkan.c.

                                                                              {
  /* The system queues the buffer for destruction after the current frame's GPU work
     is guaranteed to be complete, preventing premature release of in-flight resources. */
  if (ctx->deferredCount[ctx->currentFrame] < 64) {
    ctx->deferredBuffers[ctx->currentFrame][ctx->deferredCount[ctx->currentFrame]++] = handle;
  } else {
    /* If the deferred queue is full, the system falls back to immediate destruction
       after a device idle wait to maintain safety at the cost of performance. */
    sbgl_gfx_DeviceWaitIdle(ctx);
    sbgl_gfx_DestroyBuffer(ctx, handle);
  }
}

sbgl_gfx_DestroyComputePipeline()

void sbgl_gfx_DestroyComputePipeline	(	sbgl_GfxContext *	ctx,
		sbgl_ComputePipeline	pipeline )

Definition at line 1837 of file sbgl_backend_vulkan.c.

                                                                                        {
  /* The system releases the GPU-side pipeline and layout resources and marks
     the internal slot as inactive for future reuse. */
  if (handle == SBGL_INVALID_HANDLE)
    return;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxPipelines || !ctx->computePipelines[index].active)
    return;
 
  ctx->vk.vkDestroyPipeline(ctx->device, ctx->computePipelines[index].handle, NULL);
  ctx->vk.vkDestroyPipelineLayout(ctx->device, ctx->computePipelines[index].layout, NULL);
  ctx->computePipelines[index].active = false;
}

sbgl_gfx_DestroyPipeline()

void sbgl_gfx_DestroyPipeline	(	sbgl_GfxContext *	ctx,
		sbgl_Pipeline	pipeline )

Definition at line 1752 of file sbgl_backend_vulkan.c.

                                                                          {
  if (handle == SBGL_INVALID_HANDLE)
    return;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxPipelines || !ctx->pipelines[index].active)
    return;
 
  ctx->vk.vkDestroyPipeline(ctx->device, ctx->pipelines[index].handle, NULL);
  ctx->vk.vkDestroyPipelineLayout(ctx->device, ctx->pipelines[index].layout, NULL);
  ctx->pipelines[index].active = false;
}

sbgl_gfx_DestroyShader()

void sbgl_gfx_DestroyShader	(	sbgl_GfxContext *	ctx,
		sbgl_Shader	shader )

Definition at line 1540 of file sbgl_backend_vulkan.c.

                                                                      {
  if (handle == SBGL_INVALID_HANDLE)
    return;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxShaders || !ctx->shaders[index].active)
    return;
 
  ctx->vk.vkDestroyShaderModule(ctx->device, ctx->shaders[index].module, NULL);
  ctx->shaders[index].active = false;
}

sbgl_gfx_DeviceWaitIdle()

void sbgl_gfx_DeviceWaitIdle

(

sbgl_GfxContext *

ctx

)

Definition at line 1317 of file sbgl_backend_vulkan.c.

                                                   {
  if (ctx && ctx->device) {
    ctx->vk.vkDeviceWaitIdle(ctx->device);
  }
}

sbgl_gfx_DispatchCompute()

void sbgl_gfx_DispatchCompute	(	sbgl_GfxContext *	ctx,
		uint32_t	groupCountX,
		uint32_t	groupCountY,
		uint32_t	groupCountZ )

Definition at line 1870 of file sbgl_backend_vulkan.c.

                                                                                        {
  /* A compute dispatch command is recorded into the current frame's command buffer,
     triggering parallel execution across the specified workgroup dimensions. */
  ctx->vk.vkCmdDispatch(ctx->commandBuffers[ctx->currentFrame], x, y, z);
}

sbgl_gfx_Draw()

void sbgl_gfx_Draw	(	sbgl_GfxContext *	ctx,
		uint32_t	vertexCount,
		uint32_t	firstVertex,
		uint32_t	instanceCount )

Definition at line 1997 of file sbgl_backend_vulkan.c.

                                                                                                             {
  ctx->vk.vkCmdDraw(ctx->commandBuffers[ctx->currentFrame], vertexCount, instanceCount, firstVertex, 0);
}

sbgl_gfx_DrawIndexed()

void sbgl_gfx_DrawIndexed	(	sbgl_GfxContext *	ctx,
		uint32_t	indexCount,
		uint32_t	firstIndex,
		int32_t	vertexOffset,
		uint32_t	instanceCount )

Definition at line 2001 of file sbgl_backend_vulkan.c.

  {
  ctx->vk.vkCmdDrawIndexed(
    ctx->commandBuffers[ctx->currentFrame],
    indexCount,
    instanceCount,
    firstIndex,
    vertexOffset,
    0
  );
}

sbgl_gfx_DrawIndirect()

void sbgl_gfx_DrawIndirect	(	sbgl_GfxContext *	ctx,
		sbgl_Buffer	buffer,
		size_t	offset,
		uint32_t	drawCount )

Submits a batch of draw calls stored in a GPU buffer.

Parameters

ctx	The graphics context.
buffer	Handle to the buffer containing an array of sbgl_IndirectCommand.
offset	The byte offset into the buffer where the commands begin.
drawCount	The number of commands to execute from the buffer.

Definition at line 2018 of file sbgl_backend_vulkan.c.

  {
  if (handle == SBGL_INVALID_HANDLE)
    return;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxBuffers || !ctx->bufferActive[index])
    return;
 
  ctx->vk.vkCmdDrawIndexedIndirect(
    ctx->commandBuffers[ctx->currentFrame],
    ctx->buffers[index].handle,
    (VkDeviceSize)offset,
    drawCount,
    sizeof(sbgl_IndirectCommand)
  );
}

sbgl_gfx_EndFrame()

void sbgl_gfx_EndFrame

(

sbgl_GfxContext *

ctx

)

Submits the current frame's commands and presents the image.

Definition at line 1277 of file sbgl_backend_vulkan.c.

                                             {
  ctx->vk.vkEndCommandBuffer(ctx->commandBuffers[ctx->currentFrame]);
 
  VkPipelineStageFlags waitStages[] = { VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT };
  
  /* The system utilizes a semaphore indexed by the current image to signal completion
     to the presentation engine, preventing reuse conflicts during high-frequency updates. */
  VkSemaphore signalSemaphore = ctx->renderFinishedSemaphores[ctx->currentImageIndex];
 
  VkSubmitInfo submitInfo = {
    .sType = VK_STRUCTURE_TYPE_SUBMIT_INFO,
    .waitSemaphoreCount = 1,
    .pWaitSemaphores = &ctx->imageAvailableSemaphores[ctx->semaphoreIndex],
    .pWaitDstStageMask = waitStages,
    .commandBufferCount = 1,
    .pCommandBuffers = &ctx->commandBuffers[ctx->currentFrame],
    .signalSemaphoreCount = 1,
    .pSignalSemaphores = &signalSemaphore,
  };
  ctx->vk
    .vkQueueSubmit(ctx->graphicsQueue, 1, &submitInfo, ctx->inFlightFences[ctx->currentFrame]);
 
  VkPresentInfoKHR presentInfo = {
    .sType = VK_STRUCTURE_TYPE_PRESENT_INFO_KHR,
    .waitSemaphoreCount = 1,
    .pWaitSemaphores = &signalSemaphore,
    .swapchainCount = 1,
    .pSwapchains = &ctx->swapchain,
    .pImageIndices = &ctx->currentImageIndex,
  };
  VkResult result = ctx->vk.vkQueuePresentKHR(ctx->graphicsQueue, &presentInfo);
 
  if (result == VK_ERROR_OUT_OF_DATE_KHR || result == VK_SUBOPTIMAL_KHR) {
    recreate_swapchain(ctx);
  }
 
  ctx->semaphoreIndex = (ctx->semaphoreIndex + 1) % SBGL_MAX_SWAPCHAIN_IMAGES;
  ctx->currentFrame = (ctx->currentFrame + 1) % SBGL_MAX_FRAMES_IN_FLIGHT;
}

sbgl_gfx_EndRenderPass()

void sbgl_gfx_EndRenderPass

(

sbgl_GfxContext *

ctx

)

Ends the current graphics rendering pass.

Definition at line 1240 of file sbgl_backend_vulkan.c.

                                                  {
  /* The system records the ending timestamp at the conclusion of the frame's rendering commands.
   */
  ctx->vk.vkCmdWriteTimestamp(
    ctx->commandBuffers[ctx->currentFrame],
    VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
    ctx->queryPool,
    ctx->currentFrame * 2 + 1
  );
 
  ctx->vk.vkCmdEndRendering(ctx->commandBuffers[ctx->currentFrame]);
 
  VkImageMemoryBarrier barrier = {
    .sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER,
    .oldLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
    .newLayout = VK_IMAGE_LAYOUT_PRESENT_SRC_KHR,
    .image = ctx->images[ctx->currentImageIndex],
    .subresourceRange = { .aspectMask = VK_IMAGE_ASPECT_COLOR_BIT,
                .levelCount = 1,
                .layerCount = 1 },
    .srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT,
    .dstAccessMask = 0,
  };
  ctx->vk.vkCmdPipelineBarrier(
    ctx->commandBuffers[ctx->currentFrame],
    VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT,
    VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
    0,
    0,
    NULL,
    0,
    NULL,
    1,
    &barrier
  );
}

sbgl_gfx_FillBuffer()

void sbgl_gfx_FillBuffer	(	sbgl_GfxContext *	ctx,
		sbgl_Buffer	buffer,
		size_t	offset,
		size_t	size,
		uint32_t	value )

Performs a hardware-accelerated buffer fill.

Definition at line 1431 of file sbgl_backend_vulkan.c.

  {
  /* A hardware-accelerated fill operation is recorded into the current frame's
     command buffer, utilizing the GPU's DMA engine for maximum performance. */
  if (handle == SBGL_INVALID_HANDLE)
    return;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxBuffers || !ctx->bufferActive[index])
    return;
 
  ctx->vk.vkCmdFillBuffer(
    ctx->commandBuffers[ctx->currentFrame],
    ctx->buffers[index].handle,
    (VkDeviceSize)offset,
    (VkDeviceSize)size,
    value
  );
}

sbgl_gfx_GetBufferDeviceAddress()

uint64_t sbgl_gfx_GetBufferDeviceAddress	(	sbgl_GfxContext *	ctx,
		sbgl_Buffer	buffer )

Retrieves the 64-bit GPU virtual address for a buffer.

Used primarily for passing buffer pointers to shaders via push constants or storage buffers when using VK_KHR_buffer_device_address.

Parameters

ctx	The graphics context.
buffer	The buffer to query.

Returns

The 64-bit device address, or 0 if retrieval failed.

Definition at line 1493 of file sbgl_backend_vulkan.c.

                                                                                   {
  /* The system retrieves the 64-bit GPU virtual address for the specified buffer,
     enabling direct memory access within shaders via Buffer Device Address. */
  if (handle == SBGL_INVALID_HANDLE)
    return 0;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxBuffers || !ctx->bufferActive[index])
    return 0;
 
  VkBufferDeviceAddressInfo info = {
    .sType = VK_STRUCTURE_TYPE_BUFFER_DEVICE_ADDRESS_INFO,
    .buffer = ctx->buffers[index].handle,
  };
 
  return ctx->vk.vkGetBufferDeviceAddress(ctx->device, &info);
}

sbgl_gfx_GetFrameIndex()

uint32_t sbgl_gfx_GetFrameIndex

(

sbgl_GfxContext *

ctx

)

Retrieves the current backend frame index.

Definition at line 1455 of file sbgl_backend_vulkan.c.

                                                      {
  /* Returns the current frame index, which is used by the core engine to
     manage multi-buffered resources. */
  return ctx->currentFrame;
}

sbgl_gfx_GetGpuTime()

float sbgl_gfx_GetGpuTime

(

sbgl_GfxContext *

ctx

)

Retrieves the elapsed GPU time for the previous frame in milliseconds.

Parameters

ctx	The graphics context.

Returns

The duration in milliseconds.

Definition at line 2100 of file sbgl_backend_vulkan.c.

                                                {
  /* The system retrieves the recorded timestamps from the GPU and calculates the elapsed time
     in milliseconds, providing a non-blocking performance measurement. */
  uint64_t results[2] = { 0 };
  VkResult res = ctx->vk.vkGetQueryPoolResults(
    ctx->device,
    ctx->queryPool,
    ctx->currentFrame * 2,
    2,
    sizeof(results),
    results,
    sizeof(uint64_t),
    VK_QUERY_RESULT_64_BIT
  );
 
  if (res == VK_SUCCESS) {
    uint64_t start = results[0];
    uint64_t end = results[1];
    return (float)(end - start) * ctx->timestampPeriod / 1e6f;
  }
 
  return 0.0f;
}

sbgl_gfx_GetLastVkResult()

int32_t sbgl_gfx_GetLastVkResult

(

sbgl_GfxContext *

ctx

)

Retrieves the last VkResult from the backend for error inspection.

Parameters

ctx	The graphics context.

Returns

The last VkResult code, or 0 if no error occurred.

Definition at line 2124 of file sbgl_backend_vulkan.c.

                                                       {
  if (!ctx) return 0;
  return ctx->backendResult;
}

sbgl_gfx_Init()

sbgl_GfxContext * sbgl_gfx_Init	(	sbgl_Window *	window,
		struct SblArena *	arena,
		const sbgl_ResourceLimits *	limits,
		bool	enableValidation )

Initializes the graphics backend with configurable resource limits.

Parameters

window	The platform window handle.
arena	The arena for persistent allocations.
limits	Pointer to resource limits (must not be NULL).
enableValidation	Whether to enable Vulkan validation layers.

Returns

A pointer to the graphics context, or NULL on failure.

Definition at line 986 of file sbgl_backend_vulkan.c.

                                                                                                                                      {
  if (volkInitialize() != VK_SUCCESS) {
    fprintf(stderr, "[Vulkan] Failed to initialize volk\n");
    return NULL;
  }
 
  sbgl_GfxContext* ctx = SBL_ARENA_PUSH_STRUCT_ZERO(arena, sbgl_GfxContext);
  if (!ctx)
    return NULL;
 
  ctx->window = window;
  ctx->arena = arena;
 
  // Apply resource limits (use defaults if not provided)
  if (limits) {
    ctx->limits = *limits;
    // Enforce minimums to prevent crashes
    if (ctx->limits.maxBuffers < 64) ctx->limits.maxBuffers = 64;
    if (ctx->limits.maxShaders < 16) ctx->limits.maxShaders = 16;
    if (ctx->limits.maxPipelines < 16) ctx->limits.maxPipelines = 16;
  } else {
    ctx->limits = sbgl_DefaultResourceLimits;
  }
 
  // Dynamically allocate resource arrays from the arena
  // Use raw byte allocation since SBGL_Vulkan* types are defined later in this file
  ctx->bufferActive = (bool*)sbl_arena_alloc_zero(arena, sizeof(bool) * ctx->limits.maxBuffers);
  ctx->buffers = (SBGL_VulkanBuffer*)sbl_arena_alloc_zero(arena, sizeof(SBGL_VulkanBuffer) * ctx->limits.maxBuffers);
  ctx->shaders = (SBGL_VulkanShader*)sbl_arena_alloc_zero(arena, sizeof(SBGL_VulkanShader) * ctx->limits.maxShaders);
  ctx->pipelines = (SBGL_VulkanPipeline*)sbl_arena_alloc_zero(arena, sizeof(SBGL_VulkanPipeline) * ctx->limits.maxPipelines);
  ctx->computePipelines = (SBGL_VulkanComputePipeline*)sbl_arena_alloc_zero(arena, sizeof(SBGL_VulkanComputePipeline) * ctx->limits.maxPipelines);
 
  if (!ctx->bufferActive || !ctx->buffers || !ctx->shaders || !ctx->pipelines || !ctx->computePipelines) {
    fprintf(stderr, "[Vulkan] Failed to allocate resource arrays\n");
    sbgl_gfx_Shutdown(ctx);
    return NULL;
  }
 
  if (!create_instance(ctx, enableValidation) || !create_surface(ctx, window) || !select_physical_device(ctx) ||
    !create_logical_device(ctx) || !create_heaps(ctx) || !create_swapchain(ctx, window) ||
    !create_sync_and_command(ctx) || !create_telemetry_resources(ctx) ||
    !create_transient_resources(ctx)) {
    sbgl_gfx_Shutdown(ctx);
    return NULL;
  }
 
  /* The query pool is reset on the host immediately after creation to ensure that all 
     queries are in a valid state before the first attempt to retrieve results. */
  ctx->vk.vkResetQueryPool(ctx->device, ctx->queryPool, 0, SBGL_MAX_FRAMES_IN_FLIGHT * 2);
 
  return ctx;
}

sbgl_gfx_LoadShader()

sbgl_Shader sbgl_gfx_LoadShader	(	sbgl_GfxContext *	ctx,
		sbgl_ShaderStage	stage,
		const uint32_t *	bytecode,
		size_t	size )

Definition at line 1510 of file sbgl_backend_vulkan.c.

  {
  uint32_t index = 0;
  for (; index < ctx->limits.maxShaders; index++) {
    if (!ctx->shaders[index].active)
      break;
  }
  if (index == ctx->limits.maxShaders)
    return SBGL_INVALID_HANDLE;
 
  VkShaderModuleCreateInfo createInfo = {
    .sType = VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO,
    .codeSize = size,
    .pCode = bytecode,
  };
 
  if (ctx->vk.vkCreateShaderModule(ctx->device, &createInfo, NULL, &ctx->shaders[index].module) !=
    VK_SUCCESS) {
    return SBGL_INVALID_HANDLE;
  }
 
  ctx->shaders[index].stage = stage;
  ctx->shaders[index].active = true;
  return (sbgl_Shader)(index + 1);
}

sbgl_gfx_MapBuffer()

void * sbgl_gfx_MapBuffer	(	sbgl_GfxContext *	ctx,
		sbgl_Buffer	buffer )

Definition at line 1461 of file sbgl_backend_vulkan.c.

                                                                   {
  /* The system returns the persistently mapped pointer for the specified buffer,
     enabling high-performance data updates without the overhead of repeated mapping. */
  if (handle == SBGL_INVALID_HANDLE)
    return NULL;
  uint32_t index = (uint32_t)handle - 1;
  if (index >= ctx->limits.maxBuffers || !ctx->bufferActive[index])
    return NULL;
 
  return ctx->buffers[index].mapped;
}

sbgl_gfx_MemoryBarrier()

void sbgl_gfx_MemoryBarrier	(	sbgl_GfxContext *	ctx,
		sbgl_BarrierType	type )

Definition at line 1876 of file sbgl_backend_vulkan.c.

                                                                         {
  /* The system injects a pipeline barrier into the command stream to synchronize
     memory access between different execution stages, preventing race conditions. */
  VkMemoryBarrier barrier = { .sType = VK_STRUCTURE_TYPE_MEMORY_BARRIER };
  VkPipelineStageFlags srcStage = 0;
  VkPipelineStageFlags dstStage = 0;
 
  switch (type) {
  case SBGL_BARRIER_COMPUTE_TO_COMPUTE:
    /* Synchronizes compute and transfer (fill) writes to be visible to 
       subsequent compute operations. */
    barrier.srcAccessMask = VK_ACCESS_SHADER_WRITE_BIT | VK_ACCESS_TRANSFER_WRITE_BIT;
    barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT | VK_ACCESS_SHADER_WRITE_BIT;
    srcStage = VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT | VK_PIPELINE_STAGE_TRANSFER_BIT;
    dstStage = VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT;
    break;
  case SBGL_BARRIER_COMPUTE_TO_INDIRECT:
    /* Synchronizes compute writes to SSBOs for use in indirect draw command buffers. */
    barrier.srcAccessMask = VK_ACCESS_SHADER_WRITE_BIT;
    barrier.dstAccessMask = VK_ACCESS_INDIRECT_COMMAND_READ_BIT;
    srcStage = VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT;
    dstStage = VK_PIPELINE_STAGE_DRAW_INDIRECT_BIT;
    break;
  case SBGL_BARRIER_COMPUTE_TO_GRAPHICS:
    /* Synchronizes compute writes to be visible to vertex input and shader stages. */
    barrier.srcAccessMask = VK_ACCESS_SHADER_WRITE_BIT;
    barrier.dstAccessMask = VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT | VK_ACCESS_SHADER_READ_BIT;
    srcStage = VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT;
    dstStage = VK_PIPELINE_STAGE_VERTEX_INPUT_BIT | VK_PIPELINE_STAGE_VERTEX_SHADER_BIT;
    break;
  case SBGL_BARRIER_GRAPHICS_TO_COMPUTE:
    /* Synchronizes graphics writes to be visible to subsequent compute operations. */
    barrier.srcAccessMask = VK_ACCESS_SHADER_WRITE_BIT;
    barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT | VK_ACCESS_SHADER_WRITE_BIT;
    srcStage = VK_PIPELINE_STAGE_VERTEX_SHADER_BIT | VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
    dstStage = VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT;
    break;
  case SBGL_BARRIER_HOST_TO_COMPUTE:
    /* Synchronizes host writes to be visible to subsequent compute operations. */
    barrier.srcAccessMask = VK_ACCESS_HOST_WRITE_BIT;
    barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT | VK_ACCESS_SHADER_WRITE_BIT;
    srcStage = VK_PIPELINE_STAGE_HOST_BIT;
    dstStage = VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT;
    break;
  case SBGL_BARRIER_HOST_TO_GRAPHICS:
    /* Synchronizes host writes to be visible to subsequent graphics (vertex) operations. */
    barrier.srcAccessMask = VK_ACCESS_HOST_WRITE_BIT;
    barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT;
    srcStage = VK_PIPELINE_STAGE_HOST_BIT;
    dstStage = VK_PIPELINE_STAGE_VERTEX_SHADER_BIT;
    break;
  }
 
  ctx->vk.vkCmdPipelineBarrier(
    ctx->commandBuffers[ctx->currentFrame],
    srcStage,
    dstStage,
    0,
    1,
    &barrier,
    0,
    NULL,
    0,
    NULL
  );
}

sbgl_gfx_PushConstants()

void sbgl_gfx_PushConstants	(	sbgl_GfxContext *	ctx,
		size_t	size,
		const void *	data )

Definition at line 2067 of file sbgl_backend_vulkan.c.

                                                                                 {
  /* Push constants are submitted to both the currently bound graphics and compute
     pipelines to ensure that metadata is available across all execution stages. */
  if (size > SBGL_VK_PUSH_CONSTANT_SIZE) {
    fprintf(stderr, "[Vulkan] Push constant size (%zu) exceeds maximum (%d)\n", size, SBGL_VK_PUSH_CONSTANT_SIZE);
    return;
  }
 
  if (ctx->boundPipeline != SBGL_INVALID_HANDLE) {
    uint32_t index = (uint32_t)ctx->boundPipeline - 1;
    ctx->vk.vkCmdPushConstants(
      ctx->commandBuffers[ctx->currentFrame],
      ctx->pipelines[index].layout,
      VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT,
      0,
      (uint32_t)size,
      data
    );
  }
 
  if (ctx->boundComputePipeline != SBGL_INVALID_HANDLE) {
    uint32_t index = (uint32_t)ctx->boundComputePipeline - 1;
    ctx->vk.vkCmdPushConstants(
      ctx->commandBuffers[ctx->currentFrame],
      ctx->computePipelines[index].layout,
      VK_SHADER_STAGE_COMPUTE_BIT,
      0,
      (uint32_t)size,
      data
    );
  }
}

sbgl_gfx_Shutdown()

void sbgl_gfx_Shutdown

(

sbgl_GfxContext *

ctx

)

Definition at line 1039 of file sbgl_backend_vulkan.c.

                                             {
  if (!ctx)
    return;
 
  if (ctx->device) {
    ctx->vk.vkDeviceWaitIdle(ctx->device);
 
    // Clean up all active buffers
    for (uint32_t i = 0; i < ctx->limits.maxBuffers; i++) {
      if (ctx->bufferActive[i]) {
        sbgl_gfx_DestroyBuffer(ctx, (sbgl_Buffer)(i + 1));
      }
    }
 
    // Clean up all active shaders
    for (uint32_t i = 0; i < ctx->limits.maxShaders; i++) {
      if (ctx->shaders[i].active) {
        sbgl_gfx_DestroyShader(ctx, (sbgl_Shader)(i + 1));
      }
    }
 
    // Clean up all active pipelines
    for (uint32_t i = 0; i < ctx->limits.maxPipelines; i++) {
      if (ctx->pipelines[i].active) {
        sbgl_gfx_DestroyPipeline(ctx, (sbgl_Pipeline)(i + 1));
      }
      if (ctx->computePipelines[i].active) {
        sbgl_gfx_DestroyComputePipeline(ctx, (sbgl_ComputePipeline)(i + 1));
      }
    }
 
    // Process any remaining deferred buffers
    for (uint32_t f = 0; f < SBGL_MAX_FRAMES_IN_FLIGHT; f++) {
      for (uint32_t i = 0; i < ctx->deferredCount[f]; i++) {
        sbgl_gfx_DestroyBuffer(ctx, ctx->deferredBuffers[f][i]);
      }
      ctx->deferredCount[f] = 0;
    }
 
    for (uint32_t i = 0; i < SBGL_MAX_FRAMES_IN_FLIGHT; i++) {
      ctx->vk.vkDestroyFence(ctx->device, ctx->inFlightFences[i], NULL);
    }
 
    for (uint32_t i = 0; i < SBGL_MAX_SWAPCHAIN_IMAGES; i++) {
      if (ctx->imageAvailableSemaphores[i] != VK_NULL_HANDLE) {
        ctx->vk.vkDestroySemaphore(ctx->device, ctx->imageAvailableSemaphores[i], NULL);
      }
      if (ctx->renderFinishedSemaphores[i] != VK_NULL_HANDLE) {
        ctx->vk.vkDestroySemaphore(ctx->device, ctx->renderFinishedSemaphores[i], NULL);
      }
    }
    ctx->vk.vkDestroyQueryPool(ctx->device, ctx->queryPool, NULL);
    ctx->vk.vkDestroyCommandPool(ctx->device, ctx->commandPool, NULL);
 
    ctx->vk.vkFreeMemory(ctx->device, ctx->staticHeap.memory, NULL);
    ctx->vk.vkFreeMemory(ctx->device, ctx->dynamicHeap.memory, NULL);
    ctx->vk.vkFreeMemory(ctx->device, ctx->managedHeap.memory, NULL);
 
    cleanup_swapchain(ctx);
    ctx->vk.vkDestroyDevice(ctx->device, NULL);
  }
  if (ctx->instance) {
    vkDestroySurfaceKHR(ctx->instance, ctx->surface, NULL);
    vkDestroyInstance(ctx->instance, NULL);
  }
}

sbgl_gfx_UnmapBuffer()

void sbgl_gfx_UnmapBuffer	(	sbgl_GfxContext *	ctx,
		sbgl_Buffer	buffer )

Definition at line 1473 of file sbgl_backend_vulkan.c.

                                                                    {
  /* Persistent mapping remains active for the buffer's lifecycle, so unmapping
     is a no-op to maintain API compatibility while maximizing performance. */
  (void)ctx;
  (void)handle;
}