embedded-3dgfx

A no_std 3D graphics and physics engine for embedded systems: software rasterization, rigid/soft-body physics, skeletal animation, and effects tuned for MCUs.

Fork of embedded-gfx by Kezii, extended with textures, fog/dithering, DMA swapchains, AA, physics, BSP, and more.

Highlights

• Modular Architecture — explicit raster, shader, shapes, camera_controller, navmesh, absm, and input namespaces
• Zero-Cost FragmentShader Pipeline — composable decorator shaders (FogShader, DitherShader, ScreenTintShader, PaletteShader, WaterReflectShader, or custom materials)
• Record / execute — traverse once, rasterize from a fixed-capacity command buffer (PrimitiveHeader + packed typed descriptors for low RAM footprint)
• Rendering — MVP + frustum/backface cull, Z-buffer, flat/Gouraud/Blinn-Phong, perspective textures, Bayer dither, Reinhard tonemapping, sub-pixel Q16.16 rasterization, lights, particles, LOD, HUD
• Physics & Navigation (features physics, scene) — rigid bodies, joints, soft body, ray primitives, NavMesh A* pathfinding
• Animation — skeletal LBS, vertex morphs, ABSM state machines, transform tracks, spline curves / tweens
• Embedded-friendly — heapless caps, Cortex-M SWAR/DSP SIMD optimizations, async-agnostic swapchain present, silicon hardware offloading hooks (HardwareAccelerator)

Screenshots

cargo run --release --example screenshots --features "std,lighting,textured,raycast,scene,physics"

Installation

[dependencies]
# Embedded (no_std) — slim default is row_width_240
embedded-3dgfx = { version = "0.6", default-features = false, features = ["row_width_320", "depth-u16"] }

# Orientation-style lit meshes
embedded-3dgfx = { version = "0.6", default-features = false, features = ["row_width_320", "depth-u16", "lighting"] }

# Desktop / simulator
embedded-3dgfx = { version = "0.6", features = ["std", "physics"] }

MCU feature recipes

Quick start

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

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

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

let mut commands = embedded_3dgfx::command_buffer::CommandBuffer::<512>::new();
engine.record(core::iter::once(&mesh), &mut commands, None).unwrap();
engine.execute(&mut display, &mut frame_ctx, &commands, None).unwrap();

Geometry & Surface Normals for Lighting

When using lit render modes (RenderMode::SolidLightDir, BlinnPhong, Toon, GouraudLightDir), the engine requires surface face normals in Geometry.normals (or vertex_normals) to evaluate light angles (N · L):

• Static Flash ROM Storage (Recommended for MCUs): Precompute face normals offline or at compile-time and store them alongside vertices as &'static [[f32; 3]] (0 RAM overhead).
• On-Demand Helper: If authoring procedural geometry in code, use Geometry::compute_face_normals_into(&verts, &faces, &mut out_normals) or Geometry::compute_face_normals(&verts, &faces):

let mut normals = [[0.0f32; 3]; CUBE_FACES.len()];
Geometry::compute_face_normals_into(&CUBE_VERTS, &CUBE_FACES, &mut normals);

let geometry = Geometry {
    vertices: &CUBE_VERTS,
    faces: &CUBE_FACES,
    normals: &normals,
    ..Default::default()
};

More patterns (particles, lights, fog, physics, skeleton, soft body, async present) live under examples/ and on docs.rs.

Feature flags

Flash impact of the slim recipes is tracked in docs/feature-size.md (size_harness + CI budget).

Optional scene extras (off by default — keeps MCU binaries lean)

embedded-3dgfx = { version = "0.6", features = ["std", "scene-extras"] }

cargo test --test scene_extras --features "std,scene-extras"

Examples

cargo run --example rotating_cube --features std
cargo run --example lighting_demo --features "std,lighting"
cargo run --example texture_mapping_demo --features "std,textured"
cargo run --example skeletal_animation_demo --features "std,scene"
cargo run --example star_striker_demo --features "std,lighting,scene"
# physics demos also need: --features "std,physics"

Rendering: basic_rendering, rotating_cube, scene_viewer, lighting_demo, gouraud_demo, blinn_phong_demo, fog_dithering_demo, texture_mapping_demo, mesh_texture_demo, retro_presets_demo, bsp_builder_demo, dma_rendering_demo, billboard_demo, lod_demo, vertex_animation_demo, painters_algorithm_demo, boot_menu, stl_viewer, water_reflection_ssr_demo, hybrid_hud_sprite_demo, star_striker_demo, …

Physics: physics_rolling_ball, physics_bouncing_balls, physics_pendulum, physics_newtons_cradle, physics_stack_tower, cloth_simulation, jelly_cube_demo, raycast_demo, walkable_demo, capsule_physics_demo, …

Docs & tools

Typical target: Cortex-M4F/M33 with FPU; ~128 KB RAM minimum, ~512 KB+ recommended for double-buffer + Z + physics at 240×135.

Testing

cargo test --lib
cargo test --lib --features dma2d,depth-u16
cargo test --test scene_extras --features "std,scene-extras"

Git hooks (fmt on commit / push): ./scripts/install-git-hooks.sh

Contributing

PRs welcome — especially board backends, broad-phase spatial structures, and extra joint / collider types.

License

Dual-licensed under MIT OR Apache-2.0. See LICENSE-MIT, LICENSE-APACHE, and NOTICE.