eframe: capture a screenshot using Frame::request_screenshot

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>

crates/eframe/CHANGELOG.md

@@ -5,6 +5,7 @@ NOTE: [`egui-winit`](../egui-winit/CHANGELOG.md), [`egui_glium`](../egui_glium/C
 
 
 ## Unreleased
+* Add `Frame::request_screenshot` and `Frame::screenshot` to communicate to the backend that a screenshot of the current frame should be exposed by `Frame` during `App::post_rendering` ([#2676](https://github.com/emilk/egui/pull/2676))
 
 
 ## 0.21.3 - 2023-02-15

crates/eframe/src/epi.rs

@@ -197,7 +197,7 @@ pub trait App {
 
     /// Called each time after the rendering the UI.
     ///
-    /// Can be used to access pixel data with `get_pixels`
+    /// Can be used to access pixel data with [`Frame::screenshot`]
     fn post_rendering(&mut self, _window_size_px: [u32; 2], _frame: &Frame) {}
 }
 
@@ -674,6 +674,11 @@ pub struct Frame {
     /// Can be used to manage GPU resources for custom rendering with WGPU using [`egui::PaintCallback`]s.
     #[cfg(feature = "wgpu")]
     pub(crate) wgpu_render_state: Option<egui_wgpu::RenderState>,
+
+    /// If [`Frame::request_screenshot`] was called during a frame, this field will store the screenshot
+    /// such that it can be retrieved during [`App::post_rendering`] with [`Frame::screenshot`]
+    #[cfg(not(target_arch = "wasm32"))]
+    pub(crate) screenshot: std::cell::Cell<Option<egui::ColorImage>>,
 }
 
 impl Frame {
@@ -695,6 +700,66 @@ impl Frame {
         self.storage.as_deref()
     }
 
+    /// Request the current frame's pixel data. Needs to be retrieved by calling [`Frame::screenshot`]
+    /// during [`App::post_rendering`].
+    #[cfg(not(target_arch = "wasm32"))]
+    pub fn request_screenshot(&mut self) {
+        self.output.screenshot_requested = true;
+    }
+
+    /// Cancel a request made with [`Frame::request_screenshot`].
+    #[cfg(not(target_arch = "wasm32"))]
+    pub fn cancel_screenshot_request(&mut self) {
+        self.output.screenshot_requested = false;
+    }
+
+    /// During [`App::post_rendering`], use this to retrieve the pixel data that was requested during
+    /// [`App::update`] via [`Frame::request_screenshot`].
+    ///
+    /// Returns None if:
+    /// * Called in [`App::update`]
+    /// * [`Frame::request_screenshot`] wasn't called on this frame during [`App::update`]
+    /// * The rendering backend doesn't support this feature (yet). Currently implemented for wgpu and glow, but not with wasm as target.
+    /// * Retrieving the data was unsuccessful in some way.
+    ///
+    /// See also [`egui::ColorImage::region`]
+    ///
+    /// ## Example generating a capture of everything within a square of 100 pixels located at the top left of the app and saving it with the [`image`](crates.io/crates/image) crate:
+    /// ```
+    /// struct MyApp;
+    ///
+    /// impl eframe::App for MyApp {
+    ///     fn update(&mut self, ctx: &egui::Context, frame: &mut eframe::Frame) {
+    ///         // In real code the app would render something here
+    ///         frame.request_screenshot();
+    ///         // Things that are added to the frame after the call to
+    ///         // request_screenshot() will still be included.
+    ///     }
+    ///
+    ///     fn post_rendering(&mut self, _window_size: [u32; 2], frame: &eframe::Frame) {
+    ///         if let Some(screenshot) = frame.screenshot() {
+    ///             let pixels_per_point = frame.info().native_pixels_per_point;
+    ///             let region = egui::Rect::from_two_pos(
+    ///                 egui::Pos2::ZERO,
+    ///                 egui::Pos2{ x: 100., y: 100. },
+    ///             );
+    ///             let top_left_corner = screenshot.region(&region, pixels_per_point);
+    ///             image::save_buffer(
+    ///                 "top_left.png",
+    ///                 top_left_corner.as_raw(),
+    ///                 top_left_corner.width() as u32,
+    ///                 top_left_corner.height() as u32,
+    ///                 image::ColorType::Rgba8,
+    ///             ).unwrap();
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    #[cfg(not(target_arch = "wasm32"))]
+    pub fn screenshot(&self) -> Option<egui::ColorImage> {
+        self.screenshot.take()
+    }
+
     /// A place where you can store custom data in a way that persists when you restart the app.
     pub fn storage_mut(&mut self) -> Option<&mut (dyn Storage + 'static)> {
         self.storage.as_deref_mut()
@@ -1061,5 +1126,8 @@ pub(crate) mod backend {
         /// Set to some bool to maximize or unmaximize window.
         #[cfg(not(target_arch = "wasm32"))]
         pub maximized: Option<bool>,
+
+        #[cfg(not(target_arch = "wasm32"))]
+        pub screenshot_requested: bool,
     }
 }

crates/eframe/src/native/epi_integration.rs

@@ -128,7 +128,7 @@ pub fn window_builder<E>(
         // Restore pos/size from previous session
         window_settings.clamp_to_sane_values(largest_monitor_point_size(event_loop));
         #[cfg(windows)]
-        window_settings.clamp_window_to_sane_position(&event_loop);
+        window_settings.clamp_window_to_sane_position(event_loop);
         window_builder = window_settings.initialize_window(window_builder);
         window_settings.inner_size_points()
     } else {
@@ -228,6 +228,7 @@ pub fn handle_app_output(
         window_pos,
         visible: _, // handled in post_present
         always_on_top,
+        screenshot_requested: _, // handled by the rendering backend,
         minimized,
         maximized,
     } = app_output;
@@ -349,6 +350,7 @@ impl EpiIntegration {
             gl,
             #[cfg(feature = "wgpu")]
             wgpu_render_state,
+            screenshot: std::cell::Cell::new(None),
         };
 
         let mut egui_winit = egui_winit::State::new(event_loop);
@@ -467,6 +469,7 @@ impl EpiIntegration {
                 tracing::debug!("App::on_close_event returned {}", self.close);
             }
             self.frame.output.visible = app_output.visible; // this is handled by post_present
+            self.frame.output.screenshot_requested = app_output.screenshot_requested;
             handle_app_output(
                 window,
                 self.egui_ctx.pixels_per_point(),

crates/eframe/src/native/run.rs

@@ -803,6 +803,14 @@ mod glow_integration {
                     &textures_delta,
                 );
 
+                let screenshot_requested = &mut integration.frame.output.screenshot_requested;
+
+                if *screenshot_requested {
+                    *screenshot_requested = false;
+                    let screenshot = painter.read_screen_rgba(screen_size_in_pixels);
+                    integration.frame.screenshot.set(Some(screenshot));
+                }
+
                 integration.post_rendering(app.as_mut(), window);
 
                 {
@@ -820,11 +828,15 @@ mod glow_integration {
                             path.ends_with(".png"),
                             "Expected EFRAME_SCREENSHOT_TO to end with '.png', got {path:?}"
                         );
-                        let [w, h] = screen_size_in_pixels;
-                        let pixels = painter.read_screen_rgba(screen_size_in_pixels);
-                        let image = image::RgbaImage::from_vec(w, h, pixels).unwrap();
-                        let image = image::imageops::flip_vertical(&image);
-                        image.save(&path).unwrap_or_else(|err| {
+                        let screenshot = painter.read_screen_rgba(screen_size_in_pixels);
+                        image::save_buffer(
+                            &path,
+                            screenshot.as_raw(),
+                            screenshot.width() as u32,
+                            screenshot.height() as u32,
+                            image::ColorType::Rgba8,
+                        )
+                        .unwrap_or_else(|err| {
                             panic!("Failed to save screenshot to {path:?}: {err}");
                         });
                         eprintln!("Screenshot saved to {path:?}.");
@@ -1229,12 +1241,17 @@ mod wgpu_integration {
                     integration.egui_ctx.tessellate(shapes)
                 };
 
-                painter.paint_and_update_textures(
+                let screenshot_requested = &mut integration.frame.output.screenshot_requested;
+
+                let screenshot = painter.paint_and_update_textures(
                     integration.egui_ctx.pixels_per_point(),
                     app.clear_color(&integration.egui_ctx.style().visuals),
                     &clipped_primitives,
                     &textures_delta,
+                    *screenshot_requested,
                 );
+                *screenshot_requested = false;
+                integration.frame.screenshot.set(screenshot);
 
                 integration.post_rendering(app.as_mut(), window);
                 integration.post_present(window);

crates/egui-wgpu/CHANGELOG.md

@@ -3,6 +3,7 @@ All notable changes to the `egui-wgpu` integration will be noted in this file.
 
 
 ## Unreleased
+* Add `read_screan_rgba` to the egui-wgpu `Painter`, to allow for capturing the current frame when using wgpu. Used in conjuction with `Frame::request_screenshot`. ([#2676](https://github.com/emilk/egui/pull/2676))
 
 
 ## 0.21.0 - 2023-02-08
@@ -12,7 +13,6 @@ All notable changes to the `egui-wgpu` integration will be noted in this file.
 * `egui-wgpu` now only depends on `epaint` instead of the entire `egui` ([#2438](https://github.com/emilk/egui/pull/2438)).
 * `winit::Painter` now supports transparent backbuffer ([#2684](https://github.com/emilk/egui/pull/2684)).
 
-
 ## 0.20.0 - 2022-12-08 - web support
 * Renamed `RenderPass` to `Renderer`.
 * Renamed `RenderPass::execute` to `RenderPass::render`.