Skip to content

Latest commit

 

History

History
92 lines (67 loc) · 4.5 KB

README.md

File metadata and controls

92 lines (67 loc) · 4.5 KB
Raw

YARR - Native & Web-based Raytracing

Try it here: Web Demo Link

YARR - Yet Another Rust Raytracer

Pirate speak for "Yet Another Rust Raytracer"

YARR is the result of my personal journey with learning Rust. It also led me to cross-compiling to WebAssembly along the way.

I'm a C/C++ programmer at heart, yet my heart grows ever so fonder for Rust. Rust gives C++ a run for its money.

  • Based on Peter Shirley's great "Raytracing in One Weekend" book series
  • Core implementation in Rust, with some JavaScript glue for the web
  • Builds natively for Windows, MacOS, Linux & Web (JavaScript & WebAssembly)
  • Multi-threaded via rayon, wasm-bind-rayon, and a manually managed web worker pool
  • Tested on iOS/Android via Chrome browser

Software Prerequisites

Before you start, clone the source project. All commands listed below assumes you are in the root source directory.

Install Rust, Nightly Toolchain & NPM Packages

If you haven't already, you'll need Rust and NPM installed.

One of the best tools for Rust development is VSCode. I have this installed with these extensions: gitlens, rustanalyzer, bettertoml and powershell (for windows). If you're on windows, you'll need powershell 7.0+ (which is the version that comes with the VSCode powershell extension).

Install toolchain

One of the multi-threaded paths uses wasm-bindgen-rayon, which requires atomics and shared memory. These features are not included in stable rust, so you'll need to use a nightly version of rust to compile with these features enabled.

After this command, you may get an error: 'found a virtual manifest 'some_location' instead of a package manifest', you can safely ignore this.

cargo install

And add nightly toolchain sources:

rustup component add rust-src --toolchain nightly-2022-02-05

Install wasm-pack

cargo install wasm-pack

Windows users: the previous step may fail for you. If so, try the manual installer: Windows wasm-pack installer

Mac users with M1 chips: you will need to have Rosetta installed as some of the tools (like wasm-bin-gen) are pre-compiled against x86.

Install npm packages

npm --prefix ./web install

Build & Run Console App

Running will output a file (output.png) to the current directory.

cargo build --release
cargo run --release

Build & Run Web App

The node-js serve app is configured to serve cross-origin headers, needed by wasm-bind-rayon.

npm --prefix ./web run build
npm --prefix ./web run host

References

Learning rust

I recently joined the Rust Gang by reading Programming Rust: Fast, Safe Systems Development. It introduces and deep-dives the Rust language from the perspective of systems development. Sprinkled with light "programmer humor", it's a surprisingly fun read. If you are coming from another systems language such as C/C++, this is the book for you.

Learning raytracing

If you're new to raytracing, I highly recommend you take a weekend (or two!) and go through Peter Shirley's RayTracing in One Weekend series of books. It's a great read and this project's raytracing core is based on it.

WebAssembly & multi-threading on the web

The following are great resources in learning how to setup Rust & WebAssembly for the web.

Special Thanks

I'd like to thank the following people:

  • Peter Shirley, for the wonderful One Weekend book series
  • Diep Mai, for introducing me to Rust
  • Last but not least, thanks to my wonderful wife for giving me the space to work on this pet project

Icons courtesy of Flat Icon

License

This is free and open-source software distributed under the MIT License. Take this and go get 'em tiger.