Add impl ColorSpace example (#130)

Closes #47.

Author: tomcur

CHANGELOG.md

@@ -18,6 +18,7 @@ This release has an [MSRV][] of 1.82.
 ### Added
 
 * Support for the ACES2065-1 color space. ([#124][] by [@tomcur][])
+* A documentation example implementing `ColorSpace`. ([#130][] by [@tomcur][])
 
 ### Fixed
 
@@ -117,6 +118,7 @@ This is the initial release.
 [#124]: https://github.com/linebender/color/pull/124
 [#128]: https://github.com/linebender/color/pull/128
 [#129]: https://github.com/linebender/color/pull/129
+[#130]: https://github.com/linebender/color/pull/130
 
 [Unreleased]: https://github.com/linebender/color/compare/v0.2.2...HEAD
 [0.2.2]: https://github.com/linebender/color/releases/tag/v0.2.2

color/src/colorspace.rs

@@ -24,6 +24,51 @@ use crate::floatfuncs::FloatFuncs;
 ///
 /// See the [XYZ-D65 color space](`XyzD65`) documentation for some
 /// background information on color spaces.
+///
+/// # Implementing `ColorSpace`
+///
+/// When implementing a custom color space, take care to set the associated constants correctly.
+/// The following is an example implementation of the
+/// [Rec. 709](https://www.color.org/chardata/rgb/BT2020.xalter) color space.
+///
+/// **Note:**
+/// - [`ColorSpace::convert`] can be implemented to specialize specific conversions;
+/// - implement [`ColorSpace::scale_chroma`] if your color space has a natural representation of
+///   chroma.
+///
+/// ```rust
+/// use color::{ColorSpace, ColorSpaceLayout};
+///
+/// /// The Rec. 709 color space, using the electro-optical transfer function
+/// /// defined in ITU-R BT.1886.
+/// ///
+/// /// Rec. 709 is very similar to sRGB, having the same natural gamut, but
+/// /// does have a different transfer function.
+/// ///
+/// /// See https://www.color.org/chardata/rgb/BT709.xalter.
+/// #[derive(Clone, Copy, Debug)]
+/// pub struct Rec709;
+///
+/// impl ColorSpace for Rec709 {
+///     const IS_LINEAR: bool = false;
+///
+///     const LAYOUT: ColorSpaceLayout = ColorSpaceLayout::Rectangular;
+///
+///     const WHITE_COMPONENTS: [f32; 3] = [1., 1., 1.];
+///
+///     fn to_linear_srgb(src: [f32; 3]) -> [f32; 3] {
+///         src.map(|x| x.powf(2.4))
+///     }
+///
+///     fn from_linear_srgb(src: [f32; 3]) -> [f32; 3] {
+///         src.map(|x| x.powf(1. / 2.4))
+///     }
+///
+///     fn clip([r, g, b]: [f32; 3]) -> [f32; 3] {
+///         [r.clamp(0., 1.), g.clamp(0., 1.), b.clamp(0., 1.)]
+///     }
+/// }
+/// ```
 pub trait ColorSpace: Clone + Copy + 'static {
     /// Whether the color space is linear.
     ///