Vapoursynth Levels (GLSL)

From wiki.selur.net
Jump to navigation Jump to search

Levels (GLSL) remaps brightness levels on the GPU: values in an input range are stretched or squeezed to an output range, with a gamma curve in between. It does the same job as Levels, but runs as a small GLSL shader through libplacebo (vs-placebo).

Filtering → Vapoursynth → Color → Levels

Levels (GLSL) controls in Hybrid
Levels (GLSL) controls in Hybrid

What it does

Values between In min and In max are mapped to the range between Out min and Out max; values outside the input range are clipped. Gamma bends the curve in between: values above 1 brighten the mid tones, values below 1 darken them.

With Hybrid's defaults (In 16/235, Out 0/255) the filter expands limited (TV) range to full (PC) range.

Requirements

  • vs-placebo (libplacebo) and a GPU that libplacebo can use.
  • Hybrid's GLSL shader folder.

Settings

Control Shader parameter Range Hybrid default Meaning
In (min/max) input_low / input_high 0–255 16 / 235 Input range that is assumed.
Out (min/max) output_low / output_high 0–255 0 / 255 Range the input range is mapped to.
Gamma gamma 0–100 1.00 1 = no change, > 1 brightens, < 1 darkens, 0 = black.

All values are on the 8-bit scale, independent of the clip's bit depth; the shader divides them by 255 internally.

Example

Default settings on a 10-bit YUV 4:2:0 source:

# adjusting color space from YUV420P10 to YUV444P16 for vsGLSLLevels
clip = core.resize.Bicubic(clip=clip, format=vs.YUV444P16)
# adjusting levels using GLSL Levels
with open("F:/Hybrid/64bit/vsfilters/GLSL/parameterized/Levels.glsl") as glslf:
  glsl = glslf.read()
glsl = glsl.replace('#define input_low 16.0', '#define input_low 16')
glsl = glsl.replace('#define input_high 235.0', '#define input_high 235')
glsl = glsl.replace('#define output_low 0.0', '#define output_low 0')
glsl = glsl.replace('#define output_high 255.0', '#define output_high 255')
glsl = glsl.replace('#define gamma 1.0', '#define gamma 1')
clip = core.placebo.Shader(clip, shader_s=glsl, width=clip.width, height=clip.height, matrix=1)
# adjusting output color from YUV444P16 to YUV420P10 for NVEncModel
clip = core.resize.Bicubic(clip=clip, format=vs.YUV420P10, dither_type="error_diffusion")

Before and after (drag the handle to compare), with this call:

# adjusting levels using GLSL Levels
with open("F:/Hybrid/64bit/vsfilters/GLSL/parameterized/Levels.glsl") as glslf:
  glsl = glslf.read()
glsl = glsl.replace('#define input_low 16.0', '#define input_low 16')
glsl = glsl.replace('#define input_high 235.0', '#define input_high 235')
glsl = glsl.replace('#define output_low 0.0', '#define output_low 0')
glsl = glsl.replace('#define output_high 255.0', '#define output_high 255')
glsl = glsl.replace('#define gamma 1.0', '#define gamma 0.85')
clip = core.placebo.Shader(clip, shader_s=glsl, width=clip.width, height=clip.height, matrix=2)

How Hybrid calls it

  • The clip is converted to YUV444P16 first, the only format the filter accepts in Hybrid.
  • Hybrid passes the clip's color matrix to placebo.Shader (matrix=1 for BT.601/470bg, 2 for BT.709, 4/5 for BT.2020), so the shader's RGB values match the clip.
  • Hybrid loads the shader Levels.glsl from its GLSL folder, writes the five values into its #define lines and runs it with placebo.Shader. The frame size stays the same.
  • The shader runs in libplacebo's RGB pipeline, so all three color channels are adjusted the same way (unlike Levels with Planes set to luma only).
  • The filter is only offered when Hybrid's GLSL shader folder is present.
  • Levels (GLSL) also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

The shader

Levels.glsl is an mpv-style user shader. It normalizes the five values to 0–1, subtracts input_low, divides by the input range, clamps to 0–1, applies pow(x, 1/gamma), scales to the output range and clamps again.

vs-placebo (placebo.Shader)

placebo.Shader runs mpv-syntax GLSL shaders through libplacebo. The shader is passed as a file or, as Hybrid does, as a string. Input is a 16-bit YUV clip, output is always YUV444P16, so 4:2:0 chroma is upscaled. width and height set the output size.

VapourSynth

The CPU counterpart is std.Levels, see Levels.

AviSynth (Levels)

AviSynth's Levels uses the same transfer function, ((x − input_low) / (input_high − input_low))^(1/gamma) scaled to the output range, and adds coring and dither options. See Avisynth Levels.

Sources