client API: expose OpenGL renderer

This adds API to libmpv that lets host applications use the mpv opengl
renderer. This is a more flexible (and possibly more portable) option to
foreign window embedding (via --wid).

This assumes that methods like context sharing and multithreaded OpenGL
rendering are infeasible, and that a way is needed to integrate it with
an application that uses a single thread to render everything.

Add an example that does this with QtQuick/qml. The example is
relatively lazy, but still shows how relatively simple the integration
is. The FBO indirection could probably be avoided, but would require
more work (and would probably lead to worse QtQuick integration, because
it would have to ignore transformations like rotation).

Because this makes mpv directly use the host application's OpenGL
context, there is no platform specific code involved in mpv, except
for hw decoding interop.

main.qml is derived from some Qt example.

The following things are still missing:
- a way to do better video timing
- expose GL renderer options, allow changing them at runtime
- support for color equalizer controls
- support for screenshots

1 files changed, 35 insertions, 5 deletions

diff --git a/libmpv/client.h b/libmpv/client.h
index 11b27b26df..9ed2cabd27 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -123,14 +123,15 @@ extern "C" {
  * --------------------------
  *
  * Currently you have to get the raw window handle, and set it as "wid" option.
- * This works on X11 and win32 only. In addition, it works with a few VOs only,
- * and VOs which do not support this will just create a freestanding window.
+ * This works on X11, win32, and OSX only. In addition, it works with a few VOs
+ * only, and VOs which do not support this will just create a freestanding
+ * window.
  *
  * Both on X11 and win32, the player will fill the window referenced by the
  * "wid" option fully and letterbox the video (i.e. add black bars if the
  * aspect ratio of the window and the video mismatch).
  *
- * On OSX, embedding is not yet possible, because Cocoa makes this non-trivial.
+ * Also see client API examples and the mpv manpage.
  *
  * Compatibility
  * -------------
@@ -164,7 +165,7 @@ extern "C" {
  * relational operators (<, >, <=, >=).
  */
 #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL)
-#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 10)
+#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 11)
 
 /**
  * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.
@@ -269,7 +270,16 @@ typedef enum mpv_error {
      * When trying to load the file, the file format could not be determined,
      * or the file was too broken to open it.
      */
-    MPV_ERROR_UNKNOWN_FORMAT    = -17
+    MPV_ERROR_UNKNOWN_FORMAT    = -17,
+    /**
+     * Generic error for signaling that certain system requirements are not
+     * fulfilled.
+     */
+    MPV_ERROR_UNSUPPORTED       = -18,
+    /**
+     * The API function which was called is a stub only.
+     */
+    MPV_ERROR_NOT_IMPLEMENTED   = -19
 } mpv_error;
 
 /**
@@ -437,6 +447,9 @@ void mpv_resume(mpv_handle *ctx);
  * with playback time. For example, playback could go faster or slower due to
  * playback speed, or due to playback being paused. Use the "time-pos" property
  * instead to get the playback status.
+ *
+ * Unlike other libmpv APIs, this can be called at absolutely any time (even
+ * within wakeup callbacks), as long as the context is valid.
  */
 int64_t mpv_get_time_us(mpv_handle *ctx);
 
@@ -1426,6 +1439,23 @@ void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d);
  */
 int mpv_get_wakeup_pipe(mpv_handle *ctx);
 
+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.
+     */
+    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.
+ */
+void *mpv_get_sub_api(mpv_handle *ctx, mpv_sub_api sub_api);
+
 #ifdef __cplusplus
 }
 #endif