From 2b4adacea3c76b8b33dc5f50d296dd4a61107c16 Mon Sep 17 00:00:00 2001 From: Julian T Date: Tue, 2 Feb 2021 20:39:32 +0100 Subject: Added documentation for many of the modules --- src/camera/film.rs | 20 ++++++++++++++++++-- src/camera/mod.rs | 8 ++++++++ src/core/bound.rs | 33 +++++++++++++++++++++++++++++---- src/core/mod.rs | 5 +++++ src/core/ray.rs | 1 + src/core/spectrum.rs | 3 +++ src/core/transform.rs | 30 ++++++++++++++++++++++++------ src/core/vector2.rs | 3 +++ src/core/vector3.rs | 16 ++++++++++++++++ src/lib.rs | 10 +++++++--- src/scene/mod.rs | 3 +++ src/scene/shapes/sphere.rs | 3 +++ 12 files changed, 120 insertions(+), 15 deletions(-) diff --git a/src/camera/film.rs b/src/camera/film.rs index 1d87399..30fd2fe 100644 --- a/src/camera/film.rs +++ b/src/camera/film.rs @@ -1,19 +1,28 @@ use crate::core::*; use crate::Float; +/// Contains the necesary values when doing calculations +/// +/// This is not the final RGB value #[derive(Clone)] pub struct Pixel { + /// The sum of the collected samples rgb: Spectrum, + /// The amount of samples collected samples: u32, } pub struct Film { size: Vector2i, - drawingBound: Bound2i, + drawing_bound: Bound2i, pixels: Vec, } +/// FilmTile is a small version of the Film used when rendering +/// +/// This means that multiple threads can work on the same area and commit their changed when they +/// are done. pub struct FilmTile { bounds: Bound2i, size: Vector2i, @@ -49,11 +58,14 @@ impl Film { let area = size.x * size.y; Film { size, - drawingBound: Bound2i::new(&Vector2i::new(0), &size), + drawing_bound: Bound2i::new(&Vector2i::new(0), &size), pixels: vec![Pixel::new(); area as usize], } } + /// Creates a new FilmTile from the specified bounds + /// + /// This tile can later be commited with the commit_tile function pub fn get_tile(&self, bound: &Bound2i) -> FilmTile { FilmTile::new( bound, @@ -61,6 +73,9 @@ impl Film { } + /// Commit a tile back on the film + /// + /// This will lock the Film while the changes from the Tile is written pub fn commit_tile(&mut self, tile: &FilmTile) { let offset = tile.bounds.min; @@ -88,6 +103,7 @@ impl FilmTile { } } + /// Add a single sample sampled from the scene pub fn add_sample(&mut self, point: &Vector2f, c: Spectrum) { let point = Vector2i::from(point.floor()); // Subtract the offset diff --git a/src/camera/mod.rs b/src/camera/mod.rs index 42de3b3..4865a36 100644 --- a/src/camera/mod.rs +++ b/src/camera/mod.rs @@ -1,2 +1,10 @@ +//! Implements how light is captured on film and how rays are generated +//! +//! The Film module specifies how calculated spectrum values contribute to the final image. +//! +//! The Camera class generated rays that can be cast into the scene. +//! This requires converting the film coordinates into real coordinates + pub mod film; //pub mod filter; +//pub mod camera; diff --git a/src/core/bound.rs b/src/core/bound.rs index ea9d990..635218a 100644 --- a/src/core/bound.rs +++ b/src/core/bound.rs @@ -1,7 +1,9 @@ +//! Implements a 2d region use crate::{Number, Float}; use super::vector2::Vector2; use crate::core; +/// Implements a region between min and max #[derive(Clone)] pub struct Bound2 { pub min: Vector2, @@ -26,6 +28,9 @@ fn max (a: T, b: T) -> T { } impl Bound2 { + /// Creates a new bound from two points + /// + /// p0 does not have to be smaller than p1 pub fn new(p0: &Vector2, p1: &Vector2) -> Self { let min = Vector2::new_xy(min(p0.x, p1.x), min(p0.y, p1.y)); let max = Vector2::new_xy(max(p0.x, p1.x), max(p0.y, p1.y)); @@ -40,18 +45,37 @@ impl Bound2 { ) } + /// Calculates the diagonal vector + /// + /// Can be used to calculate the size of the bound + /// + /// # Examples + /// + /// ``` + /// use pathtrace::core::Bound2i; + /// let b = Bound2i::new_xyxy(2, 2, 6, 7); + /// let diag = b.diagonal(); + /// + /// assert!(diag.x == 4 && diag.y == 5); + /// ``` pub fn diagonal(&self) -> Vector2 { self.max - self.min } + /// Calculates the area of of the bounded region + /// + /// # Examples + /// + /// ``` + /// use pathtrace::core::Bound2i; + /// let b = Bound2i::new_xyxy(10, 10, 20, 20); + /// + /// assert!(b.area() == 100); + /// ``` pub fn area(&self) -> T { let diag = self.diagonal(); return diag.x * diag.y; } - - pub fn width(&self) -> T { - self.diagonal().x - } } impl From<&Bound2i> for Bound2f { @@ -72,6 +96,7 @@ impl From<&Bound2f> for Bound2i { } } +/// Finds the intersected area between two bounds pub fn intersect(a: &Bound2, b: &Bound2) -> Bound2 { Bound2::new( &Vector2::new_xy(max(a.min.x, b.min.x), max(a.min.y, b.min.y)), diff --git a/src/core/mod.rs b/src/core/mod.rs index 7885b9e..aed10d5 100644 --- a/src/core/mod.rs +++ b/src/core/mod.rs @@ -1,3 +1,7 @@ +//! Contains a collection of core modules used by other modules +//! +//! Also creates a shortcut for some common types + pub mod vector2; pub mod vector3; pub mod bound; @@ -11,3 +15,4 @@ pub use vector3::Vector3f; pub use bound::{Bound2i, Bound2f}; pub use spectrum::Spectrum; pub use ray::Ray; +pub use transform::Transform; diff --git a/src/core/ray.rs b/src/core/ray.rs index 54af639..2368315 100644 --- a/src/core/ray.rs +++ b/src/core/ray.rs @@ -1,3 +1,4 @@ +//! The ray class used when probing the 3d scene use crate::core::Vector3f; pub struct Ray { diff --git a/src/core/spectrum.rs b/src/core/spectrum.rs index 604c8c0..c72a251 100644 --- a/src/core/spectrum.rs +++ b/src/core/spectrum.rs @@ -1,3 +1,6 @@ +//! Used to represent color +//! +//! Currently only implements RGB colors use crate::Float; use std::ops; diff --git a/src/core/transform.rs b/src/core/transform.rs index 2c2c123..f64710c 100644 --- a/src/core/transform.rs +++ b/src/core/transform.rs @@ -1,7 +1,22 @@ +//! Implements matrix tranformations +//! +//! Used for placing shapes and camera into the scene. +//! Provides some common initializations methods for transforms like rotation, translate and camera +//! placement. +//! +//! # Examples +//! +//! ``` +//! use pathtrace::core::{Vector3f, Transform}; +//! +//! let t = Transform::new_translate(3.0, 5.0, 6.0); +//! let v = t.eval_point(&Vector3f::new_xyz(1.0, 1.0, 1.0)); +//! +//! assert!(v.x == 4.0 && v.y == 6.0 && v.z == 7.0); +//! ``` use super::matrix4x4::Matrix4x4f; use crate::Float; use crate::core::Vector3f; -use std::ops; pub struct Transform { m: Matrix4x4f, @@ -14,6 +29,7 @@ impl Transform { } } + /// Evaluation a point through the matrix pub fn eval_point(&self, p: &Vector3f) -> Vector3f { let m = &self.m.m; let x = m[0][0]*p.x + m[0][1]*p.y + m[0][2]*p.z + m[0][3]; @@ -29,7 +45,9 @@ impl Transform { out } - // Take care when transforming surface normal vector, TODO implement method for this + /// Evaluation of a vector + /// + /// This will not work for normal vectors as they become distorted pub fn eval_vector(&self, v: &Vector3f) -> Vector3f { let m = &self.m.m; let x = m[0][0]*v.x + m[0][1]*v.y + m[0][2]*v.z; @@ -42,11 +60,11 @@ impl Transform { // Creation of different transformations impl Transform { - pub fn new_translate(delta: &Vector3f) -> Self { + pub fn new_translate(x: Float, y: Float, z: Float) -> Self { Transform { m: Matrix4x4f::new( - 1.0, 0.0, 0.0, delta.x, - 0.0, 1.0, 0.0, delta.y, - 0.0, 0.0, 1.0, delta.z, + 1.0, 0.0, 0.0, x, + 0.0, 1.0, 0.0, y, + 0.0, 0.0, 1.0, z, 0.0, 0.0, 0.0, 1.0) } } diff --git a/src/core/vector2.rs b/src/core/vector2.rs index ac70947..5afa0f2 100644 --- a/src/core/vector2.rs +++ b/src/core/vector2.rs @@ -1,3 +1,6 @@ +//! Implements 2d vectors +//! +//! This is implemented generictly with types that fit in the Number trait use crate::{Float, Number}; use std::ops::{Sub, Add}; diff --git a/src/core/vector3.rs b/src/core/vector3.rs index 05bd977..48025ed 100644 --- a/src/core/vector3.rs +++ b/src/core/vector3.rs @@ -1,3 +1,6 @@ +//! Implements 3d vectors +//! +//! Also add more 3d math things needed for shading and 3d calculations. use crate::{Float, Number}; use std::ops::{Sub, Add, DivAssign}; @@ -55,6 +58,9 @@ impl DivAssign for Vector3 { } impl Vector3f { + /// Calculates the length times itself + /// + /// This is faster than using len * len as the square is ommited pub fn len_squared(&self) -> Float { self.x * self.x + self.y * self.y + self.z * self.z } @@ -67,6 +73,16 @@ impl Vector3f { self.x * op.x + self.y * op.y + self.z * op.z } + /// Inplace normal instead of creating a new vector + /// + /// # Example + /// + /// ``` + /// use pathtrace::core::Vector3f; + /// let mut v = Vector3f::new_xyz(10.0, 0.0, 0.0); + /// v.norm_in(); + /// assert!(v.x == 1.0); + /// ``` pub fn norm_in(&mut self) { let len = self.len(); if len == 0.0 { diff --git a/src/lib.rs b/src/lib.rs index 05fbff3..df9bc1d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,6 +5,9 @@ mod scene; use std::ops::{Add, Sub, Mul, DivAssign}; use std::cmp; +/// Trait used to implement generics +/// +/// This is used in Bound and Vectors pub trait Number: Copy + cmp::PartialOrd + @@ -14,9 +17,10 @@ pub trait Number: DivAssign {} -impl Number for usize {} impl Number for i32 {} impl Number for f32 {} -// Used throughout the program -type Float = f32; +/// Used for representing floating point values throughout the program +/// +/// A higher precision type will require more ram +pub type Float = f32; diff --git a/src/scene/mod.rs b/src/scene/mod.rs index 13c5e23..7c77412 100644 --- a/src/scene/mod.rs +++ b/src/scene/mod.rs @@ -1,3 +1,6 @@ +//! Defines the scene type which contains all the objects in the scene. +//! +//! Also handles finding intersections between rays and shapes pub mod shapes; mod scene; diff --git a/src/scene/shapes/sphere.rs b/src/scene/shapes/sphere.rs index f8ae11e..e30c1ec 100644 --- a/src/scene/shapes/sphere.rs +++ b/src/scene/shapes/sphere.rs @@ -1,3 +1,6 @@ +//! Implements sphere +//! +//! Spheres are relatively easy to calculate intersections between use crate::Float; use crate::core::{Ray, Vector3f}; use super::Shape; -- cgit v1.2.3