Meshes and materials, type by type

A map of the two most overloaded words in the tree. Neither mesh nor material names a type in Vixen; each names a chain of types — one link per stage of the same journey, from the file an artist saved to the bytes a draw call binds — and every link is a different shape because every stage has a different constraint. Most of the confusion in reading this code is mistaking two links of one chain for two competing designs. The rest of it is that four unrelated subsystems use the same two English words for something else entirely, and their types sort next to these ones alphabetically.

The chain exists because no one form can satisfy every stage. A file cannot hold a descriptor set or a compiled shader variant, so the authored form is names and numbers. A shipping runtime links no YAML parser — that is a deliberate exclusion, recorded in Vixen.Rendering's project file — so the content form is a baked chunk rather than the text. A frame reads per-object data out of native arrays with no indirection, so the frame form is a value type holding handles. Collapsing any two of those into one type does not simplify anything: it makes one of the stages carry a field it cannot fill.

The word "material" splits once more than "mesh" does, and that split is the one worth learning first. MaterialDescriptor is what MaterialCompiler consumes; MaterialContent is what an asset address resolves to. They look like duplicates and are not — content names its shading model as a string so a document can carry a model this build has never heard of and be told so by name, and it carries the texture assignments, which the compiler has no use for and a host does.

You do not need most of this. Putting a crate in a level is three types — MeshRenderable, AssetReference, and whichever material the artist made. Everything below the scene row is the engine's own plumbing, and the only reason to read it is that you are changing it, or that a name collided with one you were looking for.

⚠ "Feature" means two unrelated things, and they are one namespace apart. An IMaterialFeature in Vixen.Rendering.Materials is a contribution to a surface — a normal map, a clear coat — that becomes one link in a shader's composition chain. A RenderFeature in Vixen.Rendering.Features is a slice of the renderer that owns one parallel array per render object. MaterialRenderFeature is the second kind, and it is not a material feature. Nothing is going to rename either of them; the namespace is the discriminator.

⚠ The device-side geometry store is called Geometry, not Mesh. GeometryBuffer, GeometrySlice, GeometryResidency and GeometryKey are where a MeshData ends up once it is on the device, and SurfaceGeometry is the one function that converts between the two. If you are looking for "the vertex buffer my mesh lives in", it is not in a file with Mesh in its name.

The shader half lives in Raven rather than in C#:

⚠ A feature writes channels; a shading model reads them. That split is what keeps both sets small, and it is why the C# and Raven sides have the same seven names on one axis and thirteen on the other.

MaterialRenderFeature.PermutationKeys is a PermutationKeyDictionary: shader name → the keys that shader's effect key is built from. A host states a pass's set in one line, with the array the shader's own reflection produced:

⚠ A key set under a name that list does not carry reaches no compiler at all — the variant resolves to whatever the .rvn declares as its default, an effect resolves, a pipeline binds and a frame draws. That is the trap the whole type exists around.

⚠ And a composed surface's permutation is in no pass's reflection. LayerCount is declared by TexturedMaterialLayersSurface, not by ForwardPlus, so the generated array above cannot carry it and a host assigning that array is not making a mistake by leaving it out. The engine registers it with PermutationKeys.Register(shader, key) when the renderer is built — and a later assignment cannot take a registered key away, which is the reason this is a type of its own rather than a Dictionary. It was a dictionary once, the host line ran after the engine's, and every host that drew compiled three-layer materials as two-layer ones without a word.

⚠ HeightBlended is the same key one knob over and its unregistered failure is quieter. An unregistered LayerCount draws the wrong number of layers; an unregistered HeightBlended leaves the variant at the shader's false, so the height map a material paid for is never sampled and the old blend is drawn — plausibly, with nothing anywhere saying the feature did not run. MaterialKeys names both and the engine registers both.

Same word, unrelated meaning. Sorting alphabetically next to a rendering type is the whole reason they are confusing.

Building a material with no file at all, which is what the compiler is for and what a test does:

Nothing there touches a graphics device, a shader compiler or a frame — which is the property that lets a material be authored and validated in an editor that has not opened a window yet.

The same material as a file, which is the form an artist actually produces. The tags are the [DataContract] names of the feature records above:

MaterialImporter reads that at build time and writes a MaterialContent chunk. A shipping build never sees the text.

Putting a mesh and a material on an entity — the scene row of the first table, and all most code ever needs:

⚠ CastsShadows is spelled out because a zeroed struct says false. MeshRenderables.Default sets it for the same reason, and the editor's Add Component goes through that — but a renderable built field-by-field, as above, casts nothing unless the line is there. What it costs when it is not set is a stage bit, so it only bites in a project that has named its caster stages; see shadows for that wiring and for why toggling the flag on a live scene needs MeshExtractionSystem.Resettle.

⚠ A null material reference is a usable value, not a mistake. A block-out mesh dropped into a level before anybody has made a material for it draws with MeshExtractionSystem.Material, the renderer's neutral default. A null mesh reference is different: nothing is drawn, because an entity whose shape depended on disk speed would be worse than one that is late.

Joining the renderer to the content manager, which is what makes either reference mean anything. Vixen.Rendering deliberately knows nothing about bundles, so a host supplies the two sources:

Leave either null and the corresponding entities are simply never extracted — which is what a project with no content mounted is, and why an unwired renderer draws an empty frame rather than throwing.

MaterialRenderFeature.Textures is the bindless table the whole frame samples through, and a host creates one only where the device reports HasBindless — which GL, GLES, WebGL2 and MoltenVK below argument-buffer tier 2 do not. Nothing refuses to author or to compile a material with a sampling feature for those targets: the variant declares the table's descriptor set because the feature was composed into it, and the table's absence is the host's answer arriving later.

⚠ The two together are a five-set pipeline layout drawn with four sets bound, which is undefined rather than untextured — a validation error where the layers are on, and a descriptor read out of whatever the driver left at set 4 where they are not. So MeshRenderFeature refuses those draws rather than recording them, counts them in RefusedTableDrawCount, and says once per degrade — log event 4005 in docs/manual/log-events.md, through MeshRenderFeature.Logger — which shader and which stage. A mesh missing from a frame with nothing logged is the failure this pair exists to rule out: DrawCount says what was recorded and RefusedTableDrawCount says what was not, and a frame where the second is the whole scene is one material composed for a device that cannot draw it.

• Turning on dynamic global illumination — what lights the surfaces these materials describe.
• Components — what makes MeshRenderable a component, and why RenderHandle is not one.
• Getting content into a running game — how a MeshData or a MaterialContent chunk reaches a build.

The design records are docs/plan/06-rendering-pipeline.md for the render features and the extraction split, docs/plan/07-raven-shader-pipeline.md for composition and permutations, docs/plan/08-asset-pipeline-and-addressables.md for the importer/compiler split every …Importer here follows, and docs/plan/23-bindless-materials.md for why MaterialRecords exists at all.