# m2SDL3 summary — v0.1.0 (2026-09-24)

SDL3 bindings for GNU Modula-2 (`gm2` 16.0.1, SDL 3.4.16, Linux).
All builds verified with `make`; tests and showcases also pass
headless via `SDL_VIDEODRIVER=dummy`.

Upstream SDL sources in `SDL-release-3.4.16/` are a read-only
reference (prebuilt `build/libSDL3.so` used for linking) and are
*not* committed — per its `AGENTS.md` no AI-generated code is
contributed upstream. The binding is original work that only uses
SDL headers at compile time.

## v0.1.0 — starter set + renderer + showcases

- `src/SDL3.def` — init/quit, `GetError`, delay, 64-bit ticks,
  perf counter. SDL3 returns C `bool`, hence `BOOLEAN` results;
  `SDL_INIT_TIMER`/`EVERYTHING` gone, `GAMEPAD` renamed, `CAMERA` new
- `src/SDL3Version.def` — `SDL_GetVersion(): INTEGER` versionnum
  (`major*1000000+minor*1000+micro`), `GetRevision`
- `src/SDL3Video.def` — opaque `WindowHandle`,
  `CreateWindow(title, w, h, flags: LONGCARD)` (no x/y),
  title/size/position/show/hide (`[ BOOLEAN ]`), 64-bit flag constants
- `src/SDL3Events.def` — opaque 128-byte event pump (`PumpEvents`,
  `PollEvent`, `WaitEvent`, `WaitEventTimeout`, `PushEvent`,
  `HasEvent(s)`), quit/key/mouse ids plus `EventWindowCloseRequested`
- `src/SDL3Rect.def/.mod` — pure-M2 `SDLPoint`/`SDLFPoint`/`SDLRect`/
  `SDLFRect` + helpers (`SHORTREAL` = C float, verified vs C caller)
- `src/SDL3Render.def` — `<SDL_render.h>` subset: `CreateRenderer`
  (name or `NIL`), `CreateWindowAndRenderer` (title form, `BOOLEAN`),
  draw color (+float), logical presentation, clear/present,
  points/lines/rects in single (`VAR`) and array (`ADR` + count)
  forms, render scale, output size, debug text
- `src/SDL3Key.def/.mod` — pure-M2 keycode constants (unchanged values)
- `lib/SDL3Utils.def/.mod` — `CStrToM2`, `GetErrorString`,
  `VersionMajor/Minor/Micro`, `PollM2Event` (keycode at offset 28,
  verified with `offsetof`; `QUIT` + `WINDOW_CLOSE_REQUESTED` -> quit),
  `DrainEvents`
- `tests/` — init, version, rect, window, key + `run_tests.sh` (5/5 green)
- `examples/` — `hello_window`, `version`, `event_loop`, `renderer_demo`
- `showcases/` — ports of SDL `examples/renderer/` + `examples/demo/`
  (public domain): `showcase_clear` (01), `showcase_primitives` (02),
  `showcase_lines` (03), `showcase_points` (04),
  `showcase_rectangles` (05), `showcase_debug_text` (18),
  `showcase_snake` (demo 01); SDL3 is native here, adaptations noted
  in each header (callback flattening, `rand`/`randf`, ASCII text,
  counter instead of varargs `RenderDebugTextFormat`)
- `Makefile` — links the local `SDL-release-3.4.16/build/libSDL3.so`
  with `rpath`; `make check` runs the test suite

## GM2 FFI rules learned (encoded in code)

1. `DEFINITION MODULE FOR "C"` + `EXPORT UNQUALIFIED`, link `-lSDL3`.
2. No `*)` inside `(* *)` comments — C pointer spellings need a space.
3. `BOOLEAN` <-> C `bool`, `CARDINAL` <-> Uint32, `LONGCARD` <-> Uint64,
   `INTEGER` <-> int, `SHORTREAL` <-> float (`REAL` is double).
4. Ignorable C-`bool` results need `[ BOOLEAN ]` to call as statements.
5. Opaque pointers = `ADDRESS`, `ARRAY OF CHAR` params = `char *`,
   `VAR` record params = `T *`, arrays = `ADR` + count.
6. Same-size casts only: `SHORTREAL(real-expr)` fails, use
   `VAL(SHORTREAL, ...)`.
7. Pure-M2 helpers compile with `gm2 -c` to `.o`, then link.
8. Window-close buttons yield `WINDOW_CLOSE_REQUESTED`, not `QUIT` —
   handle both (done in `DrainEvents`/`PollM2Event`).

## Next

Texture/surface subset, audio streams, gamepad/joystick, typed
`SDL_Event` variant record, then `infinite-monkeys` and further demos.