# embedded-3dgfx Examples
This directory contains 23+ interactive examples demonstrating the full capabilities of embedded-3dgfx: 3D rendering, physics, skeletal animation, and soft body dynamics.
## Prerequisites
These examples use `embedded-graphics-simulator` for desktop visualization. SDL2 is required:
### macOS
```bash
brew install sdl2
```
### Ubuntu/Debian
```bash
sudo apt-get install libsdl2-dev
```
### Windows
Download SDL2 development libraries from [libsdl.org](https://www.libsdl.org/download-2.0.php)
## Running Examples
All examples require the `std` feature:
```bash
cargo run --example <name> --features std
```
## 🎨 3D Rendering Examples
### Core Rendering
#### `basic_rendering` - Render Mode Cycling
Demonstrates three fundamental render modes: Points, Lines, and Solid.
**Controls:**
- `SPACE` - Cycle through render modes
- `ESC` - Exit
```bash
cargo run --example basic_rendering --features std
```
#### `rotating_cube` - Animated 3D Rotation
Continuously rotating cube with FPS counter.
**Features:**
- Time-based transformations
- Real-time FPS display
- Smooth multi-axis rotation
```bash
cargo run --example rotating_cube --features std
```
#### `scene_viewer` - Interactive Multi-Mesh Scene
Complex scene with multiple objects and camera controls.
**Controls:**
- `Arrow Keys` - Rotate camera
- `+/-` - Zoom
- `ESC` - Exit
```bash
cargo run --example scene_viewer --features std
```
### Lighting & Shading
#### `lighting_demo` - Directional Lighting
Shows diffuse lighting with ambient term on rotating objects.
**Controls:**
- `SPACE` - Toggle light auto-rotation
- `Arrow Keys` - Manual light control
- `ESC` - Exit
```bash
cargo run --example lighting_demo --features std
```
#### `gouraud_demo` - Smooth Color Interpolation
Demonstrates Gouraud shading with per-vertex colors.
```bash
cargo run --example gouraud_demo --features std
```
#### `blinn_phong_demo` - Specular Highlights
Shows specular reflections using Blinn-Phong shading.
**Features:**
- Specular highlights
- Shininess control
- Multiple STL models
```bash
cargo run --example blinn_phong_demo --features std
```
### Visual Effects
#### `fog_dithering_demo` - Atmospheric Effects
Interactive fog and dithering effects.
**Controls:**
- `F` - Toggle fog
- `D` - Toggle dithering
- `+/-` - Adjust fog distance
- `ESC` - Exit
```bash
cargo run --example fog_dithering_demo --features std
```
#### `billboard_demo` - Camera-Facing Sprites
Demonstrates billboarding for particles and sprites.
```bash
cargo run --example billboard_demo --features std
```
### Advanced Features
#### `texture_mapping_demo` - UV Mapping
Shows affine texture mapping with multiple patterns.
**Features:**
- Multiple texture patterns
- UV coordinate mapping
- Texture switching
```bash
cargo run --example texture_mapping_demo --features std
```
#### `dma_rendering_demo` - Double Buffering
Performance comparison between single and double buffering.
**Features:**
- ~30% FPS improvement demonstration
- Swap chain visualization
```bash
cargo run --example dma_rendering_demo --features std
```
#### `lod_demo` - Level of Detail
Distance-based mesh detail switching.
**Features:**
- 3-10× performance improvement at distance
- Smooth LOD transitions
```bash
cargo run --example lod_demo --features std
```
#### `vertex_animation_demo` - Keyframe Animation
Animated models using keyframe interpolation.
```bash
cargo run --example vertex_animation_demo --features std
```
#### `stl_viewer` - STL Model Viewer
Load and view STL models (Suzanne, teapot, Blåhaj).
**Controls:**
- `1/2/3` - Switch models
- `R` - Rotate model
```bash
cargo run --example stl_viewer --features std
```
#### `painters_algorithm_demo` - Z-buffer-free Rendering
Back-to-front triangle sorting without Z-buffer (saves 1.92MB RAM).
**Controls:**
- `SPACE` - Toggle Painter's Algorithm vs Z-buffer
- `R` - Rotate objects
```bash
cargo run --example painters_algorithm_demo --features std
```
## ⚛️ Physics Examples
*See [PHYSICS_EXAMPLES.md](../PHYSICS_EXAMPLES.md) for detailed physics documentation.*
### Rigid Body Dynamics
#### `physics_rolling_ball` ⭐ **START HERE**
Beginner-friendly introduction to physics.
**Features:**
- Gravity simulation
- Friction and rolling motion
- Static ramp
**Controls:**
- `R` - Reset ball
- `SPACE` - Apply impulse
- `F` - Toggle friction
```bash
cargo run --example physics_rolling_ball --features std
```
#### `physics_bouncing_balls` - Multi-Body Collisions
Multiple spheres colliding with each other and the ground.
```bash
cargo run --example physics_bouncing_balls --features std
```
#### `physics_pendulum` - Constraint Joints
Swinging pendulum using distance constraints.
```bash
cargo run --example physics_pendulum --features std
```
#### `physics_newtons_cradle` - Chain Constraints
Classic Newton's cradle with multiple distance constraints.
```bash
cargo run --example physics_newtons_cradle --features std
```
#### `physics_stack_tower` - Stacking & Friction
Boxes stacking with realistic friction.
```bash
cargo run --example physics_stack_tower --features std
```
#### `physics_domino_chain` - Sequential Collisions
Domino chain reaction simulation.
```bash
cargo run --example physics_domino_chain --features std
```
#### `physics_wrecking_ball` - Demolition
Wrecking ball knocking down a wall.
```bash
cargo run --example physics_wrecking_ball --features std
```
#### `physics_demo` - Comprehensive Showcase
Original comprehensive physics demo showing all features together.
```bash
cargo run --example physics_demo --features std
```
#### `capsule_physics_demo` - Capsule Colliders
Capsule colliders interacting with spheres and AABBs.
**Features:**
- Capsule-sphere collisions
- Capsule-AABB collisions
- Capsule-capsule collisions
- Realistic tumbling
**Controls:**
- `SPACE` - Spawn capsule
- `C` - Add cube
- `S` - Add sphere
- `R` - Reset
```bash
cargo run --example capsule_physics_demo --features std
```
#### `raycast_demo` - Ray Casting
Interactive ray casting with visual feedback.
**Features:**
- Ray-sphere intersection
- Ray-AABB intersection
- Ray-capsule intersection
- Hit highlighting
**Controls:**
- `SPACE` - Shoot ray
- `Arrow Keys` - Rotate camera
- `R` - Reset
```bash
cargo run --example raycast_demo --features std
```
## 🦴 Skeletal Animation Examples
*See [SKELETAL_AND_SOFTBODY.md](../SKELETAL_AND_SOFTBODY.md) for detailed documentation.*
#### `skeletal_animation_demo` - Bone Hierarchy & Skinning
Animated articulated arm with hierarchical bones.
**Features:**
- Parent-child bone relationships
- Linear blend skinning (SSD)
- Real-time deformation
- Up to 4 bone influences per vertex
**Controls:**
- `SPACE` - Toggle animation
- `UP/DOWN` - Rotate shoulder
- `LEFT/RIGHT` - Rotate elbow
- `R` - Reset pose
- `ESC` - Exit
```bash
cargo run --example skeletal_animation_demo --features std
```
## 🧊 Soft Body Physics Examples
*See [SKELETAL_AND_SOFTBODY.md](../SKELETAL_AND_SOFTBODY.md) for detailed documentation.*
#### `cloth_simulation` - Mass-Spring Cloth
Hanging cloth with wind interaction.
**Features:**
- Mass-spring network
- Structural and shear springs
- Pinned constraints
- Wind forces
- Gravity toggle
**Controls:**
- `W` - Wind right
- `S` - Wind left
- `G` - Toggle gravity
- `R` - Reset
- `ESC` - Exit
```bash
cargo run --example cloth_simulation --features std
```
#### `jelly_cube_demo` - Deformable Cube
Bouncing soft body with volume preservation.
**Features:**
- 3D mass-spring network
- Pressure/volume preservation
- Ground collision
- Bouncy behavior
**Controls:**
- `SPACE` - Drop cube
- `UP` - Apply upward force
- `P` - Toggle pressure
- `R` - Reset
- `ESC` - Exit
```bash
cargo run --example jelly_cube_demo --features std
```
## 🎯 Example Categories
### By Difficulty
**Beginner:**
1. `rotating_cube` - Basic 3D rendering
2. `basic_rendering` - Render modes
3. `physics_rolling_ball` - Physics intro
**Intermediate:**
4. `lighting_demo` - Lighting basics
5. `scene_viewer` - Camera control
6. `physics_bouncing_balls` - Multi-body physics
7. `billboard_demo` - Special effects
**Advanced:**
8. `skeletal_animation_demo` - Character animation
9. `cloth_simulation` - Soft body dynamics
10. `raycast_demo` - Ray casting
11. `physics_newtons_cradle` - Complex constraints
### By Feature
**Rendering:**
- `basic_rendering`, `rotating_cube`, `scene_viewer`
- `lighting_demo`, `gouraud_demo`, `blinn_phong_demo`
- `fog_dithering_demo`, `texture_mapping_demo`
**Physics:**
- `physics_rolling_ball`, `physics_bouncing_balls`
- `physics_pendulum`, `physics_newtons_cradle`
- `physics_stack_tower`, `physics_domino_chain`
- `physics_wrecking_ball`, `physics_demo`
- `capsule_physics_demo`, `raycast_demo`
**Animation:**
- `vertex_animation_demo` - Keyframe animation
- `skeletal_animation_demo` - Bone-based animation
- `cloth_simulation` - Physics-based animation
- `jelly_cube_demo` - Soft body animation
**Performance:**
- `dma_rendering_demo` - Double buffering
- `lod_demo` - Level of detail
- `painters_algorithm_demo` - Memory optimization
## 🔧 Customizing Examples
### Changing Resolution
Edit the example source:
```rust
// Change from 320×240 to 640×480
let mut display: SimulatorDisplay<Rgb565> = SimulatorDisplay::new(Size::new(640, 480));
let mut engine = K3dengine::new(640, 480);
// Adjust window scale
let output_settings = OutputSettingsBuilder::new().scale(1).build(); // Was .scale(2)
```
### Adjusting Performance
```rust
// Reduce quality for higher FPS
engine.camera.set_near_far(2.0, 20.0); // Narrower depth range
// Use LOD for distant objects
mesh.set_lod(Some(medium_detail), Some(low_detail), lod_levels);
// Disable expensive features
// Remove fog, dithering, or use simpler shading
```
## 🚀 Performance Tips
1. **Use LOD** - 3-10× fewer triangles at distance
2. **Enable DMA** - 30% FPS improvement
3. **Tune Z-buffer** - Better depth precision
4. **Frustum culling** - Automatic 50-200% speedup
5. **Backface culling** - Eliminates ~50% of faces
## 📊 Example Performance
On desktop (Apple M1):
- Simple scenes: 1000+ FPS
- Complex scenes (500+ triangles): 200-400 FPS
- Physics (16 bodies): 60 FPS
- Soft body (64 particles): 60 FPS
On embedded (STM32 Cortex-M33 @ 100MHz):
- Simple scenes: 60-120 FPS
- Medium scenes (100 triangles): 30-60 FPS
- Physics (8 bodies): 30-60 FPS
## 🎓 Learning Path
**Recommended order for learning:**
1. **Rendering Basics**
- `rotating_cube` → `basic_rendering` → `scene_viewer`
2. **Lighting & Effects**
- `lighting_demo` → `gouraud_demo` → `fog_dithering_demo`
3. **Physics Fundamentals**
- `physics_rolling_ball` → `physics_bouncing_balls` → `physics_pendulum`
4. **Advanced Physics**
- `physics_newtons_cradle` → `capsule_physics_demo` → `raycast_demo`
5. **Animation & Soft Body**
- `skeletal_animation_demo` → `cloth_simulation` → `jelly_cube_demo`
## 🐛 Troubleshooting
**SDL2 not found:**
```
error: failed to run custom build command for `sdl2-sys`
```
→ Install SDL2 (see Prerequisites above)
**Feature errors:**
```
error: could not find `perfcounter` in `embedded_3dgfx`
```
→ Add `--features std` to cargo run command
**Window crashes:**
```
called `Option::unwrap()` on a `None` value
```
→ Ensure SDL2 is properly installed and display is available
## 📝 Notes
- All examples target 60 FPS (16ms frame time)
- Physics examples use fixed timestep (0.016s)
- Soft body examples may run slower on some systems
- Examples are for demonstration - optimize for production use
- Window close button works - press ESC or close window to exit
## 🔗 Related Documentation
- **[../PHYSICS_EXAMPLES.md](../PHYSICS_EXAMPLES.md)** - Detailed physics demo guide
- **[../SKELETAL_AND_SOFTBODY.md](../SKELETAL_AND_SOFTBODY.md)** - Animation & soft body docs
- **[../README.md](../README.md)** - Main library documentation