- Rust 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
Some checks failed
CI ARM Matrix / Native tests (ARM64 Linux) (push) Has been cancelled
CI ARM Matrix / Native tests (ARM64 macOS) (push) Has been cancelled
CI ARM Matrix / Cross-check ARM targets (Ubuntu) (push) Has been cancelled
CI x86 Matrix / Native tests (macos-13) (push) Has been cancelled
CI x86 Matrix / Native tests (ubuntu-latest) (push) Has been cancelled
CI x86 Matrix / Native tests (windows-latest) (push) Has been cancelled
CI x86 Matrix / Cross-check x86 targets (Ubuntu) (push) Has been cancelled
- OBJ loader: ObjLoadError enum with 13 variants, line-numbered errors, ear-clipping triangulation, hard size/vertex/index/face limits, BOM tolerance, parse_str entry point, 24 inline adversarial tests. - Scene descriptor: strict KvMap parsing, line-numbered errors, NaN/Inf rejection, validation of fov/aperture/exposure/radius/color/roughness/ metallic ranges, material name charset, MAX_SCENE_* limits, 30 integration tests in tests/scene_descriptor_robustness.rs. - GLB loader: GlbLoadError enum with 10 variants, validate_glb_header and iter_glb_chunks public helpers, overflow-safe chunk walking via checked_add, MAX_GLB_FILE_SIZE/MAX_GLB_CHUNK_SIZE guards, no silent magic fallback, declared_length used to cap synthesis payload, 14 inline tests including deterministic xorshift fuzz. - Realtime profiles aligned to 120 FPS across hd/mobile/ultra. - Render request production preset confirmed at 3840x2160. - Cargo.toml: rust-version 1.85, include whitelist (412 files, 220 KiB compressed), invalid 'rendering' category removed, arborescence.md added for include_str! consumers. - lib.rs: missing_docs and unsafe_op_in_unsafe_fn warnings enabled, module-level doc clarifies unsafe scope (NEON SIMD, OpenGL FFI, Linux syscalls, DMA Send/Sync). - 86 tests passing, 0 failed, 0 warnings, cargo package verifies. |
||
| .cargo | ||
| .github/workflows | ||
| fpstests | ||
| src | ||
| tests | ||
| .gitignore | ||
| arborescence.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| ChangeLog.md | ||
| CONTRIBUTING.md | ||
| License | ||
| quickstat.md | ||
| ReadMe.md | ||
🎥 EngineRenderer 🎥
A zero-dependency offline rendering engine in pure Rust
CPU Path Tracing · BVH Acceleration · 16-Band Spectral Rendering · PBR Materials · Animation & Video
244 source files · ~26,350 lines · 17 material presets · 18 interpolation curves · 9+ targets
🎨 Features
Rendering Pipeline
|
Render Presets
AnimationFast ········· 1 SPP · 1 bounce · denoised previews
PreviewCpu ············ 4 SPP · 1 bounce · adaptive sampling
UltraHdCpu ············ 16 SPP · 3 bounces · high-quality stills
ProductionReference ··· 64 SPP · max bounces · reference quality
Realtime 120 FPS Profile
EngineRenderer includes a unified ultra-constrained realtime profile for --fps 120.
- Scene-side budget: proxy showcase geometry, reduced light budget, optional panorama removal
- Runtime-side budget: cached showcase meshes, static realtime scene reuse, BVH reuse
- Loop-side budget: deadline-based frame pacing with drift compensation
- Runtime adaptation: smoothed quality bias, sample pressure, scheduler granularity, and hysteresis-based internal resolution scaling
Validated runtime benchmarks (release, 3 seconds, --fps 120 --width 1280 --height 720):
- Linux x86_64: stable high-frequency cadence with adaptive runtime controls
- Android ARM64: constrained-device adaptation validated with dynamic internal resolution and scheduler tuning
🎬 Animation
| ⏱️ Timeline keyframes | Camera · sun · sky · exposure |
| 📐 18 interpolations | Linear · Step · SmoothStep · Hermite · EaseIn/Out/InOut (Quad, Cubic, Sine, Expo) · Back · Bounce |
| 🎞️ Frame sequencer | Batch rendering with caching |
| 📹 Video export | MP4 via system FFmpeg |
🏗️ Scene Building
| 🔗 Fluent API | SceneBuilder · MaterialBuilder · CameraController |
| 📄 Scene format | Text-based .scene files with serialization & parsing |
| 📦 Mesh import | OBJ · glTF/GLB |
| 🔧 Procedural | Geometry generators · mesh operations · composite objects |
⚛️ Physics & Simulation
| 💥 Rigid bodies | Constraint solving · collision detection · raycasting |
| 🪐 N-body | Gravitational simulation for celestial mechanics |
🤖 AI Integration
| 🔍 Introspection | Capabilities::discover() → JSON feature description |
| 💬 Prompt-to-scene | Natural language → renderable scene |
| 📷 Camera presets | Front · top-down · dramatic · cinematic · closeup |
🏛️ Architecture
╔══════════════════════════════════════════════════════════════════╗
║ API Layer ║
║ SceneBuilder · MaterialCatalog · CameraController ║
║ AnimationClip · Timeline · FrameSequencer ║
║ AiRenderer · Capabilities · SceneDescriptor ║
╠══════════════════════════════════════════════════════════════════╣
║ Core Engine ║
║ Path Tracer · BVH · Spectral Shading · Shadow Maps ║
║ Volumetrics · Post-Processing · Scene Graph · Physics ║
║ Animation Sequencer · Video Exporter · Scheduler ║
╠══════════════════════════════════════════════════════════════════╣
║ Hardware Abstraction Layer ║
║ CPU (topology, SIMD) · GPU (DRM/D3D12) · Display · DMA ║
╚══════════════════════════════════════════════════════════════════╝
📋 Full module breakdown: arborescence.md
🌍 Cross-Platform Support
Targets
✅ All listed targets compile successfully. ✅ |
SIMD Detection
GPU Drivers
|
🔨 Building
| Dependency | Required | Notes |
|---|---|---|
| Rust | ✅ | Edition 2024 |
| FFmpeg | ❌ | Only for MP4 export |
cargo build --release
Quick start: quickstat.md
🔀 Cross-compilation targets
cargo build --release --target aarch64-apple-darwin # Apple Silicon
cargo build --release --target aarch64-unknown-linux-gnu # ARM64 Linux
cargo build --release --target x86_64-pc-windows-gnu # Windows (MinGW)
cargo build --release --target aarch64-linux-android # Android
cargo build --release --target x86_64-unknown-linux-musl # Static Linux
🚀 Usage
CLI Mode
cargo run --release -- render # Standard render → output file
cargo run --release -- gallery # Full gallery showcase
cargo run --release -- test # Quick smoke test
cargo run --release -- detect # Hardware/compute diagnostics
cargo run --release -- video # Render animation → MP4
cargo run --release -- run # Realtime preview mode
cargo run --release -- help # Show commands
Detect / Debug options
cargo run --release -- detect --verbose
cargo run --release -- detect --json --component gpu
cargo run --release -- detect --bench --component cpu
cargo run --release -- detect --override arch=arm,os=windows,vendor=amd
Supported values:
--component:cpu,gpu,ram,display,all--override:arch=x86|arm,os=linux|windows|macos,vendor=amd|intel|apple|unknown
Interactive Terminal
Launch with no arguments for a full REPL with module navigation and built-in docs:
cargo run --release
╭───────── Root Namespace ─────────╮
│ 🚀Welcome in Helper🚀 │
│ │
│ 📦 Modules: │
│ 🧠 ai 🎬 animation │
│ 📷 camera ⚙ engine │
│ 🎨 materials 📦 objects │
│ 🌌 scenes 🧩 types │
╰──────────────────────────────────╯
📖 All REPL commands
| Command | Description |
|---|---|
open <module> |
Enter a module namespace |
call <fn> |
Execute a function |
inspect <item> |
Show details |
docs [target] [section] |
Browse source documentation |
animate [topic] |
Show execution flow |
back |
Return to root |
clear |
Clear screen |
exit |
Quit |
engine → call render · call gallery · call test · call run
animation → call spheres · call cubes · call house · call city · call car · call world · call blackhole
📚 Built-in documentation browser
The REPL reads source code directly:
engine> docs # List all topics
engine> docs readme # README
engine> docs tree # Project structure
engine> docs changelog # Changelog
engine> docs rendering # Rendering pipeline
engine> docs ai.renderer # Sub-module docs
engine> docs ai.prompt constraints # Section filter
Sections: overview · constraints · implementation · tips
Render Examples
cargo run --example render_spheres # → output/SPHERES/spheres.ppm
cargo run --example render_cubes # → output/CUBES/cubes.ppm
cargo run --example render_house # → output/HOUSES/house.ppm
cargo run --example render_city # → output/CITY/city.ppm
cargo run --example render_car # → output/CAR/car.ppm
cargo run --example render_world # → output/WORLD/world.ppm
cargo run --example render_blackhole # → output/BLACKHOLE/blackhole.ppm
🌀 Rendu vidéo / Animation
Le mode video génère une animation MP4 à partir d'une scène :
cargo run --release -- video --duration=10 --fps=30 --width=1920 --height=1080 --output-mp4=output/animation.mp4
Chargement d'une scène existante :
cargo run --release -- video --scene-file=my_scene.scene --output-mp4=output/animation.mp4
| Option | Défaut | Description |
|---|---|---|
--duration=N |
5 |
Durée en secondes |
--fps=N |
30 |
Images par seconde |
--width=N |
1280 |
Largeur en pixels |
--height=N |
720 |
Hauteur en pixels |
--quality=preview|hd|production |
preview |
Qualité de rendu |
--scene-file=PATH |
(défaut) | Scène .scene à charger |
--output-dir=PATH |
output/video |
Dossier frames temporaires |
--output-mp4=PATH |
output/video/animation.mp4 |
Fichier MP4 final |
--prefix=NAME |
frame |
Préfixe des frames |
✅ Validation Suite
The workspace includes rendering validation tests under tests/workspace_render_validation.rs:
- Visual determinism regression for preview outputs
- Parallel stress rendering over multiple workers
- Long-run pacing campaign (ignored by default)
- Diagnostics benchmark matrix campaign (ignored by default)
Run the standard suite:
cargo test
Run the dedicated workspace validation file:
cargo test --test workspace_render_validation
Run ignored long campaigns explicitly:
cargo test --test workspace_render_validation -- --ignored
Core quality gates used in this workspace:
cargo check --all-targets
cargo clippy --all-targets
📦 Library API
use enginerenderer::api::engine::Engine;
use enginerenderer::api::scenes::builder::SceneBuilder;
use enginerenderer::api::materials::catalog::MaterialCatalog;
use enginerenderer::api::objects::primitives::RenderPreset;
use enginerenderer::api::animation::{AnimationClip, Timeline, Interpolation, FrameSequencer};
Code examples
Default render:
let report = Engine::default().run()?;
println!("Rendered {}x{} in {} ms", report.width, report.height, report.duration_ms);
Production gallery:
let reports = Engine::production_reference().render_gallery()?;
for report in reports {
println!("{}", report.output_path.display());
}
Smoke test:
let report = Engine::test_minimal().run()?;
AI capabilities:
let caps = enginerenderer::api::ai::capabilities::Capabilities::discover();
Hardware diagnostics:
enginerenderer::api::diagnose_compute_environment();
📁 Output Formats
| Format | Extension | Notes |
|---|---|---|
| PPM | .ppm |
Default still image |
| EXR | .exr |
HDR framebuffer |
| PNG | .png |
Compressed stills |
| MP4 | .mp4 |
Video (FFmpeg) |
📊 Stats
| Source files | Lines of Rust | External crates | Material presets | Interpolation curves | Render presets | Targets | Edition |
|---|---|---|---|---|---|---|---|
| 244 | ~26,350 | 0 | 17 | 18 | 4 | 9+ | 2024 |