video: add VO framedropping mode

This mostly uses the same idea as with vo_vdpau.c, but much simplified.

On X11, it tries to get the display framerate with XF86VM, and limits
the frequency of new video frames against it. Note that this is an old
extension, and is confirmed not to work correctly with multi-monitor
setups. But we're using it because it was already around (it is also
used by vo_vdpau).

This attempts to predict the next vsync event by using the time of the
last frame and the display FPS. Even if that goes completely wrong,
the results are still relatively good.

On other systems, or if the X11 code doesn't return a display FPS, a
framerate of 1000 is assumed. This is infinite for all practical
purposes, and means that only frames which are definitely too late are
dropped. This probably has worse results, but is still useful.

"--framedrop=yes" is basically replaced with "--framedrop=decoder". The
old framedropping mode is kept around, and should perhaps be improved.
Dropping on the decoder level is still useful if decoding itself is too
slow.

2 files changed, 39 insertions, 10 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 612c0cad88..f62bbce24f 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -159,7 +159,9 @@ List of Input Commands
         Take a single screenshot.
     <each-frame>
         Take a screenshot each frame. Issue this command again to stop taking
-        screenshots.
+        screenshots. Note that you should disable framedropping when using
+        this mode - or you might receive duplicate images in cases when a
+        frame was dropped.
 
 ``screenshot_to_file "<filename>" [subtitles|video|window]``
     Take a screenshot and save it to a given file. The format of the file will
@@ -635,8 +637,12 @@ Property list
     disabled.
 
 ``drop-frame-count``
-    Frames dropped because they arrived to late. Unavailable if video
-    is disabled
+    Frames dropped because they arrived to late. Doesn't necessarily indicate
+    actual framedrops, just the number of times the decoder was asked to drop.
+    Unavailable if video is disabled
+
+``vo-drop-frame-count``
+    Frames dropped by VO (when using ``--framedrop=vo``).
 
 ``percent-pos`` (RW)
     Position in current file (0-100). The advantage over using this instead of
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 356bd903b3..7839480918 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -430,16 +430,39 @@ Video
     Do not sleep when outputting video frames. Useful for benchmarks when used
     with ``--no-audio.``
 
-``--framedrop=<no|yes>``
-    Skip displaying some frames to maintain A/V sync on slow systems. Video
-    filters are not applied to such frames. For B-frames even decoding is
-    skipped completely. May produce unwatchably choppy output.
-
-    The ``--vd-lavc-framedrop`` option controls what frames to drop.
+``--framedrop=<mode>``
+    Skip displaying some frames to maintain A/V sync on slow systems, or
+    playing high framerate video on video outputs that have an upper framerate
+    limit.
+
+    The argument selects the drop methods, and can be one of the following:
+
+    <no>
+        Disable any framedropping (default).
+    <vo>
+        Drop late frames on video output. This still decodes and filters all
+        frames, but doesn't render them on the VO. It tries to query the
+        display FPS (X11 only, not correct on multi-monitor systems), or
+        assumes infinite display FPS if that fails. Drops are indicated in
+        the terminal status line as ``D: `` field. If the decoder is too slow,
+        in theory all frames would have to be dropped (because all frames are
+        too late) - to avoid this, frame dropping stops if the effective
+        framerate is below 10 FPS.
+    <decoder>
+        Old, decoder-based framedrop mode. (This is the same as ``--framedrop=yes``
+        in mpv 0.5.x and before.) This tells the decoder to skip frames (unless
+        they are needed to decode future frames). May help with slow systems,
+        but can produce unwatchably choppy output, or even freeze the display
+        complete. Not recommended.
+        The ``--vd-lavc-framedrop`` option controls what frames to drop.
+    <decoder+vo>
+        Enable both modes. Not recommended.
 
     .. note::
 
-        Practical use of this feature is questionable. Disabled by default.
+        ``--vo=vdpau`` (also the default VO) always has the ``vo`` framedrop
+        mode enabled. It doesn't increment the ``D:`` field in the statusline
+        either.
 
 ``--hwdec=<api>``
     Specify the hardware video decoding API that should be used if possible.