sdlparser-scrap/docs/API_REFERENCE.md

API Reference

Complete reference for the SDL3 header parser command-line interface.

Command Syntax

zig build run -- <header_file> [options]

Arguments

Required

<header_file> - Path to SDL C header file

Examples:

zig build run -- ../SDL/include/SDL3/SDL_gpu.h
zig build run -- /full/path/to/SDL_video.h
zig build run -- relative/path/to/header.h

Optional

--output=<file> - Write output to file instead of stdout

Examples:

--output=gpu.zig
--output=bindings/video.zig
--output=/tmp/test.zig

--mocks=<file> - Generate C mock implementations

Examples:

--mocks=gpu_mock.c
--mocks=test/mocks.c

--generate-json=<file> - Generate JSON representation of parsed types

Examples:

--generate-json=gpu.json
--generate-json=api/types.json

Output Formats

Zig Bindings (Default)

Generated when --output is specified (or to stdout if not):

pub const c = @import("c.zig").c;

pub const GPUDevice = opaque {
    pub inline fn createGPUDevice(debug_mode: bool) ?*GPUDevice {
        return c.SDL_CreateGPUDevice(debug_mode);
    }
};

Features:

• Type conversions (C → Zig)
• Method organization
• Dependency inclusion
• Doc comments preserved

C Mocks (Optional)

Generated when --mocks is specified:

// Auto-generated C mock implementations
#include <SDL3/SDL_gpu.h>

SDL_GPUDevice* SDL_CreateGPUDevice(bool debug_mode) {
    return NULL;  // Mock: always returns null
}

void SDL_DestroyGPUDevice(SDL_GPUDevice *device) {
    // Mock: no-op
}

Use Case: Testing without real SDL implementation

JSON Output (Optional)

Generated when --generate-json is specified:

{
  "header": "SDL_gpu.h",
  "opaque_types": [
    {"name": "SDL_GPUDevice"}
  ],
  "typedefs": [
    {"name": "SDL_PropertiesID", "underlying_type": "Uint32"}
  ],
  "enums": [
    {
      "name": "SDL_GPUPrimitiveType",
      "values": [
        {"name": "SDL_GPU_PRIMITIVETYPE_TRIANGLELIST"},
        {"name": "SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP"}
      ]
    }
  ],
  "structs": [
    {
      "name": "SDL_GPUViewport",
      "fields": [
        {"name": "x", "type": "float"},
        {"name": "y", "type": "float"}
      ]
    }
  ],
  "functions": [
    {
      "name": "SDL_CreateGPUDevice",
      "return_type": "SDL_GPUDevice*",
      "parameters": [
        {"name": "debug_mode", "type": "bool"}
      ]
    }
  ]
}

Use Cases:

• API documentation generation
• Schema validation
• Cross-language binding generation
• Type introspection tools

Build System Integration

In build.zig

const parser_dep = b.dependency("sdl3_parser", .{
    .target = target,
    .optimize = optimize,
});
const parser_exe = parser_dep.artifact("sdl-parser");

const gen = b.addRunArtifact(parser_exe);
gen.addFileArg(b.path("SDL/include/SDL3/SDL_gpu.h"));
gen.addArg("--output=src/gpu.zig");

const gen_step = b.step("generate", "Generate SDL bindings");
gen_step.dependOn(&gen.step);

Then run:

zig build generate

Parser Behavior

Dependency Resolution

Automatic - No configuration needed

When the parser detects missing types, it:

1. Parses #include directives from the header
2. Searches each included header
3. Extracts matching type definitions
4. Includes them in the output

Progress Reporting:

Analyzing dependencies...
Found 5 missing types:
  - SDL_Window
  - SDL_Rect
  ...

Resolving dependencies...
  ✓ Found SDL_Window in SDL_video.h
  ✓ Found SDL_Rect in SDL_rect.h

Type Filtering

Only SDL types are processed:

• Types starting with SDL_
• Known SDL types (Window, Rect, etc.)

Primitive types are ignored:

• bool, int, float, void, etc.

Pattern Matching Order

Patterns are tried in this order:

1. Opaque types (typedef struct X X;)
2. Enums (typedef enum {...} X;)
3. Structs (typedef struct {...} X;)
4. Flags (typedef Uint32 SDL_Flags; + #define values)
5. Typedefs (typedef Type SDL_Alias;)
6. Functions (extern SDL_DECLSPEC ...)

Note: Order matters! Flags must be tried before simple typedefs.

Naming Conventions

Types:

• SDL_GPUDevice → GPUDevice (strip SDL_ prefix)
• SDL_GPU_PRIMITIVE_TYPE → GPUPrimitiveType (remove first underscore)

Functions:

• SDL_CreateGPUDevice → createGPUDevice (strip SDL_, camelCase)

Enum Values:

• SDL_GPU_PRIMITIVETYPE_TRIANGLELIST → primitiveTypeTrianglelist

Parameters:

• SDL_GPUDevice *device → device: ?*GPUDevice

Exit Codes

• 0 - Success
• 1 - Error (file not found, out of memory, invalid arguments)

Console Output

Normal Operation

SDL3 Header Parser
==================

Parsing: header.h

Found N declarations
  - Opaque types: X
  - Typedefs: X
  - Enums: X
  - Structs: X
  - Flags: X
  - Functions: X

Analyzing dependencies...
[dependency information]

Generated: output.zig

File is still written, but may need manual fixes.

Type Conversion Reference

Integer Types

C Type	Zig Type
Uint8	u8
Uint16	u16
Uint32	u32
Uint64	u64
Sint8	i8
Sint16	i16
Sint32	i32
Sint64	i64
int	c_int
unsigned int	c_uint
size_t	usize

Pointer Types

C Type	Zig Type
SDL_Type*	?*Type (nullable)
const SDL_Type*	*const Type
SDL_Type**	?*?*Type
void*	?*anyopaque
const void*	*const anyopaque
const char*	[*c]const u8

Special Types

C Type	Zig Type
bool	bool
float	f32
double	f64
size_t	usize

Examples

Example

Input (depends.h):

#include <SDL3/SDL_rect.h>

extern void SDL_UseRect(SDL_Rect *rect);

Command:

zig build run -- depends.h --output=depends.zig

Output:

pub const c = @import("c.zig").c;

// Dependency automatically included
pub const Rect = extern struct {
    x: c_int,
    y: c_int,
    w: c_int,
    h: c_int,
};

pub inline fn useRect(rect: *Rect) void {
    return c.SDL_UseRect(rect);
}

Mocks example

Command:

zig build run -- simple.h --output=thing.zig --mocks=thing_mock.c

Output (thing_mock.c):

#include <SDL3/SDL.h>

SDL_ThingID SDL_CreateThing(void) {
    return 0;
}

void SDL_DestroyThing(SDL_Thing *thing) {
    // No-op
}