Prepare for supporting multiple pixel formats

src/format.rs

@@ -1,10 +1,10 @@
-/// A pixel format that Softbuffer may use.
+/// The pixel format of a surface and buffer.
 ///
 /// # Alpha
 ///
 /// These pixel formats all include the alpha channel in their name, but formats that ignore the
-/// alpha channel are supported if you set [`AlphaMode::Ignored`]. This will make `RGBA` mean `RGBX`
-/// and `BGRA` mean `BGRX`.
+/// alpha channel are supported if you use [`AlphaMode::Ignored`]. This will make `Rgba8` mean
+/// `Rgbx8`, for example.
 ///
 /// [`AlphaMode::Ignored`]: crate::AlphaMode::Ignored
 ///
@@ -13,27 +13,45 @@
 /// The [`Default::default`] implementation returns the pixel format that Softbuffer uses for the
 /// current target platform.
 ///
-/// Currently, this is [`BGRA`][Self::Bgra] on all platforms except WebAssembly and Android, where
-/// it is [`RGBA`][Self::Rgba], since the API on these platforms does not support BGRA.
+/// Currently, this is [`Bgra8`][Self::Bgra8] on all platforms except WebAssembly and Android, where
+/// it is [`Rgba8`][Self::Rgba8], since the API on these platforms does not support BGRA.
 ///
 /// 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.
+#[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Default)]
 pub enum PixelFormat {
-    /// The pixel format is `RGBA` (red, green, blue, alpha).
+    // This uses roughly the same naming scheme as WebGPU does.
+    /// 32-bit BGRA, `u8` per channel. Laid out in memory as `B,G,R,A`.
     ///
-    /// This is currently the default on macOS/iOS, KMS/DRM, Orbital, Wayland, Windows and X11.
+    /// **This is currently the default on macOS/iOS, KMS/DRM, Orbital, Wayland, Windows and X11**.
+    ///
+    /// ## Platform Support
+    ///
+    /// - macOS/iOS, KMS/DRM, Orbital, Wayland, Windows and X11: Supported.
+    /// - Android and Web: Not yet supported.
     #[cfg_attr(not(any(target_family = "wasm", target_os = "android")), default)]
-    Bgra,
-    /// The pixel format is `BGRA` (blue, green, red, alpha).
+    #[doc(alias = "Argb8888")]
+    #[doc(alias = "Xrgb8888")]
+    #[doc(alias = "VK_FORMAT_B8G8R8A8_UNORM")]
+    Bgra8,
+
+    /// 32-bit RGBA, `u8` per channel. Laid out in memory as `R,G,B,A`.
+    ///
+    /// **This is currently the default on Android and Web**.
+    ///
+    /// ## Platform Support
     ///
-    /// This is currently the default on Android and Web.
+    /// - Android and Web: Supported.
+    /// - macOS/iOS, KMS/DRM, Orbital, Wayland, Windows and X11: Not yet supported.
     #[cfg_attr(any(target_family = "wasm", target_os = "android"), default)]
-    Rgba,
-    // Intentionally exhaustive for now.
+    #[doc(alias = "Abgr8888")]
+    #[doc(alias = "Xbgr8888")]
+    #[doc(alias = "VK_FORMAT_R8G8B8A8_UNORM")]
+    Rgba8,
 }
 
 impl PixelFormat {

src/lib.rs

@@ -447,7 +447,7 @@ impl Buffer<'_> {
     /// let width = buffer.width().get();
     /// let height = buffer.height().get();
     ///
-    /// if PixelFormat::Rgba.is_default()
+    /// if PixelFormat::Rgba8.is_default()
     ///     && buffer.byte_stride().get() == width * 4
     ///     && buffer.alpha_mode() == AlphaMode::Ignored
     /// {

src/pixel.rs

@@ -43,8 +43,9 @@
 /// let red = unsafe { core::mem::transmute::<Pixel, [u8; 4]>(red) };
 ///
 /// match PixelFormat::default() {
-///     PixelFormat::Bgra => assert_eq!(red[2], 255),
-///     PixelFormat::Rgba => assert_eq!(red[0], 255),
+///     PixelFormat::Bgra8 => assert_eq!(red[2], 255),
+///     PixelFormat::Rgba8 => assert_eq!(red[0], 255),
+///     format => unimplemented!("unknown default pixel format: {format:?}"),
 /// }
 /// ```
 ///
@@ -58,8 +59,9 @@
 /// let red = unsafe { core::mem::transmute::<Pixel, u32>(red) };
 ///
 /// match PixelFormat::default() {
-///     PixelFormat::Bgra => assert_eq!(red, u32::from_ne_bytes([0x00, 0x00, 0xff, 0xff])),
-///     PixelFormat::Rgba => assert_eq!(red, u32::from_ne_bytes([0xff, 0x00, 0x00, 0xff])),
+///     PixelFormat::Bgra8 => assert_eq!(red, u32::from_ne_bytes([0x00, 0x00, 0xff, 0xff])),
+///     PixelFormat::Rgba8 => assert_eq!(red, u32::from_ne_bytes([0xff, 0x00, 0x00, 0xff])),
+///     format => unimplemented!("unknown default pixel format: {format:?}"),
 /// }
 /// ```
 #[repr(C)]