vo_opengl_cb: introduce frame queue

The previous implementation of opengl-cb kept only latest flipped frame.
This can cause massive frame drops because rendering is done asynchronously
and only the latest frame can be rendered.

This commit introduces frame queue and releated options to opengl-cb.

frame-queue-size: the maximum size of frame queue (1-100, default: 1)
frame-drop-mode: behavior when frame queue is full (pop, clear, default: pop)

The frame queue holds delayed frames and drops frames if the frame queue is
overflowed with next method:

'pop' mode: drops all the oldest frames overflown.
'clear' mode: drops all frames in queue and clear it.

With default options(frame-queue-size=1:frame-drop-mode=pop),
opengl-cb behaves in the same way as previous implementation effectively.

For frame-queue-size > 1, opengl-cb tries to calls update() without waiting
next flip_page() in order to consume queued frames.

Signed-off-by: wm4 <wm4@nowhere>

1 files changed, 20 insertions, 1 deletions

diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
index e845eef239..c296e705be 100644
--- a/DOCS/man/vo.rst
+++ b/DOCS/man/vo.rst
@@ -915,8 +915,27 @@ Available video output drivers are:
 ``opengl-cb``
     For use with libmpv direct OpenGL embedding; useless in any other contexts.
     (See ``<mpv/opengl_cb.h>``.)
+    Usually, ``opengl-cb`` renders frames asynchronously by client and this
+    can cause some frame drops. In order to provide a way to handle this
+    situation, ``opengl-cb`` has its own frame queue and calls update callback
+    more frequently if the queue is not empty regardless of existence of new frame.
+    Once the queue is filled, ``opengl-cb`` drops frames automatically.
 
-    This supports many of the suboptions the ``opengl`` VO has. Run
+    With default options, ``opengl-cb`` renders only the latest frame and drops
+    all frames handed over while waiting render function after update callback.
+
+    ``frame-queue-size=<1..100>``
+        The maximum count of frames which the frame queue can hold (default: 1)
+
+    ``frame-drop-mode=<pop|clear>``
+        Select the behavior when the frame queue is full.
+
+        pop
+            Drop the oldest frame in the frame queue. (default)
+        clear
+            Drop all frames in the frame queue.
+
+    This also supports many of the suboptions the ``opengl`` VO has. Runs
     ``mpv --vo=opengl-cb:help`` for a list.
 
     This also supports the ``vo_cmdline`` command.