command, options: deprecate old --display-fps behavior

See changelog and manpage changes.

(So much effort to fix an ancient dumb mistake for an option nobody
should use anyway.)

DOCS/interface-changes.rst

@@ -43,6 +43,10 @@ Interface changes
     - deprecate all input section commands (these will be changed/removed, as
       soon as mpv internals do not require them anymore)
     - remove deprecated --playlist-pos alias (use --playlist-start)
+    - deprecate --display-fps, introduce --override-display-fps. The display-fps
+      property now is unavailable if no VO exists (or the VO did not return a
+      display FPS), instead of returning the option value in this case. The
+      property will keep existing, but writing to it is deprecated.
  --- mpv 0.30.0 ---
     - add `--d3d11-output-format` to enable explicit selection of a D3D11
       swap chain format.

DOCS/man/input.rst

@@ -2029,13 +2029,18 @@ Property list
     Display Product Names as used in the System Information and only one display
     name is returned since a window can only be on one screen.
 
-``display-fps`` (RW)
+``display-fps``
     The refresh rate of the current display. Currently, this is the lowest FPS
     of any display covered by the video, as retrieved by the underlying system
     APIs (e.g. xrandr on X11). It is not the measured FPS. It's not necessarily
     available on all platforms. Note that any of the listed facts may change
     any time without a warning.
 
+    Writing to this property is deprecated. It has the same effect as writing to
+    ``override-display-fps``. Since mpv 0.31.0, this property is unavailable
+    if no display FPS was reported (e.g. if no video is active), while in older
+    versions, it returned the ``--display-fps`` option value.
+
 ``estimated-display-fps``
     Only available if display-sync mode (as selected by ``--video-sync``) is
     active. Returns the actual rate at which display refreshes seem to occur,
@@ -2697,8 +2702,9 @@ caveats with some properties (due to historical reasons):
     Option changes at runtime are affected by this as well.
 
 ``display-fps``
-    If a VO is created, this will return either the actual display FPS, or
-    an invalid value, instead of the option value.
+    This inconsistent behavior is deprecated. Post-deprecation, the reported
+    value and the option value are cleanly separated (``override-display-fps``
+    for the option value).
 
 ``vf``, ``af``
     If you set the properties during playback, and the filter chain fails to

DOCS/man/options.rst

@@ -949,8 +949,7 @@ Video
       frame, so if this is not done, there is some likeliness that the VO has
       to drop some frames if rendering the first frame takes longer than needed.
 
-
-``--display-fps=<fps>``
+``--override-display-fps=<fps>``
     Set the display FPS used with the ``--video-sync=display-*`` modes. By
     default, a detected value is used. Keep in mind that setting an incorrect
     value (even if slightly incorrect) can ruin video playback. On multi-monitor
@@ -960,6 +959,9 @@ Video
     Set this option only if you have reason to believe the automatically
     determined value is wrong.
 
+``--display-fps=<fps>``
+    Deprecated alias for ``--override-display-fps``.
+
 ``--hwdec=<api>``
     Specify the hardware video decoding API that should be used if possible.
     Whether hardware decoding is actually done depends on the video codec. If
@@ -4776,7 +4778,7 @@ The following video options are currently all specific to ``--vo=gpu`` and
     require driver-specific hacks if using multiple monitors, to ensure mpv
     syncs to the right one. Compositing window managers can also lead to bad
     results, as can missing or incorrect display FPS information (see
-    ``--display-fps``).
+    ``--override-display-fps``).
 
 ``--vulkan-swap-mode=<mode>``
     Controls the presentation mode of the vulkan swapchain. This is similar

options/options.c

@@ -147,7 +147,7 @@ static const m_option_t mp_vo_opt_list[] = {
     OPT_FLAG("keepaspect-window", keepaspect_window, 0),
     OPT_FLAG("hidpi-window-scale", hidpi_window_scale, 0),
     OPT_FLAG("native-fs", native_fs, 0),
-    OPT_DOUBLE("display-fps", override_display_fps, M_OPT_MIN, .min = 0),
+    OPT_DOUBLE("override-display-fps", override_display_fps, M_OPT_MIN, .min = 0),
     OPT_DOUBLERANGE("video-timing-offset", timing_offset, 0, 0.0, 1.0),
 #if HAVE_X11
     OPT_CHOICE("x11-netwm", x11_netwm, 0,
@@ -891,6 +891,7 @@ const m_option_t mp_opts[] = {
     OPT_REMOVED("video-stereo-mode", "removed, try --vf=stereo3d"),
     OPT_REMOVED("chapter", "use '--start=#123' '--end=#124' (for chapter 123)"),
     OPT_REPLACED("video-aspect", "video-aspect-override"),
+    OPT_REPLACED("display-fps", "override-display-fps"),
 
     {0}
 };

player/command.c

@@ -2445,9 +2445,27 @@ static int mp_property_display_fps(void *ctx, struct m_property *prop,
 {
     MPContext *mpctx = ctx;
     double fps = mpctx->video_out ? vo_get_display_fps(mpctx->video_out) : 0;
-    if (fps > 0 && action != M_PROPERTY_SET)
+    switch (action) {
+    case M_PROPERTY_SET: {
+        MP_WARN(mpctx, "Setting the display-fps property is deprecated; set "
+                       "the override-display-fps property instead.\n");
+        struct mpv_node val = {
+            .format = MPV_FORMAT_DOUBLE,
+            .u.double_ = *(double *)arg,
+        };
+        return m_config_set_option_node(mpctx->mconfig,
+            bstr0("override-display-fps"), &val, 0)
+            >= 0 ? M_PROPERTY_OK : M_PROPERTY_ERROR;
+    }
+    case M_PROPERTY_GET:
+        if (fps <= 0)
+            return M_PROPERTY_UNAVAILABLE;
         return m_property_double_ro(action, arg, fps);
-    return mp_property_generic_option(mpctx, prop, action, arg);
+    case M_PROPERTY_GET_TYPE:
+        *(struct m_option *)arg = (struct m_option){.type = CONF_TYPE_DOUBLE};
+        return M_PROPERTY_OK;
+    }
+    return M_PROPERTY_NOT_IMPLEMENTED;
 }
 
 static int mp_property_estimated_display_fps(void *ctx, struct m_property *prop,