diff --git a/crates/bevy_color/docs/conversion.md b/crates/bevy_color/docs/conversion.md new file mode 100644 index 0000000000..096044e52f --- /dev/null +++ b/crates/bevy_color/docs/conversion.md @@ -0,0 +1,16 @@ +# Conversion + +Conversion between the various color spaces is achieved using Rust's native [From] trait. Because certain color spaces are defined by their transformation to and from another space, these [From] implementations reflect that set of definitions. + +```rust +# use bevy_color::{Srgba, LinearRgba}; +let color = Srgba::rgb(0.5, 0.5, 0.5); + +// Using From explicitly +let linear_color = LinearRgba::from(color); + +// Using Into +let linear_color: LinearRgba = color.into(); +``` + +For example, the [sRGB](crate::Srgba) space is defined by its relationship with [Linear RGB](crate::LinearRgba), and [HWB](crate::Hwba) by its with [sRGB](crate::Srgba). As such, it is the responsibility of [sRGB](crate::Srgba) to provide [From] implementations for [Linear RGB](crate::LinearRgba), and [HWB](crate::Hwba) for [sRGB](crate::Srgba). To then provide conversion between [Linear RGB](crate::LinearRgba) and [HWB](crate::Hwba) directly, [HWB](crate::Hwba) is responsible for implementing these conversions, delegating to [sRGB](crate::Srgba) as an intermediatory. This ensures that all conversions take the shortest path between any two spaces, and limit the proliferation of domain specific knowledge for each color space to their respective definitions. diff --git a/crates/bevy_color/docs/diagrams/README.md b/crates/bevy_color/docs/diagrams/README.md new file mode 100644 index 0000000000..fc6bb9f9dd --- /dev/null +++ b/crates/bevy_color/docs/diagrams/README.md @@ -0,0 +1,3 @@ +# Creating Mermaid Diagrams + +Mermaid diagrams (`.mmd` files) can be converted to SVG using various tools. The simplest to work with is [mermaid.live](https://mermaid.live/), which is a HTML web app. When editing `.mmd` files, make sure to regenerate the associated SVGs. diff --git a/crates/bevy_color/docs/diagrams/model_graph.mmd b/crates/bevy_color/docs/diagrams/model_graph.mmd new file mode 100644 index 0000000000..d7fc5e1b24 --- /dev/null +++ b/crates/bevy_color/docs/diagrams/model_graph.mmd @@ -0,0 +1,22 @@ +%%{ init: { 'theme': 'dark', 'flowchart': { 'curve': 'stepAfter', 'padding': 30 }, 'themeCSS': '.label foreignObject { overflow: visible; }' } }%% +flowchart LR + lRGB(Linear
sRGB
) + Oklab(Oklab) + Oklch(Oklch) + XYZ(XYZ) + Lab(Lab) + Lch(Lch) + sRGB(sRGB) + HWB(HWB) + HSV(HSV) + HSL(HSL) + GPU <--> lRGB + lRGB <--Conversion--> Oklab + Oklab <--Conversion--> Oklch + lRGB <--Conversion--> XYZ + XYZ <--Conversion--> Lab + Lab <--Conversion--> Lch + lRGB <--Conversion--> sRGB + sRGB <--Conversion--> HWB + HWB <--Conversion--> HSV + HSV <--Conversion--> HSL \ No newline at end of file diff --git a/crates/bevy_color/docs/diagrams/model_graph.svg b/crates/bevy_color/docs/diagrams/model_graph.svg new file mode 100644 index 0000000000..5c1d3dceb7 --- /dev/null +++ b/crates/bevy_color/docs/diagrams/model_graph.svg @@ -0,0 +1 @@ +
GPU
\ No newline at end of file diff --git a/crates/bevy_color/src/color.rs b/crates/bevy_color/src/color.rs index d1d24e2833..665a2ee720 100644 --- a/crates/bevy_color/src/color.rs +++ b/crates/bevy_color/src/color.rs @@ -6,6 +6,10 @@ use serde::{Deserialize, Serialize}; /// /// This is useful when you need to store a color in a data structure that can't be generic over /// the color type. +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum Color { diff --git a/crates/bevy_color/src/hsla.rs b/crates/bevy_color/src/hsla.rs index 3739c4b144..b0774b1322 100644 --- a/crates/bevy_color/src/hsla.rs +++ b/crates/bevy_color/src/hsla.rs @@ -4,6 +4,10 @@ use serde::{Deserialize, Serialize}; /// Color in Hue-Saturation-Lightness (HSL) color space with alpha. /// Further information on this color model can be found on [Wikipedia](https://en.wikipedia.org/wiki/HSL_and_HSV). +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub struct Hsla { diff --git a/crates/bevy_color/src/hsva.rs b/crates/bevy_color/src/hsva.rs index 0583491e68..f671981ddc 100644 --- a/crates/bevy_color/src/hsva.rs +++ b/crates/bevy_color/src/hsva.rs @@ -4,6 +4,10 @@ use serde::{Deserialize, Serialize}; /// Color in Hue-Saturation-Value (HSV) color space with alpha. /// Further information on this color model can be found on [Wikipedia](https://en.wikipedia.org/wiki/HSL_and_HSV). +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub struct Hsva { diff --git a/crates/bevy_color/src/hwba.rs b/crates/bevy_color/src/hwba.rs index 5105e59d6a..744acd865b 100644 --- a/crates/bevy_color/src/hwba.rs +++ b/crates/bevy_color/src/hwba.rs @@ -8,6 +8,10 @@ use serde::{Deserialize, Serialize}; /// Color in Hue-Whiteness-Blackness (HWB) color space with alpha. /// Further information on this color model can be found on [Wikipedia](https://en.wikipedia.org/wiki/HWB_color_model). +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub struct Hwba { diff --git a/crates/bevy_color/src/laba.rs b/crates/bevy_color/src/laba.rs index 4b4714a3a8..43b4556359 100644 --- a/crates/bevy_color/src/laba.rs +++ b/crates/bevy_color/src/laba.rs @@ -5,6 +5,10 @@ use bevy_reflect::{Reflect, ReflectDeserialize, ReflectSerialize}; use serde::{Deserialize, Serialize}; /// Color in LAB color space, with alpha +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub struct Laba { diff --git a/crates/bevy_color/src/lcha.rs b/crates/bevy_color/src/lcha.rs index 2a01147a68..4e9192146b 100644 --- a/crates/bevy_color/src/lcha.rs +++ b/crates/bevy_color/src/lcha.rs @@ -3,6 +3,10 @@ use bevy_reflect::{Reflect, ReflectDeserialize, ReflectSerialize}; use serde::{Deserialize, Serialize}; /// Color in LCH color space, with alpha +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub struct Lcha { diff --git a/crates/bevy_color/src/lib.rs b/crates/bevy_color/src/lib.rs index a90c2fd627..0c1dca63d1 100644 --- a/crates/bevy_color/src/lib.rs +++ b/crates/bevy_color/src/lib.rs @@ -50,11 +50,10 @@ //! //! See also the [Wikipedia article on color spaces](https://en.wikipedia.org/wiki/Color_space). //! -//! # Conversions -//! -//! Each color space can be converted to and from the others using the [`From`] trait. Not all -//! possible combinations of conversions are provided, but every color space has a conversion to -//! and from [`Srgba`] and [`LinearRgba`]. +#![doc = include_str!("../docs/conversion.md")] +//!
+#![doc = include_str!("../docs/diagrams/model_graph.svg")] +//!
//! //! # Other Utilities //! diff --git a/crates/bevy_color/src/linear_rgba.rs b/crates/bevy_color/src/linear_rgba.rs index 462c7033e6..c0aeb88dfc 100644 --- a/crates/bevy_color/src/linear_rgba.rs +++ b/crates/bevy_color/src/linear_rgba.rs @@ -5,6 +5,10 @@ use bytemuck::{Pod, Zeroable}; use serde::{Deserialize, Serialize}; /// Linear RGB color with alpha. +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] #[repr(C)] diff --git a/crates/bevy_color/src/oklaba.rs b/crates/bevy_color/src/oklaba.rs index 5913dcbfa5..d98d6ef8ba 100644 --- a/crates/bevy_color/src/oklaba.rs +++ b/crates/bevy_color/src/oklaba.rs @@ -6,6 +6,10 @@ use bevy_reflect::{Reflect, ReflectDeserialize, ReflectSerialize}; use serde::{Deserialize, Serialize}; /// Color in Oklaba color space, with alpha +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub struct Oklaba { diff --git a/crates/bevy_color/src/srgba.rs b/crates/bevy_color/src/srgba.rs index 696484e7ce..b2425bb36c 100644 --- a/crates/bevy_color/src/srgba.rs +++ b/crates/bevy_color/src/srgba.rs @@ -6,6 +6,10 @@ use serde::{Deserialize, Serialize}; use thiserror::Error; /// Non-linear standard RGB with alpha. +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub struct Srgba { diff --git a/crates/bevy_color/src/xyza.rs b/crates/bevy_color/src/xyza.rs index 6694ee38e0..0aa8a0f5a9 100644 --- a/crates/bevy_color/src/xyza.rs +++ b/crates/bevy_color/src/xyza.rs @@ -3,6 +3,10 @@ use bevy_reflect::{Reflect, ReflectDeserialize, ReflectSerialize}; use serde::{Deserialize, Serialize}; /// [CIE 1931](https://en.wikipedia.org/wiki/CIE_1931_color_space) color space, also known as XYZ, with an alpha channel. +#[doc = include_str!("../docs/conversion.md")] +///
+#[doc = include_str!("../docs/diagrams/model_graph.svg")] +///
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub struct Xyza {