H073.HxGLTF 1.3.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

Core Loading

• GLTF & GLB Support — Load both text-based .gltf and binary .glb files
• Complete GLTF 2.0 Support — Scenes, nodes, meshes, materials, textures, animations, skins, cameras
• PBR Materials — Metallic-Roughness and Specular-Glossiness workflows
• Embedded & External Resources — Base64 data URIs, external files, and GLB binary chunks

Performance & Memory

• Async Loading — Non-blocking file I/O with GLTFLoaderAsync
• ArrayPool Integration — Zero-allocation accessor reading with ReadDataPooled()
• Span-Based Processing — Direct memory access without copies
• Configurable Loading — Skip animations/skins for faster load times

Extensibility

• Extension System — Register custom GLTF extension handlers
• Built-in Extensions:
  • KHR_materials_unlit
  • KHR_texture_transform
  • KHR_materials_pbrSpecularGlossiness

🚀 Quick Start

using HxGLTF;
using HxGLTF.Core;

// Simple loading
var gltfFile = GLTFLoader.Load("model.glb");

// With options
var options = new GLTFLoader.LoadOptions
{
    SkipAnimations = false,
    SkipSkins = false,
    StrictExtensionCheck = true,
    LogWarnings = true
};
var gltfFile = GLTFLoader.Load("model.glb", options);

// Access data
foreach (var mesh in gltfFile.Meshes)
{
    Console.WriteLine($"Mesh: {mesh.Name}, Primitives: {mesh.PrimitiveCount}");
    
    foreach (var primitive in mesh.Primitives)
    {
        // Read vertex positions
        var positions = AccessorReader.ReadData(primitive.GetAttribute("POSITION"));
        
        // Read indices (if indexed)
        if (primitive.HasIndices)
        {
            var indices = AccessorReader.ReadIndices(primitive.Indices);
        }
    }
}

Async Loading

using HxGLTF;

// With progress reporting
var progress = new Progress<GLTFLoadProgress>(p => 
    Console.WriteLine($"{p.Stage}: {p.Percentage:F0}%"));

var gltfFile = await GLTFLoaderAsync.LoadAsync(
    "model.glb",
    options: null,
    progress: progress,
    cancellationToken: token);

// Load multiple files in parallel
var files = await GLTFLoaderAsync.LoadManyAsync(
    paths: new[] { "model1.glb", "model2.glb", "model3.glb" },
    maxParallelism: 4,
    cancellationToken: token);

High-Performance Reading

// Zero-allocation reading with pooled arrays
var (array, length) = AccessorReader.ReadDataPooled(accessor);
try
{
    // Use data...
    ProcessVertices(array.AsSpan(0, length));
}
finally
{
    AccessorReader.ReturnPooledArray(array); // Return to pool!
}

// Or use the disposable pattern
using var reader = new PooledAccessorReader();
ReadOnlySpan<float> positions = reader.ReadData(positionAccessor);
ReadOnlySpan<int> indices = reader.ReadIndices(indexAccessor);
// Arrays automatically returned when disposed

Custom Extensions

public class MyCustomExtension : GLTFExtensionBase
{
    public override string ExtensionName => "MY_custom_extension";
    
    public override ExtensionParseResult ParseMaterialExtension(
        JToken extensionData, 
        Material material, 
        ExtensionParseContext context)
    {
        // Parse your extension data
        var myData = new MyExtensionData
        {
            CustomValue = extensionData["customValue"]?.Value<float>() ?? 0f
        };
        
        return ExtensionParseResult.Succeeded(myData);
    }
}

// Register before loading
GLTFExtensionRegistry.Register(new MyCustomExtension());

📦 Installation

dotnet add package H073.HxGLTF

Or in .csproj:

<PackageReference Include="H073.HxGLTF" Version="x.y.z" />

📊 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?

Check out HxGLTF.MonoGame for:

• Ready-to-use GameModel, GameNode, GameMesh classes
• Async model loading with precompiled binary caching
• Sample renderer for quick prototyping
• Advanced features: Animation blending, LOD, Instanced rendering

📚 Learn More

To get the most out of HxGLTF, we recommend reading the GLTF 2.0 Specification.

This will help you:

• Understand the structure of your models
• Build a proper rendering system
• Handle nodes, hierarchies, animations, skins, and materials correctly

⚠️ Important Notes

Rendering is Your Responsibility
HxGLTF's main goal is to load GLTF/GLB files into structured, usable C# objects.
You are expected to build your own renderer based on your specific needs.

🤝 Contact

Discord: sameplayer