Crate clovers

Source
Expand description

§clovers - ray tracing in rust!

Note: This library is experimental & heavily work in progress. Everything can change at a moment’s notice. It is probably not a good idea to use this library for anything other than experimentation for now!

This project uses GitHub for development and issue tracking. Link to the repository.

§Guiding thoughts

  • Keep it clean: prefer good abstractions, avoid deep integration
  • Platform agnostic: hopefully runnable by both CPU and GPU, on desktop and WebAssembly, etc
  • Prefer correctness: no “cheating” optimizations / approximations
  • Look for beautiful light <3

§How it works

There are a few core stages of using clovers.

§Creating and Loading a Scene

First, you will need a Scene. You can create a scene manually or utilize serde to deserialize from a file. Currently, the example binary uses a JSON format.

§Rendering the Scene

clovers is not opinionated on how you want to render your scene. In a usual scenario, you probably want to have some form of a pixel buffer, with knowledge of the x and y coordinates of your buffer.

  • Rendering is done by creating Rays and seeing what they hit
  • A Ray has an origin and a direction
  • Every Object has a hit() method that takes a Ray and returns an Option<HitRecord>
  • If you get None, use that information to colorize your pixel with a default color
  • If you get Some(HitRecord), use its details to colorize your pixel
  • You most likely also want to recurse: depending on the material, maybe scatter() and cast a new Ray?

You most likely want to repeat this process multiple times for each of your pixels: generating multiple samples per pixel results in a higher quality image.

§Post processing

TODO: maybe add some post processing utilities?

  • denoise support?
  • 3D & rendering aware effects?
  • etc

§Using the result

At the end, use your pixel buffer - save to an image file, draw a frame in a GUI window, etc.

Re-exports§

pub use hitrecord::HitRecord;

Modules§

aabb
Axis-aligned bounding box.
bvh
Bounding Volume Hierarchy acceleration structures and related utilities.
camera
Camera. Used for creating Rays towards the scene, with directions defined by the camera properties.
colorinit
Initialization structures for colors. This exists for deserialization purposes.
hitable
An abstraction for things that can be hit by Rays.
hitrecord
The main data structure returned for every surface intersection.
illuminants
Spectral power distributions of various illuminants.
interval
Interval helper adapted from the book
materials
Materials enable different behaviors of light on objects.
objects
Various literal objects and meta-object utilities for creating content in Scenes.
onb
Orthonormal bases
pdf
Probability density functions
random
Various internal helper functions for getting specific kinds of random values.
ray
The very core of the ray tracing rendering itself: the Ray
scenes
A collection of objects, camera, and other things necessary to describe the environment you wish to render.
spectrum
Utilities for Physically Meaningful Rendering using Tristimulus Colours
textures
Textures enable different surface textures for colorizing objects in various ways.
wavelength
The fundamental building blocks of spectral rendering.

Structs§

Box
A pointer type that uniquely owns a heap allocation of type T.
Vec
A contiguous growable array type, written as Vec<T>, short for ‘vector’.

Constants§

EPSILON_CONSTANT_MEDIUM
Internal const: epsilon used in the hit calculation of a ConstantMedium.
EPSILON_RECT_THICKNESS
Internal const: epsilon used for having a finitely-sized thickness for the bounding box of an infinitely-thin rectangle. Shouldn’t be too small.
EPSILON_SHADOW_ACNE
Internal const: epsilon used for avoiding “shadow acne”. This is mostly used for the initial minimum distance for ray hits after reflecting or scattering from a surface.
PI
Internal helper: re-exports the pi constant as our internal Float type. TODO: selectable at run time instead of build time?

Type Aliases§

Direction
Internal type alias: a nalgebra Unit of a Vector3
Displacement
Internal type alias: a nalgebra Vector3. Intended for direction and length between two points, i.e. a direction with a non-unit length
Float
Internal type alias: this allows the crate to easily switch between float precision without modifying a lot of files.
Position
Internal type alias: a nalgebra Vector3. Intended as a world-space coordinate.
Vec2
Internal type alias: a nalgebra Vector2 which is a vector with two dimensions, containing two of our internal Float types
Vec3
Internal type alias: a nalgebra Vector3 which is a vector with three dimensions, containing three of our internal Float types
Vec4
Internal type alias: a nalgebra Vector4 which is a vector with four dimensions, containing four of our internal Float types