path: root/docs/options.md

# Options

The following provides an overview of all options available via the built-in
`pl_options` system.

## Global preset

### `preset=<default|fast|high_quality>`

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=<filter>`

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=<filter>`

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=<filter>`, `plane_downscaler=<filter>`

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=<filter>`

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 `<scaler>` by the
corresponding scaler (`upscaler`, `downscaler`, etc.)

#### `<scaler>_preset=<filter>`

Overrides the value of all options in this section by their default values from
the given filter preset.

#### `<scaler>_kernel=<kernel>`, `<scaler>_window=<kernel>`

Choose the filter kernel and window function, rspectively. Pass `help` to
get a full list of filter kernels. Defaults to `none`.

#### `<scaler>_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".

#### `<scaler>_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`.

#### `<scaler>_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`.

#### `<scaler>_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`.

#### `<scaler>_antiring=<0.0..1.0>`

Antiringing override for this filter. Defaults to `0.0`, which infers the value
from `antiringing_strength`.

#### `<scaler>_param1`, `<scaler>_param2` `<scaler>_wparam1`, `<scaler>_wparam2`

Parameters for the respective filter function. Ignored if not tunable. Defaults
to `0.0`.

#### `<scaler>_polar=<yes|no>`

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=<yes|no>`

Enables debanding. Defaults to `no`.

### `deband_preset=<default>`

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=<yes|no>`

Enables sigmoidization. Defaults to `yes`.

### `sigmoid_preset=<default>`

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=<yes|no>`

Enables color adjustment. Defaults to `yes`.

### `color_adjustment_preset=<neutral>`

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=<angle>`

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=<yes|no>`

Enables HDR peak detection. Defaults to `yes`.

### `peak_detection_preset=<default|high_quality>`

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=<yes|no>`

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=<yes|no>`

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=<default|high_quality>`

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=<function>`

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=<yes|no>`

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=<yes|no>`

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=<function>`

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=<yes|no>`

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=<any|none|hdr10|hdr10plus|cie_y>`

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=<yes|no>`

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=<yes|no>`

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=<angle>`, `visualize_theta=<angle>`

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=<yes|no>`

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=<yes|no>`

Enables dithering. Defaults to `yes`.

### `dither_preset=<default>`

Overrides the value of all options in this section by their default values from
the given preset.

### `dither_method=<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=<yes|no>`

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=<yes|no>`

Enables cone distortion. Defaults to `no`.

### `cone_preset=<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=<none|l|m|s|lm|ms|ls|lms>`

Choose the set of cones to modulate. Defaults to `none`.

### `cone_strength=<gain>`

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=<yes|no>`

Enables output blending. Defaults to `no`.

### `blend_preset=<alpha_overlay>`

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=<yes|no>`

Enables deinterlacing. Defaults to `no`.

### `deinterlace_preset=<default>`

Overrides the value of all options in this section by their default values from
the given preset.

### `deinterlace_algo=<algorithm>`

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=<yes|no>`

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=<yes|no>`

Enables distortion. Defaults to `no`.

### `distort_preset=<default>`

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=<yes|no>`

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=<yes|no>`

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=<yes|no>`

If enabled, use bicubic interpolation rather than faster bilinear
interpolation. Higher quality but slower. Defaults to `no`.

### `distort_addreess_mode=<clamp|repeat|mirror>`

Specifies the texture address mode to use when sampling out of bounds. Defaults
to `clamp`.

### `distort_alpha_mode=<none|independent|premultiplied>`

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=<kernel>`

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=<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=<yes|no>`

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=<yes|no>`

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=<yes|no>`

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=<yes|no>`

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=<yes|no>`

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=<yes|no>`

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=<yes|no>`

Forces the use of the slower, "general" scaling algorithms even when faster
built-in replacements exist. Defaults to `no`.

### `correct_subpixel_offsets=<yes|no>`

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=<yes|no>`

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=<yes|no>`

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=<yes|no>`

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=<yes|no>`

Use only low-bit-depth FBOs (8 bits). Note that this also implies disabling
linear scaling and sigmoidization. Defaults to `no`.

### `dynamic_constants=<yes|no>`

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`.