Tutorial 127: Choose Platform, Renderer, and Audio Independently

CNA Tutorials  ·  CNA 0.1.0-alpha.1

ℹ

Core idea: alpha.1 has four different axes: target operating system, host platform implementation, graphics renderer, and audio implementation. “Backend” is too ambiguous to stand in for all four.

The three CMake selections

VariableImplemented valuesDefault
CNA_PLATFORMSDL3, SDL2, HEADLESS, TERMINALSDL3
CNA_GRAPHICS_RENDEREROne of 50 public identitiesOS-dependent
CNA_AUDIO_PLATFORMSDL3, SDL2, NULLSDL3

CNA_PLATFORM owns window, events, input, timing and host services. The renderer produces pixels. CNA_AUDIO_PLATFORM chooses the audio-device integration boundary. The compiler/toolchain still decides Linux, Windows, macOS, Emscripten, Android or iOS separately.

⚠

The three audio choices do not offer the same XNA feature set. Alpha.1 defines SOUND_ENABLED only for SDL3, whose SDL3_mixer engine backs SoundEffect, MediaPlayer, decoding, XACT and recording. SDL2 and Null provide real low-level IAudioDevice implementations, but the non-SDL3 build omits that high-level mixer engine. Choose them for platform/device-boundary work, not as drop-in production playback replacements.

Useful configurations

Default desktop host and audio, explicit renderer

cmake -S ../cna -B build-desktop \
  -DCNA_PLATFORM=SDL3 \
  -DCNA_GRAPHICS_RENDERER=OPENGLES3 \
  -DCNA_AUDIO_PLATFORM=SDL3

Entirely SDL2 host/device boundary with a non-SDL-direct renderer

cmake -S ../cna -B build-sdl2 \
  -DCNA_PLATFORM=SDL2 \
  -DCNA_GRAPHICS_RENDERER=OPENGLES3 \
  -DCNA_AUDIO_PLATFORM=SDL2

When both platform and audio are SDL2, CMake refuses SDL_RENDERER, SDL_GPU, FNA3D and FREEDIRECT, because those families link SDL3 directly. The configure fails instead of mixing SDL generations in one process.

No display and no high-level sound engine

cmake -S ../cna -B build-headless \
  -DCNA_PLATFORM=HEADLESS \
  -DCNA_GRAPHICS_RENDERER=HEADLESS \
  -DCNA_AUDIO_PLATFORM=NULL

This is useful for game-logic CI and servers. A headless platform does not secretly force null audio: choose SDL3 audio if the process should still play sound.

POSIX terminal presentation

cmake -S ../cna -B build-terminal \
  -DCNA_PLATFORM=TERMINAL \
  -DCNA_GRAPHICS_RENDERER=SOFTWARE \
  -DCNA_AUDIO_PLATFORM=NULL

TERMINAL is POSIX-only and accepts CPU/no-output renderers: Software, Skia, Blend2D, PortableGL, Headless or Stub. It is not an implemented Windows-console mode.

Reserved names are not support claims

SDL12, WIN32 and EMSCRIPTEN are reserved platform identifiers; OPENAL, WASAPI and ALSA are reserved audio identifiers. Alpha.1 rejects all of them. Emscripten as a target OS/toolchain is real, but it is not a CNA_PLATFORM=EMSCRIPTEN implementation.

Verify the configured axes

cmake -LA -N build-headless | grep -E 'CNA_(PLATFORM|GRAPHICS_RENDERER|AUDIO_PLATFORM)'
ctest --test-dir build-headless -N

The generated test inventory changes with all three selections and feature options. Report the values beside test results; a number without its configuration is not reproducible.

Next steps