What a human maintainer inherits

CNA snapshot 3b43bd86  ·  Development › Human Takeover  ·  source links pinned to 3b43bd86

CNA is not one engine library with replaceable window wrappers. At snapshot 3b43bd86 the tree has 23 directories under modules/ (22 declared framework modules plus the renderers/ tree), a separately selected platform, audio transport and renderer identity, 8 physical renderer-family directories serving 10 public renderer identities, an experimental C ABI (0.50.0, 60 public headers), an external C# binding (CNA.NET) maintained in its own repository beside eight archived language bindings kept in CNA Cemetery, and a large conditional build and test graph (900 C++ test source files, 11,927 statically declared GoogleTest-family cases). Those counts describe the scope a reviewer has to cover, not code quality or feature completeness.

The main engineering families

The physical layout is enforced, not conventional. modules/CMakeLists.txt declares the framework modules (_cna_framework_modules) and renderer modules (_cna_renderer_modules) and fails the configure when a translation unit lies outside every declared module's src/, tests/, examples/ or benchmarks/ tree, so a file's directory is its CMake owner. The shared renderer helpers (common/mojoshader and the DirectX 9 effect sub-target inside directx9) are deliberate sharing inside their own directories, not exceptions. Each module is created by cna_add_module as a static library cna_<name> with an alias CNA::<Alias> and exposes only its own include/ root.

Modules that look small or optional — design, diagnostics, media, net, phone and others — are not presumed simple. Each has an internals page in the Development area (for example design, phone, net), written from source reading at this snapshot; none of those pages establishes runtime behaviour on every host. The generated module index is a locator, and the repository map and source-ownership guide explain who owns what. The user-level view of the same layout is Architecture: module layout.

Understand the three backend selections before debugging

Three CMake selections decide which code actually runs, and they are composed by the root CMakeLists.txt from separate files:

The user guides count four axes — these three plus the target operating system — and one switch, CNA_ENABLE_SDL (see Platform support: four separate axes and Architecture: the four build axes); the selection axes index lists every value. The selections are validated separately and have hard exclusions that fail at configure time with a named reason rather than falling back.

Platform selection is not graphics selection. SDL3 hosts the OpenGL contexts and the plain windows that the other GPU renderers draw into, through whichever video driver SDL chose; TERMINAL has no graphical window, so cmake/RendererSelection.cmake refuses every renderer except the CPU-frame identities SOFTWARE, HEADLESS and STUB before any renderer dependency is probed. A physical family may implement several public names: EasyGL serves three GL profiles (OPENGLES3, OPENGL33, WEBGL2) through separate descriptor accessors on one target, and every other family serves one identity. And in a multi-renderer build the default, the selected and the active renderer can differ (runtime renderer selection).

Where small changes have broad effects

The broadest blast radius belongs to a handful of contracts:

• CNA::Platform::IPlatform (IPlatform.hpp) — three implementations; Headless is compiled into every build and Terminal into every POSIX build, whatever CNA_PLATFORM says, so that PlatformConformanceTests.cpp can hold several implementations to one contract in one process;
• IGraphicsRenderer and GraphicsRendererDescriptor (IGraphicsRenderer.hpp, GraphicsRendererDescriptor.hpp) — 8 families;
• GraphicsDevice and GraphicsResource (GraphicsDevice.hpp, GraphicsResource.hpp) — every resource type and every renderer;
• public headers in general, the compiled renderer selection, and the renderer identity table, which exists three times (the CMake list, CNA::GraphicsRendererType in GraphicsRendererType.hpp, and CNA_GRAPHICS_RENDERER_* in CNA/C/graphics.h) and is held together by scripts/check_renderer_identities.py;
• the C ABI's handle and ownership rules.

A one-line virtual signature or disposal-order change may demand edits in all backends, their tests, the fallback logic and the bindings. More local work can live in a specific terminal input decoder, an SDL3 event translation, a specialized content reader or one backend's shader translation — provided the common contract and the serialized format stay unchanged. "Local" must be proved by call search and tests, not inferred from a file name.

Lifecycle-sensitive areas deserve extra care; each of these is visible in the source at this snapshot:

• Game installs its owned platform from the initialiser of its first member, platform_ (InstallPlatform in Game.cpp), so every later member constructor that reaches the ambient platform finds the game's instance; a PlatformInstallation guard undoes the installation if construction throws.
• GraphicsDevice_ is a value member of Game, and the GraphicsDevice constructor runs resolveRenderer(), so the renderer and its window exist before your derived constructor body — long before Initialize.
• Resources register with the device (AddResourceReference) as raw pointers and are not C++-owned by that registry; a resource that outlives its device checks a weak lifetime token (resourceDeviceLifetime_) rather than a dangling pointer.
• GraphicsDevice::Dispose(bool) disposes every registered resource before destroyNativeResources() resets the renderer, so the renderer is still alive while resources release native objects.
• Audio device callbacks can overlap instance destruction; the SDL3-audio harnesses in cmake/Harnesses.cmake exist precisely to destroy a mixer while a voice is active.
• C API handles outlive a single call; HandleRegistry checks generation, object kind and creating thread on every use (the one any-thread lookup serves cna_sound_effect_play and cna_sound_effect_play_with_settings, and a game may opt in to queueing other threads' calls onto its own thread).

The ownership and thread and callback maps make these relationships explicit; the blast-radius page turns them into review questions.

What the repository layout signals

• modules/<name>/include is a module's public or cross-module header boundary; cross-module internal contracts live under some module's include/CNA/Internal/. src/ holds the implementation and module-private headers, and no module adds another module's src/ as an include root. Modules may also own tests/, examples/ and benchmarks/.
• modules/renderers/ contains the physical backends and the shared renderer helpers.
• cmake/ performs selection (PlatformSelection, AudioPlatformSelection, RendererIdentities, RendererSelection, RendererCombinations), registry generation (RendererRegistry), third-party discovery (ThirdParty*.cmake) and test registration (UnitTests, TestHelpers, Harnesses, TestDisplayPolicy).
• Root tests/ holds cross-module suites, fixtures, reference data and assets (OracleCorpusTests.cpp, fixtures/, assets/, reference/, gltf-l7/, interop/); module-local tests belong to their physical owners.
• tools/ and scripts/ contain generators, probes, harness sources and developer checks, not runtime libraries.
• .github/workflows/ shows where a configuration is actually compiled or executed (18 workflow files, 25 jobs; see what CI actually covers).
• third_party/ and vendor/ are dependency boundaries (submodules and vendored code); treat them as external.
• Planning and handoff material — plans/, spikes/, docs/ and the root-level handoff.md, CHECKLIST.md, CNA_ENGINE_REPAIR_HANDOFF.md and CNA_DEMOS_REPAIR_MATRIX.json — can explain a migration, but current implementation and active CMake are authoritative. The audit, remediation, modularization and integration trees of earlier snapshots, the retired misc/ notes and the closed repair handoffs survive only in Git history.

Start with CMakeLists.txt and modules/CMakeLists.txt to see composition (option defaults, selection order, the CNA umbrella target, the ownership gate), then use the generated module inventory to find a physical owner and the physical module dependency map for link edges. This page is deliberately about where responsibility lives; it does not claim that each optional family is mature or tested on every host — renderer coverage is configuration-scoped.