Graphics Renderers

CNA snapshot c1c316b9  ·  14 public identities  ·  12 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 14 public renderer identities, implemented by 12 families. The three GL identities below (OPENGLES3, OPENGL33, WEBGL2) share one family, EasyGL; none of the public identities is an alias. The defaults are WEBGL2 under Emscripten, OPENGLES3 on Linux, and SDL_RENDERER everywhere else (Windows, macOS, iOS, Android and other Unix hosts).

Every identity has a stable, sparse C ABI value (SDL_RENDERER is 1, FNA3D is 43) that is never renumbered. The CMake list, the C++ enum, the CMake registry map, the C header and the C API table are held together by scripts/check_renderer_identities.py, which CTest runs as RendererIdentityRegistry. C++ enum ordinals, by contrast, are dense and are not a stable contract.

A name outside the 14 given to CNA_GRAPHICS_RENDERER or as a member of CNA_GRAPHICS_RENDERERS — a misspelling, a lower-case spelling, an identity that an older document or an alpha.1-era build script mentions but this snapshot does not provide — stops the configure step with a FATAL_ERROR that lists the supported names, and a retired identity is refused by name on the CNA_RENDERER_<NAME>=ON route as well. The check runs first, before SDL or any dependency is configured. There are no aliases, and CMake matches the public names case-sensitively (vulkan is an unknown name; VULKAN is not). One route is not covered: a CNA_RENDERER_<X>=ON switch whose name is neither a public nor a retired identity (-DCNA_RENDERER_D3D9=ON, -DCNA_RENDERER_EASYGL=ON, a typo) is a cache entry nothing reads, so the configure does not fail and builds the platform default renderer (at most CMake's generic warning about a manually specified variable that was not used). In old scripts name the renderer with CNA_GRAPHICS_RENDERER, and read the CNA: Using <X> graphics renderer line of the configure log.

Multi-renderer builds and runtime selection

This snapshot supports 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 (otherwise the configure step fails; nothing is silently substituted). Omitting the plural option keeps the ordinary single-renderer build. Duplicates are removed, the default is moved first, and the configure log prints CNA: renderer set -- <list> (default: <X>).

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. In an Emscripten build the page property Module.cnaPreferredRenderer is consulted at the environment variable's precedence (a real environment variable wins over it), and the exported Module._cna_set_preferred_renderer(name) behaves like an explicit SetPreferred(). A name that is unknown or not compiled in throws; CNA never substitutes silently.

#include <array>
#include "CNA/GraphicsRendererSelection.hpp"

using CNA::GraphicsRendererSelection;
using CNA::GraphicsRendererType;

GraphicsRendererSelection::SetPreferred(GraphicsRendererType::Vulkan);   // or SetPreferred("VULKAN")

constexpr std::array chain{GraphicsRendererType::OpenGLES3,
                           GraphicsRendererType::Software};
GraphicsRendererSelection::SetFallbackChain(chain);                      // opt-in

MyGame game;
game.Run();

On a native build the environment route is CNA_GRAPHICS_RENDERER=VULKAN ./mygame; in a page it is var Module = { cnaPreferredRenderer: "WEBGPU" };. Names are case-insensitive at run time (unlike CMake).

Fallback is off by default. SetFallbackChain() (which takes a std::span, so pass an array rather than a bare brace list) or EnableAutomaticFallback(true) opts in; every skipped renderer is recorded in GetFallbackHistory() with a reason (NotCompiledIn, ProbeUnavailable, InitializationFailed, WindowKindConflict). 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 only the build default.

Two device flags ask for a specific renderer: GraphicsAdapter::UseNullDevice requires HEADLESS and UseReferenceDevice requires SOFTWARE (C++ accessors setUseNullDeviceProperty and setUseReferenceDeviceProperty). If that renderer is not compiled in, or the selection already latched to another one, device creation fails with NoSuitableGraphicsDeviceException; a fallback chain cannot satisfy them with a different renderer. For testing, the environment lists CNA_DEBUG_UNAVAILABLE_RENDERERS and CNA_DEBUG_FAIL_RENDERER_INIT simulate an unavailable or failing renderer, and CNA_FORCE_HEADLESS_DEVICE_EXT creates the named renderers' device without a window. The full API, fallback ordering and C ABI surface are on Runtime Renderer Selection.

Combination rules

Multi-renderer builds add code size and every selected family's dependencies. This snapshot rejects three demonstrated conflicts at configure time, each with a reason in the error:

• Windows-only, Emscripten-only and Apple-only identities cannot cross platform partitions: one toolchain cannot target both.

Several EasyGL identities may coexist in one binary — the GL profile is a runtime value — provided they do not cross the native/Emscripten partition. In a multi-renderer build only the default renderer's CNA_RENDERER_<IDENTITY> macro is defined project-wide; CNA_MULTI_RENDERER is defined when more than one is compiled in. The rules are checked by scripts/check_renderer_combinations.py.

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 when given to CNA_GRAPHICS_RENDERER or CNA_GRAPHICS_RENDERERS (an old-style -DCNA_RENDERER_D3D9=ON switch is simply not read; see above). The old option name behaves the same way: no build file at this snapshot reads CNA_GRAPHICS_BACKEND, so -DCNA_GRAPHICS_BACKEND=VULKAN is accepted without an error and the platform default renderer is configured (read from the CMake files; not executed). In old scripts, rename the option itself.

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

The 14 renderers at a glance

One row per public identity, in C ABI order. Scope comes from the code-declared ThreeD capability; maturity is CNA's own declaration (see Declared maturity), not a measurement. Detail, dependencies and caveats follow in the per-family sections.

The gaps in the C ABI numbering are deliberate: the values that are not listed are permanently reserved and refused by every C route, and the next new identity would take 52. CNA's stated policy is a curated set — a renderer earns a place with meaningful platform coverage, compatibility value, architectural value or a capability the set does not cover, and "renderer count is not a goal"; no new identity is planned.

The GL family — three profiles, one EasyGL implementation

Three renderer identities share one internal implementation, EasyGL, which lives in the ../easy-gl sibling repository (itself needing ../meta-gl). The profile is a runtime value inside the family, so the two native profiles can be linked into one binary; WEBGL2 sits on the other side of the native/Emscripten partition.

Hand-written ShaderEffect shaders execute on all three: GLSL ES on OPENGLES3 and WEBGL2, desktop GLSL on OPENGL33. Compute shaders need ES 3.1 / GL 4.3 and indirect draw needs ES 3.1 / GL 4.0, so on this family they are reported only where the context provides them, and never under WebGL. Compiled XNA effects are opt-in with CNA_EASYGL_COMPILED_EFFECTS. Against the 39-scene XNA oracle corpus, EasyGL is gated on two line scenes at tolerance 0 (EasyGL_XnaLineCoverage); a whole-corpus measurement recorded 10 of 39 on 2026-08-11, before later pixel-centre fixes — see How renderers are verified. Step-by-step use is in Tutorial 102.

"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.

Modern GPU APIs

Four renderers drive a modern explicit GPU API: two of them directly (VULKAN, METAL), two through a portable layer (WEBGPU, SDL_GPU).

The "modern graphics" work landed on VULKAN, SDL_GPU, WEBGPU and the Direct3D 11 renderer: float and half-float render targets, shadow and image-based-lighting sampling, and renderer-internal compute, indirect-draw and GPU-timer support that the capability queries report (see Modern features by renderer). VULKAN is covered by Tutorial 85, SDL_GPU by Tutorial 131, WEBGPU by Tutorial 132 and METAL by Tutorial 109.

METAL is declared Supported. CNA’s Apple campaign qualified it on a physical Mac mini M4: the full CTest tree passed (11,015 tests, 114 skipped by name, none failed), the Metal-labelled set of 261 tests — 101 shared pixel fixtures, 146 renderer-neutral oracle scenes and 14 native tests — passed under the Metal validation layers in Debug and in a Release build, and all 91 ported XNA samples passed the automated renderer matrix. CNA’s verdict is still not primary-production: compiled XNA effects are off unless CNA_METAL_COMPILED_EFFECTS=ON, custom effects are SpriteBatch-scoped MSL, on-screen presentation was never observed (the console was locked), PresentInterval.Two presents as One, the backbuffer is always BGRA8, the sampler LOD bias needs the macOS or iOS 26 SDK and OS, and no soak run has bounded its caches. No Intel Mac was run. On iOS, METAL ran in the iOS Simulator (iPhone 17 profile) with an exact pixel probe and its device build final-links; no physical iPhone or iPad ran it. In CI, metal-macos-ci.yml builds it and runs the ^Metal tests on GitHub’s macos-26 runners (a paravirtual GPU without shader validation). tvOS remains unsupported.

2D-only renderers

One identity is 2D by design (ThreeD is false in code): SDL_RENDERER. Its 3D entry points do not silently draw nothing — a failure mode you can test for. (STUB also reports ThreeD false, but it is a no-op renderer, not a 2D renderer.)

What a 3D call does on a 2D-only renderer

The behaviour is a setting, Unsupported3DGraphicsCallBehavior, changed with GraphicsDevice::SetUnsupported3DGraphicsCallBehavior (or, from C, cna_graphics_device_set_unsupported_3d_call_behavior). Throw is the default and raises std::runtime_error("<renderer> does not support 3D: <method>"); WarnAndStub logs one warning per operation and returns a safe no-op or null object. SDL_RENDERER honours WarnAndStub. WarnAndStub does not change any SupportsCapability() answer.

Windows renderers: Direct3D 9 and 11

Two renderers are hard-gated to CMAKE_SYSTEM_NAME=Windows and stop the configure step with a FATAL_ERROR anywhere else. They are the Direct3D generations that matter to an XNA-shaped framework — Direct3D 9 (the API real XNA 4.0 itself ran on) and 11 — using the genuine COM interfaces rather than emulating them over another API. (SDL_GPU can also reach Direct3D 12 on Windows, as one of the drivers SDL’s GPU API chooses from.)

Two things are worth calling out in this group:

• DIRECTX11 reports compute, indirect draw and GPU timers from renderer-internal implementations; renderer_capability_truth_test.cpp checks that the capability answers match those implementations. There is no public compute class for game code.
• Only DIRECTX9 has no SupportsCapability() override. It relies on the permissive base defaults wholesale, so its true answers are the least informative; DIRECTX11 uses a switch with no default arm (an unknown capability answers false).

Custom ShaderEffect shaders on this group are HLSL, compiled at run time with D3DCompile (DIRECTX9: vs_3_0/ps_3_0 under HiDef, vs_2_0/ps_2_0 under Reach). Compiled XNA effects are opt-in with CNA_DIRECTX9_COMPILED_EFFECTS and CNA_DIRECTX11_COMPILED_EFFECTS. DIRECTX9 is the only renderer recorded as pixel-exact against the XNA oracle corpus — see How renderers are verified. A guided tour is Tutorial 103.

Browser renderers

Two renderers draw in a browser. WEBGL2, from the GL family, exists only there and is the Emscripten default. WEBGPU also has a browser route (the browser’s own WebGPU through the emdawnwebgpu port) but is not Emscripten-only, because it also builds natively through wgpu-native. A page uses WebGPU where the browser offers it and WebGL 2 elsewhere; both can be linked into one bundle.

The Emscripten multi-renderer workflow builds one bundle containing WEBGL2 and WEBGPU and asserts that both renderer archives, both registry entries and the JavaScript selection surface are present — it builds and inspects symbols; it does not run them. Under Emscripten a WEBGPU build needs a larger Asyncify stack, which the build now sizes automatically. The strongest browser evidence is outside CI: the 90 sample builds at samples.libcna.com run on WEBGL2 and were each run in Chrome when they were published.

To pick a renderer from the page, set the property before the module starts: var Module = { cnaPreferredRenderer: "WEBGPU" }; (or call Module._cna_set_preferred_renderer); the bundle must have been built with that renderer in CNA_GRAPHICS_RENDERERS. Tutorial 105 and Tutorial 132 walk through both routes.

Translation and adapter layers

Three renderers do not name one native graphics API. Each targets a portable layer that itself picks a native API — sometimes at build time, sometimes at run time. CNA classifies SDL_RENDERER, WEBGPU, SDL_GPU and FNA3D as its TranslationLayer category; the three below are the ones where the indirection changes what your code does. 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:

• SDL_GPU is an SDL3 API, so it requires the SDL3 platform. A configure with CNA_ENABLE_SDL=OFF refuses it by name. On Windows and Apple SDL_shadercross is on by default (CNA_SDL_GPU_SHADERCROSS); Linux and Android use the committed SPIR-V natively. A custom ShaderEffect additionally needs a target-native libshaderc, so it is unavailable on Windows, Apple and Emscripten builds.
• WEBGPU is Experimental. Its native route downloads a pinned wgpu-native release unless you give CNA_WEBGPU_ROOT; its browser route needs no native library. No CI workflow names it.
• FNA3D enables XNA/FNA compiled Effect Framework bytecode automatically. It executes those binaries through MojoShader and cannot compile ShaderEffect source at all. Its Fna3d_XNA_Oracle test renders the whole corpus but gates only that every scene renders, not that it matches. See Tutorial 108.

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 reports CustomEffects false: its fixed CPU shading path produces the pixels, and your shader source will not run. HEADLESS validates and records the call without executing it, which is exactly what a harness should do. UseNullDevice maps to HEADLESS and UseReferenceDevice to SOFTWARE. See Tutorial 107.

What each renderer needs from the platform

The renderer and the platform implementation (CNA_PLATFORM: SDL3 by default, HEADLESS, TERMINAL) are independent build axes, but the platform decides which renderers can find a window, a GL context or a Vulkan surface. SDL3 is CNA’s one windowing implementation: Windows, X11, Wayland, macOS, iOS, Android and the browser are reached through SDL’s own video drivers, and a renderer that needs a native handle (an HWND, an X11 Display* and window, a Wayland wl_display* and wl_surface*, a Cocoa or UIKit view) receives it from the SDL3 window through NativeWindowHandle.

• Three renderers are SDL3 APIs or depend on SDL directly: SDL_RENDERER, SDL_GPU and FNA3D. The other families are SDL-free at source level and take their window, GL context and Vulkan surface from the platform.
• A GL context and a Vulkan surface are provided by the SDL3 platform (not Terminal, not Headless).
• An SDL-free build has no window. CNA_ENABLE_SDL=OFF refuses CNA_PLATFORM=SDL3, SDL3 audio and the three SDL renderers by name; what remains is a windowless configuration (HEADLESS or TERMINAL with HEADLESS, SOFTWARE or STUB, and Null or ALSA audio) for servers, test runners and terminal games.
• Terminal accepts only the CPU/no-pixel renderers and is POSIX-only. iOS admits SDL_RENDERER and METAL; anything else is a FATAL_ERROR unless the unsupported override -DCNA_APPLE_ALLOW_UNVALIDATED_RENDERER=ON is given.

The platform matrix, the CNA_AUDIO_PLATFORM axis and the per-OS status are on Platforms.

Sibling repositories and fetched dependencies

Sibling repositories are not submodules; the configure step checks that they sit next to the CNA checkout. Third-party sources that CNA fetches are pinned.

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 Direct3D 9 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 three separate questions apply: does the renderer accept a ShaderEffect (the CustomEffects capability), does the supplied source text determine the pixels (the detailed ShaderEffectSourceExecution feature), and which payload does it consume (its declared shader dialect).

The last column comes from the renderers' own ExecutesShaderEffectSourceEXT() overrides; the profile states an accepted-but-not-executed ShaderEffect in its report text ("the supplied source text does not determine rendered pixels on this renderer"). 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. It means the renderer can execute XNA/FNA Direct3D 9 Effect Framework bytecode (.fxb), which needs MojoShader (or CNA's translation of it) from the pinned FNA3D checkout. FNA3D supports it always; eight other families support it only when their build option is on, and every option defaults to OFF. A default configure therefore reports CompiledEffects false on 13 of the 14 identities. See Effects System.

There is no compiled-effect implementation on HEADLESS, STUB or SDL_RENDERER. Each opt-in family has its own compiled-effect test file; FNA-executed reflection, state and pixel fixtures (tests/fixtures/compiled-effects/) are replayed by several of them with a ±3 channel tolerance on 8×8 flat-input pixels — compiled effects only, not sprites or 3D scenes.

Capability reporting

GraphicsCapability now has 19 members: the 14 that existed in alpha.1 (ThreeD, DepthStencilBuffer, MultiSampleAntiAliasing, MultipleRenderTargets, AnisotropicFiltering, WireFrame, OcclusionQuery, CustomEffects, Texture3D, MultiStreamVertexInput, Instancing, StencilBuffer, AdditiveBlending, CompiledEffects) and five added since: FloatRenderTargets, HalfFloatRenderTargets, HalfFloatTextureLinearFiltering, ComputeShaders and IndirectDraw. At the device level, GraphicsDevice::SupportsCapability derives six answers from separate false-by-default virtuals rather than the renderer's own switch (CompiledEffects, the two float render-target members, half-float filtering, ComputeShaders, IndirectDraw), and ANDs MultipleRenderTargets with the profile's MRT limit. The device-level answer is the public one: a caller who holds the renderer interface directly can see different values (for example SDL_GPU).

The practical consequence is unchanged: a capability query is a hint, not a contract. The reliable checks are the ones this page states directly — which renderers are 2D only, which execute custom shaders, and which report a feature in the matrix below — plus the detailed profile that follows. Tutorial 101 shows how to query and interpret them.

One gap no capability member reports: a cube face inside a multiple-render-target set. DIRECTX9 and SDL_GPU refuse it at SetRenderTargets with "cube faces in a multi-target set are not implemented by this CNA renderer"; WEBGPU and HEADLESS refuse it too, with their own messages (a face "cannot be bound in a multiple-render-target set" on WEBGPU, "cannot bind a cube face alongside other render targets" on HEADLESS); a single cube face bound on its own is a different, ordinary path. The GL family, VULKAN, DIRECTX11 and SOFTWARE contain code for the multi-target case. Check Render Targets before relying on it.

Capability matrix

Derived from each renderer's own capability code: T true, F false, c conditional (a device, driver or build-option probe decides). The first table is the 13 original members; the second the newer six. Unless noted, a c means the answer comes from a run-time probe of the driver or device.

Reading the conditions. T*: DIRECTX9 carries its own profile table for MRT (Reach 1, HiDef 4), but the gating is not specific to it. At the device level GraphicsDevice::SupportsCapability(MultipleRenderTargets) is the renderer's answer ANDed with that same profile ceiling (the interface default is also Reach 1, HiDef 4) for every identity, and FloatRenderTargets and HalfFloatRenderTargets are refused outright under Reach (Texture::IsRenderTargetFormatAllowedByProfileEXT). CNA defaults to Reach, so the RT, F32 and F16 columns describe each renderer under HiDef: on the default profile GraphicsDevice::SupportsCapability reports them false on every renderer. The Oq column is likewise the renderer's own answer: under Reach the OcclusionQuery constructor throws NotSupportedException whatever the column says. EasyGL: AA is GL_MAX_SAMPLES>1; An needs GL_EXT_texture_filter_anisotropic; Wf is native glPolygonMode, GL_NV_polygon_mode on ES, or a WebGL extension; CE is the CNA_EASYGL_COMPILED_EFFECTS build; F32/F16 come from a run-time framebuffer probe; Cs needs ES 3.1 / GL 4.3 (never WebGL) and Id ES 3.1 / GL 4.0 (never WebGL). VULKAN: An, Wf, AA, RT, St, Cs and Id come from device features and limits. WEBGPU: AA from a 4x MSAA probe, F32/F16 from device probes, Id needs the IndirectFirstInstance feature. DIRECTX11: AA is the clamped multisample count > 1, F32/F16/HF come from DXGI format-support queries, Cs and Id need feature level 11_0 (which device creation already requires). METAL: AA is true when the device reports any supported sample count; Cx covers SpriteBatch-scoped MSL effects only; F32/F16 come from its render-target storage table (RGBA32F and RGBA16F). SDL_GPU: DS/St from the formats created, Cx only with libshaderc; the table shows the device-level answers (see the note above). FNA3D: Cx is false because FNA3D accepts only compiled D3D9 Effect binaries; Oq is whatever FNA3D’s driver reports (its SDL_GPU driver has no occlusion queries). CE c means "true only in a build with that renderer's compiled-effects option".

RendererCapabilityProfile: the detailed answer

The 19-member GraphicsCapability enum is a summary. This snapshot adds a second, finer API, CNA::RendererCapabilityProfile: 32 RendererFeature ids (the legacy summaries split further, plus ShaderEffectSourceExecution, Texture3DSampling, ComputeImageBinding, ShadowSampling, ImageBasedLighting, GpuTimers, six shader-dialect flags and BaseInstanceDrawing), a four-state answer (Unknown, Unsupported, Supported, Restricted; at this snapshot the device fills in only Supported and Unsupported), 22 RendererLimit ids (texture size, vertex streams, compute work-group limits, buffer sizes, attachments, alignments, timestamp period, each with an explicit known/unknown flag), per-format usage masks for the 27 SurfaceFormat values (each usage carries separate known and supported bits, so an unclassified use is not misread as unsupported), and a generated English report. The profile is built lazily by the GraphicsDevice and cached until renderer reconstruction or device destruction.

#include "Microsoft/Xna/Framework/Game.hpp"
#include "CNA/RendererCapabilityProfile.hpp"

// inside a Game subclass, after the device exists:
auto& device = getGraphicsDeviceProperty();

bool compute = device.SupportsRendererFeatureEXT(CNA::RendererFeature::ComputeShaders);
CNA::RendererLimitValue maxTex =
    device.GetRendererLimitEXT(CNA::RendererLimit::MaxTextureDimension);   // maxTex.known / maxTex.value
CNA::RendererFormatSupport color =
    device.GetRendererSurfaceFormatSupportEXT(Graphics::SurfaceFormat::Color);
bool colorRt = color.Supports(CNA::RendererFormatUsage::RenderTarget);

std::string_view report = device.GetRendererCapabilityReportEXT();       // English text

The accessors are GetRendererCapabilityProfileEXT(), GetRendererFeatureSupportEXT(), SupportsRendererFeatureEXT(), GetRendererLimitEXT(), GetRendererSurfaceFormatSupportEXT() and GetRendererCapabilityReportEXT(); five C functions expose the same surface in the experimental C API (ABI 0.46.0). Tutorial 133 is a full walkthrough.

Modern features by renderer

Only where the code claims the feature and a test exists. "Verified" means read in the renderer's implementation and its test registration; nothing here says a test was run.

The opt-in CNAEXT extensions (CNA::Graphics: CRT, colour-depth and ASCII effects and debug drawing) need custom ShaderEffect support for the two shader-based effects; see CNAEXT extensions. Shadow maps and environment maps are rendered by the application and passed to the receivers in the table above.

Texture and surface formats

SurfaceFormat has 27 members: the 20 classic XNA formats and 7 CNA extensions (ColorBgraEXT, ColorSrgbEXT, Dxt5SrgbEXT, Bc7EXT, Bc7SrgbEXT, ByteEXT, UShortEXT). Each renderer classifies formats itself; a renderer with no classifier gets the framework rule: SurfaceFormat::Color only, anything else throws ("... is not implemented by the selected graphics renderer"). Summaries below come from one implementation file each, so treat them as guidance and use the profile for the truth on your device.

• Color-only (no classifier): HEADLESS, STUB, SDL_RENDERER; DIRECTX9 as well, for textures and render targets alike (see the last bullet).
• METAL: all 20 classic formats in native storage — the packed 16-bit ones where the GPU has packed 16-bit formats, DXT1/3/5 as BC blocks or decoded — in Texture2D, TextureCube and (without DXT) Texture3D; render targets Color, Rgba1010102, Rg32, Rgba64 and the float and half-float formats; the 7 extension formats defer to the framework rule.
• VULKAN: the 20 classic formats, each mapped to a VkFormat and checked against the device's format properties (BC1-3 native only with textureCompressionBC, Bgra4444 only with VK_EXT_4444_formats); the 7 extension formats have VkFormat mappings for the capability-profile queries but defer at Texture2D creation, so they are refused; render targets Color, Rgba64, Single, Vector2, Vector4 and the half-float formats.
• EasyGL: Color, Alpha8 and DXT1/3/5 on every profile (CPU-decoded without S3TC), the packed 16-bit formats as sized GL storage, NormalizedByte2/4 and the remaining classic formats through the ES 3 sized-format set; the extension formats defer.
• SDL_GPU: Color, packed 16-bit, DXT (native BC or CPU decode), NormalizedByte2/4 and Alpha8; Rgba1010102, Rg32, Rgba64 and the float and half-float formats in their exact native storage (widened to four channels with Direct3D 9’s fill) where the device can sample that storage, refused otherwise — never substituted.
• DIRECTX11: the 20 classic formats asked of the device, BC1-3 native; the 7 extension formats classified unsupported. WEBGPU: BC only when the device enabled it; HalfVector4 and HdrBlendable stored natively as rgba16float in Texture2D; Rgba64 has no render-target mapping. SOFTWARE: the 20 classic formats, DXT stored as blocks. FNA3D: Color and the signed-normalized NormalizedByte2/NormalizedByte4 (authentic XNA normal maps) are classified supported; DXT and BC7 follow the driver’s own format answer; every other format defers to the framework rule, so a public Texture2D in one of them is refused although the renderer layer itself can carry it. DIRECTX9: an internal D3DFMT mapping exists (Bc7EXT/Bc7SrgbEXT unmapped), but the renderer does not override ClassifySurfaceFormatEXT, so a public Texture2D falls back to the framework rule and is Color-only.

Declared maturity

Every identity carries a code-declared maturity and category, readable from C++ and from the C API. These are CNA's own classification, not a measurement. Historical and Deprecated exist in the enum, but no renderer uses them at this snapshot.

Categories: Native (OPENGLES3, OPENGL33, VULKAN, DIRECTX9/11, METAL), TranslationLayer (SDL_RENDERER, WEBGPU, SDL_GPU, FNA3D), Software (SOFTWARE), Web (WEBGL2) and Diagnostic (HEADLESS, STUB). Automatic fallback uses these two declarations to order the candidates (mature GPU renderers first, CPU renderers ten places later, STUB last). Read "Production" with the verification section beside it: it is a declaration, and the Windows and Metal lanes in particular are exercised mostly under Wine or a build-only lane.

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 renderer-neutral reference scenes (256×256, HiDef) under tools/xna-oracle/scenes/, with 39 reference PNGs captured from the genuine Microsoft XNA 4.0 runtime running under Wine + DXVK on Linux — not on Windows. A further 7 unbound-texture scenes and a 17-format channel-expansion table were measured the same way; they sit outside every diff denominator. Renderers are compared against the 39 references at tolerance 0:

Cross-renderer parity fixtures and glTF conformance

Thirty-two renderer-neutral parity fixtures (modules/graphics/examples/parity/) each state their expected result themselves; they are registered as <Renderer>_Parity_<fixture> for four renderer families — EasyGL, WEBGPU, SDL_GPU and DIRECTX11. The oracle is the fixture's own assertions, not real XNA. Separately, a glTF conformance corpus of 148 assets (140 captured plus 8 safely rejected) has renderer-owned goldens for OPENGLES3/EasyGL, VULKAN, SOFTWARE and DIRECTX11; that proves each renderer against its own past output, not against a reference renderer, and only the EasyGL job runs in CI.

What CI does and does not reach

CI exists across Linux, macOS and Emscripten jobs: 18 workflow files, 16 of which run automatically. It builds and smoke-tests; it is not a full GPU-oracle gate:

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?