217 lines
6.6 KiB
Markdown
217 lines
6.6 KiB
Markdown
# 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
|
|
```rust
|
|
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
|
|
```rust
|
|
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
|
|
```rust
|
|
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
|
|
```rust
|
|
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
|
|
```rust
|
|
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
|
|
```rust
|
|
pub struct FbxAnimStack {
|
|
pub name: String,
|
|
pub time_begin: f64,
|
|
pub time_end: f64,
|
|
pub layers: Vec<FbxAnimLayer>,
|
|
}
|
|
```
|
|
|
|
#### **FbxAnimLayer** - Animation Layers
|
|
```rust
|
|
pub struct FbxAnimLayer {
|
|
pub name: String,
|
|
pub weight: f32,
|
|
pub additive: bool,
|
|
pub property_animations: Vec<FbxPropertyAnim>,
|
|
}
|
|
```
|
|
|
|
#### **FbxSkeleton** - Skeletal Animation
|
|
```rust
|
|
pub struct FbxSkeleton {
|
|
pub name: String,
|
|
pub root_bone: FbxBone,
|
|
pub bones: Vec<FbxBone>,
|
|
pub bone_indices: HashMap<String, usize>,
|
|
}
|
|
```
|
|
|
|
### 4. **Enhanced Metadata**
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
1. **Scene Structure** - Node hierarchy and relationships
|
|
2. **Geometry and Visual Assets** - Meshes, materials, textures, lights, cameras
|
|
3. **Animation Data** - Animation stacks, clips, skeletons
|
|
4. **Bevy Scene Conversion** - Ready-to-use Bevy scenes and materials
|
|
5. **Quick Lookups** - Hash maps for efficient name-based access
|
|
6. **Scene Information** - Axis systems, units, timing, metadata
|
|
7. **Legacy Compatibility** - Backwards compatibility support
|
|
8. **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
|
|
|
|
1. **Complete FBX Support**: The structure can now represent the full richness of FBX files
|
|
2. **Proper Scene Hierarchy**: Maintains parent-child relationships and scene structure
|
|
3. **Future-Proof**: Designed to accommodate all FBX features as they're implemented
|
|
4. **Developer Friendly**: Rich API for accessing and manipulating FBX data
|
|
5. **Bevy Integration**: Seamless conversion to Bevy's asset system
|
|
6. **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. |