gltf-v1

glTF 1.0 specification implementation

Complete glTF 1.0 support with binary GLB format

:book: Table of Contents

:pencil: About The Crate

gltf-v1 provides comprehensive support for the glTF 1.0 specification, including binary GLB format support. This crate is part of the asset-importer-rs project and serves as the main implementation for glTF 1.0 file handling, offering complete parsing, validation, and manipulation capabilities.

This crate provides the essential functionality for:

• glTF 1.0 Parsing - Complete specification compliance and validation
• Binary GLB Support - Binary format parsing and data extraction
• Image Processing - Image loading and format support
• Buffer Management - Raw data storage and access
• Mathematical Utilities - 3D mathematics and transformations
• Extension Support - glTF 1.0 extension compatibility

:cloud: Features

• Complete glTF 1.0 Support - Full specification compliance with all core components
• Binary GLB Format - Comprehensive binary format support
• Image Processing - Multi-format image loading (JPEG, PNG, BMP, GIF)
• Buffer Management - Efficient buffer data handling and access
• Comprehensive Error Handling - Detailed error types and reporting
• Mathematical Utilities - 3D mathematics for transformations
• Extension Ecosystem - Support for glTF 1.0 extensions
• Resource Loading - External resource and URI handling

:puzzle_piece: Supported Extensions

The following glTF 1.0 extensions are supported through feature flags:

Core Extensions

• KHR_binary_glTF - Binary buffer support (enabled by default)
• KHR_materials_common - Common material types

:floppy_disk: Main Components

Core glTF Components

• Document - Main entry point for glTF file handling
• Buffer - Raw data storage and management
• Accessor - Buffer access and type information
• Animation - Keyframe animations
• Camera - Camera definitions and parameters
• Material - Material properties and techniques
• Mesh - Geometry data and primitives
• Node - Scene graph nodes and transformations
• Scene - Scene organization and hierarchy
• Skin - Skeletal animations and bindings
• Texture - Image and sampler definitions
• Light - Light source definitions

Utilities and Support

• Math - 3D mathematics utilities
• Binary Parsing - GLB format support
• Image Loading - Multi-format image support
• Error Handling - Comprehensive error system

:book: Getting Started

Add the following to your Cargo.toml:

[dependencies]
gltf-v1 = "0.3.0"

# Or for development from source:
gltf-v1 = { path = "../path/to/gltf-v1" }

# Enable specific extensions
[features]
default = ["KHR_binary_glTF"]
KHR_binary_glTF = []
KHR_materials_common = []

:small_orange_diamond: Usage Examples

Basic glTF 1.0 loading example:

use gltf_v1::{
    Document,
    Gltf,
    import_buffers,
    import_images,
};

// Load a glTF file
let gltf = Gltf::open("model.gltf")?;
let document = Document::from_gltf(gltf)?;

// Import binary data
let buffers = import_buffers(&document, "model.bin")?;
let images = import_images(&document, "textures")?;

// Access scene data
println!("Document has {} scenes", document.scenes.len());
println!("Document has {} meshes", document.meshes.len());

Working with binary GLB files:

use gltf_v1::{Document, Gltf};

// Load a binary GLB file
let gltf = Gltf::open("model.glb")?;
let document = Document::from_gltf(gltf)?;

// Access embedded binary data
for buffer in &document.buffers {
    println!("Buffer: {:?}", buffer);
}

Accessing mesh and material data:

use gltf_v1::Document;

let document = Document::from_gltf(gltf)?;

// Access mesh data
for mesh in &document.meshes {
    println!("Mesh: {:?}", mesh.name);
    for primitive in &mesh.primitives {
        println!("  Primitive: {:?}", primitive);
    }
}

// Access material data
for material in &document.materials {
    println!("Material: {:?}", material.name);
    if let Some(technique) = &material.technique {
        println!("  Technique: {:?}", technique);
    }
}

:floppy_disk: Binary Support

The crate includes comprehensive support for binary GLB files, providing efficient parsing and data extraction capabilities for embedded binary data.

Binary Features

• Binary Chunk Parsing - GLB format chunk extraction
• Buffer Data Extraction - Embedded buffer data handling
• Image Data Handling - Binary image data processing
• Base64 and URI Decoding - Multiple data encoding support
• Binary Data Validation - Format integrity checking

:warning: Error Handling

The crate provides a robust error handling system designed to provide detailed information about parsing and validation issues.

Error Types

• Detailed Error Types - Specific error types for each operation
• Path-based Reporting - Error location and context information
• Binary Format Validation - GLB format integrity checking
• Resource Loading Errors - External resource access issues
• Extension-specific Errors - Extension validation and compatibility

:small_orange_diamond: Dependencies

Core Dependencies

• gltf-v1-json - JSON schema implementation
• image - Image processing (JPEG, PNG, BMP, GIF)
• base64 - Base64 encoding/decoding
• byteorder - Binary data handling
• urlencoding - URI encoding/decoding
• indexmap - Indexed hash map support

Feature Dependencies

• gltf-v1-json/KHR_binary_glTF - Binary format support
• gltf-v1-json/KHR_materials_common - Material extension support

:scroll: License

This project is part of the asset-importer-rs workspace and follows its licensing terms. See the main project LICENSE file for details.

Copyright (c) 2024 Jackson Levitt