mpv_opengl_cb_window_pos

Overview

Warning: this API is deprecated. A very similar API is provided by render.h
and render_gl.h. The deprecated API is emulated with the new API.

This API can be used to make mpv render into a foreign OpenGL context. It
can be used to handle video display.

The renderer needs to be explicitly initialized with mpv_opengl_cb_init_gl(),
and then video can be drawn with mpv_opengl_cb_draw(). The user thread can
be notified by new frames with mpv_opengl_cb_set_update_callback().

You can output and embed video without this API 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 opengl-cb API is recommended,
because window embedding can cause various issues, especially with GUI
toolkits and certain platforms.

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_draw 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 and later and OpenGL ES version 2.0 and later are supported. With OpenGL 2.1, the GL_ARB_texture_rg is required. The renderer was written for the OpenGL 3.x core profile, with additional support for OpenGL 2.1 and OpenGL ES 2.0.

Note that some hardware decoding interop API (as set with the "hwdec" option) may actually access some sort of host API, such as EGL.

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 glViewport state
     - the glScissor state (but GL_SCISSOR_TEST is in its default value)
     - glBlendFuncSeparate() state (but GL_BLEND is in its default value)
     - glClearColor() state
     - mpv may overwrite the callback set with glDebugMessageCallback()
     - mpv always disables GL_DITHER at init

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 clash. Also, legacy state
must be either in its defaults, or not interfere with core state.

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 cores created by mpv_create()) - 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()

Context and handle lifecycle

Video initialization will fail if the OpenGL context was not initialized yet
(with mpv_opengl_cb_init_gl()). Likewise, mpv_opengl_cb_uninit_gl() will
disable video.

When the mpv core is destroyed (e.g. via mpv_terminate_destroy()), the OpenGL
context must have been uninitialized. If this doesn happen, undefined
behavior will result.

Hardware decoding

Hardware decoding via opengl_cb is fully supported, but requires some additional setup. (At least if direct hardware decoding modes are wanted, instead of copying back surface data from GPU to CPU RAM.)

While "normal" mpv loads the OpenGL hardware decoding interop on demand, this can't be done with opengl_cb for internal technical reasons. Instead, it loads them by default, even if hardware decoding is not going to be used. In older mpv releases, this had to be done by setting the "opengl-hwdec-interop" or "hwdec-preload" options before calling mpv_opengl_cb_init_gl(). You can still use the newer "gpu-hwdec-interop" option to prevent loading of interop, or to load only a specific interop.

There may be certain requirements on the OpenGL implementation: - Windows: ANGLE is required (although in theory GL/DX interop could be used) - Intel/Linux: EGL is required, and also a glMPGetNativeDisplay() callback must be provided (see sections below) - nVidia/Linux: Both GLX and EGL should work (GLX is required if vdpau is used, e.g. due to old drivers.) - OSX: CGL is required (CGLGetCurrentContext() returning non-NULL) - iOS: EAGL is required (EAGLContext.currentContext returning non-nil)

Once these things are setup, hardware decoding can be enabled/disabled at any time by setting the "hwdec" property.

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.