Extract device connection to a separate doc page

Create a new "Connection" documentation page.

README.md

@@ -5,7 +5,7 @@
 _pronounced "**scr**een **c**o**py**"_
 
 This application mirrors Android devices (video and audio) connected via
-USB or [over TCP/IP](doc/connection.md#tcpip-wireless), and allows to control the
+USB or [over TCP/IP](doc/device.md#tcpip-wireless), and allows to control the
 device with the keyboard and the mouse of the computer. It does not require any
 _root_ access. It works on _Linux_, _Windows_ and _macOS_.
 

app/src/cli.c

@@ -2022,6 +2022,12 @@ parse_args_with_getopt(struct scrcpy_cli_args *args, int argc, char *argv[],
         opts->audio_playback = false;
     }
 
+    if (!opts->video_playback && !otg) {
+        // If video playback is disabled and OTG are disabled, then there is
+        // no way to control the device.
+        opts->control = false;
+    }
+
     if (opts->video && !opts->video_playback && !opts->record_filename
             && !v4l2) {
         LOGI("No video playback, no recording, no V4L2 sink: video disabled");

app/src/display.c

@@ -53,7 +53,7 @@ sc_display_init(struct sc_display *display, SDL_Window *window, bool mipmaps) {
                 display->mipmaps = true;
             } else {
                 LOGW("Trilinear filtering disabled "
-                     "(OpenGL 3.0+ or ES 2.0+ required)");
+                     "(OpenGL 3.0+ or ES 2.0+ required");
             }
         } else {
             LOGI("Trilinear filtering disabled");

app/src/scrcpy.c

@@ -252,9 +252,7 @@ sc_audio_demuxer_on_ended(struct sc_demuxer *demuxer,
 
     // Contrary to the video demuxer, keep mirroring if only the audio fails
     // (unless --require-audio is set).
-    if (status == SC_DEMUXER_STATUS_EOS) {
-        PUSH_EVENT(SC_EVENT_DEVICE_DISCONNECTED);
-    } else if (status == SC_DEMUXER_STATUS_ERROR
+    if (status == SC_DEMUXER_STATUS_ERROR
             || (status == SC_DEMUXER_STATUS_DISABLED
                 && options->require_audio)) {
         PUSH_EVENT(SC_EVENT_DEMUXER_ERROR);
@@ -450,7 +448,9 @@ scrcpy(struct scrcpy_options *options) {
 
     struct sc_file_pusher *fp = NULL;
 
-    if (options->video_playback && options->control) {
+    // control implies video playback
+    assert(!options->control || options->video_playback);
+    if (options->control) {
         if (!sc_file_pusher_init(&s->file_pusher, serial,
                                  options->push_target)) {
             goto end;

doc/audio.md

@@ -77,13 +77,6 @@ In particular, if you get the following error:
 
 then your device has no Opus encoder: try `scrcpy --audio-codec=aac`.
 
-For advanced usage, to pass arbitrary parameters to the [`MediaFormat`],
-check `--audio-codec-options` in the manpage or in `scrcpy --help`.
-
-[`MediaFormat`]: https://developer.android.com/reference/android/media/MediaFormat
-
-
-## Encoder
 
 Several encoders may be available on the device. They can be listed by:
 
@@ -93,10 +86,15 @@ scrcpy --list-encoders
 
 To select a specific encoder:
 
-```bash
+```
 scrcpy --audio-codec=opus --audio-encoder='c2.android.opus.encoder'
 ```
 
+For advanced usage, to pass arbitrary parameters to the [`MediaFormat`],
+check `--audio-codec-options` in the manpage or in `scrcpy --help`.
+
+[`MediaFormat`]: https://developer.android.com/reference/android/media/MediaFormat
+
 
 ## Bit rate
 

doc/device.md

@@ -1,7 +1,23 @@
 # Device
 
-Some command line arguments perform actions on the device itself while scrcpy is
-running.
+## Display
+
+If several displays are available on the Android device, it is possible to
+select the display to mirror:
+
+```bash
+scrcpy --display=1
+```
+
+The list of display ids can be retrieved by:
+
+```bash
+scrcpy --list-displays
+```
+
+A secondary display may only be controlled if the device runs at least Android
+10 (otherwise it is mirrored as read-only).
+
 
 ## Stay awake
 
@@ -78,3 +94,4 @@ By default, on start, the device is powered on. To prevent this behavior:
 ```bash
 scrcpy --no-power-on
 ```
+

doc/video.md

@@ -66,14 +66,6 @@ scrcpy --video-codec=av1
 H265 may provide better quality, but H264 should provide lower latency.
 AV1 encoders are not common on current Android devices.
 
-For advanced usage, to pass arbitrary parameters to the [`MediaFormat`],
-check `--video-codec-options` in the manpage or in `scrcpy --help`.
-
-[`MediaFormat`]: https://developer.android.com/reference/android/media/MediaFormat
-
-
-## Encoder
-
 Several encoders may be available on the device. They can be listed by:
 
 ```bash
@@ -87,6 +79,11 @@ try another one:
 scrcpy --video-codec=h264 --video-encoder='OMX.qcom.video.encoder.avc'
 ```
 
+For advanced usage, to pass arbitrary parameters to the [`MediaFormat`],
+check `--video-codec-options` in the manpage or in `scrcpy --help`.
+
+[`MediaFormat`]: https://developer.android.com/reference/android/media/MediaFormat
+
 
 ## Rotation
 
@@ -137,25 +134,6 @@ phone, landscape for a tablet).
 If `--max-size` is also specified, resizing is applied after cropping.
 
 
-## Display
-
-If several displays are available on the Android device, it is possible to
-select the display to mirror:
-
-```bash
-scrcpy --display=1
-```
-
-The list of display ids can be retrieved by:
-
-```bash
-scrcpy --list-displays
-```
-
-A secondary display may only be controlled if the device runs at least Android
-10 (otherwise it is mirrored as read-only).
-
-
 ## Buffering
 
 By default, there is no video buffering, to get the lowest possible latency.

server/src/main/java/com/genymobile/scrcpy/ScreenCapture.java

@@ -1,83 +0,0 @@
-package com.genymobile.scrcpy;
-
-import com.genymobile.scrcpy.wrappers.SurfaceControl;
-
-import android.graphics.Rect;
-import android.os.Build;
-import android.os.IBinder;
-import android.view.Surface;
-
-public class ScreenCapture extends SurfaceCapture implements Device.RotationListener, Device.FoldListener {
-
-    private final Device device;
-    private IBinder display;
-
-    public ScreenCapture(Device device) {
-        this.device = device;
-    }
-
-    @Override
-    public void init() {
-        display = createDisplay();
-        device.setRotationListener(this);
-        device.setFoldListener(this);
-    }
-
-    @Override
-    public void release() {
-        device.setRotationListener(null);
-        device.setFoldListener(null);
-        SurfaceControl.destroyDisplay(display);
-    }
-
-    @Override
-    public Size getSize() {
-        return device.getScreenInfo().getVideoSize();
-    }
-
-    @Override
-    public void setMaxSize(int size) {
-        device.setMaxSize(size);
-    }
-
-    @Override
-    public void setSurface(Surface surface) {
-        ScreenInfo screenInfo = device.getScreenInfo();
-        Rect contentRect = screenInfo.getContentRect();
-
-        // does not include the locked video orientation
-        Rect unlockedVideoRect = screenInfo.getUnlockedVideoSize().toRect();
-        int videoRotation = screenInfo.getVideoRotation();
-        int layerStack = device.getLayerStack();
-        setDisplaySurface(display, surface, videoRotation, contentRect, unlockedVideoRect, layerStack);
-    }
-
-    @Override
-    public void onFoldChanged(int displayId, boolean folded) {
-        requestReset();
-    }
-
-    @Override
-    public void onRotationChanged(int rotation) {
-        requestReset();
-    }
-
-    private static IBinder createDisplay() {
-        // Since Android 12 (preview), secure displays could not be created with shell permissions anymore.
-        // On Android 12 preview, SDK_INT is still R (not S), but CODENAME is "S".
-        boolean secure = Build.VERSION.SDK_INT < Build.VERSION_CODES.R || (Build.VERSION.SDK_INT == Build.VERSION_CODES.R && !"S".equals(
-                Build.VERSION.CODENAME));
-        return SurfaceControl.createDisplay("scrcpy", secure);
-    }
-
-    private static void setDisplaySurface(IBinder display, Surface surface, int orientation, Rect deviceRect, Rect displayRect, int layerStack) {
-        SurfaceControl.openTransaction();
-        try {
-            SurfaceControl.setDisplaySurface(display, surface);
-            SurfaceControl.setDisplayProjection(display, orientation, deviceRect, displayRect);
-            SurfaceControl.setDisplayLayerStack(display, layerStack);
-        } finally {
-            SurfaceControl.closeTransaction();
-        }
-    }
-}

server/src/main/java/com/genymobile/scrcpy/ScreenEncoder.java

@@ -17,7 +17,7 @@ import java.nio.ByteBuffer;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicBoolean;
 
-public class SurfaceEncoder implements AsyncProcessor {
+public class ScreenEncoder implements Device.RotationListener, Device.FoldListener, AsyncProcessor {
 
     private static final int DEFAULT_I_FRAME_INTERVAL = 10; // seconds
     private static final int REPEAT_FRAME_DELAY_US = 100_000; // repeat after 100ms
@@ -27,7 +27,9 @@ public class SurfaceEncoder implements AsyncProcessor {
     private static final int[] MAX_SIZE_FALLBACK = {2560, 1920, 1600, 1280, 1024, 800};
     private static final int MAX_CONSECUTIVE_ERRORS = 3;
 
-    private final SurfaceCapture capture;
+    private final AtomicBoolean resetCapture = new AtomicBoolean();
+
+    private final Device device;
     private final Streamer streamer;
     private final String encoderName;
     private final List<CodecOption> codecOptions;
@@ -41,9 +43,9 @@ public class SurfaceEncoder implements AsyncProcessor {
     private Thread thread;
     private final AtomicBoolean stopped = new AtomicBoolean();
 
-    public SurfaceEncoder(SurfaceCapture capture, Streamer streamer, int videoBitRate, int maxFps, List<CodecOption> codecOptions, String encoderName,
+    public ScreenEncoder(Device device, Streamer streamer, int videoBitRate, int maxFps, List<CodecOption> codecOptions, String encoderName,
             boolean downsizeOnError) {
-        this.capture = capture;
+        this.device = device;
         this.streamer = streamer;
         this.videoBitRate = videoBitRate;
         this.maxFps = maxFps;
@@ -52,29 +54,51 @@ public class SurfaceEncoder implements AsyncProcessor {
         this.downsizeOnError = downsizeOnError;
     }
 
+    @Override
+    public void onFoldChanged(int displayId, boolean folded) {
+        resetCapture.set(true);
+    }
+
+    @Override
+    public void onRotationChanged(int rotation) {
+        resetCapture.set(true);
+    }
+
+    private boolean consumeResetCapture() {
+        return resetCapture.getAndSet(false);
+    }
+
     private void streamScreen() throws IOException, ConfigurationException {
         Codec codec = streamer.getCodec();
         MediaCodec mediaCodec = createMediaCodec(codec, encoderName);
         MediaFormat format = createFormat(codec.getMimeType(), videoBitRate, maxFps, codecOptions);
+        IBinder display = createDisplay();
+        device.setRotationListener(this);
+        device.setFoldListener(this);
 
-        capture.init();
+        streamer.writeVideoHeader(device.getScreenInfo().getVideoSize());
 
+        boolean alive;
         try {
-            streamer.writeVideoHeader(capture.getSize());
-
-            boolean alive;
-
             do {
-                Size size = capture.getSize();
-                format.setInteger(MediaFormat.KEY_WIDTH, size.getWidth());
-                format.setInteger(MediaFormat.KEY_HEIGHT, size.getHeight());
+                ScreenInfo screenInfo = device.getScreenInfo();
+                Rect contentRect = screenInfo.getContentRect();
+
+                // include the locked video orientation
+                Rect videoRect = screenInfo.getVideoSize().toRect();
+                format.setInteger(MediaFormat.KEY_WIDTH, videoRect.width());
+                format.setInteger(MediaFormat.KEY_HEIGHT, videoRect.height());
 
                 Surface surface = null;
                 try {
                     mediaCodec.configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE);
                     surface = mediaCodec.createInputSurface();
 
-                    capture.setSurface(surface);
+                    // does not include the locked video orientation
+                    Rect unlockedVideoRect = screenInfo.getUnlockedVideoSize().toRect();
+                    int videoRotation = screenInfo.getVideoRotation();
+                    int layerStack = device.getLayerStack();
+                    setDisplaySurface(display, surface, videoRotation, contentRect, unlockedVideoRect, layerStack);
 
                     mediaCodec.start();
 
@@ -83,7 +107,7 @@ public class SurfaceEncoder implements AsyncProcessor {
                     mediaCodec.stop();
                 } catch (IllegalStateException | IllegalArgumentException e) {
                     Ln.e("Encoding error: " + e.getClass().getName() + ": " + e.getMessage());
-                    if (!prepareRetry(size)) {
+                    if (!prepareRetry(device, screenInfo)) {
                         throw e;
                     }
                     Ln.i("Retrying...");
@@ -97,11 +121,13 @@ public class SurfaceEncoder implements AsyncProcessor {
             } while (alive);
         } finally {
             mediaCodec.release();
-            capture.release();
+            device.setRotationListener(null);
+            device.setFoldListener(null);
+            SurfaceControl.destroyDisplay(display);
         }
     }
 
-    private boolean prepareRetry(Size currentSize) {
+    private boolean prepareRetry(Device device, ScreenInfo screenInfo) {
         if (firstFrameSent) {
             ++consecutiveErrors;
             if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
@@ -121,7 +147,7 @@ public class SurfaceEncoder implements AsyncProcessor {
 
         // Downsizing on error is only enabled if an encoding failure occurs before the first frame (downsizing later could be surprising)
 
-        int newMaxSize = chooseMaxSizeFallback(currentSize);
+        int newMaxSize = chooseMaxSizeFallback(screenInfo.getVideoSize());
         if (newMaxSize == 0) {
             // Must definitively fail
             return false;
@@ -129,7 +155,7 @@ public class SurfaceEncoder implements AsyncProcessor {
 
         // Retry with a smaller device size
         Ln.i("Retrying with -m" + newMaxSize + "...");
-        capture.setMaxSize(newMaxSize);
+        device.setMaxSize(newMaxSize);
         return true;
     }
 
@@ -150,14 +176,14 @@ public class SurfaceEncoder implements AsyncProcessor {
         boolean alive = true;
         MediaCodec.BufferInfo bufferInfo = new MediaCodec.BufferInfo();
 
-        while (!capture.consumeReset() && !eof) {
+        while (!consumeResetCapture() && !eof) {
             if (stopped.get()) {
                 alive = false;
                 break;
             }
             int outputBufferId = codec.dequeueOutputBuffer(bufferInfo, -1);
             try {
-                if (capture.consumeReset()) {
+                if (consumeResetCapture()) {
                     // must restart encoding with new size
                     break;
                 }
@@ -241,8 +267,8 @@ public class SurfaceEncoder implements AsyncProcessor {
     private static IBinder createDisplay() {
         // Since Android 12 (preview), secure displays could not be created with shell permissions anymore.
         // On Android 12 preview, SDK_INT is still R (not S), but CODENAME is "S".
-        boolean secure = Build.VERSION.SDK_INT < Build.VERSION_CODES.R || (Build.VERSION.SDK_INT == Build.VERSION_CODES.R && !"S".equals(
-                Build.VERSION.CODENAME));
+        boolean secure = Build.VERSION.SDK_INT < Build.VERSION_CODES.R || (Build.VERSION.SDK_INT == Build.VERSION_CODES.R && !"S"
+                .equals(Build.VERSION.CODENAME));
         return SurfaceControl.createDisplay("scrcpy", secure);
     }
 

server/src/main/java/com/genymobile/scrcpy/Server.java

@@ -132,8 +132,7 @@ public final class Server {
             if (video) {
                 Streamer videoStreamer = new Streamer(connection.getVideoFd(), options.getVideoCodec(), options.getSendCodecMeta(),
                         options.getSendFrameMeta());
-                ScreenCapture screenCapture = new ScreenCapture(device);
-                SurfaceEncoder screenEncoder = new SurfaceEncoder(screenCapture, videoStreamer, options.getVideoBitRate(), options.getMaxFps(),
+                ScreenEncoder screenEncoder = new ScreenEncoder(device, videoStreamer, options.getVideoBitRate(), options.getMaxFps(),
                         options.getVideoCodecOptions(), options.getVideoEncoder(), options.getDownsizeOnError());
                 asyncProcessors.add(screenEncoder);
             }

server/src/main/java/com/genymobile/scrcpy/SurfaceCapture.java

@@ -1,61 +0,0 @@
-package com.genymobile.scrcpy;
-
-import android.view.Surface;
-
-import java.util.concurrent.atomic.AtomicBoolean;
-
-/**
- * A video source which can be rendered on a Surface for encoding.
- */
-public abstract class SurfaceCapture {
-
-    private final AtomicBoolean resetCapture = new AtomicBoolean();
-
-    /**
-     * Request the encoding session to be restarted, for example if the capture implementation detects that the video source size has changed (on
-     * device rotation for example).
-     */
-    protected void requestReset() {
-        resetCapture.set(true);
-    }
-
-    /**
-     * Consume the reset request (intended to be called by the encoder).
-     *
-     * @return {@code true} if a reset request was pending, {@code false} otherwise.
-     */
-    public boolean consumeReset() {
-        return resetCapture.getAndSet(false);
-    }
-
-    /**
-     * Called once before the capture starts.
-     */
-    public abstract void init();
-
-    /**
-     * Called after the capture ends (if and only if {@link #init()} has been called).
-     */
-    public abstract void release();
-
-    /**
-     * Return the video size
-     *
-     * @return the video size
-     */
-    public abstract Size getSize();
-
-    /**
-     * Set the maximum capture size (set by the encoder if it does not support the current size).
-     *
-     * @param size Maximum size
-     */
-    public abstract void setMaxSize(int size);
-
-    /**
-     * Set the target surface.
-     *
-     * @param surface the surface which will be encoded
-     */
-    public abstract void setSurface(Surface surface);
-}