Add live device screen streaming to the Screen Capture window

com.unity.mobile.android-logcat/CHANGELOG.md

@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Changes & Improvements:
  - Unity 6.0 or later is required.
+ - Screenshots are now saved to `Library/AndroidLogcat/Screenshots` as `<device_id>_<number>.png`. Previously each capture overwrote a single file in the project's `Temp` folder, so earlier screenshots were lost.
+ - The Screen Capture window can be opened from **Window** > **Analysis** > **Android Screen Capture**, as well as from the Android Logcat window's **Tools** menu.
+ - The Screen Capture window now lists every saved screenshot. Click a row or use the Up and Down keys to cycle through them, or the cross next to a row to delete that screenshot.
+ - Ctrl+Shift+S, or Cmd+Shift+S on macOS, captures a screenshot while the Screen Capture window has focus. It appears in Edit > Shortcuts under "Android Logcat" and can be rebound there.
+ - Capturing a screenshot also writes a `.json` file beside it, recording the device it was captured from and when.
+ - The details beside a selected screenshot show the device, its Android version and display size, along with the image size, the file size and when it was captured. The device details read `Undefined` for a screenshot saved without them.
+ - The screenshot and the live view can be zoomed with Ctrl+Wheel (Cmd+Wheel on macOS), and the zoomed image moved with a Ctrl+middle mouse button drag or with the scrollbars that appear.
+ - The device screen can be viewed live from the Screen Capture window: select the "Live" row at the top of the screenshot list. Clicks, drags, the scroll wheel and typing are sent to the device as touch, scroll and key events, and Ctrl+A, Ctrl+C and Ctrl+V (Cmd on macOS) select all, copy and paste on the device using its own clipboard, and Back / Home / Overview buttons sit beside the image with the stream details. 
  - Tools->Open Terminal is now supported on Linux Editor.
  - Fixed Tools->Open Terminal not opening a window on Windows Editor when running on CoreCLR.
 

com.unity.mobile.android-logcat/Documentation~/TableOfContents.md

@@ -13,6 +13,7 @@
     * [Device Screen Capture window reference](screen-capture-window-reference.md)
     * [Capture a screenshot](screen-capture-screenshot.md)
     * [Capture a video](screen-capture-video.md)
+    * [View the device screen live](screen-capture-live-stream.md)
   * [Stacktace Utility](stacktrace-utility.md)
     * [Stacktrace Utility window reference](stacktrace-utility-window-reference.md)
     * [Set up Stacktrace Utility](stacktrace-utility-set-up.md)

com.unity.mobile.android-logcat/Documentation~/android-logcat-settings.md

@@ -7,6 +7,7 @@ To open the Android Logcat Settings window in the Unity Editor, go to **Edit** >
 * [Message Colors](#message-colors)
 * [Memory Window](#memory-window)
 * [Packages](#packages)
+* [Live Stream](#live-stream)
 * [Stacktrace Regex](#stacktrace-regex)
 * [Symbol Extensions](#symbol-extensions)
 
@@ -48,6 +49,32 @@ Use the **Request Interval ms** setting to specify a time interval to request me
 
 Use the **Max Exited Packages** setting to specify the maximum number for the applications selected in the Package Selector that are now closed. This allows you to restrict the number of entries in the Package Selector dropdown for closed applications to prevent overpopulating the dropdown.
 
+## Capture Settings
+
+Use **Captures Folder** to choose where captures are written. Screenshots are written straight into it, under the name of the device they came from. The note underneath the field spells out where that is at the moment, which a relative path does not show on its own.
+
+A relative path starts at your project folder, which is how the default `Library/AndroidLogcat/Screenshots` is written, and follows the project when it moves or is opened on another machine. An absolute path is used as it stands, for captures kept outside the project.
+
+Select **Browse...** to pick a folder. A folder inside the project is stored relative to it, and one outside it is stored as an absolute path.
+
+The default, `Library/AndroidLogcat/Screenshots`, is local to your machine and is not part of a build, and Unity deletes `Library` from time to time, so choose a folder of your own for captures you want to keep.
+
+Changing the folder takes effect immediately. Captures already written stay where they are, and the [Capture list](screen-capture-window-reference.md#capture-list) shows what is in the new folder.
+
+### Live Stream
+
+Use the **Live Stream** settings to control the [live view of the device's screen](screen-capture-live-stream.md). Streaming a display uses the device's CPU to compress each frame and the connection to your computer to carry it, so these settings trade image quality for both.
+
+|**Setting**|**Description**|
+|---|---|
+|**Max Size**|Specifies the longest side of the streamed image in pixels, between 256 and 2048. The device's display is scaled down to fit. The default value is 1024.|
+|**JPEG Quality**|Specifies the quality of each streamed frame, between 1 and 100. Lower values produce smaller frames and use less bandwidth. The default value is 70.|
+|**Max Frame Rate**|Specifies the highest number of frames per second the device sends, between 1 and 120. The device only sends a frame when its screen changes, so this is a limit rather than a rate. The default value is 30.|
+
+These settings apply when a stream starts. To apply them to a stream that is already running, turn **Live** off and on again in the [Device Screen Capture window](screen-capture-window-reference.md#capture-list).
+
+Use the **Reset** button in this section to restore the three Live Stream settings without changing any other setting.
+
 ## Stacktrace Regex
 
 ![Stacktrace Regex](images/logcat-settings-stacktrace-regex.png)
@@ -66,4 +93,4 @@ For more information, refer to [configure stacktrace regular expressions](stackt
 
 Use the **Symbol Extensions** setting to specify file extensions which are appended to symbol file names during stacktrace resolving.
 
-For example, if the symbol file name is `libunity` and the specified symbol extensions are `.so.sym`, `.so.dbg`, the Stacktrace Utility tool looks for `libunity.so.sym` and `libunity.so.dbg` symbols.
+For example, if the symbol file name is `libunity` and the specified symbol extensions are `.so.sym`, `.so.dbg`, the Stacktrace Utility tool looks for `libunity.so.sym` and `libunity.so.dbg` symbols.

com.unity.mobile.android-logcat/Documentation~/screen-capture-live-stream.md

@@ -0,0 +1,52 @@
+# View the device screen live
+
+This page explains how to use the [Screen Capture tool](screen-capture.md) to view the screen of the connected device as it changes, and how to control the device from the Unity Editor.
+
+The live view mirrors the device's display into the Unity Editor. Unlike a screenshot or a video, there is nothing to save: the view is live and stops when you select something else.
+
+## View the screen
+
+1. Open the [Device Screen Capture window](screen-capture-window-reference.md).
+2. In the [Toolbar](screen-capture-window-reference.md#toolbar), use **Device Selector** to specify the device to view.
+3. In the [Capture list](screen-capture-window-reference.md#capture-list), select the **Live** row. The Screen Capture tool starts streaming and displays the device's screen in the [Capture preview](screen-capture-window-reference.md#capture-preview).
+
+The stream stops when you select another row in the list, close the window, or disconnect the device. Selecting a different device restarts the stream against the newly selected one.
+
+The device only sends a frame when its screen changes, so **Frame Rate** in the [Live view details](screen-capture-window-reference.md#live-view-details) drops to almost nothing while the device shows a still screen. This is expected: the last frame stays on display.
+
+If the stream stops on its own, for example because the device restarted, select **Reconnect** in the live view, or turn **Live** off and on again.
+
+## Control the device
+
+While the live view is streaming, the Screen Capture tool sends your input to the device. **Input** in the [Live view details](screen-capture-window-reference.md#live-view-details) shows whether the device accepts it.
+
+| **Input**                                  | **Result on the device**                                     |
+| ------------------------------------------ | ------------------------------------------------------------ |
+| Click or drag the image                    | A tap or a swipe at the same place on the device's screen.    |
+| Scroll the wheel over the image            | Scrolls whatever is under the pointer.                        |
+| Click the image, then type                 | Sends the keys you type, including Backspace, Enter, Tab and the arrow keys. |
+| Shift and an arrow key                     | Extends the selection in a text field on the device, as it would on the device's own keyboard. |
+| Escape                                     | Sends the Back key.                                           |
+| Ctrl+A, Ctrl+C, Ctrl+V (Cmd on macOS)      | Select all, copy and paste on the device, using the device's own clipboard. |
+| The **◄**, **●** and **■** buttons          | Sends the Back, Home and Overview keys. Useful on a device that uses gesture navigation, where the mirrored image has no navigation bar to tap. |
+
+Other Ctrl and Cmd combinations are left to the Unity Editor, so its own shortcuts keep working while the image has focus. Ctrl and the wheel zoom the view instead of scrolling the device: refer to [Zoom into the image](screen-capture-window-reference.md#zoom-into-the-image).
+
+> [!NOTE]
+> Nothing is exchanged between the device's clipboard and your computer's. Ctrl+C copies on the device, and Ctrl+V pastes what was copied there.
+
+## Change the size, quality and frame rate
+
+Streaming a display uses both the device's CPU, to compress each frame, and the connection to your computer, to carry it. To trade quality for either, go to **Edit** > **Preferences** > **Analysis** > **Android Logcat Settings** (Windows) or **Unity** > **Settings** > **Analysis** > **Android Logcat Settings** (macOS) and use the [Live Stream](android-logcat-settings.md#live-stream) settings.
+
+The settings apply when a stream starts. To apply them to a stream that is already running, select **Reconnect** in the live view, or turn **Live** off and on again.
+
+> [!NOTE]
+> If you connected the device with `adb connect` rather than by USB, the stream shares the device's Wi-Fi connection with everything else adb does, including the message log. Lower **Max Size** and **Max Frame Rate**, or connect the device by USB, if the connection struggles.
+
+## Additional resources
+
+* [Device Screen Capture window reference](screen-capture-window-reference.md)
+* [Capture a screenshot](screen-capture-screenshot.md)
+* [Capture a video](screen-capture-video.md)
+* [Connect to a device](connect-to-a-device.md)

com.unity.mobile.android-logcat/Documentation~/screen-capture-screenshot.md

@@ -5,10 +5,17 @@ This page explains how to use the [Screen Capture tool](screen-capture.md) to ca
 1. Open the [Device Screen Capture window](screen-capture-window-reference.md).
 2. In the [Toolbar](screen-capture-window-reference.md#toolbar), use **Device Selector** to specify to device to take a screenshot of.
 3. Set **Screen Capture Mode** to **Screenshot**.
-4. Select **Capture**. The Screen Capture tool takes a screenshot of the connected device and displays it in the [Capture preview](screen-capture-window-reference.md#capture-preview).
-5. Select **Save As** and use the file explorer to save the image file to your computer.
+4. Select the **Live** row in the [Capture list](screen-capture-window-reference.md#capture-list), then select **Take Screenshot** in the [Live view details](screen-capture-window-reference.md#live-view-details). Pressing Ctrl+Shift+S (Cmd+Shift+S on macOS) does the same while the live view is showing. The Screen Capture tool takes a screenshot of the connected device, displays it in the [Capture preview](screen-capture-window-reference.md#capture-preview), and adds it to the list.
+5. Right-click the screenshot's row, select **Copy To...**, and use the file explorer to save a copy of the image file elsewhere on your computer. Select several screenshots first to copy them all into one folder.
+
+Every screenshot you capture is kept, so you do not have to save one before taking the next. Screenshots are named `<device id>_<number>.png` and are stored in your project, in `Library/AndroidLogcat/Screenshots`, unless you point [Captures Folder](android-logcat-settings.md#capture-settings) somewhere else. The default folder is local to your machine and is not part of your build, so use **Copy To...**, or a captures folder of your own, to keep a screenshot permanently.
+
+Each screenshot is saved with a `.json` file of the same name beside it, recording the device it came from - its name, id, Android version, API level, ABI and display size - and when it was captured. The [Screenshot details](screen-capture-window-reference.md#screenshot-details) beside the image read it, and it is renamed, deleted and saved along with the image, so a copy you keep elsewhere still knows where it came from. A screenshot without one still opens; its device details read `Undefined`.
+
+To rename or delete a screenshot, or to show it in Explorer or Finder, use the [Capture list](screen-capture-window-reference.md#capture-list). To look at part of a screenshot more closely, [zoom into it](screen-capture-window-reference.md#zoom-into-the-image).
 
 ## Additional resources
 
 * [Device Screen Capture window reference](screen-capture-window-reference.md)
-* [Capture a video](screen-capture-video.md)
+* [Capture a video](screen-capture-video.md)
+* [View the device screen live](screen-capture-live-stream.md)