eframe: capture a screenshot using Frame::request_screenshot

CHANGELOG.md

@@ -27,6 +27,8 @@ NOTE: [`epaint`](crates/epaint/CHANGELOG.md), [`eframe`](crates/eframe/CHANGELOG
 * You can turn off the vertical line left of indented regions with `Visuals::indent_has_left_vline` ([#2636](https://github.com/emilk/egui/pull/2636)).
 * Add `Response.highlight` to highlight a widget ([#2632](https://github.com/emilk/egui/pull/2632)).
 * Add `Separator::grow` and `Separator::shrink` ([#2665](https://github.com/emilk/egui/pull/2665)).
+* 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`
+* 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`
 
 ### Changed 🔧
 * Improved plot grid appearance ([#2412](https://github.com/emilk/egui/pull/2412)).

crates/eframe/src/epi.rs

@@ -651,6 +651,9 @@ 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>,
+
+    #[cfg(not(target_arch = "wasm32"))]
+    pub(crate) screenshot: std::cell::Cell<Option<egui::ColorImage>>,
 }
 
 impl Frame {
@@ -668,10 +671,69 @@ impl Frame {
     }
 
     /// A place where you can store custom data in a way that persists when you restart the app.
+    #[cfg(not(target_arch = "wasm32"))]
     pub fn storage(&self) -> Option<&dyn Storage> {
         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:
+    /// ```
+    /// impl eframe::App for MyApp{
+    ///     fn update(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()
@@ -1037,5 +1099,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,
     }
 }