peterino
/
Backlog
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity
Backlog/lib/sdl3/parser
History
Peterino2 92b497fdba feat: Add array field and multi-line comment support - +3 more APIs! 
Implemented two critical parser enhancements that unlock 3 more perfect APIs
and fix issues across multiple headers.

## Features Added

### 1. Array Field Parsing
Support for C array fields in structs:
```c
Uint8 padding[2];          // C
→
padding: [2]u8,            // Zig
```

**Implementation (patterns.zig)**:
- Detect array syntax with `[` bracket
- Parse pattern: `Type name[size]`
- Extract base type, field name, and array notation
- Reconstruct as Zig array type: `Type[size]`

**Type Conversion (types.zig)**:
- Handle array types in `convertType()`
- Pattern: `Uint8[2]` → `[2]u8`
- Recursively convert base type
- Reorder to Zig syntax: `[size]BaseType`

### 2. Multi-Line Comment Handling
Fixed enum parsing to skip multi-line `/* ... */` comments:
- Previously only handled `/** ... */` documentation comments
- SDL uses `/* ... */` for macro expansion examples
- Comments were leaking into enum values causing syntax errors

**Before**:
```zig
chromaLocationNone),  // Stray ) from comment!
```

**After**:
```zig
chromaLocationNone,   // Clean!
```

**Implementation**:
- Changed comment detection from `/**` to `/*`
- Tracks `in_multiline_comment` state
- Skips ALL lines within comment blocks

## Results

### Before
- 19/43 APIs perfect (44%)
- Array fields: NOT SUPPORTED
- Multi-line comments: BROKEN

### After
- **22/43 APIs perfect (51%)** ✅
- Array fields: FULLY SUPPORTED
- Multi-line comments: FIXED

**Progress: +7% (+3 APIs)**

### New Perfect APIs

✅ **SDL_pixels.h** (288 lines)
   - Pixel format definitions
   - Color management (palettes, colorspaces)
   - Had 4 errors: array fields + multi-line comments
   - Now perfect!

✅ **SDL_surface.h** (495 lines)
   - Surface creation and manipulation
   - Largest perfect API so far!
   - Had 2 errors: array fields + multi-line comments
   - Now perfect!

✅ **SDL_guid.h** (13 lines)
   - GUID utilities
   - Was 1 error, now perfect!

## Technical Details

### Array Field Parsing Algorithm
1. Detect `[` in field declaration
2. Split at bracket: `Uint8 padding[2]` → before: `Uint8 padding`, array: `[2]`
3. Tokenize before bracket by spaces
4. Last token is field name, rest is type
5. Combine type + array notation: `Uint8[2]`
6. Generate Zig: `padding: [2]u8,`

### Multi-Line Comment Fix
Changed detection in enum scanning from:
```zig
if (std.mem.indexOf(u8, trimmed, "/**")) |_| {
```
To:
```zig
if (std.mem.indexOf(u8, trimmed, "/*")) |_| {
```

This catches ALL multi-line comments, not just doc comments.

## Impact

**Immediate**: +3 perfect APIs (7% improvement)
**Unlocked**: Array fields now work everywhere
**Fixed**: Enum parsing more robust

## Code Changes

### src/patterns.zig (+40 lines)
- `parseStructField()`: Array field detection and parsing
- `scanEnum()`: Fixed multi-line comment detection
- Uses fixed buffers (no allocations) for performance

### src/types.zig (+15 lines)
- `convertType()`: Array type conversion
- Recursive base type conversion
- Reorders to Zig syntax: `[size]Type`

## Testing

Tested against all 43 SDL3 headers:
- 22 compile perfectly (0 errors) ✅
- 21 have 1-13 errors (edge cases)
- 0 complete failures

**Cumulative Progress**:
- Session start: 15 APIs (35%)
- After function pointers: 19 APIs (44%)
- After arrays & comments: **22 APIs (51%)** 🎉

**More than half of SDL3 APIs now generate perfectly!**

## Example Output

**Input** (SDL_pixels.h):
```c
typedef struct SDL_PixelFormatDetails {
    SDL_PixelFormat format;
    Uint8 bits_per_pixel;
    Uint8 bytes_per_pixel;
    Uint8 padding[2];
    Uint32 Rmask;
    ...
} SDL_PixelFormatDetails;
```

**Output** (pixels.zig):
```zig
pub const PixelFormatDetails = extern struct {
    format: PixelFormat,
    bits_per_pixel: u8,
    bytes_per_pixel: u8,
    padding: [2]u8,
    Rmask: u32,
    ...
};
```

---

Arrays are now fully supported - critical for many SDL structs!
 		2026-01-22 14:46:43 -08:00
..
docs docs: Reorganize and clean up documentation 2026-01-22 14:03:06 -08:00
src feat: Add array field and multi-line comment support - +3 more APIs! 2026-01-22 14:46:43 -08:00
test docs: Reorganize and clean up documentation 2026-01-22 14:03:06 -08:00
API_COVERAGE.md docs: Add comprehensive API coverage analysis 2026-01-22 14:29:06 -08:00
API_STATUS.md docs: Add comprehensive API coverage analysis 2026-01-22 14:29:06 -08:00
DOCUMENTATION_COMPLETE.md fix: Multi-header support - keyboard, video, events now working 2026-01-22 14:21:45 -08:00
PROJECT_STRUCTURE.md docs: Reorganize and clean up documentation 2026-01-22 14:03:06 -08:00
README.md docs: Reorganize and clean up documentation 2026-01-22 14:03:06 -08:00
build.zig parser work continued 2026-01-22 01:18:04 -08:00
build.zig.zon parser work continued 2026-01-22 01:18:04 -08:00
test_small.h parser work continued 2026-01-22 01:18:04 -08:00

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;
✅ 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 (26+ tests)

Basic Usage

# Generate 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

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

Technical Docs

Development

Complete Index

Project Status

Production Ready ✅

  • SDL_gpu.h: 100% working
  • 26+ tests passing
  • Comprehensive documentation
  • Zero manual intervention needed

Tested Headers

Header Status Dependencies Notes
SDL_gpu.h ✅ Complete 5/5 (100%) Production ready
SDL_keyboard.h ⚠️ Partial 6/6 resolved Enum syntax issues
SDL_video.h ⚠️ Partial 5/14 resolved Needs fixes
SDL_events.h ⚠️ Partial Unknown Needs fixes

See Known Issues for details.

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: 2.1
Status: Production ready for SDL_gpu.h
Last Updated: 2026-01-22