command: add osd-dimensions property

This "bundles" all OSD properties. It also makes some previously
Lua-only values available (Lua has mp.get_osd_margins(), unsure if
anything uses it).

The main intention is actually to allow retrieving all fields in an
"atomic" way. (Could introduce a mechanism on the level of the mpv
client API to do this, but doing ti ad-hoc all the time like this commit
is easier.)

1 files changed, 31 insertions, 0 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index d6430581a8..75709d1adf 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -2177,9 +2177,40 @@ Property list
     ``overlay-add`` command. It gives you the actual OSD size, which can be
     different from the window size in some cases.
 
+    Alias to ``osd-dimensions/w`` and ``osd-dimensions/h``.
+
 ``osd-par``
     Last known OSD display pixel aspect (can be 0).
 
+    Alias to ``osd-dimensions/osd-par``.
+
+``osd-dimensions``
+    Last known OSD dimensions.
+
+    Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE``
+    or Lua table with ``mp.get_property_native``):
+
+    ``w``
+        Size of the VO window in OSD render units (usually pixels, but may be
+        scaled pixels with VOs like ``xv``).
+
+    ``h``
+        Size of the VO window in OSD render units,
+
+    ``par``
+        Pixel aspect ratio of the OSD (usually 1).
+
+    ``aspect``
+        Display aspect ratio of the VO window. (Computing from the properties
+        above.)
+
+    ``mt``, ``mb``, ``ml``, ``mr``
+        OSD to video margins (top, bottom, left, right). This describes the
+        area into which the video is rendered.
+
+    Any of these properties may be unavailable or set to dummy values if the
+    VO window is not created or visible.
+
 ``sub-text``
     Return the current subtitle text regardless of sub visibility.
     Formatting is stripped. If the subtitle is not text-based