asset-importer-rs-gltf-v1

glTF 1.0 import and export functionality

Legacy glTF 1.0 specification support with KHR_materials_common

:book: Table of Contents

:pencil: About The Crate

asset-importer-rs-gltf-v1 provides glTF 1.0 import and export functionality for the asset-importer-rs project. This implementation supports the legacy glTF 1.0 specification, including the KHR_materials_common extension, making it essential for handling older glTF assets and maintaining backward compatibility.

This crate provides the essential functionality for:

• glTF 1.0 Import - Complete scene graph construction from legacy glTF files
• glTF 1.0 Export - Full scene serialization to glTF 1.0 format
• Legacy Material System - KHR_materials_common extension support
• Mesh Processing - Geometry and mesh data handling
• Asset Management - File loading, parsing, and resource management
• Backward Compatibility - Support for older glTF 1.0 assets

:cloud: Features

• Complete glTF 1.0 Support - Full legacy specification compliance
• Legacy Material System - KHR_materials_common extension support
• Mesh and Geometry Handling - Complete mesh data processing
• Camera and Light Support - Legacy camera and lighting system
• Texture Processing - Texture and image handling
• Node Hierarchy - Scene graph and node hierarchy support
• Asset Management - File loading, parsing, and resource management
• Buffer Handling - Binary buffer and shader management

:puzzle_piece: Supported Extensions

The following glTF 1.0 extension is fully supported:

Material Extensions

• KHR_materials_common - Legacy material system with common material types

:floppy_disk: Main Components

Core Import/Export

• GltfImporter - Main glTF 1.0 import functionality
• GltfExporter - Main glTF 1.0 export functionality
• GLTFImportError - Import error handling
• GltfExportError - Export error handling

Import Pipeline

• Scene Graph Construction - Complete node hierarchy building
• Material Loading - KHR_materials_common material processing
• Mesh Processing - Geometry data import and optimization
• Camera & Light Setup - Legacy camera and lighting configuration
• Asset Management - File loading and resource management

Export Pipeline

• Scene Serialization - Complete scene graph export
• Material Export - Legacy material and texture writing
• Mesh Writing - Geometry data serialization
• Buffer Management - Binary buffer and shader handling
• Extension Support - glTF 1.0 extension compatibility

:book: Getting Started

Add the following to your Cargo.toml:

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

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

# Enable KHR_materials_common extension
[features]
default = ["KHR_materials_common"]

:small_orange_diamond: Usage Examples

Basic glTF 1.0 import example:

use asset_importer_rs_gltf_v1::{
    GltfImporter,
    GLTFImportError,
};
use std::path::Path;

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

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

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

Basic glTF 1.0 export example:

use asset_importer_rs_gltf_v1::{
    GltfExporter,
    GltfExportError,
};
use asset_importer_rs_scene::AiScene;

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

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

Working with KHR_materials_common:

use asset_importer_rs_gltf_v1::GltfImporter;

// Create importer with KHR_materials_common support
let importer = GltfImporter::new();

// Import with legacy material support
let scene = importer.import_file("model_with_common_materials.gltf")?;

// Access legacy material data
for material in &scene.materials {
    // Handle KHR_materials_common properties
    println!("Material: {:?}", material);
}

:small_orange_diamond: Architecture

The glTF v1 crate provides a complete implementation of the legacy glTF 1.0 specification with a focus on backward compatibility and legacy asset support. The importer handles scene graph construction, legacy material processing, and mesh optimization, while the exporter manages serialization, texture handling, and extension support for the older format.

The crate integrates seamlessly with the asset-importer-rs ecosystem, providing glTF 1.0-specific implementations of the core import/export traits while maintaining compatibility with the broader 3D asset pipeline and ensuring legacy assets can be properly handled.

:small_orange_diamond: Dependencies

Core Dependencies

• gltf-v1 - Core glTF 1.0 parsing and validation
• asset-importer-rs-core - Core import/export functionality
• asset-importer-rs-scene - Scene data structures
• serde_json - JSON parsing and serialization
• bytemuck - Safe type casting
• enumflags2 - Flag-based enums
• base64 - Base64 encoding/decoding

Feature Dependencies

• gltf-v1/KHR_materials_common - Legacy material extension support

:warning: Legacy Support

This crate is specifically designed for handling legacy glTF 1.0 files and maintaining backward compatibility with older assets. For modern glTF 2.0 support with the latest features and extensions, please use the asset-importer-rs-gltf crate instead.

The glTF 1.0 specification has been superseded by glTF 2.0, but this crate ensures that legacy assets can still be properly imported, processed, and exported within the asset-importer-rs ecosystem.

: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