Tutorial 72: Choosing a Renderer

CNA Tutorials  ·  Architecture

CNA exposes 50 renderer identities, implemented by 46 renderer families. The default mode compiles one. An opt-in CNA_GRAPHICS_RENDERERS list can compile several compatible families; the application chooses one before the first graphics device is created, after which the choice latches. This is startup selection and optional fallback, not hot device switching.

The count is not a coverage claim. The 50 identities are not equally complete: some exist to prove a historical API can still be driven, several are deliberately 2D-only or no-output, and others are narrow or experimental. For reference-level capability and platform detail, see the Renderers guide.

Selecting a renderer

For the recommended single-renderer build, use either the named value or exactly one legacy boolean. Do not mix the two forms.

# Form 1 — name the renderer directly (case-sensitive)
cmake -S . -B build -DCNA_GRAPHICS_RENDERER=OPENGLES3

# Form 2 — switch exactly one CNA_RENDERER_<NAME> option ON
cmake -S . -B build -DCNA_RENDERER_OPENGLES3=ON

With form 2, turning on zero or more than one option is a hard FATAL_ERROR: "Exactly one renderer option must be ON when using CNA_RENDERER_* options."

For a multi-renderer build, provide a semicolon-separated list and keep the singular value as the default member:

cmake -S . -B build-multi \
  -DCNA_GRAPHICS_RENDERERS="OPENGLES3;VULKAN;SOFTWARE" \
  -DCNA_GRAPHICS_RENDERER=OPENGLES3

Defaults when you pass nothing: Emscripten gets WEBGL2, Linux gets OPENGLES3, and every other platform gets SDL_RENDERER. Because the Linux default is OPENGLES3, an ordinary Linux build needs the ../sharp-runtime, ../easy-gl and ../meta-gl sibling checkouts present next to cna/ — they are separate repositories, not submodules.

Group 1 — the OpenGL family (9 identities)

Five of these share one internal implementation, called EasyGL, which lives in the ../easy-gl sibling library (itself needing ../meta-gl). "EasyGL" is the implementation's name; it is not a selectable renderer value. Selecting any of the five compiles the same tree and adds a CNA_GL_PROFILE_* define.

OPENGLES3 is the renderer CNA develops against day to day, and the one its Linux CI configures. It is the safe answer if you have no reason to pick another.

Group 2 — modern GPU APIs (4 identities)

METAL is macOS-only in this tag. Alpha.1 has a separate, narrow iOS path restricted to SDL_RENDERER, with final-link and one-frame simulator smoke coverage; tvOS remains unsupported.

Group 3 — portable middleware and engine wrappers (8 identities)

These delegate to a third-party rendering library, which then picks its own native API. That extra layer is the point — and also the risk, because CNA's coverage of each wrapper is narrower than the wrapped library itself.

Group 4 — the Windows ladder (14 identities)

Fourteen renderers are hard-gated to Windows: configuring them anywhere else is a FATAL_ERROR, not a warning. Eleven of them walk the Direct3D version ladder from 1995 forward, and three are the other classic Windows drawing APIs.

Pixel-exactness is a DIRECTX9 statement, and only that. CNA's XNA oracle corpus is 39 scenes captured from the genuine Microsoft XNA 4.0 runtime. DIRECTX9 matches all 39 at tolerance 0. The EasyGL family matches 10, FNA3D 10 and OPENGLES1 11. If bit-identical XNA 4.0 output is the goal, DIRECTX9 is the answer and nothing else is.

Group 5 — browser renderers (4 identities, plus the two WebGL profiles)

Six identities are available to Emscripten. Two — WEBGL1 and WEBGL2 — are EasyGL profiles. The DOM/canvas-facing identities are:

Group 6 — 2D raster and vector (6 identities)

These have no 3D pipeline at all. That is a design decision, not a gap: a 3D call raises a deterministic exception rather than drawing nothing.

Group 7 — CPU-only and no-output (5 identities)

Which renderers refuse 3D

Thirteen renderers are 2D-only and throw deterministically the moment you reach for the 3D pipeline: SDL_RENDERER, DIRECT2D, CANVAS, HTML_DOM, SKIA, BLEND2D, FREEDIRECT, DIRECTX1, GDI, SVG_DOM, OPENVG, NANOVG and PIXIJS. Two more — HEADLESS and STUB — produce no pixel output at all, and SOFTWARE and PORTABLEGL render real pixels but never present them to a window.

Which renderers execute custom shaders

A custom ShaderEffect (see Tutorial 52) genuinely executes on the five GL profile identities, OPENGL2, OPENGL4, VULKAN, SDL_GPU, SOKOL, LLGL, MAGNUM, DIRECTX9, DIRECTX11 and DIRECTX12. HEADLESS records the submission without executing it.

Everywhere else you get one of three different outcomes, and the difference matters:

• BGFX and SOFTWARE accept the effect and silently ignore the source. No error, no shader, no clue — this is the one to watch for.
• GDI, METAL, HTML_DOM and SVG_DOM throw. You find out immediately.
• FNA3D cannot compile custom shaders at all.

The shading language also varies: GLSL on the GL family, SPIR-V on VULKAN and SDL_GPU, HLSL compiled at runtime on DIRECTX9/DIRECTX11/DIRECTX12, and WGSL on WEBGPU. One source string is not portable across all of them.

SupportsCapability() fails open

One gap worth knowing before you design around it

Cube faces inside a multiple-render-target set are unimplemented on eight otherwise-capable 3D renderers: DIRECTX9, DIRECTX11, DIRECTX12, BGFX, the EasyGL family, SDL_GPU, OPENGL2 and OPENGL4. Plain 2D MRT works on these; binding a RenderTargetCube face as one slot of an MRT set does not. See Tutorial 62.

Decision table

Setting the renderer in CMake

# Configure and build with the Vulkan renderer
cmake -S . -B build-vulkan -DCNA_GRAPHICS_RENDERER=VULKAN
cmake --build build-vulkan --target CnaTests

# Equivalent, using the per-renderer option form
cmake -S . -B build-vulkan -DCNA_RENDERER_VULKAN=ON

# Windows-only renderers need a Windows toolchain (MSVC, or MinGW-w64 from Linux)
cmake -S . -B build-d3d11 \
      -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/mingw-w64.cmake \
      -DCNA_GRAPHICS_RENDERER=DIRECTX11

# Emscripten-only renderers refuse to configure for a native target
emcmake cmake -S . -B build-canvas -DCNA_GRAPHICS_RENDERER=CANVAS

CTest labels follow the renderer names too: ctest -L DIRECTX9 works, ctest -L D3D9 matches nothing.

Compile-time defines in game code

The selected renderer emits a CNA_RENDERER_<NAME> preprocessor define. The five GL profiles are the one exception: they all emit CNA_RENDERER_EASYGL (the shared implementation identity) plus a CNA_GL_PROFILE_<NAME> define naming the profile.

#if defined(CNA_RENDERER_VULKAN)
    // Vulkan-specific startup work
#elif defined(CNA_RENDERER_EASYGL)
    // Any of OPENGLES2 / OPENGLES3 / OPENGL33 / WEBGL1 / WEBGL2.
    // Narrow it further when the profile actually matters:
    #if defined(CNA_GL_PROFILE_OPENGLES2) || defined(CNA_GL_PROFILE_WEBGL1)
        // No MRT, no occlusion queries, no Texture3D, no instancing here.
        useDeferredShading_ = false;
    #endif
#elif defined(CNA_RENDERER_DIRECTX11) || defined(CNA_RENDERER_DIRECTX12)
    // Windows-only native Direct3D path
#endif

Runtime selection in a multi-renderer build

GraphicsRendererSelection::SetPreferred() has highest precedence, followed by the CNA_GRAPHICS_RENDERER environment variable and finally the compiled default. Selection must happen before the first graphics device and then latches. Unknown or uncompiled identities throw. Fallback is opt-in; a failed preferred renderer is otherwise a hard failure.

Not every list is legal: CMake rejects known ABI/windowing conflicts such as PortableGL with a real GL family, GDI with Software, Glide with another renderer, and incompatible OS partitions. Multi-renderer builds also carry every selected dependency and increase build and binary size. See Tutorial 126.

What CI actually covers

Alpha.1 contains 21 workflow files. They include Linux, Apple, Emscripten, platform-abstraction, multi-renderer and five declared C API gates; the C API final target is compile-blocked, and Windows D3D/GDI lanes remain manual. The remaining matrix is meaningful scoped evidence, not coverage of every one of the 50 identities, every valid combination, physical iOS hardware, or the full GPU pixel/oracle matrix.