76 lines
4.8 KiB
Markdown
76 lines
4.8 KiB
Markdown
# ADR-0077: Scoped native 2D client dependencies
|
|
|
|
## Status
|
|
Accepted for M9.1's isolated probe and M9 engineering client. No final 3D renderer,
|
|
audio, UI toolkit, physics engine or transport is selected here.
|
|
|
|
## Context
|
|
M9 needs a native Windows/Linux window, input events and simple 2D primitives.
|
|
The headless libraries must configure, build and run without graphical dependencies.
|
|
M6 views already expose immutable value data; no SDL types belong in those APIs.
|
|
|
|
## Decision
|
|
Use SDL **3.4.16**, zlib licensed, for window/events and `SDL_Renderer`. Build a
|
|
shared library from an explicitly prepared SHA-256-pinned upstream source archive.
|
|
`tools/sdl3-pin.cmake` is the machine-readable pin. Normal CMake configuration
|
|
never downloads it. The dependency and `evo-client-probe` are opt-in; only the
|
|
probe links SDL at M9.1. ADR-0078 extends this to the M9.2 platform adapter and
|
|
its native tests, with direct X11 linking on Linux for lifecycle correctness.
|
|
|
|
Select SDL's small 2D abstraction rather than direct Vulkan for this scope. Retain
|
|
its platform renderer selection and allow the probe to explicitly request Vulkan,
|
|
Direct3D11 or software without silently substituting another backend. Disable
|
|
unused audio, camera, joystick, haptic, sensor and SDL_GPU subsystems. Keyboard and
|
|
mouse events remain. Audio and final UI are explicitly deferred.
|
|
|
|
This is a scoped amendment to ADR-0003, following the explicit-source approach
|
|
already used for PostgreSQL: do not require adoption of a general package manager
|
|
for one self-contained client dependency. vcpkg/Conan measured comparison remains
|
|
open before a broader dependency graph. No claim is made that either was benchmarked.
|
|
Archive preparation can use an existing verified download for offline rebuilds.
|
|
|
|
## Alternatives considered
|
|
| Option | Value | Cost / disposition |
|
|
|---|---|---|
|
|
| SDL3 + direct Vulkan | Explicit resource/synchronization control and future compute | Swapchain, shaders, pipeline and allocator work exceeds this 2D gate; defer to measured need / M13 |
|
|
| SDL3 + SDL_GPU | Portable explicit GPU API with shader pipelines | Shader build/distribution and more resource lifetime work; useful later, not required for basic views |
|
|
| SDL3 + SDL_Renderer | Window/events plus accelerated primitives and textures from one dependency | Less pipeline control; selected for scoped 2D client, not a permanent engine-wide abstraction |
|
|
| GLFW + Vulkan | Narrow window/input layer | Still needs the renderer work above and another dependency choice; no demonstrated M9 advantage |
|
|
| vcpkg manifest | Baselines/features and strong CMake/MSVC integration | Broader tool bootstrap/registry governance for one archive; remains a candidate |
|
|
| Conan lockfile | Profiles, binary packages and revision locks | Python/recipe/tool bootstrap and profile governance; remains a candidate |
|
|
|
|
These are scope/maintenance comparisons, not measured performance rankings.
|
|
The probe records actual backend, SDL version and execution result; size/build
|
|
measurements and platform limits belong in the M9.1 validation record.
|
|
|
|
## Benefits
|
|
One established C API with explicit return checks, uncomplicated RAII adapters and
|
|
small review surface for generated C++. No engine dependency and no changes to
|
|
simulation rules, formats or public headers. Software rendering permits CI pixel
|
|
checks without pretending to test a GPU driver.
|
|
|
|
## Costs
|
|
Shared-library packaging and license retention; platform-specific SDL build options
|
|
and system video libraries. Main-thread event/render calls. A later renderer may
|
|
replace the private adapter rather than inherit an unsuitable 2D abstraction.
|
|
|
|
## Risks
|
|
Backend-dependent pixels/performance, driver availability, DPI/event differences,
|
|
untrusted asset decoders and dependency updates. Synthetic event injection proves
|
|
queue plumbing only; actual keyboard/focus/DPI acceptance stays in M9.2/M9.3.
|
|
No user assets are decoded by this probe. Retain upstream third-party notices
|
|
alongside the SDL license for distribution; audit the enabled build at packaging.
|
|
|
|
## Consequences and evidence
|
|
Preparation is explicit; missing sources fail with instructions. An ordinary
|
|
headless configure never evaluates SDL. Upgrades change version and hash together,
|
|
rerun platform probes and review upstream changes. Client rendering is approximate
|
|
presentation, never authoritative biological state.
|
|
|
|
Primary sources checked 2026-10-01:
|
|
- [SDL 3.4.16 release](https://github.com/libsdl-org/SDL/releases/tag/release-3.4.16): stable bugfix release, active release maintenance.
|
|
- [SDL 2D API](https://wiki.libsdl.org/SDL3/CategoryRender): primitives/textures and main-thread requirement.
|
|
- [SDL GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU): alternative explicit pipeline API.
|
|
- License/build/platform documentation is retained in the pinned source archive
|
|
(`LICENSE.txt`, `docs/README-cmake.md`, `docs/README-platforms.md`).
|