sokol 0.1.0

Python ctypes bindings for the Sokol cross-platform graphics library

Sokol Python Bindings

Automatically generated Python ctypes bindings for the Sokol cross-platform graphics library using libclang.

Installation

pip install sokol

Or with uv:

uv add sokol

Features

• Cross-platform support: Windows (D3D11), macOS (Metal), Linux (OpenGL)
• Automatic platform detection: Just call load_sokol() and it works
• Pre-built shared libraries: Included for all supported platforms
• Automatic binding generation from Sokol C headers using libclang
• Complete type coverage: enums, structs, function pointers, and API functions
• Zero manual binding code - everything is parsed from headers

Supported Platforms

Platform	Architecture	Backend	Library
Windows	x64	D3D11	sokol-windows-x64.dll
macOS	x64	Metal	libsokol-macos-x64.dylib
macOS	ARM64	Metal	libsokol-macos-arm64.dylib
Linux	x64	OpenGL	libsokol-linux-x64.so

Generated Statistics

Type	Count
Enums	42
Structs	199
Function Pointer Types	80
API Functions	207

Requirements

• Python 3.10+
• Pre-built shared libraries are included in the package

For Development/Binding Generation

• libclang (pip install libclang)

Quick Start

1. Install Dependencies

uv pip install libclang

2. Generate Bindings

python setup_and_generate.py

This will:

• Download Sokol headers from GitHub to ./sokol/
• Parse headers with libclang
• Generate sokol_bindings.py (~6000 lines)

3. Run the Demo

python main.py

Project Structure

├── generate_bindings.py    # Binding generator using libclang
├── setup_and_generate.py   # Downloads headers & runs generator
├── sokol_bindings.py       # Auto-generated ctypes bindings
├── main.py                 # Triangle demo application
├── sokol-dll.dll           # Pre-built Sokol DLL (you provide)
├── sokol/                  # Downloaded Sokol headers
│   ├── sokol_app.h
│   ├── sokol_gfx.h
│   ├── sokol_glue.h
│   └── sokol_log.h
└── README.md

Usage

Basic Usage

from sokol.sokol_ahmedaliadeel import *

# Auto-detect platform and load the appropriate library
lib = load_sokol()

# Now use Sokol API
# lib.sg_setup(), lib.sapp_run(), etc.

Explicit Library Path

from sokol.sokol_ahmedaliadeel import load_sokol

# Load a specific library file
lib = load_sokol('/path/to/libsokol.so')

Creating Structs

# All Sokol structs are available as ctypes Structures
desc = sg_desc()
ctypes.memset(ctypes.addressof(desc), 0, ctypes.sizeof(desc))

# Set fields
desc.environment = lib.sglue_environment()

Callbacks

# Use generated function pointer types for callbacks
init_callback = _FuncPtr_init_cb_66(my_init_function)
frame_callback = _FuncPtr_frame_cb_67(my_frame_function)

desc = sapp_desc()
desc.init_cb = init_callback
desc.frame_cb = frame_callback

Vertex Buffers

# Create vertex data
vertices = (ctypes.c_float * 24)(
    # x, y, z, w,    r, g, b, a
    0.0,  0.5, 0.5, 1.0,  1.0, 0.0, 0.0, 1.0,  # top
    0.5, -0.5, 0.5, 1.0,  0.0, 1.0, 0.0, 1.0,  # right
   -0.5, -0.5, 0.5, 1.0,  0.0, 0.0, 1.0, 1.0,  # left
)

# Create buffer
buf_desc = sg_buffer_desc()
buf_desc.data.ptr = ctypes.cast(vertices, ctypes.c_void_p)
buf_desc.data.size = ctypes.sizeof(vertices)
vbuf = lib.sg_make_buffer(ctypes.byref(buf_desc))

Generator Details

The generate_bindings.py script:

1. Parses headers with libclang in combined mode (all headers together for proper dependency resolution)
2. Extracts types:
   • Enums → Python constants
   • Structs → ctypes.Structure subclasses
   • Function pointers → ctypes.CFUNCTYPE types
   • Functions → DLL function bindings with argtypes/restype
3. Handles edge cases:
   • Anonymous structs (filtered out)
   • Nested struct arrays
   • Function pointer fields in structs
   • Proper type ordering for forward declarations

Command Line Usage

# Generate with custom paths
python generate_bindings.py --sokol-dir ./sokol --output sokol_bindings.py

# Specify libclang path (if not auto-detected)
python generate_bindings.py --libclang /path/to/libclang.dll

Sokol Headers

The generator supports these Sokol headers:

Header	Description
sokol_log.h	Logging utilities
sokol_gfx.h	3D graphics API abstraction
sokol_app.h	Application/window handling
sokol_glue.h	Glue between sokol_app and sokol_gfx

Building sokol-dll.dll

If you need to build the DLL yourself:

// sokol_dll.c
#define SOKOL_DLL
#define SOKOL_D3D11
#define SOKOL_NO_ENTRY
#define SOKOL_IMPL
#include "sokol_log.h"
#include "sokol_gfx.h"
#include "sokol_app.h"
#include "sokol_glue.h"

Compile with MSVC:

cl /LD /O2 /DSOKOL_DLL sokol_dll.c /Fe:sokol-dll.dll

License

This binding generator is provided as-is. Sokol itself is licensed under the zlib license - see sokol for details.

Links

• Sokol - Minimal cross-platform standalone C headers
• Sokol Samples - Sample code and examples
• libclang Python - Python bindings for libclang