Backlog/lib/sdl3/parser/SDL_VIDEO_ANALYSIS.md

SDL_video.h Parsing Analysis

Current Status: ✅ MOSTLY WORKING

The SDL_video.h header parses successfully with only minor missing type warnings. All major functionality is captured.

Statistics

• Total declarations found: 124
  • Opaque types: 2
  • Typedefs: 6
  • Function pointers: 0
  • Enums: 4
  • Structs: 2
  • Flags: 1
  • Functions: 109

Successfully Resolved Dependencies

The parser successfully resolves and imports these types from dependency headers:

✅ SDL_PixelFormat (from SDL_pixels.h) ✅ SDL_Point (from SDL_rect.h) ✅ SDL_Rect (from SDL_rect.h) ✅ SDL_Surface (from SDL_surface.h) ✅ SDL_PropertiesID (from SDL_properties.h)

Missing Type Definitions (7 types)

These types are referenced but not found in the included headers:

1. EGL-Related Types (5 types)

These are OpenGL ES/EGL integration types defined within SDL_video.h itself:

• SDL_EGLConfig - typedef void *SDL_EGLConfig;
• SDL_EGLDisplay - typedef void *SDL_EGLDisplay;
• SDL_EGLSurface - typedef void *SDL_EGLSurface;
• SDL_EGLAttribArrayCallback - Function pointer typedef
• SDL_EGLIntArrayCallback - Function pointer typedef

Root Cause: These are defined in SDL_video.h but the parser's typedef scanner is not picking them up properly.

Issue: The typedef scanner currently only processes simple typedefs and doesn't handle:

• Pointer typedefs (typedef void *Type;)
• Function pointer typedefs with complex signatures

2. OpenGL Types (2 types)

• SDL_GLAttr - Enum type for GL attributes
• SDL_GLContext - typedef struct SDL_GLContextState *SDL_GLContext;

Root Cause: Similar to EGL types - these are typedef'd in SDL_video.h but not captured by the scanner.

3. Callback Types (1 type)

• SDL_HitTest - typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(...);

Root Cause: Function pointer typedef with calling convention modifier.

4. Generic Types (1 type)

• SDL_FunctionPointer - typedef void (SDLCALL *SDL_FunctionPointer)(void);

Root Cause: Function pointer typedef.

Implementation Plan

Phase 1: Enhance Typedef Scanner ✅ PRIORITY

Goal: Make the typedef scanner capture all typedef forms in the same file being parsed.

Tasks:

1. Add pointer typedef support

   typedef void *SDL_EGLConfig;
   typedef struct SDL_GLContextState *SDL_GLContext;
   

   • Pattern: typedef <type> *<name>;
   • Store as opaque pointer type

2. Add function pointer typedef support

   typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, const SDL_Point *area, void *data);
   typedef void (SDLCALL *SDL_FunctionPointer)(void);
   

   • Pattern: typedef <return> (SDLCALL *<name>)(<params>);
   • Store as function pointer type with signature

3. Add enum typedef support

   typedef enum SDL_GLAttr { ... } SDL_GLAttr;
   

   • Pattern: Already handled, but verify it works for GL types

Implementation Location: src/dependency_resolver.zig - scanFileForTypedefs()

Expected Result: After this phase, all 7 missing types should be found and properly typed.

Phase 2: Test and Validate

1. Run parser on SDL_video.h
2. Verify all 14 originally missing types are now resolved (7 from deps, 7 from typedefs)
3. Verify generated Zig code compiles
4. Check that function signatures using these types are correct

Phase 3: Apply to Other Headers

Once SDL_video.h parses completely clean, apply the same pattern to other headers with similar issues.

Error Categories

Category A: Typedef Scanner Limitations ⭐ PRIMARY ISSUE

• Impact: 7/14 missing types (50%)
• Difficulty: Medium
• Files affected: SDL_video.h, potentially others
• Solution: Enhance typedef scanner (Phase 1)

Category B: Cross-header Dependencies ✅ SOLVED

• Impact: 7/14 missing types (50%) - but these work!
• Difficulty: N/A (already working)
• Solution: Existing dependency resolver handles this correctly

Success Metrics

After implementing Phase 1:

• ⬜ Zero "Could not find definition" warnings for SDL_video.h
• ⬜ Generated code compiles without errors
• ⬜ All 124 declarations properly typed
• ⬜ Can use as template for other complex headers

Notes

The current parsing system is quite robust. The main gap is in the typedef scanner not recognizing all forms of typedef. This is a focused, solvable problem that will unlock SDL_video.h and similar headers.