52 lines
2.7 KiB
Markdown
52 lines
2.7 KiB
Markdown
[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.
|