Glossary of XNA and CNA terms

CNA snapshot 3b43bd86  ·  Deep Dives › Reference matrices  ·  source links pinned to 3b43bd86

Short, checked definitions of the XNA and CNA terms used across libcna.com, as they apply to CNA snapshot 3b43bd86. 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)

An earlier prerelease tag (2026-08-20), superseded by the 0.1.0 release (tag v0.1.0, 10 October 2026). This snapshot is 948 commits after the 0.1.0 release and still reports that release’s version string, 0.1.0; the string alone cannot tell the snapshot from the release. See Releases and versioning.

C ABI version

The version of CNA's experimental native C interface: 0.50.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 10 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 three 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.

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; this snapshot pairs with sharp-runtime’s next branch (the v0.1.0 tag pairs with CNA’s 0.1.0 release), and CNA’s configure step refuses a checkout that does not declare a compatible version (0.1.0 or a later 0.1 patch release). It is not a CLR: no JIT, no garbage collector, no runtime reflection.

snapshot (3b43bd86)

The CNA commit 3b43bd8687ed46523d873f9bec4b32bd8481dcb5 on branch next (2026-10-27) that this site documents: a development snapshot 948 commits after the 0.1.0 release (tag v0.1.0, 10 October 2026), whose version string it still reports. It is not itself a release; GitHub’s default branch, main, carries the 0.1.0 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 c6dec91f, repeated at 3b43bd86 without the since-removed misc/, 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), 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 standalone CNAEXT graphics extensions in CNA::Graphics (the ASCII, CRT and colour-depth effects, DebugDraw and the portable shader-package types); 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

OPENGLES3, OPENGL33 and WEBGL2: three 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: WebGL 2 has no indexed colour masks or texture swizzle, and only OPENGL33 draws base-vertex ranges natively. EASYGL is not an accepted selector.

implementation family

The code that implements one or more renderer identities: 8 families serve the 10 identities, because EasyGL serves three. 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 (the default; Windows, X11, Wayland, macOS, iOS, Android and the browser are reached through SDL’s own video drivers), HEADLESS or TERMINAL. Independent of the renderer and of audio, within named exclusion rules.

renderer identity

One of the 10 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 reserved name (one whose C ABI value CNA keeps unassigned) given as a CNA_RENDERER_<NAME>=ON switch; a CNA_RENDERER_<X>=ON switch for a name that is neither public nor reserved (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, SDL_GPU on Windows, macOS and iOS, OPENGLES3 on Linux, Android and every other system.

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_GPU is built on SDL3's GPU API, and a HEADLESS or TERMINAL platform with NULL or ALSA audio and a renderer that needs no SDL lets a build avoid SDL entirely.

Renderers and graphics back ends

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.

FNA3D

The renderer that links FNA3D, the FNA project's 3D library, built statically from CNA's fork libcna/FNA3D, whose cna branch carries CNA's fixes as commits on top of upstream. 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.

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.

MojoShader

The translator of Direct3D 9 Effect Framework bytecode from the FNA stack. CNA uses its fork libcna/mojoshader, fetched as the submodule of its FNA3D fork, 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, CNA’s modern native path and the default renderer on Windows, macOS and iOS; SDL selects its Vulkan, Direct3D 12 or Metal GPU driver underneath it, and the identity is validated on Linux through SDL’s Vulkan driver and under Wine through SDL’s Direct3D 12 driver, not yet on native Windows or Apple hardware. 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.

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.

WEBGPU

A supported renderer (declared Supported; verified on Linux x86_64 and in headless Chrome) 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).

The two classification enums in the core module use the renderer word too. GraphicsRendererCategory (GraphicsRendererCategory.hpp: Native, TranslationLayer, Software, Web, Diagnostic) and GraphicsRendererMaturity (GraphicsRendererMaturity.hpp: Production, Supported, Experimental, Historical, Deprecated) classify a renderer; getGraphicsRendererCategory(GraphicsRendererType) returns the category of the given renderer, and getCurrentGraphicsRendererCategory() that of the build default; getGraphicsRendererMaturity and getCurrentGraphicsRendererMaturity() do the same for maturity. They are descriptors, not a second selection axis; see the renderer internals. CNA’s identity check refuses the old graphics-backend identifiers in its own active files, so a source search for "backend" now finds the other meaning only, apart from upstream libraries’ own vocabulary (SDL’s GPU backends, for example).

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 8 of the 10 identities (FNA3D always; the other 7 only in a build that turns on their family’s 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 (17 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 three renderer families (EasyGL, SDL_GPU and WEBGPU); the oracle is the assertions, not XNA.

PbrEffect, SkinnedPbrEffect

CNAEXT glTF 2.0 metallic-roughness material effects with no XNA counterpart; always compiled. Every family that draws pixels (DIRECTX9, EasyGL, FNA3D, SDL_GPU, SOFTWARE, WEBGPU) reports RendererFeature::PbrEffectShading; a renderer without it draws an untextured, unlit fallback rather than failing. See Effects: CNA-only effects.

RendererCapabilityProfile

The finer CNAEXT capability answer: 33 named features, 8 named 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 GPU-skinnable mesh, skeleton and animation-clip set with keyframed bone tracks, for games that bring their own skinned characters. It is unrelated to the XNA avatar API (avatars are drawn by XNA's own AvatarRenderer, with its own 71-bone rig) and 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 is constructed without a device; it binds to one only when a vertex buffer or draw uses it, so a renderer that cannot draw it refuses at that point, not at construction.

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 every Game and ContentManager declares registered; the first Load<T>() of a type installs that type’s reader family (a stand-alone ContentManager included), so a program links only the readers of the types it loads. 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 (upstream ENet master 5a9c537, unmodified) and wrapped by an internal back end (CNA/Internal/Net/ENetBackend.hpp) behind the Net namespace's SystemLink sessions.

GamerServices

The XNA namespace for Xbox LIVE-era profiles, achievements, leaderboards and system UI. CNA implements it itself and is not Xbox LIVE compatible: by default gamers are local offline profiles created through Guide sign-in, achievements and leaderboards persist to local disk, and the Guide is a CNA-drawn system UI whose standard pages are real, where FNA keeps permanent no-op stubs. An optional CNA gamer-services server, configured outside game code, adds accounts, social features and relayed online sessions. 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; in a browser build the root is an IndexedDB-backed mount, so saves persist across reloads (not in a threaded build that keeps WasmFS). 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 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 CNA::Graphics extension classes use getX()/setX() instead because they have 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.