diff options
| -rw-r--r-- | DOCS/interface-changes.rst | 7 | ||||
| -rw-r--r-- | DOCS/man/options.rst | 799 | ||||
| -rw-r--r-- | DOCS/man/vo.rst | 849 | ||||
| -rw-r--r-- | options/m_config.c | 56 | ||||
| -rw-r--r-- | options/m_config.h | 4 | ||||
| -rw-r--r-- | options/m_option.c | 17 | ||||
| -rw-r--r-- | options/m_option.h | 13 | ||||
| -rw-r--r-- | options/options.c | 7 | ||||
| -rw-r--r-- | options/options.h | 3 | ||||
| -rw-r--r-- | player/command.c | 9 | ||||
| -rw-r--r-- | player/main.c | 27 | ||||
| -rw-r--r-- | video/out/opengl/video.c | 163 | ||||
| -rw-r--r-- | video/out/opengl/video.h | 5 | ||||
| -rw-r--r-- | video/out/vo.c | 3 | ||||
| -rw-r--r-- | video/out/vo.h | 1 | ||||
| -rw-r--r-- | video/out/vo_opengl.c | 199 | ||||
| -rw-r--r-- | video/out/vo_opengl_cb.c | 78 |
17 files changed, 1139 insertions, 1101 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. + + |