Content Pipeline

cna-content, cna_add_content() and the Content.Pipeline façade — CNA snapshot 009d40f5

What it is

The pipeline is the offline half of content handling. A source file goes through three stages, and the same importers and processors feed both output containers: only the last stage, the writer, differs.

source file  -->  Importer  -->  Processor  -->  Content type writer  -->  .cnb   (default)
 (PNG, WAV, glTF, ...)                                                       or .xnb   (--format xnb)

Quick start

Build the tool once from your CNA build tree, then point it at a directory of sources. The tool targets set no output-directory override, so with a single-configuration generator the executable lands at the top of the build tree (for example build/cna-content; a multi-configuration generator adds a configuration folder, and Windows adds .exe). See Building for configuring CNA itself.

# 1. build the tool (CMake target cna_content_tool)
cmake --build build --target cna_content_tool

# 2. compile every recognised source under ContentSource/ into Content/
./build/cna-content build ContentSource -o Content

# 3. ask why each asset was built or skipped
./build/cna-content build ContentSource -o Content --explain

# 4. compile a single file (the output extension must match --format)
./build/cna-content build ContentSource/Textures/wall.png -o Content/Textures/wall.cnb

# 5. remove what the pipeline wrote, and only that
./build/cna-content clean Content

A directory build keeps relative paths. Every output takes the source's path below the source root with the last extension replaced, and that path without an extension is the asset's logical name, the string you pass to Load<T>():

ContentSource/                      Content/
  Textures/wall.png        -->        Textures/wall.cnb          Load<Texture2D>("Textures/wall")
  Sounds/explosion.wav     -->        Sounds/explosion.cnb       Load<SoundEffect>("Sounds/explosion")
  Models/robot.glb         -->        Models/robot.cnb           Load<Model>("Models/robot")
                                      .cna-content-manifest.json
                                      .cna-content.lock

Source-to-output routes

These are the routes the stock cna-content registers, read from each importer's declared source extensions. In the two container columns, “Yes” means the container can hold the result and a dash means it cannot; the build reports why.

Command line

cna-content build <source-file | source-directory | .contentproj> -o|--output <output>
    [--format cnb|xnb] [--config <file>] [--workers <1..64>]
    [--xnb-platform <name>] [--xnb-version 4|5] [--xnb-profile reach|hidef]
    [--xnb-compress none|lzx|lz4] [--xnb-reader-names xna40|portable]
    [--xnb-allow-unverified-xbox]
    [--fx-compiler <path>] [--fx-compiler-launcher <program>]
    [--xma-encoder <path>] [--xma-encoder-launcher <program>] [--xma-encoder-arg <arg>]...
    [--font-directory <dir>]... [--build-configuration <name>]
    [--explain] [--quiet] [--xna-compatible] [--only-configured-assets]
cna-content clean <output-directory> [--quiet]

Exit codes: 0 on success, 1 when discovery or any build item fails, 2 for invalid command-line syntax.

Per-asset configuration

Convention-only builds need no configuration. When you want to rename an asset, choose a non-default importer, processor or writer, set processor parameters, or pick a container for one asset, add a strict JSON file named .cna-content.json in the source root (or pass --config <file>). Unknown fields, duplicate entries, unsafe paths and badly typed values are refused when the file is parsed.

{
  "format": "CNA.ContentPipeline.Config",
  "version": 1,
  "outputFormat": "cnb",
  "assets": {
    "Textures/wall.png": {
      "logicalName": "Textures/wall",
      "parameters": {
        "colorKey":         { "type": "string", "value": "255,0,255" },
        "generateMipmaps":  { "type": "bool",   "value": true },
        "premultiplyAlpha": { "type": "bool",   "value": true }
      }
    },
    "Models/level.glb": {
      "parameters": {
        "generateChildAssets": { "type": "bool", "value": true }
      }
    },
    "Music/theme.wav": {
      "importer":  "CNA.WavSongImporter"
    }
  }
}

The example assumes those three source files exist; a configuration entry that names a missing file, or a file with no importer, fails the build. The Music/theme.wav entry asks for the Song reading of a WAV instead of the default SoundEffect.

Each parameter is an object with a type and a value. The types are bool, i64, u64, f64 and string; the numeric types carry their value as a JSON string ({ "type": "u64", "value": "1200" }) so the persisted value is exact. Parameters take part in the build fingerprint, so changing one rebuilds that asset.

Texture parameters

The order is fixed: colour key, resize, premultiply, mip chain, block compression. We found no premultiplication in the loose-file image decode path that ContentManager uses for a plain PNG, whereas a pipeline-built texture is premultiplied unless you turn that off, so decide on one alpha convention per project and check how an asset looks when it comes from each route.

Other processor parameters

• Model (.gltf, .glb): generateChildAssets (bool). Without it, a source that yields more than one Model document is refused with a message naming the parameter. With it, the extra Models, animation clips and extracted textures are published as deterministic <logical name>_… siblings. Not accepted for .xnb output. Only the default glTF scene is imported.
• Song: streamReference (string, the root-relative media name), name (string), durationMs (u64).
• Video: streamReference, durationMs, width, height (u64), framesPerSecond (f64), soundtrackType (u64 0–2).
• Effect source (.fx): profile (reach/hidef), defines (NAME=VALUE;NAME), debug (bool).

Incremental builds

Every build reads and rewrites a manifest, .cna-content-manifest.json, in the output directory (manifest format version 9 at this snapshot, format identity CNA.ContentPipeline.Manifest). It records, per asset, the source and dependency hashes, the importer, processor and writer identities and versions, the parameters, and the SHA-256 of each published output. An asset is skipped only when all of those and the published output are unchanged.

[BUILD] <logical name> -> <output path> (<n> output(s), <bytes> bytes; <importer> -> <processor> -> <writer>)
  reason: manifest unavailable                  (only with --explain)
[SKIP] <logical name> -> <output path>
  reason: fingerprint and published output digests unchanged
Built: 1  Skipped: 1  Failed: 0

--explain reasons include manifest unavailable, new asset, primary source bytes changed, importer / processor / writer identity/version changed, processor parameters changed, source dependency bytes changed, content-build dependency effective fingerprint changed, compiled output missing and compiled output digest mismatch. Because component versions are part of the fingerprint, upgrading CNA rebuilds assets whose writers changed.

• Atomic publication. Each output is written to a temporary sibling and renamed over the destination (a replacing rename on POSIX, MoveFileExW with replace-existing on Windows), so a build whose process is killed or fails leaves the old file or the new file, never a prefix of the new one. Nothing is fsynced, so power loss or an operating-system crash is outside that guarantee. Staging happens in a private directory under the system temporary directory, and abandoned staging directories older than a day are scavenged.
• One writer at a time. A lock file, .cna-content.lock, in the output directory serialises builds and cleans; a second run reports that another content build or clean operation is active for the output root.
• The manifest is written only when every item succeeded. A failed item is counted in Failed: and the run exits with 1.
• Nested builds. A model whose materials name textures starts nested texture builds, and a processor can declare content-build dependencies, so dependent assets rebuild when what they depend on changes.
• Clean. cna-content clean deletes only files the manifest proves it owns and that are unchanged, then the manifest, and prints Cleaned: <n> Failed: <n>. It refuses a symlinked output directory.

CMake: cna_add_content()

CNA defines a CMake function that creates a build target running the same cna-content executable you would run by hand. It is available to any project that brings CNA in with add_subdirectory().

cna_add_content(
    TARGET MyGameContent
    SOURCE_DIR ContentSource            # relative to the calling CMakeLists.txt
    OUTPUT_DIR Content                  # relative to the calling binary directory
    # optional:
    # CONFIG_FILE ContentSource/pipeline.json
    # WORKERS 4
    # FORMAT xnb  XNB_PLATFORM windows  XNB_PROFILE reach  XNB_COMPRESS lzx
    # XNA_COMPATIBLE
    # QUIET
    # CONTENT_EXECUTABLE /path/to/host/cna-content
)
add_dependencies(MyGame MyGameContent)

• The target is not part of ALL. It is a custom target, so make your game depend on it with add_dependencies() as shown, or build it by name. It depends on cna_content_tool, so the tool is built first.
• It runs every time it is requested. The helper deliberately teaches CMake no second dependency model; the manifest makes an unchanged run a cheap per-asset no-op.
• A project file carries its own settings. CONTENT_PROJECT refuses FORMAT, XNB_*, CONFIG_FILE and XNA_COMPATIBLE, because accepting an option the file would silently override is worse than refusing it.
• Where the output lands matters at run time. A relative RootDirectory is resolved like any relative path, against the process's working directory; run the game from the directory that contains Content/, or set an absolute root.

Optional dependencies

The pipeline itself is always compiled. What varies is which inputs the build machine can read. Each switch below only affects the build-time tool; none of them changes what a game links.

The XNA Content.Pipeline façade

For XNA porters the pipeline also exposes the XNA-shaped API, Microsoft::Xna::Framework::Content::Pipeline, as a view over the canonical engine (not a second engine). It contains the importer, processor, ContentCompiler, intermediate-serializer and build-task types XNA Game Studio 4.0 had, implemented in C++ under modules/content-pipeline.

A .contentproj is read as MSBuild-free XML: <Compile> items are built, <Content> and <None> items are copied (honouring CopyToOutputDirectory and Link), and <Importer>, <Processor>, <ProcessorParameters_*>, platform, profile and compression are honoured. A conditional item group the reader cannot decide is refused by name rather than guessed at, and a project that names components this build lacks is refused with all of them listed while the rest are built. A <Reference> or <ProjectReference> to a game’s own pipeline assembly (anything other than Microsoft.Xna.Framework.*) is refused as well, because C++ cannot load a managed assembly: the build reports that it cannot load pipeline assemblies, still writes every asset whose importer and processor are built in, and then exits with status 1. Port such importers and processors to C++ and register them with RegisterXnaImporter<T> / RegisterXnaProcessor<T> in your own compiler (see Extending). Passing --xnb-platform, --xnb-profile or --xnb-compress overrides the project's own, the way an MSBuild property on the command line would.

./build/cna-content build MyGame/Content/Content.contentproj -o Content --build-configuration Release

To register your own XNA-shaped importer or processor with a registry, the bridge header CNA/Content/Pipeline/XnaPipelineBridge.hpp declares RegisterXnaImporter<T>(registry, className, attribute, version), RegisterXnaProcessor<T>(…) and RegisterXnaXnbOutput(registry, compiler, options). There is no assembly scanning in C++; PipelineComponentScanner enumerates what a registry holds. See Extending.

XNB output

--format xnb writes the container XNA's content pipeline produced. Every option below has a default chosen for maximum XNA 4.0 compatibility: Windows, container version 5, Reach profile, no compression, XNA-4.0 reader-name spelling.

./build/cna-content build ContentSource -o Content --format xnb \
    --xnb-platform windows --xnb-version 5 --xnb-profile reach --xnb-compress lzx

Writers exist for Texture2D, Texture3D, TextureCube, SpriteFont, SoundEffect, Song, Video, the vertex and index buffers, the five stock effects, compiled Effect, effect materials and external references, and Model, plus primitives, math types, Curve and a set of closed collections. Reading the same files back needs no registration inside a Game; see XNB Loading.

CNB output

The default output is one asset per .cnb file: a deterministic, little-endian container with a 64-byte header, a table of contents, CRC-32C checksums and typed payload chunks, plus two container chunks, metadata and a list of external asset names the file depends on (which is how a build script can ask what a Model needs, with cna_tool_cnb_info file.cnb --refs). It shares no code with XNB and has no reader tables. The byte layout, asset type identifiers, schema versions, read limits and the loading path are documented on CNB Format; Tutorial 146 writes and loads one from code.

Loading the result

Call sites do not change when the container does. ContentManager::Load<T>() tries, in order: the cache; <name>.xnb; <name>.cnb; a name that itself ends in .cnb; and then the type's loose-file reader (the literal path, a .cnj sidecar, then the reader's own extensions such as .png). So a compiled asset wins over the loose source it was built from, and a genuine .xnb wins over both.

void MyGame::LoadContent()
{
    getContentProperty().setRootDirectoryProperty("Content");   // relative to the working directory

    Texture2D   wall  = getContentProperty().Load<Texture2D>("Textures/wall");
    Model       robot = getContentProperty().Load<Model>("Models/robot");
    SoundEffect boom  = getContentProperty().Load<SoundEffect>("Sounds/explosion");
}

• Load<T> returns T by value; a failure throws ContentLoadException. From a Game the manager is getContentProperty(); there is no Content pointer.
• The .cnb loaders are built into ContentManager; nothing needs registering. A Game also registers the built-in XNB readers in its constructor.
• A .cnb declares its own asset type, so requesting the wrong C++ type is a ContentLoadException naming what the file holds.
• Whether a .cnb loads from a packaged-asset platform such as an Android APK is not something this page verifies: the .xnb tier reads through the platform's packaged-asset route, while the .cnb tiers use ordinary filesystem calls.

Extending the pipeline

You can add importers, processors and writers of your own by building your own copy of the compiler. The mechanism is source and toolchain compatibility, not a plugin ABI: nothing is loaded dynamically, and CNA marks the API experimental (ContentPipelineExtensionApiIsExperimental is true in CNA/Content/Pipeline/ContentPipeline.hpp). Registries are configured explicitly and frozen before discovery begins.

#include <filesystem>
#include <memory>
#include <vector>

#include "CNA/Content/Pipeline/ContentCompiler.hpp"

namespace Pipeline = CNA::Content::Pipeline;

// GreetingImporter : Pipeline::ContentImporter      (Identity, SourceExtensions, OutputTypes, Import)
// GreetingProcessor: Pipeline::ContentProcessor     (Identity, InputType, OutputType, ValidateParameters, Process)
// GreetingWriter   : Pipeline::ContentTypeWriter    (Identity, OutputSchemaIdentities, InputType, Write)

int main(int argc, char** argv)   // use wmain on Windows, as the example does
{
    std::vector<std::filesystem::path> arguments(argv + 1, argv + argc);

    auto registry = std::make_shared<Pipeline::ContentPipelineRegistry>();
    Pipeline::RegisterBuiltInContentPipeline(*registry);            // every stock route
    registry->RegisterImporter(std::make_shared<GreetingImporter>());
    registry->RegisterProcessor(std::make_shared<GreetingProcessor>());
    registry->RegisterWriter(std::make_shared<GreetingWriter>());

    // Same coordinator as cna-content: discovery, configuration, fingerprints,
    // incremental manifest, atomic publication, clean.
    return Pipeline::RunContentCompiler(arguments, std::move(registry));
}

• Component identities are {name, version} pairs; the version enters the incremental fingerprint, so bump it when a component's output changes.
• A processor receives typed parameters (bool, i64, u64, f64, string) and can add source dependencies, content-build dependencies, runtime references and deployment files through its context.
• To honour --fx-compiler and --fx-compiler-launcher, use the RunContentCompiler overload that takes a registry factory: the factory runs after the command line is parsed. Passing those options with a pre-built registry is refused rather than silently ignored.
• A custom .cnb asset type also needs a runtime loader: ContentManager::RegisterCnbLoaderEXT<T>(), with the identifier minted by CnbAssetTypeIdFromName(). Runnable examples: custom-content-compiler.cpp (the canonical API, target cna_custom_content_compiler_example) and xna-custom-pipeline.cpp (the XNA-shaped API, target cna_xna_custom_pipeline_example). Both examples build only under CNA_BUILD_EXAMPLES or CNA_BUILD_TESTS. Tutorial 148 covers custom types end to end.

Limits and what is not covered

Verification: what CNA reports

The statements in this section describe evidence CNA publishes about itself at this snapshot. The site did not re-run the oracle or the interop harness; treat them as CNA's claims with the scope stated.

Build success is not runtime proof. A produced asset must still be loaded, and graphics or audio content must be engaged on the renderer or device route you ship: an Effect, for instance, is written to .xnb on any host but loads only where the active renderer reports the CompiledEffects capability.

Windows CI

One workflow, content-pipeline-windows-ci.yml, builds and tests the pipeline on a native Windows runner. What it does and does not do at this snapshot:

• Trigger. Manual (workflow_dispatch) and pushes to a branch named content-pipeline-final. It has no trigger on next, so it is not part of ordinary automatic CI.
• Environment. windows-latest, native MSVC x64 with Ninja, Debug, CNA_PLATFORM=HEADLESS and CNA_GRAPHICS_RENDERER=HEADLESS, video and Draco off. It builds cna_content_tool and CnaContentTests only.
• Test gate. A GoogleTest filter over the configuration, manifest, pipeline, registry, Texture2D, SoundEffect, CNJ, Model, Song, Video, CNB codec, golden-vector and XNB-pipeline suites, excluding runtime-loading cases.
• CLI gate. Copies a small fixture to a path containing non-ASCII characters, runs cna-content build --workers 4 --explain and checks the [BUILD] line and the manifest unavailable reason; runs a second build and checks [SKIP]; runs clean; rebuilds and checks the output is byte-identical to the first build. Its last assertion greps the manifest for "version": 8, while the manifest version constant in the source at this snapshot is 9, so as written that step looks stale. We did not run the workflow.
• Not covered. No graphics, audio device, media playback or GPU work; no D3D or GDI renderer; no .spritefont (no FreeType) or FFmpeg route.

On Linux, the automatic platform-ci.yml workflow builds the content test executables in its SDL-free native X11 cell but runs only WAV and SoundEffect filters from them (*Adpcm*:*Wav* and *Wav*:*SoundEffect*). We did not trace which content-pipeline tests the unfiltered general-tests-ci.yml run registers, so this page makes no claim about them. See Verification & Known Issues for what CI gates across the project.