Merge #254

254: Replace the `Pixel` trait with `ArrayCast` and cast functions and increase the MSRV to 1.51.0 r=Ogeon a=Ogeon

This replaces the `Pixel` trait with a new system for casting that is based on fixed size arrays as a primitive representation. The initial implementation covers most of the use cases for `Pixel` and some additional features (casting `Box<[T]>` and `Vec<T>` for example). The missing feature is the implicit truncation `Pixel` did. The new system leaves it to the user to truncate collections where necessary.

I couldn't come up with a good trait system that would be universal enough, so I decided to start with this setup with free functions. It will at least give us the base to build something more convenient on.

See https://github.com/Ogeon/palette/discussions/227 for some background and an earlier solution idea.

## Breaking Change

This removes the `Pixel` and `RawPixel` traits and replaces it with a system that is based on the `ArrayCast` marker trait and a number of primitive cast functions.

 * Single color casting is available through `From`, `Into`, `AsRef`, `AsMut`, `TryFrom` and `TryInto`.
 * Slices and `Vec` can currently only be cast via the functions in the `cast` module. Something more ergonomic may come in a later change.

The MSRV is bumped to 1.51.0 to get access to const generics.

Co-authored-by: Erik Hedvall <erikwhedvall@gmail.com>

Author: bors[bot]

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        toolchain: [1.48.0, stable, beta, nightly]
+        toolchain: [1.51.0, stable, beta, nightly]
     runs-on: ${{ matrix.os }}
     env:
       RUSTFLAGS: -D warnings

README.md

@@ -15,7 +15,7 @@ A color management and conversion library that focuses on maintaining correctnes
 
 ## Minimum Supported Rust Version (MSRV)
 
-This version of Palette has been automatically tested with Rust version `1.48.0` and the `stable`, `beta`, and `nightly` channels. Future versions of the library may advance the minimum supported version to make use of new language features, but this will be considered a breaking change.
+This version of Palette has been automatically tested with Rust version `1.51.0` and the `stable`, `beta`, and `nightly` channels. Future versions of the library may advance the minimum supported version to make use of new language features, but this will be considered a breaking change.
 
 ## Contributing
 

palette/README.md

@@ -16,7 +16,7 @@ A color management and conversion library that focuses on maintaining correctnes
 
 ## Minimum Supported Rust Version (MSRV)
 
-This version of Palette has been automatically tested with Rust version `1.48.0` and the `stable`, `beta`, and `nightly` channels. Future versions of the library may advance the minimum supported version to make use of new language features, but this will be considered a breaking change.
+This version of Palette has been automatically tested with Rust version `1.51.0` and the `stable`, `beta`, and `nightly` channels. Future versions of the library may advance the minimum supported version to make use of new language features, but this will be considered a breaking change.
 
 ## Getting Started
 
@@ -93,16 +93,16 @@ A longer and more advanced example that shows how to implement the conversion tr
 
 ### Pixels And Buffers
 
-When working with image or pixel buffers, or any color type that can be converted to a slice of components (ex. `&[u8]`), the `Pixel` trait provides methods for turning them into slices of Palette colors without cloning the whole buffer:
+When working with image or pixel buffers, or any color type that can be converted to a slice of components (ex. `&[u8]`), the `cast` module provides functions for turning them into slices of Palette colors without cloning the whole buffer:
 
 ```rust
-use palette::{Srgb, Pixel};
+use palette::{cast, Srgb};
 
 // The input to this function could be data from an image file or
 // maybe a texture in a game.
 fn swap_red_and_blue(my_rgb_image: &mut [u8]) {
     // Convert `my_rgb_image` into `&mut [Srgb<u8>]` without copying.
-    let my_rgb_image = Srgb::from_raw_slice_mut(my_rgb_image);
+    let my_rgb_image: &mut [Srgb<u8>] = cast::from_component_slice_mut(my_rgb_image);
 
     for color in my_rgb_image {
         std::mem::swap(&mut color.red, &mut color.blue);
@@ -117,10 +117,10 @@ fn swap_red_and_blue(my_rgb_image: &mut [u8]) {
 It's also possible to create a single color from a slice or array. Let's say we are using something that implements `AsMut<[u8; 3]>`:
 
 ```rust
-use palette::{Srgb, Pixel};
+use palette::Srgb;
 
 fn swap_red_and_blue(mut my_rgb: impl AsMut<[u8; 3]>) {
-    let my_rgb = Srgb::from_raw_mut(my_rgb.as_mut());
+    let my_rgb: &mut Srgb<u8> = my_rgb.as_mut().into();
 
     std::mem::swap(&mut my_rgb.red, &mut my_rgb.blue);
 }
@@ -156,13 +156,13 @@ This image shows the transition from the color to `new_color` in HSL and HSV:
 In addition to the operator traits, the SVG blend functions have also been implemented.
 
 ```rust
-use palette::{blend::Blend, Pixel, Srgb, WithAlpha};
+use palette::{blend::Blend, cast, Srgb, WithAlpha};
 
 // The input to this function could be data from image files.
 fn alpha_blend_images(image1: &mut [u8], image2: &[u8]) {
     // Convert the images into `&mut [Srgb<u8>]` and `&[Srgb<u8>]` without copying.
-    let image1 = Srgb::from_raw_slice_mut(image1);
-    let image2 = Srgb::from_raw_slice(image2);
+    let image1: &mut [Srgb<u8>] = cast::from_component_slice_mut(image1);
+    let image2: &[Srgb<u8>] = cast::from_component_slice(image2);
 
     for (color1, color2) in image1.iter_mut().zip(image2) {
         // Convert the colors to linear floating point format and give them transparency values.

palette/examples/color_scheme.rs

@@ -1,4 +1,4 @@
-use palette::{Darken, IntoColor, Lch, Lighten, LinSrgb, Pixel, ShiftHue, Srgb};
+use palette::{Darken, IntoColor, Lch, Lighten, LinSrgb, ShiftHue, Srgb};
 
 use image::{GenericImage, GenericImageView, RgbImage, SubImage};
 
@@ -170,18 +170,18 @@ fn blit_shades(color: LinSrgb<f32>, mut canvas: SubImage<&mut RgbImage>) {
     let width = canvas.width();
     let height = canvas.height();
 
-    let primary = Srgb::from_linear(color).into_format().into_raw();
+    let primary = Srgb::from_linear(color).into_format().into();
 
     //Generate one lighter and two darker versions of the color
     let light = Srgb::from_linear(color.lighten(0.1).into())
         .into_format()
-        .into_raw();
+        .into();
     let dark1 = Srgb::from_linear(color.darken(0.1).into())
         .into_format()
-        .into_raw();
+        .into();
     let dark2 = Srgb::from_linear(color.darken(0.2).into())
         .into_format()
-        .into_raw();
+        .into();
 
     for x in 0..width {
         for y in 0..height {

palette/examples/gradient.rs

@@ -5,7 +5,7 @@ fn main() {
 
 #[cfg(feature = "std")]
 fn main() {
-    use palette::{FromColor, Gradient, IntoColor, Lch, LinSrgb, Pixel, Srgb};
+    use palette::{FromColor, Gradient, IntoColor, Lch, LinSrgb, Srgb};
 
     use image::{GenericImage, GenericImageView, RgbImage};
 
@@ -47,10 +47,10 @@ fn main() {
         .zip(grad3.take(256).zip(grad4.take(256)))
         .enumerate()
     {
-        let c1 = Srgb::from_linear(c1).into_format().into_raw();
-        let c2 = Srgb::from_linear(c2).into_format().into_raw();
-        let c3 = Srgb::from_linear(c3.into_color()).into_format().into_raw();
-        let c4 = Srgb::from_linear(c4.into_color()).into_format().into_raw();
+        let c1 = Srgb::from_linear(c1).into_format().into();
+        let c2 = Srgb::from_linear(c2).into_format().into();
+        let c3 = Srgb::from_linear(c3.into_color()).into_format().into();
+        let c4 = Srgb::from_linear(c4.into_color()).into_format().into();
 
         {
             let mut sub_image = image.sub_image(i as u32, 0, 1, 31);

palette/examples/hue.rs

@@ -1,4 +1,4 @@
-use palette::{FromColor, Hsl, Lch, Pixel, ShiftHue, Srgb};
+use palette::{FromColor, Hsl, Lch, ShiftHue, Srgb};
 
 fn main() {
     let mut image = image::open("example-data/input/fruits.png")
@@ -9,14 +9,14 @@ fn main() {
     //right part. Notice how LCh manages to preserve the apparent lightness of
     //of the colors, compared to the original.
     for (x, y, pixel) in image.enumerate_pixels_mut() {
-        let color = Srgb::from_raw(&pixel.0).into_format();
+        let color = Srgb::from(pixel.0).into_format();
 
         pixel.0 = if x < y {
             let hue_shifted = Hsl::from_color(color).shift_hue(180.0);
-            Srgb::from_color(hue_shifted).into_format().into_raw()
+            Srgb::from_color(hue_shifted).into_format().into()
         } else {
             let hue_shifted = Lch::from_color(color).shift_hue(180.0);
-            Srgb::from_color(hue_shifted).into_format().into_raw()
+            Srgb::from_color(hue_shifted).into_format().into()
         };
     }
 

palette/examples/random.rs

@@ -5,7 +5,7 @@ fn main() {
 
 #[cfg(feature = "random")]
 fn main() {
-    use palette::{Hsl, Hsv, Hwb, IntoColor, Pixel, RgbHue, Srgb};
+    use palette::{Hsl, Hsv, Hwb, IntoColor, RgbHue, Srgb};
 
     use image::{GenericImage, GenericImageView, RgbImage};
     use rand::Rng;
@@ -20,7 +20,7 @@ fn main() {
         for x in 0..width {
             for y in 0..height {
                 let random_color: Srgb = Srgb::new(rng.gen(), rng.gen(), rng.gen());
-                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into()));
             }
         }
     }
@@ -31,7 +31,7 @@ fn main() {
         for x in 0..width {
             for y in 0..height {
                 let random_color: Srgb = rng.gen();
-                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into()));
             }
         }
     }
@@ -44,7 +44,7 @@ fn main() {
             for y in 0..height {
                 let random_color: Srgb =
                     Hsv::new(rng.gen::<RgbHue>(), rng.gen(), rng.gen()).into_color();
-                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into()));
             }
         }
     }
@@ -55,7 +55,7 @@ fn main() {
         for x in 0..width {
             for y in 0..height {
                 let random_color: Srgb = rng.gen::<Hsv>().into_color();
-                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into()));
             }
         }
     }
@@ -68,7 +68,7 @@ fn main() {
             for y in 0..height {
                 let random_color: Srgb =
                     Hsl::new(rng.gen::<RgbHue>(), rng.gen(), rng.gen()).into_color();
-                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into()));
             }
         }
     }
@@ -79,7 +79,7 @@ fn main() {
         for x in 0..width {
             for y in 0..height {
                 let random_color: Srgb = rng.gen::<Hsl>().into_color();
-                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into()));
             }
         }
     }
@@ -92,7 +92,7 @@ fn main() {
             for y in 0..height {
                 let random_color: Srgb =
                     Hwb::new(rng.gen::<RgbHue>(), rng.gen(), rng.gen()).into_color();
-                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into()));
             }
         }
     }
@@ -103,7 +103,7 @@ fn main() {
         for x in 0..width {
             for y in 0..height {
                 let random_color: Srgb = rng.gen::<Hwb>().into_color();
-                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(random_color.into_format().into()));
             }
         }
     }

palette/examples/readme_examples.rs

@@ -26,13 +26,13 @@ fn converting() {
 }
 
 fn pixels_and_buffers() {
-    use palette::{Pixel, Srgb};
+    use palette::{cast, Srgb};
 
     // The input to this function could be data from an image file or
     // maybe a texture in a game.
     fn swap_red_and_blue(my_rgb_image: &mut [u8]) {
         // Convert `my_rgb_image` into `&mut [Srgb<u8>]` without copying.
-        let my_rgb_image = Srgb::from_raw_slice_mut(my_rgb_image);
+        let my_rgb_image: &mut [Srgb<u8>] = cast::from_component_slice_mut(my_rgb_image);
 
         for color in my_rgb_image {
             std::mem::swap(&mut color.red, &mut color.blue);
@@ -91,13 +91,13 @@ fn color_operations_1() {
 }
 
 fn color_operations_2() {
-    use palette::{blend::Blend, Pixel, Srgb, WithAlpha};
+    use palette::{blend::Blend, cast, Srgb, WithAlpha};
 
     // The input to this function could be data from image files.
     fn alpha_blend_images(image1: &mut [u8], image2: &[u8]) {
         // Convert the images into `&mut [Srgb<u8>]` and `&[Srgb<u8>]` without copying.
-        let image1 = Srgb::from_raw_slice_mut(image1);
-        let image2 = Srgb::from_raw_slice(image2);
+        let image1: &mut [Srgb<u8>] = cast::from_component_slice_mut(image1);
+        let image2: &[Srgb<u8>] = cast::from_component_slice(image2);
 
         for (color1, color2) in image1.iter_mut().zip(image2) {
             // Convert the colors to linear floating point format and give them transparency values.
@@ -216,8 +216,6 @@ fn display_colors(filename: &str, displays: &[DisplayType]) {
 }
 
 fn display_discrete(mut image: SubImage<&mut RgbImage>, colors: &[palette::Srgb<u8>]) {
-    use palette::Pixel;
-
     let (width, height) = image.dimensions();
     let swatch_size = width as f32 / colors.len() as f32;
     for (i, &color) in colors.iter().enumerate() {
@@ -227,7 +225,7 @@ fn display_discrete(mut image: SubImage<&mut RgbImage>, colors: &[palette::Srgb<
         let (width, height) = sub_image.dimensions();
         for x in 0..width {
             for y in 0..height {
-                sub_image.put_pixel(x, y, image::Rgb(*color.as_raw()));
+                sub_image.put_pixel(x, y, image::Rgb(color.into()));
             }
         }
     }
@@ -237,16 +235,10 @@ fn display_continuous(
     mut image: SubImage<&mut RgbImage>,
     color_at: &dyn Fn(f32) -> palette::Srgb<u8>,
 ) {
-    use palette::Pixel;
-
     let (width, height) = image.dimensions();
     for x in 0..width {
         for y in 0..height {
-            image.put_pixel(
-                x,
-                y,
-                image::Rgb(color_at(x as f32 / width as f32).into_raw()),
-            );
+            image.put_pixel(x, y, image::Rgb(color_at(x as f32 / width as f32).into()));
         }
     }
 }

palette/examples/saturate.rs

@@ -1,4 +1,4 @@
-use palette::{FromColor, Hsl, IntoColor, Lch, Pixel, Saturate, Srgb};
+use palette::{FromColor, Hsl, IntoColor, Lch, Saturate, Srgb};
 
 use image::{GenericImage, GenericImageView};
 
@@ -17,15 +17,15 @@ fn main() {
         let (width, height) = sub_image.dimensions();
         for x in 0..width {
             for y in 0..height {
-                let color: Hsl = Srgb::from_raw(&sub_image.get_pixel(x, y).0)
+                let color: Hsl = Srgb::from(sub_image.get_pixel(x, y).0)
                     .into_format()
                     .into_color();
 
                 let saturated = color.saturate(0.3);
                 sub_image.put_pixel(
                     x,
                     y,
-                    image::Rgb(Srgb::from_color(saturated).into_format().into_raw()),
+                    image::Rgb(Srgb::from_color(saturated).into_format().into()),
                 );
             }
         }
@@ -36,15 +36,15 @@ fn main() {
         let (width, height) = sub_image.dimensions();
         for x in 0..width {
             for y in 0..height {
-                let color: Lch = Srgb::from_raw(&sub_image.get_pixel(x, y).0)
+                let color: Lch = Srgb::from(sub_image.get_pixel(x, y).0)
                     .into_format()
                     .into_color();
 
                 let saturated = color.saturate(0.3);
                 sub_image.put_pixel(
                     x,
                     y,
-                    image::Rgb(Srgb::from_color(saturated).into_format().into_raw()),
+                    image::Rgb(Srgb::from_color(saturated).into_format().into()),
                 );
             }
         }

palette/examples/shade.rs

@@ -1,4 +1,4 @@
-use palette::{Darken, FromColor, Hsv, IntoColor, Lab, Lighten, LinSrgb, Pixel, Srgb};
+use palette::{Darken, FromColor, Hsv, IntoColor, Lab, Lighten, LinSrgb, Srgb};
 
 use image::{GenericImage, GenericImageView, RgbImage};
 
@@ -13,10 +13,10 @@ fn main() {
     for i in 0..11 {
         let rgb1 = Srgb::from_linear(rgb.darken(0.1 * i as f32))
             .into_format()
-            .into_raw();
+            .into();
         let rgb2 = Srgb::from_linear(rgb.lighten(0.1 * i as f32))
             .into_format()
-            .into_raw();
+            .into();
 
         {
             let mut sub_image = image.sub_image(i as u32 * 20, 0, 20, 31);
@@ -40,10 +40,10 @@ fn main() {
 
         let lab1 = Srgb::from_linear(lab.darken(0.1 * i as f32).into_color())
             .into_format()
-            .into_raw();
+            .into();
         let lab2 = Srgb::from_linear(lab.lighten(0.1 * i as f32).into_color())
             .into_format()
-            .into_raw();
+            .into();
 
         {
             let mut sub_image = image.sub_image(i as u32 * 20, 65, 20, 31);
@@ -67,10 +67,10 @@ fn main() {
 
         let hsv1 = Srgb::from_linear(hsv.darken(0.1 * i as f32).into_color())
             .into_format()
-            .into_raw();
+            .into();
         let hsv2 = Srgb::from_linear(hsv.lighten(0.1 * i as f32).into_color())
             .into_format()
-            .into_raw();
+            .into();
 
         {
             let mut sub_image = image.sub_image(i as u32 * 20, 130, 20, 31);