diff options
Diffstat (limited to 'DOCS')
| -rw-r--r-- | DOCS/interface-changes.rst | 7 | ||||
| -rw-r--r-- | DOCS/man/options.rst | 799 | ||||
| -rw-r--r-- | DOCS/man/vo.rst | 849 |
3 files changed, 818 insertions, 837 deletions
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index 6d33c4afad..c4dfc5fe28 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -38,6 +38,13 @@ Interface changes - remove deprecated "hwdec-active" and "hwdec-detected" properties - remove "pre-shaders", "post-shaders" and "scale-shader": deprecated in favor of "user-shaders" + - remove all vo_opengl suboptions. Use global options with the same name + instead, e.g.: --vo=opengl:scale=nearest => --scale=nearest + Some options are prefixed with "opengl-", e.g. --opengl-pbo. + - remove --vo=opengl-hq. Set --profile=opengl-hq instead. Note that this + profile does not force the VO. This means if you use the --vo option to + set another VO, it won't work. But this also means it can be used with + opengl-cb. --- mpv 0.20.0 --- - add --image-display-duration option - this also means that image duration is not influenced by --mf-fps anymore in the general case (this is an diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index e723d5cbbe..a4310208c5 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -3597,6 +3597,805 @@ DVB Default: ``no`` +OpenGL renderer options +----------------------- + +The following video options are currently all specific to ``--vo=opengl`` and +``-vo=opengl-cb`` only, which are the only VOs that implement them. + +``--opengl-dumb-mode=<yes|no>`` + This mode is extremely restricted, and will disable most extended OpenGL + features. This includes high quality scalers and custom shaders! + + It is intended for hardware that does not support FBOs (including GLES, + which supports it insufficiently), or to get some more performance out of + bad or old hardware. + + This mode is forced automatically if needed, and this option is mostly + useful for debugging. It's also enabled automatically if nothing uses + features which require FBOs. + + This option might be silently removed in the future. + +``--scale=<filter>`` + + ``bilinear`` + Bilinear hardware texture filtering (fastest, very low quality). This + is the default for compatibility reasons. + + ``spline36`` + Mid quality and speed. This is the default when using ``opengl-hq``. + + ``lanczos`` + Lanczos scaling. Provides mid quality and speed. Generally worse than + ``spline36``, but it results in a slightly sharper image which is good + for some content types. The number of taps can be controlled with + ``scale-radius``, but is best left unchanged. + + (This filter is an alias for ``sinc``-windowed ``sinc``) + + ``ewa_lanczos`` + Elliptic weighted average Lanczos scaling. Also known as Jinc. + Relatively slow, but very good quality. The radius can be controlled + with ``scale-radius``. Increasing the radius makes the filter sharper + but adds more ringing. + + (This filter is an alias for ``jinc``-windowed ``jinc``) + + ``ewa_lanczossharp`` + A slightly sharpened version of ewa_lanczos, preconfigured to use an + ideal radius and parameter. If your hardware can run it, this is + probably what you should use by default. + + ``mitchell`` + Mitchell-Netravali. The ``B`` and ``C`` parameters can be set with + ``--scale-param1`` and ``--scale-param2``. This filter is very good at + downscaling (see ``--dscale``). + + ``oversample`` + A version of nearest neighbour that (naively) oversamples pixels, so + that pixels overlapping edges get linearly interpolated instead of + rounded. This essentially removes the small imperfections and judder + artifacts caused by nearest-neighbour interpolation, in exchange for + adding some blur. This filter is good at temporal interpolation, and + also known as "smoothmotion" (see ``--tscale``). + + ``linear`` + A ``--tscale`` filter. + + There are some more filters, but most are not as useful. For a complete + list, pass ``help`` as value, e.g.:: + + mpv --scale=help + +``--scale-param1=<value>``, ``--scale-param2=<value>`` + Set filter parameters. Ignored if the filter is not tunable. Currently, + this affects the following filter parameters: + + bcspline + Spline parameters (``B`` and ``C``). Defaults to 0.5 for both. + + gaussian + Scale parameter (``t``). Increasing this makes the result blurrier. + Defaults to 1. + + oversample + Minimum distance to an edge before interpolation is used. Setting this + to 0 will always interpolate edges, whereas setting it to 0.5 will + never interpolate, thus behaving as if the regular nearest neighbour + algorithm was used. Defaults to 0.0. + +``--scale-blur=<value>`` + Kernel scaling factor (also known as a blur factor). Decreasing this makes + the result sharper, increasing it makes it blurrier (default 0). If set to + 0, the kernel's preferred blur factor is used. Note that setting this too + low (eg. 0.5) leads to bad results. It's generally recommended to stick to + values between 0.8 and 1.2. + +``--scale-radius=<value>`` + Set radius for tunable filters, must be a float number between 0.5 and + 16.0. Defaults to the filter's preferred radius if not specified. Doesn't + work for every scaler and VO combination. + + Note that depending on filter implementation details and video scaling + ratio, the radius that actually being used might be different (most likely + being increased a bit). + +``--scale-antiring=<value>`` + Set the antiringing strength. This tries to eliminate ringing, but can + introduce other artifacts in the process. Must be a float number between + 0.0 and 1.0. The default value of 0.0 disables antiringing entirely. + + Note that this doesn't affect the special filters ``bilinear`` and + ``bicubic_fast``. + +``--scale-window=<window>`` + (Advanced users only) Choose a custom windowing function for the kernel. + Defaults to the filter's preferred window if unset. Use + ``--scale-window=help`` to get a list of supported windowing functions. + +``--scale-wparam=<window>`` + (Advanced users only) Configure the parameter for the window function given + by ``--scale-window``. Ignored if the window is not tunable. Currently, + this affects the following window parameters: + + kaiser + Window parameter (alpha). Defaults to 6.33. + blackman + Window parameter (alpha). Defaults to 0.16. + gaussian + Scale parameter (t). Increasing this makes the window wider. Defaults + to 1. + +``--scaler-lut-size=<4..10>`` + Set the size of the lookup texture for scaler kernels (default: 6). The + actual size of the texture is ``2^N`` for an option value of ``N``. So the + lookup texture with the default setting uses 64 samples. + + All weights are linearly interpolated from those samples, so increasing + the size of lookup table might improve the accuracy of scaler. + +``--scaler-resizes-only`` + Disable the scaler if the video image is not resized. In that case, + ``bilinear`` is used instead of whatever is set with ``--scale``. Bilinear + will reproduce the source image perfectly if no scaling is performed. + Enabled by default. Note that this option never affects ``--cscale``. + +``--opengl-pbo`` + Enable use of PBOs. On some drivers this can be faster, especially if the + source video size is huge (e.g. so called "4K" video). On other drivers it + might be slower or cause latency issues. + + In theory, this can sometimes lead to sporadic and temporary image + corruption (because reupload is not retried when it fails). + +``--dither-depth=<N|no|auto>`` + Set dither target depth to N. Default: no. + + no + Disable any dithering done by mpv. + auto + Automatic selection. If output bit depth cannot be detected, 8 bits per + component are assumed. + 8 + Dither to 8 bit output. + + Note that the depth of the connected video display device cannot be + detected. Often, LCD panels will do dithering on their own, which conflicts + with this option and leads to ugly output. + +``--dither-size-fruit=<2-8>`` + Set the size of the dither matrix (default: 6). The actual size of the + matrix is ``(2^N) x (2^N)`` for an option value of ``N``, so a value of 6 + gives a size of 64x64. The matrix is generated at startup time, and a large + matrix can take rather long to compute (seconds). + + Used in ``--dither=fruit`` mode only. + +``--dither=<fruit|ordered|no>`` + Select dithering algorithm (default: fruit). (Normally, the + ``--dither-depth`` option controls whether dithering is enabled.) + +``--temporal-dither`` + Enable temporal dithering. (Only active if dithering is enabled in + general.) This changes between 8 different dithering patterns on each frame + by changing the orientation of the tiled dithering matrix. Unfortunately, + this can lead to flicker on LCD displays, since these have a high reaction + time. + +``--temporal-dither-period=<1-128>`` + Determines how often the dithering pattern is updated when + ``--temporal-dither`` is in use. 1 (the default) will update on every video + frame, 2 on every other frame, etc. + +``--opengl-debug`` + Check for OpenGL errors, i.e. call ``glGetError()``. Also, request a + debug OpenGL context (which does nothing with current graphics drivers + as of this writing). + +``--interpolation`` + Reduce stuttering caused by mismatches in the video fps and display refresh + rate (also known as judder). + + .. warning:: This requires setting the ``--video-sync`` option to one + of the ``display-`` modes, or it will be silently disabled. + This was not required before mpv 0.14.0. + + This essentially attempts to interpolate the missing frames by convoluting + the video along the temporal axis. The filter used can be controlled using + the ``--tscale`` setting. + + Note that this relies on vsync to work, see ``--opengl-swapinterval`` for + more information. + +``--opengl-swapinterval=<n>`` + Interval in displayed frames between two buffer swaps. 1 is equivalent to + enable VSYNC, 0 to disable VSYNC. Defaults to 1 if not specified. + + Note that this depends on proper OpenGL vsync support. On some platforms + and drivers, this only works reliably when in fullscreen mode. It may also + require driver-specific hacks if using multiple monitors, to ensure mpv + syncs to the right one. Compositing window managers can also lead to bad + results, as can missing or incorrect display FPS information (see + ``--display-fps``). + +``--dscale=<filter>`` + Like ``--scale``, but apply these filters on downscaling instead. If this + option is unset, the filter implied by ``--scale`` will be applied. + +``--cscale=<filter>`` + As ``--scale``, but for interpolating chroma information. If the image is + not subsampled, this option is ignored entirely. + +``--tscale=<filter>`` + The filter used for interpolating the temporal axis (frames). This is only + used if ``--interpolation`` is enabled. The only valid choices for + ``--tscale`` are separable convolution filters (use ``--tscale=help`` to + get a list). The default is ``mitchell``. + + Note that the maximum supported filter radius is currently 3, due to + limitations in the number of video textures that can be loaded + simultaneously. + +``--tscale-clamp`` + Clamp the ``--tscale`` filter kernel's value range to [0-1]. This reduces + excessive ringing artifacts in the temporal domain (which typically + manifest themselves as short flashes or fringes of black, mostly around + moving edges) in exchange for potentially adding more blur. + +``--interpolation-threshold=<0..1,-1>`` + Threshold below which frame ratio interpolation gets disabled (default: + ``0.0001``). This is calculated as ``abs(disphz/vfps - 1) < threshold``, + where ``vfps`` is the speed-adjusted display FPS, and ``disphz`` the + display refresh rate. + + The default is intended to almost always enable interpolation if the + playback rate is even slightly different from the display refresh rate. But + note that if you use e.g. ``--video-sync=display-vdrop``, small deviations + in the rate can disable interpolation and introduce a discontinuity every + other minute. + + Set this to ``-1`` to disable this logic. + +``--dscale-radius``, ``--cscale-radius``, ``--tscale-radius``, etc. + Set filter parameters for ``--dscale``, ``--cscale`` and ``--tscale``, + respectively. + + See the corresponding options for ``--scale``. + +``--linear-scaling`` + Scale in linear light. It should only be used with a + ``--opengl-fbo-format`` that has at least 16 bit precision. + +``--correct-downscaling`` + When using convolution based filters, extend the filter size when + downscaling. Increases quality, but reduces performance while downscaling. + + This will perform slightly sub-optimally for anamorphic video (but still + better than without it) since it will extend the size to match only the + milder of the scale factors between the axes. + +``--opengl-shaders=<files>`` + Custom GLSL hooks. These are a flexible way to add custom fragment shaders, + which 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 to these parameters, the following uniforms are also globally + available: + + float random + A random number in the range [0-1], different per frame. + int frame + A simple count of frames rendered, increases by one per frame and never + resets (regardless of seeks). + vec2 image_size + The size in pixels of the input image. + vec2 target_size + The size in pixels of the visible part of the scaled (and possibly + cropped) image. + + 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. + + MAINPRESUB (resizable) + The image, after conversion to RGB, but before + ``--blend-subtitles=video`` is applied. + + MAIN (resizable) + The main image, after conversion to RGB but before upscaling. + + LINEAR (fixed) + Linear light image, before scaling. This only fires when + ``--linear-scaling`` is in effect. + + SIGMOID (fixed) + Sigmoidized light, before scaling. This only fires when + ``--sigmoid-upscaling`` is in effect. + + PREKERNEL (fixed) + The image immediately before the scaler kernel runs. + + POSTKERNEL (fixed) + The image immediately after the scaler kernel runs. + + SCALED (fixed) + The final upscaled image, before color management. + + OUTPUT (fixed) + The final output image, after color management but before dithering and + drawing to screen. + + Only the textures labelled with ``resizable`` may be transformed by the + pass. When overwriting a texture marked ``fixed``, the WIDTH, HEIGHT and + OFFSET must be left at their default values. + +``--deband`` + Enable the debanding algorithm. This greatly reduces the amount of visible + banding, blocking and other quantization artifacts, at the expensive of + very slightly blurring some of the finest details. In practice, it's + virtually always an improvement - the only reason to disable it would be + for performance. + +``--deband-iterations=<1..16>`` + The number of debanding steps to perform per sample. Each step reduces a + bit more banding, but takes time to compute. Note that the strength of each + step falls off very quickly, so high numbers (>4) are practically useless. + (Default 1) + +``--deband-threshold=<0..4096>`` + The debanding filter's cut-off threshold. Higher numbers increase the + debanding strength dramatically but progressively diminish image details. + (Default 64) + +``--deband-range=<1..64>`` + The debanding filter's initial radius. The radius increases linearly for + each iteration. A higher radius will find more gradients, but a lower + radius will smooth more aggressively. (Default 16) + + If you increase the ``--deband-iterations``, you should probably decrease + this to compensate. + +``--deband-grain=<0..4096>`` + Add some extra noise to the image. This significantly helps cover up + remaining quantization artifacts. Higher numbers add more noise. (Default + 48) + +``--sigmoid-upscaling`` + When upscaling, use a sigmoidal color transform to avoid emphasizing + ringing artifacts. This also implies ``--linear-scaling``. + +``--sigmoid-center`` + The center of the sigmoid curve used for ``--sigmoid-upscaling``, must be a + float between 0.0 and 1.0. Defaults to 0.75 if not specified. + +``--sigmoid-slope`` + The slope of the sigmoid curve used for ``--sigmoid-upscaling``, must be a + float between 1.0 and 20.0. Defaults to 6.5 if not specified. + +``--sharpen=<value>`` + If set to a value other than 0, enable an unsharp masking filter. Positive + values will sharpen the image (but add more ringing and aliasing). Negative + values will blur the image. If your GPU is powerful enough, consider + alternatives like the ``ewa_lanczossharp`` scale filter, or the + ``--scale-blur`` option. + +``--opengl-glfinish`` + Call ``glFinish()`` before and after swapping buffers (default: disabled). + Slower, but might improve results when doing framedropping. Can completely + ruin performance. The details depend entirely on the OpenGL driver. + +``--opengl-waitvsync`` + Call ``glXWaitVideoSyncSGI`` after each buffer swap (default: disabled). + This may or may not help with video timing accuracy and frame drop. It's + possible that this makes video output slower, or has no effect at all. + + X11/GLX only. + +``--opengl-vsync-fences=<N>`` + Synchronize the CPU to the Nth past frame using the ``GL_ARB_sync`` + extension. A value of 0 disables this behavior (default). A value of 1 + means it will synchronize to the current frame after rendering it. Like + ``--glfinish`` and ``--waitvsync``, this can lower or ruin performance. Its + advantage is that it can span multiple frames, and effectively limit the + number of frames the GPU queues ahead (which also has an influence on + vsync). + +``--opengl-dwmflush=<no|windowed|yes|auto>`` + Calls ``DwmFlush`` after swapping buffers on Windows (default: auto). It + also sets ``SwapInterval(0)`` to ignore the OpenGL timing. Values are: no + (disabled), windowed (only in windowed mode), yes (also in full screen). + + The value ``auto`` will try to determine whether the compositor is active, + and calls ``DwmFlush`` only if it seems to be. + + This may help to get more consistent frame intervals, especially with + high-fps clips - which might also reduce dropped frames. Typically, a value + of ``windowed`` should be enough, since full screen may bypass the DWM. + + Windows only. + +``--opengl-dcomposition=<yes|no>`` + Allows DirectComposition when using the ANGLE backend (default: yes). + DirectComposition implies flip-model presentation, which can improve + rendering efficiency on Windows 8+ by avoiding a copy of the video frame. + mpv uses it by default where possible, but it can cause poor behaviour with + some drivers, such as a black screen or graphical corruption when leaving + full-screen mode. Use "no" to disable it. + + Windows with ANGLE only. + +``--opengl-sw`` + Continue even if a software renderer is detected. + +``--opengl-backend=<sys>`` + The value ``auto`` (the default) selects the windowing backend. You can + also pass ``help`` to get a complete list of compiled in backends (sorted + by autoprobe order). + + auto + auto-select (default) + cocoa + Cocoa/OS X + win + Win32/WGL + angle + Direct3D11 through the OpenGL ES translation layer ANGLE. This supports + almost everything the ``win`` backend does (if the ANGLE build is new + enough). + dxinterop (experimental) + Win32, using WGL for rendering and Direct3D 9Ex for presentation. Works + on Nvidia and AMD. Newer Intel chips with the latest drivers may also + work. + x11 + X11/GLX + wayland + Wayland/EGL + drm-egl + DRM/EGL + x11egl + X11/EGL + +``--opengl-es=<mode>`` + Select whether to use GLES: + + yes + Try to prefer ES over Desktop GL + no + Try to prefer desktop GL over ES + auto + Use the default for each backend (default) + +``--opengl-fbo-format=<fmt>`` + Selects the internal format of textures used for FBOs. The format can + influence performance and quality of the video output. ``fmt`` can be one + of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f, rgba12, rgba16, rgba16f, + rgba32f. Default: ``auto``, which maps to rgba16 on desktop GL, and rgba16f + or rgb10_a2 on GLES (e.g. ANGLE), unless GL_EXT_texture_norm16 is + available. + +``--opengl-gamma=<0.1..2.0>`` + Set a gamma value (default: 1.0). If gamma is adjusted in other ways (like + with the ``--gamma`` option or key bindings and the ``gamma`` property), + the value is multiplied with the other gamma value. + + Recommended values based on the environmental brightness: + + 1.0 + Brightly illuminated (default) + 0.9 + Slightly dim + 0.8 + Pitch black room + + NOTE: Typical movie content (Blu-ray etc.) already contains a gamma drop of + about 0.8, so specifying it here as well will result in even even darker + image than intended! + +``--gamma-auto`` + Automatically corrects the gamma value depending on ambient lighting + conditions (adding a gamma boost for dark rooms). + + With ambient illuminance of 64lux, mpv will pick the 1.0 gamma value (no + boost), and slightly increase the boost up until 0.8 for 16lux. + + NOTE: Only implemented on OS X. + +``--target-prim=<value>`` + Specifies the primaries of the display. Video colors will be adapted to + this colorspace when ICC color management is not being used. Valid values + are: + + auto + Disable any adaptation (default) + bt.470m + ITU-R BT.470 M + bt.601-525 + ITU-R BT.601 (525-line SD systems, eg. NTSC), SMPTE 170M/240M + bt.601-625 + ITU-R BT.601 (625-line SD systems, eg. PAL/SECAM), ITU-R BT.470 B/G + bt.709 + ITU-R BT.709 (HD), IEC 61966-2-4 (sRGB), SMPTE RP177 Annex B + bt.2020 + ITU-R BT.2020 (UHD) + apple + Apple RGB + adobe + Adobe RGB (1998) + prophoto + ProPhoto RGB (ROMM) + cie1931 + CIE 1931 RGB (not to be confused with CIE XYZ) + dci-p3 + DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2 + v-gamut + Panasonic V-Gamut (VARICAM) primaries + +``--target-trc=<value>`` + Specifies the transfer characteristics (gamma) of the display. Video colors + will be adjusted to this curve when ICC color management is not being used. + Valid values are: + + auto + Disable any adaptation (default) + bt.1886 + ITU-R BT.1886 curve (assuming infinite contrast) + srgb + IEC 61966-2-4 (sRGB) + linear + Linear light output + gamma1.8 + Pure power curve (gamma 1.8), also used for Apple RGB + gamma2.2 + Pure power curve (gamma 2.2) + gamma2.8 + Pure power curve (gamma 2.8), also used for BT.470-BG + prophoto + ProPhoto RGB (ROMM) + st2084 + SMPTE ST2084 (HDR) curve, PQ OETF + std-b67 + ARIB STD-B67 (Hybrid Log-gamma) curve, also known as BBC/NHK HDR + v-log + Panasonic V-Log (VARICAM) curve + + NOTE: When using HDR output formats, mpv will encode to the specified + curve but it will not set any HDMI flags or other signalling that + might be required for the target device to correctly display the + HDR signal. The user should independently guarantee this before + using these signal formats for display. + +``--target-brightness=<1..100000>`` + Specifies the display's approximate brightness in cd/m^2. When playing HDR + content on a SDR display (or SDR content on an HDR display), video colors + will be tone mapped to this target brightness using the algorithm specified + by ``--hdr-tone-mapping``. The default of 250 cd/m^2 corresponds to a + typical consumer display. + +``--hdr-tone-mapping=<value>`` + Specifies the algorithm used for tone-mapping HDR images onto the target + display. Valid values are: + + clip + Hard-clip any out-of-range values. + reinhard + Reinhard tone mapping algorithm. Very simple continuous curve. + Preserves dynamic range and peak but uses nonlinear contrast. + hable + Similar to ``reinhard`` but preserves dark contrast better (slightly + sigmoidal). Developed by John Hable for use in video games. (default) + gamma + Fits a logarithmic transfer between the tone curves. + linear + Linearly stretches the entire reference gamut to (a linear multiple of) + the display. + +``--tone-mapping-param=<value>`` + Set tone mapping parameters. Ignored if the tone mapping algorithm is not + tunable. This affects the following tone mapping algorithms: + + reinhard + Specifies the local contrast coefficient at the display peak. Defaults + to 0.5, which means that in-gamut values will be about half as bright + as when clipping. + gamma + Specifies the exponent of the function. Defaults to 1.8. + linear + Specifies the scale factor to use while stretching. Defaults to 1.0. + +``--icc-profile=<file>`` + Load an ICC profile and use it to transform video RGB to screen output. + Needs LittleCMS 2 support compiled in. This option overrides the + ``--target-prim``, ``--target-trc`` and ``--icc-profile-auto`` options. + +``--icc-profile-auto`` + Automatically select the ICC display profile currently specified by the + display settings of the operating system. + + NOTE: On Windows, the default profile must be an ICC profile. WCS profiles + are not supported. + +``--icc-cache-dir=<dirname>`` + Store and load the 3D LUTs created from the ICC profile in this directory. + This can be used to speed up loading, since LittleCMS 2 can take a while to + create a 3D LUT. Note that these files contain uncompressed LUTs. Their + size depends on the ``--icc-3dlut-size``, and can be very big. + + NOTE: This is not cleaned automatically, so old, unused cache files may + stick around indefinitely. + +``--icc-intent=<value>`` + Specifies the ICC intent used for the color transformation (when using + ``--icc-profile``). + + 0 + perceptual + 1 + relative colorimetric (default) + 2 + saturation + 3 + absolute colorimetric + +``--icc-3dlut-size=<r>x<g>x<b>`` + Size of the 3D LUT generated from the ICC profile in each dimension. + Default is 64x64x64. Sizes may range from 2 to 512. + +``--icc-contrast=<0-100000>`` + Specifies an upper limit on the target device's contrast ratio. This is + detected automatically from the profile if possible, but for some profiles + it might be missing, causing the contrast to be assumed as infinite. As a + result, video may appear darker than intended. This only affects BT.1886 + content. The default of 0 means no limit. + +``--blend-subtitles=<yes|video|no>`` + Blend subtitles directly onto upscaled video frames, before interpolation + and/or color management (default: no). Enabling this causes subtitles to be + affected by ``--icc-profile``, ``--target-prim``, ``--target-trc``, + ``--interpolation``, ``--opengl-gamma`` and ``--post-shader``. It also + increases subtitle performance when using ``--interpolation``. + + The downside of enabling this is that it restricts subtitles to the visible + portion of the video, so you can't have subtitles exist in the black + margins below a video (for example). + + If ``video`` is selected, the behavior is similar to ``yes``, but subs are + drawn at the video's native resolution, and scaled along with the video. + + .. warning:: This changes the way subtitle colors are handled. Normally, + subtitle colors are assumed to be in sRGB and color managed as + such. Enabling this makes them treated as being in the video's + color space instead. This is good if you want things like + softsubbed ASS signs to match the video colors, but may cause + SRT subtitles or similar to look slightly off. + +``--alpha=<blend-tiles|blend|yes|no>`` + Decides what to do if the input has an alpha component. + + blend-tiles + Blend the frame against a 16x16 gray/white tiles background (default). + blend + Blend the frame against a black background. + yes + Try to create a framebuffer with alpha component. This only makes sense + if the video contains alpha information (which is extremely rare). May + not be supported on all platforms. If alpha framebuffers are + unavailable, it silently falls back on a normal framebuffer. Note that + if you set the ``--opengl-fbo-format`` option to a non-default value, a + format with alpha must be specified, or this won't work. + no + Ignore alpha component. + +``--opengl-rectangle-textures`` + Force use of rectangle textures (default: no). Normally this shouldn't have + any advantages over normal textures. Note that hardware decoding overrides + this flag. + +``--background=<color>`` + Color used to draw parts of the mpv window not covered by video. See + ``--osd-color`` option how colors are defined. + Miscellaneous ------------- diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index 2c7b995843..afbcbaec6a 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -20,7 +20,7 @@ normal driver parameters. See ``--vo=help`` for a list of compiled-in video output drivers. - The recommended output driver is ``--vo=opengl-hq``. All other drivers are + The recommended output driver is ``--vo=opengl``. All other drivers are for compatibility or special purposes. By default, ``--vo=opengl`` is used, but if that appears not to work, it fallback to other drivers (in the same order as listed by ``--vo=help``). @@ -276,9 +276,12 @@ Available video output drivers are: OpenGL video output driver. It supports extended scaling methods, dithering and color management. - By default, it tries to use fast and fail-safe settings. Use the alias - ``opengl-hq`` to use this driver with defaults set to high quality - rendering. + See `OpenGL renderer options`_ for options specific to this VO. + + By default, it tries to use fast and fail-safe settings. Use the + ``opengl-hq`` profile to use this driver with defaults set to high + quality rendering. (This profile is also the replacement for + ``--vo=opengl-hq``.) Requires at least OpenGL 2.1. @@ -293,838 +296,12 @@ Available video output drivers are: the hardware decoder APIs. ``opengl`` makes use of FBOs by default. Sometimes you can achieve better - quality or performance by changing the ``fbo-format`` suboption to + quality or performance by changing the ``--opengl-fbo-format`` option to ``rgb16f``, ``rgb32f`` or ``rgb``. Known problems include Mesa/Intel not accepting ``rgb16``, Mesa sometimes not being compiled with float texture support, and some OS X setups being very slow with ``rgb16`` but fast - with ``rgb32f``. If you have problems, you can also try passing the - ``dumb-mode=yes`` sub-option. - - ``dumb-mode=<yes|no>`` - This mode is extremely restricted, and will disable most extended - OpenGL features. This includes high quality scalers and custom - shaders! - - It is intended for hardware that does not support FBOs (including GLES, - which supports it insufficiently), or to get some more performance out - of bad or old hardware. - - This mode is forced automatically if needed, and this option is mostly - useful for debugging. It's also enabled automatically if nothing uses - features which require FBOs. - - This option might be silently removed in the future. - - ``scale=<filter>`` - - ``bilinear`` - Bilinear hardware texture filtering (fastest, very low quality). - This is the default for compatibility reasons. - - ``spline36`` - Mid quality and speed. This is the default when using ``opengl-hq``. - - ``lanczos`` - Lanczos scaling. Provides mid quality and speed. Generally worse - than ``spline36``, but it results in a slightly sharper image - which is good for some content types. The number of taps can be - controlled with ``scale-radius``, but is best left unchanged. - - This filter corresponds to the old ``lanczos3`` alias if the default - radius is used, while ``lanczos2`` corresponds to a radius of 2. - - (This filter is an alias for ``sinc``-windowed ``sinc``) - - ``ewa_lanczos`` - Elliptic weighted average Lanczos scaling. Also known as Jinc. - Relatively slow, but very good quality. The radius can be - controlled with ``scale-radius``. Increasing the radius makes the - filter sharper but adds more ringing. - - (This filter is an alias for ``jinc``-windowed ``jinc``) - - ``ewa_lanczossharp`` - A slightly sharpened version of ewa_lanczos, preconfigured to use - an ideal radius and parameter. If your hardware can run it, this is - probably what you should use by default. - - ``mitchell`` - Mitchell-Netravali. The ``B`` and ``C`` parameters can be set with - ``scale-param1`` and ``scale-param2``. This filter is very good at - downscaling (see ``dscale``). - - ``oversample`` - A version of nearest neighbour that (naively) oversamples pixels, - so that pixels overlapping edges get linearly interpolated instead - of rounded. This essentially removes the small imperfections and - judder artifacts caused by nearest-neighbour interpolation, in - exchange for adding some blur. This filter is good at temporal - interpolation, and also known as "smoothmotion" (see ``tscale``). - - ``linear`` - A ``tscale`` filter. - - ``custom`` - A user-defined custom shader (see ``scale-shader``). - - There are some more filters, but most are not as useful. For a complete - list, pass ``help`` as value, e.g.:: - - mpv --vo=opengl:scale=help - - ``scale-param1=<value>``, ``scale-param2=<value>`` - Set filter parameters. Ignored if the filter is not tunable. - Currently, this affects the following filter parameters: - - bcspline - Spline parameters (``B`` and ``C``). Defaults to 0.5 for both. - - gaussian - Scale parameter (``t``). Increasing this makes the result blurrier. - Defaults to 1. - - oversample - Minimum distance to an edge before interpolation is used. Setting - this to 0 will always interpolate edges, whereas setting it to 0.5 - will never interpolate, thus behaving as if the regular nearest - neighbour algorithm was used. Defaults to 0.0. - - ``scale-blur=<value>`` - Kernel scaling factor (also known as a blur factor). Decreasing this - makes the result sharper, increasing it makes it blurrier (default 0). - If set to 0, the kernel's preferred blur factor is used. Note that - setting this too low (eg. 0.5) leads to bad results. It's generally - recommended to stick to values between 0.8 and 1.2. - - ``scale-radius=<value>`` - Set radius for filters listed below, must be a float number between 0.5 - and 16.0. Defaults to the filter's preferred radius if not specified. - - ``sinc`` and derivatives, ``jinc`` and derivatives, ``gaussian``, ``box`` and ``triangle`` - - Note that depending on filter implementation details and video scaling - ratio, the radius that actually being used might be different - (most likely being increased a bit). - - ``scale-antiring=<value>`` - Set the antiringing strength. This tries to eliminate ringing, but can - introduce other artifacts in the process. Must be a float number - between 0.0 and 1.0. The default value of 0.0 disables antiringing - entirely. - - Note that this doesn't affect the special filters ``bilinear`` and - ``bicubic_fast``. - - ``scale-window=<window>`` - (Advanced users only) Choose a custom windowing function for the kernel. - Defaults to the filter's preferred window if unset. Use - ``scale-window=help`` to get a list of supported windowing functions. - - ``scale-wparam=<window>`` - (Advanced users only) Configure the parameter for the window function - given by ``scale-window``. Ignored if the window is not tunable. - Currently, this affects the following window parameters: - - kaiser - Window parameter (alpha). Defaults to 6.33. - blackman - Window parameter (alpha). Defaults to 0.16. - gaussian - Scale parameter (t). Increasing this makes the window wider. - Defaults to 1. - - ``scaler-lut-size=<4..10>`` - Set the size of the lookup texture for scaler kernels (default: 6). - The actual size of the texture is ``2^N`` for an option value of ``N``. - So the lookup texture with the default setting uses 64 samples. - - All weights are bilinearly interpolated from those samples, so - increasing the size of lookup table might improve the accuracy of - scaler. - - ``scaler-resizes-only`` - Disable the scaler if the video image is not resized. In that case, - ``bilinear`` is used instead whatever is set with ``scale``. Bilinear - will reproduce the source image perfectly if no scaling is performed. - Enabled by default. Note that this option never affects ``cscale``. - - ``pbo`` - Enable use of PBOs. On some drivers this can be faster, especially if - the source video size is huge (e.g. so called "4K" video). On other - drivers it might be slower or cause latency issues. - - In theory, this can sometimes lead to sporadic and temporary image - corruption (because reupload is not retried when it fails). - - ``dither-depth=<N|no|auto>`` - Set dither target depth to N. Default: no. - - no - Disable any dithering done by mpv. - auto - Automatic selection. If output bit depth cannot be detected, - 8 bits per component are assumed. - 8 - Dither to 8 bit output. - - Note that the depth of the connected video display device cannot be - detected. Often, LCD panels will do dithering on their own, which - conflicts with ``opengl``'s dithering and leads to ugly output. - - ``dither-size-fruit=<2-8>`` - Set the size of the dither matrix (default: 6). The actual size of - the matrix is ``(2^N) x (2^N)`` for an option value of ``N``, so a - value of 6 gives a size of 64x64. The matrix is generated at startup - time, and a large matrix can take rather long to compute (seconds). - - Used in ``dither=fruit`` mode only. - - ``dither=<fruit|ordered|no>`` - Select dithering algorithm (default: fruit). (Normally, the - ``dither-depth`` option controls whether dithering is enabled.) - - ``temporal-dither`` - Enable temporal dithering. (Only active if dithering is enabled in - general.) This changes between 8 different dithering patterns on each - frame by changing the orientation of the tiled dithering matrix. - Unfortunately, this can lead to flicker on LCD displays, since these - have a high reaction time. - - ``temporal-dither-period=<1-128>`` - Determines how often the dithering pattern is updated when - ``temporal-dither`` is in use. 1 (the default) will update on every - video frame, 2 on every other frame, etc. - - ``debug`` - Check for OpenGL errors, i.e. call ``glGetError()``. Also, request a - debug OpenGL context (which does nothing with current graphics drivers - as of this writing). - - ``interpolation`` - Reduce stuttering caused by mismatches in the video fps and display - refresh rate (also known as judder). - - .. warning:: This requires setting the ``--video-sync`` option to one - of the ``display-`` modes, or it will be silently disabled. - This was not required before mpv 0.14.0. - - This essentially attempts to interpolate the missing frames by - convoluting the video along the temporal axis. The filter used can be - controlled using the ``tscale`` setting. - - Note that this relies on vsync to work, see ``swapinterval`` for more - information. - - ``swapinterval=<n>`` - Interval in displayed frames between two buffer swaps. - 1 is equivalent to enable VSYNC, 0 to disable VSYNC. Defaults to 1 if - not specified. - - Note that this depends on proper OpenGL vsync support. On some platforms - and drivers, this only works reliably when in fullscreen mode. It may - also require driver-specific hacks if using multiple monitors, to - ensure mpv syncs to the right one. Compositing window managers can - also lead to bad results, as can missing or incorrect display FPS - information (see ``--display-fps``). - - ``dscale=<filter>`` - Like ``scale``, but apply these filters on downscaling instead. If this - option is unset, the filter implied by ``scale`` will be applied. - - ``cscale=<filter>`` - As ``scale``, but for interpolating chroma information. If the image - is not subsampled, this option is ignored entirely. - - ``tscale=<filter>`` - The filter used for interpolating the temporal axis (frames). This is - only used if ``interpolation`` is enabled. The only valid choices - for ``tscale`` are separable convolution filters (use ``tscale=help`` - to get a list). The default is ``mitchell``. - - Note that the maximum supported filter radius is currently 3, due to - limitations in the number of video textures that can be loaded - simultaneously. - - ``tscale-clamp`` - Clamp the ``tscale`` filter kernel's value range to [0-1]. This reduces - excessive ringing artifacts in the temporal domain (which typically - manifest themselves as short flashes or fringes of black, mostly - around moving edges) in exchange for potentially adding more blur. - - ``interpolation-threshold=<0..1,-1>`` - Threshold below which frame ratio interpolation gets disabled (default: - ``0.0001``). This is calculated as ``abs(disphz/vfps - 1) < threshold``, - where ``vfps`` is the speed-adjusted display FPS, and ``disphz`` the - display refresh rate. - - The default is intended to almost always enable interpolation if the - playback rate is even slightly different from the display refresh rate. - But note that if you use e.g. ``--video-sync=display-vdrop``, small - deviations in the rate can disable interpolation and introduce a - discontinuity every other minute. - - Set this to ``-1`` to disable this logic. - - ``dscale-radius``, ``cscale-radius``, ``tscale-radius``, etc. - Set filter parameters for ``dscale``, ``cscale`` and ``tscale``, - respectively. - - See the corresponding options for ``scale``. - - ``linear-scaling`` - Scale in linear light. It should only be used with a ``fbo-format`` - that has at least 16 bit precision. - - ``correct-downscaling`` - When using convolution based filters, extend the filter size - when downscaling. Increases quality, but reduces performance while - downscaling. - - This will perform slightly sub-optimally for anamorphic video (but still - better than without it) since it will extend the size to match only the - milder of the scale factors between the axes. - - ``user-shaders=<files>`` - Custom GLSL hooks. These are a flexible way to add custom fragment - shaders, which 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 to these parameters, the following uniforms are also - globally available: - - float random - A random number in the range [0-1], different per frame. - int frame - A simple count of frames rendered, increases by one per frame and - never resets (regardless of seeks). - vec2 image_size - The size in pixels of the input image. - vec2 target_size - The size in pixels of the visible part of the scaled (and possibly - cropped) image. - - 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. - - MAINPRESUB (resizable) - The image, after conversion to RGB, but before - ``blend-subtitles=video`` is applied. - - MAIN (resizable) - The main image, after conversion to RGB but before upscaling. - - LINEAR (fixed) - Linear light image, before scaling. This only fires when - ``linear-scaling`` is in effect. - - SIGMOID (fixed) - Sigmoidized light, before scaling. This only fires when - ``sigmoid-upscaling`` is in effect. - - PREKERNEL (fixed) - The image immediately before the scaler kernel runs. - - POSTKERNEL (fixed) - The image immediately after the scaler kernel runs. - - SCALED (fixed) - The final upscaled image, before color management. - - OUTPUT (fixed) - The final output image, after color management but before - dithering and drawing to screen. - - Only the textures labelled with ``resizable`` may be transformed by the - pass. When overwriting a texture marked ``fixed``, the WIDTH, HEIGHT - and OFFSET must be left at their default values. - - ``deband`` - Enable the debanding algorithm. This greatly reduces the amount of - visible banding, blocking and other quantization artifacts, at the - expensive of very slightly blurring some of the finest details. In - practice, it's virtually always an improvement - the only reason to - disable it would be for performance. - - ``deband-iterations=<1..16>`` - The number of debanding steps to perform per sample. Each step reduces - a bit more banding, but takes time to compute. Note that the strength - of each step falls off very quickly, so high numbers (>4) are - practically useless. (Default 1) - - ``deband-threshold=<0..4096>`` - The debanding filter's cut-off threshold. Higher numbers increase the - debanding strength dramatically but progressively diminish image - details. (Default 64) - - ``deband-range=<1..64>`` - The debanding filter's initial radius. The radius increases linearly - for each iteration. A higher radius will find more gradients, but - a lower radius will smooth more aggressively. (Default 16) - - If you increase the ``deband-iterations``, you should probably - decrease this to compensate. - - ``deband-grain=<0..4096>`` - Add some extra noise to the image. This significantly helps cover up - remaining quantization artifacts. Higher numbers add more noise. - (Default 48) - - ``sigmoid-upscaling`` - When upscaling, use a sigmoidal color transform to avoid emphasizing - ringing artifacts. This also implies ``linear-scaling``. - - ``sigmoid-center`` - The center of the sigmoid curve used for ``sigmoid-upscaling``, must - be a float between 0.0 and 1.0. Defaults to 0.75 if not specified. - - ``sigmoid-slope`` - The slope of the sigmoid curve used for ``sigmoid-upscaling``, must - be a float between 1.0 and 20.0. Defaults to 6.5 if not specified. - - ``sharpen=<value>`` - If set to a value other than 0, enable an unsharp masking filter. - Positive values will sharpen the image (but add more ringing and - aliasing). Negative values will blur the image. If your GPU is powerful - enough, consider alternatives like the ``ewa_lanczossharp`` scale - filter, or the ``scale-blur`` sub-option. - - (This feature is the replacement for the old ``sharpen3`` and - ``sharpen5`` scalers.) - - ``glfinish`` - Call ``glFinish()`` before and after swapping buffers (default: disabled). - Slower, but might improve results when doing framedropping. - Can completely ruin performance. The details depend entirely on the - OpenGL driver. - - ``waitvsync`` - Call ``glXWaitVideoSyncSGI`` after each buffer swap (default: disabled). - This may or may not help with video timing accuracy and frame drop. It's - possible that this makes video output slower, or has no effect at all. - - X11/GLX only. - - ``vsync-fences=<N>`` - Synchronize the CPU to the Nth past frame using the ``GL_ARB_sync`` - extension. A value of 0 disables this behavior (default). A value of - 1 means it will synchronize to the current frame after rendering it. - Like ``glfinish`` and ``waitvsync``, this can lower or ruin performance. - Its advantage is that it can span multiple frames, and effectively limit - the number of frames the GPU queues ahead (which also has an influence - on vsync). - - ``dwmflush=<no|windowed|yes|auto>`` - Calls ``DwmFlush`` after swapping buffers on Windows (default: auto). - It also sets ``SwapInterval(0)`` to ignore the OpenGL timing. Values - are: no (disabled), windowed (only in windowed mode), yes (also in - full screen). - - The value ``auto`` will try to determine whether the compositor is - active, and calls ``DwmFlush`` only if it seems to be. - - This may help to get more consistent frame intervals, especially with - high-fps clips - which might also reduce dropped frames. Typically, a - value of ``windowed`` should be enough, since full screen may bypass the - DWM. - - Windows only. - - ``dcomposition=<yes|no>`` - Allows DirectComposition when using the ANGLE backend (default: yes). - DirectComposition implies flip-model presentation, which can improve - rendering efficiency on Windows 8+ by avoiding a copy of the video frame. - mpv uses it by default where possible, but it can cause poor behaviour - with some drivers, such as a black screen or graphical corruption when - leaving full-screen mode. Use "no" to disable it. - - Windows with ANGLE only. - - ``sw`` - Continue even if a software renderer is detected. - - ``backend=<sys>`` - The value ``auto`` (the default) selects the windowing backend. You - can also pass ``help`` to get a complete list of compiled in backends - (sorted by autoprobe order). - - auto - auto-select (default) - cocoa - Cocoa/OS X - win - Win32/WGL - angle - Direct3D11 through the OpenGL ES translation layer ANGLE. This - supports almost everything the ``win`` backend does (if the ANGLE - build is new enough). - dxinterop (experimental) - Win32, using WGL for rendering and Direct3D 9Ex for presentation. - Works on Nvidia and AMD. Newer Intel chips with the latest drivers - may also work. - x11 - X11/GLX - wayland - Wayland/EGL - drm-egl - DRM/EGL - x11egl - X11/EGL - - ``es=<mode>`` - Select whether to use GLES: - - yes - Try to prefer ES over Desktop GL - no - Try to prefer desktop GL over ES - auto - Use the default for each backend (default) - - ``fbo-format=<fmt>`` - Selects the internal format of textures used for FBOs. The format can - influence performance and quality of the video output. - ``fmt`` can be one of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, - rgb32f, rgba12, rgba16, rgba16f, rgba32f. - Default: ``auto``, which maps to rgba16 on desktop GL, and rgba16f or - rgb10_a2 on GLES (e.g. ANGLE), unless GL_EXT_texture_norm16 is - available. - - ``gamma=<0.1..2.0>`` - Set a gamma value (default: 1.0). If gamma is adjusted in other ways - (like with the ``--gamma`` option or key bindings and the ``gamma`` - property), the value is multiplied with the other gamma value. - - Recommended values based on the environmental brightness: - - 1.0 - Brightly illuminated (default) - 0.9 - Slightly dim - 0.8 - Pitch black room - - NOTE: Typical movie content (Blu-ray etc.) already contains a gamma - drop of about 0.8, so specifying it here as well will result in even - even darker image than intended! - - ``gamma-auto`` - Automatically corrects the gamma value depending on ambient lighting - conditions (adding a gamma boost for dark rooms). - - With ambient illuminance of 64lux, mpv will pick the 1.0 gamma value - (no boost), and slightly increase the boost up until 0.8 for 16lux. - - NOTE: Only implemented on OS X. - - ``target-prim=<value>`` - Specifies the primaries of the display. Video colors will be adapted to - this colorspace when ICC color management is not being used. Valid - values are: - - auto - Disable any adaptation (default) - bt.470m - ITU-R BT.470 M - bt.601-525 - ITU-R BT.601 (525-line SD systems, eg. NTSC), SMPTE 170M/240M - bt.601-625 - ITU-R BT.601 (625-line SD systems, eg. PAL/SECAM), ITU-R BT.470 B/G - bt.709 - ITU-R BT.709 (HD), IEC 61966-2-4 (sRGB), SMPTE RP177 Annex B - bt.2020 - ITU-R BT.2020 (UHD) - apple - Apple RGB - adobe - Adobe RGB (1998) - prophoto - ProPhoto RGB (ROMM) - cie1931 - CIE 1931 RGB (not to be confused with CIE XYZ) - dci-p3 - DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2 - v-gamut - Panasonic V-Gamut (VARICAM) primaries - - ``target-trc=<value>`` - Specifies the transfer characteristics (gamma) of the display. Video - colors will be adjusted to this curve when ICC color management is - not being used. Valid values are: - - auto - Disable any adaptation (default) - bt.1886 - ITU-R BT.1886 curve (assuming infinite contrast) - srgb - IEC 61966-2-4 (sRGB) - linear - Linear light output - gamma1.8 - Pure power curve (gamma 1.8), also used for Apple RGB - gamma2.2 - Pure power curve (gamma 2.2) - gamma2.8 - Pure power curve (gamma 2.8), also used for BT.470-BG - prophoto - ProPhoto RGB (ROMM) - st2084 - SMPTE ST2084 (HDR) curve, PQ OETF - std-b67 - ARIB STD-B67 (Hybrid Log-gamma) curve, also known as BBC/NHK HDR - v-log - Panasonic V-Log (VARICAM) curve - - NOTE: When using HDR output formats, mpv will encode to the specified - curve but it will not set any HDMI flags or other signalling that - might be required for the target device to correctly display the - HDR signal. The user should independently guarantee this before - using these signal formats for display. - - ``target-brightness=<1..100000>`` - Specifies the display's approximate brightness in cd/m^2. When playing - HDR content on a SDR display (or SDR content on an HDR display), video - colors will be tone mapped to this target brightness using the - algorithm specified by ``hdr-tone-mapping``. The default of 250 cd/m^2 - corresponds to a typical consumer display. - - ``hdr-tone-mapping=<value>`` - Specifies the algorithm used for tone-mapping HDR images onto the - target display. Valid values are: - - clip - Hard-clip any out-of-range values. - reinhard - Reinhard tone mapping algorithm. Very simple continuous curve. - Preserves dynamic range and peak but uses nonlinear contrast. - hable - Similar to ``reinhard`` but preserves dark contrast better - (slightly sigmoidal). Developed by John Hable for use in video - games. (default) - gamma - Fits a logarithmic transfer between the tone curves. - linear - Linearly stretches the entire reference gamut to (a linear multiple - of) the display. - - ``tone-mapping-param=<value>`` - Set tone mapping parameters. Ignored if the tone mapping algorithm is - not tunable. This affects the following tone mapping algorithms: - - reinhard - Specifies the local contrast coefficient at the display peak. - Defaults to 0.5, which means that in-gamut values will be about - half as bright as when clipping. - gamma - Specifies the exponent of the function. Defaults to 1.8. - linear - Specifies the scale factor to use while stretching. Defaults to - 1.0. - - ``icc-profile=<file>`` - Load an ICC profile and use it to transform video RGB to screen output. - Needs LittleCMS 2 support compiled in. This option overrides the - ``target-prim``, ``target-trc`` and ``icc-profile-auto`` options. - - ``icc-profile-auto`` - Automatically select the ICC display profile currently specified by - the display settings of the operating system. - - NOTE: On Windows, the default profile must be an ICC profile. WCS - profiles are not supported. - - ``icc-cache-dir=<dirname>`` - Store and load the 3D LUTs created from the ICC profile in this directory. - This can be used to speed up loading, since LittleCMS 2 can take a while - to create a 3D LUT. Note that these files contain uncompressed LUTs. - Their size depends on the ``3dlut-size``, and can be very big. - - NOTE: This is not cleaned automatically, so old, unused cache files - may stick around indefinitely. - - ``icc-intent=<value>`` - Specifies the ICC intent used for the color transformation (when using - ``icc-profile``). - - 0 - perceptual - 1 - relative colorimetric (default) - 2 - saturation - 3 - absolute colorimetric - - ``3dlut-size=<r>x<g>x<b>`` - Size of the 3D LUT generated from the ICC profile in each dimension. - Default is 64x64x64. Sizes may range from 2 to 512. - - ``icc-contrast=<0-100000>`` - Specifies an upper limit on the target device's contrast ratio. - This is detected automatically from the profile if possible, but for - some profiles it might be missing, causing the contrast to be assumed - as infinite. As a result, video may appear darker than intended. This - only affects BT.1886 content. The default of 0 means no limit. - - ``blend-subtitles=<yes|video|no>`` - Blend subtitles directly onto upscaled video frames, before - interpolation and/or color management (default: no). Enabling this - causes subtitles to be affected by ``icc-profile``, ``target-prim``, - ``target-trc``, ``interpolation``, ``gamma`` and ``post-shader``. It - also increases subtitle performance when using ``interpolation``. - - The downside of enabling this is that it restricts subtitles to the - visible portion of the video, so you can't have subtitles exist in the - black margins below a video (for example). - - If ``video`` is selected, the behavior is similar to ``yes``, but subs - are drawn at the video's native resolution, and scaled along with the - video. - - .. warning:: This changes the way subtitle colors are handled. Normally, - subtitle colors are assumed to be in sRGB and color managed - as such. Enabling this makes them treated as being in the - video's color space instead. This is good if you want - things like softsubbed ASS signs to match the video colors, - but may cause SRT subtitles or similar to look slightly off. - - ``alpha=<blend-tiles|blend|yes|no>`` - Decides what to do if the input has an alpha component. - - blend-tiles - Blend the frame against a 16x16 gray/white tiles background (default). - blend - Blend the frame against a black background. - yes - Try to create a framebuffer with alpha component. This only makes sense - if the video contains alpha information (which is extremely rare). May - not be supported on all platforms. If alpha framebuffers are - unavailable, it silently falls back on a normal framebuffer. Note - that if you set the ``fbo-format`` option to a non-default value, - a format with alpha must be specified, or this won't work. - no - Ignore alpha component. - - ``rectangle-textures`` - Force use of rectangle textures (default: no). Normally this shouldn't - have any advantages over normal textures. Note that hardware decoding - overrides this flag. - - ``background=<color>`` - Color used to draw parts of the mpv window not covered by video. - See ``--osd-color`` option how colors are defined. - -``opengl-hq`` - Same as ``opengl``, but with default settings for high quality rendering. - - This is equivalent to:: - - --vo=opengl:scale=spline36:cscale=spline36:dscale=mitchell:dither-depth=auto:correct-downscaling:sigmoid-upscaling:deband:es=no - - Note that some cheaper LCDs do dithering that gravely interferes with - ``opengl``'s dithering. Disabling dithering with ``dither-depth=no`` helps. + with ``rgb32f``. If you have problems, you can also try enabling the + ``--opengl-dumb-mode=yes`` option. ``sdl`` SDL 2.0+ Render video output driver, depending on system with or without @@ -1260,10 +437,7 @@ Available video output drivers are: For use with libmpv direct OpenGL embedding; useless in any other contexts. (See ``<mpv/opengl_cb.h>``.) - This also supports many of the suboptions the ``opengl`` VO has. Run - ``mpv --vo=opengl-cb:help`` for a list. - - This also supports the ``vo-cmdline`` command. + This also supports many of the options the ``opengl`` VO has. ``rpi`` (Raspberry Pi) Native video output on the Raspberry Pi using the MMAL API. @@ -1304,3 +478,4 @@ Available video output drivers are: ``mode=<number>`` Mode ID to use (resolution, bit depth and frame rate). (default: 0) + |