Add Pixel struct

This is much more intuitive to use than manually bit-packing into a u32.

Author: madsmtm

CHANGELOG.md

@@ -5,6 +5,7 @@
 - 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:** 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.

README.md

@@ -67,6 +67,7 @@ To run the Android-specific example on an Android phone: `cargo apk r --example
 ```rust,no_run
 use std::num::NonZeroU32;
 use std::rc::Rc;
+use softbuffer::{Context, Pixel, Surface};
 use winit::event::{Event, WindowEvent};
 use winit::event_loop::{ControlFlow, EventLoop};
 use winit::window::Window;
@@ -76,14 +77,14 @@ mod util;
 
 fn main() {
     let event_loop = EventLoop::new().unwrap();
-    let context = softbuffer::Context::new(event_loop.owned_display_handle()).unwrap();
+    let context = Context::new(event_loop.owned_display_handle()).unwrap();
 
     let mut app = util::WinitAppBuilder::with_init(
         |elwt| {
             let window = elwt.create_window(Window::default_attributes());
             Rc::new(window.unwrap())
         },
-        |_elwt, window| softbuffer::Surface::new(&context, window.clone()).unwrap(),
+        |_elwt, window| Surface::new(&context, window.clone()).unwrap(),
     )
     .with_event_handler(|window, surface, window_id, event, elwt| {
         elwt.set_control_flow(ControlFlow::Wait);
@@ -108,11 +109,11 @@ fn main() {
 
                 let mut buffer = surface.buffer_mut().unwrap();
                 for (x, y, pixel) in buffer.pixels_iter() {
-                    let red = x % 255;
-                    let green = y % 255;
-                    let blue = (x * y) % 255;
+                    let red = (x % 255) as u8;
+                    let green = (y % 255) as u8;
+                    let blue = ((x * y) % 255) as u8;
 
-                    *pixel = blue | (green << 8) | (red << 16);
+                    *pixel = Pixel::new_rgb(red, green, blue);
                 }
 
                 buffer.present().unwrap();

benches/buffer_mut.rs

@@ -7,7 +7,7 @@
 )))]
 fn buffer_mut(c: &mut criterion::Criterion) {
     use criterion::black_box;
-    use softbuffer::{Context, Surface};
+    use softbuffer::{Context, Pixel, Surface};
     use std::num::NonZeroU32;
     use winit::event_loop::ControlFlow;
     use winit::platform::run_on_demand::EventLoopExtRunOnDemand;
@@ -43,16 +43,16 @@ fn buffer_mut(c: &mut criterion::Criterion) {
             c.bench_function("pixels()", |b| {
                 let mut buffer = surface.buffer_mut().unwrap();
                 b.iter(|| {
-                    let pixels: &mut [u32] = buffer.pixels();
+                    let pixels: &mut [Pixel] = buffer.pixels();
                     black_box(pixels);
                 });
             });
 
-            c.bench_function("fill u32", |b| {
+            c.bench_function("fill pixels", |b| {
                 let mut buffer = surface.buffer_mut().unwrap();
                 b.iter(|| {
                     let buffer = black_box(&mut buffer);
-                    buffer.pixels().fill(0x00000000);
+                    buffer.pixels().fill(Pixel::default());
                 });
             });
 
@@ -64,7 +64,7 @@ fn buffer_mut(c: &mut criterion::Criterion) {
                         let red = (x & 0xff) ^ (y & 0xff);
                         let green = (x & 0x7f) ^ (y & 0x7f);
                         let blue = (x & 0x3f) ^ (y & 0x3f);
-                        *pixel = blue | (green << 8) | (red << 16);
+                        *pixel = Pixel::new_rgb(red as u8, green as u8, blue as u8);
                     }
                 });
             });

examples/animation.rs

@@ -1,5 +1,6 @@
 #[cfg(not(target_family = "wasm"))]
 use rayon::prelude::*;
+use softbuffer::{Context, Pixel, Surface};
 use std::f64::consts::PI;
 use std::num::NonZeroU32;
 use web_time::Instant;
@@ -15,7 +16,7 @@ fn main() {
     let event_loop = EventLoop::new().unwrap();
     let start = Instant::now();
 
-    let context = softbuffer::Context::new(event_loop.owned_display_handle()).unwrap();
+    let context = Context::new(event_loop.owned_display_handle()).unwrap();
 
     let app = util::WinitAppBuilder::with_init(
         |event_loop| {
@@ -26,9 +27,7 @@ fn main() {
 
             (window, old_size, frames)
         },
-        move |_elwft, (window, _old_size, _frames)| {
-            softbuffer::Surface::new(&context, window.clone()).unwrap()
-        },
+        move |_elwft, (window, _old_size, _frames)| Surface::new(&context, window.clone()).unwrap(),
     )
     .with_event_handler(move |state, surface, window_id, event, elwt| {
         let (window, old_size, frames) = state;
@@ -95,7 +94,7 @@ fn main() {
     util::run_app(event_loop, app);
 }
 
-fn pre_render_frames(width: u32, height: u32) -> Vec<Vec<u32>> {
+fn pre_render_frames(width: u32, height: u32) -> Vec<Vec<Pixel>> {
     let render = |frame_id| {
         let elapsed = ((frame_id as f64) / (60.0)) * 2.0 * PI;
 
@@ -104,14 +103,11 @@ fn pre_render_frames(width: u32, height: u32) -> Vec<Vec<u32>> {
             .map(|(x, y)| {
                 let y = (y as f64) / (height as f64);
                 let x = (x as f64) / (width as f64);
-                let red =
-                    ((((y + elapsed).sin() * 0.5 + 0.5) * 255.0).round() as u32).clamp(0, 255);
-                let green =
-                    ((((x + elapsed).sin() * 0.5 + 0.5) * 255.0).round() as u32).clamp(0, 255);
-                let blue =
-                    ((((y - elapsed).cos() * 0.5 + 0.5) * 255.0).round() as u32).clamp(0, 255);
-
-                blue | (green << 8) | (red << 16)
+                let r = ((((y + elapsed).sin() * 0.5 + 0.5) * 255.0).round() as u32).clamp(0, 255);
+                let g = ((((x + elapsed).sin() * 0.5 + 0.5) * 255.0).round() as u32).clamp(0, 255);
+                let b = ((((y - elapsed).cos() * 0.5 + 0.5) * 255.0).round() as u32).clamp(0, 255);
+
+                Pixel::new_rgb(r as u8, g as u8, b as u8)
             })
             .collect::<Vec<_>>()
     };

examples/drm.rs

@@ -17,7 +17,7 @@ mod imple {
     use drm::Device;
 
     use raw_window_handle::{DisplayHandle, DrmDisplayHandle, DrmWindowHandle, WindowHandle};
-    use softbuffer::{Context, Surface};
+    use softbuffer::{Context, Pixel, Surface};
 
     use std::num::NonZeroU32;
     use std::os::unix::io::{AsFd, AsRawFd, BorrowedFd};
@@ -161,16 +161,15 @@ mod imple {
         Ok(())
     }
 
-    fn draw_to_buffer(buf: &mut [u32], tick: usize) {
+    fn draw_to_buffer(buf: &mut [Pixel], tick: usize) {
         let scale = colorous::SINEBOW;
         let mut i = (tick as f64) / 20.0;
         while i > 1.0 {
             i -= 1.0;
         }
 
         let color = scale.eval_continuous(i);
-        let pixel = ((color.r as u32) << 16) | ((color.g as u32) << 8) | (color.b as u32);
-        buf.fill(pixel);
+        buf.fill(Pixel::new_rgb(color.r, color.g, color.b));
     }
 
     struct Card(std::fs::File);

examples/fruit.rs

@@ -1,4 +1,5 @@
 use image::GenericImageView;
+use softbuffer::{Context, Pixel, Surface};
 use std::num::NonZeroU32;
 use winit::event::{KeyEvent, WindowEvent};
 use winit::event_loop::{ControlFlow, EventLoop};
@@ -14,7 +15,7 @@ fn main() {
     let (width, height) = (fruit.width(), fruit.height());
 
     let event_loop = EventLoop::new().unwrap();
-    let context = softbuffer::Context::new(event_loop.owned_display_handle()).unwrap();
+    let context = Context::new(event_loop.owned_display_handle()).unwrap();
 
     let app = util::WinitAppBuilder::with_init(
         move |elwt| {
@@ -23,7 +24,7 @@ fn main() {
             })
         },
         move |_elwt, window| {
-            let mut surface = softbuffer::Surface::new(&context, window.clone()).unwrap();
+            let mut surface = Surface::new(&context, window.clone()).unwrap();
             // Intentionally only set the size of the surface once, at creation.
             // This is needed if the window chooses to ignore the size we passed in above, and for the
             // platforms softbuffer supports that don't yet extract the size from the window.
@@ -53,12 +54,8 @@ fn main() {
                 let mut buffer = surface.buffer_mut().unwrap();
                 let width = fruit.width();
                 for (x, y, pixel) in fruit.pixels() {
-                    let red = pixel.0[0] as u32;
-                    let green = pixel.0[1] as u32;
-                    let blue = pixel.0[2] as u32;
-
-                    let color = blue | (green << 8) | (red << 16);
-                    buffer.pixels()[(y * width + x) as usize] = color;
+                    let pixel = Pixel::new_rgb(pixel.0[0], pixel.0[1], pixel.0[2]);
+                    buffer.pixels()[(y * width + x) as usize] = pixel;
                 }
 
                 buffer.present().unwrap();

examples/libxcb.rs

@@ -17,6 +17,7 @@ mod example {
         DisplayHandle, RawDisplayHandle, RawWindowHandle, WindowHandle, XcbDisplayHandle,
         XcbWindowHandle,
     };
+    use softbuffer::{Context, Pixel, Surface};
     use std::{env, num::NonZeroU32, ptr::NonNull};
     use x11rb::{
         connection::Connection,
@@ -27,8 +28,6 @@ mod example {
         xcb_ffi::XCBConnection,
     };
 
-    const RED: u32 = 255 << 16;
-
     pub(crate) fn run() {
         // Create a new XCB connection
         let (conn, screen) = XCBConnection::connect(None).expect("Failed to connect to X server");
@@ -78,8 +77,8 @@ mod example {
             unsafe { DisplayHandle::borrow_raw(RawDisplayHandle::Xcb(display_handle)) };
         let window_handle =
             unsafe { WindowHandle::borrow_raw(RawWindowHandle::Xcb(window_handle)) };
-        let context = softbuffer::Context::new(display_handle).unwrap();
-        let mut surface = softbuffer::Surface::new(&context, window_handle).unwrap();
+        let context = Context::new(display_handle).unwrap();
+        let mut surface = Surface::new(&context, window_handle).unwrap();
 
         // Register an atom for closing the window.
         let wm_protocols_atom = conn
@@ -124,7 +123,7 @@ mod example {
                         )
                         .unwrap();
                     let mut buffer = surface.buffer_mut().unwrap();
-                    buffer.pixels().fill(RED);
+                    buffer.pixels().fill(Pixel::new_rgb(0xff, 0, 0));
                     buffer.present().unwrap();
                 }
                 Event::ConfigureNotify(configure_notify) => {

examples/raytracing/game.rs

@@ -2,7 +2,7 @@ use std::time::{Duration, Instant};
 
 use rand::rngs::SmallRng;
 use rand::{Rng, SeedableRng};
-use softbuffer::Buffer;
+use softbuffer::{Buffer, Pixel};
 
 use crate::camera::Camera;
 use crate::vec3::{Color, Point3, Vec3};
@@ -71,9 +71,9 @@ impl Game {
             dist_to_focus,
         );
 
-        let mut pixels = vec![0; width as usize * height as usize];
+        let mut pixels = vec![Pixel::default(); width as usize * height as usize];
 
-        let each_pixel = |rng: &mut SmallRng, i, pixel: &mut u32| {
+        let each_pixel = |rng: &mut SmallRng, i, pixel: &mut Pixel| {
             let y = i % (width as usize);
             let x = i / (width as usize);
             let mut pixel_color = Color::default();
@@ -125,7 +125,7 @@ impl Game {
             right: f32,
             top: f32,
             bottom: f32,
-            color: u32,
+            color: Pixel,
         }
 
         let width = buffer.width().get() as f32 / scale_factor;
@@ -136,14 +136,14 @@ impl Game {
                 right: width - 10.0,
                 top: height - 90.0,
                 bottom: height - 10.0,
-                color: 0x00eeaaaa,
+                color: Pixel::new_rgb(0xee, 0xaa, 0xaa),
             },
             Rect {
                 left: 30.0,
                 right: 70.0,
                 top: height - 70.0,
                 bottom: height - 30.0,
-                color: 0x00aaaaee,
+                color: Pixel::new_rgb(0xaa, 0xaa, 0xee),
             },
         ];
 
@@ -193,7 +193,7 @@ impl Game {
     }
 }
 
-fn color_to_pixel(pixel_color: Color, samples_per_pixel: i32) -> u32 {
+fn color_to_pixel(pixel_color: Color, samples_per_pixel: i32) -> Pixel {
     let mut r = pixel_color.x;
     let mut g = pixel_color.y;
     let mut b = pixel_color.z;
@@ -203,7 +203,9 @@ fn color_to_pixel(pixel_color: Color, samples_per_pixel: i32) -> u32 {
     g = f32::sqrt(scale * g);
     b = f32::sqrt(scale * b);
 
-    (256.0 * b.clamp(0.0, 0.999)) as u32
-        | (((256.0 * g.clamp(0.0, 0.999)) as u32) << 8)
-        | (((256.0 * r.clamp(0.0, 0.999)) as u32) << 16)
+    Pixel::new_rgb(
+        (256.0 * r.clamp(0.0, 0.999)) as u8,
+        (256.0 * g.clamp(0.0, 0.999)) as u8,
+        (256.0 * b.clamp(0.0, 0.999)) as u8,
+    )
 }

examples/raytracing/main.rs

@@ -3,6 +3,7 @@
 //! Note that this is quite slow, you probably don't want to do realtime CPU raytracing in practice.
 //!
 //! [Ray Tracing in One Weekend]: https://raytracing.github.io/books/RayTracingInOneWeekend.html
+use softbuffer::{Context, Surface};
 use std::num::NonZeroU32;
 use winit::event::{DeviceEvent, ElementState, KeyEvent, WindowEvent};
 use winit::event_loop::EventLoop;
@@ -25,12 +26,12 @@ fn main() {
     util::setup();
 
     let event_loop = EventLoop::new().unwrap();
-    let context = softbuffer::Context::new(event_loop.owned_display_handle()).unwrap();
+    let context = Context::new(event_loop.owned_display_handle()).unwrap();
 
     let app = util::WinitAppBuilder::with_init(
         |elwt| util::make_window(elwt, |w| w),
         move |_elwt, window| {
-            let mut surface = softbuffer::Surface::new(&context, window.clone()).unwrap();
+            let mut surface = Surface::new(&context, window.clone()).unwrap();
             surface
                 .resize(
                     NonZeroU32::new(window.inner_size().width).unwrap(),

examples/rectangle.rs

@@ -1,4 +1,4 @@
-use softbuffer::Buffer;
+use softbuffer::{Buffer, Context, Pixel, Surface};
 use std::num::NonZeroU32;
 use winit::event::{ElementState, KeyEvent, WindowEvent};
 use winit::event_loop::{ControlFlow, EventLoop};
@@ -11,12 +11,12 @@ fn redraw(buffer: &mut Buffer<'_>, flag: bool) {
     let height = buffer.height().get();
     for (x, y, pixel) in buffer.pixels_iter() {
         *pixel = if flag && x >= 100 && x < width - 100 && y >= 100 && y < height - 100 {
-            0x00ffffff
+            Pixel::new_rgb(0xff, 0xff, 0xff)
         } else {
             let red = (x & 0xff) ^ (y & 0xff);
             let green = (x & 0x7f) ^ (y & 0x7f);
             let blue = (x & 0x3f) ^ (y & 0x3f);
-            blue | (green << 8) | (red << 16)
+            Pixel::new_rgb(red as u8, green as u8, blue as u8)
         };
     }
 }
@@ -25,7 +25,7 @@ fn main() {
     util::setup();
 
     let event_loop = EventLoop::new().unwrap();
-    let context = softbuffer::Context::new(event_loop.owned_display_handle()).unwrap();
+    let context = Context::new(event_loop.owned_display_handle()).unwrap();
 
     let app = util::WinitAppBuilder::with_init(
         |elwt| {
@@ -37,7 +37,7 @@ fn main() {
 
             (window, flag)
         },
-        move |_elwt, (window, _flag)| softbuffer::Surface::new(&context, window.clone()).unwrap(),
+        move |_elwt, (window, _flag)| Surface::new(&context, window.clone()).unwrap(),
     )
     .with_event_handler(|state, surface, window_id, event, elwt| {
         let (window, flag) = state;