Sokol

sokol_app.h provides a unified application entry point and window/canvas management for 3D rendering. It supports multiple platforms (Win32, MacOS, Linux, iOS, WASM, Android, UWP) and 3D APIs (GL3.3, Metal, D3D11, GLES3/WebGL2).

To use it, implement a sokol_main function that returns a sapp_desc structure containing callbacks for initialization (init_cb), per-frame updates (frame_cb), and cleanup (cleanup_cb).

#include "sokol_app.h"
#include "sokol_gfx.h"
#include "sokol_log.h"
#include "sokol_glue.h"
#include "triangle-sapp.glsl.h"

static void init(void) {
    // initialization logic
}

void frame(void) {
    // per-frame rendering logic
}

void cleanup(void) {
    // cleanup logic
}

sapp_desc sokol_main(int argc, char* argv[]) {
    (void)argc; (void)argv;
    return (sapp_desc){
        .init_cb = init,
        .frame_cb = frame,
        .cleanup_cb = cleanup,
        .width = 640,
        .height = 480,
        .window_title = "Triangle",
        .icon.sokol_default = true,
        .logger.func = slog_func,
    };
}

sokol_fetch.h allows loading files from the local filesystem (native) or streaming data over HTTP (WASM/Emscripten).

Key Requirements:

• Call sfetch_setup() during initialization.
• Call sfetch_dowork() once per frame to process asynchronous requests.
• Call sfetch_shutdown() during cleanup.
• Use sfetch_send() to initiate a request. The response is handled in a callback function.

#include "sokol_fetch.h"
#include "sokol_log.h"

static void response_callback(const sfetch_response_t* response);

#define MAX_FILE_SIZE (1024*1024)
static uint8_t buffer[MAX_FILE_SIZE];

static void init(void) {
    sfetch_setup(&(sfetch_desc_t){ .logger.func = slog_func });

    sfetch_send(&(sfetch_request_t){
        .path = "hello_world.txt",
        .callback = response_callback,
        .buffer_ptr = buffer,
        .buffer_size = sizeof(buffer)
    });
}

static void frame(void) {
    sfetch_dowork();
}

static void response_callback(const sfetch_response_t* response) {
    if (response->fetched) {
        const void* data = response->buffer_ptr;
        uint64_t data_size = response->fetched_size;
    }
    if (response->failed) {
        switch (response->error_code) {
            case SFETCH_ERROR_FILE_NOT_FOUND: ...
            case SFETCH_ERROR_BUFFER_TOO_SMALL: ...
        }
    }
}

static void shutdown(void) {
    sfetch_shutdown();
}

If your Sokol integration fails to compile or link, check the following common configuration mismatches:

Implementation Definition

Define SOKOL_IMPL (or the specific per-header SOKOL_*_IMPL) in exactly one C or C++ translation unit before including the headers. All other files should include the headers without this define.

Backend Selection

Select exactly one rendering backend in your implementation translation unit. Common defines include:

• SOKOL_GLCORE (uses GLX on Linux by default; use SOKOL_FORCE_EGL for EGL)
• SOKOL_GLES3 (requires -s USE_WEBGL2=1 for Emscripten WebGL2 builds)
• SOKOL_D3D11 (MinGW/MSYS2 may need -ld3d11)
• SOKOL_METAL (macOS/iOS: compile implementation as Objective-C/Objective-C++ .m or .mm and link required frameworks)
• SOKOL_WGPU (WebGPU)
• SOKOL_VULKAN

Note: If using sokol_gfx.h and sokol_app.h together, they must use the same backend define.

Shader Compatibility

Ensure generated shader headers are from a sokol-shdc version compatible with your Sokol headers and were generated for the same backend(s) selected at compile time.