asset-importer-rs-gltf

glTF 2.0 import and export functionality

Complete glTF 2.0 specification support with extensions

:book: Table of Contents

:pencil: About The Crate

asset-importer-rs-gltf provides comprehensive glTF 2.0 import and export functionality for the asset-importer-rs project. This implementation supports the full glTF 2.0 specification including all major extensions, making it a complete solution for working with glTF assets in Rust applications.

This crate provides the essential functionality for:

• glTF 2.0 Import - Complete scene graph construction from glTF files
• glTF 2.0 Export - Full scene serialization to glTF format
• Material System - Comprehensive PBR material support with extensions
• Mesh Processing - Geometry and mesh data handling
• Animation Support - Keyframe and morph target animations
• Extension Support - Extensive glTF extension compatibility

:cloud: Features

• Complete glTF 2.0 Support - Full specification compliance with all major features
• Comprehensive Material System - PBR materials with extensive extension support
• Mesh and Geometry Handling - Complete mesh data processing and optimization
• Animation Framework - Support for keyframe and morph target animations
• Camera and Light Support - Complete camera and lighting system
• Texture Processing - Advanced texture and image handling
• Node Hierarchy - Full scene graph and node hierarchy support
• Extension Ecosystem - Extensive glTF extension compatibility

:puzzle_piece: Supported Extensions

The following glTF extensions are fully supported:

Material Extensions

• KHR_texture_transform - Texture coordinate transformations
• KHR_materials_unlit - Unlit material support
• KHR_materials_transmission - Transmission material properties
• KHR_materials_ior - Index of refraction
• KHR_materials_volume - Volume material properties
• KHR_materials_specular - Specular material properties
• KHR_materials_pbrSpecularGlossiness - Specular-glossiness workflow
• KHR_materials_emissive_strength - Enhanced emissive materials

Lighting Extensions

• KHR_lights_punctual - Point, spot, and directional lights

:floppy_disk: Main Components

Core Import/Export

• Gltf2Importer - Main glTF 2.0 import functionality
• Gltf2Exporter - Main glTF 2.0 export functionality
• Gltf2ImportError - Import error handling
• Gltf2ExportError - Export error handling

Import Pipeline

• Scene Graph Construction - Complete node hierarchy building
• Material Loading - PBR material and texture processing
• Mesh Processing - Geometry data import and optimization
• Animation Import - Keyframe and morph target data
• Camera & Light Setup - Camera and lighting configuration

Export Pipeline

• Scene Serialization - Complete scene graph export
• Material Export - PBR material and texture writing
• Mesh Writing - Geometry data serialization
• Animation Export - Animation data serialization
• Extension Support - glTF extension compatibility

:book: Getting Started

Add the following to your Cargo.toml:

[dependencies]
asset-importer-rs-gltf = "0.3.0"

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

# Enable specific extensions as needed
[features]
default = [
    "guess_mime_type",
    "extensions",
    "KHR_texture_transform",
    "KHR_materials_unlit",
    "KHR_materials_transmission",
    "KHR_materials_ior",
    "KHR_materials_volume",
    "KHR_materials_specular",
    "KHR_materials_pbrSpecularGlossiness",
    "KHR_materials_emissive_strength",
    "KHR_lights_punctual",
]

:small_orange_diamond: Usage Examples

Basic glTF import example:

use asset_importer_rs_gltf::{
    Gltf2Importer,
    Gltf2ImportError,
};
use std::path::Path;

// Create an importer
let importer = Gltf2Importer::new();

// Import a glTF file
let scene = importer.import_file(Path::new("model.gltf"))?;

// Access scene data
println!("Scene has {} meshes", scene.meshes.len());
println!("Scene has {} materials", scene.materials.len());

Basic glTF export example:

use asset_importer_rs_gltf::{
    Gltf2Exporter,
    Gltf2ExportError,
};
use asset_importer_rs_scene::AiScene;

// Create an exporter
let exporter = Gltf2Exporter::new();

// Export scene to glTF
let scene = AiScene::default(); // Your scene data
exporter.export_file(&scene, Path::new("output.gltf"))?;

Working with extensions:

use asset_importer_rs_gltf::Gltf2Importer;

// Create importer with specific extension support
let mut importer = Gltf2Importer::new();
importer.enable_extension("KHR_materials_unlit")?;
importer.enable_extension("KHR_lights_punctual")?;

// Import with extension support
let scene = importer.import_file("model_with_extensions.gltf")?;

:small_orange_diamond: Architecture

The glTF crate provides a complete implementation of the glTF 2.0 specification with a modular architecture that separates import and export concerns. The importer handles scene graph construction, material processing, and mesh optimization, while the exporter manages serialization, texture handling, and extension support.

The crate integrates seamlessly with the asset-importer-rs ecosystem, providing glTF-specific implementations of the core import/export traits while maintaining compatibility with the broader 3D asset pipeline.

:small_orange_diamond: Dependencies

Core Dependencies

• gltf - Core glTF parsing and validation
• asset-importer-rs-core - Core import/export functionality
• asset-importer-rs-scene - Scene data structures
• image - Image processing and format support
• base64 - Base64 encoding/decoding
• serde_json - JSON parsing and serialization
• urlencoding - URI encoding/decoding
• bytemuck - Safe type casting

Feature Dependencies

• gltf/extensions - glTF extension support
• gltf/guess_mime_type - MIME type detection

: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