From b4a78e73712ee9ea6cee60d335314c5b776af23b Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Wed, 22 Apr 2026 20:26:06 +0200 Subject: [PATCH] Prepare for supporting multiple pixel formats Make `PixelFormat` `#[non_exhaustive]`, and rename the variants from `Rgba` -> `Rgba8` and `Bgra` -> `Bgra8`. --- src/format.rs | 42 ++++++++++++++++++++++++++++++------------ src/lib.rs | 2 +- src/pixel.rs | 10 ++++++---- 3 files changed, 37 insertions(+), 17 deletions(-) diff --git a/src/format.rs b/src/format.rs index b4a1dad1..2912100f 100644 --- a/src/format.rs +++ b/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 { diff --git a/src/lib.rs b/src/lib.rs index 06acf64f..ed05a9e7 100644 --- a/src/lib.rs +++ b/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 /// { diff --git a/src/pixel.rs b/src/pixel.rs index f0df0d20..7f1f7a3a 100644 --- a/src/pixel.rs +++ b/src/pixel.rs @@ -43,8 +43,9 @@ /// let red = unsafe { core::mem::transmute::(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::(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)]