eframe: capture a screenshot using Frame::request_screenshot

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

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,
     }
 }