go-gui sdl2 shim - #1

Summary

Adds Go interop layers on top of this Zig-built SDL3 so go-gui (and downstream apps) can target SDL3 directly — no sdl2-compat, no MSYS2/MinGW — and produce single-shared-library or fully static builds.

Three independent pieces, on top of the release-3.4.x SDL 3.4.10 base:

1. go-sdl2-sdl3/sdl — go-sdl2 API shim on SDL3

A cgo drop-in replacement for the subset of github.com/veandco/go-sdl2/sdl that go-gui actually uses (SDL renderer backend, OpenGL backend, sdlkey, and the go-glyph SDL backend). It is published as module github.com/veandco/go-sdl2 so consumers enable it with a single replace github.com/veandco/go-sdl2 => ../SDL/go-sdl2-sdl3.

• Reshapes SDL3's split window-event model and float coordinates back into the SDL2-style API go-gui expects, so backend code compiles and runs unchanged.
• convertEvent folds SDL3's distinct window event types back into SDL2-style WindowEvent subtypes; an //export event-watch is registered once and dispatched through a Go registry (watch.go).
• Links SDL3 from this repo's zig build output. link_dynamic.go (-lSDL3 from zig-out) and link_static.go (-tags sdl3static, from zig-out-static) select linkage.

2. go-sdl2-sdl3/mix — SDL_mixer-compatible audio on SDL3

A small SDL_mixer-API-compatible engine built directly on SDL3's audio API (per-channel auto-mixed SDL_AudioStreams + a music stream), so go-gui's gui/audio builds on SDL3 without SDL_mixer. WAV decodes natively; MP3/OGG via vendored dr_mp3 / stb_vorbis.

3. gosdl3 — generated cgo SDL3 bindings (experimental)

A Zig-comptime bindgen that emits full cgo SDL3 Go bindings (gosdl3/sdl3/sdl3.go) from the SDL3 headers: zig build gentc → translate-c, then zig build gensdl3 → consts + type aliases + function wrappers. Separate from the hand-written shim in (1); useful as a complete generated surface.

Plus supporting build.zig steps and .gitignore entries.

Build / usage

# Dynamic SDL3 (libSDL3 dylib/dll beside the binary):
zig build install_sdl -Dpreferred_linkage=dynamic

# Static SDL3 (for fully static consumer builds, -tags sdl3static):
zig build install_sdl -Dpreferred_linkage=static -Doptimize=ReleaseFast -Dstrip=true --prefix zig-out-static

In the consumer (e.g. go-gui): replace github.com/veandco/go-sdl2 => ../SDL/go-sdl2-sdl3.

How to use it (with go-gui)

Consuming this is a single-line go.mod change on the app side — no go-gui source changes are required. See the companion PR for the exact diff:

→ go-gui/pull/1 changes: https://github.com/cataggar/go-gui/pull/1/changes

Steps:

1. Check out this repo as a sibling of go-gui:

   <parent>/
     go-gui/   (consumer)
     SDL/      (this repo, branch go-gui — SDL3 + the go-sdl2-sdl3 shim)
   

2. Build SDL3 here (dynamic or static, see above).
3. In go-gui's go.mod, point the go-sdl2 dependency at the shim (this is the entire change in build: render and play audio on SDL3 via the go-sdl2-sdl3 shim go-gui#1):

   replace github.com/veandco/go-sdl2 => ../SDL/go-sdl2-sdl3
   

4. Build go-gui with CC="zig cc". The SDL renderer backend, OpenGL backend, sdlkey, and gui/audio then compile and run unchanged on SDL3.

Notes

• This branch carries Go code inside the SDL tree intentionally, so the shim, the static SDL3, and the consumer can be built from one checkout.
• No upstream SDL C sources are modified; all additions live under go-sdl2-sdl3/ and gosdl3/.

Verified: go-gui's headless tests and the SDL renderer + OpenGL backends build and run against this shim; go-gui's gui/audio builds against mix.