Tutorial 45: ContentManager and Asset Pipeline

CNA — C++ XNA 4.0 reimplementation

CNA's ContentManager provides the same Load<T> interface as XNA 4.0, and it reads three kinds of content: compiled .xnb binaries, compiled .cnb containers (CNA's own format), and open file formats such as PNG, glTF, WAV, OGG and .cnj descriptors. The ladder is fixed: an .xnb wins over a .cnb, which wins over the loose files.

ContentManager::Load<T> generic

#include "Microsoft/Xna/Framework/Content/ContentManager.hpp"
using namespace Microsoft::Xna::Framework::Content;
using namespace Microsoft::Xna::Framework::Graphics;
using namespace Microsoft::Xna::Framework::Audio;

// Inside Game::LoadContent():
auto& content = getContentProperty(); // returns ContentManager&
content.setRootDirectoryProperty("Content");  // under the title folder, else the working directory

// Load<T> returns T by value — not a pointer. A failed load throws
// ContentLoadException; there is no null to check.

// Texture2D — loads PNG/JPG/BMP from Content/textures/player.png
Texture2D tex = content.Load<Texture2D>("textures/player");

// Model — resolves Content/models/ship.xnb, then .cnb, then .cnj, then .gltf/.glb
Model model = content.Load<Model>("models/ship");

// SoundEffect — loads from Content/audio/explosion.wav
auto sfx = content.Load<SoundEffect>("audio/explosion");

// Song (streaming) — loads from Content/music/theme.ogg
auto song = content.Load<Song>("music/theme");

// SpriteFont — loads from Content/fonts/arial20.cnj
SpriteFont font = content.Load<SpriteFont>("fonts/arial20");

Supported asset types

ContentManager::RootDirectory

// The manager inside a Game (and ContentManager()) starts at "Content".
// ContentManager(IServiceProvider*) alone starts with an empty root, as XNA does.
// A relative root is looked up under the game's title folder (TitleLocation.Path)
// first, as in XNA, and otherwise relative to the process's working directory.
content.setRootDirectoryProperty("Content");

// Nested managers per state (one content manager per game screen)
ContentManager levelContent(&getServicesProperty(), "Content/Level1");

ContentManager::Unload()

Unload() clears the cache of every asset loaded through that ContentManager instance. Call it when transitioning between game states so the manager stops holding the assets. Because Load<T> returns copies whose GPU state is shared-owned, memory is actually reclaimed once the manager’s cache and every copy you kept are gone — reset your own holders too.

// On screen exit:
levelContent.Unload();
// The manager no longer caches anything it loaded for this screen.
// Copies you still hold remain valid until you drop them; pointers you took
// into them (for example a Texture2D* given to an effect) are yours to clear.

JSON descriptor formats

Only some content types have a descriptor. Texture2D and SoundEffect do not — the image or WAV file is read directly, and everything you might expect a descriptor to configure is set on the object in C++ instead. The types that do use one all share CNA's single .cnj document format, which carries a cnjVersion and a type that must match the C++ type you ask for.

Texture2D — no descriptor

There is no .texture.json. Load<Texture2D> resolves the asset name against .png, .jpg, .jpeg, .bmp, .gif, .tga, .tif, .tiff and .qoi, and decodes whichever it finds. Sampling and wrapping are not asset properties in XNA at all — they are device state you set at draw time:

Texture2D tex = content.Load<Texture2D>("textures/terrain");

// Wrapping and filtering are sampler state, not file metadata.
gd.getSamplerStatesProperty()[0] = SamplerState::LinearWrap;

SoundEffect — no descriptor

There is no .sound.json. Load<SoundEffect> reads a .wav file and nothing else. Volume, pitch and pan are per-playback values, so they are arguments to Play or properties of a SoundEffectInstance:

SoundEffect sfx = content.Load<SoundEffect>("audio/explosion");

// volume, pitch, pan — set at the call site, not in a file.
sfx.Play(0.8f, 0.0f, 0.0f);

.cnj (Model)

Geometry lives in the binary sidecars the descriptor names; the JSON just wires them together. Generate it with gltf_to_cnj rather than writing it by hand — see Tutorial 35.

// Content/models/ship.cnj
{
    "cnjVersion": 1,
    "type": "Model",
    "meshes": [
        { "name": "Hull",   "vertices": "ship_body_verts.bin",   "indices": "ship_body_idx.bin",   "vertexStride": 32, "effect": "BasicEffect" },
        { "name": "Engine", "vertices": "ship_engine_verts.bin", "indices": "ship_engine_idx.bin", "vertexStride": 32, "effect": "BasicEffect" }
    ]
}

.cnj (SpriteFont)

texture names the glyph atlas and is required — a descriptor without it raises a ContentLoadException. That name goes back through ContentManager, so the atlas is resolved and cached like any other texture. Each glyph carries source (its rectangle in the atlas), crop (the offset and size used when drawing), and kerning as XNA's three floats: left bearing, advance width, right bearing.

// Content/fonts/arial20.cnj
{
    "cnjVersion": 1,
    "type": "SpriteFont",
    "texture": "fonts/arial20_atlas",
    "lineSpacing": 24,
    "spacing": 0.0,
    "defaultCharacter": "?",
    "glyphs": [
        { "char": 32, "source": [0, 0, 6, 20],   "crop": [0, 0, 6, 20],  "kerning": [0.0, 6.0, 0.0] },
        { "char": 65, "source": [10, 0, 14, 20], "crop": [0, 0, 14, 20], "kerning": [0.0, 14.0, 0.0] }
    ]
}

.cnj (Effect)

The Effect descriptor has exactly two shader fields, vertex and fragment, each naming a GLSL source file relative to the content root, not to the descriptor's own folder. Missing either raises a ContentLoadException. Load it as Effect — the type the reader is registered for — then downcast to ShaderEffect. See Tutorial 52.

// Content/effects/wave.cnj (the shader paths are written from Content/, not from Content/effects/)
{
    "cnjVersion": 1,
    "type": "Effect",
    "vertex": "effects/wave.vert",
    "fragment": "effects/wave.frag"
}

Compiled content: .cnb and .xnb

Every loose format above can also be compiled ahead of time. The cna-content build tool turns a folder of PNGs, WAVs, glTF models, .cnj descriptors and more into .cnb files (the default) or .xnb files, keeping the same logical names, so the code in this tutorial does not change — the manager simply finds the compiled file first:

cna-content build ContentSource -o Content            # .cnb, one per asset
cna-content build ContentSource -o Content --format xnb   # XNA-compatible .xnb

Because compiled files outrank loose ones, a stale .cnb beside an edited .png keeps winning until you rebuild it. Tutorial 145 covers the workflow, incremental rebuilds and the CMake helper; Tutorial 146 covers the .cnb container itself.

Code example: load multiple assets, unload on state change

class MultiAssetGame final : public Game {
public:
    MultiAssetGame() : graphics_(this) {}

protected:
    void Initialize() override {
        Game::Initialize();
        state_ = GameState::Menu;
    }

    void LoadContent() override {
        // Menu assets use the global ContentManager
        auto& shared = getContentProperty();
        shared.setRootDirectoryProperty("Content");
        menuFont_     = shared.Load<SpriteFont>("fonts/title");
        menuBg_       = shared.Load<Texture2D>("ui/menu_bg");

        // Game-level assets in a separate manager so they can be unloaded
        gameContent_ = std::make_unique<ContentManager>(
            &getServicesProperty(), "Content/Game");
        playerTex_   = gameContent_->Load<Texture2D>("player");
        enemyTex_    = gameContent_->Load<Texture2D>("enemy");
        shootSfx_    = gameContent_->Load<SoundEffect>("shoot");
        levelModel_  = gameContent_->Load<Model>("level01");
    }

    void Update(GameTime& gameTime) override {
        auto kb = Keyboard::GetState();
        if (state_ == GameState::Menu && kb.IsKeyDown(Keys::Enter)) {
            state_ = GameState::Playing;
        }
        if (state_ == GameState::Playing && kb.IsKeyDown(Keys::Escape)) {
            // Free all in-game assets; menu assets remain loaded
            gameContent_->Unload();
            playerTex_ = {};
            enemyTex_ = {};
            shootSfx_.reset();
            levelModel_ = {};
            state_ = GameState::Menu;
        }
    }

    void Draw(const GameTime&) override {
        auto& gd = getGraphicsDeviceProperty();
        gd.Clear(Color::Black);
        // ... draw based on state_ ...
        // No gd.Present(): Game presents in EndDraw, after Draw() returns.
    }

private:
    enum class GameState { Menu, Playing };
    GameState state_ = GameState::Menu;

    GraphicsDeviceManager                  graphics_;
    std::unique_ptr<ContentManager>        gameContent_;
    Texture2D                              menuBg_;
    Texture2D                              playerTex_;
    Texture2D                              enemyTex_;
    Model                                  levelModel_;
    std::optional<SpriteFont>              menuFont_;   // no default ctor
    std::optional<SoundEffect>             shootSfx_;   // no default ctor
};