H073.HxGLTF 2.0.0

HxGLTF — High-Performance GLTF/GLB Loader for .NET

HxGLTF is a fast, memory-efficient library for loading GLTF 2.0 and GLB files into structured C# objects.

Features

• GLTF & GLB Support — Load both .gltf and binary .glb files
• Complete GLTF 2.0 — Scenes, nodes, meshes, materials, textures, animations, skins, cameras
• PBR Materials — Metallic-Roughness and Specular-Glossiness workflows
• Async Loading — GLTFReader.ReadAsync() with progress and cancellation
• ArrayPool Integration — Zero-allocation accessor reading
• 7 Built-in Extensions — KHR_texture_transform, KHR_materials_unlit, KHR_materials_clearcoat, KHR_materials_transmission, KHR_materials_ior, KHR_materials_pbrSpecularGlossiness, KHR_mesh_quantization
• Custom Extension System — Register your own extension handlers

Installation

dotnet add package H073.HxGLTF

<PackageReference Include="H073.HxGLTF" Version="2.0.0" />

Quick Start

using HxGLTF;
using HxGLTF.Core;

// Load a GLTF/GLB file
var gltf = GLTFReader.Read("model.glb");

// With options
var gltf = GLTFReader.Read("model.glb", new GLTFReadOptions
{
    SkipAnimations = false,
    SkipSkins = false,
    StrictExtensionCheck = true
});

// Async loading with progress
var gltf = await GLTFReader.ReadAsync("model.glb",
    progress: new Progress<GLTFLoadProgress>(p => Console.WriteLine($"{p.Stage}: {p.Percentage:F0}%")),
    cancellationToken: token);

Accessing Data

// Meshes
foreach (var mesh in gltf.Meshes)
{
    foreach (var prim in mesh.Primitives)
    {
        var positions = AccessorReader.ReadData(prim.GetAttribute("POSITION"));
        if (prim.HasIndices)
        {
            var indices = AccessorReader.ReadIndices(prim.Indices);
        }
    }
}

// Materials
foreach (var mat in gltf.Materials)
{
    var baseColor = mat.BaseColorFactor;
    var metallic = mat.MetallicFactor;
    var roughness = mat.RoughnessFactor;
    var emissive = mat.EmissiveFactor;
    var alphaMode = mat.AlphaMode; // "OPAQUE", "MASK", "BLEND"
}

// Animations
foreach (var anim in gltf.Animations)
{
    foreach (var channel in anim.Channels)
    {
        var times = AccessorReader.ReadData(channel.Sampler.Input);
        var values = AccessorReader.ReadData(channel.Sampler.Output);
        var targetPath = channel.Target.Path; // Translation, Rotation, Scale, Weights
    }
}

// Skeletons
foreach (var skin in gltf.Skins)
{
    var joints = skin.Joints;
    var ibm = skin.InverseBindMatrices;
}

High-Performance Reading

// Zero-allocation with pooled arrays
var (array, length) = AccessorReader.ReadDataPooled(accessor);
try
{
    ProcessVertices(array.AsSpan(0, length));
}
finally
{
    AccessorReader.ReturnPooledArray(array);
}

Extensions

Built-in

Custom Extensions

using HxGLTF.Core.Extensions;

public class MyExtension : GLTFExtensionBase
{
    public override string ExtensionName => "MY_custom_extension";

    public override ExtensionParseResult ParseMaterialExtension(
        JsonElement extensionData, Material material, ExtensionParseContext context)
    {
        float myValue = 0f;
        if (extensionData.TryGetProperty("myValue", out var prop))
            myValue = prop.GetSingle();

        return ExtensionParseResult.Succeeded(new { MyValue = myValue });
    }
}

// Register before loading
GLTFExtensionRegistry.Register(new MyExtension());
var gltf = GLTFReader.Read("model.glb");

// Access after loading
if (mat.Extensions.TryGetValue("MY_custom_extension", out var data))
{
    // data contains what ParseMaterialExtension returned
}

Available parse hooks:

• ParseRootExtension — document-level
• ParseMaterialExtension — per-material
• ParsePrimitiveExtension — per-mesh-primitive
• ParseNodeExtension — per-node
• ParseTextureExtension — per-texture

Data Structure

GLTFFile
├── Asset (version, generator, copyright)
├── Scenes[] → Nodes[]
├── Nodes[] → Children[], Mesh, Camera, Skin
├── Meshes[] → Primitives[] → Attributes, Indices, Material
├── Materials[] → Textures, PBR factors, Extensions
├── Textures[] → Image, Sampler
├── Animations[] → Channels[], Samplers[]
├── Skins[] → Joints[], InverseBindMatrices
├── Cameras[] → Perspective/Orthographic
├── Buffers[] / BufferViews[] / Accessors[]
└── ExtensionsUsed[] / ExtensionsRequired[]

Using MonoGame?

Use HxGLTF.MonoGame — loads glTF/GLB directly into a ModelKit Scene with animations, skeletons, PBR materials, and morph targets.

License

MIT

Contact

Discord: sameplayer