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,11 +1,13 @@
 # Unreleased
 
+- Added `PixelFormat` enum.
 - Added `Buffer::pixels()` for accessing the buffer's pixel data.
 - Added `Buffer::pixel_rows()` for iterating over rows of the buffer data.
 - Added `Buffer::pixels_iter()` for iterating over each pixel with its associated `x`/`y` coordinate.
 - **Breaking:** Removed generic type parameters `D` and `W` from `Buffer<'_>` struct.
 - **Breaking:** Removed `Deref[Mut]` implementation on `Buffer<'_>`. Use `Buffer::pixels()` instead.
 - **Breaking:** Add `Pixel` struct, and use that for pixels instead of `u32`.
+- **Breaking:** The pixel format is now target-dependent. Access `DEFAULT_PIXEL_FORMAT` to see which format to use on the current platform.
 
 # 0.4.7
 

src/backends/android.rs

@@ -156,8 +156,8 @@ impl BufferInterface for BufferImpl<'_> {
             assert_eq!(output.len(), input.len() * 4);
 
             // Write RGB(A) to the output.
-            // TODO: Use `slice::write_copy_of_slice` once stable and in MSRV and once the pixel
-            // structure is of the RGBA format.
+            // 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/format.rs

@@ -0,0 +1,11 @@
+/// A pixel format that `softbuffer` may use.
+///
+/// See [`DEFAULT_PIXEL_FORMAT`][crate::DEFAULT_PIXEL_FORMAT].
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
+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 for now.
+}

src/lib.rs

@@ -10,6 +10,7 @@ mod backend_dispatch;
 mod backend_interface;
 mod backends;
 mod error;
+mod format;
 mod pixel;
 mod util;
 
@@ -26,7 +27,8 @@ use self::backend_interface::*;
 pub use self::backends::web::SurfaceExtWeb;
 use self::error::InitError;
 pub use self::error::SoftBufferError;
-pub use self::pixel::Pixel;
+pub use self::format::PixelFormat;
+pub use self::pixel::{Pixel, DEFAULT_PIXEL_FORMAT};
 
 /// An instance of this struct contains the platform-specific data that must be managed in order to
 /// write to a window on that platform.

src/pixel.rs

@@ -1,20 +1,23 @@
+use crate::PixelFormat;
+
 /// A RGBA pixel.
 ///
 /// # 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 4 `u8`'s laid out in the order defined by [`DEFAULT_PIXEL_FORMAT`].
+///
+/// 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`.
 ///
-/// 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.
+/// [`DEFAULT_PIXEL_FORMAT`]: crate::DEFAULT_PIXEL_FORMAT
 ///
 /// # 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);
@@ -28,36 +31,96 @@
 /// Convert a pixel to an array of `u8`s.
 ///
 /// ```
-/// # use softbuffer::Pixel;
-/// #
+/// use softbuffer::{Pixel, PixelFormat, DEFAULT_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 DEFAULT_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, DEFAULT_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 DEFAULT_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, DEFAULT_PIXEL_FORMAT};
+///
+/// # let mut pixel_data = [Pixel::new_rgb(0, 0xff, 0xff)];
+/// let pixels: &mut [Pixel];
+/// # pixels = &mut pixel_data;
+///
+/// if DEFAULT_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))] // Help the compiler to see that this is a u32
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Default)]
 pub struct Pixel {
+    #[cfg_attr(docsrs, doc(auto_cfg = false))]
+    #[cfg(any(doc, target_family = "wasm", target_os = "android"))]
+    /// The red component.
+    pub r: u8,
+    #[cfg_attr(docsrs, doc(auto_cfg = false))]
+    #[cfg(any(doc, target_family = "wasm", target_os = "android"))]
+    /// The green component.
+    pub g: u8,
+    #[cfg_attr(docsrs, doc(auto_cfg = false))]
+    #[cfg(any(doc, target_family = "wasm", target_os = "android"))]
     /// The blue component.
     pub b: u8,
+
+    #[cfg(not(any(doc, target_family = "wasm", target_os = "android")))]
+    /// The blue component.
+    pub b: u8,
+    #[cfg(not(any(doc, target_family = "wasm", target_os = "android")))]
     /// The green component.
     pub g: u8,
+    #[cfg(not(any(doc, target_family = "wasm", target_os = "android")))]
     /// The red component.
     pub r: u8,
 
@@ -106,3 +169,24 @@ 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.
+
+/// 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, where it is RGBX, since the API on these platforms
+/// does not support BGRX.
+///
+/// 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 the documentation for [`Pixel`] for examples.
+pub const DEFAULT_PIXEL_FORMAT: PixelFormat =
+    if cfg!(any(doc, target_family = "wasm", target_os = "android")) {
+        PixelFormat::Rgbx
+    } else {
+        PixelFormat::Bgrx
+    };