Rename buffer_mut -> next_buffer (#337)

There isn't a use-case for an immutable `buffer()` method, so the "mut"
suffix is kinda unnecessary, and "next" a bit more clearly communicates
that `softbuffer::Surface` potentially contains more than one buffer.

Author: madsmtm

CHANGELOG.md

@@ -5,6 +5,7 @@
 - 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.
 - Added `Buffer::byte_stride()` for pixel buffers whose rows are aligned and may contain padding bytes at the end. Prefer to use the above helpers instead of accessing pixel data directly.
+- Renamed `Surface::buffer_mut()` to `Surface::next_buffer()`.
 - **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 generic type parameters `D` and `W` from `Buffer<'_>` struct.

Cargo.toml

@@ -167,7 +167,7 @@ name = "winit_multithread_android"
 crate-type = ["cdylib"]
 
 [[bench]]
-name = "buffer_mut"
+name = "buffer"
 harness = false
 
 [dev-dependencies]

README.md

@@ -11,7 +11,7 @@ To use Softbuffer, first create a window using `winit`, `sdl3`, or any other cra
 [`raw_window_handle::HasWindowHandle`].
 
 Next, you create a [`Context`] and [`Surface`] from that window, and can now call
-[`Surface::buffer_mut()`] to get a [`Buffer`] that you can draw into. Once you're done drawing, call
+[`Surface::next_buffer()`] to get a [`Buffer`] that you can draw into. Once you're done drawing, call
 [`Buffer::present()`] to show the buffer on the window.
 
 Note that Softbuffer only provides the `&mut [...]` buffer, it does not provide any rendering
@@ -117,7 +117,7 @@ fn main() {
                     )
                     .unwrap();
 
-                let mut buffer = surface.buffer_mut().unwrap();
+                let mut buffer = surface.next_buffer().unwrap();
                 for (x, y, pixel) in buffer.pixels_iter() {
                     let red = (x % 255) as u8;
                     let green = (y % 255) as u8;

benches/buffer_mut.rs benches/buffer.rsbenches/buffer_mut.rs renamed to benches/buffer.rs

@@ -5,7 +5,7 @@
     all(target_vendor = "apple", not(target_os = "macos")),
     target_os = "redox"
 )))]
-fn buffer_mut(c: &mut criterion::Criterion) {
+fn buffer(c: &mut criterion::Criterion) {
     use criterion::black_box;
     use softbuffer::{Context, Pixel, Surface};
     use std::num::NonZeroU32;
@@ -34,30 +34,30 @@ fn buffer_mut(c: &mut criterion::Criterion) {
                 )
                 .unwrap();
 
-            c.bench_function("buffer_mut()", |b| {
+            c.bench_function("next_buffer()", |b| {
                 b.iter(|| {
-                    black_box(surface.buffer_mut().unwrap());
+                    black_box(surface.next_buffer().unwrap());
                 });
             });
 
             c.bench_function("pixels()", |b| {
-                let mut buffer = surface.buffer_mut().unwrap();
+                let mut buffer = surface.next_buffer().unwrap();
                 b.iter(|| {
                     let pixels: &mut [Pixel] = buffer.pixels();
                     black_box(pixels);
                 });
             });
 
             c.bench_function("fill pixels", |b| {
-                let mut buffer = surface.buffer_mut().unwrap();
+                let mut buffer = surface.next_buffer().unwrap();
                 b.iter(|| {
                     let buffer = black_box(&mut buffer);
                     buffer.pixels().fill(Pixel::default());
                 });
             });
 
             c.bench_function("render pixels_iter", |b| {
-                let mut buffer = surface.buffer_mut().unwrap();
+                let mut buffer = surface.next_buffer().unwrap();
                 b.iter(|| {
                     let buffer = black_box(&mut buffer);
                     for (x, y, pixel) in buffer.pixels_iter() {
@@ -78,7 +78,7 @@ fn buffer_mut(c: &mut criterion::Criterion) {
     all(target_vendor = "apple", not(target_os = "macos")),
     target_os = "redox"
 )))]
-criterion::criterion_group!(benches, buffer_mut);
+criterion::criterion_group!(benches, buffer);
 
 #[cfg(not(any(
     target_family = "wasm",

examples/animation.rs

@@ -59,7 +59,7 @@ fn main() {
 
                 let elapsed = start.elapsed().as_secs_f64() % 1.0;
 
-                let mut buffer = surface.buffer_mut().unwrap();
+                let mut buffer = surface.next_buffer().unwrap();
 
                 let size = (buffer.width().get(), buffer.height().get());
                 if size != *old_size {

examples/drm.rs

@@ -127,7 +127,7 @@ mod imple {
             tracing::info!("Drawing tick {tick}");
 
             // Start drawing.
-            let mut buffer = surface.buffer_mut()?;
+            let mut buffer = surface.next_buffer()?;
             draw_to_buffer(buffer.pixels(), tick);
             buffer.present()?;
 

examples/fruit.rs

@@ -51,7 +51,7 @@ fn main() {
                     return;
                 };
 
-                let mut buffer = surface.buffer_mut().unwrap();
+                let mut buffer = surface.next_buffer().unwrap();
                 let stride = buffer.byte_stride().get() / 4;
                 for (x, y, pixel) in fruit.pixels() {
                     let pixel = Pixel::new_rgb(pixel.0[0], pixel.0[1], pixel.0[2]);

examples/libxcb.rs

@@ -122,7 +122,7 @@ mod example {
                             NonZeroU32::new(height.into()).unwrap(),
                         )
                         .unwrap();
-                    let mut buffer = surface.buffer_mut().unwrap();
+                    let mut buffer = surface.next_buffer().unwrap();
                     buffer.pixels().fill(Pixel::new_rgb(0xff, 0, 0));
                     buffer.present().unwrap();
                 }

examples/raytracing/main.rs

@@ -68,7 +68,7 @@ fn main() {
 
                 game.update();
 
-                let mut buffer = surface.buffer_mut().unwrap();
+                let mut buffer = surface.next_buffer().unwrap();
                 game.draw(&mut buffer, window.scale_factor() as f32);
                 buffer.present().unwrap();
                 window.request_redraw();

examples/rectangle.rs

@@ -68,7 +68,7 @@ fn main() {
                     return;
                 };
                 // Draw something in the window
-                let mut buffer = surface.buffer_mut().unwrap();
+                let mut buffer = surface.next_buffer().unwrap();
                 redraw(&mut buffer, *flag);
                 buffer.present().unwrap();
             }