Graphics Renderers

CNA 0.1.0-alpha.1  ·  50 public identities  ·  46 implementation families

How renderers work

CNA separates the game-facing rendering API from the underlying graphics implementation with a pure virtual interface, IGraphicsRenderer. Game code never calls a graphics API directly, and never names a renderer.

The compact default is a single-renderer build. Choose its renderer at configure time with either form below; do not mix the forms:

# Long form: name the renderer
cmake -S . -B build -DCNA_GRAPHICS_RENDERER=VULKAN

# Option form: exactly one CNA_RENDERER_<NAME> may be ON
cmake -S . -B build -DCNA_RENDERER_VULKAN=ON

CNA exposes 50 public renderer identities, implemented by 46 families. The five EasyGL identities below share one family; none of the public identities is an alias. The defaults are WEBGL2 under Emscripten, OPENGLES3 on Linux, and SDL_RENDERER everywhere else.

Multi-renderer builds and runtime selection

v0.1.0-alpha.1 adds an opt-in build mode that links several compatible renderer families into one binary. CNA_GRAPHICS_RENDERERS is a semicolon-separated set; CNA_GRAPHICS_RENDERER remains the default and must be a member of that set. Omitting the plural option keeps the ordinary single-renderer build.

cmake -S . -B build-multi -G Ninja \
  -DCNA_GRAPHICS_RENDERER=HEADLESS \
  -DCNA_GRAPHICS_RENDERERS="HEADLESS;SOFTWARE;STUB"

Before the first GraphicsDevice is created, CNA::GraphicsRendererSelection resolves the renderer in this order: an explicit SetPreferred() call, the CNA_GRAPHICS_RENDERER environment variable, then the compile-time default. A name that is unknown or not compiled in throws; CNA never substitutes silently.

#include "CNA/GraphicsRendererSelection.hpp"

CNA::GraphicsRendererSelection::SetPreferred(
    CNA::GraphicsRendererType::Vulkan);
CNA::GraphicsRendererSelection::SetFallbackChain({
    CNA::GraphicsRendererType::OpenGLES3,
    CNA::GraphicsRendererType::Software
});
MyGame game;
game.Run();

Fallback is off by default. SetFallbackChain() or EnableAutomaticFallback(true) opts in; failures are recorded in GetFallbackHistory(). GetSelected() is the renderer CNA will try, GetActive() is what actually started, and GraphicsDevice::GetGraphicsRendererType() reports the device's real renderer. The compile-time getCurrentGraphicsRendererType() still reports the build default.

Combination rules

Multi-renderer builds add code size and every selected family's dependencies. The tag rejects demonstrated conflicts at configure time:

• PORTABLEGL cannot share a binary with a renderer that calls real OpenGL because PortableGL defines the same global gl* symbols.
• GDI cannot be combined with SOFTWARE; GDI recompiles the Software sources with a different mode.
• Windows-only, Emscripten-only and macOS-only identities cannot cross platform partitions in one toolchain.
• GLIDE pins the binary to the 32-bit Glide ABI and cannot be combined with another renderer.

Several EasyGL identities may coexist after alpha.1's runtime-profile work, provided they do not cross the native/Emscripten platform partition.

Names that changed (and one trap)

The renderer vocabulary was normalised. If you are following an older document, translate first — the old spellings are not aliases, they are unknown values that stop the configure step with a FATAL_ERROR.

Test labels moved with the names too: ctest -L D3D9 and ctest -R D3D11 match nothing. The labels are DIRECTX9 and DIRECTX11.

The GL family — five profiles, one EasyGL implementation

Five renderer identities share one internal implementation, EasyGL, which lives in the ../easy-gl sibling repository (itself needing ../meta-gl). The profiles are distinguished by a CNA_GL_PROFILE_* define.

Hand-written ShaderEffect shaders execute on all five. Cube faces used inside a multiple-render-target set are unimplemented on this family. Against the 39-scene XNA oracle corpus, EasyGL matches 10 of 39 scenes at tolerance 0 — see How renderers are verified.

"EasyGL" remains the correct name for the implementation and for the sibling library. It is no longer a value you can pass to CNA_GRAPHICS_RENDERER.

Standalone GL renderers

Four further GL renderers are deliberately independent of EasyGL: each creates its own context because EasyGL cannot express the profile they target.

OPENGL2 and OPENGL4 execute custom ShaderEffect shaders; both leave cube faces inside an MRT set unimplemented. OPENGLES1 is the strongest non-Direct3D result against the XNA oracle corpus, matching 11 of 39 scenes at tolerance 0.

Modern GPU APIs

Four renderers drive a modern explicit GPU API directly, with no middleware in between.

VULKAN, SDL_GPU and METAL are the three here with a stated shader position: custom ShaderEffect shaders execute on VULKAN and SDL_GPU, and throw on METAL. SDL_GPU is one of the four renderers that never override SupportsCapability() (see below), and it leaves cube faces inside an MRT set unimplemented.

METAL has automatically triggered macOS CI on a macos-14 runner. Alpha.1's separate iOS path is restricted to SDL_RENDERER and proves final linking plus a one-frame simulator launch; it does not validate METAL on iOS, physical devices or pixels. tvOS remains unsupported.

Portable 2D renderers and vector rasterizers

These five are 2D by design. Their 3D entry points throw deterministically rather than silently drawing nothing — a failure mode you can test for.

SKIA is the one renderer here that cannot be built from a plain git clone: Skia has to be checked out and built separately, then pointed at with two cache variables.

Windows renderers: the Direct3D ladder

Fourteen renderers are hard-gated to CMAKE_SYSTEM_NAME=Windows and stop the configure step with a FATAL_ERROR anywhere else. Eleven of them walk the historical Direct3D ladder from DirectX 1 to DirectX 12, using the genuine COM interfaces of each era rather than emulating them over a modern API.

Three things are worth calling out in this group:

• FREEDIRECT is the odd one out. It is listed here because it is DirectDraw-shaped and inherited the old DX3 name, but it is not Windows-gated — it is built on SDL3 through the free-direct sibling repository and configures anywhere.
• DIRECTX1 is a declared stub for 3D. Its entire 3D pipeline throws; it is a 2D renderer in practice.
• GLIDE needs a 32-bit toolchain. Glide's native application ABI is 32-bit, so an x86_64 configure is refused rather than silently truncating pointers.

DIRECTX9, DIRECTX11 and DIRECTX12 execute custom ShaderEffect shaders and leave cube faces inside an MRT set unimplemented; all three also never override SupportsCapability(). GDI throws on custom shaders. DIRECTX9 is the only renderer that is pixel-exact against the XNA oracle corpus — see How renderers are verified.

Browser renderers (Emscripten-only)

Four renderers exist only inside a browser, on top of browser-facing 2D APIs. They join WEBGL1 and WEBGL2 from the GL family, which are Emscripten-only for the same reason.

HTML_DOM has its own automatic browser workflow, while the Emscripten multi-renderer workflow also exercises browser configurations. HTML_DOM and SVG_DOM throw on custom ShaderEffect shaders.

Portable middleware layers

Seven renderers do not name a native graphics API at all. Each targets a portable middleware layer that itself picks a native API — sometimes at build time, sometimes at runtime. That indirection is the point, and it is also where the surprises live.

Group-specific caveats, all of which change what your code does rather than merely how fast it runs:

• BGFX accepts custom ShaderEffect shaders and silently ignores them. Nothing throws, nothing warns; the effect simply does not happen. It also leaves cube faces inside an MRT set unimplemented.
• LLGL is experimental, Linux/X11-only and OpenGL-only. LLGL's own Vulkan module cannot be selected from CNA. Custom shaders do execute.
• SOKOL's native API is a build-time choice. CNA_SOKOL_API defaults to GLCORE; the other values are wired but unverified. Custom shaders execute.
• MAGNUM executes custom shaders and, like WICKED, cannot be selected under Emscripten.
• FNA3D enables XNA/FNA compiled Effect Framework bytecode automatically. It executes those binaries through MojoShader and CNA feeds it the stock-effect blobs from the pinned FNA checkout. EasyGL, SDL_GPU and Vulkan can enable the same compiled-effect layer explicitly; it is not universal. FNA3D still cannot compile ShaderEffect source. Against the XNA oracle corpus it matches 10 of 39 scenes at tolerance 0.

CPU and no-GPU renderers

Four renderers need no GPU, no driver and no display server. Two of them produce real pixels on the CPU; two produce none at all.

SOFTWARE accepts a custom ShaderEffect but does not execute it: its effect renderer takes any GLSL/HLSL/WGSL source, reports success without compiling it, and its own fixed CPU shading path produces the pixels. Your shader will not run. HEADLESS records the call without executing it, which is exactly what a harness should do.

Shaders: what actually executes where

Two separate things get called "shaders" in an XNA-shaped framework, and CNA treats them very differently.

Compiled Effect Framework bytecode is the XNA-compatible path described below. It accepts XNA/FNA D3D9 Effect binaries on qualified renderer builds; it is not a compiler for HLSL .fx source and does not accept DXBC or MGFX.

Renderer-native custom shaders use ShaderEffect, and they genuinely execute on: the five GL-profile identities, OPENGL2, OPENGL4, VULKAN, SDL_GPU, SOKOL, LLGL, MAGNUM, DIRECTX9, DIRECTX11 and DIRECTX12. HEADLESS records them only. Elsewhere:

• BGFX accepts them and silently ignores them — the one case with no diagnostic at all.
• GDI, METAL, HTML_DOM and SVG_DOM throw.
• FNA3D cannot compile custom shaders at all; its only shader entry point is XNA's own compiled stock-effect bytecode, run through MojoShader.

See Shader Effects for the API itself.

Compiled XNA effects

GraphicsCapability::CompiledEffects is independent of CustomEffects. FNA3D supports XNA/FNA Direct3D 9 Effect Framework bytecode by default. EasyGL, SDL_GPU and Vulkan support it only when their respective CNA_EASYGL_COMPILED_EFFECTS, CNA_SDL_GPU_COMPILED_EFFECTS or CNA_VULKAN_COMPILED_EFFECTS option is enabled; all three default to OFF. Other renderer families report the capability unavailable. See Effects System.

Capability reporting

The practical consequence is that a capability query is a hint, not a contract. If your game needs a feature, the reliable checks are the ones this page states directly: which renderers are 2D only, which execute custom shaders, and which leave cube faces inside an MRT set unimplemented (DIRECTX9, DIRECTX11, DIRECTX12, BGFX, the EasyGL family, SDL_GPU, OPENGL2 and OPENGL4).

How renderers are verified

Renderer verification is configuration-scoped. The selected renderer set, platform implementation, audio implementation, host and feature options decide which pixel, smoke and integration tests are built and registered. A multi-renderer build may contain several renderer test sets. Report ctest -N and executed results for the exact configuration rather than quoting a tree-wide registration total as though it were universal.

The XNA oracle corpus

CNA keeps 39 reference scenes under tools/xna-oracle/scenes/, with 39 reference PNGs captured from real XNA 4.0 running under Wine + DXVK. Renderers are diffed against those images:

What CI does and does not reach

CI exists across Linux, macOS and headless-browser jobs, but alpha.1 has no effective full-suite or GPU-oracle gate. The intended unfiltered job fails at configure time because it still selects the removed EASYGL identity:

The workflow inventory is evidence of build and smoke coverage, not of universal renderer fidelity. In particular, it does not establish every graphics driver path or the full GPU pixel/oracle matrix. Platforms has the workflow grouping, and Verification & Known Issues the wider testing story.

Which renderer should I choose?