vo_opengl_cb: deprecate mpv_opengl_cb_render()

Its vp parameter made no sense anymore. Introduce a new one.

DOCS/client-api-changes.rst

@@ -27,6 +27,7 @@ API changes
 
  --- mpv 0.9.0 will be released ---
  1.16   - add mpv_opengl_cb_report_flip()
+        - introduce mpv_opengl_cb_draw() and deprecate mpv_opengl_cb_render()
  1.15   - mpv_initialize() will now load config files. This requires setting
           the "config" and "config-dir" options. In particular, it will load
           mpv.conf.

DOCS/client_api_examples/qml/main.cpp

@@ -46,9 +46,8 @@ public:
     void render()
     {
         QOpenGLFramebufferObject *fbo = framebufferObject();
-        int vp[4] = {0, 0, fbo->width(), fbo->height()};
         window->resetOpenGLState();
-        mpv_opengl_cb_render(mpv_gl, fbo->handle(), vp);
+        mpv_opengl_cb_draw(mpv_gl, fbo->handle(), fbo->width(), fbo->height());
         window->resetOpenGLState();
     }
 };

DOCS/client_api_examples/qml_direct/main.cpp

@@ -39,15 +39,13 @@ void MpvRenderer::paint()
 {
     window->resetOpenGLState();
 
-    // Render to the whole window.
-    int vp[4] = {0, 0, size.width(), -size.height()};
-
     // This uses 0 as framebuffer, which indicates that mpv will render directly
     // to the frontbuffer. Note that mpv will always switch framebuffers
     // explicitly. Some QWindow setups (such as using QQuickWidget) actually
     // want you to render into a FBO in the beforeRendering() signal, and this
     // code won't work there.
-    mpv_opengl_cb_render(mpv_gl, 0, vp);
+    // The negation is used for rendering with OpenGL's flipped coordinates.
+    mpv_opengl_cb_draw(mpv_gl, 0, size.width(), -size.height());
 
     window->resetOpenGLState();
 }

libmpv/mpv.def

@@ -22,6 +22,7 @@ mpv_get_wakeup_pipe
 mpv_initialize
 mpv_load_config_file
 mpv_observe_property
+mpv_opengl_cb_draw
 mpv_opengl_cb_init_gl
 mpv_opengl_cb_report_flip
 mpv_opengl_cb_render

libmpv/opengl_cb.h

@@ -44,7 +44,7 @@ extern "C" {
  * 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
+ * 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().
  *
  * OpenGL interop
@@ -53,7 +53,7 @@ extern "C" {
  * 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_draw
  *      mpv_opengl_cb_uninit_gl
  *
  * The OpenGL context is indirectly accessed through the OpenGL function
@@ -172,30 +172,45 @@ int mpv_opengl_cb_init_gl(mpv_opengl_cb_context *ctx, const char *exts,
 /**
  * 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 video will use the full provided framebuffer. 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.)
  *
+ * This function implicitly pulls a video frame from the internal queue and
+ * renders it. If no new frame is available, the previous frame is redrawn.
+ * The update callback set with mpv_opengl_cb_set_update_callback() notifies
+ * you when a new frame was added.
+ *
  * @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(0, 0, 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).
- *           vp[0] and vp[1] should be set to 0.
- *           The viewport width and height imply the target FBO or framebuffer's
- *           size. It will always render to the full size of it.
+ * @param w Width of the framebuffer. This is either the video size if the fbo
+ *          parameter is 0, or the allocated size of the texture backing the
+ *          fbo. The renderer will always use the full size of the fbo.
+ * @param h Height of the framebuffer. Same as with the w parameter, except
+ *          that this parameter can be negative. In this case, the video
+ *          frame will be rendered flipped.
  * @return the number of left frames in the internal queue to be rendered
  */
+int mpv_opengl_cb_draw(mpv_opengl_cb_context *ctx, int fbo, int w, int h);
+
+/**
+ * Deprecated. Use mpv_opengl_cb_draw(). This function is equivalent to:
+ *
+ * int mpv_opengl_cb_render(mpv_opengl_cb_context *ctx, int fbo, int vp[4])
+ *  { return mpv_opengl_cb_draw(ctx, fbo, vp[2], vp[3]); }
+ *
+ * vp[0] and vp[1] used to have a meaning, but are ignored in newer versions.
+ *
+ * This function will be removed in the future without version bump (this API
+ * was never marked as stable).
+ */
 int mpv_opengl_cb_render(mpv_opengl_cb_context *ctx, int fbo, int vp[4]);
 
 /**

player/client.c

@@ -1705,7 +1705,7 @@ int mpv_opengl_cb_init_gl(mpv_opengl_cb_context *ctx, const char *exts,
 {
     return MPV_ERROR_NOT_IMPLEMENTED;
 }
-int mpv_opengl_cb_render(mpv_opengl_cb_context *ctx, int fbo, int vp[4])
+int mpv_opengl_cb_draw(mpv_opengl_cb_context *ctx, int fbo, int w, int h)
 {
     return MPV_ERROR_NOT_IMPLEMENTED;
 }
@@ -1719,6 +1719,11 @@ int mpv_opengl_cb_uninit_gl(mpv_opengl_cb_context *ctx)
 }
 #endif
 
+int mpv_opengl_cb_render(mpv_opengl_cb_context *ctx, int fbo, int vp[4])
+{
+    return mpv_opengl_cb_draw(ctx, fbo, vp[2], vp[3]);
+}
+
 void *mpv_get_sub_api(mpv_handle *ctx, mpv_sub_api sub_api)
 {
     if (!ctx->mpctx->initialized)

video/out/vo_opengl_cb.c

@@ -269,7 +269,7 @@ int mpv_opengl_cb_uninit_gl(struct mpv_opengl_cb_context *ctx)
     return 0;
 }
 
-int mpv_opengl_cb_render(struct mpv_opengl_cb_context *ctx, int fbo, int vp[4])
+int mpv_opengl_cb_draw(mpv_opengl_cb_context *ctx, int fbo, int vp_w, int vp_h)
 {
     assert(ctx->renderer);
 
@@ -281,7 +281,6 @@ int mpv_opengl_cb_render(struct mpv_opengl_cb_context *ctx, int fbo, int vp[4])
 
     ctx->force_update |= ctx->reconfigured;
 
-    int vp_w = vp[2], vp_h = vp[3];
     if (ctx->vp_w != vp_w || ctx->vp_h != vp_h)
         ctx->force_update = true;