From 46c499d02a6803421a04ef5ebb5f4077c968da3d Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 10 Oct 2015 15:44:27 +0200 Subject: DOCS/client_api_examples/README: rewrite The new one is much more detailed. Also add part of it to the libmpv doxygen. --- DOCS/client_api_examples/README.md | 107 +++++++++++++++++++++++++++++++------ libmpv/client.h | 16 ++++++ 2 files changed, 106 insertions(+), 17 deletions(-) diff --git a/DOCS/client_api_examples/README.md b/DOCS/client_api_examples/README.md index 013098bf14..d2d28d029e 100644 --- a/DOCS/client_api_examples/README.md +++ b/DOCS/client_api_examples/README.md @@ -1,35 +1,108 @@ -Client API examples -=================== +# Client API examples All these examples use the mpv client API through libmpv. -cocoa ------ +## Where are the docs? + +The libmpv C API is documented directly in the header files (on normal Unix +systems, this is in `/usr/include/mpv/client.h`. + +libmpv merely gives you access to mpv's command interface, which is documented +here: +* Options (`mpv_set_option()` and friends): http://mpv.io/manual/master/#options +* Commands (`mpv_command()` and friends): http://mpv.io/manual/master/#list-of-input-commands +* Properties (`mpv_set_property()` and friends): http://mpv.io/manual/master/#properties + +Essentially everything is done with them, including loading a file, retrieving +playback progress, and so on. + +## Methods of embedding the video window + +All of these examples concentrate on how to integrate mpv's video renderers +with your own GUI. This is generally the hardest part. libmpv enforces a +somewhat efficient video output method, rather than e.g. returning a RGBA +surface in memory for each frame. The latter would be prohibitively inefficient, +because it would require conversion on the CPU. The goal is also not requiring +the API users to reinvent their own video rendering/scaling/presentation +mechanisms. + +There are currently 2 methods of embedding video. + +### Native window embedding + +This uses the platform's native method of nesting multiple windows. For example, +Linux/X11 can nest a window from a completely different process. The nested +window can redraw contents on its own, and receive user input if the user +interacts with this window. + +libmpv lets you specify a parent window for its own video window via the `wid` +option. Then libmpv will create its window with your window as parent, and +render its video inside of it. + +This method is highly OS-dependent. Some behavior is OS-specific. There are +problems with focusing on X11 (the ancient X11 focus policy mismatches with +that of modern UI toolkits - it's normally worked around, but this is not +easily possible with raw window embedding). It seems to have stability problems +on OSX when using the Qt toolkit. + +### OpenGL embedding + +This method lets you use libmpv's OpenGL renderer directly. You create an +OpenGL context, and then use `mpv_opengl_cb_draw()` to render the video on +each frame. + +This is more complicated, because libmpv will work directly on your own OpenGL +state. It's also not possible to have mpv automatically receive user input. +You will have to simulate this with the `mouse`/`keypress`/`keydown`/`keyup` +commands. + +You also get much more flexibility. For example, you can actually render your +own OSD on top of the video, something that is not possible with raw window +embedding. + +### Which one to use? + +Due to the various platform-specific behavior and problems (in particular on +OSX), OpenGL embedding is recommended. If you're not comfortable with requiring +OpenGL, or want to support "direct" video output such as vdpau (which might +win when it comes to performance and energy-saving), you should probably +support both methods if possible. + +## List of examples + +### cocoa Shows how to embed the mpv video window in Objective-C/Cocoa. -qt --- +### cocoa-openglcb + +Similar to the cocoa sample, but shows how to integrate mpv's OpenGL renderer +using libmpv's opengl-cb API. Since it does not require complicated interaction +with Cocoa elements from different libraries, it's more robust. + +### qt Shows how to embed the mpv video window in Qt (using normal desktop widgets). -qml ---- +### qml -Shows how to use mpv's OpenGL video renderer in QtQuick2 with QML. +Shows how to use mpv's OpenGL video renderer in QtQuick2 with QML. Uses the +opengl-cb API for video. Since it does not rely on embedding "foreign" native +Windows, it's usually more robust, potentially faster, and it's easier to +control how your GUI interacts with the video. It's trivial to create OSD +overlays with QML-native graphical elements as well. -qml_direct ----------- +### qml_direct Alternative example, which typically avoids a FBO indirection. Might be -slightly faster, but is less flexible and harder to use. +slightly faster, but is less flexible and harder to use. Uses the +opengl-cb API for video. -sdl ---- +### sdl -Show how to embed the mpv OpenGL renderer in SDL. +Show how to embed the mpv OpenGL renderer in SDL. Uses the opengl-cb API for +video. -simple ------- +### simple Very primitive terminal-only example. Shows some most basic API usage. diff --git a/libmpv/client.h b/libmpv/client.h index af583d9571..fb4f379626 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -49,6 +49,22 @@ extern "C" { * 2) Using mpv as a library with mpv_create(). This basically allows embedding * mpv in other applications. * + * Documentation + * ------------- + * + * The libmpv C API is documented directly in this header. Note that most + * actual interaction with this player is done through + * options/commands/properties, which can be accessed through this API. + * Essentially everything is done with them, including loading a file, + * retrieving playback progress, and so on. + * + * These are documented elsewhere: + * * http://mpv.io/manual/master/#options + * * http://mpv.io/manual/master/#list-of-input-commands + * * http://mpv.io/manual/master/#properties + * + * You can also look at the examples in DOCS/client_api_examples/. + * * Event loop * ---------- * -- cgit v1.2.3