Build and run locally

Requirements

• Git and the current stable Rust toolchain, including Cargo. Install Rust with rustup.
• A native compiler and linker: Visual Studio C++ build tools on Windows, Xcode command-line tools on macOS, or your Linux distribution’s C/C++ development tools and pkg-config. See the Rust installation guide.
• A GPU and driver exposing compute shaders and storage buffers through Vulkan, Metal, or DirectX 12. Native windows use X11 or Wayland on Linux. Software Vulkan can render but may be much slower.
• Network access for the first Cargo build. External libraries, including vecmat, ccgeom, and wgame, come from crates.io; no sibling repositories are required.

Native validation has covered Intel Arc Vulkan and Mesa’s llvmpipe software Vulkan. Other drivers and operating systems may need platform-specific setup.

Get the source

git clone https://github.com/agerasev/hypertrace.git
cd hypertrace
# Use the exact source revision published with this website:
git fetch origin gh-pages
git checkout d2e08cc248ccc2e616f3f0a1c1ce9d304885f202

The first run compiles the application. Use --release for interactive rendering.

Hyperbolic space

cargo run --release -p hypertrace-examples --bin hyperbolic

Scene, screenshots, and observations

Euclidean space

cargo run --release -p hypertrace-examples --bin euclidean

Scene, screenshots, and observations

Spherical space

cargo run --release -p hypertrace-examples --bin spherical

Scene, screenshots, and observations

Euclidean fog

cargo run --release -p hypertrace-examples --bin fog

Scene, screenshots, and observations

Controls

Stop moving to let samples accumulate. Fog, small lights, and caustics need more samples than directly lit surfaces. Changing the camera resets accumulation.

Other examples and scene editing

cargo run --release -p hypertrace-examples --bin ball-tilings
cargo run --release -p hypertrace-gallery --bin viewer -- --list-scenes

Edit examples/src/bin/<name>/scene.rs to change objects and materials; main.rs shows renderer initialization and camera input. The example guide describes all demonstrations and how to create your own.

Render a still image

cargo run --release -p hypertrace-gallery --bin headless -- \
  --scene spherical --width 2560 --height 1920 --samples 4096 --batch 1 \
  --seed 3735928559 --output spherical

This writes spherical.ppm, linear spherical.rgba32f, and spherical.json. For a detail view, add --fov 0.6 --yaw 0.2 --pitch 0.1. Angles are local offsets in radians; fov is tan(vertical field of view / 2). Camera settings are included in the JSON.

Gallery images link to their exact settings and source revision. Earlier captures can differ from the current scene. To reproduce one, check out its recorded revision and use its recorded scene ID, dimensions, sample count, seed, event budget, and camera settings.

If rendering does not start

• No suitable adapter: update the graphics driver and check that a compute-capable device is exposed. For native troubleshooting, select an available WGPU backend, for example WGPU_BACKEND=vulkan cargo run --release -p hypertrace-examples --bin spherical on Linux.
• Driver resets during a long capture: use --batch 1 to reduce individual dispatch duration.
• Requested image exceeds storage limits: reduce headless width and height. Windowed viewers fit the render resolution to the device and scale the result for display.
• Mouse capture denied: left-drag remains available; release capture in another application and retry Tab.
• Browser viewer unavailable: each example reports its startup failure and links here. WebGPU requires a secure context and a supporting browser/driver configuration. Native running uses the commands above; no browser, Trunk, or WebAssembly installation is needed.