CNAEXT catalogue: extension surfaces by namespace

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

CNA adds a large surface that XNA 4.0 never had, and much of it lives inside the XNA namespaces next to faithful declarations. This page is a catalogue of that extension surface at snapshot c1c316b9, namespace by namespace, with the real member names, why each extension exists and where its boundary is; it also explains how much of it the CNAEXT marker actually covers and what the strict compile check does and does not prove. For the opt-in CNA::Graphics extensions (the retro post-process effects, DebugDraw and the shader-package types) in depth, read CNAEXT extensions.

Three mechanisms that share a name

"CNA extension" names three related but non-equivalent mechanisms. Keeping them apart prevents both API over-claiming and build confusion.

The build-side switches (CNA_CNAEXT, CNA_DEVICES) and the fact that CNA_STRICT_XNA_API is a compile definition rather than a CMake option are tabulated on What CNAEXT is; Two things named CNAEXT is the maintainer's view.

How much of the surface is marked

The authoritative inventory is the source together with the reference-surface census, not a hand-copied list. How large the marked surface looks depends on how it is counted: at this snapshot the marker occurs as a code token (comments stripped) 1,840 times in 321 public headers under modules/*/include, and as a whole word including comments 2,248 times in 338 of the .hpp headers (2,280 times in 343 files if the C API's plain .h headers are included). Neither figure counts extension members, and both will move as APIs are classified. The CNA:: namespaces, which hold most of the non-XNA headers, are not tagged declaration by declaration.

The EXT suffix is a naming convention and is independent of the marker in both directions. Marked declarations without the suffix include ShaderEffect, BasicEffect::SetOwnedTexture and GraphicsDevice::SetContextRecoveryEnabled. Conversely, a few public suffixed members carry no marker at this snapshot: Texture::GetFormatSizeEXT and Texture::GetBlockSizeSquaredEXT, and the GameWindow::getIsBorderlessEXTProperty()/setIsBorderlessEXTProperty() pair. Strict mode does not flag those, which is one reason neither spelling can decide by itself what is an extension; compare against the reference surface instead.

Framework and math bridges

Graphics and model extensions

Graphics extensions span three physical modules (graphics, content and graphics-ext); directory ownership and API classification are different axes. Everything in this table except the last row is compiled in every build.

Content extensions

Input, audio, media and host services

The marker says only "not original XNA". An extension still needs the same ownership, failure, hostile-input and host-evidence analysis as a faithful member, and several of these surfaces are host-dependent (camera, haptics, sensors). XNA compatibility: what CNA adds gives the user-level summary.

The graphics-ext module at a glance

The graphics-ext module holds the opt-in graphics extensions: small, standalone pieces over GraphicsDevice, not another renderer and not a frame pipeline. At this snapshot its public CNA/Graphics directory holds 11 headers (the master include CNAEXT.hpp among them), its src tree 9 C++ sources, its test tree 6 sources with 76 test definitions and its examples 6 programs; every declaration is wrapped in #ifdef CNA_CNAEXT. Its surfaces form three groups: the retro post-process effects (AsciiPostProcessEffect with AsciiQuantizeMode; CRTEffect with CRTMaskType; DepthEffect with DepthEffectMode and DitherMode, which reduces colour depth or maps to a palette and does not visualise the depth buffer), DebugDraw (lines, boxes, spheres, frustums and crosses drawn through the core BasicEffect), and the portable shader-package types ShaderCodeEXT and ShaderPackageEXT that the CRT and colour-depth effects and ShaderEffect's package constructors use.

The effects ship one shader package (post_process: GLSL ES, desktop GLSL, SPIR-V and WGSL, plus HLSL variants carried in a generated header), and the CTest PostProcessShaderPackageReproducibility proves that the generated payload is fresh. The six test sources cover the three effects, DebugDraw, the shader infrastructure and the master include; the six examples (the ASCII font atlas, quantizer and post-effect programs and the CRT and colour-depth demos) reach pixels only in a build with a renderer that runs them. No CI workflow configures CNA_CNAEXT=ON or the cnaext preset; CNA's own scope-reduction record reports the retained set built with the option on and off on OPENGLES3 and its 78 retained-effect and graphics-profile tests passing (2026-09-27, not reproduced here). Shadow-map rendering, image-based-lighting textures, instancing helpers and post-process chains are not part of the module: an application that wants them builds them itself from RenderTarget2D, the stock effects and the receiving types in the table above. The full account, with build switches and per-renderer notes, is CNAEXT extensions.

How the strict check proves itself

In a normal build CNAEXT expands to nothing. Two standalone targets in cmake/Harnesses.cmake give it force, and they are built only when CNA_BUILD_TESTS is on and the compiler is GCC or Clang:

1. The positive direction. cna_strict_xna_api_check compiles StrictXnaApiSurfaceCheck.cpp with CNA_STRICT_XNA_API and -Werror=deprecated-declarations. The file exercises the genuine Microsoft::Devices and sensor API and its header lists every marked member it deliberately does not call. The CTest StrictXnaApiSurfaceCheck_Compile_Run runs the result (under Wine in a Direct3D cross-build tree).
2. The negative direction. cna_strict_xna_api_leak_check is EXCLUDE_FROM_ALL, so it never takes part in an ordinary build. Its whole body is one deliberate violation:

   Microsoft::Devices::Sensors::Accelerometer accelerometer;
   accelerometer.InjectSyntheticSensorUpdate(1.0f, 0.0f, 0.0f); // CNAEXT -- must fail to compile here.

   The CTest StrictXnaApiSurfaceLeakCheck_MustFailToCompile runs cmake --build for that target with WILL_FAIL TRUE, so it passes only if the build fails.

A positive-only check ("the real API still compiles") is equally consistent with a guard that never fires. The pair proves both acceptance and sensitivity for the slice it exercises: if a change to the macro or to the define's wiring ever let the leak compile, the negative test would turn red, catching a regression in the safety net itself. What the pair does not prove is that every addition elsewhere is marked, or that other namespaces are pure; that still takes comparison with the reference surface. (The comment in CNAHelper.hpp still names an old tests/Microsoft/Devices/ location for the positive check; the files live under tools/devices/.)

A game can use the same mechanism on its own code. Define the macro on the target to check and promote the warning:

target_compile_definitions(my_game PRIVATE CNA_STRICT_XNA_API)
target_compile_options(my_game PRIVATE -Werror=deprecated-declarations)

Passing -DCNA_STRICT_XNA_API=ON to the CMake configure step instead only creates an unused cache variable. Tutorial 115 walks through the marker, strict mode and the build gate with code.