Make the pixel format platform dependent

The format is RGBX on WASM and Android and BGRX elsewhere. This should
allow avoiding needless copying on these platforms.

Author: madsmtm

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Unreleased
 
 - **Breaking:** Add `Pixel` struct, and use that for pixels instead of `u32`.
+- **Breaking:** The pixel format is now target-dependent.
 
 # 0.4.7
 

src/backends/android.rs

@@ -164,6 +164,7 @@ impl<'a, D: HasDisplayHandle, W: HasWindowHandle> BufferInterface for BufferImpl
 
             // Write RGB(A) to the output.
             // TODO: Use `slice::write_copy_of_slice` once stable and in MSRV.
+            // TODO(madsmtm): Verify that this compiles down to an efficient copy.
             for (i, pixel) in input.iter().enumerate() {
                 output[i * 4].write(pixel.r);
                 output[i * 4 + 1].write(pixel.g);

src/backends/web.rs

@@ -145,6 +145,8 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> WebImpl<D, W> {
                     .skip(union_damage.x as usize)
                     .take(union_damage.width.get() as usize)
             })
+            // TODO(madsmtm): Once we support alpha, add it here, and verify that this
+            // optimize away to nothing (and if it doesn't, unsafely cast instead).
             .flat_map(|pixel| [pixel.r, pixel.g, pixel.b, 255])
             .collect();
 

src/lib.rs

@@ -23,7 +23,7 @@ use std::sync::Arc;
 
 use self::error::InitError;
 pub use self::error::SoftBufferError;
-pub use self::pixel::Pixel;
+pub use self::pixel::{Pixel, PixelFormat, PIXEL_FORMAT};
 
 use raw_window_handle::{HasDisplayHandle, HasWindowHandle, RawDisplayHandle, RawWindowHandle};
 

src/pixel.rs

@@ -2,20 +2,18 @@
 ///
 /// # Representation
 ///
-/// This is a set of `u8`'s in the order BGRX (first component blue, second green, third red and
-/// last unset).
+/// This is a set of `u8`'s in the order defined by [`PIXEL_FORMAT`].
 ///
-/// If you're familiar with [the `rgb` crate](https://docs.rs/rgb/), you can treat this mostly as-if
-/// it is `rgb::Bgra<u8>`, except that this type has an alignment of `4` for performance reasons, as
-/// that makes copies faster on many platforms.
+/// This type has an alignment of `4` for performance reasons, as that makes copies faster on many
+/// platforms, and makes this type have the same in-memory representation as `u32`.
 ///
 /// # Example
 ///
 /// Construct a new pixel.
 ///
 /// ```
-/// # use softbuffer::Pixel;
-/// #
+/// use softbuffer::Pixel;
+///
 /// let red = Pixel::new_rgb(0xff, 0x80, 0);
 /// assert_eq!(red.r, 255);
 /// assert_eq!(red.g, 128);
@@ -25,36 +23,93 @@
 /// Convert a pixel to an array of `u8`s.
 ///
 /// ```
-/// # use softbuffer::Pixel;
-/// #
+/// use softbuffer::{Pixel, PixelFormat, PIXEL_FORMAT};
+///
 /// let red = Pixel::new_rgb(0xff, 0, 0);
 /// // SAFETY: `Pixel` can be reinterpreted as `[u8; 4]`.
 /// let red = unsafe { core::mem::transmute::<Pixel, [u8; 4]>(red) };
 ///
-/// // BGRX
-/// assert_eq!(red[2], 255);
+/// match PIXEL_FORMAT {
+///     PixelFormat::Rgbx => assert_eq!(red[0], 255),
+///     PixelFormat::Bgrx => assert_eq!(red[2], 255),
+/// }
 /// ```
 ///
 /// Convert a pixel to an `u32`.
 ///
 /// ```
-/// # use softbuffer::Pixel;
-/// #
+/// use softbuffer::{Pixel, PixelFormat, PIXEL_FORMAT};
+///
 /// let red = Pixel::new_rgb(0xff, 0, 0);
 /// // SAFETY: `Pixel` can be reinterpreted as `u32`.
 /// let red = unsafe { core::mem::transmute::<Pixel, u32>(red) };
 ///
-/// // BGRX
-/// assert_eq!(red, u32::from_le_bytes([0x00, 0x00, 0xff, 0x00]));
+/// match PIXEL_FORMAT {
+///     PixelFormat::Rgbx => assert_eq!(red, u32::from_le_bytes([0xff, 0x00, 0x00, 0x00])),
+///     PixelFormat::Bgrx => assert_eq!(red, u32::from_le_bytes([0x00, 0x00, 0xff, 0x00])),
+/// }
+/// ```
+///
+/// Convert a slice of pixels to a slice of `u32`s. This might be useful for library authors that
+/// want to keep rendering using BGRX.
+///
+/// ```
+/// // Assume the user controls the following rendering function:
+/// fn render(pixels: &mut [u32]) {
+///     pixels.fill(u32::from_le_bytes([0xff, 0xff, 0x00, 0x00])); // Yellow in BGRX
+/// }
+///
+/// // Then we'd convert pixel data as follows:
+/// use softbuffer::{Pixel, PixelFormat, PIXEL_FORMAT};
+///
+/// # let mut pixel_data = [Pixel::new_rgb(0, 0xff, 0xff)];
+/// let pixels: &mut [Pixel];
+/// # pixels = &mut pixel_data;
+///
+/// if PIXEL_FORMAT == PixelFormat::Bgrx {
+///     // Fast implementation when the pixel format is BGRX.
+///
+///     // SAFETY: `Pixel` can be reinterpreted as `u32`.
+///     let pixels = unsafe { std::mem::transmute::<&mut [Pixel], &mut [u32]>(pixels) };
+///     // CORRECTNESS: We just checked that the format is BGRX.
+///     render(pixels);
+/// } else {
+///     // Fall back to slower implementation when the format is RGBX.
+///
+///     // Render into temporary buffer.
+///     let mut buffer = vec![0u32; pixels.len()];
+///     render(&mut buffer);
+///
+///     // And copy from temporary buffer to actual pixel data.
+///     for (old, new) in pixels.iter_mut().zip(buffer) {
+///         let new = new.to_le_bytes();
+///         *old = Pixel::new_bgr(new[0], new[1], new[2]);
+///     }
+/// }
+/// #
+/// # assert_eq!(pixel_data, [Pixel::new_rgb(0, 0xff, 0xff)]);
 /// ```
 #[repr(C)]
 #[repr(align(4))] // May help the compiler to see that this is a u32
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct Pixel {
+    #[cfg(any(target_family = "wasm", target_os = "android"))]
+    /// The red component.
+    pub r: u8,
+    #[cfg(any(target_family = "wasm", target_os = "android"))]
+    /// The green component.
+    pub g: u8,
+    #[cfg(any(target_family = "wasm", target_os = "android"))]
     /// The blue component.
     pub b: u8,
+
+    #[cfg(not(any(target_family = "wasm", target_os = "android")))]
+    /// The blue component.
+    pub b: u8,
+    #[cfg(not(any(target_family = "wasm", target_os = "android")))]
     /// The green component.
     pub g: u8,
+    #[cfg(not(any(target_family = "wasm", target_os = "android")))]
     /// The red component.
     pub r: u8,
 
@@ -110,3 +165,35 @@ impl Pixel {
 }
 
 // TODO: Implement `Add`/`Mul`/similar `std::ops` like `rgb` does?
+
+// TODO: Implement `zerocopy` / `bytemuck` traits behind a feature flag?
+// May not be that useful, since the representation is platform-specific.
+
+/// A pixel format that `softbuffer` may use.
+///
+/// See [`PIXEL_FORMAT`].
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub enum PixelFormat {
+    /// The pixel format is `RGBX` (red, green, blue, unset).
+    Rgbx,
+    /// The pixel format is `BGRX` (blue, green, red, unset).
+    Bgrx,
+    // Intentionally exhaustive.
+}
+
+/// The pixel format that `softbuffer` uses for the current target platform.
+///
+/// Currently, this is BGRX (first component blue, second green, third red and last unset) on all
+/// platforms except WebAssembly and Android targets, where it is RGBX, since the API on these
+/// platforms only support that format.
+///
+/// The format for a given platform may change in a non-breaking release if found to be more
+/// performant.
+///
+/// This distinction should only be relevant if you're bitcasting `Pixel` to/from a `u32`, to e.g.
+/// avoid unnecessary copying, see [`Pixel`] for examples.
+pub const PIXEL_FORMAT: PixelFormat = if cfg!(any(target_family = "wasm", target_os = "android")) {
+    PixelFormat::Rgbx
+} else {
+    PixelFormat::Bgrx
+};