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.
| 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_raytracingcrates/cc_raytracing/src/lib.rs
Re-exports
pub use render::{Control, Image, Outcome, Progress, Region, render_image, run}pub use scene::{MAX_TRIANGLES, RenderScene}Items: RenderError · guarded
RenderErrorpub enum RenderError
What went wrong building or rendering a scene, or writing its image.
Traits: Debug, Clone, PartialEq, Error
Variants
TooManyTriangles { limit: usize }
The view shows more triangles than a render takes.
InvalidCamera(String)
The camera has values that are not numbers.
InvalidImage(String)
The image or region asked for cannot be rendered or written.
UnsupportedFormat(String)
An image file of a kind that is not written.
Write(String)
Writing the image file failed.
Internal(String)
The path tracer failed (it panicked); the message says where.
guardedpub(crate) fn guarded<T>(what: &str, f: impl FnOnce() -> T) -> Result<T, RenderError>
Run f, turning a panic into RenderError::Internal.
cc_raytracing::cameracrates/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
VIEWPORT_FOV_DEGpub const VIEWPORT_FOV_DEG: f64
The field of view of the 3D viewport, degrees (vertical).
eye_and_forwardpub 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.
tracer_camerapub(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.
fitpub 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::environmentcrates/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
ENV_WIDTHpub const ENV_WIDTH: usize
Width of the sky map, pixels (longitude).
ENV_HEIGHTpub const ENV_HEIGHT: usize
Height of the sky map, pixels (latitude, zenith to nadir).
SUN_IRRADIANCEpub 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).
DEFAULT_SUN_ALTITUDEpub const DEFAULT_SUN_ALTITUDE: f64
Altitude of the sun of a view with none, degrees.
DEFAULT_SUN_AZIMUTHpub 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.
GROUND_NUDGEpub 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.
MIN_GROUND_HALF_SIDEpub const MIN_GROUND_HALF_SIDE: f64
Smallest half side of the ground plane, meters.
GROUND_RADIIpub const GROUND_RADII: f64
Half side of the ground plane in model radii (around the model’s center).
sun_statepub 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.
default_sunpub 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.
sun_irradiancepub fn sun_irradiance(sun: &SunState) -> DVec3
The sun’s irradiance (linear RGB) at strength 1, on a surface facing it.
sky_radiancepub 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.
sky_mappub 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.
lightspub 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.
ground_heightpub 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::materialscrates/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
GLASS_TRANSPARENCYpub 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.
GLASS_TINTpub 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.
MAX_TEXTURESpub const MAX_TEXTURES: usize
The most textures a render decodes; the materials past them show their color.
MAX_TEXTURE_SIDEpub const MAX_TEXTURE_SIDE: u32
The longest side of a decoded texture, pixels (larger images are reduced).
CLAY_COLORpub 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.
Surfacepub struct Surface
How a face is shaded: the recipe of one path tracer material.
Traits: Debug, Clone, PartialEq, Eq, Hash
Fields
color: [u8; 3]
Base color, sRGB.
finish: Finishmetal: boolglass: bool
Thin glass.
opacity: u16
How much of each point is there, in thousandths (1000: opaque).
texture: Option<usize>
The texture replacing the color, an index into Textures.
Methods
pub fn of(project: &cc_core::Project, input: &SurfaceInput, style: &Style, clay: bool, textures: &mut Textures) -> Self
The surface of a face with input, in an element of view graphics
style; clay makes every opaque surface CLAY_COLOR and matte,
and glass clear.
pub fn matte(color: [u8; 3]) -> Self
A matte surface of color (the ground).
pub fn material(&self, textures: &Textures) -> Material
The path tracer’s material. Finishes, as roughness / specular
(0.5 is a reflectance of 4 % head on) / clear coat:
| finish | dielectric | metal (metallic 1) |
|———-|———————|——————–|
| matte | 0.90 / 0.25 / none | roughness 0.65 |
| satin | 0.55 / 0.50 / none | roughness 0.40 |
| glossy | 0.30 / 0.50 / 0.4 | roughness 0.22 |
| polished | 0.12 / 0.50 / 1.0 | roughness 0.06 |
Glass is thin, fully transmissive, smooth, of index 1.5, tinted by
GLASS_TINT of its color. A texture multiplies a white base.
Stylepub struct Style
The view graphics of an element’s solids, as the 3D view applies them.
Traits: Debug, Clone, Copy, Default, PartialEq
Fields
color: Option<[u8; 3]>transparency: Option<f64>
0 (opaque) to 1.
halftone: bool
Faces mixed with white.
Methods
pub fn of(g: &cc_core::GraphicOverride) -> Self
How a resolved graphic override shows on surfaces (as the 3D view reads it): the surface fill’s color (white for a fill of no pattern), transparency and halftone.
Texturespub struct Textures
The decoded textures of a render, one per image.
Traits: Default
Some fields are private.
Methods
pub fn index(&mut self, texture: &MaterialTexture) -> Option<usize>
The index of texture’s image, decoded on first use; None when it
cannot be decoded or MAX_TEXTURES are taken.
pub fn get(&self, index: usize) -> Option<&Arc<Texture>>
The decoded texture index.
pub fn len(&self) -> usizepub fn is_empty(&self) -> boolsrgb_to_linearpub fn srgb_to_linear(c: u8) -> f32
An sRGB channel as linear light.
linearpub fn linear(c: [u8; 3]) -> Vec3
An sRGB color as linear light.
SurfaceInputpub struct SurfaceInput<'a>
What a face of a material shows, as the 3D view’s textures style shows it.
Fields
material: Option<&'a str>
The material’s name (the solid’s own, or the paint’s).
appearance: [u8; 3]
The appearance color (when the project has no such material).
transparency: f64
The transparency the model gives the face (0 to 1).
mass: bool
A mass: kept see-through, never glass.
texture_uvpub 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::rendercrates/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
Regionpub struct Region
A rectangle of the image, in pixels from its top left corner.
Traits: Debug, Clone, Copy, PartialEq, Eq
Fields
x: u32y: u32width: u32height: u32Controlpub enum Control
What the callback of run says after a step.
Traits: Debug, Clone, Copy, PartialEq, Eq
Variants
Continue
Render more samples.
Stop
Stop: run returns the image so far.
Progresspub struct Progress<'a>
A render in progress, as the callback of run sees it after a step.
Some fields are private.
Methods
pub fn samples(&self) -> u32
Samples per pixel rendered so far.
pub fn total_samples(&self) -> u32
Samples per pixel of the finished render.
pub fn is_done(&self) -> boolpub fn elapsed(&self) -> Duration
Time spent rendering so far.
pub fn region(&self) -> Region
The part of the image being rendered (all of it unless a region was given).
pub fn image(&self) -> Image
The whole image so far, black outside the region.
pub fn region_image(&self) -> Image
The region alone so far, as an image of its size.
Outcomepub struct Outcome
How a run ended.
Traits: Debug, Clone, PartialEq
Fields
image: Image
The whole image (black outside the region, if one was given).
samples: u32
Samples per pixel rendered.
stopped: bool
The callback stopped the render before the last sample.
runpub 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.
render_imagepub fn render_image(scene: &RenderScene) -> Result<Image, RenderError>
Render all of scene to the last sample.
Imagepub struct Image
An image of linear radiance (RGB), rows from the top.
Traits: Debug, Clone, PartialEq
Fields
width: u32height: u32pixels: Vec<[f32; 3]>Methods
pub fn is_valid(&self) -> bool
Whether the pixels are as many as the size says (and there are some).
pub fn to_rgba8(&self, exposure_stops: f64, tone_map: ToneMap) -> Vec<u8>
The pixels multiplied by 2^exposure_stops, tone mapped and sRGB
encoded, as RGBA bytes (alpha 255), 4 per pixel. Values that are not
numbers come out black.
pub fn save(&self, path: &Path, exposure_stops: f64, tone_map: ToneMap) -> Result<(), RenderError>
Write the image to path: .png, .jpg and .jpeg exposed, tone
mapped and sRGB encoded (as Image::to_rgba8); .exr and .hdr
in linear light, exposed but not tone mapped.
cc_raytracing::scenecrates/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
MAX_TRIANGLESpub const MAX_TRIANGLES: usize
The most triangles a render takes (about a gigabyte of scene); a view showing more is refused.
RenderScenepub 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
scene: Scenecamera: Cameratracer: TracerSettingsSome fields are private.
Methods
pub fn build(project: &Project, geom: &ModelGeometry, view: &View, camera: &CameraState, settings: &RenderSettings, temporary: Option<&TemporaryVisibility>) -> Result<Self, RenderError>
The scene of view seen through camera (the 3D view’s camera: the
one in the view, or the viewport’s live one) with settings (brought
into range first). geom is the geometry the view shows (its phase
and design options, Session::view_geometry), and temporary what is
temporarily hidden or isolated in it: the elements the view’s graphics
hide are left out, its overrides of color, transparency and halftone
shown as in its textures style. Errors for a camera that is not a
number and a scene of more than MAX_TRIANGLES; an empty view
gives the sky and the ground.
pub fn width(&self) -> u32
Width of the image, pixels.
pub fn height(&self) -> u32
Height of the image, pixels.
pub fn samples(&self) -> u32
Samples per pixel of the finished render.
pub fn exposure(&self) -> f64
The exposure the image is shown with, stops.
pub fn tone_map(&self) -> ToneMap
The tone mapping the image is shown with.
pub fn triangles(&self) -> usize
Triangles of the model in the scene (the ground plane not counted).
pub fn textures(&self) -> usize
Material textures decoded for the scene.
cc_raytracing::spacecrates/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
Spacepub struct Space
Model coordinates to the path tracer’s, around a chosen origin.
Traits: Debug, Clone, Copy, PartialEq
Fields
origin: DVec3
The model point that is the tracer’s origin.
Methods
pub fn new(origin: DVec3) -> Selfpub fn point(&self, p: DVec3) -> Vec3
A model point in the tracer’s frame.
pub fn model_point(&self, p: Vec3) -> DVec3
A tracer point back in model coordinates.
dirpub fn dir(d: DVec3) -> Vec3
A model direction (or any vector) in the tracer’s frame.
model_dirpub fn model_dir(d: Vec3) -> DVec3
A tracer direction back in model coordinates.