Sovereign 8s.is mirror of standardgalactic/EngineRenderer
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Rayan Morel 5a7b0b5477
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
Harden OBJ/scene/GLB parsers and prepare crates.io packaging
- 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.
2026-04-22 13:12:10 +02:00
.cargo chore: apply pending workspace changes 2026-04-20 03:52:26 +02:00
.github/workflows ci: maximize architecture/os target coverage 2026-04-14 22:31:29 +02:00
fpstests chore: apply pending workspace changes 2026-04-20 03:52:26 +02:00
src Harden OBJ/scene/GLB parsers and prepare crates.io packaging 2026-04-22 13:12:10 +02:00
tests Harden OBJ/scene/GLB parsers and prepare crates.io packaging 2026-04-22 13:12:10 +02:00
.gitignore initial commit 2026-04-12 14:41:24 +02:00
arborescence.md Harden OBJ/scene/GLB parsers and prepare crates.io packaging 2026-04-22 13:12:10 +02:00
Cargo.lock refactor: terminal_mode → multi-file module + hardware detect command 2026-04-14 18:08:11 +02:00
Cargo.toml Harden OBJ/scene/GLB parsers and prepare crates.io packaging 2026-04-22 13:12:10 +02:00
ChangeLog.md Harden OBJ/scene/GLB parsers and prepare crates.io packaging 2026-04-22 13:12:10 +02:00
CONTRIBUTING.md chore: apply pending workspace changes 2026-04-20 03:52:26 +02:00
License refactor: terminal_mode → multi-file module + hardware detect command 2026-04-14 18:08:11 +02:00
quickstat.md Harden OBJ/scene/GLB parsers and prepare crates.io packaging 2026-04-22 13:12:10 +02:00
ReadMe.md Harden OBJ/scene/GLB parsers and prepare crates.io packaging 2026-04-22 13:12:10 +02:00

🎥 EngineRenderer 🎥

A zero-dependency offline rendering engine in pure Rust


CPU Path Tracing · BVH Acceleration · 16-Band Spectral Rendering · PBR Materials · Animation & Video


Rust Platforms Build Matrix Crates License


244 source files · ~26,350 lines · 17 material presets · 18 interpolation curves · 9+ targets


🎨 Features

Rendering Pipeline

🔦 Path Tracing Configurable SPP (1–64+), multi-bounce, BVH-accelerated
🌈 Spectral 16-band wavelength dispatch, CIE 1931 XYZ conversion
🪩 PBR Materials Albedo · roughness · metallic · emission · IOR · subsurface · anisotropy · iridescence · clearcoat · transmission
🎭 17 Presets Stellar · planetary · manufactured · celestial · natural
💡 Lighting Area lights · soft shadows · cascaded shadow maps (PCF + contact)
🌫️ Volumetrics God rays · participating media · atmospheric scattering · clouds
✨ Post-Processing Bloom · blur · depth-of-field (physical lens) · tone mapping
🏎️ Motion Blur Time-sampled primitives
🎯 Optimization Adaptive sampling · firefly rejection · denoising · frustum culling · LOD

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

Target Arch OS
x86_64-unknown-linux-gnu x86_64 Linux
i686-unknown-linux-gnu x86 Linux
aarch64-unknown-linux-gnu ARM64 Linux
armv7-unknown-linux-gnueabihf ARMv7 Linux
x86_64-apple-darwin x86_64 macOS Intel
aarch64-apple-darwin ARM64 macOS Silicon
x86_64-pc-windows-gnu x86_64 Windows
i686-pc-windows-gnu x86 Windows
aarch64-linux-android ARM64 Android
  • musl variants for static linking

✅ All listed targets compile successfully.

✅ cargo clippy --target x86_64-pc-windows-gnu passes cleanly.

SIMD Detection

ISA Extensions
x86 / x86_64 SSE4.2 · AVX · AVX-512
ARM / AArch64 NEON · SVE
Fallback Scalar paths

GPU Drivers

OS Drivers
Linux amdgpu radeon i915 xe nouveau mali msm
Windows D3D12 / DXGI
macOS AppleGPU · Intel iGPU

Automatic CPU fallback if no GPU available


🔨 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

License

MIT