What a human maintainer inherits

CNA snapshot 009d40f5  ·  Development › Human Takeover  ·  source links pinned to 009d40f5

CNA is not one engine library with replaceable window wrappers. At snapshot 009d40f5 the tree has 23 directories under modules/ (22 declared framework modules plus the renderers/ tree), a separately selected platform, audio transport and renderer identity, 21 physical renderer-family directories serving 25 public renderer identities, an experimental C ABI (0.29.0, 61 public headers), eight external language bindings in other repositories, and a large conditional build and test graph (904 C++ test source files, 12,610 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 one documented exception is the GDI renderer compiling eight software-module 2D translation units; their physical owner stays software. 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 can host Vulkan or SDL_gpu; native X11 and Wayland expose their own GL-context and Vulkan-surface services; TERMINAL has no graphical window, so cmake/RendererSelection.cmake refuses every renderer except the CPU-frame identities SOFTWARE, PORTABLEGL, HEADLESS and STUB before any renderer dependency is probed. A physical family may implement several public names: EasyGL serves five GL profiles (OPENGLES2, OPENGLES3, OPENGL33, WEBGL1, WEBGL2) through separate descriptor accessors on one target, while OPENGL4 is a family of its own. 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) — seven 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) — 21 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, X11 event translator, 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 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 (20 workflow files, 28 jobs; see what CI actually covers).
• third_party/ and vendor/ are dependency boundaries (submodules and vendored code); treat them as external.
• Historical material — plans/, plan/, spikes/, audit/, remediation/, modularization/, integration/, docs/ and the root-level NEXT*.md, TODO.md and handoff notes — can explain a migration, but current implementation and active CMake are authoritative.

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.