Glossary of XNA and CNA terms

CNA snapshot 009d40f5  ·  Deep Dives › Reference matrices  ·  source links pinned to 009d40f5

Short, checked definitions of the XNA and CNA terms used across libcna.com, as they apply to CNA snapshot 009d40f5. Each entry says what the term means now, corrects a common older reading where one exists, and links to the page that carries the detail. Terms are grouped by subject; within a group they are alphabetical.

Project, versions and ecosystem

alpha.1 (v0.1.0-alpha.1)

The only tagged CNA release (tag date 2026-08-20). This snapshot is 2,877 commits later but still reports the product version string 0.1.0-alpha.1; the string alone cannot tell the two apart. See Releases and versioning.

C ABI version

The version of CNA's experimental native C interface: 0.29.0 at this snapshot. It moves independently of the product version and is not a statement that the C library builds (no CI job builds it). See Experimental C API.

CNA

A native C++ library, compiled as C++23, that reimplements the XNA 4.0 programming model (Microsoft::Xna::Framework) for C++ programs: a framework and runtime, not a game and not an editor. SDL3 is its default platform and audio implementation, not a requirement, and rendering goes through one of 25 selectable renderer identities. See CNA and XNA 4.0.

cna-samples, cna-examples

Consumer repositories. cna-samples (Ms-PL) ports Microsoft's XNA Game Studio 4.0 samples and asks whether CNA runs historical XNA code; cna-examples (MIT) is one application cataloguing live demos of every CNA area. Both are evidence for their own pinned CNA revision. See the ecosystem.

easy-gl, meta-gl

Sibling libraries: easy-gl is a toolkit-independent C++ wrapper over OpenGL and OpenGL ES (its README says C++20; its CMake requires C++23) that creates no window or context; meta-gl is the typed function-loading layer under it. CNA needs them only for the five GL identities. Not to be confused with EasyGL, CNA's internal implementation family.

FNA

An independent open-source C# reimplementation of XNA 4.0 (Ms-PL), binary-compatible with XNA assemblies. CNA's day-to-day behavioural reference and, through an executed FNA.dll harness, one of its oracles, but not its authority on API surface (FNA omits some XNA members) and not the tie-breaker when measured XNA behaves differently. The local reference tree selects SDL3 by default; "FNA on SDL2" is historical shorthand.

free-direct, free-api

Sibling libraries behind the FREEDIRECT renderer: free-direct is a narrow, game-driven DirectDraw, DirectSound and DirectPlay subset over SDL3; free-api is a minimal Win32 API subset underneath it. Neither aims at general DirectX or Windows compatibility.

sharp-runtime (SharpRuntime)

The sibling C++23 library that implements a practical subset of .NET System.*: System::Object, System::EventHandler<T>, TimeSpan, exceptions, collections, streams and the primitive aliases (bytecs, intcs, Single, String, in namespace SharpRuntime). Required by every CNA build, on its next branch. It is not a CLR: no JIT, no garbage collector, no runtime reflection.

snapshot (009d40f5)

The CNA commit 009d40f5dd085c4e674d3479675fac84b12b3e0a on branch next (2026-09-24) that this site documents. It is a development snapshot, not a release.

XNA 4.0

Microsoft's managed game framework (XNA Game Studio 4.0) for Windows, Xbox 360 and Windows Phone, the API CNA reimplements. Its reference assemblies (XML documentation plus DLL metadata) are the authority for what the API surface is; its runtime, executed under Wine and DXVK, is the authority for the pixels in the oracle corpus.

xna4-spec

A sibling repository of 544 XML type files in 19 namespace directories, transcribed from Microsoft's XNA 4.0 web documentation (checked at fedc17aa). A searchable offline inventory for audits; CNA's code, CMake and workflows do not use it, and its census reads Microsoft's own XML and DLL metadata instead. Verify a row independently before relying on it.

The name "CNA"

CNA's repository gives no expansion of its name. The title of README.md is just "CNA". A search of the README, AGENTS.md, CLAUDE.md and the docs/, misc/ and plans/ trees at 009d40f5 finds no statement of what the letters stand for. Treat "CNA" as a proper name, not an acronym. Any spelled-out form is an interpretation, not project terminology.

Build and selection

audio implementation (CNA_AUDIO_PLATFORM)

Which audio-device layer a build uses: SDL3 (default), SDL2, NULL or ALSA. Only SDL3 and ALSA carry the mixer that XNA playback, MediaPlayer and XACT need. See Platforms: audio.

CNA_CNAEXT, CNA::CnaExt

CNA_CNAEXT is the CMake option (default OFF) that compiles the CNA::Graphics engine layer; CNA::CnaExt is an interface link target composing cna_graphics_ext with cna_devices_ext. Neither is the CNAEXT marker. See What CNAEXT is.

CNA_STRICT_XNA_API

A preprocessor definition, not a CMake option, that turns every CNAEXT-marked declaration into a [[deprecated]] one in the translation units that define it; with -Werror=deprecated-declarations a use becomes an error. See the strict check.

EasyGL profiles

OPENGLES2, OPENGLES3, OPENGL33, WEBGL1 and WEBGL2: five public identities served by CNA's one internal EasyGL implementation family (built on easy-gl) and distinguished by a GL profile. They are not cosmetic variants: the ES 2 generation lacks multiple render targets, occlusion queries, 3D textures and instancing. EASYGL is not an accepted selector.

implementation family

The code that implements one or more renderer identities: 21 families serve the 25 identities, because EasyGL serves five. Evidence is usually gathered per family and qualified per identity.

multi-renderer build

A build configured with CNA_GRAPHICS_RENDERERS that links a compatible set of renderers and chooses one at run time before the first graphics device exists; the choice latches on the first successful renderer creation and fallback is off unless requested. The default build contains one renderer. See Runtime renderer selection.

platform implementation (CNA_PLATFORM)

Who owns windows, events, input, timing and host services: SDL3 (default), SDL2, native X11, WAYLAND and WIN32 (no SDL), HEADLESS or TERMINAL. Independent of the renderer and of audio, within named exclusion rules.

renderer identity

One of the 25 public names that CNA_GRAPHICS_RENDERER accepts, listed in cmake/RendererIdentities.cmake, each with a fixed C ABI value that is never reassigned. A name outside the list given to CNA_GRAPHICS_RENDERER or as a member of CNA_GRAPHICS_RENDERERS is a configure-time error, never a silent fallback, and so is a retired name given as a CNA_RENDERER_<NAME>=ON switch; a CNA_RENDERER_<X>=ON switch for a name that is neither public nor retired (an old D3D9 or EASYGL spelling, a typo) is not read by anything and the platform default renderer is configured (CNA-BUG-269). Defaults: WEBGL2 under Emscripten, OPENGLES3 on Linux, SDL_RENDERER elsewhere.

SDL3

The cross-platform windowing, input and audio library CNA vendors as submodules and uses by default for its platform and audio layers. It is not itself a renderer: SDL_RENDERER is built on SDL3's 2D renderer API and SDL_GPU on its GPU API, and the native X11, Wayland and Win32 platforms let a build avoid SDL entirely.

Renderers and graphics back ends

CANVAS, HTML_DOM, SVG_DOM

The three Emscripten-only 2D renderers: CANVAS draws through an HTML canvas 2D context, HTML_DOM places each sprite as a CSS-transformed element with no canvas in the sprite path, and SVG_DOM uses SVG image elements. All three refuse 3D.

descriptor heap (Direct3D 12)

A Direct3D 12 table of resource-view descriptors rather than of resources. CNA's DIRECTX12 renderer keeps separate RTV, DSV, CBV/SRV/UAV and sampler heaps. At this snapshot its CPU descriptor heaps grow in doubling blocks that are never moved (so handed-out handles stay valid) and freed descriptors are recycled once the fence shows the GPU has finished with them (D3D12DescriptorHeaps.cpp); older descriptions of a fixed-capacity allocator with no reclamation no longer apply.

DIRECT2D, GDI

Windows-only 2D renderers: DIRECT2D draws with an ID2D1DeviceContext (Direct3D 11 and DXGI only host it), and GDI uses no GPU API at all.

DIRECTX9 (formerly D3D9)

The Windows-only Direct3D 9 renderer, built with MinGW-w64 and exercised under Wine and DXVK. It compiles Microsoft's Stock Effects HLSL (vendored verbatim through FNA) and is the one renderer held to XNA's own pixels at tolerance 0 by the oracle corpus. D3D9 is an old spelling that now stops the configure step.

DIRECTX11

The Direct3D 11 renderer. It shares Direct3D helpers with DIRECTX12 in modules/renderers/common/d3d and generates render-target mip chains with the native ID3D11DeviceContext::GenerateMips call.

DIRECTX12

The Direct3D 12 renderer. Direct3D 12 has no built-in mip generator, so render-target mip chains are produced by an explicit loop that reads each level back, box-filters it on the CPU and uploads the next level, one face at a time for cube targets (D3D12RenderTargets.cpp).

fence (Direct3D 12)

A GPU completion counter. The DIRECTX12 renderer keeps two frames in flight, records one fence value per command-allocator slot and waits for that value before reusing the slot, rather than waiting for the frame it just submitted; helper paths that need deterministic readback submit and wait synchronously.

FNA3D

The renderer that links FNA's own 3D library. It runs compiled XNA effects unconditionally (through MojoShader) and uses FNA3D's internal driver choice, which is not a CNA identity; it cannot execute ShaderEffect source.

FREEDIRECT

A 2D-only renderer fronting the sibling free-direct library; it builds natively on non-Windows hosts. Its old name DX3 is refused at configure time.

HEADLESS

A renderer that never rasterises. It counts calls in one of three modes chosen by CNA_HEADLESS_MODE: Fast (counters only; argument checks are skipped), Validation (the default, which also throws HeadlessValidationException on misuse a real renderer would reject) or Trace (Validation plus a call log and resource creation sites). Back-buffer readback throws NotSupportedException instead of fabricating a frame; older descriptions of it returning the last Clear() colour no longer apply.

METAL, OPENGL4, PORTABLEGL

METAL is the macOS-only native renderer and the most conservative 3D one; OPENGL4 is a desktop OpenGL 4.1+ core renderer independent of EasyGL; PORTABLEGL is GL-shaped CPU rendering with a bounded 3D scope and no window.

MojoShader

The translator of Direct3D 9 Effect Framework bytecode from the FNA stack. CNA fetches it with FNA3D and uses it for the FNA3D renderer and for every CNA_*_COMPILED_EFFECTS option. It is not a loader for HLSL .fx source, DXBC or MGFX. See Effects: compiled effects.

SDL_GPU

The renderer on SDL3's GPU API. SDL's GPU API mandates a fixed descriptor-set layout, so CNA remaps each portable SPIR-V payload into it and turns push-constant blocks into uniform buffers (SdlGpuSpirvBindings.hpp). Custom ShaderEffect source compiles GLSL to SPIR-V through libshaderc, only in builds that find it and never on Windows, Apple or Emscripten targets.

SDL_RENDERER

A 2D-only renderer on SDL3's 2D renderer API, and the default everywhere except Linux and Emscripten.

SOFTWARE

A real CPU triangle rasteriser (edge functions, perspective-correct interpolation, per-pixel depth test) that needs no GPU and no display, so it can produce deterministic pixels on a headless machine. It renders off-screen (the Terminal platform displays it) and accepts ShaderEffect source for compatibility without executing it.

STUB

A no-op renderer that reports every capability false; it proves that the framework survives without rendering.

VULKAN

The Vulkan renderer. Its ShaderEffect route takes SPIR-V words rather than GLSL text.

WEBGPU

An experimental renderer with two routes: native through wgpu-native, and in the browser through Emscripten's WebGPU port. Custom shaders are WGSL.

"Backend" in CNA's own identifiers

The selectable graphics implementation is a renderer: the option is CNA_GRAPHICS_RENDERER, the enum is GraphicsRendererType and the implementations live under modules/renderers. In CNA's own identifiers, "backend" usually names something else: an internal service implementation behind a device or network interface. Examples are ICompassBackend and IMotionBackend for the sensors (implemented on Android by AndroidCompassBackend and AndroidMotionBackend), IVibrateBackend for vibration, and ENetBackend for SystemLink networking (ENetBackend.hpp).

Two graphics enums in the core module keep the older word. GraphicsBackendCategory (GraphicsBackendCategory.hpp: Native, TranslationLayer, Software, Web, Diagnostic) and GraphicsBackendMaturity (Production, Supported, Experimental, Historical, Deprecated) classify a renderer. For example, getGraphicsBackendCategory(GraphicsRendererType) returns the category of the given renderer. They are descriptors, not a second selection axis; see the renderer internals. A source search for "backend" therefore finds both meanings. A search for "renderer" finds only the graphics one.

Graphics API

Effect

The XNA base class for a shader program bound to a GraphicsDevice. CNA has three routes behind it: renderer-owned stock effects; compiled XNA/FNA Direct3D 9 Effect Framework bytecode through Effect(GraphicsDevice&, bytes) and the XNB EffectReader on 14 of the 25 identities (FNA3D always; the other 13 only in a build that turns on their default-OFF CNA_*_COMPILED_EFFECTS option); and the CNAEXT ShaderEffect. See Effects: effect paths.

golden-image test

A captured frame compared with a retained reference image under a stated tolerance and environment. CNA's glTF goldens are renderer-owned (each renderer compared with its own past output), which proves determinism and regression detection, not agreement with a reference renderer; the reference's provenance is part of the claim.

GraphicsCapability

A CNA enum (19 members) that GraphicsDevice::SupportsCapability answers for the active renderer. The answer is a hint: the base renderer default is still permissive for the original members unless a renderer narrows them, and a Boolean cannot express device-dependent limits. See Capability reporting.

GraphicsDevice

The central XNA class every draw, state change and resource operation passes through on its way to the selected renderer. See Graphics state and How renderers work.

GraphicsProfile (Reach, HiDef)

XNA's two feature profiles. Reach is the default and is enforced on every renderer, so multiple render targets, occlusion queries, 32-bit indices, float targets and large cubes throw unless HiDef is requested.

oracle corpus (XNA oracle)

39 scenes with reference images captured from the genuine XNA 4.0 runtime under Wine and DXVK on Linux, diffed pixel for pixel at tolerance 0. CNA's records report DIRECTX9 matching all 39; other renderers are measured, not held to it, and no workflow runs it. See the XNA 4.0 oracle corpus.

parity fixture

One of 32 renderer-neutral programs that state their expected result in their own assertions and are registered for four renderer families; the oracle is the assertions, not XNA.

PbrEffect, SkinnedPbrEffect

CNAEXT glTF 2.0 metallic-roughness material effects with no XNA counterpart; always compiled. Support is qualified per renderer family (FNA3D and PortableGL refuse PBR draws). See Effects: CNA-only effects.

RendererCapabilityProfile

The finer CNAEXT capability answer: 32 features, 22 limits, per-format usage masks and a text report, read through GetRendererCapabilityProfileEXT() and related queries. See the capability profile.

ShaderEffect

The CNAEXT route for renderer-native custom shader source or binaries. The dialect is renderer-specific, some renderers accept it without executing it, and it does not make a renderer support compiled XNA effects. Ask ExecutesShaderEffectSourceEXT(). See Shader effects.

SkinnedModelEXT

A CNAEXT skinned model with keyframed bone tracks whose clip names conventionally follow XNA's AvatarAnimationPreset values; it lets avatars render for real through the CNAEXT AvatarRenderer path, while XNA's own AvatarRenderer.Draw() stays faithfully inert. It is separate from the sample-derived SkinningData and AnimationPlayer.

SpriteBatch

The primary 2D drawing API in XNA and CNA, available on every pixel-producing renderer. See SpriteBatch.

stock effects

The five built-in XNA effects: BasicEffect, AlphaTestEffect, DualTextureEffect, EnvironmentMapEffect and SkinnedEffect (plus the internal SpriteEffect that SpriteBatch uses).

VertexDeclaration

A renderer-independent vertex layout: a stride plus VertexElement records naming offsets, formats and usages. It is pure data and can be constructed on a 2D-only renderer; the 3D draw that would use it is where such a renderer refuses.

Content

.cnb

CNA's checksummed binary content container and the default output of the build-time cna-content tool; tried after .xnb. See CNB format.

.cnj

CNA's JSON content descriptor: a typed envelope whose payload rules belong to the loader for each type, not one universal schema. A registered loose-file reader can prefer a same-named .cnj before its native formats.

ContentManager

The XNA class that resolves an asset name to loaded content. Load<T>("name") returns T by value and tries .xnb, then .cnb, then loose files. See ContentManager.

MemoryStream

sharp-runtime's in-memory stream, which CNA uses wherever content bytes are already in memory (for example the XNB decompressor in XnbDecompression.cpp). After Close() its I/O throws ObjectDisposedException but GetBuffer() and ToArray() keep working, as in .NET. Its raw-buffer constructor is writable by default, matching .NET's MemoryStream(byte[]) (checked at sharp-runtime 41b918c9); descriptions of a read-only default are out of date.

ReflectiveReader<T>

XNA's implicit reader for types serialised without a dedicated writer, driven by .NET reflection at load time. CNA has no runtime reflection, but it is not a dead end: the CNAEXT ReflectiveTypeReaderBuilder<T> lets a game declare the field list once, in wire order (serialised properties first, then public fields), and registers the reader and any enum readers it needs (ReflectiveTypeReader.hpp). See Tutorial 148.

.xnb

XNA's compiled content container. CNA reads it with 61 built-in type readers (60 without native 128-bit integers), which a Game registers in its constructor; a stand-alone ContentManager must register them itself. Reader coverage is finite, and unsupported reader names or versions fail explicitly. cna-content can also write .xnb at build time. See XNB loading.

Services

ENet

The UDP networking library vendored in CNA and wrapped by an internal back end (CNA/Internal/Net/ENetBackend.hpp) behind the Net namespace's SystemLink sessions. free-direct's optional DirectPlay transport uses the same library, independently.

GamerServices

The XNA namespace for Xbox LIVE-era profiles, achievements, leaderboards and system UI. CNA persists achievements and leaderboards to local disk and draws its Guide message-box and keyboard overlays for real, where FNA keeps permanent no-op stubs; there is no online half. See GamerServices.

Storage

The XNA namespace for user-data persistence (StorageDevice, StorageContainer). CNA implements it over std::filesystem with path containment, keeps XNA's fake-asynchronous Begin*/End* shape (the callback runs before Begin* returns), and takes its root from an environment-variable chain. See Storage.

XACT

Microsoft's Cross-platform Audio Creation Tool format and engine. CNA parses the .xgs, .xsb and .xwb files and plays them through the selected mixer: SDL3_mixer with the SDL3 audio implementation, CNA's own mixer with ALSA. With SDL2 or NULL audio the classes compile but produce no sound. See Audio.

Conventions and evidence

CNAEXT

An empty marker macro, defined in CNAHelper.hpp, placed on a declaration inside an XNA-shaped namespace that is not part of XNA 4.0. It compiles to nothing unless CNA_STRICT_XNA_API is defined. It is not the CNA_CNAEXT option, and it never removes anything from a build. See the CNAEXT catalogue.

EXT suffix

A naming convention for many non-XNA members and types, such as GameWindow::MinimizeEXT() and RestoreEXT(). It is independent of the marker: some marked members have no suffix, and a few suffixed public members carry no marker, so neither spelling decides what is an extension.

getXProperty() / setXProperty()

How every C# property of the XNA API is spelled in C++; the engine layer uses getX()/setX() instead because it has no XNA name to preserve. See translation conventions.

representation

A declaration with the documented shape exists. The census finds 331/331 XNA 4.0 runtime types and 3,627/3,627 documented members represented; representation is not behaviour. See compatibility levels.