SharpGLTF Documentation

SharpGLTF Core is organized into several namespaces that handle different aspects of glTF2 processing:

• .Schema2: The primary low-level API for accessing glTF2 documents. The main entry point for representing a glTF2 model is the ModelRoot object.
• .Runtime: Used for evaluating a model. This is useful for tasks like dumping a raw list of triangles in their final positions or preparing a model for rendering in a graphics engine.
• .Transforms: Manages the scene graph and node relationships (typically via 4x4 matrices). It also handles coordinate space transformations, including skinning and morphing (moving meshes from local to world space).
• .Animations: Provides classes for decoding and interpolating animation curves.
• .Memory: Provides helper classes and structures to facilitate seamless access to structured arrays stored as encoded byte buffers in glTF2.
• .IO: Contains logic related to JSON serialization.

To render glTF models in a custom graphics engine, SharpGLTF.Runtime uses a two-tier abstraction: SceneTemplate and SceneInstance.

1. SceneTemplate: An immutable object representing the resource asset in memory. You create it from a glTF scene (e.g., model.DefaultScene). It serves as the master blueprint for all instances.
2. SceneInstance: Lightweight objects that reference a SceneTemplate. Instances allow you to:
   • Animate the model independently using SetAnimationFrame(animationName, time).
   • Manually edit individual nodes (e.g., using SetWorldMatrix(nodeName, matrix)) without affecting other instances.
   • Maintain separate states for multiple copies of the same model in a scene.

This pattern allows you to load the heavy glTF data once and then efficiently manage many different animated or positioned versions of that model.

// 1. Create the immutable template
var modelTemplate = SharpGLTF.Runtime.SceneTemplate(model.DefaultScene, true);

// 2. Create lightweight, independent instances
var inst1 = modelTemplate.CreateInstance();
inst1.SetAnimationFrame("Walking", 2.17f);

var inst2 = modelTemplate.CreateInstance();
inst2.SetWorldMatrix("Head", Matrix.LookAt(...) );

The SharpGLTF.Schema2 namespace provides two distinct ways to traverse a glTF document depending on your goal:

1. Logical Traversal: Use the ModelRoot.Logical* collections. This provides direct access to the individual building blocks exactly as they are stored in the glTF schema (often as plain lists with integer index cross-referencing). This is useful for low-level inspection of the document structure.

2. Visual Traversal: Start with ModelRoot.DefaultScene and navigate through nodes and properties using .Visual* properties. This treats the document as a visual tree graph, which is more intuitive for navigating the scene hierarchy and spatial relationships.

Note on Editing: Editing existing glTF models via Schema2 has very limited support. Removing elements is generally not possible because glTF data is often shared between elements, and removal would require expensive internal data reshuffling. For complex editing tasks, use SharpGLTF.Toolkit instead.

The Toolkit API uses a high-level, visual approach compared to the low-level glTF Schema2 API.

In the glTF Schema2 API, you manually manage the hierarchy: you create a Scene, add Node children to it, and then manually assign Mesh and Skin references to those nodes.

In the Toolkit API, you focus on what you want to render. Methods like AddMesh automatically handle the creation of the necessary nodes and instances. A SceneBuilder acts as a collection of rendering instances, and NodeBuilder objects are used to define hierarchical structures or armatures.

// glTF Schema2 API approach (Manual hierarchy management)
scene = model.UseScene(0);
var n1 = scene.CreateNode();
n1.Mesh = ...
var n2 = scene.CreateNode();
n2.Mesh = ...

// Toolkit API approach (Visual/Intent-based rendering)
scene = new SceneBuilder();
scene.AddRigidMesh(...);
scene.AddSkinnedMesh(...);