sbgl_core.c File Reference

#include "sbgl.h"
#include "sbgl_types.h"
#include "core/sbl_arena.h"
#include "backend/sbgl_graphics_hal.h"
#include "core/sbgl_batcher.h"
#include "core/sbgl_context_internal.h"
#include "core/sbgl_internal_log.h"
#include "core/sbgl_platform.h"
#include "core/sbgl_sort.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>

Include dependency graph for sbgl_core.c:

Go to the source code of this file.

Data Structures
struct	sbgl_RenderQueue
	Internal storage for draw packets awaiting submission. More...
struct	sbgl_InternalContext
	Internal state for the engine context. More...

Macros
#define	SBL_ARENA_IMPLEMENTATION

Functions
SblArena *	sbgl_GetContextArena (sbgl_Context *ctx)
	Retrieves the persistent arena associated with a context.
sbgl_Result	sbgl_GetResult (sbgl_Context *ctx)
	Retrieves the last result code from the context.
sbgl_ErrorDetail	sbgl_GetErrorDetail (sbgl_Context *ctx)
	Retrieves detailed error information including backend-specific codes.
void	sbgl_ClearResult (sbgl_Context *ctx)
	Clears the result code to SBGL_SUCCESS.
sbgl_InitResult	sbgl_InitWithConfig (const sbgl_InitConfig *config)
	Initializes the engine and opens a window with explicit configuration.
sbgl_InitResult	sbgl_Init (int w, int h, const char *title)
	Initializes the engine and opens a window.
void	sbgl_Shutdown (sbgl_Context *ctx)
	Gracefully shuts down the engine and releases all resources.
bool	sbgl_WindowShouldClose (sbgl_Context *ctx)
	Checks if the user or OS has requested to close the window.
double	sbgl_GetTime (sbgl_Context *ctx)
	Retrieves the current monotonic system time in seconds.
void	sbgl_GetWindowSize (sbgl_Context *ctx, int *w, int *h)
	Retrieves the current window dimensions.
void	sbgl_BeginDrawing (sbgl_Context *ctx)
	Prepares the engine for a new frame of drawing.
void	sbgl_EndDrawing (sbgl_Context *ctx)
	Finalizes the current frame and presents it to the screen.
void	sbgl_BeginCompute (sbgl_Context *ctx)
	Prepares the engine for compute operations before the main drawing pass.
void	sbgl_EndCompute (sbgl_Context *ctx)
	Finalizes the compute phase.
void	sbgl_DeviceWaitIdle (sbgl_Context *ctx)
	Synchronizes the CPU with the GPU, waiting for all commands to complete.
void	sbgl_SetClearColor (sbgl_Context *ctx, float r, float g, float b, float a)
	Sets the clear color for the next frame.
const sbgl_InputState *	sbgl_GetInputState (sbgl_Context *ctx)
	Retrieves the input state for the current frame.
void	sbgl_SetMouseMode (sbgl_Context *ctx, sbgl_MouseMode mode)
	Sets the cursor behavior and visibility.
sbgl_Telemetry	sbgl_GetTelemetry (sbgl_Context *ctx)
	Retrieves the performance telemetry data for the previous frame.
sbgl_Buffer	sbgl_CreateBuffer (sbgl_Context *ctx, sbgl_BufferUsage usage, size_t size, const void *data)
	Creates a GPU buffer.
void	sbgl_DestroyBuffer (sbgl_Context *ctx, sbgl_Buffer buffer)
	Destroys a GPU buffer.
void	sbgl_FillBuffer (sbgl_Context *ctx, sbgl_Buffer buffer, size_t offset, size_t size, uint32_t value)
	Fills a region of a GPU buffer with a fixed 32-bit value.
uint32_t	sbgl_GetFrameIndex (sbgl_Context *ctx)
	Retrieves the current frame index for double/triple buffering.
void *	sbgl_MapBuffer (sbgl_Context *ctx, sbgl_Buffer buffer)
	Maps a GPU buffer into the CPU's address space.
void	sbgl_UnmapBuffer (sbgl_Context *ctx, sbgl_Buffer buffer)
	Unmaps a previously mapped GPU buffer.
sbgl_Shader	sbgl_LoadShader (sbgl_Context *ctx, sbgl_ShaderStage stage, const uint32_t *bytecode, size_t size)
	Loads a shader from SPIR-V bytecode.
sbgl_Shader	sbgl_LoadShaderFromFile (sbgl_Context *ctx, sbgl_ShaderStage stage, const char *filename)
	Helper function to load a shader directly from a SPIR-V file.
void	sbgl_DestroyShader (sbgl_Context *ctx, sbgl_Shader shader)
	Destroys a shader module.
sbgl_Pipeline	sbgl_CreatePipeline (sbgl_Context *ctx, const sbgl_PipelineConfig *config)
	Creates a graphics pipeline.
void	sbgl_DestroyPipeline (sbgl_Context *ctx, sbgl_Pipeline pipeline)
	Destroys a graphics pipeline.
sbgl_ComputePipeline	sbgl_CreateComputePipeline (sbgl_Context *ctx, sbgl_Shader shader)
	Creates a compute pipeline.
void	sbgl_DestroyComputePipeline (sbgl_Context *ctx, sbgl_ComputePipeline pipeline)
	Destroys a compute pipeline.
void	sbgl_BindComputePipeline (sbgl_Context *ctx, sbgl_ComputePipeline pipeline)
	Binds a compute pipeline for subsequent dispatch calls.
void	sbgl_DispatchCompute (sbgl_Context *ctx, uint32_t x, uint32_t y, uint32_t z)
	Dispatches a compute workload.
void	sbgl_MemoryBarrier (sbgl_Context *ctx, sbgl_BarrierType type)
	Injects a memory barrier to synchronize compute and graphics operations.
void	sbgl_BindPipeline (sbgl_Context *ctx, sbgl_Pipeline pipeline)
	Binds a graphics pipeline for subsequent draw calls.
void	sbgl_BindBuffer (sbgl_Context *ctx, sbgl_Buffer buffer, sbgl_BufferUsage usage)
	Binds a buffer to the pipeline.
uint64_t	sbgl_GetBufferDeviceAddress (sbgl_Context *ctx, sbgl_Buffer buffer)
	Retrieves the 64-bit GPU virtual address for a buffer.
void	sbgl_Draw (sbgl_Context *ctx, uint32_t vertexCount, uint32_t firstVertex, uint32_t instanceCount)
	Submits a non-indexed draw command.
void	sbgl_DrawIndexed (sbgl_Context *ctx, uint32_t indexCount, uint32_t firstIndex, int32_t vertexOffset, uint32_t instanceCount)
	Submits an indexed draw command.
void	sbgl_DrawIndirect (sbgl_Context *ctx, sbgl_Buffer buffer, size_t offset, uint32_t drawCount)
	Submits a batch of draw calls stored in a GPU buffer.
void	sbgl_PushConstants (sbgl_Context *ctx, size_t size, const void *data)
	Updates push constants for the currently bound pipeline.
sbgl_RenderQueue *	sbgl_CreateRenderQueue (sbgl_Context *ctx, SblArena *arena)
	Creates a thread-local render queue for collecting draw commands.
void	sbgl_SubmitDraw (sbgl_RenderQueue *queue, uint32_t mesh, uint32_t material, uint32_t blendMode, uint32_t sidedness, uint32_t tags, sbgl_SortKey key, const sbgl_InstanceData *data)
	Appends a draw command to the render queue.
void	sbgl_RenderQueues (sbgl_Context *ctx, sbgl_RenderQueue **queues, uint32_t queueCount, const sbgl_Mat4 *viewProj)
	Merges, sorts, and submits pending draw commands to the GPU.
void	sbgl_RenderQueuesEx (sbgl_Context *ctx, sbgl_RenderQueue **queues, uint32_t queueCount, const sbgl_Mat4 *viewProj, uint64_t userAddress)
	Extended version of sbgl_RenderQueues with user metadata.

Macro Definition Documentation

SBL_ARENA_IMPLEMENTATION

#define SBL_ARENA_IMPLEMENTATION

Definition at line 4 of file sbgl_core.c.

Function Documentation

sbgl_BeginCompute()

void sbgl_BeginCompute

(

sbgl_Context *

ctx

)

Prepares the engine for compute operations before the main drawing pass.

If a frame has not yet been started, this function initiates the frame lifecycle, acquiring a swapchain image and starting the command buffer. It must be called outside of a BeginDrawing/EndDrawing block.

Parameters

ctx	The engine context.

Definition at line 344 of file sbgl_core.c.

                                          {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    // Reset graphics handle to prevent cross-phase push constant delivery
    sbgl_gfx_BindPipeline(inner->gfx, SBGL_INVALID_HANDLE);
 
    /* If a frame has not yet been initiated, the system handles event polling,
       focus management, and starts the GPU command stream. */
    if (!inner->state.hasStartedFrame) {
        sbgl_os_PollEvents(inner->window);
 
        bool currentlyFocused = sbgl_os_IsWindowFocused(inner->window);
        if (currentlyFocused && !inner->state.wasFocused) {
            if (inner->mouseMode == SBGL_MOUSE_MODE_CAPTURED) {
                sbgl_os_SetCursorVisible(inner->window, false);
                sbgl_os_SetCursorLocked(inner->window, true);
            }
        }
        inner->state.wasFocused = currentlyFocused;
 
        inner->frameStartTicks = sbgl_os_GetPerfCount(inner->window);
 
        inner->currentFrame.draw_calls = 0;
        inner->currentFrame.instance_count = 0;
        inner->currentFrame.cpu_sort_time = 0.0f;
 
        if (sbgl_gfx_BeginFrame(inner->gfx)) {
            inner->state.hasStartedFrame = 1;
            if (inner->frameCount > 2) {
                inner->currentFrame.gpu_render_time = sbgl_gfx_GetGpuTime(inner->gfx);
            }
        } else {
            ctx->result = SBGL_ERROR_GRAPHICS_FAILED;
            return;
        }
    }
    ctx->result = SBGL_SUCCESS;
}

sbgl_BeginDrawing()

void sbgl_BeginDrawing

(

sbgl_Context *

ctx

)

Prepares the engine for a new frame of drawing.

This function handles event polling and Vulkan swapchain image acquisition. It is called before clearing or drawing commands.

Parameters

ctx	The engine context.

Definition at line 262 of file sbgl_core.c.

                                          {
    if (!ctx || !ctx->inner) return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    // Reset compute handle to prevent cross-phase push constant delivery
    sbgl_gfx_BindComputePipeline(inner->gfx, SBGL_INVALID_HANDLE);
 
    if (!inner->state.hasStartedFrame) {
        sbgl_os_PollEvents(inner->window);
 
        // Detect focus transitions to re-apply mouse locking if necessary.
        bool currentlyFocused = sbgl_os_IsWindowFocused(inner->window);
        if (currentlyFocused && !inner->state.wasFocused) {
            if (inner->mouseMode == SBGL_MOUSE_MODE_CAPTURED) {
                sbgl_os_SetCursorVisible(inner->window, false);
                sbgl_os_SetCursorLocked(inner->window, true);
            }
        }
        inner->state.wasFocused = currentlyFocused;
 
        inner->frameStartTicks = sbgl_os_GetPerfCount(inner->window);
 
        // Performance counters are reset at the start of every frame
        inner->currentFrame.draw_calls = 0;
        inner->currentFrame.instance_count = 0;
        inner->currentFrame.cpu_sort_time = 0.0f;
 
        if (sbgl_gfx_BeginFrame(inner->gfx)) {
            inner->state.hasStartedFrame = 1;
            
            /* GPU performance data for the previous frame in this slot is now guaranteed 
               to be ready. Telemetry is skipped for the very first frames to allow 
               the pipeline to prime and avoid uninitialized query errors. */
            if (inner->frameCount > 2) {
                inner->currentFrame.gpu_render_time = sbgl_gfx_GetGpuTime(inner->gfx);
            }
        } else {
            ctx->result = SBGL_ERROR_GRAPHICS_FAILED;
            return;
        }
    }
 
    sbgl_gfx_BeginRenderPass(
        inner->gfx,
        inner->clearColor[0],
        inner->clearColor[1],
        inner->clearColor[2],
        inner->clearColor[3]
    );
    inner->state.isDrawing = 1;
    ctx->result = SBGL_SUCCESS;
}

sbgl_BindBuffer()

void sbgl_BindBuffer	(	sbgl_Context *	ctx,
		sbgl_Buffer	buffer,
		sbgl_BufferUsage	usage )

Binds a buffer to the pipeline.

Parameters

ctx	The engine context.
buffer	The buffer handle.
usage	The usage to bind it as (Vertex/Index).

Definition at line 681 of file sbgl_core.c.

                                                                                    {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_BindBuffer(inner->gfx, buffer, usage);
    ctx->result = SBGL_SUCCESS;
}

sbgl_BindComputePipeline()

void sbgl_BindComputePipeline	(	sbgl_Context *	ctx,
		sbgl_ComputePipeline	pipeline )

Binds a compute pipeline for subsequent dispatch calls.

Parameters

ctx	The engine context.
pipeline	The compute pipeline handle.

Definition at line 649 of file sbgl_core.c.

                                                                                {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_BindComputePipeline(inner->gfx, pipeline);
    ctx->result = SBGL_SUCCESS;
}

sbgl_BindPipeline()

void sbgl_BindPipeline	(	sbgl_Context *	ctx,
		sbgl_Pipeline	pipeline )

Binds a graphics pipeline for subsequent draw calls.

Parameters

ctx	The engine context.
pipeline	The pipeline handle.

Definition at line 673 of file sbgl_core.c.

                                                                  {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_BindPipeline(inner->gfx, pipeline);
    ctx->result = SBGL_SUCCESS;
}

sbgl_ClearResult()

void sbgl_ClearResult

(

sbgl_Context *

ctx

)

Clears the result code to SBGL_SUCCESS.

Parameters

ctx	The engine context (may be NULL).

Definition at line 103 of file sbgl_core.c.

                                         {
  if (!ctx) {
    return;
  }
  ctx->result = SBGL_SUCCESS;
}

sbgl_CreateBuffer()

sbgl_Buffer sbgl_CreateBuffer	(	sbgl_Context *	ctx,
		sbgl_BufferUsage	usage,
		size_t	size,
		const void *	data )

Creates a GPU buffer.

Parameters

ctx	The engine context.
usage	Intended usage of the buffer (Vertex/Index).
size	Size in bytes.
data	Optional initial data. If NULL, the buffer is created empty.

Returns

A handle to the created buffer.

Definition at line 445 of file sbgl_core.c.

                                                                                            {
    if (!ctx || !ctx->inner)
        return SBGL_INVALID_HANDLE;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_Buffer res = sbgl_gfx_CreateBuffer(inner->gfx, usage, size, data);
 
    ctx->result =
        (res != SBGL_INVALID_HANDLE) ? SBGL_SUCCESS : SBGL_ERROR_GRAPHICS_FAILED;
    return res;
}

sbgl_CreateComputePipeline()

sbgl_ComputePipeline sbgl_CreateComputePipeline	(	sbgl_Context *	ctx,
		sbgl_Shader	shader )

Creates a compute pipeline.

Parameters

ctx	The engine context.
shader	The compute shader handle.

Returns

A handle to the created compute pipeline.

Definition at line 619 of file sbgl_core.c.

                                                                                       {
    if (!ctx || !ctx->inner)
        return SBGL_INVALID_HANDLE;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_ComputePipeline res = sbgl_gfx_CreateComputePipeline(inner->gfx, shader);
    ctx->result =
        (res != SBGL_INVALID_HANDLE) ? SBGL_SUCCESS : SBGL_ERROR_GRAPHICS_FAILED;
    return res;
}

sbgl_CreatePipeline()

sbgl_Pipeline sbgl_CreatePipeline	(	sbgl_Context *	ctx,
		const sbgl_PipelineConfig *	config )

Creates a graphics pipeline.

Parameters

ctx	The engine context.
config	Configuration for the pipeline.

Returns

A handle to the created pipeline.

Definition at line 587 of file sbgl_core.c.

                                                                                        {
    if (!ctx || !ctx->inner)
        return SBGL_INVALID_HANDLE;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_Pipeline res = sbgl_gfx_CreatePipeline(inner->gfx, config);
    ctx->result =
        (res != SBGL_INVALID_HANDLE) ? SBGL_SUCCESS : SBGL_ERROR_GRAPHICS_FAILED;
    return res;
}

sbgl_CreateRenderQueue()

sbgl_RenderQueue * sbgl_CreateRenderQueue	(	sbgl_Context *	ctx,
		struct SblArena *	arena )

Creates a thread-local render queue for collecting draw commands.

Draw packets are stored in this queue and submitted to the backend for rendering. Multiple queues enable parallel command recording.

Parameters

ctx	The engine context.
arena	The arena to use for queue allocations.

Returns

A pointer to the newly created render queue.

Definition at line 743 of file sbgl_core.c.

                                                                             {
    if (!ctx || !arena) {
        return NULL;
    }
 
    // Allocate the queue structure from the provided arena
    sbgl_RenderQueue* queue = SBL_ARENA_PUSH_STRUCT_ZERO(arena, sbgl_RenderQueue);
    if (!queue) {
        ctx->result = SBGL_ERROR_OUT_OF_MEMORY;
        return NULL;
    }
 
    // Initialize the queue with a default capacity of 16,384 packets
    /* Initialize the queue with a high capacity to support massive batching (e.g., voxels). */
    queue->capacity = 131072;
    queue->count = 0;
    queue->arena = arena;
    queue->packets = SBL_ARENA_PUSH_ARRAY_ZERO(arena, sbgl_DrawPacket, queue->capacity);
    queue->instances = SBL_ARENA_PUSH_ARRAY_ZERO(arena, sbgl_InstanceData, queue->capacity);
 
    if (!queue->packets || !queue->instances) {
        ctx->result = SBGL_ERROR_OUT_OF_MEMORY;
        return NULL;
    }
 
    ctx->result = SBGL_SUCCESS;
    return queue;
}

sbgl_DestroyBuffer()

void sbgl_DestroyBuffer	(	sbgl_Context *	ctx,
		sbgl_Buffer	buffer )

Destroys a GPU buffer.

All submitted GPU commands referencing this buffer must have completed before calling this. Use sbgl_DeviceWaitIdle() to synchronize.

Parameters

ctx	The engine context.
buffer	The buffer handle.

Definition at line 457 of file sbgl_core.c.

                                                               {
    if (!ctx || !ctx->inner)
        return;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    if (!inner->state.isIdle) {
        sbgl_log_impl(
            SBGL_LOG_WARN,
            SBGL_LOG_CAT_GFX,
            "Buffer destroyed while GPU is busy! Missing sbgl_DeviceWaitIdle."
        );
 
        ctx->result = SBGL_ERROR_DEVICE_BUSY;
 
        // Force a wait to safely destroy it anyway and prevent driver crash
        sbgl_DeviceWaitIdle(ctx);
    }
 
    sbgl_gfx_DestroyBuffer(inner->gfx, buffer);
    ctx->result = SBGL_SUCCESS;
}

sbgl_DestroyComputePipeline()

void sbgl_DestroyComputePipeline	(	sbgl_Context *	ctx,
		sbgl_ComputePipeline	pipeline )

Destroys a compute pipeline.

Parameters

ctx	The engine context.
pipeline	The compute pipeline handle.

Definition at line 629 of file sbgl_core.c.

                                                                                   {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    if (!inner->state.isIdle) {
        sbgl_log_impl(
            SBGL_LOG_ERROR,
            SBGL_LOG_CAT_GFX,
            "Destroy Compute Pipeline called while GPU is busy! Missing sbgl_DeviceWaitIdle."
        );
 
        ctx->result = SBGL_ERROR_DEVICE_BUSY;
        sbgl_DeviceWaitIdle(ctx);
    }
 
    sbgl_gfx_DestroyComputePipeline(inner->gfx, pipeline);
    ctx->result = SBGL_SUCCESS;
}

sbgl_DestroyPipeline()

void sbgl_DestroyPipeline	(	sbgl_Context *	ctx,
		sbgl_Pipeline	pipeline )

Destroys a graphics pipeline.

The pipeline must not be in use by any submitted command buffers. Use sbgl_DeviceWaitIdle() to ensure safe destruction.

Parameters

ctx	The engine context.
pipeline	The pipeline handle.

Definition at line 597 of file sbgl_core.c.

                                                                     {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    if (!inner->state.isIdle) {
        sbgl_log_impl(
            SBGL_LOG_ERROR,
            SBGL_LOG_CAT_GFX,
            "Destroy Pipeline called while GPU is busy! Missing sbgl_DeviceWaitIdle."
        );
 
        ctx->result = SBGL_ERROR_DEVICE_BUSY;
 
        // Force a wait to safely destroy it anyway and prevent driver crash
        sbgl_DeviceWaitIdle(ctx);
    }
 
    sbgl_gfx_DestroyPipeline(inner->gfx, pipeline);
    ctx->result = SBGL_SUCCESS;
}

sbgl_DestroyShader()

void sbgl_DestroyShader	(	sbgl_Context *	ctx,
		sbgl_Shader	shader )

Destroys a shader module.

Shaders must not be in use by the GPU. Use sbgl_DeviceWaitIdle() before destruction during shutdown.

Parameters

ctx	The engine context.
shader	The shader handle.

Definition at line 565 of file sbgl_core.c.

                                                               {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    if (!inner->state.isIdle) {
        sbgl_log_impl(
            SBGL_LOG_ERROR,
            SBGL_LOG_CAT_GFX,
            "Destroy Shader called while GPU is busy! Missing sbgl_DeviceWaitIdle."
        );
 
        ctx->result = SBGL_ERROR_DEVICE_BUSY;
 
        // Force a wait to safely destroy it anyway and prevent driver crash
        sbgl_DeviceWaitIdle(ctx);
    }
 
    sbgl_gfx_DestroyShader(inner->gfx, shader);
    ctx->result = SBGL_SUCCESS;
}

sbgl_DeviceWaitIdle()

void sbgl_DeviceWaitIdle

(

sbgl_Context *

ctx

)

Synchronizes the CPU with the GPU, waiting for all commands to complete.

This is called before destroying resources (Pipelines, Buffers, Shaders) to ensure they are no longer in use by the GPU. Failure to do so results in Vulkan validation errors and instability.

Parameters

ctx	The engine context.

Definition at line 391 of file sbgl_core.c.

                                            {
    if (!ctx || !ctx->inner)
        return;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_DeviceWaitIdle(inner->gfx);
    inner->state.isIdle = 1;
    ctx->result = SBGL_SUCCESS;
}

sbgl_DispatchCompute()

void sbgl_DispatchCompute	(	sbgl_Context *	ctx,
		uint32_t	groupCountX,
		uint32_t	groupCountY,
		uint32_t	groupCountZ )

Dispatches a compute workload.

Parameters

ctx	The engine context.
groupCountX	Number of workgroups in X dimension.
groupCountY	Number of workgroups in Y dimension.
groupCountZ	Number of workgroups in Z dimension.

Definition at line 657 of file sbgl_core.c.

                                                                                 {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_DispatchCompute(inner->gfx, x, y, z);
    ctx->result = SBGL_SUCCESS;
}

sbgl_Draw()

void sbgl_Draw	(	sbgl_Context *	ctx,
		uint32_t	vertexCount,
		uint32_t	firstVertex,
		uint32_t	instanceCount )

Submits a non-indexed draw command.

Parameters

ctx	The engine context.
vertexCount	Number of vertices to draw.
firstVertex	Offset to the first vertex.
instanceCount	Number of instances to draw.

Definition at line 698 of file sbgl_core.c.

                                                                                                      {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_Draw(inner->gfx, vertexCount, firstVertex, instanceCount);
    ctx->result = SBGL_SUCCESS;
}

sbgl_DrawIndexed()

void sbgl_DrawIndexed	(	sbgl_Context *	ctx,
		uint32_t	indexCount,
		uint32_t	firstIndex,
		int32_t	vertexOffset,
		uint32_t	instanceCount )

Submits an indexed draw command.

Parameters

ctx	The engine context.
indexCount	Number of indices to draw.
firstIndex	Offset to the first index.
vertexOffset	Value added to each index before indexing into vertex buffers.
instanceCount	Number of instances to draw.

Definition at line 706 of file sbgl_core.c.

  {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_DrawIndexed(inner->gfx, indexCount, firstIndex, vertexOffset, instanceCount);
    ctx->result = SBGL_SUCCESS;
}

sbgl_DrawIndirect()

void sbgl_DrawIndirect	(	sbgl_Context *	ctx,
		sbgl_Buffer	buffer,
		size_t	offset,
		uint32_t	drawCount )

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

Parameters

ctx	The engine 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 720 of file sbgl_core.c.

  {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_DrawIndirect(inner->gfx, buffer, offset, drawCount);
    ctx->result = SBGL_SUCCESS;
}

sbgl_EndCompute()

void sbgl_EndCompute

(

sbgl_Context *

ctx

)

Finalizes the compute phase.

This function is semantically symmetrical to sbgl_BeginCompute. It does not submit the frame; that is still handled by sbgl_EndDrawing.

Parameters

ctx	The engine context.

Definition at line 385 of file sbgl_core.c.

                                        {
    /* The compute phase finalize is currently a no-op at the core level,
       as command buffer submission is deferred until the main frame end. */
    (void)ctx;
}

sbgl_EndDrawing()

void sbgl_EndDrawing

(

sbgl_Context *

ctx

)

Finalizes the current frame and presents it to the screen.

This function submits the recorded GPU commands and swaps the buffer.

Parameters

ctx	The engine context.

Definition at line 315 of file sbgl_core.c.

                                        {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    if (inner->state.isDrawing) {
        sbgl_gfx_EndRenderPass(inner->gfx);
        inner->state.isDrawing = 0;
    }
 
    if (inner->state.hasStartedFrame) {
        sbgl_gfx_EndFrame(inner->gfx);
        inner->state.hasStartedFrame = 0;
        inner->state.isIdle = 0;
        inner->frameCount++;
 
        uint64_t frameEndTicks = sbgl_os_GetPerfCount(inner->window);
        inner->currentFrame.cpu_frame_time =
            (float)((double)(frameEndTicks - inner->frameStartTicks) * 1000.0 / (double)sbgl_os_GetPerfFreq(inner->window));
 
        // The completed telemetry data is archived for user retrieval
        inner->lastFrame = inner->currentFrame;
    }
 
    // Reset pressed states for next frame
    memset(inner->input.keysPressed, 0, sizeof(inner->input.keysPressed));
    ctx->result = SBGL_SUCCESS;
}

sbgl_FillBuffer()

void sbgl_FillBuffer	(	sbgl_Context *	ctx,
		sbgl_Buffer	buffer,
		size_t	offset,
		size_t	size,
		uint32_t	value )

Fills a region of a GPU buffer with a fixed 32-bit value.

This operation is performed on the GPU and is highly efficient for clearing counters or initializing large memory regions.

Parameters

ctx	The engine context.
buffer	The buffer handle.
offset	Byte offset into the buffer.
size	Number of bytes to fill. Must be a multiple of 4.
value	The 32-bit value to fill with.

Definition at line 480 of file sbgl_core.c.

                                                                                                        {
    if (!ctx || !ctx->inner)
        return;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_FillBuffer(inner->gfx, buffer, offset, size, value);
    ctx->result = SBGL_SUCCESS;
}

sbgl_GetBufferDeviceAddress()

uint64_t sbgl_GetBufferDeviceAddress	(	sbgl_Context *	ctx,
		sbgl_Buffer	buffer )

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

This address is used for Buffer Device Address (BDA) lookups in shaders.

Parameters

ctx	The engine context.
buffer	The buffer handle.

Returns

The 64-bit GPU address, or 0 on failure.

Definition at line 689 of file sbgl_core.c.

                                                                            {
    if (!ctx || !ctx->inner)
        return 0;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    uint64_t addr = sbgl_gfx_GetBufferDeviceAddress(inner->gfx, buffer);
    ctx->result = (addr != 0) ? SBGL_SUCCESS : SBGL_ERROR_GRAPHICS_FAILED;
    return addr;
}

sbgl_GetContextArena()

SblArena * sbgl_GetContextArena

(

sbgl_Context *

ctx

)

Retrieves the persistent arena associated with a context.

Subsystems that need a lifetime-bound allocation region (e.g., the voxel engine) use this arena instead of malloc to remain consistent with the library's memory model.

Parameters

ctx	The engine context.

Returns

Pointer to the context's persistent arena, or NULL if the context is invalid.

Definition at line 62 of file sbgl_core.c.

                                                  {
  if (!ctx || !ctx->inner)
    return NULL;
  sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
  return &inner->arena;
}

sbgl_GetErrorDetail()

sbgl_ErrorDetail sbgl_GetErrorDetail

(

sbgl_Context *

ctx

)

Retrieves detailed error information including backend-specific codes.

Parameters

ctx	The engine context (may be NULL).

Returns

Detailed error structure.

Definition at line 78 of file sbgl_core.c.

                                                        {
  sbgl_ErrorDetail detail = {
    .type = SBGL_BACKEND_VULKAN,
    .coreResult = SBGL_SUCCESS,
    .vkResult = 0,
    .extension = 0,
  };
 
  if (!ctx) {
    detail.coreResult = SBGL_ERROR_NULL_CONTEXT;
    return detail;
  }
 
  detail.coreResult = ctx->result;
 
  if (ctx->inner) {
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    if (inner->gfx) {
      detail.vkResult = sbgl_gfx_GetLastVkResult(inner->gfx);
    }
  }
 
  return detail;
}

sbgl_GetFrameIndex()

uint32_t sbgl_GetFrameIndex

(

sbgl_Context *

ctx

)

Retrieves the current frame index for double/triple buffering.

Parameters

ctx	The engine context.

Returns

The current frame index (typically 0 or 1).

Definition at line 489 of file sbgl_core.c.

                                               {
    if (!ctx || !ctx->inner)
        return 0;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    return sbgl_gfx_GetFrameIndex(inner->gfx);
}

sbgl_GetInputState()

const sbgl_InputState * sbgl_GetInputState

(

sbgl_Context *

ctx

)

Retrieves the input state for the current frame.

Adheres to Data-Oriented Design by providing a read-only view of input arrays (keys, mouse) for batch processing.

Parameters

ctx	The engine context.

Returns

A read-only pointer to the current input state. Never returns NULL.

Definition at line 413 of file sbgl_core.c.

                                                             {
    static const sbgl_InputState dummy = { 0 };
    if (!ctx || !ctx->inner)
        return &dummy;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    return &inner->input;
}

sbgl_GetResult()

sbgl_Result sbgl_GetResult

(

sbgl_Context *

ctx

)

Retrieves the last result code from the context.

Parameters

ctx	The engine context (may be NULL).

Returns

The result code, or SBGL_ERROR_NULL_CONTEXT if ctx is NULL.

Definition at line 71 of file sbgl_core.c.

                                              {
  if (!ctx) {
    return SBGL_ERROR_NULL_CONTEXT;
  }
  return ctx->result;
}

sbgl_GetTelemetry()

sbgl_Telemetry sbgl_GetTelemetry

(

sbgl_Context *

ctx

)

Retrieves the performance telemetry data for the previous frame.

Parameters

ctx	The active engine context.

Returns

A structure containing CPU and GPU timing data.

Definition at line 436 of file sbgl_core.c.

                                                    {
    if (!ctx || !ctx->inner) {
        return (sbgl_Telemetry){ 0 };
    }
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    return inner->lastFrame;
}

sbgl_GetTime()

double sbgl_GetTime

(

sbgl_Context *

ctx

)

Retrieves the current monotonic system time in seconds.

This timer is high-resolution and suitable for frame-time calculation.

Parameters

ctx	The active engine context.

Returns

Monotonic time in seconds.

Definition at line 245 of file sbgl_core.c.

                                       {
    if (!ctx || !ctx->inner)
        return 0.0;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    return (double)sbgl_os_GetPerfCount(inner->window) / (double)sbgl_os_GetPerfFreq(inner->window);
}

sbgl_GetWindowSize()

void sbgl_GetWindowSize	(	sbgl_Context *	ctx,
		int *	w,
		int *	h )

Retrieves the current window dimensions.

Parameters

ctx	The active engine context.
w	Pointer to store the width.
h	Pointer to store the height.

Definition at line 252 of file sbgl_core.c.

                                                           {
    if (w)
        *w = 0;
    if (h)
        *h = 0;
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_os_GetWindowSize(inner->window, w, h);
}

sbgl_Init()

sbgl_InitResult sbgl_Init	(	int	w,
		int	h,
		const char *	title )

Initializes the engine and opens a window.

This function sets up the internal HALs and the Vulkan 1.3 backend. It is a convenience wrapper around sbgl_InitWithConfig() that uses default resource limits and enables validation in debug builds.

Parameters

w	Desired width of the window.
h	Desired height of the window.
title	Title displayed in the OS window manager.

Returns

An initialization result containing the context and any error code.

Definition at line 193 of file sbgl_core.c.

                                                           {
    sbgl_InitConfig config = {
        .windowWidth = w,
        .windowHeight = h,
        .windowTitle = title,
        .limits = { .maxBuffers = 1024, .maxShaders = 256, .maxPipelines = 256 },
        .enableValidation = true
    };
    return sbgl_InitWithConfig(&config);
}

sbgl_InitWithConfig()

sbgl_InitResult sbgl_InitWithConfig

(

const sbgl_InitConfig *

config

)

Initializes the engine and opens a window with explicit configuration.

This function sets up the internal HALs and the Vulkan 1.3 backend using the provided configuration. This allows fine-grained control over resource limits and validation settings.

Parameters

config

Pointer to the initialization configuration.

Returns

An initialization result containing the context and any error code.

Definition at line 112 of file sbgl_core.c.

                                                                   {
    sbgl_InitResult res = { .ctx = NULL, .error = SBGL_SUCCESS };
 
    if (!config) {
        res.error = SBGL_ERROR_INVALID_ARGUMENT;
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_CORE,
                      "sbgl_InitWithConfig: NULL config passed");
        return res;
    }
 
    SblArena main_arena;
    if (!sbl_arena_init(&main_arena, 4 * 1024 * 1024)) {
        res.error = SBGL_ERROR_OUT_OF_MEMORY;
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_CORE,
                      "sbgl_InitWithConfig: arena initialization failed");
        return res;
    }
 
    sbgl_Context* ctx = SBL_ARENA_PUSH_STRUCT_ZERO(&main_arena, sbgl_Context);
    if (!ctx) {
        sbl_arena_free(&main_arena);
        res.error = SBGL_ERROR_OUT_OF_MEMORY;
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_CORE,
                      "sbgl_InitWithConfig: context allocation failed");
        return res;
    }
 
    sbgl_InternalContext* inner = SBL_ARENA_PUSH_STRUCT_ZERO(&main_arena, sbgl_InternalContext);
    if (!inner) {
        sbl_arena_free(&main_arena);
        res.error = SBGL_ERROR_OUT_OF_MEMORY;
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_CORE,
                      "sbgl_InitWithConfig: inner context allocation failed");
        return res;
    }
 
    inner->arena = main_arena;
    sbl_arena_init(&inner->transientArena, 16 * 1024 * 1024);
    inner->clearColor[0] = 0.0f;
    inner->clearColor[1] = 0.0f;
    inner->clearColor[2] = 0.0f;
    inner->clearColor[3] = 0.0f;
    inner->state.isIdle = 1;
    inner->mouseMode = SBGL_MOUSE_MODE_NORMAL;
    inner->state.wasFocused = 0;
 
    ctx->inner = inner;
    ctx->result = SBGL_SUCCESS;
 
    const char* title = config->windowTitle ? config->windowTitle : "SBgl";
    sbgl_platform_Result platformRes = sbgl_os_CreateWindow(
      &inner->arena, &inner->input,
      config->windowWidth, config->windowHeight, title,
      &inner->window
    );
 
    if (platformRes != SBGL_PLATFORM_SUCCESS) {
        res.error = SBGL_ERROR_WINDOW_CREATION_FAILED;
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_PLATFORM,
                      "sbgl_InitWithConfig: window creation failed");
        sbl_arena_free(&inner->arena);
        return res;
    }
 
    inner->gfx = sbgl_gfx_Init(inner->window, &inner->arena, &config->limits, config->enableValidation);
    if (!inner->gfx) {
        res.error = SBGL_ERROR_GRAPHICS_FAILED;
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_GFX,
                      "sbgl_InitWithConfig: graphics initialization failed");
        sbgl_os_DestroyWindow(inner->window);
        sbl_arena_free(&inner->arena);
        return res;
    }
 
    sbgl_log_impl(SBGL_LOG_INFO, SBGL_LOG_CAT_CORE,
                  "sbgl_InitWithConfig: initialization successful");
 
    res.ctx = ctx;
    return res;
}

sbgl_LoadShader()

sbgl_Shader sbgl_LoadShader	(	sbgl_Context *	ctx,
		sbgl_ShaderStage	stage,
		const uint32_t *	bytecode,
		size_t	size )

Loads a shader from SPIR-V bytecode.

Parameters

ctx	The engine context.
stage	The shader stage (Vertex/Fragment).
bytecode	Pointer to the SPIR-V bytecode.
size	Size of the bytecode in bytes.

Returns

A handle to the loaded shader.

Definition at line 523 of file sbgl_core.c.

                                                                                                  {
    if (!ctx || !ctx->inner)
        return SBGL_INVALID_HANDLE;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_Shader res = sbgl_gfx_LoadShader(inner->gfx, stage, bytecode, size);
    ctx->result =
        (res != SBGL_INVALID_HANDLE) ? SBGL_SUCCESS : SBGL_ERROR_GRAPHICS_FAILED;
    return res;
}

sbgl_LoadShaderFromFile()

sbgl_Shader sbgl_LoadShaderFromFile	(	sbgl_Context *	ctx,
		sbgl_ShaderStage	stage,
		const char *	filename )

Helper function to load a shader directly from a SPIR-V file.

Parameters

ctx	The engine context.
stage	The shader stage (Vertex/Fragment).
filename	Path to the SPIR-V file.

Returns

A handle to the loaded shader, or SBGL_INVALID_HANDLE on failure.

Definition at line 534 of file sbgl_core.c.

                                                                                         {
    FILE* file = fopen(filename, "rb");
    if (!file) {
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_GFX, "Failed to open shader file.");
        return SBGL_INVALID_HANDLE;
    }
 
    fseek(file, 0, SEEK_END);
    size_t size = ftell(file);
    fseek(file, 0, SEEK_SET);
 
    uint32_t* buffer = malloc(size);
    if (!buffer) {
        fclose(file);
        return SBGL_INVALID_HANDLE;
    }
 
    size_t read = fread(buffer, 1, size, file);
    fclose(file);
 
    if (read != size) {
        free(buffer);
        return SBGL_INVALID_HANDLE;
    }
 
    sbgl_Shader shader = sbgl_LoadShader(ctx, stage, buffer, size);
    free(buffer);
 
    return shader;
}

sbgl_MapBuffer()

void * sbgl_MapBuffer	(	sbgl_Context *	ctx,
		sbgl_Buffer	buffer )

Maps a GPU buffer into the CPU's address space.

This allows for direct reading from and writing to GPU memory. SBgl buffers are created as host-visible and coherent by default.

Parameters

ctx	The engine context.
buffer	The buffer handle.

Returns

A pointer to the mapped memory, or NULL on failure.

Definition at line 497 of file sbgl_core.c.

                                                            {
    /* The system maps the specified GPU buffer into the CPU's address space,
       allowing for direct memory access. This is essential for reading back
       results from compute shaders or updating dynamic vertex data. */
    if (!ctx || !ctx->inner)
        return NULL;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    void* ptr = sbgl_gfx_MapBuffer(inner->gfx, buffer);
 
    ctx->result = (ptr != NULL) ? SBGL_SUCCESS : SBGL_ERROR_GRAPHICS_FAILED;
    return ptr;
}

sbgl_MemoryBarrier()

void sbgl_MemoryBarrier	(	sbgl_Context *	ctx,
		sbgl_BarrierType	type )

Injects a memory barrier to synchronize compute and graphics operations.

Parameters

ctx	The engine context.
type	The type of barrier to inject.

Definition at line 665 of file sbgl_core.c.

                                                                  {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_MemoryBarrier(inner->gfx, type);
    ctx->result = SBGL_SUCCESS;
}

sbgl_PushConstants()

void sbgl_PushConstants	(	sbgl_Context *	ctx,
		size_t	size,
		const void *	data )

Updates push constants for the currently bound pipeline.

Parameters

ctx	The engine context.
size	Size of the data to push.
data	Pointer to the data.

Definition at line 733 of file sbgl_core.c.

                                                                          {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_PushConstants(inner->gfx, size, data);
    ctx->result = SBGL_SUCCESS;
}

sbgl_RenderQueues()

void sbgl_RenderQueues	(	sbgl_Context *	ctx,
		sbgl_RenderQueue **	queues,
		uint32_t	queueCount,
		const sbgl_Mat4 *	viewProj )

Merges, sorts, and submits pending draw commands to the GPU.

This function processes render queues in a batching operation. A stable radix sort is performed on the packets to minimize state transitions, followed by baking them into indirect draw commands.

Parameters

ctx	The engine context.
queues	Array of pointers to the render queues to be processed.
queueCount	Number of queues in the array.
viewProj	Pointer to the view-projection matrix for the frame.

Definition at line 808 of file sbgl_core.c.

  {
    sbgl_RenderQueuesEx(ctx, queues, queueCount, viewProj, 0);
}

sbgl_RenderQueuesEx()

void sbgl_RenderQueuesEx	(	sbgl_Context *	ctx,
		sbgl_RenderQueue **	queues,
		uint32_t	queueCount,
		const sbgl_Mat4 *	viewProj,
		uint64_t	userAddress )

Extended version of sbgl_RenderQueues with user metadata.

Parameters

ctx	The engine context.
queues	Array of render queues.
queueCount	Number of queues.
viewProj	View-projection matrix.
userAddress	A 64-bit GPU address for user-defined data (e.g., SSBO heightmap).

Definition at line 817 of file sbgl_core.c.

  {
    if (!ctx || !ctx->inner || !queues || queueCount == 0) {
        return;
    }
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    // Total packet count is calculated across all queues to determine buffer requirements
    uint32_t totalPackets = 0;
    for (uint32_t i = 0; i < queueCount; ++i) {
        if (queues[i]) {
            totalPackets += queues[i]->count;
        }
    }
 
    if (totalPackets == 0) {
        return;
    }
 
    // The transient arena is reset for this frame's batching work
    sbl_arena_reset(&inner->transientArena);
 
    inner->sortStartTicks = sbgl_os_GetPerfCount(inner->window);
 
    // Temporary host memory is allocated for merging and sorting from the transient arena
    sbgl_DrawPacket* mergedPackets =
        SBL_ARENA_PUSH_ARRAY(&inner->transientArena, sbgl_DrawPacket, totalPackets);
    sbgl_InstanceData* mergedInstances =
        SBL_ARENA_PUSH_ARRAY(&inner->transientArena, sbgl_InstanceData, totalPackets);
    sbgl_SortKey* keys = SBL_ARENA_PUSH_ARRAY(&inner->transientArena, sbgl_SortKey, totalPackets);
    uint32_t* indices = SBL_ARENA_PUSH_ARRAY(&inner->transientArena, uint32_t, totalPackets);
 
    if (!mergedPackets || !mergedInstances || !keys || !indices) {
        ctx->result = SBGL_ERROR_OUT_OF_MEMORY;
        return;
    }
 
    // Packets and instance data are merged from all queues
    uint32_t current = 0;
    for (uint32_t i = 0; i < queueCount; ++i) {
        if (!queues[i])
            continue;
        for (uint32_t j = 0; j < queues[i]->count; ++j) {
            mergedPackets[current] = queues[i]->packets[j];
            mergedInstances[current] = queues[i]->instances[j];
            keys[current] = mergedPackets[current].key;
            indices[current] = current;
            current++;
        }
        // The queue is cleared for the next frame
        queues[i]->count = 0;
    }
 
    // A stable radix sort is performed on the packets based on sort keys
    sbgl_SortKey* temp_keys =
        SBL_ARENA_PUSH_ARRAY(&inner->transientArena, sbgl_SortKey, totalPackets);
    uint32_t* temp_indices = SBL_ARENA_PUSH_ARRAY(&inner->transientArena, uint32_t, totalPackets);
    if (!temp_keys || !temp_indices) {
        ctx->result = SBGL_ERROR_OUT_OF_MEMORY;
        return;
    }
 
    sbgl_radix_sort(keys, indices, totalPackets, temp_keys, temp_indices);
 
    // Packets and instances are reordered according to the sorted indices
    sbgl_DrawPacket* sortedPackets =
        SBL_ARENA_PUSH_ARRAY(&inner->transientArena, sbgl_DrawPacket, totalPackets);
    sbgl_InstanceData* sortedInstances =
        SBL_ARENA_PUSH_ARRAY(&inner->transientArena, sbgl_InstanceData, totalPackets);
    if (!sortedPackets || !sortedInstances) {
        ctx->result = SBGL_ERROR_OUT_OF_MEMORY;
        return;
    }
 
    for (uint32_t i = 0; i < totalPackets; ++i) {
        sortedPackets[i] = mergedPackets[indices[i]];
        sortedInstances[i] = mergedInstances[indices[i]];
    }
 
    // Sorted packets are baked into optimized indirect draw commands
    sbgl_IndirectCommand* commands =
        SBL_ARENA_PUSH_ARRAY(&inner->transientArena, sbgl_IndirectCommand, totalPackets);
    if (!commands) {
        ctx->result = SBGL_ERROR_OUT_OF_MEMORY;
        return;
    }
 
    uint32_t commandCount = sbgl_bake_commands(sortedPackets, totalPackets, commands, totalPackets);
 
    uint64_t sortEndTicks = sbgl_os_GetPerfCount(inner->window);
    inner->currentFrame.cpu_sort_time +=
        (float)((double)(sortEndTicks - inner->sortStartTicks) * 1000.0 / (double)sbgl_os_GetPerfFreq(inner->window));
 
    inner->currentFrame.draw_calls += commandCount;
    inner->currentFrame.instance_count += totalPackets;
 
    if (commandCount > 0) {
        // Allocate transient GPU space for packed instance data
        sbgl_GfxTransientAllocation instanceAlloc = sbgl_gfx_AllocateTransient(
            inner->gfx,
            sizeof(sbgl_InstanceData) * totalPackets,
            256 // Storage buffer alignment
        );
 
        if (instanceAlloc.buffer != SBGL_INVALID_HANDLE) {
            memcpy(instanceAlloc.mapped, sortedInstances, sizeof(sbgl_InstanceData) * totalPackets);
 
            // Retrieve BDA address and update push constants
            uint64_t bdaAddress = instanceAlloc.deviceAddress;
 
            struct {
                sbgl_Mat4 viewProj;
                uint64_t instanceAddress;
                uint64_t userAddress;
            } pc;
            pc.viewProj = viewProj ? *viewProj : sbgl_Mat4Identity();
            pc.instanceAddress = bdaAddress;
            pc.userAddress = userAddress;
 
            sbgl_gfx_PushConstants(inner->gfx, sizeof(pc), &pc);
 
            // Allocate transient GPU space for baked commands and dispatch MDI
            sbgl_GfxTransientAllocation indirectAlloc = sbgl_gfx_AllocateTransient(
                inner->gfx,
                sizeof(sbgl_IndirectCommand) * commandCount,
                16 // Indirect buffer alignment
            );
 
            if (indirectAlloc.buffer != SBGL_INVALID_HANDLE) {
                memcpy(indirectAlloc.mapped, commands, sizeof(sbgl_IndirectCommand) * commandCount);
                sbgl_gfx_DrawIndirect(
                    inner->gfx,
                    indirectAlloc.buffer,
                    indirectAlloc.offset,
                    commandCount
                );
            }
        }
    }
 
    ctx->result = SBGL_SUCCESS;
}

sbgl_SetClearColor()

void sbgl_SetClearColor	(	sbgl_Context *	ctx,
		float	r,
		float	g,
		float	b,
		float	a )

Sets the clear color for the next frame.

Parameters

ctx	The engine context.
r	Red component (0.0 to 1.0).
g	Green component (0.0 to 1.0).
b	Blue component (0.0 to 1.0).
a	Alpha component (0.0 to 1.0).

Definition at line 401 of file sbgl_core.c.

                                                                               {
    if (!ctx || !ctx->inner)
        return;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    inner->clearColor[0] = r;
    inner->clearColor[1] = g;
    inner->clearColor[2] = b;
    inner->clearColor[3] = a;
    ctx->result = SBGL_SUCCESS;
}

sbgl_SetMouseMode()

void sbgl_SetMouseMode	(	sbgl_Context *	ctx,
		sbgl_MouseMode	mode )

Sets the cursor behavior and visibility.

Parameters

ctx	The engine context.
mode	The desired mouse mode.

Definition at line 422 of file sbgl_core.c.

                                                               {
    if (!ctx || !ctx->inner)
        return;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    inner->mouseMode = mode;
 
    bool visible = (mode == SBGL_MOUSE_MODE_NORMAL);
    bool locked = (mode == SBGL_MOUSE_MODE_CAPTURED);
 
    sbgl_os_SetCursorVisible(inner->window, visible);
    sbgl_os_SetCursorLocked(inner->window, locked);
    ctx->result = SBGL_SUCCESS;
}

sbgl_Shutdown()

void sbgl_Shutdown

(

sbgl_Context *

ctx

)

Gracefully shuts down the engine and releases all resources.

Parameters

ctx	The context to destroy.

Definition at line 204 of file sbgl_core.c.

                                      {
    if (!ctx) {
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_CORE,
                      "sbgl_Shutdown: NULL context");
        return;
    }
    if (!ctx->inner) {
        ctx->result = SBGL_ERROR_NULL_CONTEXT;
        sbgl_log_impl(SBGL_LOG_ERROR, SBGL_LOG_CAT_CORE,
                      "sbgl_Shutdown: uninitialized context");
        return;
    }
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
 
    sbgl_log_impl(SBGL_LOG_INFO, SBGL_LOG_CAT_CORE, "Initiating shutdown...");
 
    if (!inner->state.isIdle) {
        sbgl_DeviceWaitIdle(ctx);
    }
 
    if (inner->gfx)
        sbgl_gfx_Shutdown(inner->gfx);
    if (inner->window)
        sbgl_os_DestroyWindow(inner->window);
 
    sbl_arena_free(&inner->transientArena);
 
    // The context itself is allocated within inner->arena, 
    // so we cannot access it after the arena is freed.
    ctx->result = SBGL_SUCCESS;
    
    sbl_arena_free(&inner->arena);
}

sbgl_SubmitDraw()

void sbgl_SubmitDraw	(	sbgl_RenderQueue *	queue,
		uint32_t	mesh,
		uint32_t	material,
		uint32_t	blendMode,
		uint32_t	sidedness,
		uint32_t	tags,
		sbgl_SortKey	key,
		const sbgl_InstanceData *	data )

Appends a draw command to the render queue.

The packets are cached in the queue until the next frame.

Parameters

queue	The render queue to append to.
mesh	The mesh identifier.
material	The material identifier.
blendMode	The blend mode identifier.
sidedness	The sidedness flag (e.g., single/double sided).
tags	Custom user tags for filtering.
key	The sort key for minimizing state changes.
data	Pointer to the per-instance data (transform, color, etc).

Definition at line 772 of file sbgl_core.c.

  {
    if (!queue) {
        return;
    }
 
    // Verify the queue has not reached maximum capacity
    if (queue->count >= queue->capacity) {
        return;
    }
 
    // The system appends the draw packet to the contiguous array
    uint32_t index = queue->count++;
    sbgl_DrawPacket* packet = &queue->packets[index];
    packet->key = key;
    packet->header = SBGL_PACK_HEADER(mesh, material, blendMode, sidedness, tags);
 
    // Per-instance data is copied into the parallel array
    if (data) {
        queue->instances[index] = *data;
    } else {
        // An identity transform and white color are used if no data is provided
        memset(&queue->instances[index], 0, sizeof(sbgl_InstanceData));
        queue->instances[index].transform = sbgl_Mat4Identity();
        queue->instances[index].color = sbgl_Vec4Set(1, 1, 1, 1);
    }
}

sbgl_UnmapBuffer()

void sbgl_UnmapBuffer	(	sbgl_Context *	ctx,
		sbgl_Buffer	buffer )

Unmaps a previously mapped GPU buffer.

Parameters

ctx	The engine context.
buffer	The buffer handle.

Definition at line 511 of file sbgl_core.c.

                                                             {
    /* The mapping between the CPU and GPU buffer is released, finalizing any
       pending memory writes and ensuring synchronization for subsequent GPU operations. */
    if (!ctx || !ctx->inner)
        return;
 
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    sbgl_gfx_UnmapBuffer(inner->gfx, buffer);
    ctx->result = SBGL_SUCCESS;
}

sbgl_WindowShouldClose()

bool sbgl_WindowShouldClose

(

sbgl_Context *

ctx

)

Checks if the user or OS has requested to close the window.

This flag is set by the OS (for instance, clicking the 'X' button or Alt+F4). The application polls this flag in the main loop and manually initiates shutdown by calling sbgl_Shutdown() when it returns true.

Parameters

ctx	The active engine context.

Returns

True if a close request is pending, false otherwise.

Definition at line 238 of file sbgl_core.c.

                                               {
    if (!ctx || !ctx->inner)
        return true;
    sbgl_InternalContext* inner = (sbgl_InternalContext*)ctx->inner;
    return sbgl_os_WindowShouldClose(inner->window);
}