Allow accessing frame on immutable buffer (#288)

* Allow accessing frame on immutable buffer

* Rename `get_frame` to `get_frame_mut`

* Use `get_frame_mut` in examples

examples/conway/src/main.rs

@@ -44,7 +44,7 @@ fn main() -> Result<(), Error> {
     event_loop.run(move |event, _, control_flow| {
         // The one and only event that winit_input_helper doesn't have for us...
         if let Event::RedrawRequested(_) = event {
-            life.draw(pixels.get_frame());
+            life.draw(pixels.get_frame_mut());
             if pixels
                 .render()
                 .map_err(|e| error!("pixels.render() failed: {}", e))

examples/custom-shader/src/main.rs

@@ -50,7 +50,7 @@ fn main() -> Result<(), Error> {
     event_loop.run(move |event, _, control_flow| {
         // Draw the current frame
         if let Event::RedrawRequested(_) = event {
-            world.draw(pixels.get_frame());
+            world.draw(pixels.get_frame_mut());
 
             let render_result = pixels.render_with(|encoder, render_target, context| {
                 let noise_texture = noise_renderer.get_texture_view();

examples/imgui-winit/src/main.rs

@@ -59,7 +59,7 @@ fn main() -> Result<(), Error> {
         // Draw the current frame
         if let Event::RedrawRequested(_) = event {
             // Draw the world
-            world.draw(pixels.get_frame());
+            world.draw(pixels.get_frame_mut());
 
             // Prepare Dear ImGui
             gui.prepare(&window).expect("gui.prepare() failed");

examples/invaders/src/main.rs

@@ -139,7 +139,7 @@ fn main() -> Result<(), Error> {
         },
         move |g| {
             // Drawing
-            g.game.world.draw(g.game.pixels.get_frame());
+            g.game.world.draw(g.game.pixels.get_frame_mut());
             if let Err(e) = g.game.pixels.render() {
                 error!("pixels.render() failed: {}", e);
                 g.exit();

examples/minimal-egui/src/main.rs

@@ -83,7 +83,7 @@ fn main() -> Result<(), Error> {
             // Draw the current frame
             Event::RedrawRequested(_) => {
                 // Draw the world
-                world.draw(pixels.get_frame());
+                world.draw(pixels.get_frame_mut());
 
                 // Prepare egui
                 framework.prepare(&window);

examples/minimal-fltk/src/main.rs

@@ -50,7 +50,7 @@ fn main() -> Result<(), Error> {
         world.update();
 
         // Draw the current frame
-        world.draw(pixels.get_frame());
+        world.draw(pixels.get_frame_mut());
         if pixels
             .render()
             .map_err(|e| error!("pixels.render() failed: {}", e))

examples/minimal-sdl2/src/main.rs

@@ -61,7 +61,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         world.update();
 
         // Draw the current frame
-        world.draw(pixels.get_frame());
+        world.draw(pixels.get_frame_mut());
         pixels.render()?;
     }
 

examples/minimal-web/src/main.rs

@@ -110,7 +110,7 @@ async fn run() {
     event_loop.run(move |event, _, control_flow| {
         // Draw the current frame
         if let Event::RedrawRequested(_) = event {
-            world.draw(pixels.get_frame());
+            world.draw(pixels.get_frame_mut());
             if pixels
                 .render()
                 .map_err(|e| error!("pixels.render() failed: {}", e))

examples/minimal-winit/src/main.rs

@@ -45,7 +45,7 @@ fn main() -> Result<(), Error> {
     event_loop.run(move |event, _, control_flow| {
         // Draw the current frame
         if let Event::RedrawRequested(_) = event {
-            world.draw(pixels.get_frame());
+            world.draw(pixels.get_frame_mut());
             if pixels
                 .render()
                 .map_err(|e| error!("pixels.render() failed: {}", e))

examples/raqote-winit/src/main.rs

@@ -46,7 +46,7 @@ fn main() -> Result<(), Error> {
         // Draw the current frame
         if let Event::RedrawRequested(_) = event {
             for (dst, &src) in pixels
-                .get_frame()
+                .get_frame_mut()
                 .chunks_exact_mut(4)
                 .zip(shapes.get_frame().iter())
             {

src/lib.rs

@@ -354,7 +354,7 @@ impl Pixels {
     /// let mut pixels = Pixels::new(320, 240, surface_texture)?;
     ///
     /// // Clear the pixel buffer
-    /// let frame = pixels.get_frame();
+    /// let frame = pixels.get_frame_mut();
     /// for pixel in frame.chunks_exact_mut(4) {
     ///     pixel[0] = 0x00; // R
     ///     pixel[1] = 0x00; // G
@@ -399,7 +399,7 @@ impl Pixels {
     /// let mut pixels = Pixels::new(320, 240, surface_texture)?;
     ///
     /// // Clear the pixel buffer
-    /// let frame = pixels.get_frame();
+    /// let frame = pixels.get_frame_mut();
     /// for pixel in frame.chunks_exact_mut(4) {
     ///     pixel[0] = 0x00; // R
     ///     pixel[1] = 0x00; // G
@@ -493,10 +493,18 @@ impl Pixels {
 
     /// Get a mutable byte slice for the pixel buffer. The buffer is _not_ cleared for you; it will
     /// retain the previous frame's contents until you clear it yourself.
-    pub fn get_frame(&mut self) -> &mut [u8] {
+    pub fn get_frame_mut(&mut self) -> &mut [u8] {
         &mut self.pixels
     }
 
+    /// Get an immutable byte slice for the pixel buffer.
+    ///
+    /// This may be useful for operations that must sample the buffer, such as blending pixel
+    /// colours directly into it.
+    pub fn get_frame(&self) -> &[u8] {
+        &self.pixels
+    }
+
     /// Calculate the pixel location from a physical location on the window,
     /// dealing with window resizing, scaling, and margins. Takes a physical
     /// position (x, y) within the window, and returns a pixel position (x, y).