From 8fb0d2ee27d3e9026d37aa356acd43b567d3df17 Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Thu, 2 Mar 2017 05:53:05 +0100
Subject: client API: update outdated recommendations about window embedding

Basically, the opengl-cb API causes fewer issues, even if it's a bit
harder on the API user.

See #4197.
---
 libmpv/client.h | 30 +++++++++++++-----------------
 1 file changed, 13 insertions(+), 17 deletions(-)

(limited to 'libmpv/client.h')

diff --git a/libmpv/client.h b/libmpv/client.h
index 14777b429a..a016df691f 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -161,23 +161,19 @@ extern "C" {
  * Embedding the video window
  * --------------------------
  *
- * Currently you have to get the raw window handle, and set it as "wid" option.
- * 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).
- *
- * Setting the "input-vo-keyboard" may be required to get keyboard input
- * through the embedded window, if this is desired.
- *
- * For OpenGL integration (e.g. rendering video to a texture), a separate API
- * is available. Look at opengl_cb.h. This API does not include keyboard or
- * mouse input directly.
- *
- * Also see client API examples and the mpv manpage.
+ * Using the opengl-cb API (in opengl_cb.h) is recommended. This API requires
+ * you to create and maintain an OpenGL context, to which you can render
+ * video using a specific API call. This API does not include keyboard or mouse
+ * input directly.
+ *
+ * There is an older way to embed the native mpv window into your own. You have
+ * to get the raw window handle, and set it as "wid" option. This works on X11,
+ * win32, and OSX only. It's much easier to use than the opengl-cb API, but
+ * also has various problems.
+ *
+ * Also see client API examples and the mpv manpage. There is an extensive
+ * discussion here:
+ * https://github.com/mpv-player/mpv-examples/tree/master/libmpv#methods-of-embedding-the-video-window
  *
  * Compatibility
  * -------------
-- 
cgit v1.2.3