diff options
Diffstat (limited to 'DOCS')
| -rw-r--r-- | DOCS/client-api-changes.rst | 19 | ||||
| -rw-r--r-- | DOCS/interface-changes.rst | 16 | ||||
| -rw-r--r-- | DOCS/man/af.rst | 6 | ||||
| -rw-r--r-- | DOCS/man/input.rst | 87 | ||||
| -rw-r--r-- | DOCS/man/lua.rst | 10 | ||||
| -rw-r--r-- | DOCS/man/mpv.rst | 16 | ||||
| -rw-r--r-- | DOCS/man/options.rst | 111 | ||||
| -rw-r--r-- | DOCS/man/osc.rst | 4 | ||||
| -rw-r--r-- | DOCS/man/vf.rst | 20 | ||||
| -rw-r--r-- | DOCS/man/vo.rst | 282 | ||||
| -rw-r--r-- | DOCS/mplayer-changes.rst | 3 |
11 files changed, 471 insertions, 103 deletions
diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst index f2cc5993eb..8ef01a05e1 100644 --- a/DOCS/client-api-changes.rst +++ b/DOCS/client-api-changes.rst @@ -32,6 +32,25 @@ API changes :: + --- mpv 0.17.1 --- + 1.21 - mpv_set_property() changes behavior with MPV_FORMAT_NODE. Before this + change it rejected mpv_nodes with format==MPV_FORMAT_STRING if the + property was not a string or did not have special mechanisms in place + the function failed. Now it always invokes the option string parser, + and mpv_node with a basic data type works exactly as if the function + is invoked with that type directly. This new behavior is equivalent + to mpv_set_option(). + This also affects the mp.set_property_native() Lua function. + - generally, setting choice options/properties with "yes"/"no" options + can now be set as MPV_FORMAT_FLAG + - reading a choice property as MPV_FORMAT_NODE will now return a + MPV_FORMAT_FLAG value if the choice is "yes" (true) or "no" (false) + This implicitly affects Lua and JSON IPC interfaces as well. + - big changes to vo-cmdline on vo_opengl and vo_opengl_hq (but not + vo_opengl_cb): options are now normally not reset, but applied on top + of the current options. The special undocumented value "-" still + works, but now resets all options to before any vo-cmdline command + has been called. --- mpv 0.12.0 --- 1.20 - deprecate "GL_MP_D3D_interfaces"/"glMPGetD3DInterface", and introduce "GL_MP_MPGetNativeDisplay"/"glMPGetNativeDisplay" (this is a diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index ee6e135808..7ffbbd60e0 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -19,6 +19,22 @@ Interface changes :: + --- mpv 0.17.1 --- + - now ab-loops are active even if one of the "ab-loop-a"/"-b" properties is + unset ("no"), in which case the start of the file is used if the A loop + point is unset, and the end of the file for an unset B loop point + - deprecate --sub-ass=no option by --ass-style-override=strip + (also needs --embeddedfonts=no) + - add "hwdec-interop" and "hwdec-current" properties + - deprecated "hwdec-active" and "hwdec-detected" properties (to be removed + in mpv 0.19.0) + - choice option/property values that are "yes" or "no" will now be returned + as booleans when using the mpv_node functions in the client API, the + "native" property accessors in Lua, and the JSON API. They can be set as + such as well. + - the VO opengl fbo-format sub-option does not accept "rgb" or "rgba" + anymore + - all VO opengl prescalers have been removed (replaced by user scripts) --- mpv 0.17.0 --- - deprecate "track-list/N/audio-channels" property (use "track-list/N/demux-channel-count" instead) diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst index be90f09b62..8fe60250fb 100644 --- a/DOCS/man/af.rst +++ b/DOCS/man/af.rst @@ -70,7 +70,7 @@ Available filters are: Set AVOptions on the SwrContext or AVAudioResampleContext. These should be documented by FFmpeg or Libav. -``lavcac3enc[=tospdif[:bitrate[:minch]]]`` +``lavcac3enc[=options]`` Encode multi-channel audio to AC-3 at runtime using libavcodec. Supports 16-bit native-endian input format, maximum 6 channels. The output is big-endian when outputting a raw AC-3 stream, native-endian when @@ -103,6 +103,10 @@ Available filters are: If the input channel number is less than ``<minch>``, the filter will detach itself (default: 3). + ``encoder=<name>`` + Select the libavcodec encoder used. Currently, this should be an AC-3 + encoder, and using another codec will fail horribly. + ``equalizer=g1:g2:g3:...:g10`` 10 octave band graphic equalizer, implemented using 10 IIR band-pass filters. This means that it works regardless of what type of audio is diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 241f6740fb..d58f2dc4d5 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -634,10 +634,10 @@ Input Commands that are Possibly Subject to Change Send a message to all clients, and pass it the following list of arguments. What this message means, how many arguments it takes, and what the arguments mean is fully up to the receiver and the sender. Every client receives the - message, so be careful about name clashes (or use ``script_message_to``). + message, so be careful about name clashes (or use ``script-message-to``). ``script-message-to "<target>" "<arg1>" "<arg2>" ...`` - Same as ``script_message``, but send it only to the client named + Same as ``script-message``, but send it only to the client named ``<target>``. Each client (scripts etc.) has a unique name. For example, Lua scripts can get their name via ``mp.get_script_name()``. @@ -651,8 +651,8 @@ Input Commands that are Possibly Subject to Change separator, e.g. ``script_binding scriptname/bindingname``. For completeness, here is how this command works internally. The details - could change any time. On any matching key event, ``script_message_to`` - or ``script_message`` is called (depending on whether the script name is + could change any time. On any matching key event, ``script-message-to`` + or ``script-message`` is called (depending on whether the script name is included), with the following arguments: 1. The string ``key-binding``. @@ -1081,8 +1081,8 @@ Property list "default" MPV_FORMAT_FLAG ``ab-loop-a``, ``ab-loop-b`` (RW) - Set/get A-B loop points. See corresponding options and ``ab_loop`` command. - The special value ``no`` on either of these properties disables looping. + Set/get A-B loop points. See corresponding options and ``ab-loop`` command + for details. ``angle`` (RW) Current DVD angle. @@ -1349,6 +1349,9 @@ Property list ``colormatrix-primaries`` (R) See ``colormatrix``. +``taskbar-progress`` (RW) + See ``--taskbar-progress``. + ``ontop`` (RW) See ``--ontop``. @@ -1385,14 +1388,39 @@ Property list properties to see whether this was successful. Unlike in mpv 0.9.x and before, this does not return the currently active - hardware decoder. + hardware decoder. Since mpv 0.17.1, ``hwdec-current`` is available for + this purpose. + +``hwdec-current`` + Return the current hardware decoding in use. If decoding is active, return + one of the values used by the ``hwdec`` option/property. ``no`` indicates + software decoding. If no decoder is loaded, the property is unavailable. + +``hwdec-interop`` + This returns the currently loaded hardware decoding/output interop driver. + This is known only once the VO has opened (and possibly later). With some + VOs (like ``opengl``), this might be never known in advance, but only when + the decoder attempted to create the hw decoder successfully. (Using + ``--hwdec-preload`` can load it eagerly.) If there are multiple drivers + loaded, they will be separated by ``,``. + + If no VO is active or no interop driver is known, this property is + unavailable. + + This does not necessarily use the same values as ``hwdec``. There can be + multiple interop drivers for the same hardware decoder, depending on + platform and VO. ``hwdec-active`` + Deprecated. To be removed in mpv 0.19.0. Use ``hwdec-current`` instead. + Return ``yes`` or ``no``, depending on whether any type of hardware decoding is actually in use. ``hwdec-detected`` - If software decoding is active, this returns the hardware decoder in use. + Deprecated. To be removed in mpv 0.19.0. + + If hardware decoding is active, this returns the hardware decoder in use. Otherwise, it returns either ``no``, or if applicable, the currently loaded hardware decoding API. This is known only once the VO has opened (and possibly later). With some VOs (like ``opengl``), this is never known in @@ -1646,6 +1674,9 @@ Property list Current position on playlist. The first entry is on position 0. Writing to the property will restart playback at the written entry. +``playlist-pos-1`` (RW) + Same as ``playlist-pos``, but 1-based. + ``playlist-count`` Number of total playlist entries. @@ -1787,9 +1818,11 @@ Property list "albumart" MPV_FORMAT_FLAG "default" MPV_FORMAT_FLAG "forced" MPV_FORMAT_FLAG + "selected" MPV_FORMAT_FLAG "external" MPV_FORMAT_FLAG "external-filename" MPV_FORMAT_STRING "codec" MPV_FORMAT_STRING + "ff-index" MPV_FORMAT_INT64 "decoder-desc" MPV_FORMAT_STRING "demux-w" MPV_FORMAT_INT64 "demux-h" MPV_FORMAT_INT64 @@ -1904,6 +1937,44 @@ Property list whether the video window is visible. If the ``--force-window`` option is used, this is usually always returns ``yes``. +``vo-performance`` + Some video output performance metrics. Not implemented by all VOs. This has + a number of sup-properties, of the form ``vo-performance/<metric>-<value>``, + all of them in milliseconds. + + ``<metric>`` refers to one of: + + ``upload`` + Time needed to make the frame available to the GPU (if necessary). + ``render`` + Time needed to perform all necessary video postprocessing and rendering + passes (if necessary). + ``present`` + Time needed to present a rendered frame on-screen. + + When a step is unnecessary or skipped, it will have the value 0. + + ``<value>`` refers to one of: + + ``last`` + Last measured value. + ``avg`` + Average over a fixed number of past samples. (The exact timeframe + varies, but it should generally be a handful of seconds) + ``peak`` + The peak (highest value) within this averaging range. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_MAP + "<metric>-<value>" MPV_FORMAT_INT64 + + (One entry for each ``<metric>`` and ``<value>`` combination) + ``video-bitrate``, ``audio-bitrate``, ``sub-bitrate`` Bitrate values calculated on the packet level. This works by dividing the bit size of all packets between two keyframes by their presentation diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 6b2c5af031..b0d66c1760 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -350,6 +350,10 @@ The ``mp`` module is preloaded, although it can be loaded manually with with ``add_timeout()``), this starts the timer from the beginning, using the initially configured timeout. + ``is_enabled()`` + Whether the timer is currently enabled or was previously disabled + (e.g. by ``stop()`` or ``kill()``). + ``timeout`` (RW) This field contains the current timeout period. This value is not updated as time progresses. It's only used to calculate when the @@ -454,9 +458,9 @@ are useful only in special situations. The level is a string, see ``msg.log`` for allowed log levels. ``mp.register_script_message(name, fn)`` - This is a helper to dispatch ``script_message`` or ``script_message_to`` - invocations to Lua functions. ``fn`` is called if ``script_message`` or - ``script_message_to`` (with this script as destination) is run + This is a helper to dispatch ``script-message`` or ``script-message-to`` + invocations to Lua functions. ``fn`` is called if ``script-message`` or + ``script-message-to`` (with this script as destination) is run with ``name`` as first parameter. The other parameters are passed to ``fn``. If a message with the given name is already registered, it's overwritten. diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index ea0681c5ae..736ef02c48 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -320,11 +320,22 @@ example, paths starting with ``-`` will be interpreted as options. Likewise, if a path contains the sequence ``://``, the string before that might be interpreted as protocol prefix, even though ``://`` can be part of a legal UNIX path. To avoid problems with arbitrary paths, you should be sure that -absolute paths passed to mpv start with ``/``, and relative paths with ``./``. +absolute paths passed to mpv start with ``/``, and prefix relative paths with +``./``. + +Using the ``file://`` pseudo-protocol is discouraged, because it involves +strange URL unescaping rules. The name ``-`` itself is interpreted as stdin, and will cause mpv to disable console controls. (Which makes it suitable for playing data piped to stdin.) +The special argument ``--`` can be used to stop mpv from interpreting the +following arguments as options. + +When using the client API, you should strictly avoid using ``mpv_command_string`` +for invoking the ``loadfile`` command, and instead prefer e.g. ``mpv_command`` +to avoid the need for filename escaping. + For paths passed to suboptions, the situation is further complicated by the need to escape special characters. To work this around, the path can be additionally wrapped in the fixed-length syntax, e.g. ``%n%string_of_length_n`` @@ -715,6 +726,9 @@ PROTOCOLS ``memory://data`` Use the ``data`` part as source data. +``hex://data`` + Like ``memory://``, but the string is interpreted as hexdump. + PSEUDO GUI MODE =============== diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 18ac7fd2f0..a42d87912b 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -261,8 +261,13 @@ Playback Control ``--ab-loop-a=<time>``, ``--ab-loop-b=<time>`` Set loop points. If playback passes the ``b`` timestamp, it will seek to the ``a`` timestamp. Seeking past the ``b`` point doesn't loop (this is - intentional). The loop-points can be adjusted at runtime with the - corresponding properties. See also ``ab_loop`` command. + intentional). + + If both options are set to ``no``, looping is disabled. Otherwise, the + start/end of the file is used if one of the options is set to ``no``. + + The loop-points can be adjusted at runtime with the corresponding + properties. See also ``ab-loop`` command. ``--ordered-chapters``, ``--no-ordered-chapters`` Enabled by default. @@ -576,6 +581,7 @@ Video :no: always use software decoding (default) :auto: see below + :auto-copy: see below :vdpau: requires ``--vo=vdpau`` or ``--vo=opengl`` (Linux only) :vaapi: requires ``--vo=opengl`` or ``--vo=vaapi`` (Linux only) :vaapi-copy: copies video back into system RAM (Linux with Intel GPUs only) @@ -583,7 +589,9 @@ Video :dxva2: requires ``--vo=opengl:backend=angle`` or ``--vo=opengl:backend=dxinterop`` (Windows only) :dxva2-copy: copies video back to system RAM (Windows only) - :d3d11va-copy: experimental (Windows only) + :d3d11va: requires ``--vo=opengl:backend=angle`` (Windows only) + :d3d11va-copy: copies video back to system RAM (Windows only) + :mediacodec: copies video back to system RAM (Android only) :rpi: requires ``--vo=rpi`` (Raspberry Pi only - default if available) ``auto`` tries to automatically enable hardware decoding using the first @@ -593,6 +601,13 @@ Video work, it will always fall back to software decoding, instead of trying the next method (might matter on some Linux systems). + ``auto-copy`` selects only modes that copy the video data back to system + memory after decoding. Currently, this selects only one of the following + modes: ``vaapi-copy``, ``dxva2-copy``, ``d3d11va-copy``, ``mediacodec``. + If none of these work, hardware decoding is disabled. This mode is always + guaranteed to incur no additional loss compared to software decoding, and + will allow CPU processing with video filters. + The ``vaapi`` mode, if used with ``--vo=opengl``, requires Mesa 11 and most likely works with Intel GPUs only. It also requires the opengl EGL backend (automatically used if available). You can also try the old GLX backend by @@ -614,6 +629,46 @@ Video codecs. See ``--hwdec-codecs`` to enable hardware decoding for more codecs. + .. admonition:: Quality reduction with hardware decoding + + Normally, hardware decoding does not reduce video quality (at least for + the codecs h264 and HEVC). However, due to restrictions in video output + APIs, there can be some loss, or blatantly incorrect results. + + In some cases, RGB conversion is forced, which means the RGB conversion + is performed by the hardware decoding API, instead of the OpenGL code + used by ``--vo=opengl``. This means certain obscure colorspaces may + not display correctly, and not certain filtering (such as debanding) + can not be applied in an ideal way. + + ``vdpau`` is usually safe. If deinterlacing enabled (or the ``vdpaupp`` + video filter is active in general), it forces RGB conversion. The latter + currently does not treat certain colorspaces like BT.2020 correctly + (which is mostly a mpv-specific restriction). If the ``vdpauprb`` + retrieves image data without RGB conversion, but does not work with + postprocessing. + + ``vaapi`` is safe if the ``vaapi-egl`` backend is indicated in the logs. + If ``vaapi-glx`` is indicated, and the video colorspace is either BT.601 + or BT.709, a forced but correct RGB conversion is performed. Otherwise, + the result will be incorrect. + + ``d3d11va`` is usually safe (if used with ANGLE builds that support + ``EGL_KHR_stream path`` - otherwise, it converts to RGB), except that + 10 bit input (HEVC main 10 profiles) will be rounded down to 8 bits. + + ``dxva2`` is not safe. It appears to always use BT.601 for forced RGB + conversion, but actual behavior depends on the GPU drivers. Some drivers + appear to convert to limited range RGB, which gives a faded appearance. + In addition to driver-specific behavior, global system settings might + affect this additionally. This can give incorrect results even with + completely ordinary video sources. + + All other methods, in particular the copy-back methods (like + ``dxva2-copy`` etc.) are either fully safe, or not worse than software + decoding. In particular, ``auto-copy`` will only select safe modes + (although potentially slower than other methods). + ``--hwdec-preload=<api>`` This is useful for the ``opengl`` and ``opengl-cb`` VOs for creating the hardware decoding OpenGL interop context, but without actually enabling @@ -1423,7 +1478,7 @@ Subtitles Using this option may lead to incorrect subtitle rendering. -``--ass-style-override=<yes|no|force>`` +``--ass-style-override=<yes|no|force|signfs|strip>`` Control whether user style overrides should be applied. :yes: Apply all the ``--ass-*`` style override options. Changing the default @@ -1433,6 +1488,8 @@ Subtitles :no: Render subtitles as forced by subtitle scripts. :force: Try to force the font style as defined by the ``--sub-text-*`` options. Can break rendering easily. + :strip: Radically strip all ASS tags and styles from the subtitle. This + is equivalent to the old ``--no-ass`` / ``--no-sub-ass`` options. ``--ass-force-margins`` Enables placing toptitles and subtitles in black borders when they are @@ -1529,6 +1586,13 @@ Subtitles ``--sub-ass``, ``--no-sub-ass`` Render ASS subtitles natively (enabled by default). + .. note:: + + This has been deprecated by ``--ass-style-override=strip``. You also + may need ``--embeddedfonts=no`` to get the same behavior. Also, + using ``--ass-style-override=force`` should give better results + without breaking subtitles too much. + If ``--no-sub-ass`` is specified, all tags and style declarations are stripped and ignored on display. The subtitle renderer uses the font style as specified by the ``--sub-text-`` options instead. @@ -1539,10 +1603,6 @@ Subtitles rendering of ASS/SSA subtitles. It can sometimes be useful to forcibly override the styling of ASS subtitles, but should be avoided in general. - .. note:: - - Try using ``--ass-style-override=force`` instead. - ``--sub-auto=<no|exact|fuzzy|all>``, ``--no-sub-auto`` Load additional subtitle files matching the video filename. The parameter specifies how external subtitle files are matched. ``exact`` is enabled by @@ -1783,6 +1843,12 @@ Window mode can be used to create the window always on program start, but this may cause other issues. +``--taskbar-progress``, ``--no-taskbar-progress`` + (Windows only) + Enable/disable playback progress rendering in taskbar (Windows 7 and above). + + Enabled by default. + ``--ontop`` Makes the player window stay on top of other windows. @@ -1794,6 +1860,12 @@ Window Play video with window border and decorations. Since this is on by default, use ``--no-border`` to disable the standard window decorations. +``--fit-border``, ``--no-fit-border`` + (Windows only) Fit the whole window with border and decorations on the + screen. Since this is on by default, use ``--no-fit-border`` to make mpv + try to only fit client area with video on the screen. This behavior only + applied to window/video with size exceeding size of the screen. + ``--on-all-workspaces`` (X11 only) Show the video window on all virtual desktops. @@ -1885,7 +1957,7 @@ Window Make the window width 70% of the screen size, keeping aspect ratio. ``1000`` Set the window width to 1000 pixels, keeping aspect ratio. - ``70%:60%`` + ``70%x60%`` Make the window as large as possible, without being wider than 70% of the screen width, or higher than 60% of the screen height. @@ -1972,7 +2044,7 @@ Window .. admonition:: Example for GNOME screensaver - ``mpv --heartbeat-cmd="gnome-screensaver-command -p" file`` + ``mpv --heartbeat-cmd="gnome-screensaver-command --deactivate" file`` ``--heartbeat-interval=<sec>`` @@ -2068,9 +2140,17 @@ Window This option might be removed in the future. -``--x11-bypass-compositor=<yes|no>`` +``--x11-bypass-compositor=<yes|no|fs-only|never>`` If set to ``yes``, then ask the compositor to unredirect the mpv window - (default: no). This uses the ``_NET_WM_BYPASS_COMPOSITOR`` hint. + (default: ``fs-only``). This uses the ``_NET_WM_BYPASS_COMPOSITOR`` hint. + + ``fs-only`` asks the window manager to disable the compositor only in + fullscreen mode. + + ``no`` sets ``_NET_WM_BYPASS_COMPOSITOR`` to 0, which is the default value + as declared by the EWMH specification, i.e. no change is done. + + ``never`` asks the window manager to never disable the compositor. Disc Devices @@ -3524,7 +3604,7 @@ Miscellaneous frame dropping due to the audio "overshooting" and skipping multiple video frames before the sync logic can react. -``--video-sync-adrop-size=<value`` +``--video-sync-adrop-size=<value>`` For the ``--video-sync=display-adrop`` mode. This mode duplicates/drops audio data to keep audio in sync with video. To avoid audio artifacts on jitter (which would add/remove samples all the time), this is done in @@ -3597,7 +3677,7 @@ Miscellaneous - A label of the form ``aidN`` selects audio track N as input (e.g. ``aid1``). - A label of the form ``vidN`` selects video track N as input. - - A label named ``ao`` will be connected to the audio input. + - A label named ``ao`` will be connected to the audio output. - A label named ``vo`` will be connected to the video output. Each label can be used only once. If you want to use e.g. an audio stream @@ -3634,4 +3714,5 @@ Miscellaneous - ``null:// --lavfi-complex='life [vo]'`` Conways' Life Game. - See the FFmpeg libavfilter documentation for details on the filter. + See the FFmpeg libavfilter documentation for details on the available + filters. diff --git a/DOCS/man/osc.rst b/DOCS/man/osc.rst index 587b8104d2..c737d2e898 100644 --- a/DOCS/man/osc.rst +++ b/DOCS/man/osc.rst @@ -266,6 +266,6 @@ Example You could put this into ``input.conf`` to hide the OSC with the ``a`` key and to set auto mode (the default) with ``b``:: - a script_message osc-visibility never - b script_message osc-visibility auto + a script-message osc-visibility never + b script-message osc-visibility auto diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst index faca4114a9..b4e4438f78 100644 --- a/DOCS/man/vf.rst +++ b/DOCS/man/vf.rst @@ -303,13 +303,22 @@ Available filters are: Available gamma functions are: :auto: automatic selection (default) - :bt.1886: ITU-R BT.1886 (approximation of BT.601/BT.709/BT.2020 curve) + :bt.1886: ITU-R BT.1886 (EOTF corresponding to BT.601/BT.709/BT.2020) :srgb: IEC 61966-2-4 (sRGB) :linear: Linear light :gamma1.8: Pure power curve (gamma 1.8) :gamma2.2: Pure power curve (gamma 2.2) :gamma2.8: Pure power curve (gamma 2.8) :prophoto: ProPhoto RGB (ROMM) curve + :st2084: SMPTE ST2084 (HDR) curve + + ``<peak>`` + Reference peak illumination for the video file. This is mostly + interesting for HDR, but it can also be used tone map SDR content + to a darker or brighter exposure. + + The default of 0.0 will default to the display's reference brightness + for SDR and the source's reference brightness for HDR. ``<stereo-in>`` Set the stereo mode the video is assumed to be encoded in. Takes the @@ -800,6 +809,15 @@ Available filters are: This filter must be specified before ``vdpaupp`` in the filter chain if ``vdpaupp`` is used. +``d3d11vpp`` + Direct3D 11 video post processing. Currently requires D3D11 hardware + decoding for use. + + ``deint=<yes|no>`` + Whether deinterlacing is enabled (default: no). + ``interlaced-only=<yes|no>`` + If ``yes`` (default), only deinterlace frames marked as interlaced. + ``buffer=<num>`` Buffer ``<num>`` frames in the filter chain. This filter is probably pretty useless, except for debugging. (Note that this won't help to smooth out diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index 18e3f4ae64..bdc317fc8f 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -582,68 +582,6 @@ Available video output drivers are: better than without it) since it will extend the size to match only the milder of the scale factors between the axes. - ``prescale-luma=<filter>`` - Apply additional pre-scaling (image doubling) on the luma plane - (if present). As the name implies, these will run before the main - upscaling pass. - - ``none`` - Disable all prescalers. This is the default. - - ``superxbr`` - A relatively fast prescaler originally developed for pixel art. - - Some parameters can be tuned with ``superxbr-sharpness`` and - ``superxbr-edge-strength`` options. - - ``nnedi3`` - An artificial neural network based deinterlacer, which can be used - to upscale images. - - Extremely slow and requires a recent mid or high end graphics card - to work smoothly (as of 2015). - - ``prescale-passes=<1..5>`` - The number of passes to apply the prescaler (defaults to be 1). Setting - it to 2 will perform a 4x upscaling. - - ``prescale-downscaling-threshold=<0..32>`` - This option prevents "overkill" use of prescalers, which can be caused - by misconfiguration, or user trying to play a video with much larger - size. With this option, user can specify the maximal allowed downscaling - ratio in both dimension. To satisfy it, the number of passes for - prescaler will be reduced, and if necessary prescaler could also be - disabled. - - The default value is 2.0, and should be able to prevent most seemingly - unreasonable use of prescalers. Most user would probably want to set it - to a smaller value between 1.0 and 1.5 for better performance. - - A value less than 1.0 will disable the check. - - ``nnedi3-neurons=<16|32|64|128>`` - Specify the neurons for nnedi3 prescaling (defaults to be 32). The - rendering time is expected to be linear to the number of neurons. - - ``nnedi3-window=<8x4|8x6>`` - Specify the size of local window for sampling in nnedi3 prescaling - (defaults to be ``8x4``). The ``8x6`` window produces sharper images, - but is also slower. - - ``nnedi3-upload=<ubo|shader>`` - Specify how to upload the NN weights to GPU. Depending on the graphics - card, driver, shader compiler and nnedi3 settings, both method can be - faster or slower. - - ``ubo`` - Upload these weights via uniform buffer objects. This is the - default. (requires OpenGL 3.1 / GLES 3.0) - - ``shader`` - Hard code all the weights into the shader source code. (requires - OpenGL 3.3 / GLES 3.0) - - ``pre-shaders=<files>``, ``post-shaders=<files>``, ``scale-shader=<file>`` Custom GLSL fragment shaders. @@ -700,6 +638,152 @@ Available video output drivers are: return vec4(1.0 - color.rgb, color.a); } + ``user-shaders=<files>`` + Custom GLSL hooks. These are similar to ``post-shaders`` etc., but more + flexible: They can be injected at almost arbitrary points in the + rendering pipeline, and access all previous intermediate textures. + + .. admonition:: Warning + + The syntax is not stable yet and may change any time. + + The general syntax of a user shader looks like this:: + + //!METADATA ARGS... + //!METADATA ARGS... + + vec4 hook() { + ... + return something; + } + + //!METADATA ARGS... + //!METADATA ARGS... + + ... + + Each block of metadata, along with the non-metadata lines after it, + defines a single pass. Each pass can set the following metadata: + + HOOK <name> (required) + The texture which to hook into. May occur multiple times within a + metadata block, up to a predetermined limit. See below for a list + of hookable textures. + + BIND <name> + Loads a texture and makes it available to the pass, and sets up + macros to enable accessing it. See below for a list of set macros. + By default, no textures are bound. The special name HOOKED can be + used to refer to the texture that triggered this pass. + + SAVE <name> + Gives the name of the texture to save the result of this pass + into. By default, this is set to the special name HOOKED which has + the effect of overwriting the hooked texture. + + WIDTH <szexpr>, HEIGHT <szexpr> + Specifies the size of the resulting texture for this pass. + ``szexpr`` refers to an expression in RPN (reverse polish + notation), using the operators + - * / > < !, floating point + literals, and references to sizes of existing texture and OUTPUT + (such as MAIN.width or CHROMA.height). By default, these are set to + HOOKED.w and HOOKED.h, respectively. + + WHEN <szexpr> + Specifies a condition that needs to be true (non-zero) for the + shader stage to be evaluated. If it fails, it will silently be + omitted. (Note that a shader stage like this which has a dependency + on an optional hook point can still cause that hook point to be + saved, which has some minor overhead) + + OFFSET ox oy + Indicates a pixel shift (offset) introduced by this pass. These + pixel offsets will be accumulated and corrected during the + next scaling pass (``cscale`` or ``scale``). The default values + are 0 0 which correspond to no shift. Note that offsets are ignored + when not overwriting the hooked texture. + + COMPONENTS n + Specifies how many components of this pass's output are relevant + and should be stored in the texture, up to 4 (rgba). By default, + this value is equal to the number of components in HOOKED. + + Each bound texture (via ``BIND``) will make available the following + definitions to that shader pass, where NAME is the name of the bound + texture: + + vec4 NAME_tex(vec2 pos) + The sampling function to use to access the texture at a certain + spot (in texture coordinate space, range [0,1]). This takes care + of any necessary normalization conversions. + vec4 NAME_texOff(vec2 offset) + Sample the texture at a certain offset in pixels. This works like + NAME_tex but additionally takes care of necessary rotations, so + that sampling at e.g. vec2(-1,0) is always one pixel to the left. + vec2 NAME_pos + The local texture coordinate of that texture, range [0,1]. + vec2 NAME_size + The (rotated) size in pixels of the texture. + mat2 NAME_rot + The rotation matrix associated with this texture. (Rotates + pixel space to texture coordinates) + vec2 NAME_pt + The (unrotated) size of a single pixel, range [0,1]. + sampler NAME_raw + The raw bound texture itself. The use of this should be + avoided unless absolutely necessary. + + In addition, the global uniforms described in ``post-shaders`` are + also available. + + Internally, vo_opengl may generate any number of the following + textures. Whenever a texture is rendered and saved by vo_opengl, all of + the passes that have hooked into it will run, in the order they were + added by the user. This is a list of the legal hook points: + + RGB, LUMA, CHROMA, ALPHA, XYZ (resizable) + Source planes (raw). Which of these fire depends on the image + format of the source. + + CHROMA_SCALED, ALPHA_SCALED (fixed) + Source planes (upscaled). These only fire on subsampled content. + + NATIVE (resizable) + The combined image, in the source colorspace, before conversion + to RGB. |