sokol

Kind	ffi-zig
Capabilities	ffi
Categories	graphics gamedev multimedia
Keywords	graphics audio gamedev sokol zig-ffi

Cross-platform graphics and audio library bindings for Kit using sokol-zig

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/blend.kit`	Blend mode grid example
`examples/buffer-offsets.kit`	Buffer offset example
`examples/clear.kit`	Minimal animated framebuffer clear example
`examples/cube.kit`	Indexed cube example
`examples/debug-text-print.kit`	Debug text print API example
`examples/debug-text-userfont.kit`	Debug text user font example
`examples/debug-text.kit`	Debug text rendering example
`examples/defer-pattern.kit`	Resource cleanup pattern example
`examples/instancing-compute.kit`	Compute and instancing example
`examples/instancing.kit`	Particle instancing example
`examples/mrt.kit`	Multiple render targets example
`examples/noninterleaved.kit`	Non-interleaved vertex buffer example
`examples/offscreen.kit`	Offscreen render target example
`examples/quad.kit`	Textured quad example
`examples/saudio.kit`	sokol_audio example
`examples/sgl-context.kit`	sokol_gl context example
`examples/sgl-points.kit`	sokol_gl points example
`examples/sgl.kit`	sokol_gl immediate-mode rendering example
`examples/shapes.kit`	Procedural shape generation example
`examples/tex-cube.kit`	Textured cube example
`examples/triangle.kit`	Triangle example
`examples/vertex-pull.kit`	Vertex pulling example
`kit.toml`	Package manifest with metadata, capabilities, and tasks
`src/sokol.kit`	Kit API surface for sokolapp, sokolgfx, sokol_gl, debug text, audio, and shapes
`tests/sokol.test.kit`	Tests for exported API members and helper functions
`zig/kit_ffi.zig`	Kit FFI compatibility types and helpers
`zig/sokol_wrapper.zig`	Zig FFI wrapper used by `extern-zig` bindings

Dependencies

No Kit package dependencies.

This package requires the ffi capability:

[capabilities]
requires = ["ffi"]

The package is declared as kind = "ffi-zig" and uses zig/sokol_wrapper.zig as the bridge between Kit values and the Sokol-facing API.

Installation

kit add gitlab.com/kit-lang/packages/kit-sokol.git

Usage

import Kit.Sokol as Sokol

state = {
  g: 0.0
}

init = fn =>
  Sokol.Gfx.setup {
    environment: Sokol.Glue.environment
  }

frame = fn(st) =>
  g = st.g + 0.01
  new-g = if g > 1.0 then 0.0 else g

  pass-action = Sokol.Gfx.pass-action {
    colors: [{
      load-action: :clear,
      clear-value: {r: 1.0, g: new-g, b: 0.0, a: 1.0}
    }]
  }

  Sokol.Gfx.begin-pass {
    action: pass-action,
    swapchain: Sokol.Glue.swapchain
  }
  Sokol.Gfx.end-pass
  Sokol.Gfx.commit

  {g: new-g}

cleanup = fn =>
  Sokol.Gfx.shutdown

main = fn =>
  Sokol.App.run {
    init: init,
    frame: frame,
    cleanup: cleanup,
    initial-state: state,
    width: 640,
    height: 480,
    window-title: "kit-sokol",
    icon: {sokol-default: true}
  }

main

When working inside this repository, examples import the local source file:

import "../src/sokol" as Sokol

Installed package users should import Kit.Sokol.

API Overview

The public module is organized into records that mirror the Sokol libraries:

API	Purpose
`Sokol.App`	Application lifecycle, window size, frame timing, and quit requests
`Sokol.Gfx`	Graphics setup, resources, passes, pipelines, bindings, uniforms, draw, and dispatch
`Sokol.Glue`	Environment and swapchain helpers for connecting app and graphics
`Sokol.GL`	Immediate-mode rendering helpers from sokol_gl
`Sokol.DebugText`	Built-in debug text rendering and font handles
`Sokol.Audio`	Audio setup, device queries, and sample push
`Sokol.Shapes`	Procedural mesh helpers for boxes, planes, spheres, cylinders, and torus shapes
`Sokol.rgb`, `Sokol.rgba`, `Sokol.colors`	Color helpers

The package also exports SokolError variants for typed error handling:

SokolConfigError
SokolCallbackError
SokolGraphicsError
SokolNotImplementedError

Development

Running Examples

Run examples with the interpreter:

kit run --allow=ffi examples/clear.kit

Compile examples to a native binary:

kit build --allow=ffi examples/clear.kit -o /tmp/kit-sokol-clear
/tmp/kit-sokol-clear

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running Parity

Check that interpreter and compiled example outputs match:

kit parity --no-spinner --failures-only

Parity writes timestamped *-results.txt files in the package root. They can be removed with the clean task.

Running kit dev

Run the standard development workflow:

kit dev

This will format, check, and test the package according to the Kit development workflow.

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, parity results, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/sokol/, making it available for import as Kit.Sokol in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

`SokolError`

Sokol error type for typed error handling.

Variants

SokolConfigError {message}

SokolCallbackError {message}

SokolGraphicsError {message}

SokolNotImplementedError {message}

`App`

Application lifecycle and window query functions.

`Gfx`

Graphics API functions for setup, resources, passes, and draw calls.

`Glue`

Integration helpers connecting sokol_app and sokol_gfx.

`GL`

Immediate-mode rendering functions from sokol_gl.

`DebugText`

Debug text rendering functions and built-in font handles.

`Audio`

Audio setup, query, and sample push functions.

`Shapes`

Procedural shape generation functions.

`rgb`

Create a color from RGB values (0-255).

Int -> Int -> Int -> {r: Float, g: Float, b: Float, a: Float}

`rgba`

Create a color from RGBA values (0-255).

Int -> Int -> Int -> Int -> {r: Float, g: Float, b: Float, a: Float}

`colors`

Common colors.