Add a few new pixel formats

Author: jdahlstrom

core/src/util/pixfmt.rs

@@ -16,32 +16,71 @@ pub trait IntoPixel<T, F>: Sized {
     }
 }
 
-/// Eight-bit channels in R,G,B order.
+/// Three eight-bit channels in R,G,B order.
+///
+/// Each channel has 2^8 = 256 distinct values, and each pixel takes three
+/// bytes of memory.
 #[derive(Copy, Clone, Default)]
 pub struct Rgb888;
-/// 5,6,5-bit channels in R,G,B order.
+/// Three channels with 5 bits for R, 6 bits for G, and 5 bits for B.
 #[derive(Copy, Clone, Default)]
 pub struct Rgb565;
+/// Three 5-bit channels plus one-bit alpha (1 = opaque, 0 = transparent).
+///
+/// Each color channel has 2^5 = 32 distinct values, and each pixel takes
+/// two bytes of memory.
+#[derive(Copy, Clone, Default)]
+pub struct Rgba5551;
 
-/// Eight-bit channels in X,R,G,B order, where X is unused.
+/// Three eight-bit channels in x,R,G,B order, where x is unused.
+///
+/// Each channel has 2^8 = 256 distinct values, and each pixel takes
+/// four bytes of memory.
 #[derive(Copy, Clone, Default)]
 pub struct Xrgb8888;
-/// Eight-bit channels in R,G,B,A order.
+
+/// Four eight-bit channels in R,G,B,A order.
+///
+/// Each channel has 2^8 = 256 distinct values, and each pixel takes
+/// four bytes of memory.
 #[derive(Copy, Clone, Default)]
 pub struct Rgba8888;
-/// Eight-bit channels in A,R,G,B order.
+
+/// Four eight-bit channels in A,R,G,B order.
+///
+/// Each channel has 2^8 = 256 distinct values, and each pixel takes
+/// four bytes of memory.
 #[derive(Copy, Clone, Default)]
 pub struct Argb8888;
-/// Eight-bit channels in B,G,R,A order.
+
+/// Four eight-bit channels in B,G,R,A order.
+///
+/// Each channel has 2^8 = 256 distinct values, and each pixel takes
+/// four bytes of memory.
 #[derive(Copy, Clone, Default)]
 pub struct Bgra8888;
 
-/// Four-bit channels in R,G,B,A order.
+/// Four four-bit channels in R,G,B,A order.
+///
+/// Each channel has 2^4 = 16 distinct values, and the number of different
+/// RGB values is 2^12 = 4096. Each pixel takes two bytes.
 #[derive(Copy, Clone, Default)]
 pub struct Rgba4444;
 
+/// Three channels with 3 bits for R and g and 2 bits for B.
+///
+/// Red and green have 2^3 = 8 and blue 2^2 = 4 distinct values. The number of
+/// different RGB values is 256, and each pixel takes a single byte.
+#[derive(Copy, Clone, Default)]
+pub struct Rgb332;
+
+/// A single 8-bit luminance channel.
+#[derive(Copy, Clone, Default)]
+pub struct Lum8;
+
 // Impls for Color3
 
+// Rgb888
 impl IntoPixel<u32, Rgb888> for Color3 {
     fn into_pixel(self) -> u32 {
         let [r, g, b] = self.0;
@@ -55,22 +94,34 @@ impl IntoPixel<[u8; 3], Rgb888> for Color3 {
     }
 }
 
+// Rgb565
 impl IntoPixel<u16, Rgb565> for Color3 {
+    /// Packs `self` into a `u16` in `0bRRRRR_GGGGGG_BBBBB` format.
     fn into_pixel(self) -> u16 {
         let [r, g, b] = self.0;
         (r as u16 >> 3 & 0x1F) << 11
             | (g as u16 >> 2 & 0x3F) << 5
             | (b as u16 >> 3 & 0x1F)
     }
 }
-
 impl IntoPixel<[u8; 2], Rgb565> for Color3 {
+    /// Packs `self` into two bytes in `[0bGGG_BBBBB, 0bRRRRR_GGG]` format.
+    // TODO is this correct?
     fn into_pixel(self) -> [u8; 2] {
         let c: u16 = self.into_pixel();
         c.to_ne_bytes()
     }
 }
 
+// Rgb332
+impl IntoPixel<u8, Rgb332> for Color3 {
+    /// Packs `self` into a single byte in `0bRRR_GGG_BB` format.
+    fn into_pixel(self) -> u8 {
+        let [r, g, b] = self.0;
+        (r & 0b111_000_00) | (g >> 3 & 0b000_111_00) | (b >> 6)
+    }
+}
+
 // Impls for Color4
 
 impl<F> IntoPixel<u32, F> for Color4
@@ -83,13 +134,26 @@ where
     }
 }
 
+/*
+impl<T, F> IntoPixel<T, F> for Color4
+where
+    Color3: IntoPixel<T, F>,
+{
+    fn into_pixel(self) -> T {
+        self.to_rgb().into_pixel()
+    }
+}*/
+
+// Xrgb8888
 impl IntoPixel<u32, Xrgb8888> for Color4 {
     fn into_pixel(self) -> u32 {
         let [r, g, b, _] = self.0;
         // From [0x00, 0xRR, 0xGG, 0xBB] to 0x00_RR_GG_BB -> big-endian!
         u32::from_be_bytes([0, r, g, b])
     }
 }
+
+// Rgba8888 and permutations
 impl IntoPixel<[u8; 4], Rgba8888> for Color4 {
     fn into_pixel(self) -> [u8; 4] {
         self.0
@@ -107,11 +171,8 @@ impl IntoPixel<[u8; 4], Bgra8888> for Color4 {
         [b, g, r, a]
     }
 }
-impl IntoPixel<[u8; 3], Rgb888> for Color4 {
-    fn into_pixel(self) -> [u8; 3] {
-        [self.r(), self.g(), self.b()]
-    }
-}
+
+// Rgba4444
 impl IntoPixel<[u8; 2], Rgba4444> for Color4 {
     fn into_pixel(self) -> [u8; 2] {
         let c: u16 = self.into_pixel_fmt(Rgba4444);
@@ -125,18 +186,41 @@ impl IntoPixel<u16, Rgba4444> for Color4 {
         r << 12 | g << 8 | b << 4 | a
     }
 }
-impl IntoPixel<u16, Rgb565> for Color4 {
+
+// Rgba 5551
+impl IntoPixel<u16, Rgba5551> for Color4 {
+    /// Packs `self` into a `u16` in a `0bRRRRR_GGGGG_BBBBB_A` format.
+    /// The alpha value `0xFF` is considered opaque, any other value
+    /// fully transparent.
     fn into_pixel(self) -> u16 {
-        self.to_rgb().into_pixel()
+        let [r, g, b, a] = self.0;
+        (r as u16 >> 3 & 0x1F) << 11
+            | (g as u16 >> 3 & 0x1F) << 6
+            | (b as u16 >> 3 & 0x1F) << 1
+            | (a == 0xFF) as u16
     }
 }
-impl IntoPixel<[u8; 2], Rgb565> for Color4 {
+impl IntoPixel<[u8; 2], Rgba5551> for Color4 {
     fn into_pixel(self) -> [u8; 2] {
-        let c: u16 = self.into_pixel_fmt(Rgb565);
+        let c: u16 = self.into_pixel_fmt(Rgba5551);
         c.to_ne_bytes()
     }
 }
 
+// Rgb332
+impl IntoPixel<u8, Rgb332> for Color4 {
+    /// Packs `self` into a single byte in `0bRRR_GGG_BB` format.
+    fn into_pixel(self) -> u8 {
+        self.to_rgb().into_pixel()
+    }
+}
+impl IntoPixel<[u8; 1], Rgb332> for Color4 {
+    /// Packs `self` into a single byte in `0bRRR_GGG_BB` format.
+    fn into_pixel(self) -> [u8; 1] {
+        [self.into_pixel()]
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::math::{rgb, rgba};
@@ -160,6 +244,15 @@ mod tests {
         assert_eq!(pix, [0b000_00010, 0b01000_001]);
     }
 
+    #[test]
+    fn color3_to_rgb332() {
+        let pix: u8 = rgb(0xFF, 0x00, 0xFF).into_pixel();
+        assert_eq!(pix, 0b111_000_11, "bits: {pix:b}");
+
+        let pix: u8 = rgb(0x00, 0x0FF, 0x00).into_pixel();
+        assert_eq!(pix, 0b000_111_00, "bits: {pix:b}");
+    }
+
     #[test]
     fn color4_to_rgba8888() {
         let col = rgba(0x11u8, 0x22, 0x33, 0x44);
@@ -199,4 +292,23 @@ mod tests {
         let pix: u16 = COL4.into_pixel_fmt(Rgba4444);
         assert_eq!(pix, 0x1234);
     }
+
+    #[test]
+    fn color4_to_rgba5551_u16() {
+        let pix: u16 = rgba(0x40u8, 0x20, 0x10, 0).into_pixel_fmt(Rgba5551);
+        assert_eq!(pix, 0b01000_00100_00010_0_u16, "bits: {pix:b}");
+        let pix: u16 = rgba(0x40u8, 0x20, 0x10, 0x80).into_pixel_fmt(Rgba5551);
+        assert_eq!(pix, 0b01000_00100_00010_0_u16, "bits: {pix:b}");
+        let pix: u16 = rgba(0x40u8, 0x20, 0x10, 0xFF).into_pixel_fmt(Rgba5551);
+        assert_eq!(pix, 0b01000_00100_00010_1_u16, "bits: {pix:b}");
+    }
+
+    #[test]
+    fn color4_to_rgba5551_2u8() {
+        let pix: [u8; 2] = rgba(0x40u8, 0x20, 0x10, 0).into_pixel_fmt(Rgba5551);
+        assert_eq!(pix, [0b00_00010_0, 0b01000_001]);
+        let pix: [u8; 2] =
+            rgba(0x40u8, 0x20, 0x10, 0xFF).into_pixel_fmt(Rgba5551);
+        assert_eq!(pix, [0b00_00010_1, 0b01000_001]);
+    }
 }

demos/src/bin/crates.rs

@@ -9,9 +9,8 @@ use re::core::render::{
     scene::Obj,
     tex::SamplerClamp,
 };
-// Try also Rgb565 or Rgba4444
+// Try also Rgb565, Rgba4444, or Rgb332
 use re::core::util::{pixfmt::Rgba8888, pnm::read_pnm};
-
 use re::front::sdl2::Window;
 use re::geom::solids::{Build, Cube};
 

front/src/sdl2.rs

@@ -11,6 +11,7 @@ use sdl2::{
     video::{FullscreenType, Window as SdlWindow, WindowBuildError},
 };
 
+use super::{Frame, dims};
 use retrofire_core::math::{Color4, Vary};
 use retrofire_core::render::{
     Colorbuf, Context, FragmentShader, Target, raster::Scanline,
@@ -19,11 +20,9 @@ use retrofire_core::render::{
 use retrofire_core::util::{
     Dims,
     buf::{AsMutSlice2, Buf2, MutSlice2},
-    pixfmt::{IntoPixel, Rgb565, Rgba4444, Rgba8888},
+    pixfmt::*,
 };
 
-use super::{Frame, dims};
-
 /// Helper trait to support different pixel format types.
 pub trait PixelFmt: Copy + Default {
     type Pixel: AsRef<[u8]> + Copy + Sized;
@@ -104,7 +103,12 @@ impl<'t, PF: PixelFmt> Builder<'t, PF> {
     }
     /// Sets the framebuffer pixel format.
     ///
-    /// Supported formats are [`Rgba8888`], [`Rgb565`], and [`Rgba4444`].
+    /// Currently supported formats are
+    /// * [`Rgba8888`],
+    /// * [`Rgba5551`],
+    /// * [`Rgba4444`],
+    /// * [`Rgb565`], and
+    /// * [`Rgb332`].
     pub fn pixel_fmt(mut self, fmt: PF) -> Self {
         self.pixfmt = fmt;
         self
@@ -265,6 +269,14 @@ impl PixelFmt for Rgba4444 {
     type Pixel = [u8; 2];
     const SDL_FMT: PixelFormatEnum = PixelFormatEnum::RGBA4444;
 }
+impl PixelFmt for Rgba5551 {
+    type Pixel = [u8; 2];
+    const SDL_FMT: PixelFormatEnum = PixelFormatEnum::RGBA5551;
+}
+impl PixelFmt for Rgb332 {
+    type Pixel = [u8; 1];
+    const SDL_FMT: PixelFormatEnum = PixelFormatEnum::RGB332;
+}
 
 impl<'a, PF, const N: usize> Target for Framebuf<'a, PF>
 where