GLSL shader system
Overall design
Shaders in libplacebo are all written in GLSL, and built up incrementally, on
demand. Generally, all shaders for each frame are generated per frame. So
functions like pl_shader_color_map etc. are run anew for every frame. This
makes the renderer very stateless and allows us to directly embed relevant
constants, uniforms etc. as part of the same code that generates the actual
GLSL shader.
To avoid this from becoming wasteful, libplacebo uses an internal string
building abstraction
(pl_str_builder).
Rather than building up a string directly, a pl_str_builder is like a list of
string building functions/callbacks to execute in order to generate the actual
shader. Combined with an efficient pl_str_builder_hash, this allows us to
avoid the bulk of the string templating work for already-cached shaders.
Legacy API
For the vast majority of libplacebo's history, the main entry-point into the
shader building mechanism was the GLSL() macro (and
variants), which works like a
printf-append:
The special macro $ is a stand-in for an identifier (ident_t), which is
the internal type used to pass references to loaded uniforms, descriptors and
so on:
typedef unsigned short ident_t;
#define $ "_%hx"
#define NULL_IDENT 0u
// ...
ident_t sh_var_mat3(pl_shader sh, const char *name, pl_matrix3x3 val);
#define SH_MAT3(val) sh_var_mat3(sh, "mat", val)
In general, constants in libplacebo are divided into three categories:
Literal shader constants
These are values that are expected to change very infrequently (or never), or
for which we want to generate a different shader variant per value. Such values
should be directly formatted as numbers into the shader text: %d, %f and so
on. This is commonly used for array sizes, constants that depend only on
hardware limits, constants that never change (but which have a friendly name,
like PQ_C2 above), and so on.
As an example, the debanding iterations weights are hard-coded like this, because the debanding shader is expected to change as a result of a different number of iterations anyway:
- The
%d.0here corresponds to the iteration indexi, while the%fcorresponds to the fixed constantM_PI * 2.
Specializable shader constants
These are used for tunable parameters that are expected to change infrequently
during normal playback. These constitute by far the biggest category, and most
parameters coming from the various _params structs should be loaded like
this.
They are loaded using the sh_const_*() functions, which generate a
specialization constant on supported platforms, falling back to a literal
shader #define otherwise. For anoymous parameters, you can use the
short-hands SH_FLOAT, SH_INT etc.:
ident_t sh_const_int(pl_shader sh, const char *name, int val);
ident_t sh_const_uint(pl_shader sh, const char *name, unsigned int val);
ident_t sh_const_float(pl_shader sh, const char *name, float val);
#define SH_INT(val) sh_const_int(sh, "const", val)
#define SH_UINT(val) sh_const_uint(sh, "const", val)
#define SH_FLOAT(val) sh_const_float(sh, "const", val)
Here is an example of them in action:
The advantage of this type of shader constant is that they will be
transparently replaced by dynamic uniforms whenever
pl_render_params.dynamic_constants is true, which allows the renderer to
respond more instantly to changes in the parameters (e.g. as a result of a user
dragging a slider around). During "normal" playback, they will then be
"promoted" to actual shader constants to prevent them from taking up registers.
Dynamic variables
For anything else, e.g. variables which are expected to change very frequently,
you can use the generic sh_var() mechanism, which sends constants either as
elements of a uniform buffer, or directly as push constants:
ident_t sh_var_int(pl_shader sh, const char *name, int val, bool dynamic);
ident_t sh_var_uint(pl_shader sh, const char *name, unsigned int val, bool dynamic);
ident_t sh_var_float(pl_shader sh, const char *name, float val, bool dynamic);
#define SH_INT_DYN(val) sh_var_int(sh, "const", val, true)
#define SH_UINT_DYN(val) sh_var_uint(sh, "const", val, true)
#define SH_FLOAT_DYN(val) sh_var_float(sh, "const", val, true)
These are used primarily when a variable is expected to change very frequently, e.g. as a result of randomness, or for constants which depend on dynamically computed, source-dependent variables (e.g. input frame characteristics):
Shader sections (GLSL, GLSLH, GLSLF)
Shader macros come in three main flavors, depending on where the resulting text should be formatted:
GLSL: Expanded in the scope of the currentmainfunction, and is related to code directly processing the current pixel value.GLSLH: Printed to the 'header', before the first function, but after variables, uniforms etc. This is used for global definitions, helper functions, shared memory variables, and so on.GLSLF: Printed to thefooter, which is always at the end of the currentmainfunction, but before returning to the caller / writing to the framebuffer. Used to e.g. update SSBO state in preparation for the next frame.
Finally, there is a fourth category GLSLP (prelude), which is currently only
used internally to generate preambles during e.g. compute shader translation.
New #pragma GLSL macro
Starting with libplacebo v6, the internal shader system has been augmented by a custom macro preprocessor, which is designed to ease the boilerplate of writing shaders (and also strip redundant whitespace from generated shaders). The code for this is found in the tools/glsl_preproc directory.
In a nutshell, this allows us to embed GLSL snippets directly as #pragma GLSL
macros (resp. #pragma GLSLH, #pragma GLSLF):
This gets transformed, by the GLSL macro preprocessor, into an optimized shader template invocation like the following:
To support this style of shader programming, special syntax was invented:
Shader variables
Instead of being formatted with "$", %f etc. and supplied in a big list,
printf style, GLSL macros may directly embed shader variables:
ident_t pos, tex = sh_bind(sh, texture, ..., &pos, ...);
#pragma GLSL vec4 color = texture($tex, $pos);
The simplest possible shader variable is just $name, which corresponds to
any variable of type ident_t. More complicated expression are also possible:
In the expression ${float:params->noise}, the float: prefix here transforms
the shader variable into the equivalent of SH_FLOAT() in the legacy API,
that is, a generic float (specialization) constant. Other possible types are:
TYPE i = ${ident: sh_desc(...)};
float f = ${float: M_PI};
int i = ${int: params->width};
uint u = ${uint: sizeof(ssbo)};
In addition to a type specifier, the optional qualifiers dynamic and const
will modify the variable, turning it into (respectively) a dynamically loaded
uniform (SH_FLOAT_DYN etc.), or a hard-coded shader literal (%d, %f
etc.):
For sampling from component masks, the special types swizzle and
(u|i)vecType can be used to generate the appropriate texture swizzle and
corresponding vector type:
Macro directives
Lines beginning with @ are not included in the GLSL as-is, but instead parsed
as macro directives, to control the code flow inside the macro expansion:
@if / @else
Standard-purpose conditional. Example:
float alpha = ...;
@if (repr.alpha == PL_ALPHA_INDEPENDENT)
color.a *= alpha;
@else
color.rgba *= alpha;
The condition is evaluated outside the macro (in the enclosing scope) and the resulting boolean variable is directly passed to the template.
An @if block can also enclose multiple lines:
@if (threshold > 0) {
float thresh = ${float:threshold};
coeff = mix(coeff, vec2(0.0), lessThan(coeff, vec2(thresh)));
coeff = mix(coeff, vec2(1.0), greaterThan(coeff, vec2(1.0 - thresh)));
@}
@for
This can be used to generate (unrolled) loops:
int offset = ${const int: params->kernel_width / 2};
float sum = 0.0;
@for (x < params->kernel_width)
sum += textureLodOffset($luma, $pos, 0.0, int(@sum - offset)).r;
This introduces a local variable, @x, which expands to an integer containing
the current loop index. Loop indices always start at 0. Valid terminating
conditions include < and <=, and the loop stop condition is also evaluated
as an integer.
Alternatively, this can be used to iterate over a bitmask (as commonly used for e.g. components in a color mask):
float weight = /* ... */;
vec4 color = textureLod($tex, $pos, 0.0);
@for (c : params->component_mask)
sum[@c] += weight * color[@c];
Finally, to combine loops with conditionals, the special syntax @if @(cond)
may be used to evaluate expressions inside the template loop:
@for (i < 10) {
float weight = /* ... */;
@if @(i < 5)
weight = -weight;
sum += weight * texture(...);
@}
In this case, the @if conditional may only reference local (loop) variables.
@switch / @case
This corresponds fairly straightforwardly to a normal switch/case from C:
@switch (color->transfer) {
@case PL_COLOR_TRC_SRGB:
color.rgb = mix(color.rgb * 1.0/12.92,
pow((color.rgb + vec3(0.055)) / 1.055, vec3(2.4)),
lessThan(vec3(0.04045), color.rgb));
@break;
@case PL_COLOR_TRC_GAMMA18:
color.rgb = pow(color.rgb, vec3(1.8));
@break;
@case PL_COLOR_TRC_GAMMA20:
color.rgb = pow(color.rgb, vec3(2.0));
@break;
@case PL_COLOR_TRC_GAMMA22:
color.rgb = pow(color.rgb, vec3(2.2));
@break;
/* ... */
@}
The switch body is always evaluated as an unsigned int.