client API: deprecate opengl-cb API and introduce a replacement API

The purpose of the new API is to make it useable with other APIs than
OpenGL, especially D3D11 and vulkan. In theory it's now possible to
support other vo_gpu backends, as well as backends that don't use the
vo_gpu code at all.

This also aims to get rid of the dumb mpv_get_sub_api() function. The
life cycle of the new mpv_render_context is a bit different from
mpv_opengl_cb_context, and you explicitly create/destroy the new
context, instead of calling init/uninit on an object returned by
mpv_get_sub_api().

In other to make the render API generic, it's annoyingly EGL style, and
requires you to pass in API-specific objects to generic functions. This
is to avoid explicit objects like the internal ra API has, because that
sounds more complicated and annoying for an API that's supposed to never
change.

The opengl_cb API will continue to exist for a bit longer, but
internally there are already a few tradeoffs, like reduced
thread-safety.

Mostly untested. Seems to work fine with mpc-qt.

DOCS/client-api-changes.rst

@@ -33,6 +33,19 @@ API changes
 ::
 
  --- mpv 0.29.0 ---
+ 1.28   - deprecate the render opengl_cb API, and replace it with render.h
+          and render_gl.h. The goal is allowing support for APIs other than
+          OpenGL. The old API is emulated with the new API.
+          Likewise, the "opengl-cb" VO is renamed to "libmpv".
+          mpv_get_sub_api() is deprecated along the opengl_cb API.
+          The new API is relatively similar, but not the same. The rough
+          equivalents are:
+            mpv_opengl_cb_init_gl => mpv_render_context_create
+            mpv_opengl_cb_set_update_callback => mpv_render_context_set_update_callback
+            mpv_opengl_cb_draw => mpv_render_context_render
+            mpv_opengl_cb_report_flip => mpv_render_context_report_swap
+            mpv_opengl_cb_uninit_gl => mpv_render_context_free
+          The VO opengl-cb is also renamed to "libmpv".
  1.27   - make opengl-cb the default VO. This causes a subtle behavior change
           if the API user called mpv_opengl_cb_init_gl(), but does not set
           the "vo" option. Before, it would still have used another VO (like

DOCS/interface-changes.rst

@@ -72,6 +72,8 @@ Interface changes
       will probably stall.
     - deprecate the OpenGL cocoa backend, option choice --gpu-context=cocoa
       when used with --gpu-api=opengl (use --vo=opengl-cb)
+    - rename --vo=opengl-cb to --vo=libmpv (goes in hand with the opengl-cb
+      API deprecation, see client-api-changes.rst)
     - make --deinterlace=yes always deinterlace, instead of trying to check
       certain unreliable video metadata. Also flip the defaults of all builtin
       HW deinterlace filters to always deinterlace.

DOCS/man/options.rst

@@ -5221,6 +5221,9 @@ The following video options are currently all specific to ``--vo=gpu`` and
     NOTE: On Windows, the default profile must be an ICC profile. WCS profiles
     are not supported.
 
+    Applications using libmpv with the render API need to provide the ICC
+    profile via ``MPV_RENDER_PARAM_ICC_PROFILE``.
+
 ``--icc-cache-dir=<dirname>``
     Store and load the 3D LUTs created from the ICC profile in this directory.
     This can be used to speed up loading, since LittleCMS 2 can take a while to

DOCS/man/vo.rst

@@ -428,13 +428,14 @@ Available video output drivers are:
     ``--vo-image-outdir=<dirname>``
         Specify the directory to save the image files to (default: ``./``).
 
-``opengl-cb``
-    For use with libmpv direct OpenGL embedding. As a special case, on OS X it
+``libmpv``
+    For use with libmpv direct embedding. As a special case, on OS X it
     is used like a normal VO within mpv (cocoa-cb). Otherwise useless in any
     other contexts.
-    (See ``<mpv/opengl_cb.h>``.)
+    (See ``<mpv/render.h>``.)
 
-    This also supports many of the options the ``gpu`` VO has.
+    This also supports many of the options the ``gpu`` VO has, depending on the
+    backend.
 
 ``rpi`` (Raspberry Pi)
     Native video output on the Raspberry Pi using the MMAL API.

libmpv/client.h

@@ -210,7 +210,7 @@ extern "C" {
  * relational operators (<, >, <=, >=).
  */
 #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL)
-#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 27)
+#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 28)
 
 /**
  * The API user is allowed to "#define MPV_ENABLE_DEPRECATED 0" before
@@ -1691,23 +1691,34 @@ int mpv_get_wakeup_pipe(mpv_handle *ctx);
  */
 void mpv_wait_async_requests(mpv_handle *ctx);
 
+#if MPV_ENABLE_DEPRECATED
+
+/**
+ * @deprecated use render.h
+ */
 typedef enum mpv_sub_api {
     /**
      * For using mpv's OpenGL renderer on an external OpenGL context.
      * mpv_get_sub_api(MPV_SUB_API_OPENGL_CB) returns mpv_opengl_cb_context*.
      * This context can be used with mpv_opengl_cb_* functions.
      * Will return NULL if unavailable (if OpenGL support was not compiled in).
      * See opengl_cb.h for details.
+     *
+     * @deprecated use render.h
      */
     MPV_SUB_API_OPENGL_CB = 1
 } mpv_sub_api;
 
 /**
  * This is used for additional APIs that are not strictly part of the core API.
  * See the individual mpv_sub_api member values.
+ *
+ * @deprecated use render.h
  */
 void *mpv_get_sub_api(mpv_handle *ctx, mpv_sub_api sub_api);
 
+#endif
+
 #ifdef __cplusplus
 }
 #endif

libmpv/mpv.def

@@ -28,6 +28,12 @@ mpv_opengl_cb_report_flip
 mpv_opengl_cb_render
 mpv_opengl_cb_set_update_callback
 mpv_opengl_cb_uninit_gl
+mpv_render_context_create
+mpv_render_context_free
+mpv_render_context_render
+mpv_render_context_report_swap
+mpv_render_context_set_parameter
+mpv_render_context_set_update_callback
 mpv_request_event
 mpv_request_log_messages
 mpv_resume

libmpv/opengl_cb.h

@@ -18,6 +18,10 @@
 
 #include "client.h"
 
+#if !MPV_ENABLE_DEPRECATED
+#error "This header and all API provided by it is deprecated. Use render.h instead."
+#else
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -27,6 +31,9 @@ extern "C" {
  * Overview
  * --------
  *
+ * Warning: this API is deprecated. A very similar API is provided by render.h
+ * and render_gl.h. The deprecated API is emulated with the new API.
+ *
  * This API can be used to make mpv render into a foreign OpenGL context. It
  * can be used to handle video display.
  *
@@ -328,7 +335,6 @@ int mpv_opengl_cb_init_gl(mpv_opengl_cb_context *ctx, const char *exts,
  */
 int mpv_opengl_cb_draw(mpv_opengl_cb_context *ctx, int fbo, int w, int h);
 
-#if MPV_ENABLE_DEPRECATED
 /**
  * Deprecated. Use mpv_opengl_cb_draw(). This function is equivalent to:
  *
@@ -341,7 +347,6 @@ int mpv_opengl_cb_draw(mpv_opengl_cb_context *ctx, int fbo, int w, int h);
  * was never marked as stable).
  */
 int mpv_opengl_cb_render(mpv_opengl_cb_context *ctx, int fbo, int vp[4]);
-#endif
 
 /**
  * Tell the renderer that a frame was flipped at the given time. This is
@@ -375,4 +380,6 @@ int mpv_opengl_cb_uninit_gl(mpv_opengl_cb_context *ctx);
 }
 #endif
 
+#endif /* else #if MPV_ENABLE_DEPRECATED */
+
 #endif