diff options
Diffstat (limited to 'libmpv')
| -rw-r--r-- | libmpv/client.h | 40 | ||||
| -rw-r--r-- | libmpv/mpv.def | 7 | ||||
| -rw-r--r-- | libmpv/opengl_cb.h | 199 |
3 files changed, 240 insertions, 6 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 diff --git a/libmpv/mpv.def b/libmpv/mpv.def index e8dc65db58..83ad9b315b 100644 --- a/libmpv/mpv.def +++ b/libmpv/mpv.def @@ -15,11 +15,16 @@ mpv_get_property mpv_get_property_async mpv_get_property_osd_string mpv_get_property_string +mpv_get_sub_api mpv_get_time_us mpv_get_wakeup_pipe mpv_initialize mpv_load_config_file mpv_observe_property +mpv_opengl_cb_init_gl +mpv_opengl_cb_render +mpv_opengl_cb_set_update_callback +mpv_opengl_cb_uninit_gl mpv_request_event mpv_request_log_messages mpv_resume @@ -33,4 +38,4 @@ mpv_suspend mpv_terminate_destroy mpv_unobserve_property mpv_wait_event -mpv_wakeup +mpv_wakeup
\ No newline at end of file diff --git a/libmpv/opengl_cb.h b/libmpv/opengl_cb.h new file mode 100644 index 0000000000..3f5010b26e --- /dev/null +++ b/libmpv/opengl_cb.h @@ -0,0 +1,199 @@ +/* Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +/* + * Note: the client API is licensed under ISC (see above) to ease + * interoperability with other licenses. But keep in mind that the + * mpv core is still mostly GPLv2+. It's up to lawyers to decide + * whether applications using this API are affected by the GPL. + * One argument against this is that proprietary applications + * using mplayer in slave mode is apparently tolerated, and this + * API is basically equivalent to slave mode. + */ + +#ifndef MPV_CLIENT_API_OPENGL_CB_H_ +#define MPV_CLIENT_API_OPENGL_CB_H_ + +#include "client.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Warning: this API is not stable yet. + * + * Overview + * -------- + * + * This API can be used to make mpv render into a foreign OpenGL context. It + * can be used to handle video display. Be aware that using this API is not + * required: you can embed the mpv window by setting the mpv "wid" option to + * a native window handle (see "Embedding the video window" section in the + * client.h header). In general, using the "wid" option is recommended over + * the OpenGL API, because it's simpler and more flexible on the mpv side. + * + * The renderer needs to be explicitly initialized with mpv_opengl_cb_init_gl(), + * and then video can be drawn with mpv_opengl_cb_render(). The user thread can + * be notified by new frames with mpv_opengl_cb_set_update_callback(). + * + * OpenGL interop + * -------------- + * + * This assumes the OpenGL context lives on a certain thread controlled by the + * API user. The following functions require access to the OpenGL context: + * mpv_opengl_cb_init_gl + * mpv_opengl_cb_render + * mpv_opengl_cb_uninit_gl + * + * The OpenGL context is indirectly accessed through the OpenGL function + * pointers returned by the get_proc_address callback in mpv_opengl_cb_init_gl. + * Generally, mpv will not load the system OpenGL library when using this API. + * + * Only "desktop" OpenGL version 2.1 or later is supported. With OpenGL 2.1, + * the GL_ARB_texture_rg is required. The renderer was written against + * OpenGL 3.x core profile, with additional support for OpenGL 2.1. + * + * Note that some hardware decoding interop API (as set with the "hwdec" option) + * may actually access + * + * OpenGL state + * ------------ + * + * OpenGL has a large amount of implicit state. All the mpv functions mentioned + * above expect that the OpenGL state is reasonably set to OpenGL standard + * defaults. Likewise, mpv will attempt to leave the OpenGL context with + * standard defaults. The following state is excluded from this: + * + * - the current viewport (can have/is set to an arbitrary value) + * + * Messing with the state could be avoided by creating shared OpenGL contexts, + * but this is avoided for the sake of compatibility and interoperability. + * + * On OpenGL 2.1, mpv will strictly call functions like glGenTextures() to + * create OpenGL objects. You will have to do the same. This ensures that + * objects created by mpv and the API users don't clash. + * + * Threading + * --------- + * + * The mpv_opengl_cb_* functions can be called from any thread, under the + * following conditions: + * - only one of the mpv_opengl_cb_* functions can be called at the same time + * (unless they belong to different mpv_handles) + * - for functions which need an OpenGL context (see above) the OpenGL context + * must be "current" in the current thread, and it must be the same context + * as used with mpv_opengl_cb_init_gl() + * - never can be called from within the callbacks set with + * mpv_set_wakeup_callback() or mpv_opengl_cb_set_update_callback() + */ + +/** + * Opaque context, returned by mpv_get_sub_api(MPV_SUB_API_OPENGL_CB). + * + * A context is bound to the mpv_handle it was retrieved from. The context + * will always be the same (for the same mpv_handle), and is valid until the + * mpv_handle it belongs to is released. + */ +typedef struct mpv_opengl_cb_context mpv_opengl_cb_context; + +typedef void (*mpv_opengl_cb_update_fn)(void *cb_ctx); +typedef void *(*mpv_opengl_cb_get_proc_address_fn)(void *fn_ctx, const char *name); + +/** + * Set the callback that notifies you when a new video frame is available, or + * if the video display configuration somehow changed and requires a redraw. + * Similar to mpv_set_wakeup_callback(), you must not call any mpv API from + * the callback. + * + * @param callback callback(callback_ctx) is called if the frame should be + * redrawn + * @param callback_ctx opaque argument to the callback + */ +void mpv_opengl_cb_set_update_callback(mpv_opengl_cb_context *ctx, + mpv_opengl_cb_update_fn callback, + void *callback_ctx); + +/** + * Initialize the mpv OpenGL state. This retrieves OpenGL function pointers via + * get_proc_address, and creates OpenGL objects needed by mpv internally. It + * will also call APIs needed for rendering hardware decoded video in OpenGL, + * according to the mpv "hwdec" option. + * + * You must free the associated state at some point by calling the + * mpv_opengl_cb_uninit_gl() function. Not doing so may result in memory leaks + * or worse. + * + * @param exts optional _additional_ extension string, can be NULL + * @param get_proc_address callback used to retrieve function pointers to OpenGL + * functions. This is used for both standard functions + * and extension functions. (The extension string is + * checked whether extensions are really available.) + * The callback will be called from this function only + * (it is not stored and never used later). + * @param get_proc_address_ctx arbitrary opaque user context passed to the + * get_proc_address callback + * @return error code (same as normal mpv_* API), including but not limited to: + * MPV_ERROR_UNSUPPORTED: the OpenGL version is not supported + * (or required extensions are missing) + * MPV_ERROR_INVALID_PARAMETER: the OpenGL state was already initialized + */ +int mpv_opengl_cb_init_gl(mpv_opengl_cb_context *ctx, const char *exts, + mpv_opengl_cb_get_proc_address_fn get_proc_address, + void *get_proc_address_ctx); + +/** + * Render video. Requires that the OpenGL state is initialized. + * + * The video will use the provided viewport rectangle as window size. Options + * like "panscan" are applied to determine which part of the video should be + * visible and how the video should be scaled. You can change these options + * at runtime by using the mpv property API. + * + * The renderer will reconfigure itself every time the output rectangle/size + * is changed. (If you want to do animations, it might be better to do the + * animation on a FBO instead.) + * + * @param fbo The framebuffer object to render on. Because the renderer might + * manage multiple FBOs internally for the purpose of video + * postprocessing, it will always bind and unbind FBOs itself. If + * you want mpv to render on the main framebuffer, pass 0. + * @param vp Viewport to render on. The renderer will essentially call: + * glViewport(vp[0], vp[1], vp[2], vp[3]); + * before rendering. The height (vp[3]) can be negative to flip the + * image - the renderer will flip it before setting the viewport + * (typically you want to flip the image if you are rendering + * directly to the main framebuffer). + * @return error code + */ +int mpv_opengl_cb_render(mpv_opengl_cb_context *ctx, int fbo, int vp[4]); + +/** + * Destroy the mpv OpenGL state. + * + * This will trigger undefined behavior (i.e. crash hard) if the hardware + * decoder is still active, because the OpenGL hardware decoding interop state + * can't be destroyed synchronously. If no hardware decoding is active, the + * state can be destroyed at any time. + * + * Calling this multiple times is ok. + * + * @return error code + */ +int mpv_opengl_cb_uninit_gl(mpv_opengl_cb_context *ctx); + +#ifdef __cplusplus +} +#endif + +#endif |