CNAEXT Engine Layer

CNA snapshot 009d40f5

CNA reimplements the XNA 4.0 API. Everything it adds on top — physically based materials, shadow generation, image-based lighting, a post-processing pipeline, compute passes, clipboard and file dialogs — is labelled as an extension, and the biggest body of it lives in one opt-in module. This page is the reference for that module: what “CNAEXT” means, what the engine layer contains, which renderers can run which part of it, how it is built and tested, and where its limits are. For a guided tour with code, start with Tutorial 115, then Tutorial 153 (image-based lighting) and Tutorial 154 (cascaded shadows).

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/RenderPipeline.hpp" succeeds in a default build and declares nothing, so the error you get is “no type named RenderPipeline”, 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.
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 engine layer")
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 engine-layer type; empty without CNA_CNAEXT

Where the tests and examples come from: engine-layer 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: engine_layer.h declares its routes in every build and they return CNA_RESULT_NOT_SUPPORTED when the layer is absent; the C ABI number (0.29.0) is independent of the engine-layer revision. See the C API page. Whether the C API library builds at this snapshot was not verified by us.
• No extra dependencies. The layer's shaders are embedded (11 packaged shader directories holding 156 GLSL source files, plus 11 package manifests and 11 generated headers; the manifests declare 208 shader payload entries. Regenerated by tools/shader_package/generate_shader_package.py); at run time nothing links a shader compiler.

From 12 to 98 headers

Alpha.1's graphics-ext was twelve files: AsciiPostProcessEffect, AsciiQuantizeMode, CRTEffect, CRTMaskType, DepthEffect, DepthEffectMode, DitherMode, PbrMaterial, RenderPipelineSettings, RenderQuality, ShadowQuality and TonemappingMode. RenderPipelineSettings was a configuration bag with no orchestrator to consume it. At this snapshot the layer is a real engine:

The counts are source counts made with a stated method (headers under modules/graphics-ext/include/CNA/Graphics/; TEST, TEST_F, TEST_P and TYPED_TEST macros under modules/graphics-ext/tests); they say nothing about how many tests pass. Note that 233 commits touch modules/graphics-ext between the alpha.1 tag and this snapshot, and much of the work was merged after the tag from side branches, so the tag contains none of it.

What the engine layer contains

Every header below is wrapped in #ifdef CNA_CNAEXT. Names are the C++ types under CNA::Graphics unless stated.

Which renderers can run it

The engine layer never assumes a renderer. Almost every shader-based subsystem asks the same two questions, and both must be yes:

1. Does the renderer accept custom effects? GraphicsCapability::CustomEffects (and ThreeD for shadows and the prepass).
2. Does a shader variant exist that this renderer takes? ShaderPackageEXT::selectFor(device) walks the package's languages in a fixed preference order and keeps the first for which GraphicsDevice::SupportsShaderLanguageEXT(language, stage) accepts every required stage (it also checks the package's binding requirements, such as 3D-texture sampling, and returns a diagnostic that says why a package was refused). The engine's packages contain GLSL ES (#version 300 es, and 310 es for compute), desktop GLSL (330 core, and 430 core for compute), SPIR-V and WGSL. The default answer for SupportsShaderLanguageEXT is false for every pair, and exactly five renderer families override it: EasyGL, OPENGL4, VULKAN, SDL_GPU and WEBGPU.

Shadow generation and shadow/IBL sampling are separate questions: generation is engine-layer work that needs the two answers above; sampling is a property of the receiving renderer (SupportsShadowSamplingEXT(), SupportsImageBasedLightingEXT()), and it is false by default. The table lists all 25 public renderer identities, grouped where the answer is identical.

Reading the table: engine shader subsystems can run on up to nine of the 25 identities — EasyGL's five profiles, OPENGL4, VULKAN, WEBGPU, and SDL_GPU in builds that have libshaderc. They cannot run on the DirectX renderers, METAL, FNA3D, SOFTWARE, PORTABLEGL, HEADLESS, STUB or any of the seven 2D-only identities, and that is a property of the shipped packages (no HLSL or MSL variant), not of those renderers' quality. Three cautions:

• The two ES-2-generation profiles are the least certain. OPENGLES2 and WEBGL1 report GLSL ES, but the engine's ES payloads are written for GLSL ES 3.00 and those profiles lack multiple render targets, instancing and 3D textures; whether individual passes compile on a live ES 2.0 or WebGL 1 context was not verified.
• Vulkan reports ExecutesShaderEffectSourceEXT() == false because it consumes SPIR-V rather than the GLSL text. The built-in passes override the base-class check with their own CustomEffects-plus-package test, so Vulkan runs them; a user-written PostProcessPass that keeps the default isSupported() would report unsupported there.
• The detailed capability profile is misleading for shader dialects on VULKAN and SDL_GPU: they report all six ShaderDialect* features unsupported even though they take SPIR-V. Ask SupportsShaderLanguageEXT(ShaderLanguageEXT::SpirV, ShaderStageEXT::Fragment) instead.

Requirements per feature

Each row is read from the subsystem's own isSupported() / construction code in modules/graphics-ext/src. “Package” means selectFor(device).isUsable().

How a renderer's “no” is handled

The layer's stated preference is to ask rather than throw. Every subsystem exposes isSupported() and degrades where a sensible fallback exists: a pass copies its input to its output, a shadow map leaves the scene unshadowed, a skybox draws nothing, order-independent transparency becomes sorted. Shadow maps, skyboxes and shader-compile failures log once in the renderer log category, naming the subsystem and what was missing; order-independent transparency records its reason in getTransparencyFallbackReasonEXT().

There is also a throwing route: CNA::Graphics::EngineException (with notSupported(subsystem, what, rendererName) and accessors getSubsystemProperty(), getRequirementProperty(), getRendererNameProperty()), and an internal detail::requireCapability(device, capability, subsystem) that throws it. In this snapshot no built-in subsystem calls requireCapability (we searched every module; only its own unit test does), and in library code EngineException is thrown by the CubeLut parser (malformed .cube files) and by requireCapability. Do not design around exceptions for unsupported renderers: design around the query methods.

A minimal example

Wrapping an existing draw in a pipeline is the layer's central promise: switch things on and the frame improves without the draw changing. This complete program uses the calls that CNA's own cnaext_render_pipeline_test uses (resize, getSettings, begin, end). It was syntax-checked against the snapshot headers with -DCNA_CNAEXT; it was not built or run.

#include "CNA/Graphics/CNAEXT.hpp"
#include "Microsoft/Xna/Framework/Color.hpp"
#include "Microsoft/Xna/Framework/Game.hpp"
#include "Microsoft/Xna/Framework/GraphicsDeviceManager.hpp"
#include "Microsoft/Xna/Framework/Graphics/GraphicsAdapter.hpp"
#include "Microsoft/Xna/Framework/Graphics/GraphicsDevice.hpp"
#include "Microsoft/Xna/Framework/Graphics/GraphicsProfile.hpp"
#include "Microsoft/Xna/Framework/Graphics/SpriteBatch.hpp"

#include <memory>

using namespace Microsoft::Xna::Framework;
using namespace Microsoft::Xna::Framework::Graphics;
using CNA::Graphics::RenderPipeline;
using CNA::Graphics::TonemappingMode;

class GlowGame final : public Game {
public:
    GlowGame() : graphics_(this) {
        // The HDR path wants float targets, which the default Reach profile refuses.
        if (GraphicsAdapter::getDefaultAdapterProperty().IsProfileSupported(GraphicsProfile::HiDef))
            graphics_.setGraphicsProfileProperty(GraphicsProfile::HiDef);
        graphics_.setPreferredBackBufferWidthProperty(960);
        graphics_.setPreferredBackBufferHeightProperty(540);
    }

protected:
    void LoadContent() override {
        auto& device = getGraphicsDeviceProperty();
        spriteBatch_ = std::make_unique<SpriteBatch>(device);
        white_ = std::make_unique<Texture2D>(device, 1, 1);
        const Color pixel = Color::White;
        white_->SetData(&pixel, 1);

        pipeline_ = std::make_unique<RenderPipeline>(device);
        pipeline_->resize(960, 540);

        auto& s = pipeline_->getSettings();
        s.setHDREnabled(true);
        s.setBloomEnabled(true);
        s.setBloomThreshold(0.6f);
        s.setBloomIntensity(1.2f);
        s.setTonemappingMode(TonemappingMode::Aces);
        s.setFXAAEnabled(true);
    }

    void Draw(const GameTime&) override {
        pipeline_->begin(Color::CornflowerBlue);   // draws below go to the scene target

        spriteBatch_->Begin();
        spriteBatch_->Draw(*white_, Rectangle(400, 200, 160, 120), Color::White);
        spriteBatch_->End();

        pipeline_->end();                           // runs the enabled passes, resolves to the back buffer
    }

private:
    GraphicsDeviceManager graphics_;
    std::unique_ptr<SpriteBatch> spriteBatch_;
    std::unique_ptr<Texture2D> white_;
    std::unique_ptr<RenderPipeline> pipeline_;
};

There is no Present() call: Game presents in EndDraw. On a renderer that cannot run the shader passes the same program still runs; each enabled pass copies its input, so the picture is the unprocessed sprite. To find out which it is, ask the passes rather than the renderer name:

const bool bloomRuns = CNA::Graphics::BloomPass(device).isSupported(device);
const bool shadowsRun = CNA::Graphics::ShadowMap(device, CNA::Graphics::ShadowQuality::Low).isSupported();

// Renderer-wide answers, when you need them:
const bool spirv  = device.SupportsShaderLanguageEXT(CNA::ShaderLanguageEXT::SpirV, CNA::ShaderStageEXT::Fragment);
const bool sample = device.SupportsShadowSamplingEXT();
const bool ibl    = device.SupportsImageBasedLightingEXT();

CNA::Logger::Info(CNA::Graphics::getEngineLayerVersionString(), CNA::LogCategory::RENDER);  // "CNA engine layer 18"

// A human-readable feature/limit/format dump for bug reports (returns std::string_view; do not parse it):
const std::string report{device.GetRendererCapabilityReportEXT()};

API style and ownership

The engine layer has its own style, and a lint check enforces it: verbs are lowerCamelCase (begin, end, addUserPass), accessors are getBloomThreshold()/setBloomThreshold()/isSupported(), and every get/is/has is [[nodiscard]] (and const when it takes no argument). The XNA-style getXProperty() spelling appears only on EngineException (getSubsystemProperty() and friends). UpperCamelCase functions exist only as named exceptions: XNA base-class overrides, System.Object mirrors, and AsciiPostProcessEffect::Draw/GetLastGridDimensions for the C ABI.

Ownership follows three public shapes and no public shared_ptr: objects that return resources hand you a unique_ptr (EnvironmentProcessor's cubes); passes and skyboxes you attach are borrowed pointers that must outlive the pipeline (addUserPass(PostProcessPass*), setSkybox(Skybox*)); some helpers are attached by reference. Nothing may outlive its GraphicsDevice, and the layer is not thread-safe. RenderPipeline subscribes to the device's reset event and drops its targets on a device reset (it can also be released explicitly with releaseDeviceResourcesEXT(), but not inside a frame).

Stability

• Pre-1.0, and the whole project says so. This is a development snapshot after the alpha.1 tag; CNA's own version string is still 0.1.0-alpha.1. Nothing here is a release.
• Revision 18. CNA_CNAEXT_ENGINE_VERSION (a macro, so it records what your headers said) and getEngineLayerVersion() (what the linked library was built with) start at 1 and rise whenever a consumer could notice a change — including additions. They exist so that a header/library mismatch is visible. They do not promise compatibility between two revisions.
• It has already broken callers. CNA's changelog records revision 2 as an incompatible rename of six members to lowerCamelCase plus a behaviour change (shadow and skybox isSupported() began asking for capability and source execution), then a burst of additions in revisions 3–18 (texture arrays, storage textures and buffers, base-instance and indirect draws, GPU timing, explicit shader languages, packages, selection and diagnostics, typed constant buffers).
• What is settled and what is not. The design note calls the shape of the layer, the ownership rules, the two-part support question and the naming conventions settled; per-renderer behaviour, capability queries and compute/storage are still moving. Its advice is to pin a CNA revision.
• The C ABI is separate. The C API's ABI version (0.29.0 at this snapshot) does not move with the engine-layer revision.

Test evidence and what is CI'd

CNA's own unit tests generally use small synthetic scenes and A/B comparisons (“the same frame with exactly one subsystem switched off”) rather than golden images, and its example programs say plainly which capability they need. That is honest evidence that a feature was exercised on a developer's renderer; it is not evidence about the other renderers in the table above, and it is not a comparison with any reference renderer.

Limits and open questions

• IBL products are 8-bit. EnvironmentProcessor writes SurfaceFormat::Color cubes and a Color BRDF table on the CPU, so a “high dynamic range” panorama is quantised before it is convolved. It is a load-time cost, and it works on any renderer that can create the textures.
• HDR needs the HiDef profile. The default profile is Reach, which refuses float render targets, multiple render targets, occlusion queries and 32-bit indices on every renderer; the engine layer's own examples request HiDef when the adapter offers it, and so should you (Tutorial 152).
• SSAO and friends need your help. Producing depth and normals means drawing your geometry a second time with a different effect, which only the game can do; RenderPipeline deliberately does not.
• Cascades are app-driven. RenderPipeline::setShadowScene drives a single ShadowMap; CascadedShadowMap, SpotShadowMap and CubeShadowMap are used by calling begin/end yourself, and the casters are drawn once per cascade.
• No Windows or Apple evidence. DirectX 9/11/12 and Metal are outside the engine layer's packages anyway; the SDL_GPU Direct3D 12 and Metal routes and the cross-build claims were not verified.
• Some CNA documents are stale against the code. CNA's own docs/cnaext-engine-layer.md renderer matrix (it says OPENGL4 has no shadow sampling or IBL, which the code contradicts) and docs/cnaext-engine-changelog.md (C ABI 0.26.0) lag the snapshot; and several header comments (PbrEffect.hpp saying there is no image-based lighting, FileDialog/MessageBox saying support is unconditional) predate the code. This page follows the code.
• The 12-to-98 growth is quantity, not maturity. The engine layer has no CI, one preset renderer, and a revision counter that CNA's changelog dates from revision 1 on 2026-08-18 to revision 18 on 2026-09-10.

Where to go next

• Tutorial 115: CNAEXT — extending beyond XNA — the marker, strict mode and the build gate, with code.
• Tutorial 153: Image-based lighting with PbrEffect — EnvironmentProcessor and ImageBasedLightEXT end to end.
• Tutorial 154: Cascaded shadow maps — CascadedShadowMap end to end.
• Tutorial 114: PBR materials, Tutorial 116: post-process effects, Tutorial 117: the Devices layer.
• Effects System, Shader Effects, Renderers, Experimental C API, Verification & Known Issues.
• In the CNA repository at this snapshot: modules/graphics-ext/include/CNA/Graphics/CNAEXT.hpp (the master include) and cnaext_showcase_test.cpp (every subsystem in one frame).