2.7 KiB
[Reviewed]
ADR-0078: Native client lifecycle and immutable presentation frames
Status
Accepted for M9.2 engineering client; no gameplay or protocol decision.
Context
SDL requires main-thread window/render ownership. A renderer must not retain mutable simulation stores, and DPI changes must not reinterpret world units.
Decision
Use one RAII application with a private SDL implementation, typed expected errors, and a synchronous bounded immutable frame of copied presentation primitives. Separate logical/drawable dimensions and content scale. Suspend rendering for hidden/minimized surfaces. Recreate on recoverable device reset; fail closed on device loss or adapter errors. Document the single-main-thread precondition. The executable owns pacing and exception handling. See CLIENT_ARCHITECTURE.md.
Linux X11 builds set SDL's supported SDL_X11_SHARED=OFF: link X11 libraries
directly rather than repeatedly dlopen/dlclose them with SDL. Repeated init/quit
with dynamic loading left 1,700,544 bytes reported by LeakSanitizer over this
fixture (32 repeated lifecycles, a hidden window and failed renderer initialization). Preloading
libX11 avoided the report; direct linking makes library lifetime explicit without
a preload requirement or sanitizer suppression. This adds system X11 runtime
dependencies when that backend is enabled; headless targets remain unaffected.
Alternatives considered
- Public SDL handles: simple but leaks backend lifetime into callers; rejected.
- Render thread / queued scene graph: unnecessary synchronization and lifetime complexity for this gate; defer until profiling justifies it.
- Renderer directly reads world stores: violates the immutable view boundary.
- Retry every failed frame: risks busy loops and hides fatal failures; rejected.
Benefits
Bounded memory and work, release-active failure tests, no graphical dependencies in headless targets. SDL can be replaced behind private source files.
Costs
Frame copy (bounded), one window, simple rectangles only. Native library/global state precludes embedding another SDL owner in the same process for this scope.
Risks
Synthetic events do not prove a real GPU reset or physical multi-monitor DPI. System driver allocations remain outside owned-code instrumentation. Direct linking addresses the observed unload/lifecycle case, not every platform library leak or arbitrary GPU driver. Re-run repeated native lifecycle checks on upgrades.
Consequences
M9.3 adds camera and input intentions; M9.4/5 add biology-derived projections. No current simulation interfaces, rules or formats change. Desktop packaging, hardware matrix and native driver recovery remain explicit qualification work.