Sokol Module

GX includes a Sokol module for cross-platform graphics and windowing. Sokol is a set of single-header C libraries providing a platform-agnostic graphics API that compiles to OpenGL, Direct3D 11, Metal, WebGL2, and WebGPU. Unlike raylib’s polling game loop, Sokol uses a callback-based architecture — you provide init, frame, cleanup, and event functions.

The module has four sub-modules:

Prerequisites

The module ships with all Sokol headers bundled — no external dependencies needed. The C source is compiled automatically via @cfile. On Windows, links against opengl32, gdi32, user32, shell32 automatically.

Usage

import sokol.app     // window + events
import sokol.gfx     // graphics API
import sokol.glue    // app↔gfx bridge
import sokol.gp      // 2D drawing (optional)

Build with -I modules:

gx myapp.gx -I modules -o myapp.exe

Quick Example — Animated Shapes

import sokol.app
import sokol.gfx
import sokol.glue
import sokol.gp
import math.scalar

var g_time: f32 = 0.0

@c_abi fn init() {
    var gfx_desc: sg_desc
    gfx_desc.environment = sglue_environment()
    sg_setup(&gfx_desc)

    var gp_desc: sgp_desc
    sgp_setup(&gp_desc)
}

@c_abi fn frame() {
    var w = sapp_width()
    var h = sapp_height()
    g_time = g_time + 0.016

    sgp_begin(w, h)
    sgp_viewport(0, 0, w, h)
    sgp_project(0.0, 800.0, 0.0, 600.0)

    // Dark background
    sgp_set_color(0.1, 0.1, 0.15, 1.0)
    sgp_clear()

    // Pulsing red rectangle
    var pulse = sinf(g_time * 3.0) * 20.0
    sgp_set_color(0.9, 0.2, 0.2, 1.0)
    sgp_draw_filled_rect(100.0 - pulse, 100.0 - pulse, 200.0 + pulse * 2.0, 150.0 + pulse * 2.0)

    // Spinning triangle
    var cx = 500.0
    var cy = 300.0
    sgp_set_blend_mode(BLENDMODE_BLEND)
    sgp_set_color(0.2, 0.6, 0.9, 0.8)
    sgp_draw_filled_triangle(
        cx + cosf(g_time) * 80.0, cy + sinf(g_time) * 80.0,
        cx + cosf(g_time + 2.094) * 80.0, cy + sinf(g_time + 2.094) * 80.0,
        cx + cosf(g_time + 4.189) * 80.0, cy + sinf(g_time + 4.189) * 80.0
    )

    // Flush 2D draws into Sokol GFX pass
    var pass: sg_pass
    pass.swapchain = sglue_swapchain()
    sg_begin_pass(&pass)
    sgp_flush()
    sgp_end()
    sg_end_pass()
    sg_commit()
}

@c_abi fn event(ev: const *sapp_event) {
    if (ev.type == EVENTTYPE_KEY_DOWN) {
        if (ev.key_code == KEYCODE_ESCAPE) { sapp_quit() }
    }
}

@c_abi fn cleanup() {
    sgp_shutdown()
    sg_shutdown()
}

fn main() {
    var desc: sapp_desc
    desc.init_cb = init
    desc.frame_cb = frame
    desc.event_cb = event
    desc.cleanup_cb = cleanup
    desc.width = 800
    desc.height = 600
    desc.window_title = "GX + Sokol"
    sapp_run(&desc)
}

Callback Architecture

Sokol uses an event-driven model. You define four callback functions marked @c_abi and pass them via sapp_desc:

@c_abi fn init()                          // called once at startup
@c_abi fn frame()                         // called every frame
@c_abi fn event(ev: const *sapp_event)    // called on input/window events
@c_abi fn cleanup()                       // called on shutdown

The @c_abi attribute is required because Sokol calls these from C code.

Comparison with Raylib

App (sokol.app) — Window & Events

Application Descriptor

var desc: sapp_desc
desc.init_cb = init             // fn()
desc.frame_cb = frame           // fn()
desc.event_cb = event           // fn(const *sapp_event)
desc.cleanup_cb = cleanup       // fn()
desc.width = 800                // initial window width
desc.height = 600               // initial window height
desc.sample_count = 4           // MSAA samples (1 = off)
desc.swap_interval = 1          // V-sync (1 = 60fps on 60Hz)
desc.high_dpi = true            // HiDPI support
desc.fullscreen = false         // fullscreen mode
desc.window_title = "My App"    // window title
sapp_run(&desc)

Window Functions

Event Handling

Events arrive via the event_cb callback:

@c_abi fn event(ev: const *sapp_event) {
    if (ev.type == EVENTTYPE_KEY_DOWN) {
        if (ev.key_code == KEYCODE_W) { move_forward() }
        if (ev.key_code == KEYCODE_ESCAPE) { sapp_quit() }
    }
    if (ev.type == EVENTTYPE_MOUSE_DOWN) {
        if (ev.mouse_button == MOUSEBUTTON_LEFT) {
            shoot(ev.mouse_x, ev.mouse_y)
        }
    }
    if (ev.type == EVENTTYPE_MOUSE_MOVE) {
        look_at(ev.mouse_dx, ev.mouse_dy)
    }
    if (ev.type == EVENTTYPE_MOUSE_SCROLL) {
        zoom(ev.scroll_y)
    }
}

Event Struct (sapp_event)

Event Types

Keyboard Constants

All standard keycodes: KEYCODE_A through KEYCODE_Z, KEYCODE_0 through KEYCODE_9, KEYCODE_SPACE, KEYCODE_ESCAPE, KEYCODE_ENTER, KEYCODE_TAB, KEYCODE_BACKSPACE, KEYCODE_DELETE, arrow keys (KEYCODE_UP, KEYCODE_DOWN, KEYCODE_LEFT, KEYCODE_RIGHT), function keys (KEYCODE_F1 through KEYCODE_F25), modifiers (KEYCODE_LEFT_SHIFT, KEYCODE_LEFT_CONTROL, KEYCODE_LEFT_ALT), numpad (KEYCODE_KP_0 through KEYCODE_KP_9).

Mouse Button Constants

MOUSEBUTTON_LEFT, MOUSEBUTTON_RIGHT, MOUSEBUTTON_MIDDLE.

GFX (sokol.gfx) — GPU Rendering

The low-level graphics API for creating buffers, shaders, and pipelines.

Initialization

@c_abi fn init() {
    var gfx_desc: sg_desc
    gfx_desc.environment = sglue_environment()
    sg_setup(&gfx_desc)
}

Render Pass

A render pass clears the framebuffer and draws geometry:

@c_abi fn frame() {
    var pass: sg_pass
    pass.swapchain = sglue_swapchain()
    pass.action.colors[0].load_action = 1     // SG_LOADACTION_CLEAR
    pass.action.colors[0].clear_value.r = 0.1
    pass.action.colors[0].clear_value.g = 0.1
    pass.action.colors[0].clear_value.b = 0.15
    pass.action.colors[0].clear_value.a = 1.0
    sg_begin_pass(&pass)
    // ... draw ...
    sg_end_pass()
    sg_commit()
}

Core Functions

Resource Creation

Custom Shader Example

For advanced rendering (e.g. a custom particle system), you create shaders, pipelines, and vertex buffers manually:

// Vertex data for a colored triangle
var vertices: f32[15] = [
    // x,    y,     r,   g,   b
     0.0,  0.5,   1.0, 0.0, 0.0,
     0.5, -0.5,   0.0, 1.0, 0.0,
    -0.5, -0.5,   0.0, 0.0, 1.0
]

// Create vertex buffer
var buf_desc: sg_buffer_desc
buf_desc.data.ptr = &vertices
buf_desc.data.size = 60   // 15 floats * 4 bytes
var vbuf = sg_make_buffer(&buf_desc)

// Create shader with inline GLSL
var shd_desc: sg_shader_desc
shd_desc.vertex_func.source = "
    #version 330
    layout(location=0) in vec2 pos;
    layout(location=1) in vec3 col;
    out vec3 v_color;
    void main() { gl_Position = vec4(pos, 0.0, 1.0); v_color = col; }
"
shd_desc.fragment_func.source = "
    #version 330
    in vec3 v_color;
    out vec4 frag_color;
    void main() { frag_color = vec4(v_color, 1.0); }
"
shd_desc.attrs[0].glsl_name = "pos"
shd_desc.attrs[1].glsl_name = "col"
var shd = sg_make_shader(&shd_desc)

// Create pipeline
var pip_desc: sg_pipeline_desc
pip_desc.shader = shd
pip_desc.layout.attrs[0].format = 3    // SG_VERTEXFORMAT_FLOAT2
pip_desc.layout.attrs[1].format = 5    // SG_VERTEXFORMAT_FLOAT3
var pip = sg_make_pipeline(&pip_desc)

// Draw each frame
sg_apply_pipeline(pip)
var bind: sg_bindings
bind.vertex_buffers[0] = vbuf
sg_apply_bindings(&bind)
sg_draw(0, 3, 1)

Handle Types

All GPU resources are opaque 32-bit handles:

GP (sokol.gp) — 2D Drawing

A high-level 2D drawing API built on top of sokol.gfx. Similar in concept to raylib’s shape drawing but with explicit batching and state management.

Initialization

@c_abi fn init() {
    // Initialize gfx first
    var gfx_desc: sg_desc
    gfx_desc.environment = sglue_environment()
    sg_setup(&gfx_desc)

    // Then initialize 2D painter
    var gp_desc: sgp_desc
    sgp_setup(&gp_desc)
}

Frame Structure

@c_abi fn frame() {
    var w = sapp_width()
    var h = sapp_height()

    sgp_begin(w, h)                    // begin 2D draw batch
    sgp_viewport(0, 0, w, h)          // set viewport
    sgp_project(0.0, 800.0, 0.0, 600.0) // coordinate system

    sgp_set_color(0.1, 0.1, 0.1, 1.0)
    sgp_clear()                        // clear background

    // ... draw shapes ...

    // Flush into Sokol GFX pass
    var pass: sg_pass
    pass.swapchain = sglue_swapchain()
    sg_begin_pass(&pass)
    sgp_flush()                        // submit 2D draws
    sgp_end()                          // end 2D batch
    sg_end_pass()
    sg_commit()
}

Drawing Primitives

Drawing a Game HUD

// Health bar background
sgp_set_color(0.3, 0.0, 0.0, 0.8)
sgp_draw_filled_rect(20.0, 20.0, 200.0, 20.0)

// Health bar fill (proportional)
var health_pct = 0.75  // 75% health
sgp_set_color(0.0, 0.9, 0.0, 0.9)
sgp_draw_filled_rect(20.0, 20.0, 200.0 * health_pct, 20.0)

// Minimap border
sgp_set_color(0.5, 0.5, 0.5, 0.8)
sgp_draw_filled_rect(600.0, 20.0, 164.0, 164.0)  // border
sgp_set_color(0.1, 0.1, 0.15, 0.9)
sgp_draw_filled_rect(602.0, 22.0, 160.0, 160.0)  // inner

// Player dot on minimap
sgp_set_color(0.0, 1.0, 0.0, 1.0)
sgp_draw_filled_rect(680.0, 100.0, 4.0, 4.0)

// Enemy dots
sgp_set_color(1.0, 0.0, 0.0, 1.0)
sgp_draw_filled_rect(650.0, 80.0, 3.0, 3.0)
sgp_draw_filled_rect(700.0, 130.0, 3.0, 3.0)

Color & Blending

Blend Modes:

Transforms

Apply 2D transforms to subsequent draw calls:

// Draw a rotated rectangle (like a spinning pickup item)
sgp_push_transform()
sgp_rotate_at(g_time * 2.0, 400.0, 300.0)  // spin around center
sgp_set_color(1.0, 0.8, 0.0, 1.0)
sgp_draw_filled_rect(385.0, 285.0, 30.0, 30.0)
sgp_pop_transform()

Textures

// Draw a textured sprite
sgp_set_image(0, sprite_texture)
sgp_set_color(1.0, 1.0, 1.0, 1.0)  // no tint
var dst: sgp_rect
dst.x = player_x; dst.y = player_y; dst.w = 64.0; dst.h = 64.0
var src: sgp_rect
src.x = 0.0; src.y = 0.0; src.w = 1.0; src.h = 1.0  // full texture
sgp_draw_textured_rect(0, dst, src)
sgp_unset_image(0)

Viewport & Scissor

// Draw only within a UI panel region
sgp_scissor(20, 100, 300, 400)  // clip to panel bounds
// ... draw panel contents ...
sgp_reset_scissor()

Batch Control

All sgp_draw_* calls are batched internally. sgp_flush() submits them as Sokol GFX draw commands inside a render pass.

Error Handling

Glue (sokol.glue) — App/GFX Bridge

Two functions that connect sokol.app to sokol.gfx:

// In init:
var desc: sg_desc
desc.environment = sglue_environment()
sg_setup(&desc)

// In frame:
var pass: sg_pass
pass.swapchain = sglue_swapchain()
sg_begin_pass(&pass)

Common Patterns

Game Loop Template

import sokol.app
import sokol.gfx
import sokol.glue
import sokol.gp

var g_time: f32 = 0.0

@c_abi fn init() {
    var gfx_desc: sg_desc
    gfx_desc.environment = sglue_environment()
    sg_setup(&gfx_desc)
    var gp_desc: sgp_desc
    sgp_setup(&gp_desc)
}

@c_abi fn frame() {
    var w = sapp_width()
    var h = sapp_height()
    g_time = g_time + sapp_frame_duration()

    sgp_begin(w, h)
    sgp_viewport(0, 0, w, h)
    sgp_project(0.0, 800.0, 0.0, 600.0)

    // Clear
    sgp_set_color(0.0, 0.0, 0.0, 1.0)
    sgp_clear()

    // Draw game world here...

    // Flush to screen
    var pass: sg_pass
    pass.swapchain = sglue_swapchain()
    sg_begin_pass(&pass)
    sgp_flush()
    sgp_end()
    sg_end_pass()
    sg_commit()
}

@c_abi fn event(ev: const *sapp_event) {
    if (ev.type == EVENTTYPE_KEY_DOWN) {
        if (ev.key_code == KEYCODE_ESCAPE) { sapp_quit() }
    }
}

@c_abi fn cleanup() {
    sgp_shutdown()
    sg_shutdown()
}

fn main() {
    var desc: sapp_desc
    desc.init_cb = init
    desc.frame_cb = frame
    desc.event_cb = event
    desc.cleanup_cb = cleanup
    desc.width = 800
    desc.height = 600
    desc.swap_interval = 1
    desc.window_title = "My Game"
    sapp_run(&desc)
}

Dynamic Vertex Buffer (Snake Game Pattern)

For games that update geometry every frame (tile maps, particle systems):

var g_verts: f32[5000]   // x, y, r, g, b per vertex
var g_vert_count: i32 = 0
var g_vbuf: sg_buffer

@c_abi fn init() {
    // ... setup gfx ...

    // Create dynamic vertex buffer
    var buf_desc: sg_buffer_desc
    buf_desc.size = 20000           // 5000 floats * 4 bytes
    buf_desc.usage.dynamic_update = true
    g_vbuf = sg_make_buffer(&buf_desc)
}

@c_abi fn frame() {
    // Rebuild vertex data
    g_vert_count = 0
    // ... push_vertex() calls to fill g_verts ...

    // Upload to GPU
    var range: sg_range
    range.ptr = &g_verts
    range.size = g_vert_count * 20   // 5 floats * 4 bytes per vertex
    sg_update_buffer(g_vbuf, &range)

    // Draw
    sg_apply_pipeline(g_pip)
    var bind: sg_bindings
    bind.vertex_buffers[0] = g_vbuf
    sg_apply_bindings(&bind)
    sg_draw(0, g_vert_count, 1)
}

Differences from Raylib

Platform Notes

• Windows: Uses OpenGL Core Profile. Links opengl32, gdi32, user32, shell32.
• Linux: Links GL, X11, Xi, Xcursor, dl, pthread, m.
• macOS: Uses Metal. Links Cocoa, QuartzCore, Metal, MetalKit.
• Web: Compiles to WebGL2/WebGPU via Emscripten.
• TCC: Supported for simple programs. Clang/GCC recommended for optimized builds.
• SOKOL_GLCORE is the default backend on desktop. Change in sokol_impl.c for others.

Module Layout

modules/
  sokol/
    c/
      sokol_app.h        Platform windowing + events
      sokol_gfx.h        GPU graphics API
      sokol_gp.h         2D drawing painter
      sokol_glue.h       App ↔ GFX bridge
      sokol_impl.c       Single compilation unit (SOKOL_IMPL)
    gx/
      app.gx             Window, events, keycodes (build directives here)
      gfx.gx             Buffers, shaders, pipelines, passes
      gp.gx              2D drawing, transforms, blending
      glue.gx            Environment + swapchain bridge

Examples