Selection axes index

CNA snapshot c1c316b9 · Development › Generated References · source links pinned to c1c316b9

✓

Evidence basis: source-verified at the pinned commit. Claims on this page were checked by reading the CNA source at commit c1c316b9; 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 c1c316b9; 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.

14 public renderer identities12 implementation families3 platform implementations3 audio implementations

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`
`OPENGLES3`	3	`OpenGLES3`	`easygl/` · internals	`GetDescriptorOpenGLES3`
`OPENGL33`	4	`OpenGL33`	`easygl/` · internals	`GetDescriptorOpenGL33`
`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`
`DIRECTX9`	22	`DirectX9`	`directx9/`	`GetDescriptor`
`SDL_GPU`	31	`SdlGpu`	`sdl-gpu/` · internals	`GetDescriptor`
`METAL`	42	`Metal`	`metal/`	`GetDescriptor`
`FNA3D`	43	`Fna3d`	`fna3d/`	`GetDescriptor`

Platform implementations (`CNA_PLATFORM`)

From cmake/PlatformSelection.cmake. SDL12 and EMSCRIPTEN are reserved identifiers that are refused rather than aliased. SDL3 and HEADLESS are offered on every host. Only TERMINAL is host-conditional: it is built on termios, so on a Windows host it is reserved and refused with an explanation rather than replaced by SDL3. Windows is a host environment, not an implementation, and X11 and Wayland are display environments: SDL3 reaches all three through SDL’s own video drivers, so whatever is host- or driver-specific lives inside SDL, while HEADLESS opens no window at all. The values WIN32, X11 and WAYLAND are refused by name, with a message that says to configure SDL3.

Value	Role
`SDL3`	default, on every host; CNA's one windowing implementation: SDL's own video drivers reach Windows, X11, Wayland, macOS, iOS, Android and the browser, and the renderer receives the native handle through `IPlatformWindow::GetNativeHandle()`
`HEADLESS`	on every host; no window; injected events; conformance and CI role
`TERMINAL`	POSIX hosts only (termios); CPU-frame presentation

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`)
`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.

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