ConstructCraft

cc_raytracing API

← API reference · Generated from the source by cargo run -p api_doc; edit the doc comments, not this page.

Photorealistic rendering of a 3D view: path tracing on the pure Rust sort-raytracing library, with no GPU. RenderScene::build turns the solids a view shows (its visibility, phase and design options through cc_views’ graphics resolver, its detail level, painted faces, material textures laid as the 3D view’s textures style lays them, smooth normals across curved facets) into the path tracer’s triangles and materials (materials), lights them with a small generated sky, ground and sun (environment) and places the camera the viewport has (camera). run then refines the picture a few samples at a time, handing each step to a callback that may stop it (an application shows it while it converges); render_image renders it to the end. An Image holds linear radiance, which Image::to_rgba8 exposes, tone maps and encodes for display and Image::save writes as PNG or JPEG (or linear as EXR or HDR). The model is Z up; the path tracer is Y up (its sky’s poles are on its Y axis), so every point and direction goes through space: (x, y, z) becomes (x, z, -y), a rotation, so windings and normals are kept. The scene is also moved so the model’s center is at the origin, which keeps the path tracer’s f32 precise for models far from the project origin. The library may panic on input it does not expect; every call into it is made inside catch_unwind, and a panic comes back as RenderError::Internal. Input is checked before that: non-finite or degenerate triangles are dropped, cameras and settings validated, and scenes past MAX_TRIANGLES refused.

Modules

Module Items Summary
cc_raytracing 2 Photorealistic rendering of a 3D view: path tracing on the pure Rust sort-raytracing library, with no GPU.
cc_raytracing::camera 4 The render’s camera: the 3D view’s orbit camera (CameraState) as a pinhole camera of the path tracer, framing the picture the viewport frames (its perspective has a vertical field of view of 45°, the default of cc_core::RenderSettings::fov_deg) at the render’s aspect.
cc_raytracing::environment 15 The light around the model: a generated sky map with the ground below the horizon, a sun, and an optional ground plane that catches shadows.
cc_raytracing::materials 12 The path tracer’s materials, made from the model’s.
cc_raytracing::render 7 Rendering a RenderScene: progressively with a callback that sees each step and may stop the render (run), or to the end (render_image), and the image it gives (Image).
cc_raytracing::scene 2 The scene of a render: the triangles, materials, lights and camera of a view, owned so a worker thread can render it.
cc_raytracing::space 3 The path tracer’s frame.

cc_raytracing

crates/cc_raytracing/src/lib.rs

Re-exports

Items: RenderError · guarded

enum RenderError

pub enum RenderError

What went wrong building or rendering a scene, or writing its image.

Traits: Debug, Clone, PartialEq, Error

Variants

fn guarded

pub(crate) fn guarded<T>(what: &str, f: impl FnOnce() -> T) -> Result<T, RenderError>

Run f, turning a panic into RenderError::Internal.

cc_raytracing::camera

crates/cc_raytracing/src/camera.rs

The render’s camera: the 3D view’s orbit camera (CameraState) as a pinhole camera of the path tracer, framing the picture the viewport frames (its perspective has a vertical field of view of 45°, the default of cc_core::RenderSettings::fov_deg) at the render’s aspect.

Items: VIEWPORT_FOV_DEG · eye_and_forward · tracer_camera · fit

const VIEWPORT_FOV_DEG

pub const VIEWPORT_FOV_DEG: f64

The field of view of the 3D viewport, degrees (vertical).

fn eye_and_forward

pub fn eye_and_forward(camera: &CameraState) -> Result<(DVec3, DVec3), RenderError>

The eye and the unit direction the camera looks along, in model coordinates. A camera with no distance (or a negative one) stands at its target, still looking along its yaw and pitch.

fn tracer_camera

pub(crate) fn tracer_camera(camera: &CameraState, fov_deg: f64, width: u32, height: u32, space: &Space) -> Result<Camera, RenderError>

The path tracer’s camera for camera with a vertical field of view of fov_deg and an image of width × height pixels, in space.

fn fit

pub fn fit(camera: &CameraState, geom: &ModelGeometry, fov_deg: f64, aspect: f64) -> CameraState

camera moved back along its direction so the whole of geom fits a picture of aspect aspect (width over height) with a vertical field of view of fov_deg, around the model’s center (what the 3D view does to a view whose camera was never moved); the camera itself when there is no geometry.

cc_raytracing::environment

crates/cc_raytracing/src/environment.rs

The light around the model: a generated sky map with the ground below the horizon, a sun, and an optional ground plane that catches shadows. The sky is an equirectangular map of ENV_WIDTH × ENV_HEIGHT pixels in linear light (about 0.35° a pixel: the path tracer reads the nearest pixel, and coarser maps show the sky’s gradient as bands), made from the sun’s altitude: deep blue at the zenith, paler towards the horizon, warmer there towards a low sun, with a soft glow around the sun; once the sun is below the horizon it fades through a blue-gray dusk to night. Below the horizon the map holds the ground color lit by the sun and the sky (a matte ground’s radiance), blended into the sky over a degree or two, so the horizon past the ground plane reads right. The sky map is scaled by cc_core::RenderEnvironment::sky_strength. The sun is a distant light of SUN_IRRADIANCE at the zenith, dimmed and warmed by the air it crosses (an air mass formula and a per-channel extinction), none below the horizon, scaled by cc_core::RenderEnvironment::sun_strength. Its disk is not drawn in the sky map: rays bouncing off surfaces would find it and count the sun a second time, as bright isolated pixels; the glow around it is broad and dim enough not to. A view with no sun is lit by default_sun, a sun that follows the view: DEFAULT_SUN_ALTITUDE high, behind the viewer and to the left (where the 3D view’s own light comes from), so the faces seen are lit and the shadows fall to the right. At the default strengths, exposure 0 and the filmic curve, a white wall facing a high sun comes out bright but not clipped, the sky light blue and shaded faces mid gray.

Items: ENV_WIDTH · ENV_HEIGHT · SUN_IRRADIANCE · DEFAULT_SUN_ALTITUDE · DEFAULT_SUN_AZIMUTH · GROUND_NUDGE · MIN_GROUND_HALF_SIDE · GROUND_RADII · sun_state · default_sun · sun_irradiance · sky_radiance · sky_map · lights · ground_height

const ENV_WIDTH

pub const ENV_WIDTH: usize

Width of the sky map, pixels (longitude).

const ENV_HEIGHT

pub const ENV_HEIGHT: usize

Height of the sky map, pixels (latitude, zenith to nadir).

const SUN_IRRADIANCE

pub const SUN_IRRADIANCE: f64

Irradiance of the sun at the zenith on a surface facing it, before the air dims it (in the units of the sky map’s radiance).

const DEFAULT_SUN_ALTITUDE

pub const DEFAULT_SUN_ALTITUDE: f64

Altitude of the sun of a view with none, degrees.

const DEFAULT_SUN_AZIMUTH

pub const DEFAULT_SUN_AZIMUTH: f64

Where the sun of a view with none stands, degrees clockwise from the direction the viewer looks: behind and to the left.

const GROUND_NUDGE

pub const GROUND_NUDGE: f64

The ground plane is this far below the ground height, meters, so faces lying at that height (floor slabs) cover it.

const MIN_GROUND_HALF_SIDE

pub const MIN_GROUND_HALF_SIDE: f64

Smallest half side of the ground plane, meters.

const GROUND_RADII

pub const GROUND_RADII: f64

Half side of the ground plane in model radii (around the model’s center).

fn sun_state

pub fn sun_state(project: &Project, view: &View, camera: &CameraState) -> SunState

The sun lighting view through camera: the view’s own sun (a view sun turning with the view follows camera), else default_sun.

fn default_sun

pub fn default_sun() -> SunSettings

The sun of a view that has none: DEFAULT_SUN_ALTITUDE high, at DEFAULT_SUN_AZIMUTH from the direction the viewer looks.

fn sun_irradiance

pub fn sun_irradiance(sun: &SunState) -> DVec3

The sun’s irradiance (linear RGB) at strength 1, on a surface facing it.

fn sky_radiance

pub fn sky_radiance(d: DVec3, sun: &SunState) -> DVec3

The sky’s radiance (linear RGB) at strength 1 along unit direction d (model coordinates, at or above the horizon) under sun.

fn sky_map

pub fn sky_map(sun: &SunState, environment: &RenderEnvironment) -> EnvMap

The sky map of sun and environment (in the tracer’s frame), with the ground of environment’s color below the horizon.

fn lights

pub fn lights(sun: &SunState, environment: &RenderEnvironment) -> Vec<Light>

The lights of a render under sun: the sun (when it is above the horizon and has strength) and the sky.

fn ground_height

pub fn ground_height(project: &Project, view: &View, bottom: Option<f64>) -> f64

The height of the ground plane: the view’s sun’s ground level, else the lowest level, else the bottom of the model (bottom), else 0 (the rule the 3D view and the 2D views’ shadows share, Project::sun_ground_height).

cc_raytracing::materials

crates/cc_raytracing/src/materials.rs

The path tracer’s materials, made from the model’s. Each face is shaded by a Surface: what the 3D view’s textures style shows of its material (or of the paint on it), after the view’s graphics (a color override, halftone, transparency). Its appearance color is the base color, its Finish sets how rough and shiny it is (table in Surface::material), metals (material class Metal) are metallic, and its texture, decoded once per image (Textures), replaces the color. Glass is a material of class Glass, or one at least GLASS_TRANSPARENCY transparent: it becomes thin glass (light goes straight through, the pane reflects like a dielectric and shadow rays cross it), so the sun enters rooms through windows. Masses, which the model always draws see-through, and any other transparent material keep their transparency as partial coverage instead.

Items: GLASS_TRANSPARENCY · GLASS_TINT · MAX_TEXTURES · MAX_TEXTURE_SIDE · CLAY_COLOR · Surface · Style · Textures · srgb_to_linear · linear · SurfaceInput · texture_uv

const GLASS_TRANSPARENCY

pub const GLASS_TRANSPARENCY: f64

A material at least this transparent (0 to 1) that is not of class glass renders as glass all the same.

const GLASS_TINT

pub const GLASS_TINT: f32

How much of a glass material’s color tints the light through it: clear panes read as their color in the views, but a pane that absorbed that much would darken a room.

const MAX_TEXTURES

pub const MAX_TEXTURES: usize

The most textures a render decodes; the materials past them show their color.

const MAX_TEXTURE_SIDE

pub const MAX_TEXTURE_SIDE: u32

The longest side of a decoded texture, pixels (larger images are reduced).

const CLAY_COLOR

pub const CLAY_COLOR: [u8; 3]

The base color of clay renders (sRGB): a white matte of about 0.8 in linear light, lit by the sky and the sun like any other surface.

struct Surface

pub struct Surface

How a face is shaded: the recipe of one path tracer material.

Traits: Debug, Clone, PartialEq, Eq, Hash

Fields

Methods

struct Style

pub struct Style

The view graphics of an element’s solids, as the 3D view applies them.

Traits: Debug, Clone, Copy, Default, PartialEq

Fields

Methods

struct Textures

pub struct Textures

The decoded textures of a render, one per image.

Traits: Default

Some fields are private.

Methods

fn srgb_to_linear

pub fn srgb_to_linear(c: u8) -> f32

An sRGB channel as linear light.

fn linear

pub fn linear(c: [u8; 3]) -> Vec3

An sRGB color as linear light.

struct SurfaceInput

pub struct SurfaceInput<'a>

What a face of a material shows, as the 3D view’s textures style shows it.

Fields

fn texture_uv

pub fn texture_uv(texture: &MaterialTexture, uv: [f64; 2]) -> [f64; 2]

The texture coordinates of a point with plane coordinates uv (meters, see cc_geom::plane_axes) for texture, as the 3D view lays them: in repeats, rows running down the image so its up is the face’s up.

cc_raytracing::render

crates/cc_raytracing/src/render.rs

Rendering a RenderScene: progressively with a callback that sees each step and may stop the render (run), or to the end (render_image), and the image it gives (Image).

Items: Region · Control · Progress · Outcome · run · render_image · Image

struct Region

pub struct Region

A rectangle of the image, in pixels from its top left corner.

Traits: Debug, Clone, Copy, PartialEq, Eq

Fields

enum Control

pub enum Control

What the callback of run says after a step.

Traits: Debug, Clone, Copy, PartialEq, Eq

Variants

struct Progress

pub struct Progress<'a>

A render in progress, as the callback of run sees it after a step.

Some fields are private.

Methods

struct Outcome

pub struct Outcome

How a run ended.

Traits: Debug, Clone, PartialEq

Fields

fn run

pub fn run(scene: &RenderScene, region: Option<Region>, mut on_step: impl FnMut(&Progress<'_>) -> Control) -> Result<Outcome, RenderError>

Render scene (the region of its image only, when given: the rest is never traced and stays black), a few samples per pixel at a time, calling on_step after each step until the render is done or the callback says Control::Stop. The first steps add one sample, so the first picture comes fast; later ones grow so a step takes about a quarter of a second. Blocking: an application runs it on a thread of its own and stops it from the callback (an atomic flag the callback reads). A panic of the path tracer comes back as RenderError::Internal.

fn render_image

pub fn render_image(scene: &RenderScene) -> Result<Image, RenderError>

Render all of scene to the last sample.

struct Image

pub struct Image

An image of linear radiance (RGB), rows from the top.

Traits: Debug, Clone, PartialEq

Fields

Methods

cc_raytracing::scene

crates/cc_raytracing/src/scene.rs

The scene of a render: the triangles, materials, lights and camera of a view, owned so a worker thread can render it.

Items: MAX_TRIANGLES · RenderScene

const MAX_TRIANGLES

pub const MAX_TRIANGLES: usize

The most triangles a render takes (about a gigabyte of scene); a view showing more is refused.

struct RenderScene

pub struct RenderScene

A view ready to render: the path tracer’s scene (geometry, materials, lights), its camera and how it is sampled, plus the exposure and tone mapping its image is shown with. It owns everything (Send and Sync), so a worker thread can take it (or an Arc of it) and render it with crate::run.

Fields

Some fields are private.

Methods

cc_raytracing::space

crates/cc_raytracing/src/space.rs

The path tracer’s frame. The model is Z up, in meters, in f64; the path tracer is Y up (its sky map has its poles on Y) and works in f32. A model point p becomes p - origin turned by (x, y, z) → (x, z, -y): a rotation of -90° about X, so the handedness, triangle windings and normals are kept, model up (+Z) is the tracer’s up (+Y) and model north (+Y) is the tracer’s -Z.

Items: Space · dir · model_dir

struct Space

pub struct Space

Model coordinates to the path tracer’s, around a chosen origin.

Traits: Debug, Clone, Copy, PartialEq

Fields

Methods

fn dir

pub fn dir(d: DVec3) -> Vec3

A model direction (or any vector) in the tracer’s frame.

fn model_dir

pub fn model_dir(d: Vec3) -> DVec3

A tracer direction back in model coordinates.