Embedded-3dgfx

A complete no_std 3D graphics and physics engine for embedded systems. Features real-time rendering, rigid body dynamics, soft body physics, skeletal animation, and advanced visual effects optimized for resource-constrained devices.

Note: This is a fork of embedded-gfx by Kezii. This fork adds texture mapping, fog/dithering effects, DMA rendering, Z-buffer improvements, and a complete physics engine.

🌟 Key Features

🎨 3D Graphics Rendering

Complete MVP Pipeline - Model-View-Projection with perspective projection
Z-buffering - Hardware-style depth testing with tunable epsilon
Advanced Shading - Flat, Gouraud, directional lighting, Blinn-Phong specular
Texture Mapping - Affine UV mapping with multi-texture support
Visual Effects - Fog, dithering, billboards, vertex animation
LOD System - Distance-based mesh detail switching
Performance - Frustum culling, backface culling, DMA rendering

⚛️ Physics Engine

Rigid Body Dynamics - Linear/angular motion, forces, torques
Collision Detection - Sphere, AABB, and Capsule colliders
Collision Response - Impulse-based with friction and restitution
Constraints - Distance, ball-socket, and fixed joints
Ray Casting - Line-of-sight, shooting, object selection
Body Management - Activation/deactivation, lifecycle control

🦴 Skeletal Animation

Bone Hierarchy - Parent-child skeletal structures
Linear Blend Skinning - Smooth vertex deformation (SSD)
Multi-Bone Influence - Up to 4 bones per vertex
Real-time Animation - Interactive character animation

🧊 Soft Body Physics

Mass-Spring Systems - Deformable objects (cloth, jelly, soft bodies)
Pressure Preservation - Volume maintenance for enclosed bodies
Collision Response - Ground collision with friction
Pre-built Shapes - Cloth grids, jelly cubes, soft spheres

🚀 Quick Start

Installation

[dependencies]
# For embedded (no_std)
embedded-3dgfx = { version = "0.1", default-features = false }

# For desktop/simulator with all features
embedded-3dgfx = { version = "0.1", features = ["std"] }

Basic Example

use embedded_3dgfx::{K3dengine, mesh::{Geometry, K3dMesh, RenderMode}};
use nalgebra::Vector3;

// Create engine
let mut engine = K3dengine::new(320, 240);
engine.camera.set_position(Vector3::new(0.0, 0.0, 5.0).into());

// Create a cube mesh
let geometry = Geometry { vertices: &CUBE_VERTS, faces: &CUBE_FACES, /* ... */ };
let mut mesh = K3dMesh::new(geometry);
mesh.set_render_mode(RenderMode::Lines);

// Render
engine.render(std::iter::once(&mesh), |primitive| {
    draw(primitive, &mut display);
});

Physics Example

use embedded_3dgfx::physics::{PhysicsWorld, RigidBody, Collider, Ray};
use nalgebra::Vector3;

// Create physics world
let mut world = PhysicsWorld::<16, 4>::new();
world.set_gravity(Vector3::new(0.0, -9.81, 0.0));

// Add a falling sphere
let sphere = RigidBody::new(1.0)
    .with_collider(Collider::Sphere { radius: 0.5 })
    .with_position(Vector3::new(0.0, 10.0, 0.0));
world.add_body(sphere);

// Add static ground
let ground = RigidBody::new_static()
    .with_collider(Collider::Aabb { half_extents: Vector3::new(10.0, 0.5, 10.0) });
world.add_body(ground);

// Simulate
world.step::<8>(0.016);

// Ray cast
let ray = Ray::new(Vector3::zeros(), Vector3::new(0.0, -1.0, 0.0));
if let Some(hit) = world.ray_cast(&ray, 100.0) {
    println!("Hit at distance: {}", hit.distance);
}

🎮 Examples

The project includes 23+ interactive examples. Run with:

cargo run --example <name> --features std

3D Rendering Examples

Core Rendering:

basic_rendering - Render mode cycling (Points, Lines, Solid)
rotating_cube - Animated 3D transformations
scene_viewer - Interactive multi-mesh scene

Lighting & Effects:

lighting_demo - Directional lighting with ambient
gouraud_demo - Smooth color interpolation
blinn_phong_demo - Specular highlights
fog_dithering_demo - Atmospheric effects

Advanced Features:

texture_mapping_demo - UV-mapped textures
dma_rendering_demo - Double-buffer performance
billboard_demo - Camera-facing quads
lod_demo - Level of detail switching
vertex_animation_demo - Keyframe animation
stl_viewer - Load and view STL models

Physics Examples

Rigid Body Dynamics: (See PHYSICS_EXAMPLES.md)

physics_rolling_ball ⭐ START HERE - Beginner-friendly intro
physics_bouncing_balls - Multiple colliding spheres
physics_pendulum - Swinging pendulum with constraints
physics_newtons_cradle - Newton's cradle with chain constraints
physics_stack_tower - Stacking boxes with friction
physics_domino_chain - Domino effect simulation
physics_wrecking_ball - Wrecking ball demolition
physics_demo - Comprehensive physics showcase
capsule_physics_demo - Capsule collider interactions

Advanced Physics: (See SKELETAL_AND_SOFTBODY.md)

skeletal_animation_demo - Bone hierarchy and skinning
cloth_simulation - Hanging cloth with wind
jelly_cube_demo - Soft deformable cube
raycast_demo - Ray casting and hit detection

📚 Feature Flags

`std` (includes `perfcounter`)

Enables Painter's Algorithm (uses std::vec::Vec)
Performance counter with std timing
Required for desktop simulator examples

`perfcounter` (optional)

Enables FPS/timing measurements
Requires timing source: std or embassy-time
Automatically included with std

`embassy-time` (optional)

Timing for embedded targets using Embassy framework
Use with perfcounter for embedded performance monitoring

`row_width_*` (mutually exclusive)

row_width_160 - Optimize for 160px wide displays
row_width_240 - Optimize for 240px wide displays (default)
row_width_320 - Optimize for 320px wide displays

🎯 Core Rendering Features

Rendering Pipeline

Full MVP Transforms - Model-View-Projection with perspective
Z-buffering - 16.16 fixed-point depth testing
Backface Culling - ~50% face elimination
Frustum Culling - 50-200% speedup for off-screen objects
Optimized Rasterization - Integer-only triangle filling

Shading & Lighting

Flat Shading - Per-face solid colors
Gouraud Shading - Smooth vertex color interpolation
Directional Lighting - Diffuse with ambient term
Blinn-Phong - Specular highlights with half-vector
Pre-computed Constants - Per-mesh optimization

Visual Effects

Fog - Depth-based atmospheric effects
Dithering - 4×4 Bayer matrix ordered dithering
Billboards - Camera-facing sprites
Vertex Animation - Keyframe interpolation

Texturing

Affine Mapping - UV-based texture coordinates
Multi-texture - Multiple textures per scene
Power-of-2 Optimization - Fast wrapping with bit masks
RGB565 Format - Memory-efficient 16-bit color

Performance Systems

DMA Rendering - ~30% FPS boost with double buffering
LOD - 3-10× triangle reduction at distance
Swap Chain - Asynchronous buffer transfers
Inline Optimization - Aggressive hot-path inlining

⚛️ Physics System

Rigid Body Dynamics

let body = RigidBody::new(1.0)
    .with_collider(Collider::Capsule { height: 2.0, radius: 0.5 })
    .with_position(Vector3::new(0.0, 5.0, 0.0))
    .with_restitution(0.6)  // Bounciness
    .with_friction(0.5);     // Surface friction

Collision Detection

Sphere Collider - Cheapest, perfect for balls and particles
AABB Collider - Boxes, platforms, walls (axis-aligned)
Capsule Collider - Best for characters (efficient + smooth)
Broad Phase - O(n²) narrow-phase only (spatial partitioning planned)

Constraints & Joints

// Distance constraint (rope, rod)
world.add_constraint(Constraint::Distance {
    body_a: ball_id,
    body_b: anchor_id,
    rest_length: 2.0,
    compliance: 0.0,  // Stiffness
});

// Ball-socket joint (ragdoll)
world.add_constraint(Constraint::BallSocket { /* ... */ });

// Fixed joint (welding)
world.add_constraint(Constraint::Fixed { /* ... */ });

Ray Casting

let ray = Ray::new(origin, direction);
if let Some(hit) = world.ray_cast(&ray, 100.0) {
    println!("Hit body {:?} at {}", hit.body_id, hit.distance);
    println!("Point: {:?}, Normal: {:?}", hit.point, hit.normal);
}

🦴 Skeletal Animation

let mut skeleton = Skeleton::<8>::new();
let root = skeleton.add_bone(Bone::new("root"), None).unwrap();
let arm = skeleton.add_bone(
    Bone::new("arm").with_position(Vector3::new(0.0, 1.0, 0.0)),
    Some(root)
).unwrap();

skeleton.update_transforms();
skeleton.compute_inverse_bind_poses();

// Animate
skeleton.get_bone_mut(arm).unwrap().set_rotation(rotation);
skeleton.update_transforms();

// Apply to mesh
apply_skinning(&skeleton, &skinning_data, &bind_vertices, &mut deformed);

🧊 Soft Body Physics

// Create cloth (8×8 grid)
let mut cloth = SoftBody::<64, 256>::create_cloth(8, 8, 0.4, 200.0, 1.0).unwrap();
cloth.set_gravity(Vector3::new(0.0, -9.81, 0.0));

// Create jelly cube (3×3×3 particles)
let mut jelly = SoftBody::<64, 256>::create_jelly_cube(3, 0.5, 150.0, 0.5).unwrap();
jelly.pressure_config.enabled = true;  // Volume preservation

// Simulate
cloth.step(0.016);
jelly.step(0.016);

// Get deformed vertices for rendering
cloth.get_vertex_positions(&mut vertex_buffer);

📋 System Requirements

Embedded Targets

Minimum:

ARM Cortex-M4F (with FPU)
128KB RAM (single-buffer + small scenes)
256KB+ Flash

Recommended:

ARM Cortex-M33 with FPU (e.g., STM32WBA)
512KB+ RAM (double-buffer + Z-buffer + physics)
512KB+ Flash

Performance Budget (240×135 @ 60 FPS)

Rendering: ~10-13ms per frame
Physics (16 bodies): ~2-3ms per frame
Display transfer (DMA): ~3ms (parallel)
Total: 60+ FPS achievable

Memory Usage

Feature	Memory Cost
Single framebuffer (240×135)	65 KB
Double framebuffer (240×135)	130 KB
Z-buffer (240×135)	130 KB
Physics (16 bodies)	~4 KB
Soft body (64 particles)	~2 KB
Skeleton (8 bones)	~1 KB

Total typical usage: 200-300 KB RAM

🧪 Testing

# Run all 182 tests
cargo test

# Run library tests only
cargo test --lib

# Test with all features
cargo test --lib --all-features

Test Coverage:

✅ 182 passing tests
✅ Rendering pipeline (transformations, clipping, rasterization)
✅ Physics (collisions, constraints, integration)
✅ Skeletal animation (skinning, bone hierarchy)
✅ Soft body (springs, particles, pressure)
✅ Ray casting (all collider types)

📦 no_std Compatibility

Fully no_std compatible by default. All core features work without the standard library.

Feature Flag Combinations

Pure Embedded (no_std):

embedded-3dgfx = { version = "0.1", default-features = false }

Embedded with Embassy Timing:

embedded-3dgfx = { version = "0.1", default-features = false, features = ["perfcounter", "embassy-time"] }

Desktop/Simulator:

embedded-3dgfx = { version = "0.1", features = ["std"] }

Custom Row Width:

embedded-3dgfx = { version = "0.1", default-features = false, features = ["row_width_320"] }

🎯 Use Cases

Game Development

✅ Character controllers (capsule colliders + ray casting)
✅ Projectile physics (rigid bodies + continuous motion)
✅ Skeletal animation (characters, creatures)
✅ Particle systems (billboards + soft bodies)
✅ Level geometry (static AABB colliders)

Simulations

✅ Robotics visualization (skeletal arms, kinematics)
✅ Physics demonstrations (pendulum, Newton's cradle)
✅ Cloth/soft body (flags, deformable objects)
✅ Mechanical systems (constraints, joints)

Embedded Displays

✅ STM32 with LCD displays
✅ ESP32 with TFT screens
✅ RP2040 with displays
✅ M5Stack devices

📚 Documentation

PHYSICS_EXAMPLES.md - Complete physics demo guide
SKELETAL_AND_SOFTBODY.md - Animation & soft body documentation
examples/README.md - All examples with screenshots
API Docs - cargo doc --open

🏗️ Architecture

embedded-3dgfx/
├── src/
│   ├── lib.rs              # Main engine & rendering
│   ├── camera.rs           # View/projection matrices
│   ├── mesh.rs             # Geometry & LOD
│   ├── draw.rs             # Rasterization & effects
│   ├── physics.rs          # Rigid body dynamics (3048 lines)
│   ├── skeleton.rs         # Skeletal animation (470 lines)
│   ├── softbody.rs         # Soft body physics (749 lines)
│   ├── texture.rs          # Texture management
│   ├── billboard.rs        # Camera-facing quads
│   ├── animation.rs        # Keyframe animation
│   ├── swapchain.rs        # DMA double-buffering
│   ├── perfcounter.rs      # Performance monitoring
│   └── painters.rs         # Painter's algorithm
│
├── examples/               # 23 interactive demos
│   ├── basic_rendering.rs
│   ├── rotating_cube.rs
│   ├── physics_*.rs        # 8 physics demos
│   ├── cloth_simulation.rs
│   ├── skeletal_animation_demo.rs
│   ├── raycast_demo.rs
│   └── ...
│
└── load_stl/              # STL file embedding macro

🔧 Performance Optimizations

Recent performance improvements (2026):

✅ Interpolator-based rasterization - Faster triangle filling
✅ FnvIndexSet edge deduplication - Faster mesh processing
✅ Configurable row buffers - Memory/speed trade-off
✅ Inline hot paths - Better compiler optimization
✅ mem::swap optimizations - Reduced allocations

Measured improvements:

Triangle rasterization: ~20% faster
Edge generation: ~30% faster
Memory usage: Configurable (160-320px row buffers)

🎓 Learning Resources

Start with these examples in order:

rotating_cube - Learn basic 3D rendering
physics_rolling_ball ⭐ - Understand physics basics
lighting_demo - Explore shading
skeletal_animation_demo - See advanced animation
cloth_simulation - Experience soft body physics

🤝 Contributing

Contributions welcome! Priority areas:

Hardware-specific display backends (ESP32, STM32, RP2040)
Spatial partitioning (octree/grid for broad-phase)
More joint types (hinge, slider, prismatic)
Perspective-correct texture mapping
Character controller system
Mesh colliders (convex hulls)

🌟 Production Use

Working embedded example: Rust on M5Stack Cardputer

📖 References

Graphics:

Physics:

Game Physics Engine Development
Real-Time Collision Detection
Game Programming Gems (Physics sections)

📜 License

MIT OR Apache-2.0 - See LICENSE file for details.

Built with ❤️ for the embedded Rust community

embedded-3dgfx 0.2.0

Embedded-3dgfx

🌟 Key Features

🎨 3D Graphics Rendering

⚛️ Physics Engine

🦴 Skeletal Animation

🧊 Soft Body Physics

🚀 Quick Start

Installation

Basic Example

Physics Example

🎮 Examples

3D Rendering Examples

Physics Examples

📚 Feature Flags

std (includes perfcounter)

perfcounter (optional)

embassy-time (optional)

row_width_* (mutually exclusive)

🎯 Core Rendering Features

Rendering Pipeline

Shading & Lighting

Visual Effects

Texturing

Performance Systems

⚛️ Physics System

Rigid Body Dynamics

Collision Detection

Constraints & Joints

Ray Casting

🦴 Skeletal Animation

🧊 Soft Body Physics

📋 System Requirements

Embedded Targets

Performance Budget (240×135 @ 60 FPS)

Memory Usage

🧪 Testing

📦 no_std Compatibility

Feature Flag Combinations

🎯 Use Cases

Game Development

Simulations

Embedded Displays

📚 Documentation

🏗️ Architecture

🔧 Performance Optimizations

🎓 Learning Resources

🤝 Contributing

🌟 Production Use

📖 References

📜 License

`std` (includes `perfcounter`)

`perfcounter` (optional)

`embassy-time` (optional)

`row_width_*` (mutually exclusive)