client API: rename GL_MP_D3D_interfaces

This is a pseudo-OpenGL extension for letting libmpv query native
windowing system handles from the API user. (It uses the OpenGL
extension mechanism because I'm lazy. In theory it would be nicer to let
the user pass them with mpv_opengl_cb_init_gl(), but this would require
a more intrusive API change to extend its argument list.)

The naming of the extension and associated function was unnecessarily
Windows specific (using "D3D"), even though it would work just fine for
other platforms. So deprecate the old names and introduce new ones. The
old ones still work.

DOCS/client-api-changes.rst

@@ -32,7 +32,12 @@ API changes
 
 ::
 
+ --- mpv 0.12.0 ---
+ 1.20   - deprecate "GL_MP_D3D_interfaces"/"glMPGetD3DInterface", and introduce
+          "GL_MP_MPGetNativeDisplay"/"glMPGetNativeDisplay" (this is a
+          backwards-compatible rename)
  --- mpv 0.11.0 ---
+ --- mpv 0.10.0 ---
  1.19   - add "GL_MP_D3D_interfaces" pseudo extension to make it possible to
           use DXVA2 in OpenGL fullscreen mode in some situations
         - mpv_request_log_messages() now accepts "terminal-default" as parameter

libmpv/client.h

@@ -198,7 +198,7 @@ extern "C" {
  * relational operators (<, >, <=, >=).
  */
 #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL)
-#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 19)
+#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 20)
 
 /**
  * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.

libmpv/opengl_cb.h

@@ -108,8 +108,26 @@ extern "C" {
  * context must have been uninitialized. If this doesn't happen, undefined
  * behavior will result.
  *
- * Special D3D interop considerations
+ * Special windowing system interop considerations
- * ----------------------------------
+ * ------------------------------------------------
+ *
+ * In some cases, libmpv needs to have access to the windowing system's handles.
+ * This can be a pointer to a X11 "Display" for example. Usually this is needed
+ * only for hardware decoding.
+ *
+ * You can communicate these handles to libmpv by adding a pseudo-OpenGL
+ * extension "GL_MP_MPGetNativeDisplay" to the additional extension string when
+ * calling mpv_opengl_cb_init_gl(). The get_proc_address callback should resolve
+ * a function named "glMPGetNativeDisplay", which has the signature:
+ *
+ *    void* GLAPIENTRY glMPGetNativeDisplay(const char* name)
+ *
+ * See below what names are defined. Usually, libmpv will use the native handle
+ * up until mpv_opengl_cb_uninit_gl() is called. If the name is not anything
+ * you know/expected, return NULL from the function.
+ *
+ * Windowing system interop on MS win32
+ * ------------------------------------
  *
  * If OpenGL switches to fullscreen, most players give it access GPU access,
  * which means DXVA2 hardware decoding in mpv won't work. This can be worked
@@ -117,14 +135,14 @@ extern "C" {
  * create a decoder. The device can be either the real device used for display,
  * or a "blank" device created before switching to fullscreen.
  *
- * You can do this by adding "GL_MP_D3D_interfaces" to the additional extension
+ * You can provide glMPGetNativeDisplay as described in the previous section.
- * string when calling mpv_opengl_cb_init_gl(). The get_proc_address callback
+ * If it is called with name set to "IDirect3DDevice9", it should return a
- * should resolve a function named "glMPGetD3DInterface", which has the
+ * IDirect3DDevice9 pointer (or NULL if not available). libmpv will release
- * signature: "void* __stdcall glMPGetD3DInterface(const char* name)". If
+ * this interface when it is done with it.
- * name is "IDirect3DDevice9", it should return a IDirect3DDevice9 pointer
+ *
- * (or NULL if not available). libmpv will release this interface when it is
+ * In previous libmpv releases, this used "GL_MP_D3D_interfaces" and
- * done with it (usually when mpv_opengl_cb_uninit_gl() is called). New
+ * "glMPGetD3DInterface". This is deprecated; use glMPGetNativeDisplay instead
- * interface names can be added in the future.
+ * (the semantics are 100% compatible).
  */
 
 /**

video/out/opengl/common.c

@@ -290,10 +290,18 @@ static const struct gl_functions gl_functions[] = {
     },
     // These don't exist - they are for the sake of mpv internals, and libmpv
     // interaction (see libmpv/opengl_cb.h).
+    {
+        .extension = "GL_MP_MPGetNativeDisplay",
+        .functions = (const struct gl_function[]) {
+            DEF_FN(MPGetNativeDisplay),
+            {0}
+        },
+    },
+    // Same, but using the old name.
     {
         .extension = "GL_MP_D3D_interfaces",
         .functions = (const struct gl_function[]) {
-            DEF_FN(MPGetD3DInterface),
+            DEF_FN_NAME(MPGetNativeDisplay, "glMPGetD3DInterface"),
             {0}
         },
     },

video/out/opengl/common.h

@@ -271,7 +271,7 @@ struct GL {
     void (GLAPIENTRY *DebugMessageCallback)(MP_GLDEBUGPROC callback,
                                             const void *userParam);
 
-    void *(GLAPIENTRY *MPGetD3DInterface)(const char *name);
+    void *(GLAPIENTRY *MPGetNativeDisplay)(const char *name);
 };
 
 #endif /* MPLAYER_GL_COMMON_H */

video/out/opengl/hwdec_dxva2.c

@@ -23,13 +23,13 @@ static void destroy(struct gl_hwdec *hw)
 static int create(struct gl_hwdec *hw)
 {
     GL *gl = hw->gl;
-    if (hw->hwctx || !gl->MPGetD3DInterface)
+    if (hw->hwctx || !gl->MPGetNativeDisplay)
         return -1;
 
     struct priv *p = talloc_zero(hw, struct priv);
     hw->priv = p;
 
-    p->ctx.d3d9_device = gl->MPGetD3DInterface("IDirect3DDevice9");
+    p->ctx.d3d9_device = gl->MPGetNativeDisplay("IDirect3DDevice9");
     if (!p->ctx.d3d9_device)
         return -1;