Model Loading & Rendering

Microsoft::Xna::Framework::Graphics — Model, ModelMesh, ModelMeshPart, runtime glTF, the gltf_to_cnj and cna-content pipelines, and CNAEXT skeletal animation

Overview

The Model class lives in the Microsoft::Xna::Framework::Graphics namespace and represents a complete 3D mesh asset ready for rendering. A Model holds a hierarchy of ModelMesh objects; each mesh in turn contains one or more ModelMeshPart entries that map directly to a single draw call. Every part references a VertexBuffer, an IndexBuffer and an Effect (the parts of one model may share them), the same shape as XNA 4.0. The shape is XNA’s; the behaviour is not identical: CNA keeps deliberate C++ deviations, such as skipping a part whose effect is null, a copyable Model value over one shared graph and several XNA-internal setters exposed as CNAEXT members. The runtime graph and draw contract lists them.

Loading glTF 2.0 at runtime

The simplest path needs no tooling step at all: drop a .gltf or .glb into your content root and load it like any other asset. glTF support is compiled into every build — there is no CMake option to enable, and the loader (a vendored copy of cgltf) is always present.

// No conversion step. Content/models/house.glb on disk:
Model house = getContentProperty().Load<Model>("models/house");

Load<Model> resolves candidates in a fixed order: name.xnb always wins first, then name.cnb (CNA’s compiled container, new in this snapshot), then — only when you passed a name ending in .cnb — that literal file, then a literal name on disk, then name.cnj, then the reader extensions .cnj, .gltf and .glb. Both JSON .gltf and binary .glb are handled, including external .bin buffers, base64-embedded buffers and images, and PNG/JPEG textures embedded in a buffer view. Only glTF version 2.0 is accepted. Because .cnb outranks the loose sources it was compiled from, you can keep hero.glb next to a built hero.cnb and the compiled file wins.

Both this direct path and the converter-backed .cnj path attach structured diagnostics to Model::getGltfImportReportEXTProperty(). Inspect its stable codes when an optional extension, a third distinct UV set, or another deliberately reduced feature needs your attention; do not rely on parsing warning text.

Runtime glTF: what is and is not imported

These limits were re-verified against the importer source at this snapshot. They are the ones people ask about most; the runtime path and the offline converter share one import core.

The extension registry

One source-owned registry of 21 extension records decides what extensionsRequired may name. CNA’s own limitations document is generated from it and checked against it by a test, so it does not drift from the code.

The importer is built on cgltf 1.15. CNA’s conformance corpus for it is described by CNA as renderer-owned goldens rather than a comparison with a reference renderer; see Verification & Known Issues.

The gltf_to_cnj tool

For the cases the runtime path deliberately does not cover, the gltf_to_cnj tool (target cna_tool_gltf_to_cnj, under tools/gltf_to_cnj/, built unconditionally with the project) converts glTF 2.0 into CNA's own .cnj JSON asset format. It emits one Model .cnj per mesh group, plus <name>_meshN_verts.bin/<name>_meshN_idx.bin/<name>.skeleton.bin sidecars, one .cnj per animation clip, morph sidecars, and extracted PNG/JPEG textures.

# cna_tool_gltf_to_cnj <input.gltf|.glb> <outDir> <baseName> [unitScale]
cna_tool_gltf_to_cnj input/house.glb Content/models house 0.01

Use it when you want one output asset per mesh group or a unit scale other than 1.0. Otherwise the runtime path is simpler and costs you nothing at build time. (.cnj is also an input to the .cnb tools below.)

Compiled models: .cnb and cna-content

New in this snapshot: models can be compiled at build time into CNA’s binary .cnb container, which ContentManager loads in the tier just below .xnb and above every loose source. Three tools produce it, and each route keeps a different subset of what a glTF file can carry:

See Content Pipeline for the full option list and Tutorial 145 for an end-to-end walk-through. The command-line catalogue is on Command-Line Tools.

Loading pipeline-built models from .xnb

If you are porting an existing XNA title, its models are already compiled into .xnb. CNA's XNB reader registers the full model reader family, so those assets load without conversion — ContentManager prefers an .xnb over a .cnb and over any loose file when both are present. A Game subclass registers the built-in XNB readers itself; only a ContentManager used outside a Game needs an explicit CNA::Internal::Xnb::RegisterAllBuiltInXnbReaders() call. See XNB Loading & Interoperability for the full picture, including what will not load.

Model API

ModelMesh

ModelMeshPart

Code Examples

1. Simple one-call draw

The simplest way to render a model. Model::Draw iterates every part, sets the world/view/projection matrices on each effect via IEffectMatrices, and issues the draw calls automatically.

model.Draw(world, view, projection);

2. Loading via ContentManager

Pass the asset name without extension. ContentManager resolves it against the content root, preferring an .xnb if one exists, then a .cnb, and otherwise reading the .cnj or glTF file, and returns a fully initialised Model by value.

Model model = getContentProperty().Load<Model>("models/house");

3. Per-mesh effect override

Override the default effect on each part to apply custom lighting or material properties per mesh. The BasicEffect cast means this loop only touches BasicEffect parts: a model loaded from direct glTF or a converted .cnj usually carries PbrEffect or SkinnedPbrEffect for its metallic-roughness materials, which the cast skips. Set the matrices through IEffectMatrices (example 4) and cast to a concrete effect type only for that type’s own properties.

for (ModelMesh* mesh : model.getMeshesProperty()) {
    for (ModelMeshPart* part : mesh->getMeshPartsProperty()) {
        if (auto* effect = dynamic_cast<BasicEffect*>(part->getEffectProperty())) {
            effect->setWorldProperty(world);
            effect->setViewProperty(view);
            effect->setProjectionProperty(projection);
            effect->setLightingEnabledProperty(true);
        }
    }
    mesh->Draw();
}

4. A bone hierarchy without skinning (rigid parts)

Call CopyAbsoluteBoneTransformsTo to obtain the absolute (model-space) transform of every bone. Multiply each mesh's parent-bone transform by the scene world matrix before setting it on the effect. This is the standard pattern for a rigid multi-part model — a vehicle with turning wheels, an articulated arm — and it is not skinning: the array is indexed by scene node and carries no inverse bind pose, so it cannot feed SkinnedEffect or SkinnedPbrEffect. A skinned model takes its palette from AnimationPlayer::GetSkinTransforms() (see Skeletal animation below).

std::vector<Matrix> transforms(model.getBonesProperty().getCountProperty());
model.CopyAbsoluteBoneTransformsTo(transforms);

for (ModelMesh* mesh : model.getMeshesProperty()) {
    ModelBone* parent = mesh->getParentBoneProperty();   // null only for an XNB mesh whose file names no parent
    Matrix meshWorld = transforms[parent != nullptr ? parent->getIndexProperty() : 0] * world;
    for (Effect* effect : mesh->getEffectsProperty()) {
        // IEffectMatrices covers BasicEffect and the other stock effects, including the PbrEffect and
        // SkinnedPbrEffect that glTF and converted .cnj models use; a dynamic_cast<BasicEffect*> would skip them.
        if (auto* matrices = dynamic_cast<IEffectMatrices*>(effect)) {
            matrices->setWorldProperty(meshWorld);
            matrices->setViewProperty(view);
            matrices->setProjectionProperty(projection);
        }
    }
    mesh->Draw();
}

Skeletal animation (CNAEXT)

XNA 4.0 gave you bones and SkinnedEffect and left clip playback to your game code — the well-known "Skinned Model Sample" existed precisely to fill that hole. CNA closes it in the framework itself, through a set of types tagged CNAEXT because they have no XNA counterpart. Direct glTF loading, the gltf_to_cnj converter and the .cnb route all deliver the clip data these types consume: a skinned model carries a SkinningData object on Model::Tag that AnimationPlayer is constructed from, and an unskinned model with rigid node animation carries ModelAnimationsEXT there instead (posed with ApplyClipToBonesEXT), so an animated glTF asset is playable end to end without writing a sampler. SkinnedModelEXT is a separate, self-contained type that these routes do not produce (it is loaded from a .skinnedmodel.json manifest).

Driving SkinnedEffect directly

The lower-level path remains available and is what the animation layer ultimately feeds. Set the bone palette with SetBoneTransforms(vector) and configure the number of skinning influences per vertex with setWeightsPerVertexProperty(n), where n is 1, 2 or 4.

auto* skinned = dynamic_cast<SkinnedEffect*>(part->getEffectProperty());
if (skinned != nullptr) {
    skinned->setWorldProperty(meshWorld);
    skinned->setViewProperty(view);
    skinned->setProjectionProperty(projection);
    skinned->EnableDefaultLighting();
    skinned->setWeightsPerVertexProperty(4);
    skinned->SetBoneTransforms(boneMatrices);  // std::vector<Matrix>
}