Custom Shaders (mpv .hook syntax)
libplacebo supports the same custom shader syntax used by mpv, with some important changes. This document will serve as a complete reference for this syntax.
In general, user shaders are divided into distinct blocks. Each block can
define a shader, a texture, a buffer, or a tunable parameter. Each block
starts with a collection of header directives, which are lines starting with
As an example, here is a simple shader that simply inverts the video signal:
This shader defines one block - a shader block which hooks into the two
RGB, binds the hooked texture, inverts the value
rgb channels, and then returns the modified color.
In a few contexts, shader directives accept arithmetic expressions, denoted by
<expr> in the listing below. For historical reasons, all expressions are
given in reverse polish notation
(RPN), and the only
value type is a floating point number. The following value types and
arithmetic operations are available:
1.234: Literal float constant, evaluates to itself.
NAME.width: Evaluates to the width of a texture with name
NAME.height: Evaluates to the height of a texture with name
PAR: Evaluates to the value of a tunable shader parameter with name
+: Evaluates to
-: Evaluates to
*: Evaluates to
/: Evaluates to
%: Evaluates to
>: Evaluates to
(X > Y) ? 1.0 : 0.0.
<: Evaluates to
(X < Y) ? 1.0 : 0.0.
=: Evaluates to
fuzzy_eq(X, Y) ? 1.0 : 0.0, with some tolerance to allow for floating point inaccuracy. (Around 1 ppm)
!: Evaluates to
X ? 0.0 : 1.0.
* can be used as suitable replacements for the otherwise
absent boolean logic expressions (
Shaders are the default block type, and have no special syntax to indicate
their presence. Shader stages contain raw GLSL code that will be
(conditionally) executed. This GLSL snippet must define a single function
vec4 hook(), or
void hook() for compute shaders.
During the execution of any shader, the following global variables are made available:
int frame: A raw counter tracking the number of executions of this shader stage.
float random: A pseudo-random float uniformly distributed in the range
vec2 input_size: The nominal size (in pixels) of the original input image.
vec2 target_size: The nominal size (in pixels) of the output rectangle.
vec2 tex_offset: The nominal offset (in pixels), of the original input crop.
vec4 linearize(vec4 color): Linearize the input color according to the image's tagged gamma function.
vec4 delinearize(vec4 color): Opposite counterpart to
Shader stages accept the following directives:
HOOK directive determines when a shader stage is run. During internal
processing, libplacebo goes over a number of pre-defined hook points at set
points in the processing pipeline. It is only possible to intercept the image,
and run custom shaders, at these fixed hook points.
Here is a current list of hook points:
RGB: Input plane containing RGB values
LUMA: Input plane containing a Y value
CHROMA: Input plane containing chroma values (one or both)
ALPHA: Input plane containing a single alpha value
XYZ: Input plane containing XYZ values
CHROMA_SCALED: Chroma plane, after merging and upscaling to luma size
ALPHA_SCALED: Alpha plane, after upscaling to luma size
NATIVE: Merged input planes, before any sort of color conversion (as-is)
MAIN: After conversion to RGB, before linearization/scaling
LINEAR: After conversion to linear light (for scaling purposes)
SIGMOID: After conversion to sigmoidized light (for scaling purposes)
PREKERNEL: Immediately before the execution of the main scaler kernel
POSTKERNEL: Immediately after the execution of the main scaler kernel
SCALED: After scaling, in either linear or non-linear light RGB
PREOUTPUT: After color conversion to target colorspace, before alpha blending
OUTPUT: After alpha blending, before dithering and final output pass
MAINPRESUB are separate shader stages, because the
--blend-subtitles=video allows rendering overlays directly
onto the pre-scaled video stage. libplacebo does not support this feature,
and as such, the
MAINPRESUB shader stage does not exist. It is still
valid to refer to this name in shaders, but it is handled identically to
It's possible for a hook point to never fire. For example,
SIGMOID will not
fire when downscaling, as sigmoidization only happens when upscaling.
CHROMA will not fire on an RGB video and vice versa.
A single shader stage may hook multiple hook points simultaneously, for
example, to cover both
RGB cases with the same logic. (See the
example shader in the introduction)
BIND directive makes a texture available for use in the shader. This can
be any of the previously named hook points, a custom texture define by a
TEXTURE block, a custom texture saved by a
SAVE directive, or the special
HOOKED which allows binding whatever texture hook dispatched this
A bound texture will define the following GLSL functions (as macros):
sampler2D NAME_raw: A reference to the raw texture sampler itself.
vec2 NAME_pos: The texel coordinates of the current pixel.
vec2 NAME_map(ivec2 id): A function that maps from
gl_GlobalInvocationIDto texel coordinates. (Compute shaders)
vec2 NAME_size: The size (in pixels) of the texture.
vec2 NAME_pt: Convenience macro for
1.0 / NAME_size. The size of a single pixel (in texel coordinates).
vec2 NAME_off: The sample offset of the texture. Basically, the pixel coordinates of the top-left corner of the sampled area.
float NAME_mul: The coefficient that must be multiplied into sampled values in order to rescale them to
vec4 NAME_tex(vec2 pos): A wrapper around
NAME_mul * textureLod(NAME_raw, pos, 0.0).
vec4 NAME_texOff(vec2 offset): A wrapper around
NAME_tex(NAME_pos + NAME_pt * offset). This can be used to easily access adjacent pixels, e.g.
NAME_texOff(-1,2)samples a pixel one to the left and two to the bottom of the current location.
vec4 NAME_gather(vec2 pos, int c): A wrapper around
NAME_mul * textureGather(pos, c), with appropriate scaling. (Only when supported1)
For compatibility with mpv, we also define a
mat2 NAME_rot which is
simply equal to a 2x2 identity matrix. libplacebo never rotates input
planes - all rotation happens during the final output to the display.
This same directive can also be used to bind buffer blocks (i.e.
uniform/storage buffers), as defined by the
By default, after execution of a shader stage, the resulting output is
captured back into the same hooked texture that triggered the shader. This
behavior can be overridden using the explicit
SAVE directive. For example,
a shader might need access to a low-res version of the luma input texture in
order to process chroma:
This shader binds both luma and chroma and resizes the luma plane down to the
size of the chroma plane, saving the result as a new texture
general, you can pick any name you want, here.
This purely informative directive simply gives the shader stage a name. This is the name that will be reported to the shader stage and execution time metrics.
OFFSET <xo yo | ALIGN>
This directive indicates a pixel shift (offset) introduced by this pass. These pixel offsets will be accumulated and corrected automatically as part of plane alignment / main scaling.
A special value of
ALIGN will attempt to counteract any existing offset of
the hooked texture by aligning it with reference plane (i.e. luma). This can
be used to e.g. introduce custom chroma scaling in a way that doesn't break
chroma subtexel offsets.
This (slightly silly) shader simply shifts the entire sampled region to the
bottom right by 100.5 pixels, and propagates this shift to the main scaler
OFFSET directive. As such, the end result of this is that there is
no visible shift of the overall image, but some detail (~100 pixels) near the
bottom-right border is lost due to falling outside the bounds of the texture.
These directives can be used to override the dimensions of the resulting
texture. Note that not all textures can be resized this way. Currently, only
MAIN are resizable. Trying to
save a texture with an incompatible size to any other shader stage will result
in an error.
This directive takes an expression that can be used to make shader stages conditionally executed. If this evaluates to 0, the shader stage will be skipped.
This example defines a shader stage that only conditionally executes itself
if the value of the
intensity shader parameter is non-zero.
This directive overrides the number of components present in a texture.
For example, if you want to extract a one-dimensional feature map from the
otherwise 3 or 4 dimensional
MAIN texture, you can use this directive to
save on memory bandwidth and consumption by having libplacebo only allocate a
one-component texture to store the feature map in:
COMPUTE <bw> <bh> [<tw> <th>]
This directive specifies that the shader should be treated as a compute
shader, with the block size
bh. The compute shader will be
dispatched with however many blocks are necessary to completely tile over the
output. Within each block, there will be
tw*th threads, forming a single
work group. In other words:
th specify the work group size, which
can be different from the block size. So for example, a compute shader with
bw = bh = 32 and
tw = th = 8 running on a
500x500 texture would dispatch
16x16 blocks (rounded up), each with
Instead of defining a
vec4 hook(), compute shaders must define a
hook() which results directly to the output texture, a
out_image made available to the shader stage.
For example, here is a shader executing a single-pass 41x41 convolution (average blur) on the luma plane, using a compute shader to share sampling work between adjacent threads in a work group:
Custom textures can be defined and made available to shader stages using
TEXTURE blocks. These can be used to provide e.g. LUTs or pre-trained
The data for a texture is provided as a raw hexadecimal string encoding the in-memory representation of a texture, according to its given texture format, for example:
Texture blocks accept the following directives:
This must be the first directive in a texture block, and marks it as such. The
name given is the name that the texture will be referred to (via
SIZE <width> [<height> [<depth>]]
This directive gives the size of the texture, as integers. For example,
//!SIZE 512 512 marks a 512x512 texture block. Textures can be 1D, 2D or 3D
depending on the number of coordinates specified.
This directive specifies the texture format. A complete list of known textures
is exposed as part of the
pl_gpu struct metadata, but they follow the format
r64i and so on.
FILTER <LINEAR | NEAREST>
This directive specifies the texture magnification/minification filter.
BORDER <CLAMP | REPEAT | MIRROR>
This directive specifies the border clamping method of the texture.
If present, this directive marks the texture as a storage image. It will still
be initialized with the initial values, but rather than being bound as a
read-only and immutable
sampler2D, it is bound as a
image2D. Such texture scan be used to, for example, store persistent state
across invocations of the shader.
Custom uniform / storage shader buffer blocks can be defined using
The (initial) data for a buffer is provided as a raw hexadecimal string encoding the in-memory representation of a buffer in the corresponding GLSL packing layout (std140 or std430 for uniform and storage blocks, respectively):
Buffer blocks accept the following directives:
This must be the first directive in a buffer block, and marks it as such. The
name given is mostly cosmetic, as individual variables can be accessed
directly using the names given in the corresponding
If present, this directive marks the buffer as a (readwrite coherent) shader storage block, instead of a readonly uniform buffer block. Such storage blocks can be used to track and evolve state across invocations of this shader.
Storage blocks may also be initialized with default data, but this is
optional. They can also be initialized as part of the first shader execution
(e.g. by testing for
frame == 0).
VAR <type> <name>
This directive appends a new variable to the shader block, with GLSL type
<type> and shader name
<name>. For example,
VAR float foo introduces a
float foo; member into the buffer block, and
VAR mat4 transform introduces
mat4 transform; member.
It is also possible to introduce array variables, using
[N] as part of the
PARAM directive allows introducing tunable shader parameters,
which are exposed programmatically as part of the C API (
The default value of a parameter is given as the block body, for example:
Parameters accept the following directives:
This must be the first directive in a parameter block, and marks it as such. The name given is the name that will be used to refer to this parameter in GLSL code.
This directive can be used to provide a friendlier description of the shader parameter, exposed as part of the C API to end users.
Provides the minimum/maximum value bound of this parameter. If absent, no minimum/maximum is enforced.
TYPE [ENUM] <DEFINE | [DYNAMIC | CONSTANT] <type>>
This gives the type of the parameter, which determines what type of values it
can hold and how it will be made available to the shader.
<type> must be
a scalar GLSL numeric type, such as
If a type is
ENUM, it is treated as an enumeration type. To use this,
must either be
DEFINE. Instead of providing a single default value,
the param body should be a list of all possible enumeration values (as separate
lines). These names will be made available inside the shader body (as a
#define), as well as inside RPN expressions (e.g.
WHEN). The qualifiers
MAXIMUM are ignored for
ENUM parameters, with the value
range instead being set implicitly from the list of options.
The optional qualifiers
CONSTANT mark the parameter as
dynamically changing and compile-time constant, respectively. A
variable is assumed to change frequently, and will be grouped with other
frequently-changing input parameters. A
CONSTANT parameter will be
introduced as a compile-time constant into the shader header, which means thy
can be used in e.g. constant expressions such as array sizes.3
Finally, the special type
TYPE DEFINE marks a variable as a preprocessor
define, which can be used inside
#if preprocessor expressions. For example:
An example of an enum parameter:
A collection of full examples can be found in the mpv user shaders wiki, but here is an example of a parametrized Gaussian smoothed film grain compute shader:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
Because these are macros, their presence can be tested for using
#ifdefinside the GLSL preprocessor. ↩
On supported platforms, these are implemented using specialization constants, which can be updated at run-time without requiring a full shader recompilation. ↩