drm: rename plane options to better, invariant, names

This commit bumps the libmpv version to 1.102

drm-osd-plane -> drm-draw-plane
drm-video-plane -> drm-drmprime-video-plane
drm-osd-size -> drm-draw-surface-size

"draw plane", as in the plane that OpenGL draws to, whether it be
video + OSD or just OSD.

"drmprime video plane", as in the plane used for hwdec video imported
via drmprime.

"draw surface size", as in the size of the surface used for the draw plane

The new names are invariant whether or not hwdec_drmprime_drm is being
used or not. The original naming was very confusing, as when doing
regular rendering (swdec or vaapi) the video would be displayed on the
"OSD plane", and the "Video plane" would remain unused.

3 files changed, 44 insertions, 20 deletions

diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst
index cb80d0a698..6197e48a39 100644
--- a/DOCS/client-api-changes.rst
+++ b/DOCS/client-api-changes.rst
@@ -31,6 +31,9 @@ API changes
 ===========
 
 ::
+ --- mpv 0.30.0 ---
+ 1.102  - rename struct mpv_opengl_drm_osd_size to mpv_opengl_drm_draw_surface_size
+        - rename MPV_RENDER_PARAM_DRM_OSD_SIZE to MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE
 
  --- mpv 0.29.0 ---
  1.101  - add MPV_RENDER_PARAM_ADVANCED_CONTROL and related API
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index f7ed1597ab..26f39beba7 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -20,9 +20,16 @@ Interface changes
 ::
 
  --- mpv 0.30.0 ---
-    - the `--drm-osd-plane-id` and `--drm-video-plane-id`
+    - rename `--drm-osd-plane-id` to `--drm-draw-plane`, `--drm-video-plane-id` to
+      `--drm-drmprime-video-plane` and `--drm-osd-size` to `--drm-draw-surface-size`
+      to better reflect what the options actually control, that the values they
+      accept aren't actually internal DRM ID's (like with similar options in
+      ffmpeg's KMS support), and that the video plane is only used when the drmprime
+      overlay hwdec interop is active, with the video being drawn to the draw plane
+      otherwise.
+    - in addition to the above, the `--drm-draw-plane` and `--drm-drmprime-video-plane`
       options now accept either an integer index, or the values primary or overlay.
-      `--drm-osd-plane-id` now defaults to primary and `--drm-video-plane-id`
+      `--drm-draw-plane` now defaults to primary and `--drm-drmprime-video-plane`
       defaults to overlay. This should be similar to previous behavior on most drivers
       due to how planes are usually sorted.
     - rename --opensles-frames-per-buffer to --opensles-frames-per-enqueue to
diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
index a3cc328b1d..69e4341b44 100644
--- a/DOCS/man/vo.rst
+++ b/DOCS/man/vo.rst
@@ -488,21 +488,28 @@ Available video output drivers are:
         Mode ID to use (resolution and frame rate).
         (default: 0)
 
-    ``--drm-osd-plane-id=<primary|overlay|N>``
-        Select the DRM plane to use for OSD (or OSD and video). The plane can be
-        specified as ``primary``, which will pick the first applicable primary
-        plane; ``overlay``, which will pick the first applicable overlay plane;
-        or by index. The index is zero based, and related to the CRTC. When using
-        this option with the drm_prime renderer, it will only affect the OSD
-        contents. Otherwise it will set OSD & video plane.
+    ``--drm-draw-plane=<primary|overlay|N>``
+        Select the DRM plane to which video and OSD is drawn to, under normal
+        circumstances. The plane can be specified as ``primary``, which will
+        pick the first applicable primary plane; ``overlay``, which will pick
+        the first applicable overlay plane; or by index. The index is zero
+        based, and related to the CRTC.
         (default: primary)
 
-    ``--drm-video-plane-id=<primary|overlay|N>``
-        Select the DRM plane index to use for video layer. This option accepts
-        the same values as ``--drm-osd-plane-id``. This option has an effect
-        only when using the drm_prime renderer (which supports several layers)
-        together with ``vo=gpu`` and ``gpu-context=drm``.
-        (default: overlay)
+        When using this option with the drmprime-drm hwdec interop, only the OSD
+        is rendered to this plane.
+
+    ``--drm-drmprime-video-plane=<primary|overlay|N>``
+        Select the DRM plane to use for video with the drmprime-drm hwdec
+        interop (used by e.g. the rkmpp hwdec on RockChip SoCs, and v4l2 hwdec:s
+        on various other SoC:s). The plane is unused otherwise. This option
+        accepts the same values as ``--drm-draw-plane``. (default: overlay)
+
+        To be able to successfully play 4K video on various SoCs you might need
+        to set ``--drm-draw-plane=overlay --drm-drmprime-video-plane=primary``
+        and setting ``--drm-draw-surface-size=1920x1080``, to render the OSD at a
+        lower resolution (the video when handled by the hwdec will be on the
+        drmprime-video plane and at full 4K resolution)
 
     ``--drm-format=<xrgb8888|xrgb2101010>``
         Select the DRM format to use (default: xrgb8888). This allows you to
@@ -517,11 +524,18 @@ Available video output drivers are:
         This currently only has an effect when used together with the ``drm``
         backend for the ``gpu`` VO. The ``drm`` VO always uses xrgb8888.
 
-    ``--drm-osd-size=<[WxH]>``
-        Sets the OSD OpenGL size to the specified size. OSD will then be upscaled
-        to the current screen resolution. This option can be useful when using
-        several layers in high resolutions with a GPU which cannot handle it.
-        Note : this option is only available with DRM atomic support.
+    ``--drm-draw-surface-size=<[WxH]>``
+        Sets the size of the surface used on the draw plane. The surface will
+        then be upscaled to the current screen resolution. This option can be
+        useful when used together with the drmprime-drm hwdec interop at high
+        resolutions, as it allows scaling the draw plane (which in this case
+        only handles the OSD) down to a size the GPU can handle.
+
+        When used without the drmprime-drm hwdec interop this option will just
+        cause the video to get rendered at a different resolution and then
+        scaled to screen size.
+
+        Note: this option is only available with DRM atomic support.
         (default: display resolution)
 
 ``mediacodec_embed`` (Android)