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 Submodule Architecture (v0.5.1) — explicit embedded_3dgfx::raster::* and embedded_3dgfx::shader::* namespaces
• Zero-Cost FragmentShader Pipeline — composable decorator shaders (FogShader, DitherShader, ScreenTintShader, PaletteShader, 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-correct textures, fog, point lights, particles, LOD, HUD
• Physics (feature physics) — rigid bodies, joints, soft body, raycast with UV
• Animation — skeletal LBS, vertex morphs, transform tracks / tweens
• Embedded-friendly — heapless caps, async-agnostic swapchain present, silicon hardware offloading hooks (HardwareAccelerator)

Screenshots

cargo run --example screenshots --features std

Installation

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

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

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

MCU feature recipes

0.5 breaking change: std, aa-heuristic, and aa-coverage are no longer in the default feature set. Desktop apps should opt into std (and AA) explicitly.

Quick start

use embedded_3dgfx::{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();

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.5", features = ["std", "scene-extras"] }

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

Examples

cargo run --example rotating_cube --features std
cargo run --example custom_material_demo --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"
# physics demos also need: --features "std,physics" (many also want lighting)

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, …

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

Docs & bring-up

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.