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 `PixelFormat::default()` to see which format is used on the current platform.
 - **Breaking:** Removed unintentional Cargo features for Softbuffer's optional dependencies.
 - **Breaking:** Disable the DRM/KMS backend by default.
 - **Breaking:** Removed `DamageOutOfRange` error case. If the damage value is greater than the backend supports, it is instead clamped to an appropriate value.

src/backends/android.rs

@@ -166,8 +166,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,37 @@
+/// A pixel format that Softbuffer may use.
+///
+/// # Default
+///
+/// The [`Default::default`] implementation returns the pixel format that Softbuffer uses for the
+/// current target platform.
+///
+/// Currently, this is [`BGRX`][Self::Bgrx] on all platforms except WebAssembly and Android, where
+/// it is [`RGBX`][Self::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`][crate::Pixel] for examples.
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Default)]
+pub enum PixelFormat {
+    /// The pixel format is `RGBX` (red, green, blue, unset).
+    ///
+    /// This is currently the default on macOS/iOS, KMS/DRM, Orbital, Wayland, Windows and X11.
+    #[cfg_attr(not(any(target_family = "wasm", target_os = "android")), default)]
+    Bgrx,
+    /// The pixel format is `BGRX` (blue, green, red, unset).
+    ///
+    /// This is currently the default on Android and Web.
+    #[cfg_attr(any(target_family = "wasm", target_os = "android"), default)]
+    Rgbx,
+    // Intentionally exhaustive for now.
+}
+
+impl PixelFormat {
+    /// Check whether the given pixel format is the default format that Softbuffer uses.
+    #[inline]
+    pub fn is_default(self) -> bool {
+        self == Self::default()
+    }
+}

src/lib.rs

@@ -10,6 +10,7 @@ mod backend_dispatch;
 mod backend_interface;
 mod backends;
 mod error;
+mod format;
 mod pixel;
 mod util;
 
@@ -26,6 +27,7 @@ use self::backend_interface::*;
 pub use self::backends::web::SurfaceExtWeb;
 use self::error::InitError;
 pub use self::error::SoftBufferError;
+pub use self::format::PixelFormat;
 pub use self::pixel::Pixel;
 
 /// An instance of this struct contains the platform-specific data that must be managed in order to
@@ -309,6 +311,46 @@ impl Buffer<'_> {
     /// # let buffer: Buffer<'_> = unimplemented!();
     /// buffer.pixels().fill(Pixel::new_rgb(0xff, 0x00, 0x00));
     /// ```
+    ///
+    /// Render to a slice of `[u8; 4]`s. This might be useful for library authors that want to
+    /// provide a simple API that provides RGBX rendering.
+    ///
+    /// ```no_run
+    /// use softbuffer::{Pixel, PixelFormat};
+    ///
+    /// // Assume the user controls the following rendering function:
+    /// fn render(pixels: &mut [[u8; 4]], width: u32, height: u32) {
+    ///     pixels.fill([0xff, 0xff, 0x00, 0x00]); // Yellow in RGBX
+    /// }
+    ///
+    /// // Then we'd convert pixel data as follows:
+    ///
+    /// # let buffer: softbuffer::Buffer<'_> = todo!();
+    /// # #[cfg(false)]
+    /// let buffer = surface.buffer_mut();
+    ///
+    /// let width = buffer.width().get();
+    /// let height = buffer.height().get();
+    ///
+    /// // Use fast, zero-copy implementation when possible, and fall back to slower version when not.
+    /// if PixelFormat::Rgbx.is_default() {
+    ///     // SAFETY: `Pixel` can be reinterpreted as `[u8; 4]`.
+    ///     let pixels = unsafe { std::mem::transmute::<&mut [Pixel], &mut [[u8; 4]]>(buffer.pixels()) };
+    ///     // CORRECTNESS: We just checked that the format is RGBX.
+    ///     render(pixels, width, height);
+    /// } else {
+    ///     // Render into temporary buffer.
+    ///     let mut temporary = vec![[0; 4]; width as usize * height as usize];
+    ///     render(&mut temporary, width, height);
+    ///
+    ///     // And copy from temporary buffer to actual pixel data.
+    ///     for (tmp, actual) in temporary.iter_mut().zip(buffer.pixels()) {
+    ///         *actual = Pixel::new_rgb(tmp[0], tmp[1], tmp[2]);
+    ///     }
+    /// }
+    ///
+    /// buffer.present();
+    /// ```
     pub fn pixels(&mut self) -> &mut [Pixel] {
         self.buffer_impl.pixels_mut()
     }

src/pixel.rs

@@ -2,19 +2,20 @@
 ///
 /// # 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 [`PixelFormat::default()`].
 ///
-/// 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.
+/// 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`.
+///
+/// [`PixelFormat::default()`]: crate::PixelFormat#default
 ///
 /// # 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 +29,52 @@
 /// Convert a pixel to an array of `u8`s.
 ///
 /// ```
-/// # use softbuffer::Pixel;
-/// #
+/// use softbuffer::{Pixel, PixelFormat};
+///
 /// 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 PixelFormat::default() {
+///     PixelFormat::Bgrx => assert_eq!(red[2], 255),
+///     PixelFormat::Rgbx => assert_eq!(red[0], 255),
+/// }
 /// ```
 ///
 /// Convert a pixel to an `u32`.
 ///
 /// ```
-/// # use softbuffer::Pixel;
-/// #
+/// use softbuffer::{Pixel, PixelFormat};
+///
 /// 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 PixelFormat::default() {
+///     PixelFormat::Bgrx => assert_eq!(red, u32::from_ne_bytes([0x00, 0x00, 0xff, 0x00])),
+///     PixelFormat::Rgbx => assert_eq!(red, u32::from_ne_bytes([0xff, 0x00, 0x00, 0x00])),
+/// }
 /// ```
 #[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(not(any(doc, target_family = "wasm", target_os = "android")))]
     /// The blue component.
     pub b: u8,
+
     /// 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 red component.
     pub r: u8,
 
@@ -106,3 +123,6 @@ 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.