Development

CNA snapshot 009d40f5  ·  Development › Development home  ·  source links pinned to 009d40f5

The Development area is the maintainer layer of libcna.com: how CNA is put together, where each behaviour is owned, how to change it safely, and what evidence a change needs. It is written for a human C++ engineer who has to own CNA — including after heavy AI-assisted development — and it stays pinned to one exact source snapshot so every claim can be checked.

Four altitudes, one subsystem

The same subsystem is explained at four different altitudes on this site. They are deliberately separate pages: mixing them makes a guide too heavy for a user and an internals page too vague for a maintainer.

Every Internals and Handbook page ends with a Related pages block that links its neighbours at the other altitudes.

Choose a path

The shortest useful mental model

Your Game / public CNA API
          │
          ▼
 runtime/Game ── coordinates time, events, Update and Draw
    │       │
    │       └── graphics/GraphicsDevice ── selected renderer implementation
    │                                      │
    └── platform/IPlatform ────────────────┘
          │       │                         window/surface services
          │       ├── input snapshots
          │       ├── audio platform
          │       └── timing / events / windows
          ▼
      host OS / SDL / headless / terminal

CNA is not one monolithic “backend”. A build chooses a platform (CNA_PLATFORM, 7 implementations), an audio platform (CNA_AUDIO_PLATFORM, 4) and a graphics renderer (CNA_GRAPHICS_RENDERER, 25 public identities over 21 implementation families) independently. The runtime owns orchestration; concrete backends own OS and GPU work. The canonical maintainer model adds the other control paths and the places where the dependency graph is intentionally not acyclic. The three axes are tabulated, straight from the CMake registries, in the selection axes index.

Evidence policy: what these pages do and do not claim

Every architectural claim in this area is tied to a path or symbol in the CNA source at one exact commit, 009d40f5 (branch next, 24 September 2026). Source links carry the full commit hash, never a moving branch; the generated inventories are rebuilt from the Git objects of that commit. Where the source does not establish something, the page says so.

Each page states its evidence basis under the title, using distinct terms that are never silently upgraded into one another:

“The implementation exists” is not “the behaviour is proven correct everywhere”. A page that says a backend was traced from construction to teardown does not say it passes on every driver or host.

Three anchors to start from when you want to check a claim yourself:

• Production modules — the 23 physical module directories.
• Physical module contract — CNA’s own statement of what a module is and how CMake partitions it.
• Renderer identities — the public identity list every count on this site is derived from.

What is covered in depth, and what is not

The Development area is a maintainer manual, not a full catalogue, and its depth is uneven by design. A subsystem without a dedicated internals page has simply not been given a deep tour here; that says nothing about how mature it is in CNA. The module index shows, for every module and every renderer directory, whether a dedicated internals page exists.

• Toured in depth: runtime lifecycle; GraphicsDevice, renderer selection and the indexed-draw path; the EasyGL, OpenGL4, Vulkan, SDL_gpu, Software, Headless and Stub renderer families; all seven platform backends; the audio engine; ContentManager and the Content Pipeline; input events; fourteen further modules (core, math, design, storage, media, FFmpeg video, devices, device host services, diagnostics, inspector, phone, gamer services, graphics extensions, networking); the C API and the C#, Java and Python bindings.
• Not yet given a dedicated internals page: the remaining renderer families (WebGPU, DirectX 9/11/12, Direct2D, Metal, PortableGL, GDI, FNA3D, the DOM/canvas family, FreeDirect, SDL_Renderer) and the shared renderer helpers; the controller/joystick and touch input paths; the Rust, TypeScript, Swift, Go and Ruby bindings; the tooling and source-audit scripts. The user-facing Renderers guide covers those renderer families from the user’s side.

Pin policy

These pages describe CNA at 009d40f5; CNA moves faster than the pages. Before trusting a trace for a new patch, compare your branch with that snapshot and re-audit the changed paths, as described on Maintenance & pin policy. The user-facing documentation is pinned to the same commit.