From 7a76b577d85ddc8f9e255b1a1c195ee88b76a7d8 Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Fri, 6 Mar 2020 18:20:11 +0100
Subject: command: extend osd-overlay command with bounds reporting

This is more or less a minimal hack to make _some_ text measurement
functionality available to scripts. Since libass does not support such a
thing, this simply uses the bounding box of the rendered text.

This is far from ideal. Problems include:
- using a bitmap bounding box
- additional memory waste and/or flushing caches
- dependency on window size
- odd small deviations with different window sizes (run osd-test.lua and
  resize the window after each timer update; the bounding boxes aren't
  adjusted in an overly useful way)
- inability to query the size _after_ actual rendering

But I guess it's a start. Since I'm aware that it's crap, add a threat
to the manpage that this may be changed/removed again. For now, I'm
interested whether anyone will have use for it in its current form, as
it's an often requested feature.
---
 DOCS/man/input.rst | 25 +++++++++++++++++++++++++
 DOCS/man/lua.rst   |  1 +
 2 files changed, 26 insertions(+)

(limited to 'DOCS/man')

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index a6f77dff0a..651ae7f645 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -1019,6 +1019,31 @@ Input Commands that are Possibly Subject to Change
         It's possible that future mpv versions will randomly change how Z order
         between different OSD formats and builtin OSD is handled.
 
+    ``hidden``
+        If set to ``yes``/true, do not display this (default: no).
+
+    ``compute_bounds``
+        If set to ``yes``/true, attempt to determine bounds and write them to
+        the command's result value as ``x0``, ``x1``, ``y0``, ``y1`` rectangle
+        (default: no). If the rectangle is empty, not known, or somehow
+        degenerate, it is not set. ``x1``/``y1`` is the coordinate of the bottom
+        exclusive corner of the rectangle.
+
+        The result value may depend on the VO window size, and is based on the
+        last known window size at the time of the call. This means the results
+        may be different from what is actually rendered.
+
+        For ``ass-events``, the result rectangle is recomputed to ``PlayRes``
+        coordinates (``res_x``/``res_y``). If window size is not known, a
+        fallback is chosen.
+
+        You should be aware that this mechanism is very inefficient, as it
+        renders the full result, and then uses the bounding box of the rendered
+        bitmap list (even if ``hidden`` is set). It will flush various caches.
+        Its results also depend on the used libass version.
+
+        This feature is experimental, and may change in some way again.
+
     Note: always use named arguments (``mpv_command_node()``). Scripts should
     use the ``mp.create_osd_overlay()`` helper instead of invoking this command
     directly.
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index a9fc02ed44..92debe8a75 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -599,6 +599,7 @@ are useful only in special situations.
     ``update()``
         Commit the OSD overlay to the screen, or in other words, run the
         ``osd-overlay`` command with the current fields of the overlay table.
+        Returns the result of the ``osd-overlay`` command itself.
 
     ``remove()``
         Remove the overlay from the screen. A ``update()`` call will add it
-- 
cgit v1.2.3