How khronosgroup/gltf-csharp-loader works
1. Repository purpose
- This is a C# reference implementation of a glTF loader.
- The public entry point is the glTFLoader library, which exposes a simple API such as Interface.LoadModel("PathToModel.gltf").
2. Top-level architecture
- The repo is split into three main concerns:
- Code generation tooling: Generator, GeneratorLib, GeneratorSchema
- Runtime loader library: glTFLoader
- Validation/tests: GeneratorUnitTests, glTFLoaderUnitTests
- This separation is important: the schema model is generated, while the loader logic is handwritten.
3. Schema generation pipeline
- GeneratorSchema contains the machinery for reading glTF schema/spec input and turning it into an internal representation.
- GeneratorLib converts that representation into C# type definitions.
- Generator is the executable that drives the generation process during the build.
- The README indicates the generator consumes .spec files from the glTF repository and produces the schema classes used by the loader.
4. Generated schema layer
- The glTFLoader/Schema folder contains the generated C# model types for the glTF format.
- These types mirror the glTF domain model: Gltf, Node, Mesh, Material, Accessor, Buffer, Scene, Texture, Animation, Skin, and related child objects.
- This layer is the primary data model boundary between parsed JSON and the loader API.
5. Runtime loader responsibilities
- glTFLoader is the runtime assembly that consumers reference.
- It contains the public interface (Interface.cs) and helper utilities for reading model files and converting them into the generated schema objects.
- ArrayConverter.cs and StreamExtensions.cs suggest custom handling for JSON array shapes and stream-based file reading, which are key pieces of the parsing pipeline.
6. Data flow from file to object graph
- A glTF file is loaded through the public API.
- The loader reads the file stream, parses JSON into the generated schema classes, and builds the in-memory representation of the model.
- The result is a strongly typed object graph rooted at Gltf, with references across nodes, meshes, materials, buffers, and textures resolved through the schema structure.
7. Modeling strategy
- The schema types are organized around glTF inheritance and composition:
- base/shared primitives like GltfProperty, GltfChildOfRootProperty, Extension, Extras
- domain objects like Accessor, MeshPrimitive, AnimationSampler, CameraPerspective
- This indicates the loader is oriented around faithfully representing the standard rather than abstracting it into a higher-level engine-specific API.
8. Generator architecture
- GeneratorLib includes factories such as ArrayValueCodegenTypeFactory and SingleValueCodegenTypeFactory, implying the generator handles different schema field shapes differently.
- CodeGenerator, CodegenType, and CodegenTypeFactory form the internal generation model.
- The generator likely translates schema metadata into C# class declarations, properties, and converters.
9. Testing boundaries
- GeneratorUnitTests validate the generation and schema parsing logic, protecting the codegen pipeline.
- glTFLoaderUnitTests validate loader behavior against real sample models.
- The README references the separate glTF-Sample-Models repository, so test coverage depends on external canonical test assets.
10. External dependencies and build assumptions
- The solution depends on the glTF schema source repository and the glTF sample models repository being checked out alongside this repo.
- This matters architecturally because the generated schema is not fully self-contained; it is derived from upstream glTF spec inputs.
- The resulting package is published as a NuGet library (glTF2Loader per the README), making the loader consumable from other C# projects.
11. How to think about the boundary for a diagram
- Draw one boundary for schema generation inputs coming from upstream glTF spec files.
- Draw a second boundary for generated schema types in glTFLoader/Schema.
- Draw a third boundary for the runtime loader API that reads .gltf/model data and returns typed objects.
- Tests sit beside these boundaries and verify both code generation and runtime parsing.
Main entry points: Gltf.cs Gltf root · CodeGenerator.cs Codegen core · Interface.cs Loader API · SchemaLoader.cs Schema loader
Components 20
External inputs
Upstream glTF spec files and sample assets consumed by tooling and tests.
- glTF spec · External .spec/schema inputs from the glTF source repository.
- Sample models · External glTF sample files used to validate loader behavior.
Generation
Schema parsing and C# code generation pipeline.
- Generator · Executable that drives schema generation during the build.
Generator/Program.cs - Schema loader · Loads schema input into the generator's internal representation.
GeneratorSchema/SchemaLoader.cs - Schema parser · Parses schema/spec structure into generator-friendly objects.
GeneratorSchema/SchemaParser.cs - Schema model · Internal representation of the glTF schema used by code generation.
GeneratorSchema/Schema.cs - Codegen core · Transforms generator IR into C# declarations and properties.
GeneratorLib/CodeGenerator.cs - Type model · Codegen type abstractions shared by the generation pipeline.
GeneratorLib/CodegenType.cs - Type factories · Factories that map schema field shapes to codegen types.
GeneratorLib/ArrayValueCodegenTypeFactory.cs
Runtime loader
Public loader API and handwritten parsing helpers used by consumers.
- Loader API · Public consumer-facing API for loading glTF models.
glTFLoader/Interface.cs - Stream helpers · Helpers for stream-based file reading during model loading.
glTFLoader/StreamExtensions.cs - Array converter · Custom handling for array-shaped JSON data in the loader.
glTFLoader/ArrayConverter.cs - Gltf root · Root object of the typed glTF model graph.
glTFLoader/Schema/Gltf.cs - Schema base · Shared base types for glTF properties and root children.
glTFLoader/Schema/GltfProperty.cs - Scene graph · Core node/mesh/scene types that form the structural model.
glTFLoader/Schema/Node.cs - Materials · Material and PBR-related schema types.
glTFLoader/Schema/Material.cs - Resources · Buffer, image, sampler, and texture schema types.
glTFLoader/Schema/Buffer.cs - Animation · Animation and skinning schema types.
glTFLoader/Schema/Animation.cs
Tests
Validation of generation logic and runtime loading behavior.
- Gen tests · Validates schema parsing and code generation behavior.
GeneratorUnitTests/CodeGeneratorTest.cs - Loader tests · Validates runtime loading against sample glTF assets.
glTFLoaderUnitTests/SampleModelsTest.cs
Connections 21
- glTF spec → Schema loader: feeds · Schema/spec inputs are consumed by the generation pipeline.
- Generator → Schema loader: drives · The executable orchestrates schema ingestion.
- Schema loader → Schema parser: parses with · Loader delegates structured interpretation to the parser.
- Schema parser → Schema model: builds · Parsed schema data is normalized into the internal IR.
- Schema model → Codegen core: inputs · The code generator consumes the schema IR.
- Type model → Codegen core: shapes · Shared codegen type abstractions guide generation output.
- Type factories → Type model: produces · Factories create codegen type variants for different schema field shapes.
- Codegen core → Gltf root: emits · Generated C# schema classes are written into the runtime schema layer.
- Generator → Codegen core: invokes · The build tool runs the generator library.
- Loader API → Stream helpers: uses · The public API relies on stream utilities when loading files.
- Loader API → Array converter: uses · The public API uses custom JSON conversion helpers.
- Loader API → Gltf root: returns · Loaded models are materialized as typed glTF objects.
- Gltf root → Schema base: inherits · Generated root and child types share common schema base classes.
- Gltf root → Scene graph: contains · The root model references scene graph structures.
- Gltf root → Materials: contains · The root model references material structures.
- Gltf root → Resources: contains · The root model references resource and texture structures.
- Gltf root → Animation: contains · The root model references animation and skin structures.
- Gen tests → Schema model: validates · Unit tests protect schema parsing and generation inputs.
- Gen tests → Codegen core: validates · Unit tests cover the code generation pipeline.
- Loader tests → Loader API: validates · Tests exercise the public loading surface.
- Loader tests → Sample models: uses · Runtime tests depend on canonical sample assets.