Embedded-3dgfx

A no_std 3D graphics engine for embedded systems, built around embedded-graphics. Features a complete rendering pipeline with Z-buffering, texture mapping, lighting, 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, and Z-buffer improvements.

no_std Compatibility

This crate is fully no_std compatible by default. All core rendering features work in embedded environments without the standard library.

Feature Flags

std (includes perfcounter)

Enables std::vec::Vec for Painter's Algorithm
Enables performance counter with std timing
Required for desktop simulator examples

perfcounter (optional)

Enables PerformanceCounter module for FPS/timing measurements
Requires a timing source: either std or embassy-time
Automatically included when std is enabled

embassy-time (optional)

Provides timing for PerformanceCounter on embedded targets
Use with perfcounter feature for embedded timing

Usage Examples

Pure no_std embedded (no performance counter):

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

Embedded with Embassy timing and performance counter:

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

Desktop/simulator with all features:

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

Features

Core Rendering

Full MVP Pipeline - Model-View-Projection transformations with perspective projection
Z-buffering - Depth testing for correct occlusion with configurable epsilon
Backface Culling - Skips ~50% of faces pointing away from camera
Frustum Culling - Automatic clipping of off-screen objects (50-200% speedup)
Fixed-point Rasterization - Integer-only triangle filling optimized for embedded systems
Integer Z-buffer - 16.16 fixed-point depth values for memory efficiency

Rendering Modes

Point Cloud Rendering - 3D point visualization
Wireframe Rendering - Line-based mesh visualization
Flat Shading - Per-face solid colors
Gouraud Shading - Smooth vertex color interpolation across triangles
Painter's Algorithm - Back-to-front sorting without Z-buffer (saves 1.92MB RAM)

Lighting & Materials

Directional Lighting - Diffuse lighting with ambient term
Blinn-Phong Shading - Specular highlights with half-vector approximation
Pre-computed Lighting - Per-mesh constants for performance

Texture Mapping

Affine Texture Mapping - UV-mapped textures with nearest-neighbor sampling
TextureManager - Stores multiple textures using heapless::Vec
Power-of-2 Textures - Fast wrapping using bit masks (no divisions)
Static Texture Data - RGB565 format for embedded efficiency

Visual Effects

Fog Effects - Depth-based color blending with configurable near/far planes
Ordered Dithering - 4x4 Bayer matrix for retro visual effects
Billboard System - Camera-facing quads for particles and sprites
Vertex Animation - Keyframe interpolation for animated models

Performance Optimizations

DMA Rendering - Double-buffered rendering with platform-agnostic backend trait (~30% FPS boost)
LOD System - Distance-based mesh detail switching
Inline Optimization - Hot functions marked for aggressive inlining
Swap Chain - Asynchronous framebuffer transfers while rendering

Hardware Abstraction

DisplayBackend Trait - Platform-agnostic DMA interface
SimulatorBackend - No-op implementation for desktop testing
Mesh Loading - Import geometry from STL files

Recent Additions (2026)

Fog & Dithering Effects

Scanline-based effects with zero overhead when disabled:

let fog = FogConfig::new(Rgb565::CSS_GRAY, 5.0, 15.0);
let dither = DitherConfig { intensity: 8 };
draw_zbuffered_with_effects(prims, fb, zbuf, Some(&fog), Some(&dither));

Affine Texture Mapping

Complete texture system for embedded devices:

static TEXTURE_DATA: [Rgb565; 64] = [...];
let texture = Texture::new(&TEXTURE_DATA, 8, 8);
let mut tex_mgr = TextureManager::<16>::new();
let tex_id = tex_mgr.add_texture(texture).unwrap();

Geometry {
    vertices: &VERTS,
    uvs: &[[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]],
    texture_id: Some(tex_id),
    // ...
}

DMA Rendering (Double Buffering)

Hardware abstraction for asynchronous framebuffer transfers (~30% FPS improvement):

let mut swap_chain = SwapChain::new(
    fb0.as_mut_ptr(),
    fb1.as_mut_ptr(),
    false,
    SimulatorBackend::new(),
);

loop {
    let back_buffer = swap_chain.get_back_buffer();
    render_to(back_buffer);
    swap_chain.present().unwrap();
}

Z-Fighting Improvements

Enhanced depth buffer precision control:

// Tune camera planes for your scene depth range
camera.set_near_far(1.0, 15.0);  // Ratio: 15:1 (excellent)
println!("Ratio: {:.1}:1", camera.get_near_far_ratio());

See ZBUFFER_TUNING.md for comprehensive tuning guide.

Examples

Interactive visual examples are available in the examples/ directory. These demos use the embedded-graphics-simulator to run on desktop:

# Run examples (requires SDL2)
cargo run --example basic_rendering --features std
cargo run --example rotating_cube --features std
cargo run --example scene_viewer --features std
cargo run --example lighting_demo --features std
cargo run --example gouraud_demo --features std
cargo run --example fog_dithering_demo --features std
cargo run --example texture_mapping_demo --features std
cargo run --example dma_rendering_demo --features std

Available Examples

Core Rendering:

basic_rendering - Cycle through render modes (Points, Lines, Solid)
rotating_cube - Animated 3D rotation with FPS counter
scene_viewer - Interactive scene with camera controls

Lighting & Shading:

lighting_demo - Directional lighting demonstration
gouraud_demo - Smooth vertex color interpolation
painters_algorithm_demo - Back-to-front rendering without Z-buffer

Advanced Features:

fog_dithering_demo - Interactive fog and dithering effects
texture_mapping_demo - UV-mapped textures with multiple patterns
dma_rendering_demo - Double-buffered rendering performance comparison
billboard_demo - Camera-facing sprites and particles
lod_demo - Distance-based level of detail switching
vertex_animation_demo - Keyframe-based model animation

See examples/README.md for detailed documentation.

Recommendations for Embedded Systems

ARM Cortex-M33 with FPU (e.g., STM32WBA65RI)

Immediate Use (Production-Ready):

✓ DMA rendering - ~30% FPS improvement, essential for production
✓ Fog & dithering - Professional look with < 10% overhead
✓ Affine texture mapping - Classic 3D look, manageable performance cost
✓ Z-buffer tuning - Adjust camera near/far planes for your scene depth

Performance Budget Example: For 60 FPS (16.67ms per frame) at 240×135:

Vertex transform: 2ms (1000 vertices)
Rasterization: 10ms (500 triangles)
Clear/setup: 1ms
Display transfer: 3ms (with DMA, parallel)
Total: ~13ms → 75 FPS achievable

With optimizations:

LOD: 3-10x fewer triangles at distance
Frustum culling: 50-90% fewer objects
DMA: 30% better throughput
Result: Complex scenes at 60 FPS

Memory Considerations

Single-buffered: 1× framebuffer (e.g., 320×240×2 = 150KB)
Double-buffered: 2× framebuffer (300KB) - recommended for DMA
Z-buffer: 1× depth buffer (e.g., 320×240×4 = 300KB for u32)
Painter's Algorithm: No Z-buffer needed (saves 300KB for 320×240 scenes)

Future Enhancements

Potential additions for the library:

Perspective-correct texture mapping (upgrade from affine)
Lightmapping (baked lighting for static scenes)
Portal rendering (indoor scene optimization)
Hardware-specific display backends (ESP32, STM32, RP2040)
BSP trees (complex static scenes)
Tile-based deferred rendering

Testing

The library includes a comprehensive test suite covering all major components:

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

Test coverage includes:

Camera transformations and projections
Mesh geometry validation
Coordinate transformation and clipping
Performance counter timing
Drawing primitives (points, lines, triangles)
Texture sampling and management
Display backend and swap chain
Full rendering pipeline integration tests

Production Example

You can find a working embedded example in the Rust on M5Stack Cardputer project:

https://github.com/Kezii/Rust-M5Stack-Cardputer

https://github.com/Kezii/Rust-M5Stack-Cardputer/assets/3357750/658bd303-03c5-4dc2-9c49-75a98b667719

Contributing

Contributions are welcome! Areas of interest:

Hardware-specific display backends (ESP32, STM32, RP2040)
Perspective-correct texture mapping
Lightmapping support
Portal rendering for indoor scenes
Additional visual effects

References

Tricks of the 3D Game Programming Gurus - Classic techniques
Michael Abrash's Graphics Programming Black Book - Optimization techniques
PSX Graphics Programming - Affine texture mapping
Fabien Sanglard's Game Engine Black Books - Doom, Quake architecture

License

See LICENSE file for details.

embedded-3dgfx 0.1.2