summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2013-09-30 22:27:37 +0200
committerwm4 <wm4@nowhere>2013-10-05 22:46:55 +0200
commitae9a3e33aafaa0d708d54e2c42a563e45dadb0f7 (patch)
treedcdd7a4ee2e1b6456c69b02a90a15fad410fbff3 /DOCS
parentfd49edccf811de0d6c61f30d8b2b524f8df93b36 (diff)
downloadmpv-ae9a3e33aafaa0d708d54e2c42a563e45dadb0f7.tar.bz2
mpv-ae9a3e33aafaa0d708d54e2c42a563e45dadb0f7.tar.xz
command: add commands for displaying overlays
Requested by github issue #255. Does not work where mmap is not available (i.e. Windows).
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/man/en/input.rst71
1 files changed, 71 insertions, 0 deletions
diff --git a/DOCS/man/en/input.rst b/DOCS/man/en/input.rst
index a0014c51bd..c2ba45a61c 100644
--- a/DOCS/man/en/input.rst
+++ b/DOCS/man/en/input.rst
@@ -325,6 +325,77 @@ Input Commands that are Possibly Subject to Change
``disable_section "<section>"``
Disable the named input section. Undoes ``enable_section``.
+``overlay_add <id> <x> <y> "<file>" <offset> "<fmt>" <w> <h> <stride>``
+ Add an OSD overlay sourced from raw data. This might be useful for scripts
+ and applications controlling mpv, and which want to display things on top
+ of the video window.
+
+ Overlays are usually displayed in screen resolution, but with some VOs,
+ the resolution is reduced to that of the video's. You can read the
+ ``osd-width`` and ``osd-height`` properties. At least with ``--vo-xv`` and
+ anamorphic video (such as DVD), ``osd-par`` should be read as well, and the
+ overlay should be aspect-compensated. (Future directions: maybe mpv should
+ take care of some of these things automatically, but it's hard to tell
+ where to draw the line.)
+
+ ``id`` is an integer between 0 and 63 identifying the overlay element. The
+ ID can be used to add multiple overlay parts, update a part by using this
+ command with an already existing ID, or to remove a part with
+ ``overlay_remove``. Using a previously unused ID will add a new overlay,
+ while reusing an ID will update it. (Future directions: there should be
+ something to ensure different programs wanting to create overlays don't
+ conflict with each others, should that ever be needed.)
+
+ ``x`` and ``y`` specify the position where the OSD should be displayed.
+
+ ``file`` specifies the file the raw image data is read from. It can be
+ either a numeric UNIX file descriptor prefixed with ``@`` (e.g. ``@4``),
+ or a filename. The file will be mapped into memory with ``mmap()``. Some VOs
+ will pass the mapped pointer directly to display APIs (e.g. opengl or
+ vdpau), so no actual copying is involved. Truncating the source file while
+ the overlay is active will crash the player. You shouldn't change the data
+ while the overlay is active, because the data is essentially accessed at
+ random points. Instead, call ``overlay_add`` again (preferably with a
+ different memory region to prevent tearing).
+
+ ``offset`` is the offset of the first pixel in the source file. It is
+ passed directly to ``mmap`` and is subject to certain restrictions
+ (see ``man mmap`` for details). In particular, this value has to be a
+ multiple of the system's page size.
+
+ ``fmt`` is a string identifying the image format. Currently, only ``bgra``
+ is defined. This format has 4 bytes per pixels, with 8 bits per component.
+ The least significant 8 bits are blue, and the most significant 8 bits
+ are alpha (in little endian, the components are B-G-R-A, with B as first
+ byte). This uses premultiplied alpha: every color component is already
+ multiplied with the alpha component. This means the numeric value of each
+ component is equal to or smaller than the alpha component. (Violating this
+ rule will lead to different results with different VOs: numeric overflows
+ resulting from blending broken alpha values is considered something that
+ shouldn't happen, and consequently implementations don't ensure that you
+ get predictable behavior in this case.)
+
+ ``w``, ``h``, and ``stride`` specify the size of the overlay. ``w`` is the
+ visible width of the overlay, while ``stride`` gives the width in bytes in
+ memory. In the simple case, and with the ``bgra`` format, ``stride==4*w``.
+ In general, the total amount of memory accessed is ``stride * h``.
+ (Technically, the minimum size would be ``stride * (h - 1) + w * 4``, but
+ for simplicity, the player will access all ``stride * h`` bytes.)
+
+ .. admonition:: Warning
+
+ When updating the overlay, you should prepare a second shared memory
+ region (e.g. make use of the offset parameter) and add this as overlay,
+ instead of reusing the same memory every time. Otherwise, you might
+ get the equivalent of tearing, when your application and mpv write/read
+ the buffer at the same time. Also, keep in mind that mpv might access
+ an overlay's memory at random times whenever it feels the need to do
+ so, for example when redrawing the screen.
+
+``overlay_remove <id>``
+ Remove an overlay added with ``overlay_add`` and the same ID. Does nothing
+ if no overlay with this ID exists.
+
Undocumented commands: ``tv_start_scan``, ``tv_step_channel``, ``tv_step_norm``,
``tv_step_chanlist``, ``tv_set_channel``, ``tv_last_channel``, ``tv_set_freq``,
``tv_step_freq``, ``tv_set_norm``, ``dvb_set_channel``, ``radio_step_channel``,