docs(unity): Describe how screenshots get captured

docs/platforms/unity/configuration/options/index.mdx

@@ -94,14 +94,20 @@ Grouping in Sentry is different for events with stack traces and without. As a r
 
 <SdkOption name="AttachScreenshot" type="bool" defaultValue="false">
 
-Takes a screenshot of the application when an error happens and includes it as an attachment.
+Attaches a screenshot of the game to events, such as errors and messages, and sends it in the same envelope as the event. Screenshots aren't attached in the Editor, in batch mode, or on WebGL.
 Learn more about enriching events with screenshots in our <PlatformLink to="/enriching-events/screenshots/">Screenshots documentation</PlatformLink>.
 
 </SdkOption>
 
 <SdkOption name="ScreenshotQuality" type="enum" defaultValue="high">
 
-The quality of the attached screenshot. It can be set to `full`, `high`, `medium` or `low`.
+The resolution of the attached screenshot. `Full` keeps the game's resolution, while `High`, `Medium`, and `Low` scale it down so that its longest side is at most 1920, 1280, or 854 pixels.
+
+</SdkOption>
+
+<SdkOption name="ScreenshotCompression" type="int" defaultValue="75">
+
+The JPEG quality of the attached screenshot, from 1 to 100. Higher values result in better quality and larger files.
 
 </SdkOption>
 
@@ -191,7 +197,13 @@ By the time <PlatformIdentifier name="SetBeforeSendTransaction" /> is executed,
 
 <SdkOption name="SetBeforeCaptureScreenshot" type="function">
 
-A callback function that controls screenshot capture behavior. Return `false` to prevent a screenshot from being captured for a specific event. This allows for fine-grained control over when screenshots are included with error reports.
+A callback function that controls screenshot capture behavior. Return `false` to prevent a screenshot from being attached to a specific event. It can run on a background thread and runs before <PlatformIdentifier name="SetBeforeSend" /> and sampling. Learn more in our <PlatformLink to="/enriching-events/screenshots/">Screenshots documentation</PlatformLink>.
+
+</SdkOption>
+
+<SdkOption name="SetBeforeSendScreenshot" type="function">
+
+A callback function that receives the screenshot as a `Texture2D` before it gets compressed, along with the event it belongs to. Modify or replace the texture and return it, or return `null` to discard the screenshot. Setting it makes the SDK read and compress screenshots on the main thread. Learn more in our <PlatformLink to="/enriching-events/screenshots/">Screenshots documentation</PlatformLink>.
 
 </SdkOption>
 

docs/platforms/unity/enriching-events/screenshots/index.mdx

@@ -22,19 +22,76 @@ Or, like so, if you're [configuring things programmatically](/platforms/unity/co
 options.AttachScreenshot = true;
 ```
 
-## Screenshot capture mechanism
+Screenshots aren't attached in the Editor, in batch mode, or on WebGL.
+
+## Screenshot Capture Mechanism
 
 Since the Unity SDK internally consists of multiple SDKs, the mechanism with which a screenshot gets captured depends on where the error originates.
 
-- C# errors from within your game will be captured through Unity's built-in [ScreenCapture](https://docs.unity3d.com/ScriptReference/ScreenCapture.html). This means that screenshots only contain things visible within your game. Overlays on top of your game will not be visible.
-- Native errors get captured by their respective SDK. If you're using a native plugin to display an overlay and an error occurs then that SDK will try to capture a screenshot that contains the overlay.
+### C# Errors
+
+Events captured by the C# SDK, such as exceptions, messages, and errors logged through `Debug.LogError`, get a screenshot. Transactions and user feedback don't. The SDK captures the screenshot through Unity's built-in [ScreenCapture](https://docs.unity3d.com/ScriptReference/ScreenCapture.html), so it only contains what your game renders. Overlays on top of your game aren't visible.
+
+The SDK takes the screenshot at the end of the frame, so it shows the fully rendered frame. Events captured on background threads get a screenshot as well, taken at the end of a following frame. Events captured while a screenshot is still being taken, for example several errors within the same frame, share it. Events that get dropped by <PlatformIdentifier name="SetBeforeSend" /> or sampling don't trigger a screenshot.
+
+The screenshot gets scaled down according to `ScreenshotQuality` and compressed to JPEG according to `ScreenshotCompression`, and is attached as `screenshot.jpg`. It's sent in the same envelope as the event it belongs to. If the event gets dropped, for example because of rate limiting, its screenshot gets dropped along with it.
+
+To keep the cost of an error low, the main thread only issues the capture to the GPU. Where the device supports [asynchronous GPU readback](https://docs.unity3d.com/ScriptReference/SystemInfo-supportsAsyncGPUReadback.html), the SDK reads the screenshot back [asynchronously](https://docs.unity3d.com/ScriptReference/Rendering.AsyncGPUReadback.html) and compresses it on a background thread. Otherwise, or when <PlatformIdentifier name="SetBeforeSendScreenshot" /> is set, it reads and compresses the screenshot on the main thread. On Nintendo Switch, screenshots are always read on the main thread.
+
+If the screenshot can't be taken, for example because the main thread doesn't reach the end of the frame within one second while it's blocked or the app is in the background, the event gets sent without it.
+
+### Native Errors
+
+| Platform              | Screenshot for native errors and crashes                                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| iOS                   | Captured by sentry-cocoa, only with <PlatformLink to="/native-support/#build-time-initialization">build time initialization</PlatformLink> |
+| Windows               | Captured by sentry-native when the game crashes                                                                                            |
+| Android, macOS, Linux | None                                                                                                                                       |
+
+These screenshots are taken by the native SDK, so they include overlays, and <PlatformIdentifier name="SetBeforeCaptureScreenshot" /> and <PlatformIdentifier name="SetBeforeSendScreenshot" /> don't apply to them.
 
 <Alert>
 
 Screenshots might contain PII of your app. For example, if your game has a registration form and an error happens while the form is being displayed.
 
 </Alert>
 
+## Customize Screenshot Capturing
+
+To decide whether an event gets a screenshot, use <PlatformIdentifier name="SetBeforeCaptureScreenshot" />. It runs on the thread that captured the event, which can be a background thread, so don't call the Unity API from within it:
+
+```csharp
+options.SetBeforeCaptureScreenshot(sentryEvent =>
+{
+    // Don't attach screenshots while the payment screen is open
+    return !PaymentScreen.IsOpen;
+});
+```
+
+## Modifying or Discarding Screenshots
+
+To edit a screenshot before it's sent, for example to black out sensitive areas, or to discard it, use <PlatformIdentifier name="SetBeforeSendScreenshot" />:
+
+```csharp
+options.SetBeforeSendScreenshot((screenshot, sentryEvent) =>
+{
+    // Return null to discard the screenshot instead
+    return screenshot;
+});
+```
+
+The callback runs once per screenshot, and events that share a screenshot also share the result.
+
+<Alert level="warning">
+
+Since <PlatformIdentifier name="SetBeforeSendScreenshot" /> hands out the screenshot as a `Texture2D`, setting it makes the SDK read and compress every screenshot on the main thread, which stalls your game.
+
+</Alert>
+
+## User Feedback
+
+Automatic screenshots don't get attached to user feedback. To attach one, pass `addScreenshot: true` to `SentrySdk.CaptureFeedback`. The SDK takes the screenshot right away, so call it from the main thread, ideally after `WaitForEndOfFrame`, so the frame is fully rendered. Feedback screenshots don't depend on <PlatformIdentifier name="AttachScreenshot" />, aren't passed to the screenshot callbacks, and are also taken in the Editor. Learn more in <PlatformLink to="/user-feedback/">User Feedback</PlatformLink>.
+
 ## Viewing Screenshots
 
 If one is available, you'll see a thumbnail of the screenshot when you click on a specific issue from the [**Issues**](https://demo.sentry.io/issues/) page.

docs/platforms/unity/troubleshooting/index.mdx

@@ -96,4 +96,4 @@ Outside of this helper function, Sentry is unaware of any **real world** crash t
 
 ### Screenshot contain artifacts
 
-The screenshot capture relies on Unity's `ScreenCapture.CaptureScreenshotIntoRenderTexture` function. When capturing errors in the Editor, this might lead to artifacts or scaling issues in the captured screenshot.
+The screenshot capture relies on Unity's `ScreenCapture.CaptureScreenshotIntoRenderTexture` function. In the Editor, the SDK only takes screenshots for user feedback, and these can contain artifacts or scaling issues.

docs/platforms/unity/user-feedback/index.mdx

@@ -27,7 +27,7 @@ The Unity SDK includes a ready-to-use prefab that provides a complete user feedb
   - Name (optional)
   - Email (optional)
   - Message/feedback (required)
-  - Screenshot (optional, taken automatically)
+  - Screenshot (optional, included by default and the user can uncheck it; the form hides itself before the screenshot gets taken)
 
 ### Adding the Prefab to Your Scene