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

Record / execute — traverse once, rasterize from a fixed-capacity command buffer (optional tiled / textured execute)
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, optional DMA2D / Embassy hooks

Screenshots

cargo run --example screenshots --features std

Installation

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

# With physics
embedded-3dgfx = { version = "0.4", features = ["physics"] }

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

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

Flag	Default	Description
`std`	on	Painter's algorithm helpers, `perfcounter`
`physics`	off	Rigid body, soft body, physics raycast
`aa-heuristic` / `aa-coverage`	on	Triangle edge AA (coverage needs a W×H buffer)
`row_width_*`	`240`	Row-buffer width (`96` / `160` / `240` / `320`, mutually exclusive)
`dsp` / `fixed-transform` / `fixed-raster`	off	Shared Q16.16 / quat path via `embedded-dsp`
`triple-buffering` / `embassy` / `dma2d`	off	Swapchain / Embassy / DMA2D hooks
`perfcounter` / `dwt-profiler` / `rtt-trace` / `itm-trace`	off	Timing / trace sinks

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

Feature	What you get
`aabb-cull`	Cached AABB, two-stage frustum cull, raycast broadphase
`render-layers`	Camera ↔ mesh layer bitmasks
`record-sort`	Priority / distance sort in `record`
`lod-crossfade`	LOD fade margins
`anim-blend`	Clip blending, bone slerp, skinned AABBs
`gizmos`	AABB / frustum debug wireframes
`visibility-extras`	`aabb-cull` + `render-layers` + `record-sort` + `lod-crossfade`
`scene-extras`	All of the above

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

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

Examples

cargo run --example <name> --features std
# 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, …

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

Doc	Topic
`docs/caps-and-telemetry.md`	Caps, telemetry, CI budgets
`docs/backend-integration.md`	Board bring-up, memory sizing
`docs/asset-pipeline.md`	Offline assets / scene streaming

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.

embedded-3dgfx 0.4.2