Selection axes index
Evidence basis: source-verified at the pinned commit. Claims on this page were checked by reading the CNA source at commit 009d40f5; unless a sentence says otherwise, nothing here was built or executed. Derived from the CMake registries; whether a given combination builds or runs on a host is not established here.
Generated page. Produced by python3 scripts/generate_dev_reference.py from the Git objects of CNA commit 009d40f5; do not edit it by hand. It is a syntactic inventory: it locates declarations and files, and does not establish behaviour, build success or test results.
CNA composes a build from independent axes: which platform owns the window and events, which audio platform owns the device, and which renderer identity produces pixels. This page lists each axis from the registries that define it, so the counts used across the site have one mechanical source.
Renderer identities and their families
Identities come from cmake/RendererIdentities.cmake (CNA_RENDERER_PUBLIC_IDENTITIES); the C ABI value and C++ enumerator from the canonical table in scripts/check_renderer_identities.py; the identity-to-family map from cmake/RendererRegistry.cmake. The three sources agree (checked at generation time: the generator refuses to write this page if they disagree with each other or with the site's canonical counts). A name outside this set is a configure-time error.
Identity (CNA_GRAPHICS_RENDERER) | C ABI value | C++ enumerator | Implementation family | Descriptor accessor |
|---|---|---|---|---|
SDL_RENDERER | 1 | SdlRenderer | sdl-renderer/ | GetDescriptor |
OPENGLES2 | 2 | OpenGLES2 | easygl/ · internals | GetDescriptorOpenGLES2 |
OPENGLES3 | 3 | OpenGLES3 | easygl/ · internals | GetDescriptorOpenGLES3 |
OPENGL33 | 4 | OpenGL33 | easygl/ · internals | GetDescriptorOpenGL33 |
WEBGL1 | 5 | WebGL1 | easygl/ · internals | GetDescriptorWebGL1 |
WEBGL2 | 6 | WebGL2 | easygl/ · internals | GetDescriptorWebGL2 |
VULKAN | 8 | Vulkan | vulkan/ · internals | GetDescriptor |
WEBGPU | 9 | WebGPU | webgpu/ | GetDescriptor |
HEADLESS | 11 | Headless | headless/ · internals | GetDescriptor |
SOFTWARE | 12 | Software | software/ · internals | GetDescriptor |
STUB | 13 | Stub | stub/ · internals | GetDescriptor |
DIRECTX11 | 14 | DirectX11 | directx11/ | GetDescriptor |
DIRECTX12 | 15 | DirectX12 | directx12/ | GetDescriptor |
DIRECT2D | 16 | Direct2D | direct2d/ | GetDescriptor |
CANVAS | 17 | Canvas | canvas/ | GetDescriptor |
HTML_DOM | 18 | HtmlDom | html-dom/ | GetDescriptor |
FREEDIRECT | 21 | FreeDirect | freedirect/ | GetDescriptor |
DIRECTX9 | 22 | DirectX9 | directx9/ | GetDescriptor |
SDL_GPU | 31 | SdlGpu | sdl-gpu/ · internals | GetDescriptor |
OPENGL4 | 33 | OpenGL4 | opengl4/ · internals | GetDescriptor |
GDI | 40 | Gdi | gdi/ | GetDescriptor |
METAL | 42 | Metal | metal/ | GetDescriptor |
FNA3D | 43 | Fna3d | fna3d/ | GetDescriptor |
SVG_DOM | 44 | SvgDom | svg-dom/ | GetDescriptor |
PORTABLEGL | 46 | PortableGL | portablegl/ | GetDescriptor |
Platform implementations (CNA_PLATFORM)
From cmake/PlatformSelection.cmake. SDL12 and EMSCRIPTEN are reserved identifiers that are refused rather than aliased. Some implementations are host-conditional (Terminal is POSIX-only, Win32 Windows-only, X11 and Wayland need their development packages) and are refused with an explanation rather than replaced by SDL3.
| Value | Role |
|---|---|
SDL3 | default; SDL3 windowing, events and input |
SDL2 | SDL2 windowing, events and input (partial services) |
X11 | native Xlib backend, no SDL; offered only where the X development environment exists |
WAYLAND | native Wayland client, no SDL and no X11 library; offered only where the Wayland development environment exists |
HEADLESS | no window; injected events; conformance and CI role |
TERMINAL | POSIX terminal session (termios); CPU-frame presentation |
WIN32 | native user32/gdi32 backend; offered when the target is Windows |
Audio implementations (CNA_AUDIO_PLATFORM)
From cmake/AudioPlatformSelection.cmake. Reserved and refused: OPENAL, WASAPI. Audio selection is independent of the platform: a headless application may use SDL3 audio, and a graphical one may choose deterministic NULL audio.
| Value | Role |
|---|---|
SDL3 | default; SDL3 device transport with the SDL3_mixer-backed XNA playback engine (defines SOUND_ENABLED) |
SDL2 | SDL2 device transport; no XNA mixer |
NULL | deterministic paced callback transport; no XNA mixer |
ALSA | native Linux backend: libasound loaded at run time, CNA's own mixer (defines SOUND_ENABLED) |
How the axes combine
The axes are validated separately and then together (see cmake/RendererCombinations.cmake and cmake/RendererSelection.cmake); not every combination is valid, and a GPU renderer needs a native window handle that the Headless and Terminal platforms do not provide. Multiple renderer identities can be compiled into one binary through CNA_GRAPHICS_RENDERERS; an API choice beats the CNA_GRAPHICS_RENDERER environment variable, which beats the compiled default. See the renderer selection internals and platform backends.
Deep dives on this topic
Long-form pages that explain the exact semantics, invariants and evidence behind this subject.
- Glossary of XNA and CNA terms — Checked definitions of the XNA and CNA terms used across libcna.com, grouped by subject, each correcting common older readings and linking to the page with the detail.
- The renderer contract: IGraphicsRenderer defaults, factories and failure shapes — Which IGraphicsRenderer bodies a renderer family must write, what each inherited default does to a public call, how null factories fail, and the evidence ladder behind a feature.
Related pages
The same subsystem is explained at four altitudes. These are the neighbouring pages at each one.
- User guide
- Renderers · Platforms · Audio system
- Internals
- Renderer selection internals · Platform backends
- Maintainer workflow
- Source ownership
- Reference
- Module index · CMake option index