Chapter 38 Models, Meshes, and Drawing

Model owns a ModelBoneCollection and a ModelMeshCollection; each ModelMesh owns a ModelMeshPartCollection and a ModelEffectCollection; each ModelMeshPart references a shared VertexBuffer / IndexBuffer pair and an Effect. This is the same shape as real XNA. The reader-side contract is deliberately separate (and is covered by §38.4 below and Chapter 33); at runtime, the useful distinction is between a normally loaded, internally consistent model and a hand-built one. The latter can use several CNAEXT construction/mutation hooks, so it must preserve the invariants that a content reader normally supplies. The exact boundary, including the remaining intentional C++ safety deviations from FNA, matters more than a blanket claim of zero gaps. Model exposes CopyAbsoluteBoneTransformsTo, CopyBoneTransformsFrom / To, and a convenience Draw(world, view, projection); one small, intentionally-kept deviation from FNA is that CNA’s Copy*BoneTransforms* methods loop by Bones.Count rather than trusting the caller’s array length the way FNA does — strictly safer against an oversized destination array, never a compatibility problem for correctly-sized callers.

ModelBone carries Name, Index, a get/set Transform, its Parent, and a Children collection built via a CNAEXT AddChild. CNA also exposes setters for a ModelMesh’s BoundingSphere and ParentBone; FNA reserves both setters for its internal reader. They are useful for CNA hand construction and the XNB reader, but turn reader-populated metadata into caller-maintained state, which is exactly where the two model loaders and the draw contract below diverge sharply.

The simplest path is the convenience method already named above:

This is correct for a loaded, renderable model with at least a root bone, even if it has no interesting hierarchy to speak of. A real, multi-bone model (a character, a vehicle with independently-animated wheels) needs each mesh drawn with its own absolute bone transform composed into world space first — the classic pattern, grounded directly in the real CopyAbsoluteBoneTransformsTo and IEffectMatrices signatures:

boneTransforms[mesh.getParentBoneProperty()->getIndexProperty()] selects the mesh’s parent-bone absolute transform, not bone 0 or the model root. The former loose-JSON route assigned one default bone to every mesh and welded parts together. That defect is fixed; the example applies to current XNB, CNJ, and direct glTF/GLB outputs.

Model::Draw is deliberately a thin convenience path, not a validator or a general scene graph. It retains one thread_local static vector of absolute bone matrices (the same scratch-buffer shape as FNA’s static array, but one instance per thread), grows it only when a later model on that thread has more bones, copies the absolute transforms into it, then visits every mesh. For every distinct effect listed by that mesh it requires the matrix interface, writes boneMatrix * world, view, and projection, and only then asks the mesh to issue its part draws. An effect in the mesh’s effect collection that does not implement that interface is therefore a hard runtime_error; it is not silently ignored or drawn with some other matrix convention.

That compact loop establishes three input invariants which a normal content load satisfies, but which the public/extended hand-build API does not enforce:

• •

  A renderable mesh needs an applicable bone matrix. CNA deliberately treats a null ParentBone as bone index 0, whereas FNA immediately dereferences the mesh parent to obtain its index and fails for null. This is a sensible C++ safety improvement for a one-root-bone hand-built model, and the real EasyGL/Bgfx hierarchy pixel tests exercise it for their root mesh. It does not make a zero-bone model renderable: with a positive-effect mesh, index 0 is outside an initially empty scratch vector; after another model has grown that thread’s vector, it can instead reuse that earlier model’s stale slot. FNA’s static array is likewise retained, but its usual null ParentBone path fails first rather than recovering. Give every model that can draw at least one bone, and give each mesh a parent explicitly when it is not that root.

• •

  CopyAbsoluteBoneTransformsTo computes slots in collection order. A child therefore has to name a parent whose result was already written; it neither topologically sorts nor detects cycles, duplicate parents, or an index that disagrees with the vector position. The XNB reader’s malformed-graph boundary is documented in Chapter 33; the same ordering rule applies to a hand-built graph.

• •

  The manual loop in the previous section intentionally dereferences the mesh parent pointer so that an invalid attachment is visible at the call site. Unlike Model::Draw, it has no null-to-root fallback. Well-formed outputs of the current loaders assign a mesh parent, but an XNB shared-resource reference of zero can still leave it null; a manually assembled mesh must either set one or choose and check its root fallback before indexing boneTransforms.

ModelMesh::Draw has a different, narrower safety rule: it skips a part with a null Effect or a non-positive PrimitiveCount. FNA skips only the latter, then dereferences a null effect, so the CNA skip is another deliberate no-undefined-behaviour deviation. It does not validate the remaining draw fields: a positive-count part still passes its raw vertex buffer, index buffer, offsets, vertex count, start index, and primitive count to GraphicsDevice. A missing buffer or invalid range consequently fails at the graphics-device/renderer boundary rather than becoming a harmless skipped part. This is why a model’s successful construction is not proof that it is drawable.

The old two-loader and .model.json framing no longer describes the resolver. CNA now has four distinct model-producing paths: the wire-compatible XNB ModelReader, self-contained .cnj, direct .gltf/.glb, and the older Avatar-specific .skinnedmodel.json reader. The first three return the ordinary Model; the fourth returns SkinnedModelEXT, a separate runtime type that must not be mistaken for another serialization of the same graph. For an extensionless cache miss, ContentManager looks for name.xnb, then a literal name, then name.cnj, name.gltf, and name.glb. Thus a same-named CNJ hides a glTF/GLB asset, and an XNB sibling hides both; passing an existing literal name.gltf explicitly reaches that literal before the extensionless sidecar probe. The full resolver contract is in Chapter 33; the resulting runtime graphs are the important distinction here.

The real .xnb ModelReader

(CNA::Internal::Xnb::ModelReader) is wire-compatible with real XNA/MonoGame/FNA compiled model assets. It reconstructs the full bone hierarchy, assigns each mesh’s serialized ParentBone, computes its serialized BoundingSphere, and resolves shared VertexBuffer/IndexBuffer/Effect resources. Its exact malformed-graph, draw-field, tag, and shared-resource boundary is covered in Chapter 33.

The self-contained .cnj ModelTypeReader route

validates a Model CNJ envelope and rejects sourceFile; the former .model.json name survives only in historical comments and test-target names, not in this reader’s extension list. A version-2 descriptor reconstructs its complete parent-before-child bones array and attaches every mesh to the indexed parentBone; this is how the converter preserves the selected glTF scene hierarchy and rigid placement. A version-1 descriptor (or one without a general hierarchy) retains the older compatibility shape: one root plus a synthetic named child bone per mesh. An optional skeleton/animations sidecar pair builds SkinningData on Model.Tag, and morph data lives on the corresponding part’s Tag.

This route still leaves BoundingSphere degenerate and ModelMesh.Tag null. It allocates a fresh vertex/index buffer and built-in stock effect for each described mesh part; a named custom effect instead goes through the manager’s cached shared_ptr<Effect> route. This is not XNB’s serialized shared-resource graph, even where repeated custom-effect names happen to share a cached object.

The direct .gltf/.glb ModelTypeReader route

parses glTF 2.0 and its buffers without producing a CNJ or binary sidecars first. It reuses the offline converter’s import core, including sparse-accessor-safe extraction, topological skin ordering, material/image extraction, and morph/animation data. Its runtime shape is one Load<Model> containing the selected scene’s mesh placements, including independent skin groups, with a fixed unit scale of 1.0. Model::SkinsEXT preserves each skin-to-mesh mapping while the legacy Model.Tag convention aliases the first skin. Convert offline when a scale factor or one-output-per-group asset layout matters.

Direct glTF creates an identity synthetic root followed by one ModelBone per reachable node of the selected scene, in parent-before-child order. A rigid mesh is attached to its instancing node; a skinned mesh is attached to the synthetic root so the skin palette does not double-apply the mesh-node transform. The separate reordered skin hierarchies are retained through Model::SkinsEXT; morph targets and their tracks are retained on each ModelMeshPart.Tag. Imported cameras live in Model::CamerasEXT; material variants have a source-order selection API; and GltfImportReportEXT records counts plus named dropped/approximated features. Extracted images are decoded in memory and cached by glTF image pointer during that one import, but mesh buffers and effects remain per primitive.

The legacy .skinnedmodel.json route

dispatches to SkinnedModelTypeReader and produces SkinnedModelEXT, the Avatar-oriented runtime described later in Chapter 41. It is neither a CNJ alias nor the historical name of the current Model descriptor. Code loading it opts into a different public type, animation representation, and draw path; its continued presence is therefore a compatibility route, not evidence that the generic Model reader accepts a fourth file spelling.

The evidence is much stronger than the old chapter wording suggested. The focused CNJ tests cover descriptors, envelope rejection, report persistence, variants, cameras, and shared clips. The generated glTF corpus and its L1–L7 ladder cover scene graphs, multiple skins, rigid and skeletal animation, morphs, material state, and pixels; Chapter 43 states the exact denominators. Those tests do not make the four routes interchangeable: use XNB for compiled XNA asset fidelity, CNJ for a controlled self-contained/imported description, direct glTF/GLB for an in-process glTF 2.0 import, and the legacy route only when the application consumes SkinnedModelEXT.

Model is a copy-constructible C++ value, but copying it is not a deep model clone. Its compiler-generated copy operation copies the two collection vectors, Root, and Tag as raw pointers, while copying its private type-erased shared_ptr<void> ownership handle. The vectors are separate little wrappers after the copy, but every ModelBone, ModelMesh, ModelMeshPart, buffer, effect, and the graph below them is the same object. A bone-transform or part/effect mutation observed through one copy is therefore observed through every copy; this is shared mutable model state, not a way to pose or material-override one instance independently.

Each normal reader intentionally fills that last ownership handle before returning. The XNB reader’s private bundle retains unique bones, meshes, and parts plus shared vertex buffers, index buffers, and effects. The CNJ and direct-glTF routes share a corresponding bundle which also retains their buffers, graph objects, effects, decoded textures, skinning data, and morph data. That is why a cached or caller-held loaded Model can safely keep the raw pointers used by its collections: the bundle itself is shared among every copy. It also explains why CNJ/glTF’s Model.Tag and part Tags remain valid while such a model lives — their SkinningData and morph objects are in that same bundle. XNB rejects non-null serialized Tags, so it has no analogous reader-provided Tag object to retain.

The visible cache behavior follows directly from that representation:

The real XNB test checks the decisive GPU identity part of this rule: two loads expose the same underlying VertexBuffer, not a fresh decode/upload. The generic content-cache and Unload() tests separately prove cache eviction, but no located test holds a Model through Unload(), copies one and checks a shared mutation, or exercises the final bundle destruction. The code makes the first two outcomes clear; the missing tests remain an evidence boundary rather than permission to assume a complete shutdown protocol.

There are two qualifications to “shared” worth keeping precise. Reassigning the top-level Tag changes only that particular C++ wrapper’s raw pointer; it does not rewrite another wrapper’s Tag field, although both initially point to the same reader-owned object. In contrast, a mesh Tag or a bone/part/effect change is made on the shared pointed-to graph and is visible through all copies. FNA returns its cached Model class reference, so ordinary managed assignment aliases even the top-level wrapper; CNA’s value syntax is consequently not a deep-copy compatibility promise.

CNA ships two separate, unrelated systems for animated meshes, and conflating them is an easy mistake to make. AnimationPlayer (CNAEXT, mirroring Microsoft’s own unshipped XNA “Skinned Model Sample” reference code rather than anything in the framework assembly itself) drives a bone-track timeline: StartClip(clip), Update(TimeSpan, relativeToCurrentTime, loop=true), and GetBoneTransforms() / GetWorldTransforms() / GetSkinTransforms() — the last of which is exactly what feeds SkinnedEffect::SetBoneTransforms (Chapter 15). Its skinning data (bone count, hierarchy, bind pose, inverse bind pose, animation clips) is stashed on a loaded Model’s own Tag — the same convention the original Microsoft sample used, since real XNA’s Model has no dedicated skinning-data property of its own to hold it in.

MorphTargetEXT (also CNAEXT) is a completely independent, glTF-style morph-target blending system: CPU-side re-blend plus a full vertex-buffer re-upload on every call to SetMorphWeightsEXT, a deliberate simplicity-over-throughput tradeoff. Because glTF’s “weights” animation channel targets a mesh instance node rather than a bone index, this system has no relationship to AnimationPlayer’s bone timeline at all; it supports linear, step, and real cubic-spline (Hermite) interpolation, and attaches itself via a loaded ModelMeshPart’s own Tag — the same attachment convention, applied to a different object in the hierarchy, for a different purpose.

A third, still more separate system exists for the Avatar subsystem specifically: SkinnedModelEXT (its own .skeleton.bin / .clip.bin binary formats) is deliberately not built on Model / ModelBone / ModelMesh at all, has its own full test coverage, and is covered alongside the rest of the Avatar system in this book.

Model’s hand-build constructor had a real, previously-undocumented gap versus FNA, confirmed by reading FNA’s own Model.cs directly: FNA’s constructor never sets Root at all — it is real XNA’s own ModelReader that assigns model.Root = bones[rootBoneIndex] afterward, where rootBoneIndex can name any bone in the model, not necessarily the first one. CNA’s original 4-argument constructor (the one that also accepts meshParentBones) had no equivalent parameter at all, silently defaulting Root to bones[0] unconditionally — correct for the common case, but unable to represent a hand-built model whose true root bone is not the first entry in its own bones vector.

The fix is a fifth, defaulted constructor parameter, additive-only so no existing call site’s behavior changes:

One edge case is worth reasoning through explicitly, because a naive implementation gets it wrong: an empty bones vector must leave Root as nullptr regardless of the requested index, rather than throwing on the harmless default value 0 — the real constructor body checks emptiness first, matching the existing 3-argument constructor’s own leniency, and only bounds-checks rootBoneIndex against a genuinely non-empty bones vector:

The real regression tests earned by this fix (ModelTests.cpp) are worth naming for the verification technique they demonstrate, not just their existence:

The nonzero-index case uses a three-bone hierarchy, selects index 2, and checks both equality with the expected bone and inequality with bone 0. A test that only checked equality could pass even if the parameter were silently ignored and the implementation happened to default to the requested bone by coincidence. The fix’s own commit history records a real sabotage-and-revert check applied to confirm these tests actually exercise what they claim to: with the constructor temporarily edited to ignore rootBoneIndex entirely (falling back to the old, hardcoded bones[0]), exactly the two tests that depend on honoring a non-default index failed as predicted, while the other 24 ModelTest.* cases were unaffected — the same discriminating-power methodology this book applies throughout (a test suite’s own ability to catch a real regression is itself worth verifying, not assumed from the fact that it currently passes).

This fix closes the hand-build runtime-API gap only. Neither loose route calls the five-argument constructor, and both reserve index 0 as their root. Direct glTF/GLB appends one ModelBone per reachable selected-scene node beneath a synthetic identity root; a generated version-2 CNJ serializes and reconstructs that same parent-before-child array. The version-1 CNJ fallback instead appends one synthetic child per mesh. A glTF skin’s independently reordered palette hierarchy still lives in SkinningData, not in the model-bone index space. Consequently neither route has a serialized arbitrary rootBoneIndex for this constructor parameter to represent. The gap is closed for a hand-built model, but remains deliberately inapplicable to the two loose content routes; the reader-specific distinctions are tracked in §38.4, not hidden by the runtime fix.

The four model collections deliberately expose C++ iteration rather than FNA’s managed enumerators, but they do not have one identical API.

ModelBoneCollection has checked integer lookup, name lookup, TryGetValue, Contains, and iterators. Its storage is populated by Model or a bone’s CNAEXT AddChild; name lookup returns the first matching name, so names are useful handles, not enforced unique identifiers.

The mesh collection has the same named-lookup family. Its integer lookup is checked, as is the bone collection’s, so an invalid index throws rather than invoking C++ undefined behaviour. One small FNA divergence remains: FNA rejects a null or empty mesh-name argument before searching, while CNA’s std::string API has no null spelling and accepts the empty string. It can consequently return a deliberately empty-named mesh or simply return false. Do not use an empty name as a portable not-supplied sentinel.

ModelMeshPartCollection has checked integer access, Count, and iterators — there is no part name, Contains, or TryGetValue. Its operator explicitly rejects a negative index and one greater than or equal to Count with ArgumentOutOfRangeException, matching the bone/mesh collections rather than exposing raw vector[] behaviour.

ModelEffectCollection likewise has integer access, Count, Contains, and iterators, but no name lookup or TryGetValue. Its integer operator has the same explicit negative/upper-bound checks. Its mutable operations are the CNAEXT escape hatches described in §38.3, not a fourth normal collection-builder API.

All name searches are linear and return the first matching pointer; neither loader nor collection constructor rejects duplicate names. The focused bone/mesh suites cover normal name/index/iterator behaviour and missing names, while ModelCollectionIndexTests.cpp checks negative, Count, and above-count indices for all four collection families plus first/last identity. No located collection test covers the empty-name FNA difference. The safe cross-collection rule is therefore simple: keep the model’s ownership and topology coherent at construction time and use name lookup only where that collection actually exposes it; invalid integer indices fail loudly but are still caller errors.