CNAEXT Extensions

CNA snapshot b0e97bb1

CNA reimplements the XNA 4.0 API. What it adds on top is labelled as an extension: physically based materials and their shadow and lighting inputs, morph targets, renderer capability queries, the device-services layer, and one small opt-in graphics module with retro post-processing effects and a debug-drawing helper. This page is the reference for what “CNAEXT” means, what that module contains, which renderers can run it, how it is built and tested, and where its limits are. For a guided tour with code, start with Tutorial 115 and Tutorial 116.

What CNAEXT is

Four unrelated things share the name, and confusing them is the most common mistake. Only two of them are build switches.

The marker is exactly this (modules/core/include/CNA/CNAHelper.hpp):

#ifdef CNA_STRICT_XNA_API
#define CNAEXT [[deprecated("CNAEXT: not part of the XNA 4.0 API surface")]]
#else
#define CNAEXT
#endif

It is never a compile guard: everything it marks is compiled in every build. CNA_STRICT_XNA_API is not a CMake option — nothing in CMake declares it — so you set it on the one target you want checked, together with -Werror=deprecated-declarations. Its verification harness (cna_strict_xna_api_check, and a WILL_FAIL leak check) covers only the Microsoft::Devices and Sensors surface, not the graphics, content or input API, so a clean strict build is a hint about your own code, not a proof that you stayed within XNA 4.0. Tutorial 115 walks through the mechanism.

Where extensions live

CNA::Graphics is not a synonym for “gated”: CNA::Graphics::VertexTypeRegistryEXT lives in the always-compiled graphics module. And CNAEXT itself can never be a namespace, because it is a macro.

The always-compiled extension surface

A large part of what people call “CNAEXT” needs no build option. The headers say so deliberately: an effect's public surface must not change with a build flag.

Building it, and how the gate works

Both options are attached as public compile definitions to the shared CNA::BuildConfig interface target, so every consumer of the CNA target sees the same macro the headers test. Both extension modules are always added and always compiled; with the option off, every source file and every header of graphics-ext is wrapped in #ifdef CNA_CNAEXT ... #endif (a text-level check enforces this) and compiles to nothing. The consequence is the classic trap: #include "CNA/Graphics/CRTEffect.hpp" succeeds in a default build and declares nothing, so the error you get is “no type named CRTEffect”, not “missing header”. The fix is the CMake flag, not an include path.

# The repository's own preset: OPENGLES3, Debug, CNA_CNAEXT=ON, tests on, examples off.
# (Its display name in CMakePresets.json still says "engine layer"; it builds this module.)
cmake --preset cnaext

# Or by hand, in your own build directory:
cmake -S . -B build -DCNA_GRAPHICS_RENDERER=OPENGLES3 -DCNA_CNAEXT=ON

# In a game project that adds CNA as a subdirectory (Tutorial 03), set the option first:
set(CNA_GRAPHICS_RENDERER "OPENGLES3" CACHE STRING "CNA graphics renderer")
set(CNA_CNAEXT ON CACHE BOOL "Build the CNA::Graphics extensions")
add_subdirectory(${CNA_DIR} ${CMAKE_BINARY_DIR}/cna)

target_link_libraries(MyGame PRIVATE CNA)   # CNA already includes graphics-ext; CNA_CNAEXT reaches your code

Then include the master header and use CNA::Graphics:

#include "CNA/Graphics/CNAEXT.hpp"   // every CNA::Graphics extension type; empty without CNA_CNAEXT

Where the tests and examples come from: the module’s tests need CNA_BUILD_TESTS and CNA_CNAEXT; the CRT and colour-depth demos additionally need CNA_BUILD_EXAMPLES and a renderer of OPENGLES3, OPENGL33 or VULKAN. The cnaext preset builds tests but not examples. Two more facts worth knowing before you plan a project around it:

• Shared library and C API. A shared libcna names both extension modules when they are present. The C API keeps one exported ABI regardless of the option: graphics_ext.h declares its 44 routes (CRT, colour-depth and ASCII effects, debug drawing and two value initializers) in every build, and they return CNA_RESULT_NOT_SUPPORTED when the module is absent. See the C API page.
• No extra dependencies. The effects’ shaders are embedded as one portable shader package (GLSL ES, desktop GLSL, SPIR-V and WGSL payloads, regenerated by tools/shader_package/generate_shader_package.py), with HLSL variants of the CRT and colour-depth shaders compiled in; at run time nothing links a shader compiler.

What the CNAEXT module contains

modules/graphics-ext has 11 public headers in CNA::Graphics, all included by CNA/Graphics/CNAEXT.hpp:

CRT and colour-depth reduction are used the way any custom post-process is: draw the scene into a RenderTarget2D, then redraw it through SpriteBatch::Begin(…, &effect). Anything beyond these effects — bloom, tone mapping, shadow-map generation, sky rendering — is application code built on the XNA API, as Tutorial 66 and Tutorial 59 show.

Which renderers can run it

Ask at run time rather than assuming: GraphicsDevice::SupportsShaderLanguageEXT and ExecutesShaderEffectSourceEXT answer whether a ShaderEffect variant can run, and a ShaderEffect whose package has no usable variant fails at construction with a diagnostic.

A minimal example

#include "CNA/Graphics/CNAEXT.hpp"
#include "Microsoft/Xna/Framework/Graphics/RenderTarget2D.hpp"
#include "Microsoft/Xna/Framework/Graphics/SpriteBatch.hpp"

using namespace Microsoft::Xna::Framework::Graphics;

// LoadContent: one scene target and the effect.
sceneTarget_ = std::make_unique<RenderTarget2D>(device, width, height);
crt_ = std::make_unique<CNA::Graphics::CRTEffect>(device);
crt_->setScanlineIntensity(0.35f);
crt_->setCurvature(0.08f);

// Draw: render the scene off-screen, then present it through the effect.
device.SetRenderTarget(sceneTarget_.get());
DrawScene();
device.SetRenderTarget(static_cast<RenderTarget2D*>(nullptr));
SamplerState pointClamp = SamplerState::PointClamp;
spriteBatch_->Begin(SpriteSortMode::Deferred, BlendState::Opaque, &pointClamp, nullptr, nullptr, crt_.get());
spriteBatch_->Draw(*sceneTarget_, Rectangle(0, 0, width, height), Color::White);
spriteBatch_->End();

The calls follow CNA’s own crt_effect_demo (modules/graphics-ext/examples); the snippet was not compiled for this page. Tutorial 116 builds the same pipeline step by step, with DepthEffect and AsciiPostProcessEffect as well.

API style and ownership

Extension types follow C++ conventions rather than XNA’s: lowerCamelCase methods, getX()/setX() accessors and RAII ownership. CRTEffect and DepthEffect derive from ShaderEffect, so they are owned and disposed like any effect; AsciiPostProcessEffect and DebugDraw own their internal resources and must be destroyed before the GraphicsDevice they were created with.

Stability

The module is small and recent. Its API is not covered by any compatibility promise beyond CNA’s general pre-1.0 rule, and the C ABI routes in graphics_ext.h follow the C ABI’s own versioning (0.44.0 at this snapshot).

Test evidence and what is CI'd

• Tests in the tree: 6 test files with 76 GoogleTest-family definitions for the module, 6 example programs (ASCII atlas, quantizer and pixel tests, CRT and colour-depth demos) and one shader-package reproducibility test (PostProcessShaderPackageReproducibility).
• Recorded by CNA: CNA’s scope note records 78 of 78 retained-effect and graphics-profile tests, 4 of 4 ASCII examples and 17 of 17 focused C API tests passing with CNA_CNAEXT=ON on OPENGLES3, and a Vulkan compile, on 27 September 2026. That is CNA’s record, not a result we reproduced.
• CI: no workflow configures CNA_CNAEXT=ON or the cnaext preset.

Limits and open questions

• The ASCII effect pays a GPU-to-CPU readback every frame; a shader-only path is deliberately deferred so the effect keeps working on 2D-only renderers.
• The HLSL variants of the CRT and colour-depth shaders have not been shown to render on DIRECTX11 or DIRECTX12.
• DrawPrimitivesIndirectEXT and DrawIndexedPrimitivesIndirectEXT are declared on GraphicsDevice, but they take a renderer-internal argument buffer that no public class creates, so game code cannot use them.
• CNA’s own preset description and parts of its older CNAEXT notes still describe a larger module; the headers are authoritative.

Where to go next

• Tutorial 115: CNAEXT overview — the marker, the options and the strict-XNA check.
• Tutorial 116: post-process effects — CRT, colour-depth and ASCII effects on a scene target.
• Tutorial 114: PBR materials — PbrEffect, with image-based lighting and shadow inputs.
• Tutorial 117: the devices layer — CNA::Devices.
• Effects System, Shader Effects and the C API.