Backlog/lib/sdl3/parser/README.md

SDL3 Header Parser

A Zig tool that automatically generates idiomatic Zig bindings from SDL3 C headers with automatic dependency resolution.

Features

✅ Automatic Dependency Resolution - Detects and extracts missing types from included headers
✅ Multi-Field Struct Parsing - Handles compact C syntax like int x, y;
✅ JSON Output - Export structured JSON representation of all parsed types
✅ Type Conversion - Converts C types to idiomatic Zig types
✅ Method Organization - Groups functions as methods on opaque types
✅ Mock Generation - Creates C stub implementations for testing
✅ Production Ready - 100% dependency resolution for SDL_gpu.h

Quick Start

Installation

cd parser/
zig build          # Build the parser
zig build test     # Run tests

Generate All SDL3 Bindings

# From lib/sdl3 directory
zig build regenerate-zig  # Generates all SDL3 .zig files in v2/

Basic Usage

# Generate single header Zig bindings
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig

# Generate with C mocks for testing
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig --mocks=gpu_mock.c

# Generate JSON representation
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --generate-json=gpu.json

Example Output

Input (SDL_gpu.h):

typedef struct SDL_GPUDevice SDL_GPUDevice;
extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device);

Output (gpu.zig):

pub const GPUDevice = opaque {
    pub inline fn destroyGPUDevice(gpudevice: *GPUDevice) void {
        return c.SDL_DestroyGPUDevice(gpudevice);
    }
};

Supported C Patterns

Type Declarations

• Opaque types: typedef struct SDL_Type SDL_Type;
• Structs: typedef struct { int x, y; } SDL_Rect; (multi-field support!)
• Enums: typedef enum { VALUE1, VALUE2 } SDL_Enum;
• Flags: Bitfield enums with #define values
• Typedefs: typedef Uint32 SDL_PropertiesID;

Functions

• Extern functions: extern SDL_DECLSPEC RetType SDLCALL SDL_Func(...);
• Method grouping: Functions with opaque first parameter become methods

Automatic Type Conversion

C Type	Zig Type
bool	bool
Uint32	u32
int	c_int
SDL_Type*	?*Type
const SDL_Type*	*const Type
void*	?*anyopaque

Dependency Resolution

The parser automatically:

1. Detects types referenced but not defined
2. Searches included headers for definitions
3. Extracts required types
4. Generates unified output with all dependencies

Example:

SDL_gpu.h references SDL_Window
  → Parser finds #include <SDL3/SDL_video.h>
  → Extracts SDL_Window definition
  → Includes in output automatically

Success Rate: 100% for SDL_gpu.h (5/5 dependencies)

Documentation

Start Here: Getting Started Guide

User Guides

• Getting Started - Installation and first steps
• Quickstart - Quick reference
• API Reference - All command-line options

Technical Docs

• Architecture - How the parser works
• Dependency Resolution - Automatic type extraction
• Known Issues - Current limitations

Development

• Development Guide - Contributing and extending
• Roadmap - Future plans

Complete Index

• Documentation Index - All documentation

Project Status

Production Ready ✅

• 45+ SDL3 headers successfully parsed and generated
• All tests passing
• Comprehensive documentation
• Automatic dependency resolution
• JSON export capability

Successfully Generated Headers

All major SDL3 APIs are supported:

Core APIs: audio, camera, clipboard, dialog, events, filesystem, gamepad, gpu, haptic, hints, init, joystick, keyboard, log, mouse, pen, power, properties, rect, render, sensor, storage, surface, time, timer, touch, video

Platform APIs: hidapi, iostream, loadso, locale, messagebox, misc, process, stdinc, system, tray, version, vulkan

Specialized APIs: blendmode, error, guid, iostream, metal, pixels, scancode

Skipped: assert (macro-only), mutex (unsafe primitives), thread (complex concurrency)

See Known Issues for remaining limitations.

Performance

• Small headers (<100 decls): ~100ms
• Large headers (SDL_gpu.h, 169 decls): ~520ms
• Memory usage: ~2-5MB peak
• Output: ~1KB per declaration

Requirements

• Zig 0.15+
• SDL3 headers (included in parent directory)

Examples

Parse a Header

zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig

Use Generated Bindings

const gpu = @import("gpu.zig");

pub fn main() !void {
    const device = gpu.createGPUDevice(true);
    defer if (device) |d| d.destroyGPUDevice();
    
    // All dependency types available automatically
}

Run Tests

zig build test

Contributing

See DEVELOPMENT.md for:

• Architecture overview
• Adding new patterns
• Testing guidelines
• Code style

License

Part of the Backlog game engine project.

Acknowledgments

Developed for automatic SDL3 binding generation in the Backlog engine.

---

Version: 3.0
Status: Production ready - 45+ SDL3 headers supported
Last Updated: 2026-01-23