VitalyR fe6d6d0ef4 add more fbx data

2025-07-13 00:25:22 +08:00

6.6 KiB

Raw Blame History

Comprehensive FBX Structure Redesign

Based on an in-depth analysis of the ufbx crate API, I have completely redesigned the struct Fbx to better capture the rich data that FBX files provide. This document outlines the major improvements and new capabilities.

🚀 Major Improvements

1. Scene Hierarchy Preservation

Before: Flattened scene with basic transform handling
After: Full scene hierarchy with proper parent-child relationships
- nodes: Vec<FbxNode> - Complete node hierarchy
- root_node_ids: Vec<u32> - Multiple root support
- node_indices: HashMap<u32, usize> - Fast node lookup

2. Rich Data Structures

FbxNode - Complete Scene Node

pub struct FbxNode {
    pub name: String,
    pub id: u32,
    pub parent_id: Option<u32>,
    pub children_ids: Vec<u32>,
    pub local_transform: Transform,
    pub world_transform: Transform,
    pub visible: bool,
    pub mesh_id: Option<usize>,
    pub light_id: Option<usize>,
    pub camera_id: Option<usize>,
    pub material_ids: Vec<usize>,
}

FbxMaterial - Enhanced PBR Materials

pub struct FbxMaterial {
    pub name: String,
    pub base_color: Color,
    pub metallic: f32,
    pub roughness: f32,
    pub emission: Color,
    pub normal_scale: f32,
    pub alpha: f32,
    pub textures: HashMap<FbxTextureType, FbxTexture>,
}

FbxLight - Comprehensive Lighting

pub struct FbxLight {
    pub name: String,
    pub light_type: FbxLightType, // Directional, Point, Spot, Area, Volume
    pub color: Color,
    pub intensity: f32,
    pub cast_shadows: bool,
    pub inner_angle: Option<f32>,
    pub outer_angle: Option<f32>,
}

FbxCamera - Camera Support

pub struct FbxCamera {
    pub name: String,
    pub projection_mode: FbxProjectionMode, // Perspective, Orthographic
    pub field_of_view_deg: f32,
    pub aspect_ratio: f32,
    pub near_plane: f32,
    pub far_plane: f32,
    pub focal_length_mm: f32,
}

FbxTexture - Texture Information

pub struct FbxTexture {
    pub name: String,
    pub filename: String,
    pub absolute_filename: String,
    pub uv_set: String,
    pub uv_transform: Mat4,
    pub wrap_u: FbxWrapMode,
    pub wrap_v: FbxWrapMode,
}

3. Animation System

FbxAnimStack - Animation Timeline

pub struct FbxAnimStack {
    pub name: String,
    pub time_begin: f64,
    pub time_end: f64,
    pub layers: Vec<FbxAnimLayer>,
}

FbxAnimLayer - Animation Layers

pub struct FbxAnimLayer {
    pub name: String,
    pub weight: f32,
    pub additive: bool,
    pub property_animations: Vec<FbxPropertyAnim>,
}

FbxSkeleton - Skeletal Animation

pub struct FbxSkeleton {
    pub name: String,
    pub root_bone: FbxBone,
    pub bones: Vec<FbxBone>,
    pub bone_indices: HashMap<String, usize>,
}

4. Enhanced Metadata

pub struct FbxMeta {
    pub creator: Option<String>,
    pub creation_time: Option<String>,
    pub original_application: Option<String>,
    pub version: Option<u32>,         // NEW
    pub time_mode: Option<String>,    // NEW
    pub time_protocol: Option<String>, // NEW
}

5. Comprehensive Asset Labels

Extended FbxAssetLabel to support all new data types:

Node(usize) - Individual scene nodes
Light(usize) - Light definitions
Camera(usize) - Camera definitions
Texture(usize) - Texture references
AnimationStack(usize) - Animation stacks
DefaultScene - Main scene
RootNode - Scene root

6. Convenience Methods

Added comprehensive API for working with the scene hierarchy:

impl Fbx {
    pub fn get_node(&self, id: u32) -> Option<&FbxNode>
    pub fn get_node_by_name(&self, name: &str) -> Option<&FbxNode>
    pub fn get_root_nodes(&self) -> impl Iterator<Item = &FbxNode>
    pub fn get_children(&self, node_id: u32) -> Vec<&FbxNode>
    pub fn get_parent(&self, node_id: u32) -> Option<&FbxNode>
    pub fn get_mesh_nodes(&self) -> impl Iterator<Item = &FbxNode>
    pub fn get_light_nodes(&self) -> impl Iterator<Item = &FbxNode>
    pub fn get_camera_nodes(&self) -> impl Iterator<Item = &FbxNode>
    pub fn get_animation_time_range(&self) -> Option<(f64, f64)>
    pub fn has_animations(&self) -> bool
    pub fn has_skeletons(&self) -> bool
}

🎯 Data Organization

The new Fbx struct is organized into logical sections:

Scene Structure - Node hierarchy and relationships
Geometry and Visual Assets - Meshes, materials, textures, lights, cameras
Animation Data - Animation stacks, clips, skeletons
Bevy Scene Conversion - Ready-to-use Bevy scenes and materials
Quick Lookups - Hash maps for efficient name-based access
Scene Information - Axis systems, units, timing, metadata
Legacy Compatibility - Backwards compatibility support
Debug Information - Raw data for development

🔧 Technical Improvements

Type Safety

Changed IDs from u64 to u32 to match ufbx exactly
Added proper enum types for light types, projection modes, etc.
Strong typing for texture types and wrap modes

Performance

Efficient lookup tables for all named objects
Hierarchical data structures for fast traversal
Indexed access patterns

Extensibility

Modular design allows future expansion
TODO markers for future features (texture processing, advanced materials, etc.)
Clean separation between FBX data and Bevy conversions

🚧 Implementation Status

✅ Completed

Scene hierarchy processing
Basic mesh extraction and conversion
Node relationship preservation
Material and texture data structures
Animation data structures
Comprehensive API design
Asset label system

🔄 TODO (Marked for Future Development)

Full texture processing and loading
Advanced material property extraction from FBX
Animation curve processing
Skeletal animation support
Light and camera processing
Advanced metadata extraction

🎉 Benefits

Complete FBX Support: The structure can now represent the full richness of FBX files
Proper Scene Hierarchy: Maintains parent-child relationships and scene structure
Future-Proof: Designed to accommodate all FBX features as they're implemented
Developer Friendly: Rich API for accessing and manipulating FBX data
Bevy Integration: Seamless conversion to Bevy's asset system
Performance: Efficient data structures and lookup mechanisms

This redesign transforms bevy_fbx from a basic mesh loader into a comprehensive FBX processing system that can handle the full complexity of modern FBX files while maintaining clean integration with Bevy's asset pipeline.

6.6 KiB Raw Blame History