# Options The following provides an overview of all options available via the built-in `pl_options` system. ## Global preset ### `preset=` Override all options from all sections by the values from the given preset. The following presets are available: - `default`: Default settings, tuned to provide a balance of performance and quality. Should be fine on almost all systems. - `fast`: Disable all advanced rendering, equivalent to passing `no` to every option. Increases performance on very slow / old integrated GPUs. - `high_quality`: Reset all structs to their `high_quality` presets (where available), set the upscaler to `ewa_lanczossharp`, and enable `deband=yes`. Suitable for use on machines with a discrete GPU. ## Scaling ### `upscaler=` Sets the filter used for upscaling. Defaults to `lanczos`. Pass `upscaler=help` to see a full list of filters. The most relevant options, roughly ordered from fastest to slowest: - `none`: No filter, only use basic GPU texture sampling - `nearest`: Nearest-neighbour (box) sampling (very fast) - `bilinear`: Bilinear sampling (very fast) - `oversample`: Aspect-ratio preserving nearest neighbour sampling (very fast) - `bicubic`: Bicubic interpolation (fast) - `gaussian`: Gaussian smoothing (fast) - `catmull_rom`: Catmull-Rom cubic spline - `lanczos`: Lanczos reconstruction - `ewa_lanczos`: EWA Lanczos ("Jinc") reconstruction (slow) - `ewa_lanczossharp`: Sharpened version of `ewa_lanczos` (slow) - `ewa_lanczos4sharpest`: Very sharp version of `ewa_lanczos`, with anti-ringing (very slow) ### `downscaler=` Sets the filter used for downscaling. Defaults to `hermite`. Pass `downscaler=help` to see a full list of filters. The most relevant options, roughly ordered from fastest to slowest: - `none`: Use the same filter as specified for `upscaler` - `box`: Box averaging (very fast) - `hermite`: Hermite-weighted averaging (fast) - `bilinear`: Bilinear (triangle) averaging (fast) - `bicubic`: Bicubic interpolation (fast) - `gaussian`: Gaussian smoothing (fast) - `catmull_rom`: Catmull-Rom cubic spline - `mitchell`: Mitchell-Netravalia cubic spline - `lanczos`: Lanczos reconstruction ### `plane_upscaler=`, `plane_downscaler=` Override the filter used for upscaling/downscaling planes, e.g. chroma/alpha. If set to `none`, use the same setting as `upscaler` and `downscaler`, respectively. Defaults to `none` for both. ### `frame_mixer=` Sets the filter used for frame mixing (temporal interpolation). Defaults to `oversample`. Pass `frame_mixer=help` to see a full list of filters. The most relevant options, roughly ordered from fastest to slowest: - `none`: Disable frame mixing, show nearest frame to target PTS - `oversample`: Oversampling, only mix "edge" frames while preserving FPS - `hermite`: Hermite-weighted frame mixing - `linear`: Linear frame mixing - `cubic`: Cubic B-spline frame mixing ### `antiringing_strength=<0.0..1.0>` Antiringing strength to use for all filters. A value of `0.0` disables antiringing, and a value of `1.0` enables full-strength antiringing. Defaults to `0.0`. !!! note Specific filter presets may override this option. ### Custom scalers Custom filter kernels can be created by setting the filter to `custom`, in addition to setting the respective options, replacing `` by the corresponding scaler (`upscaler`, `downscaler`, etc.) #### `_preset=` Overrides the value of all options in this section by their default values from the given filter preset. #### `_kernel=`, `_window=` Choose the filter kernel and window function, rspectively. Pass `help` to get a full list of filter kernels. Defaults to `none`. #### `_radius=<0.0..16.0>` Override the filter kernel radius. Has no effect if the filter kernel is not resizeable. Defaults to `0.0`, meaning "no override". #### `_clamp=<0.0..1.0>` Represents an extra weighting/clamping coefficient for negative weights. A value of `0.0` represents no clamping. A value of `1.0` represents full clamping, i.e. all negative lobes will be removed. Defaults to `0.0`. #### `_blur=<0.0..100.0>` Additional blur coefficient. This effectively stretches the kernel, without changing the effective radius of the filter radius. Setting this to a value of `0.0` is equivalent to disabling it. Values significantly below `1.0` may seriously degrade the visual output, and should be used with care. Defaults to `0.0`. #### `_taper=<0.0..1.0>` Additional taper coefficient. This essentially flattens the function's center. The values within `[-taper, taper]` will return `1.0`, with the actual function being squished into the remainder of `[taper, radius]`. Defaults to `0.0`. #### `_antiring=<0.0..1.0>` Antiringing override for this filter. Defaults to `0.0`, which infers the value from `antiringing_strength`. #### `_param1`, `_param2` `_wparam1`, `_wparam2` Parameters for the respective filter function. Ignored if not tunable. Defaults to `0.0`. #### `_polar=` If true, this filter is a polar/2D filter (EWA), instead of a separable/1D (orthogonal) filter. Defaults to `no`. ## Debanding These options control the optional debanding step. Debanding can be used to reduce the prevalence of quantization artefacts in low quality sources, but can be heavy to compute on weaker devices. !!! note This can also be used as a pure grain generator, by setting `deband_iterations=0`. ### `deband=` Enables debanding. Defaults to `no`. ### `deband_preset=` Overrides the value of all options in this section by their default values from the given preset. ### `deband_iterations=<0..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. Defaults to `1`. ### `deband_threshold=<0.0..1000.0>` The debanding filter's cut-off threshold. Higher numbers increase the debanding strength dramatically, but progressively diminish image details. Defaults to `3.0`. ### `deband_radius=<0.0..1000.0>` 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. Defaults to `16.0`. ### `deband_grain=<0.0..1000.0>` Add some extra noise to the image. This significantly helps cover up remaining quantization artifacts. Higher numbers add more noise. Defaults to `4.0`, which is very mild. ### `deband_grain_neutral_r, deband_grain_neutral_g, deband_grain_neutral_b` 'Neutral' grain value for each channel being debanded. Grain application will be modulated to avoid disturbing colors close to this value. Set this to a value corresponding to black in the relevant colorspace. !!! note This is done automatically by `pl_renderer` and should not need to be touched by the user. This is purely a debug option. ## Sigmoidization These options control the sigmoidization parameters. Sigmoidization is an optional step during upscaling which reduces the prominence of ringing artifacts. ### `sigmoid=` Enables sigmoidization. Defaults to `yes`. ### `sigmoid_preset=` Overrides the value of all options in this section by their default values from the given preset. ### `sigmoid_center=<0.0..1.0>` The center (bias) of the sigmoid curve. Defaults to `0.75`. ### `sigmoid_slope=<1.0..20.0>` The slope (steepness) of the sigmoid curve. Defaults to `6.5`. ## Color adjustment These options affect the decoding of the source color values, and can be used to subjectively alter the appearance of the video. ### `color_adjustment=` Enables color adjustment. Defaults to `yes`. ### `color_adjustment_preset=` Overrides the value of all options in this section by their default values from the given preset. ### `brightness=<-1.0..1.0>` Brightness boost. Adds a constant bias onto the source luminance signal. `0.0` = neutral, `1.0` = solid white, `-1.0` = solid black. Defaults to `0.0`. ### `contrast=<0.0..100.0>` Contrast gain. Multiplies the source luminance signal by a constant factor. `1.0` = neutral, `0.0` = solid black. Defaults to `1.0`. ### `saturation=<0.0..100.0>` Saturation gain. Multiplies the source chromaticity signal by a constant factor. `1.0` = neutral, `0.0` = grayscale. Defaults to `1.0`. ### `hue=` Hue shift. Corresponds to a rotation of the UV subvector around the neutral axis. Specified in radians. Defaults to `0.0` (neutral). ### `gamma=<0.0..100.0>` Gamma lift. Subjectively brightnes or darkens the scene while preserving overall contrast. `1.0` = neutral, `0.0` = solid black. Defaults to `1.0`. ### `temperature=<-1.143..5.286>` Color temperature shift. Relative to 6500 K, a value of `0.0` gives you 6500 K (no change), a value of `-1.0` gives you 3000 K, and a value of `1.0` gives you 10000 K. Defaults to `0.0`. ## HDR peak detection These options affect the HDR peak detection step. This can be used to greatly improve the HDR tone-mapping process in the absence of dynamic video metadata, but may be prohibitively slow on some devices (e.g. weaker integrated GPUs). ### `peak_detect=` Enables HDR peak detection. Defaults to `yes`. ### `peak_detection_preset=` Overrides the value of all options in this section by their default values from the given preset. `high_quality` also enables frame histogram measurement. ### `peak_smoothing_period=<0.0..1000.0>` Smoothing coefficient for the detected values. This controls the time parameter (tau) of an IIR low pass filter. In other words, it represent the cutoff period (= 1 / cutoff frequency) in frames. Frequencies below this length will be suppressed. This helps block out annoying "sparkling" or "flickering" due to small variations in frame-to-frame brightness. If left as `0.0`, this smoothing is completely disabled. Defaults to `20.0`. ### `scene_threshold_low=<0.0..100.0>`, `scene_threshold_high=<0.0..100.0>` In order to avoid reacting sluggishly on scene changes as a result of the low-pass filter, we disable it when the difference between the current frame brightness and the average frame brightness exceeds a given threshold difference. But rather than a single hard cutoff, which would lead to weird discontinuities on fades, we gradually disable it over a small window of brightness ranges. These parameters control the lower and upper bounds of this window, in units of 1% PQ. Setting either one of these to 0.0 disables this logic. Defaults to `1.0` and `3.0`, respectively. ### `peak_percentile=<0.0..100.0>` Which percentile of the input image brightness histogram to consider as the true peak of the scene. If this is set to `100` (or `0`), the brightest pixel is measured. Otherwise, the top of the frequency distribution is progressively cut off. Setting this too low will cause clipping of very bright details, but can improve the dynamic brightness range of scenes with very bright isolated highlights. Defaults to `100.0`. The `high_quality` preset instead sets this to `99.995`, which is very conservative and should cause no major issues in typical content. ### `allow_delayed_peak=` Allows the peak detection result to be delayed by up to a single frame, which can sometimes improve thoughput, at the cost of introducing the possibility of 1-frame flickers on transitions. Defaults to `no`. ## Color mapping These options affect the way colors are transformed between color spaces, including tone- and gamut-mapping where needed. ### `color_map=` Enables the use of these color mapping settings. Defaults to `yes`. !!! note Disabling this option does *not* disable color mapping, it just means "use the default options for everything". ### `color_map_preset=` Overrides the value of all options in this section by their default values from the given preset. `high_quality` also enables HDR contrast recovery. ### `gamut_mapping=` Gamut mapping function to use to handle out-of-gamut colors, including colors which are out-of-gamut as a consequence of tone mapping. Defaults to `perceptual`. The following options are available: - `clip`: Performs no gamut-mapping, just hard clips out-of-range colors per-channel. - `perceptual`: Performs a perceptually balanced (saturation) gamut mapping, using a soft knee function to preserve in-gamut colors, followed by a final softclip operation. This works bidirectionally, meaning it can both compress and expand the gamut. Behaves similar to a blend of `saturation` and `softclip`. - `softclip`: Performs a perceptually balanced gamut mapping using a soft knee function to roll-off clipped regions, and a hue shifting function to preserve saturation. - `relative`: Performs relative colorimetric clipping, while maintaining an exponential relationship between brightness and chromaticity. - `saturation`: Performs simple RGB->RGB saturation mapping. The input R/G/B channels are mapped directly onto the output R/G/B channels. Will never clip, but will distort all hues and/or result in a faded look. - `absolute`: Performs absolute colorimetric clipping. Like `relative`, but does not adapt the white point. - `desaturate`: Performs constant-luminance colorimetric clipping, desaturing colors towards white until they're in-range. - `darken`: Uniformly darkens the input slightly to prevent clipping on blown-out highlights, then clamps colorimetrically to the input gamut boundary, biased slightly to preserve chromaticity over luminance. - `highlight`: Performs no gamut mapping, but simply highlights out-of-gamut pixels. - `linear`: Linearly/uniformly desaturates the image in order to bring the entire image into the target gamut. ### Gamut mapping constants These settings can be used to fine-tune the constants used for the various gamut mapping algorithms. #### `perceptual_deadzone=<0.0..1.0>` (Relative) chromaticity protection zone for `perceptual` mapping. Defaults to `0.30`. #### `perceptual_strength=<0.0..1.0>` Strength of the `perceptual` saturation mapping component. Defaults to `0.80`. #### `colorimetric_gamma=<0.0..10.0>` I vs C curve gamma to use for colorimetric clipping (`relative`, `absolute` and `darken`). Defaults to `1.80`. #### `softclip_knee=<0.0..1.0>` Knee point to use for soft-clipping methods (`perceptual`, `softclip`). Defaults to `0.70`. #### `softclip_desat=<0.0..1.0>` Desaturation strength for `softclip`. Defaults to `0.35`. ### `lut3d_size_I=<0..1024>`, `lut3d_size_C=<0..1024>`, `lut3d_size_h=<0..1024>` Gamut mapping 3DLUT size. Setting a dimension to `0` picks the default value. Defaults to `48`, `32` and `256`, respectively, for channels `I`, `C` and `h`. ### `lut3d_tricubic=` Use higher quality, but slower, tricubic interpolation for gamut mapping 3DLUTs. May substantially improve the 3DLUT gamut mapping accuracy, in particular at smaller 3DLUT sizes. Shouldn't have much effect at the default size. Defaults to `no`. ### `gamut_expansion=` If enabled, allows the gamut mapping function to expand the gamut, in cases where the target gamut exceeds that of the source. If disabled, the source gamut will never be enlarged, even when using a gamut mapping function capable of bidirectional mapping. Defaults to `no`. ### `tone_mapping=` Tone mapping function to use for adapting between difference luminance ranges, including black point adaptation. Defaults to `spline`. The following functions are available: - `clip`: Performs no tone-mapping, just clips out-of-range colors. Retains perfect color accuracy for in-range colors but completely destroys out-of-range information. Does not perform any black point adaptation. - `spline`: Simple spline consisting of two polynomials, joined by a single pivot point, which is tuned based on the source scene average brightness (taking into account dynamic metadata if available). This function can be used for both forward and inverse tone mapping. - `st2094-40`: EETF from SMPTE ST 2094-40 Annex B, which uses the provided OOTF based on Bezier curves to perform tone-mapping. The OOTF used is adjusted based on the ratio between the targeted and actual display peak luminances. In the absence of HDR10+ metadata, falls back to a simple constant bezier curve. - `st2094-10`: EETF from SMPTE ST 2094-10 Annex B.2, which takes into account the input signal average luminance in addition to the maximum/minimum. !!! warning This does *not* currently include the subjective gain/offset/gamma controls defined in Annex B.3. (Open an issue with a valid sample file if you want such parameters to be respected.) - `bt2390`: EETF from the ITU-R Report BT.2390, a hermite spline roll-off with linear segment. - `bt2446a`: EETF from ITU-R Report BT.2446, method A. Can be used for both forward and inverse tone mapping. - `reinhard:` Very simple non-linear curve. Named after Erik Reinhard. - `mobius`: Generalization of the `reinhard` tone mapping algorithm to support an additional linear slope near black. The name is derived from its function shape `(ax+b)/(cx+d)`, which is known as a Möbius transformation. This function is considered legacy/low-quality, and should not be used. - `hable`: Piece-wise, filmic tone-mapping algorithm developed by John Hable for use in Uncharted 2, inspired by a similar tone-mapping algorithm used by Kodak. Popularized by its use in video games with HDR rendering. Preserves both dark and bright details very well, but comes with the drawback of changing the average brightness quite significantly. This is sort of similar to `reinhard` with `reinhard_contrast=0.24`. This function is considered legacy/low-quality, and should not be used. - `gamma`: Fits a gamma (power) function to transfer between the source and target color spaces, effectively resulting in a perceptual hard-knee joining two roughly linear sections. This preserves details at all scales, but can result in an image with a muted or dull appearance. This function is considered legacy/low-quality and should not be used. - `linear`: Linearly stretches the input range to the output range, in PQ space. This will preserve all details accurately, but results in a significantly different average brightness. Can be used for inverse tone-mapping in addition to regular tone-mapping. - `linearlight`: Like `linear`, but in linear light (instead of PQ). Works well for small range adjustments but may cause severe darkening when downconverting from e.g. 10k nits to SDR. ### Tone-mapping constants These settings can be used to fine-tune the constants used for the various tone mapping algorithms. #### `knee_adaptation=<0.0..1.0>` Configures the knee point, as a ratio between the source average and target average (in PQ space). An adaptation of `1.0` always adapts the source scene average brightness to the (scaled) target average, while a value of `0.0` never modifies scene brightness. Affects all methods that use the ST2094 knee point determination (currently `spline`, `st2094-40` and `st2094-10`). Defaults to `0.4`. #### `knee_minimum=<0.0..0.5>`, `knee_maximum=<0.5..1.0>` Configures the knee point minimum and maximum, respectively, as a percentage of the PQ luminance range. Provides a hard limit on the knee point chosen by `knee_adaptation`. Defaults to `0.1` and `0.8`, respectively. #### `knee_default=<0.0..1.0>` Default knee point to use in the absence of source scene average metadata. Normally, this is ignored in favor of picking the knee point as the (relative) source scene average brightness level. Defaults to `0.4`. #### `knee_offset=<0.5..2.0>` Knee point offset (for `bt2390` only). Note that a value of `0.5` is the spec-defined default behavior, which differs from the libplacebo default of `1.0`. #### `slope_tuning=<0.0..10.0>`, `slope_offset=<0.0..1.0>` For the single-pivot polynomial (spline) function, this controls the coefficients used to tune the slope of the curve. This tuning is designed to make the slope closer to `1.0` when the difference in peaks is low, and closer to linear when the difference between peaks is high. Defaults to `1.5`, with offset `0.2`. #### `spline_contrast=<0.0..1.5>` Contrast setting for the `spline` function. Higher values make the curve steeper (closer to `clip`), preserving midtones at the cost of losing shadow/highlight details, while lower values make the curve shallowed (closer to `linear`), preserving highlights at the cost of losing midtone contrast. Values above `1.0` are possible, resulting in an output with more contrast than the input. Defaults to `0.5`. #### `reinhard_contrast=<0.0..1.0>` For the `reinhard` function, this specifies the local contrast coefficient at the display peak. Essentially, a value of `0.5` implies that the reference white will be about half as bright as when clipping. Defaults to `0.5`. #### `linear_knee=<0.0..1.0>` For legacy functions (`mobius`, `gamma`) which operate on linear light, this directly sets the corresponding knee point. Defaults to `0.3`. #### `exposure=<0.0..10.0>` For linear methods (`linear`, `linearlight`), this controls the linear exposure/gain applied to the image. Defaults to `1.0`. ### `inverse_tone_mapping=` If enabled, and supported by the given tone mapping function, will perform inverse tone mapping to expand the dynamic range of a signal. libplacebo is not liable for any HDR-induced eye damage. Defaults to `no`. ### `tone_map_metadata=` Data source to use when tone-mapping. Setting this to a specific value allows overriding the default metadata preference logic. Defaults to `any`. ### `tone_lut_size=<0..4096>` Tone mapping LUT size. Setting `0` picks the default size. Defaults to `256`. ### `contrast_recovery=<0.0..2.0>` HDR contrast recovery strength. If set to a value above `0.0`, the source image will be divided into high-frequency and low-frequency components, and a portion of the high-frequency image is added back onto the tone-mapped output. May cause excessive ringing artifacts for some HDR sources, but can improve the subjective sharpness and detail left over in the image after tone-mapping. Defaults to `0.0`. The `high_quality` preset sets this to `0.3`, which is a fairly conservativee value and should subtly enhance the image quality without creating too many obvious artefacts. ### `contrast_smoothness=<1.0..32.0>` HDR contrast recovery lowpass kernel size. Increasing or decreasing this will affect the visual appearance substantially. Defaults to `3.5`. ### Debug options Miscellaneous debugging and display options related to tone/gamut mapping. #### `force_tone_mapping_lut=` Force the use of a full tone-mapping LUT even for functions that have faster pure GLSL replacements (e.g. `clip`, `linear`, `saturation`). This is a debug option. Defaults to `no`. #### `visualize_lut=` Visualize the color mapping LUTs. Displays a (PQ-PQ) graph of the active tone-mapping LUT. The X axis shows PQ input values, the Y axis shows PQ output values. The tone-mapping curve is shown in green/yellow. Yellow means the brightness has been boosted from the source, dark blue regions show where the brightness has been reduced. The extra colored regions and lines indicate various monitor limits, as well a reference diagonal (neutral tone-mapping) and source scene average brightness information (if available). The background behind this shows a visualization of the gamut mapping 3DLUT, in IPT space. Iso-luminance, iso-chromaticity and iso-hue lines are highlighted (depending on the exact value of `visualize_theta`). Defaults to `no`. #### `visualize_lut_x0`, `visualize_lut_y0`, `visualize_lut_x0`, `visualize_lut_y1` Controls where to draw the LUt visualization, relative to the rendered video. Defaults to `0.0` for `x0`/`y0`, and `1.0` for `x1`/`y1`. #### `visualize_hue=`, `visualize_theta=` Controls the rotation of the gamut 3DLUT visualization. The `hue` parameter rotates the gamut through hue space (around the `I` axis), while the `theta` parameter vertically rotates the cross section (around the `C` axis), in radians. Defaults to `0.0` for both. #### `show_clipping=` Graphically highlight hard-clipped pixels during tone-mapping (i.e. pixels that exceed the claimed source luminance range). Defaults to `no`. ## Dithering These options affect the way colors are dithered before output. Dithering is always required to avoid introducing banding artefacts as a result of quantization to a lower bit depth output texture. ### `dither=` Enables dithering. Defaults to `yes`. ### `dither_preset=` Overrides the value of all options in this section by their default values from the given preset. ### `dither_method=` Chooses the dithering method to use. Defaults to `blue`. The following methods are available: - `blue`: Dither with blue noise. Very high quality, but requires the use of a LUT. !!! warning Computing a blue noise texture with a large size can be very slow, however this only needs to be performed once. Even so, using this with a `dither_lut_size` greater than `6` is generally ill-advised. - `ordered_lut`: Dither with an ordered (bayer) dither matrix, using a LUT. Low quality, and since this also uses a LUT, there's generally no advantage to picking this instead of `blue`. It's mainly there for testing. - `ordered`: The same as `ordered`, but uses fixed function math instead of a LUT. This is faster, but only supports a fixed dither matrix size of 16x16 (equivalent to `dither_lut_size=4`). - `white`: Dither with white noise. This does not require a LUT and is fairly cheap to compute. Unlike the other modes it doesn't show any repeating patterns either spatially or temporally, but the downside is that this is visually fairly jarring due to the presence of low frequencies in the noise spectrum. ### `dither_lut_size=<1..8>` For the dither methods which require the use of a LUT (`blue`, `ordered_lut`), this controls the size of the LUT (base 2). Defaults to `6`. ### `dither_temporal=` Enables temporal dithering. This reduces the persistence of dithering artifacts by perturbing the dithering matrix per frame. Defaults to `no`. !!! warning This can cause nasty aliasing artifacts on some LCD screens. ## Cone distortion These options can be optionally used to modulate the signal in LMS space, in particular, to simulate color blindiness. ### `cone=` Enables cone distortion. Defaults to `no`. ### `cone_preset=` Overrides the value of all options in this section by their default values from the given preset. The following presets are available: - `normal`: No distortion (92% of population) - `protanomaly`: Red cone deficiency (0.66% of population) - `protanopia`: Red cone absence (0.59% of population) - `deuteranomaly`: Green cone deficiency (2.7% of population) - `deuteranopia`: Green cone absence (0.56% of population) - `tritanomaly`: Blue cone deficiency (0.01% of population) - `tritanopia`: Blue cone absence (0.016% of population) - `monochromacy`: Blue cones only (<0.001% of population) - `achromatopsia`: Rods only (<0.0001% of population) ### `cones=` Choose the set of cones to modulate. Defaults to `none`. ### `cone_strength=` Defect/gain coefficient to apply to these cones. `1.0` = unaffected, `0.0` = full blindness. Defaults to `1.0`. Values above `1.0` can be used to instead boost the signal going to this cone. For example, to partially counteract deuteranomaly, you could set `cones=m`, `cone_strength=2.0`. Defaults to `0.0`. ## Output blending These options affect the way the image is blended onto the output framebuffer. ### `blend=` Enables output blending. Defaults to `no`. ### `blend_preset=` Overrides the value of all options in this section by their default values from the given preset. Currently, the only preset is `alpha_overlay`, which corresponds to normal alpha blending. ### `blend_src_rgb`, `blend_src_alpha`, `blend_dst_rgb`, `blend_dst_alpha` Choose the blending mode for each component. Defaults to `zero` for all. The following modes are available: - `zero`: Component will be unused. - `one`: Component will be added at full strength. - `alpha`: Component will be multiplied by the source alpha value. - `one_minus_alpha`: Component will be multiplied by 1 minus the source alpha. ## Deinterlacing Configures the settings used to deinterlace frames, if required. !!! note The use of these options requires the caller to pass extra metadata to incoming frames to link them together / mark them as fields. ### `deinterlace=` Enables deinterlacing. Defaults to `no`. ### `deinterlace_preset=` Overrides the value of all options in this section by their default values from the given preset. ### `deinterlace_algo=` Chooses the algorithm to use for deinterlacing. Defaults to `yadif`. The following algorithms are available: - `weave`: No-op deinterlacing, just sample the weaved frame un-touched. - `bob`: Naive bob deinterlacing. Doubles the field lines vertically. - `yadif`: "Yet another deinterlacing filter". Deinterlacer with temporal and spatial information. Based on FFmpeg's Yadif filter algorithm, but adapted slightly for the GPU. ### `deinterlace_skip_spatial=` Skip the spatial interlacing check for `yadif`. Defaults to `no`. ## Distortion The settings in this section can be used to distort/transform the output image. ### `distort=` Enables distortion. Defaults to `no`. ### `distort_preset=` Overrides the value of all options in this section by their default values from the given preset. ### `distort_scale_x`, `distort_scale_y` Scale the image in the X/Y dimension by an arbitrary factor. Corresponds to the main diagonal of the transformation matrix. Defaults to `1.0` for both. ### `distort_shear_x`, `distort_shear_y` Adds the X/Y dimension onto the Y/X dimension (respectively), scaled by an arbitrary amount. Corresponds to the anti-diagonal of the 2x2 transformation matrix. Defaults to `0.0` for both. ### `distort_offset_x`, `distort_offset_y` Offsets the X/Y dimensions by an arbitrary offset, relative to the image size. Corresponds to the bottom row of a 3x3 affine transformation matrix. Defaults to `0.0` for both. ### `distort_unscaled=` If enabled, the texture is placed inside the center of the canvas without scaling. Otherwise, it is effectively stretched to the canvas size. Defaults to `no`. !!! note This option has no effect when using `pl_renderer`. ### `distort_constrain=` If enabled, the transformation is automatically scaled down and shifted to ensure that the resulting image fits inside the output canvas. Defaults to `no`. ### `distort_bicubic=` If enabled, use bicubic interpolation rather than faster bilinear interpolation. Higher quality but slower. Defaults to `no`. ### `distort_addreess_mode=` Specifies the texture address mode to use when sampling out of bounds. Defaults to `clamp`. ### `distort_alpha_mode=` If set to something other than `none`, all out-of-bounds accesses will instead be treated as transparent, according to the given alpha mode. ## Miscellaneous renderer settings ### `error_diffusion=` Enables error diffusion dithering. Error diffusion is a very slow and memory intensive method of dithering without the use of a fixed dither pattern. If set, this will be used instead of `dither_method` whenever possible. It's highly recommended to use this only for still images, not moving video. Defaults to `none`. The following options are available: - `simple`: Simple error diffusion (fast) - `false-fs`: False Floyd-Steinberg kernel (fast) - `sierra-lite`: Sierra Lite kernel (slow) - `floyd-steinberg`: Floyd-Steinberg kernel (slow) - `atkinson`: Atkinson kernel (slow) - `jarvis-judice-ninke`: Jarvis, Judice & Ninke kernel (very slow) - `stucki`: Stucki kernel (very slow) - `burkes`: Burkes kernel (very slow) - `sierra-2`: Two-row Sierra (very slow) - `sierra-3`: Three-row Sierra (very slow) ### `lut_type=` Overrides the color mapping LUT type. Defaults to `unknown`. The following options are available: - `unknown`: Unknown LUT type, try and guess from metadata - `native`: LUT is applied to raw image contents - `normalized`: LUT is applied to normalized (HDR) RGB values - `conversion`: LUT fully replaces color conversion step !!! note There is no way to load LUTs via the options mechanism, so this option only has an effect if the LUT is loaded via external means. ### `background_r=<0.0..1.0>`, `background_g=<0.0..1.0>`, `background_b=<0.0..1.0>` If the image being rendered does not span the entire size of the target, it will be cleared explicitly using this background color (RGB). Defaults to `0.0` for all. ### `background_transparency=<0.0..1.0>` The (inverted) alpha value of the background clear color. Defaults to `0.0`. ### `skip_target_clearing=` If set, skips clearing the background backbuffer entirely. Defaults to `no`. !!! note This is automatically skipped if the image to be rendered would completely cover the backbuffer. ### `corner_rounding=<0.0..1.0>` If set to a value above `0.0`, the output will be rendered with rounded corners, as if an alpha transparency mask had been applied. The value indicates the relative fraction of the side length to round - a value of `1.0` rounds the corners as much as possible. Defaults to `0.0`. ### `blend_against_tiles=` If true, then transparent images will made opaque by painting them against a checkerboard pattern consisting of alternating colors. Defaults to `no`. ### `tile_color_hi_r`, `tile_color_hi_g`, `tile_color_hi_b`, `tile_color_lo_r`, `tile_color_lo_g`, `tile_color_l_b` The colors of the light/dark tiles used for `blend_against_tiles`. Defaults to `0.93` for light R/G/B and `0.87` for dark R/G/B, respectively. ### `tile_size=<2..256>` The size, in output pixels, of the tiles used for `blend_against_tiles`. Defaults to `32`. ## Performance / quality trade-offs These should generally be left off where quality is desired, as they can degrade the result quite noticeably; but may be useful for older or slower hardware. Note that libplacebo will automatically disable advanced features on hardware where they are unsupported, regardless of these settings. So only enable them if you need a performance bump. ### `skip_anti_aliasing=` Disables anti-aliasing on downscaling. This will result in moiré artifacts and nasty, jagged pixels when downscaling, except for some very limited special cases (e.g. bilinear downsampling to exactly 0.5x). Significantly speeds up downscaling with high downscaling ratios. Defaults to `no`. ### `preserve_mixing_cache=` Normally, when the size of the target framebuffer changes, or the render parameters are updated, the internal cache of mixed frames must be discarded in order to re-render all required frames. Setting this option to `yes` will skip the cache invalidation and instead re-use the existing frames (with bilinear scaling to the new size if necessary). This comes at a hefty quality loss shortly after a resize, but should make it much more smooth. Defaults to `no`. ## Debugging, tuning and testing These may affect performance or may make debugging problems easier, but shouldn't have any effect on the quality (except where otherwise noted). ### `skip_caching_single_frame=` Normally, single frames will also get pushed through the mixer cache, in order to speed up re-draws. Enabling this option disables that logic, causing single frames to bypass being written to the cache. Defaults to `no`. !!! note If a frame is *already* cached, it will be re-used, regardless. ### `disable_linear_scaling=` Disables linearization / sigmoidization before scaling. This might be useful when tracking down unexpected image artifacts or excessing ringing, but it shouldn't normally be necessary. Defaults to `no`. ### `disable_builtin_scalers=` Forces the use of the slower, "general" scaling algorithms even when faster built-in replacements exist. Defaults to `no`. ### `correct_subpixel_offsets=` Forces correction of subpixel offsets (using the configured `upscaler`). Defaults to `no`. !!! warning Enabling this may cause such images to get noticeably blurrier, especially when using a polar scaler. It's not generally recommended to enable this. ### `force_dither=` Forces the use of dithering, even when rendering to 16-bit FBOs. This is generally pretty pointless because most 16-bit FBOs have high enough depth that rounding errors are below the human perception threshold, but this can be used to test the dither code. Defaults to `no`. ### `disable_dither_gamma_correction=` Disables the gamma-correct dithering logic which normally applies when dithering to low bit depths. No real use, outside of testing. Defaults to `no`. ### `disable_fbos=` Completely overrides the use of FBOs, as if there were no renderable texture format available. This disables most features. Defaults to `no`. ### `force_low_bit_depth_fbos=` Use only low-bit-depth FBOs (8 bits). Note that this also implies disabling linear scaling and sigmoidization. Defaults to `no`. ### `dynamic_constants=` If this is enabled, all shaders will be generated as "dynamic" shaders, with any compile-time constants being replaced by runtime-adjustable values. This is generally a performance loss, but has the advantage of being able to freely change parameters without triggering shader recompilations. It's a good idea to enable this if you will change these options very frequently, but it should be disabled once those values are "dialed in". Defaults to `no`.