From ae9a3e33aafaa0d708d54e2c42a563e45dadb0f7 Mon Sep 17 00:00:00 2001 From: wm4 Date: Mon, 30 Sep 2013 22:27:37 +0200 Subject: command: add commands for displaying overlays Requested by github issue #255. Does not work where mmap is not available (i.e. Windows). --- DOCS/man/en/input.rst | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) (limited to 'DOCS') 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 "
"`` Disable the named input section. Undoes ``enable_section``. +``overlay_add "" "" `` + 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 `` + 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``, -- cgit v1.2.3