API for the SiputBiru Graphics Library (SBgl). More...

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

Include dependency graph for sbgl.h:

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

Macros
#define	SBGL_KEY_UNKNOWN SBGL_SCANCODE_UNKNOWN

#define	SBGL_KEY_A SBGL_SCANCODE_A

#define	SBGL_KEY_B SBGL_SCANCODE_B

#define	SBGL_KEY_C SBGL_SCANCODE_C

#define	SBGL_KEY_D SBGL_SCANCODE_D

#define	SBGL_KEY_E SBGL_SCANCODE_E

#define	SBGL_KEY_F SBGL_SCANCODE_F

#define	SBGL_KEY_G SBGL_SCANCODE_G

#define	SBGL_KEY_H SBGL_SCANCODE_H

#define	SBGL_KEY_I SBGL_SCANCODE_I

#define	SBGL_KEY_J SBGL_SCANCODE_J

#define	SBGL_KEY_K SBGL_SCANCODE_K

#define	SBGL_KEY_L SBGL_SCANCODE_L

#define	SBGL_KEY_M SBGL_SCANCODE_M

#define	SBGL_KEY_N SBGL_SCANCODE_N

#define	SBGL_KEY_O SBGL_SCANCODE_O

#define	SBGL_KEY_P SBGL_SCANCODE_P

#define	SBGL_KEY_Q SBGL_SCANCODE_Q

#define	SBGL_KEY_R SBGL_SCANCODE_R

#define	SBGL_KEY_S SBGL_SCANCODE_S

#define	SBGL_KEY_T SBGL_SCANCODE_T

#define	SBGL_KEY_U SBGL_SCANCODE_U

#define	SBGL_KEY_V SBGL_SCANCODE_V

#define	SBGL_KEY_W SBGL_SCANCODE_W

#define	SBGL_KEY_X SBGL_SCANCODE_X

#define	SBGL_KEY_Y SBGL_SCANCODE_Y

#define	SBGL_KEY_Z SBGL_SCANCODE_Z

#define	SBGL_KEY_1 SBGL_SCANCODE_1

#define	SBGL_KEY_2 SBGL_SCANCODE_2

#define	SBGL_KEY_3 SBGL_SCANCODE_3

#define	SBGL_KEY_4 SBGL_SCANCODE_4

#define	SBGL_KEY_5 SBGL_SCANCODE_5

#define	SBGL_KEY_6 SBGL_SCANCODE_6

#define	SBGL_KEY_7 SBGL_SCANCODE_7

#define	SBGL_KEY_8 SBGL_SCANCODE_8

#define	SBGL_KEY_9 SBGL_SCANCODE_9

#define	SBGL_KEY_0 SBGL_SCANCODE_0

#define	SBGL_KEY_MINUS SBGL_SCANCODE_MINUS

#define	SBGL_KEY_EQUAL SBGL_SCANCODE_EQUAL

#define	SBGL_KEY_RETURN SBGL_SCANCODE_RETURN

#define	SBGL_KEY_ESCAPE SBGL_SCANCODE_ESCAPE

#define	SBGL_KEY_BACKSPACE SBGL_SCANCODE_BACKSPACE

#define	SBGL_KEY_TAB SBGL_SCANCODE_TAB

#define	SBGL_KEY_SPACE SBGL_SCANCODE_SPACE

#define	SBGL_KEY_RIGHT SBGL_SCANCODE_RIGHT

#define	SBGL_KEY_LEFT SBGL_SCANCODE_LEFT

#define	SBGL_KEY_DOWN SBGL_SCANCODE_DOWN

#define	SBGL_KEY_UP SBGL_SCANCODE_UP

#define	SBGL_KEY_LSHIFT SBGL_SCANCODE_LSHIFT

#define	SBGL_KEY_LCTRL SBGL_SCANCODE_LCTRL

#define	SBGL_KEY_LALT SBGL_SCANCODE_LALT

#define	SBGL_MOUSE_LEFT SBGL_MOUSE_BUTTON_LEFT

#define	SBGL_MOUSE_RIGHT SBGL_MOUSE_BUTTON_RIGHT

#define	SBGL_MOUSE_MIDDLE SBGL_MOUSE_BUTTON_MIDDLE

#define	sbgl_Clear sbgl_SetClearColor
	Backward compatibility alias for sbgl_SetClearColor.

Functions
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.

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.

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_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 groupCountX, uint32_t groupCountY, uint32_t groupCountZ)
	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, struct 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.

Detailed Description

API for the SiputBiru Graphics Library (SBgl).

This header defines the interface for window management, frame lifecycle, and input handling.

Definition in file sbgl.h.

Macro Definition Documentation

◆ sbgl_Clear

#define sbgl_Clear sbgl_SetClearColor

Backward compatibility alias for sbgl_SetClearColor.

Definition at line 229 of file sbgl.h.

◆ SBGL_KEY_0

#define SBGL_KEY_0 SBGL_SCANCODE_0

Definition at line 78 of file sbgl.h.

◆ SBGL_KEY_1

#define SBGL_KEY_1 SBGL_SCANCODE_1

Definition at line 69 of file sbgl.h.

◆ SBGL_KEY_2

#define SBGL_KEY_2 SBGL_SCANCODE_2

Definition at line 70 of file sbgl.h.

◆ SBGL_KEY_3

#define SBGL_KEY_3 SBGL_SCANCODE_3

Definition at line 71 of file sbgl.h.

◆ SBGL_KEY_4

#define SBGL_KEY_4 SBGL_SCANCODE_4

Definition at line 72 of file sbgl.h.

◆ SBGL_KEY_5

#define SBGL_KEY_5 SBGL_SCANCODE_5

Definition at line 73 of file sbgl.h.

◆ SBGL_KEY_6

#define SBGL_KEY_6 SBGL_SCANCODE_6

Definition at line 74 of file sbgl.h.

◆ SBGL_KEY_7

#define SBGL_KEY_7 SBGL_SCANCODE_7

Definition at line 75 of file sbgl.h.

◆ SBGL_KEY_8

#define SBGL_KEY_8 SBGL_SCANCODE_8

Definition at line 76 of file sbgl.h.

◆ SBGL_KEY_9

#define SBGL_KEY_9 SBGL_SCANCODE_9

Definition at line 77 of file sbgl.h.

◆ SBGL_KEY_A

#define SBGL_KEY_A SBGL_SCANCODE_A

Definition at line 42 of file sbgl.h.

◆ SBGL_KEY_B

#define SBGL_KEY_B SBGL_SCANCODE_B

Definition at line 43 of file sbgl.h.

◆ SBGL_KEY_BACKSPACE

#define SBGL_KEY_BACKSPACE SBGL_SCANCODE_BACKSPACE

Definition at line 85 of file sbgl.h.

◆ SBGL_KEY_C

#define SBGL_KEY_C SBGL_SCANCODE_C

Definition at line 44 of file sbgl.h.

◆ SBGL_KEY_D

#define SBGL_KEY_D SBGL_SCANCODE_D

Definition at line 45 of file sbgl.h.

◆ SBGL_KEY_DOWN

#define SBGL_KEY_DOWN SBGL_SCANCODE_DOWN

Definition at line 90 of file sbgl.h.

◆ SBGL_KEY_E

#define SBGL_KEY_E SBGL_SCANCODE_E

Definition at line 46 of file sbgl.h.

◆ SBGL_KEY_EQUAL

#define SBGL_KEY_EQUAL SBGL_SCANCODE_EQUAL

Definition at line 81 of file sbgl.h.

◆ SBGL_KEY_ESCAPE

#define SBGL_KEY_ESCAPE SBGL_SCANCODE_ESCAPE

Definition at line 84 of file sbgl.h.

◆ SBGL_KEY_F

#define SBGL_KEY_F SBGL_SCANCODE_F

Definition at line 47 of file sbgl.h.

◆ SBGL_KEY_G

#define SBGL_KEY_G SBGL_SCANCODE_G

Definition at line 48 of file sbgl.h.

◆ SBGL_KEY_H

#define SBGL_KEY_H SBGL_SCANCODE_H

Definition at line 49 of file sbgl.h.

◆ SBGL_KEY_I

#define SBGL_KEY_I SBGL_SCANCODE_I

Definition at line 50 of file sbgl.h.

◆ SBGL_KEY_J

#define SBGL_KEY_J SBGL_SCANCODE_J

Definition at line 51 of file sbgl.h.

◆ SBGL_KEY_K

#define SBGL_KEY_K SBGL_SCANCODE_K

Definition at line 52 of file sbgl.h.

◆ SBGL_KEY_L

#define SBGL_KEY_L SBGL_SCANCODE_L

Definition at line 53 of file sbgl.h.

◆ SBGL_KEY_LALT

#define SBGL_KEY_LALT SBGL_SCANCODE_LALT

Definition at line 94 of file sbgl.h.

◆ SBGL_KEY_LCTRL

#define SBGL_KEY_LCTRL SBGL_SCANCODE_LCTRL

Definition at line 93 of file sbgl.h.

◆ SBGL_KEY_LEFT

#define SBGL_KEY_LEFT SBGL_SCANCODE_LEFT

Definition at line 89 of file sbgl.h.

◆ SBGL_KEY_LSHIFT

#define SBGL_KEY_LSHIFT SBGL_SCANCODE_LSHIFT

Definition at line 92 of file sbgl.h.

◆ SBGL_KEY_M

#define SBGL_KEY_M SBGL_SCANCODE_M

Definition at line 54 of file sbgl.h.

◆ SBGL_KEY_MINUS

#define SBGL_KEY_MINUS SBGL_SCANCODE_MINUS

Definition at line 80 of file sbgl.h.

◆ SBGL_KEY_N

#define SBGL_KEY_N SBGL_SCANCODE_N

Definition at line 55 of file sbgl.h.

◆ SBGL_KEY_O

#define SBGL_KEY_O SBGL_SCANCODE_O

Definition at line 56 of file sbgl.h.

◆ SBGL_KEY_P

#define SBGL_KEY_P SBGL_SCANCODE_P

Definition at line 57 of file sbgl.h.

◆ SBGL_KEY_Q

#define SBGL_KEY_Q SBGL_SCANCODE_Q

Definition at line 58 of file sbgl.h.

◆ SBGL_KEY_R

#define SBGL_KEY_R SBGL_SCANCODE_R

Definition at line 59 of file sbgl.h.

◆ SBGL_KEY_RETURN

#define SBGL_KEY_RETURN SBGL_SCANCODE_RETURN

Definition at line 83 of file sbgl.h.

◆ SBGL_KEY_RIGHT

#define SBGL_KEY_RIGHT SBGL_SCANCODE_RIGHT

Definition at line 88 of file sbgl.h.

◆ SBGL_KEY_S

#define SBGL_KEY_S SBGL_SCANCODE_S

Definition at line 60 of file sbgl.h.

◆ SBGL_KEY_SPACE

#define SBGL_KEY_SPACE SBGL_SCANCODE_SPACE

Definition at line 87 of file sbgl.h.

◆ SBGL_KEY_T

#define SBGL_KEY_T SBGL_SCANCODE_T

Definition at line 61 of file sbgl.h.

◆ SBGL_KEY_TAB

#define SBGL_KEY_TAB SBGL_SCANCODE_TAB

Definition at line 86 of file sbgl.h.

◆ SBGL_KEY_U

#define SBGL_KEY_U SBGL_SCANCODE_U

Definition at line 62 of file sbgl.h.

◆ SBGL_KEY_UNKNOWN

#define SBGL_KEY_UNKNOWN SBGL_SCANCODE_UNKNOWN

Definition at line 41 of file sbgl.h.

◆ SBGL_KEY_UP

#define SBGL_KEY_UP SBGL_SCANCODE_UP

Definition at line 91 of file sbgl.h.

◆ SBGL_KEY_V

#define SBGL_KEY_V SBGL_SCANCODE_V

Definition at line 63 of file sbgl.h.

◆ SBGL_KEY_W

#define SBGL_KEY_W SBGL_SCANCODE_W

Definition at line 64 of file sbgl.h.

◆ SBGL_KEY_X

#define SBGL_KEY_X SBGL_SCANCODE_X

Definition at line 65 of file sbgl.h.

◆ SBGL_KEY_Y

#define SBGL_KEY_Y SBGL_SCANCODE_Y

Definition at line 66 of file sbgl.h.

◆ SBGL_KEY_Z

#define SBGL_KEY_Z SBGL_SCANCODE_Z

Definition at line 67 of file sbgl.h.

◆ SBGL_MOUSE_LEFT

#define SBGL_MOUSE_LEFT SBGL_MOUSE_BUTTON_LEFT

Definition at line 96 of file sbgl.h.

◆ SBGL_MOUSE_MIDDLE

#define SBGL_MOUSE_MIDDLE SBGL_MOUSE_BUTTON_MIDDLE

Definition at line 98 of file sbgl.h.

◆ SBGL_MOUSE_RIGHT

#define SBGL_MOUSE_RIGHT SBGL_MOUSE_BUTTON_RIGHT

Definition at line 97 of file sbgl.h.

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_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);
}

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ sbgl_Clear

◆ SBGL_KEY_0

◆ SBGL_KEY_1

◆ SBGL_KEY_2

◆ SBGL_KEY_3

◆ SBGL_KEY_4

◆ SBGL_KEY_5

◆ SBGL_KEY_6

◆ SBGL_KEY_7

◆ SBGL_KEY_8

◆ SBGL_KEY_9

◆ SBGL_KEY_A

◆ SBGL_KEY_B

◆ SBGL_KEY_BACKSPACE

◆ SBGL_KEY_C

◆ SBGL_KEY_D

◆ SBGL_KEY_DOWN

◆ SBGL_KEY_E

◆ SBGL_KEY_EQUAL

◆ SBGL_KEY_ESCAPE

◆ SBGL_KEY_F

◆ SBGL_KEY_G

◆ SBGL_KEY_H

◆ SBGL_KEY_I

◆ SBGL_KEY_J

◆ SBGL_KEY_K

◆ SBGL_KEY_L

◆ SBGL_KEY_LALT

◆ SBGL_KEY_LCTRL

◆ SBGL_KEY_LEFT

◆ SBGL_KEY_LSHIFT

◆ SBGL_KEY_M

◆ SBGL_KEY_MINUS

◆ SBGL_KEY_N

◆ SBGL_KEY_O

◆ SBGL_KEY_P

◆ SBGL_KEY_Q

◆ SBGL_KEY_R

◆ SBGL_KEY_RETURN

◆ SBGL_KEY_RIGHT

◆ SBGL_KEY_S

◆ SBGL_KEY_SPACE

◆ SBGL_KEY_T

◆ SBGL_KEY_TAB

◆ SBGL_KEY_U

◆ SBGL_KEY_UNKNOWN

◆ SBGL_KEY_UP

◆ SBGL_KEY_V

◆ SBGL_KEY_W

◆ SBGL_KEY_X

◆ SBGL_KEY_Y

◆ SBGL_KEY_Z

◆ SBGL_MOUSE_LEFT

◆ SBGL_MOUSE_MIDDLE

◆ SBGL_MOUSE_RIGHT

Function Documentation

◆ sbgl_BeginCompute()

◆ sbgl_BeginDrawing()

◆ sbgl_BindBuffer()

◆ sbgl_BindComputePipeline()

◆ sbgl_BindPipeline()

◆ sbgl_ClearResult()

◆ sbgl_CreateBuffer()

◆ sbgl_CreateComputePipeline()

◆ sbgl_CreatePipeline()

◆ sbgl_CreateRenderQueue()

◆ sbgl_DestroyBuffer()

◆ sbgl_DestroyComputePipeline()

◆ sbgl_DestroyPipeline()

◆ sbgl_DestroyShader()

◆ sbgl_DeviceWaitIdle()

◆ sbgl_DispatchCompute()

◆ sbgl_Draw()

◆ sbgl_DrawIndexed()

◆ sbgl_DrawIndirect()

◆ sbgl_EndCompute()