CNAEXT catalogue: extension surfaces by namespace

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

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 009d40f5, 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 engine layer in depth, read CNAEXT Engine Layer.

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,843 times in 330 public headers under modules/*/include, and as a whole word including comments 2,279 times in 353 of the .hpp headers (2,320 times in 358 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 engine layer at a glance

The graphics-ext module is an engine-oriented layer over GraphicsDevice: not another renderer, and not a turn towards an editor-led runtime. At this snapshot its public CNA/Graphics directory holds 98 headers and its test tree 92 C++ sources; those counts describe scope, not uniform execution. Its surfaces form six cooperating groups: materials and environments (PbrMaterial, glTF material bridge, environment processing, sky, light probes), lights and shadows (single, cube and cascaded shadow maps; the clustered-forward many-light path), the frame pipeline (RenderPipeline, target pooling, a depth-normal prepass and an ordered post-process chain), geometry scale (InstancedRendererEXT, FrustumCullerEXT, LodGroupEXT, GPU culling, particles, transparency ordering), modern resources (ComputeShader, storage and constant buffers, texture arrays, shader packages) and observation (GPU timers, pipeline diagnostics, debug draw).

The layer checks named GraphicsCapability values and validates resources where they are used. Some algorithms keep an intentional CPU path: clustered light assignment runs without compute through ClusteredLightAssignment, and ClusteredLightComputeTests.cpp compares the CPU and GPU assignments. Features that need GPU primitives refuse by name instead of substituting silently. Its tests must be read by kind: arithmetic, grid and material tests run against recording test doubles; shader-package tests prove that generated payloads are fresh; resource and interop tests need an engaged renderer; and visibility, shadow, post-process and readback tests reach pixels. So 92 test sources are not 92 renderer-qualified pixel suites, and no CI workflow configures CNA_CNAEXT=ON. Application repositories built on the layer add integrated observations, each for its own pinned revision and host. The full account, with per-renderer support and the degradation rules, is CNAEXT Engine Layer.

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.