aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJulian T <julian@jtle.dk>2021-02-02 20:39:32 +0100
committerJulian T <julian@jtle.dk>2021-02-02 20:39:32 +0100
commit2b4adacea3c76b8b33dc5f50d296dd4a61107c16 (patch)
tree905b672e4005b29dad5807060ae3a966d4a3d264
parentd79d5d18c8281cce1e782892e5f85680906481dd (diff)
Added documentation for many of the modules
-rw-r--r--src/camera/film.rs20
-rw-r--r--src/camera/mod.rs8
-rw-r--r--src/core/bound.rs33
-rw-r--r--src/core/mod.rs5
-rw-r--r--src/core/ray.rs1
-rw-r--r--src/core/spectrum.rs3
-rw-r--r--src/core/transform.rs30
-rw-r--r--src/core/vector2.rs3
-rw-r--r--src/core/vector3.rs16
-rw-r--r--src/lib.rs10
-rw-r--r--src/scene/mod.rs3
-rw-r--r--src/scene/shapes/sphere.rs3
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<Pixel>,
}
+/// 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<T: Number> {
pub min: Vector2<T>,
@@ -26,6 +28,9 @@ fn max<T: Number> (a: T, b: T) -> T {
}
impl<T: Number> Bound2<T> {
+ /// Creates a new bound from two points
+ ///
+ /// p0 does not have to be smaller than p1
pub fn new(p0: &Vector2<T>, p1: &Vector2<T>) -> 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<T: Number> Bound2<T> {
)
}
+ /// 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<T> {
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<T: Number>(a: &Bound2<T>, b: &Bound2<T>) -> Bound2<T> {
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<T: Number> DivAssign<T> for Vector3<T> {
}
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;