library: core: document color module

This commit is contained in:
Antoine Martin 2020-03-20 18:41:20 +01:00
parent db84708392
commit 07dbad95b5

View file

@ -1,3 +1,5 @@
//! Color definition and operations
use derive_more::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Sub, SubAssign, Sum}; use derive_more::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Sub, SubAssign, Sum};
use serde::Deserialize; use serde::Deserialize;
use std::ops::{Div, DivAssign, Mul, MulAssign}; use std::ops::{Div, DivAssign, Mul, MulAssign};
@ -19,12 +21,34 @@ use std::ops::{Div, DivAssign, Mul, MulAssign};
)] )]
/// A structure to represent operations in the linear RGB colorspace. /// A structure to represent operations in the linear RGB colorspace.
pub struct LinearColor { pub struct LinearColor {
/// The color's red component
pub r: f32, pub r: f32,
/// The color's green component
pub g: f32, pub g: f32,
/// The color's blue component
pub b: f32, pub b: f32,
} }
impl LinearColor { impl LinearColor {
/// Creates the color black.
///
/// All 3 components are set to 0.
///
/// # Examples
///
/// ```
/// # use pathtracer::core::LinearColor;
/// #
/// let black = LinearColor::black();
/// assert_eq!(
/// black,
/// LinearColor {
/// r: 0.,
/// g: 0.,
/// b: 0.
/// }
/// );
/// ```
pub fn black() -> Self { pub fn black() -> Self {
LinearColor { LinearColor {
r: 0., r: 0.,
@ -33,11 +57,30 @@ impl LinearColor {
} }
} }
/// Creates a new `Color`.
///
/// # Examples
///
/// ```
/// # use pathtracer::core::LinearColor;
/// #
/// let color = LinearColor::new(1.0, 0.0, 0.0); // bright red!
/// ```
pub fn new(r: f32, g: f32, b: f32) -> Self { pub fn new(r: f32, g: f32, b: f32) -> Self {
LinearColor { r, g, b } LinearColor { r, g, b }
} }
#[must_use] #[must_use]
/// Clamps the color's RGB components between 0.0 and 1.0.
///
/// # Examples
///
/// ```
/// # use pathtracer::core::LinearColor;
/// #
/// let color = LinearColor::new(1.5, -1.0, 0.5);
/// assert_eq!(color.clamp(), LinearColor::new(1.0, 0.0, 0.5))
/// ```
pub fn clamp(self) -> Self { pub fn clamp(self) -> Self {
fn clamp(v: f32) -> f32 { fn clamp(v: f32) -> f32 {
if v > 1. { if v > 1. {
@ -109,19 +152,6 @@ impl From<LinearColor> for image::Rgb<u8> {
mod test { mod test {
use super::*; use super::*;
#[test]
fn black_is_black() {
let black = LinearColor::black();
assert_eq!(
black,
LinearColor {
r: 0.,
g: 0.,
b: 0.
}
)
}
#[test] #[test]
fn default_is_black() { fn default_is_black() {
assert_eq!(<LinearColor as Default>::default(), LinearColor::black()) assert_eq!(<LinearColor as Default>::default(), LinearColor::black())
@ -304,12 +334,6 @@ mod test {
); );
} }
#[test]
fn clamp_works() {
let color = LinearColor::new(1.5, -1., 0.5);
assert_eq!(color.clamp(), LinearColor::new(1., 0., 0.5))
}
#[test] #[test]
fn deserialization_works() { fn deserialization_works() {
let yaml = "{r: 1.0, g: 0.5, b: 0.2}"; let yaml = "{r: 1.0, g: 0.5, b: 0.2}";