Add --capture-orientation

Deprecate --lock-video-orientation in favor of a more general option
--capture-orientation, which supports all possible orientations
(0, 90, 180, 270, flip0, flip90, flip180, flip270), and a "locked" flag
via a '@' prefix.

All the old "locked video orientations" are supported:
 - --lock-video-orientation      ->  --capture-orientation=@
 - --lock-video-orientation=0    ->  --capture-orientation=@0
 - --lock-video-orientation=90   ->  --capture-orientation=@90
 - --lock-video-orientation=180  ->  --capture-orientation=@180
 - --lock-video-orientation=270  ->  --capture-orientation=@270

In addition, --capture-orientation can rotate/flip the display without
locking, so that it follows the physical device rotation.

For example:

    scrcpy --capture-orientation=flip90

always flips and rotates the capture by 90° clockwise.

The arguments are consistent with --display-orientation and
--record-orientation and --orientation (which provide separate
client-side orientation settings).

Refs #4011 <#4011>
PR #5455 <#5455>

app/data/bash-completion/scrcpy

@@ -17,6 +17,7 @@ _scrcpy() {
         --camera-fps=
         --camera-high-speed
         --camera-size=
+        --capture-orientation=
         --crop=
         -d --select-usb
         --disable-screensaver
@@ -37,8 +38,6 @@ _scrcpy() {
         --list-cameras
         --list-displays
         --list-encoders
-        --lock-video-orientation
-        --lock-video-orientation=
         -m --max-size=
         -M
         --max-fps=
@@ -138,6 +137,10 @@ _scrcpy() {
             COMPREPLY=($(compgen -W 'disabled uhid aoa' -- "$cur"))
             return
             ;;
+        --capture-orientation)
+            COMPREPLY=($(compgen -W '0 90 180 270 flip0 flip90 flip180 flip270 @0 @90 @180 @270 @flip0 @flip90 @flip180 @flip270' -- "$cur"))
+            return
+            ;;
         --orientation|--display-orientation)
             COMPREPLY=($(compgen -W '0 90 180 270 flip0 flip90 flip180 flip270' -- "$cur"))
             return
@@ -146,10 +149,6 @@ _scrcpy() {
             COMPREPLY=($(compgen -W '0 90 180 270' -- "$cur"))
             return
             ;;
-        --lock-video-orientation)
-            COMPREPLY=($(compgen -W 'unlocked initial 0 90 180 270' -- "$cur"))
-            return
-            ;;
         --pause-on-exit)
             COMPREPLY=($(compgen -W 'true false if-error' -- "$cur"))
             return

app/data/zsh-completion/_scrcpy

@@ -24,6 +24,7 @@ arguments=(
     '--camera-facing=[Select the device camera by its facing direction]:facing:(front back external)'
     '--camera-fps=[Specify the camera capture frame rate]'
     '--camera-size=[Specify an explicit camera capture size]'
+    '--capture-orientation=[Set the capture video orientation]:orientation:(0 90 180 270 flip0 flip90 flip180 flip270 @0 @90 @180 @270 @flip0 @flip90 @flip180 @flip270)'
     '--crop=[\[width\:height\:x\:y\] Crop the device screen on the server]'
     {-d,--select-usb}'[Use USB device]'
     '--disable-screensaver[Disable screensaver while scrcpy is running]'
@@ -44,7 +45,6 @@ arguments=(
     '--list-cameras[List cameras available on the device]'
     '--list-displays[List displays available on the device]'
     '--list-encoders[List video and audio encoders available on the device]'
-    '--lock-video-orientation=[Lock video orientation]:orientation:(unlocked initial 0 90 180 270)'
     {-m,--max-size=}'[Limit both the width and height of the video to value]'
     '-M[Use UHID/AOA mouse (same as --mouse=uhid or --mouse=aoa, depending on OTG mode)]'
     '--max-fps=[Limit the frame rate of screen capture]'

app/scrcpy.1

@@ -121,6 +121,18 @@ If not specified, Android's default frame rate (30 fps) is used.
 .BI "\-\-camera\-size " width\fRx\fIheight
 Specify an explicit camera capture size.
 
+.TP
+.BI "\-\-capture\-orientation " value
+Possible values are 0, 90, 180, 270, flip0, flip90, flip180 and flip270, possibly prefixed by '@'.
+
+The number represents the clockwise rotation in degrees; the "flip" keyword applies a horizontal flip before the rotation.
+
+If a leading '@' is passed (@90) for display capture, then the rotation is locked, and is relative to the natural device orientation.
+
+If '@' is passed alone, then the rotation is locked to the initial device orientation.
+
+Default is 0.
+
 .TP
 .BI "\-\-crop " width\fR:\fIheight\fR:\fIx\fR:\fIy
 Crop the device screen on the server.
@@ -241,16 +253,6 @@ List video and audio encoders available on the device.
 .B \-\-list\-displays
 List displays available on the device.
 
-.TP
-\fB\-\-lock\-video\-orientation\fR[=\fIvalue\fR]
-Lock capture video orientation to \fIvalue\fR.
-
-Possible values are "unlocked", "initial" (locked to the initial orientation), 0, 90, 180, and 270. The values represent the clockwise rotation from the natural device orientation, in degrees.
-
-Default is "unlocked".
-
-Passing the option without argument is equivalent to passing "initial".
-
 .TP
 .BI "\-m, \-\-max\-size " value
 Limit both the width and height of the video to \fIvalue\fR. The other dimension is computed so that the device aspect\-ratio is preserved.
@@ -548,8 +550,6 @@ Default is "info" for release builds, "debug" for debug builds.
 .BI "\-\-v4l2-sink " /dev/videoN
 Output to v4l2loopback device.
 
-It requires to lock the video orientation (see \fB\-\-lock\-video\-orientation\fR).
-
 .TP
 .BI "\-\-v4l2-buffer " ms
 Add a buffering delay (in milliseconds) before pushing frames. This increases latency to compensate for jitter.

app/src/cli.c

@@ -107,6 +107,7 @@ enum {
     OPT_LIST_APPS,
     OPT_START_APP,
     OPT_SCREEN_OFF_TIMEOUT,
+    OPT_CAPTURE_ORIENTATION,
 };
 
 struct sc_option {
@@ -471,18 +472,27 @@ static const struct sc_option options[] = {
         .text = "List video and audio encoders available on the device.",
     },
     {
+        .longopt_id = OPT_CAPTURE_ORIENTATION,
+        .longopt = "capture-orientation",
+        .argdesc = "value",
+        .text = "Set the capture video orientation.\n"
+                "Possible values are 0, 90, 180, 270, flip0, flip90, flip180 "
+                "and flip270, possibly prefixed by '@'.\n"
+                "The number represents the clockwise rotation in degrees; the "
+                "flip\" keyword applies a horizontal flip before the "
+                "rotation.\n"
+                "If a leading '@' is passed (@90) for display capture, then "
+                "the rotation is locked, and is relative to the natural device "
+                "orientation.\n"
+                "If '@' is passed alone, then the rotation is locked to the "
+                "initial device orientation.\n"
+                "Default is 0.",
+    },
+    {
+        // deprecated
         .longopt_id = OPT_LOCK_VIDEO_ORIENTATION,
         .longopt = "lock-video-orientation",
         .argdesc = "value",
-        .optional_arg = true,
-        .text = "Lock capture video orientation to value.\n"
-                "Possible values are \"unlocked\", \"initial\" (locked to the "
-                "initial orientation), 0, 90, 180 and 270. The values "
-                "represent the clockwise rotation from the natural device "
-                "orientation, in degrees.\n"
-                "Default is \"unlocked\".\n"
-                "Passing the option without argument is equivalent to passing "
-                "\"initial\".",
     },
     {
         .shortopt = 'm',
@@ -895,8 +905,6 @@ static const struct sc_option options[] = {
         .longopt = "v4l2-sink",
         .argdesc = "/dev/videoN",
         .text = "Output to v4l2loopback device.\n"
-                "It requires to lock the video orientation (see "
-                "--lock-video-orientation).\n"
                 "This feature is only available on Linux.",
     },
     {
@@ -1582,66 +1590,6 @@ parse_audio_output_buffer(const char *s, sc_tick *tick) {
     return true;
 }
 
-static bool
-parse_lock_video_orientation(const char *s,
-                             enum sc_lock_video_orientation *lock_mode) {
-    if (!s || !strcmp(s, "initial")) {
-        // Without argument, lock the initial orientation
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_INITIAL;
-        return true;
-    }
-
-    if (!strcmp(s, "unlocked")) {
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_UNLOCKED;
-        return true;
-    }
-
-    if (!strcmp(s, "0")) {
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_0;
-        return true;
-    }
-
-    if (!strcmp(s, "90")) {
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_90;
-        return true;
-    }
-
-    if (!strcmp(s, "180")) {
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_180;
-        return true;
-    }
-
-    if (!strcmp(s, "270")) {
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_270;
-        return true;
-    }
-
-    if (!strcmp(s, "1")) {
-        LOGW("--lock-video-orientation=1 is deprecated, use "
-             "--lock-video-orientation=270 instead.");
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_270;
-        return true;
-    }
-
-    if (!strcmp(s, "2")) {
-        LOGW("--lock-video-orientation=2 is deprecated, use "
-             "--lock-video-orientation=180 instead.");
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_180;
-        return true;
-    }
-
-    if (!strcmp(s, "3")) {
-        LOGW("--lock-video-orientation=3 is deprecated, use "
-             "--lock-video-orientation=90 instead.");
-        *lock_mode = SC_LOCK_VIDEO_ORIENTATION_90;
-        return true;
-    }
-
-    LOGE("Unsupported --lock-video-orientation value: %s (expected initial, "
-         "unlocked, 0, 90, 180 or 270).", s);
-    return false;
-}
-
 static bool
 parse_rotation(const char *s, uint8_t *rotation) {
     long value;
@@ -1693,6 +1641,32 @@ parse_orientation(const char *s, enum sc_orientation *orientation) {
     return false;
 }
 
+static bool
+parse_capture_orientation(const char *s, enum sc_orientation *orientation,
+                          enum sc_orientation_lock *lock) {
+    if (*s == '\0') {
+        LOGE("Capture orientation may not be empty (expected 0, 90, 180, 270, "
+             "flip0, flip90, flip180 or flip270, possibly prefixed by '@')");
+        return false;
+    }
+
+    // Lock the orientation by a leading '@'
+    if (s[0] == '@') {
+        // Consume '@'
+        ++s;
+        if (*s == '\0') {
+            // Only '@': lock to the initial orientation (orientation is unused)
+            *lock = SC_ORIENTATION_LOCKED_INITIAL;
+            return true;
+        }
+        *lock = SC_ORIENTATION_LOCKED_VALUE;
+    } else {
+        *lock = SC_ORIENTATION_UNLOCKED;
+    }
+
+    return parse_orientation(s, orientation);
+}
+
 static bool
 parse_window_position(const char *s, int16_t *position) {
     // special value for "auto"
@@ -2367,8 +2341,13 @@ parse_args_with_getopt(struct scrcpy_cli_args *args, int argc, char *argv[],
                      "--mouse=uhid instead.");
                 return false;
             case OPT_LOCK_VIDEO_ORIENTATION:
-                if (!parse_lock_video_orientation(optarg,
-                        &opts->lock_video_orientation)) {
+                LOGE("--lock-video-orientation has been removed, use "
+                     "--capture-orientation instead.");
+                return false;
+            case OPT_CAPTURE_ORIENTATION:
+                if (!parse_capture_orientation(optarg,
+                                          &opts->capture_orientation,
+                                          &opts->capture_orientation_lock)) {
                     return false;
                 }
                 break;
@@ -2852,13 +2831,6 @@ parse_args_with_getopt(struct scrcpy_cli_args *args, int argc, char *argv[],
             return false;
         }
 
-        if (opts->lock_video_orientation ==
-                SC_LOCK_VIDEO_ORIENTATION_UNLOCKED) {
-            LOGI("Video orientation is locked for v4l2 sink. "
-                 "See --lock-video-orientation.");
-            opts->lock_video_orientation = SC_LOCK_VIDEO_ORIENTATION_INITIAL;
-        }
-
         // V4L2 could not handle size change.
         // Do not log because downsizing on error is the default behavior,
         // not an explicit request from the user.

app/src/options.c

@@ -50,7 +50,8 @@ const struct scrcpy_options scrcpy_options_default = {
     .video_bit_rate = 0,
     .audio_bit_rate = 0,
     .max_fps = NULL,
-    .lock_video_orientation = SC_LOCK_VIDEO_ORIENTATION_UNLOCKED,
+    .capture_orientation = SC_ORIENTATION_0,
+    .capture_orientation_lock = SC_ORIENTATION_UNLOCKED,
     .display_orientation = SC_ORIENTATION_0,
     .record_orientation = SC_ORIENTATION_0,
     .window_x = SC_WINDOW_POSITION_UNDEFINED,

app/src/options.h

@@ -84,6 +84,12 @@ enum sc_orientation {         // v v v
     SC_ORIENTATION_FLIP_270,  // 1 1 1
 };
 
+enum sc_orientation_lock {
+    SC_ORIENTATION_UNLOCKED,
+    SC_ORIENTATION_LOCKED_VALUE,   // lock to specified orientation
+    SC_ORIENTATION_LOCKED_INITIAL, // lock to initial device orientation
+};
+
 static inline bool
 sc_orientation_is_mirror(enum sc_orientation orientation) {
     assert(!(orientation & ~7));
@@ -130,16 +136,6 @@ sc_orientation_get_name(enum sc_orientation orientation) {
     }
 }
 
-enum sc_lock_video_orientation {
-    SC_LOCK_VIDEO_ORIENTATION_UNLOCKED = -1,
-    // lock the current orientation when scrcpy starts
-    SC_LOCK_VIDEO_ORIENTATION_INITIAL = -2,
-    SC_LOCK_VIDEO_ORIENTATION_0 = 0,
-    SC_LOCK_VIDEO_ORIENTATION_90 = 3,
-    SC_LOCK_VIDEO_ORIENTATION_180 = 2,
-    SC_LOCK_VIDEO_ORIENTATION_270 = 1,
-};
-
 enum sc_keyboard_input_mode {
     SC_KEYBOARD_INPUT_MODE_AUTO,
     SC_KEYBOARD_INPUT_MODE_UHID_OR_AOA, // normal vs otg mode
@@ -251,7 +247,8 @@ struct scrcpy_options {
     uint32_t video_bit_rate;
     uint32_t audio_bit_rate;
     const char *max_fps; // float to be parsed by the server
-    enum sc_lock_video_orientation lock_video_orientation;
+    enum sc_orientation capture_orientation;
+    enum sc_orientation_lock capture_orientation_lock;
     enum sc_orientation display_orientation;
     enum sc_orientation record_orientation;
     int16_t window_x; // SC_WINDOW_POSITION_UNDEFINED for "auto"

app/src/scrcpy.c

@@ -429,7 +429,8 @@ scrcpy(struct scrcpy_options *options) {
         .audio_bit_rate = options->audio_bit_rate,
         .max_fps = options->max_fps,
         .screen_off_timeout = options->screen_off_timeout,
-        .lock_video_orientation = options->lock_video_orientation,
+        .capture_orientation = options->capture_orientation,
+        .capture_orientation_lock = options->capture_orientation_lock,
         .control = options->control,
         .display_id = options->display_id,
         .new_display = options->new_display,

app/src/server.c

@@ -274,9 +274,17 @@ execute_server(struct sc_server *server,
         VALIDATE_STRING(params->max_fps);
         ADD_PARAM("max_fps=%s", params->max_fps);
     }
-    if (params->lock_video_orientation != SC_LOCK_VIDEO_ORIENTATION_UNLOCKED) {
-        ADD_PARAM("lock_video_orientation=%" PRIi8,
-                  params->lock_video_orientation);
+    if (params->capture_orientation_lock != SC_ORIENTATION_UNLOCKED
+            || params->capture_orientation != SC_ORIENTATION_0) {
+        if (params->capture_orientation_lock == SC_ORIENTATION_LOCKED_INITIAL) {
+            ADD_PARAM("capture_orientation=@");
+        } else {
+            const char *orient =
+                sc_orientation_get_name(params->capture_orientation);
+            bool locked =
+                params->capture_orientation_lock != SC_ORIENTATION_UNLOCKED;
+            ADD_PARAM("capture_orientation=%s%s", locked ? "@" : "", orient);
+        }
     }
     if (server->tunnel.forward) {
         ADD_PARAM("tunnel_forward=true");

app/src/server.h

@@ -46,7 +46,8 @@ struct sc_server_params {
     uint32_t audio_bit_rate;
     const char *max_fps; // float to be parsed by the server
     sc_tick screen_off_timeout;
-    int8_t lock_video_orientation;
+    enum sc_orientation capture_orientation;
+    enum sc_orientation_lock capture_orientation_lock;
     bool control;
     uint32_t display_id;
     const char *new_display;

app/tests/test_cli.c

@@ -51,7 +51,6 @@ static void test_options(void) {
         "--fullscreen",
         "--max-fps", "30",
         "--max-size", "1024",
-        "--lock-video-orientation=2", // optional arguments require '='
         // "--no-control" is not compatible with "--turn-screen-off"
         // "--no-playback" is not compatible with "--fulscreen"
         "--port", "1234:1236",
@@ -80,7 +79,6 @@ static void test_options(void) {
     assert(opts->fullscreen);
     assert(!strcmp(opts->max_fps, "30"));
     assert(opts->max_size == 1024);
-    assert(opts->lock_video_orientation == 2);
     assert(opts->port_range.first == 1234);
     assert(opts->port_range.last == 1236);
     assert(!strcmp(opts->push_target, "/sdcard/Movies"));