Shader Library

pySSV provides a small library of commonly used GLSL functions to reduce boilerplate. These can be imported into any shader using the #include "xxxx.glsl" directive.

Library Reference

Colour Utilities

#include "color_utils.glsl"

This file includes a number of functions related to colour space transforms and colour maps.

const float _HCV_EPSILON

const float _HSL_EPSILON

const float _HCY_EPSILON

const float SRGB_GAMMA

const float SRGB_INVERSE_GAMMA

const float SRGB_ALPHA

const mat3 RGB_2_XYZ

Used to convert from linear RGB to XYZ space

const mat3 XYZ_2_RGB

Used to convert from XYZ to linear RGB space

const vec3 LUMA_COEFFS

The RGB coefficients used to compute luminosity.

float luminance(vec3 rgb)

Converts a linear rgb colour to its luminance.

Parameters:

• rgb – the linear rgb value.

Returns:

the linear luminance of the colour.

vec3 rgb_to_srgb_approx(vec3 rgb)

Converts a linear rgb colour to sRGB using an approximation.

Parameters:

• rgb – the linear rgb value.

Returns:

the colour in sRGB.

vec3 srgb_to_rgb_approx(vec3 srgb)

Converts an sRGB colour to linear rgb using an approximation.

Parameters:

• rgb – the sRGB colour.

Returns:

the colour in linear rgb.

float linear_to_srgb(float channel)

Converts a linear value to sRGB.

Parameters:

• rgb – the linear value.

Returns:

the value in sRGB space.

float srgb_to_linear(float channel)

Converts an sRGB value to linear space.

Parameters:

• rgb – the sRGB value.

Returns:

the value in linear space.

vec3 rgb_to_srgb(vec3 rgb)

Converts a linear rgb colour to sRGB (exact).

Parameters:

• rgb – the linear rgb value.

Returns:

the colour in sRGB.

vec3 srgb_to_rgb(vec3 srgb)

Converts an sRGB colour to linear rgb (exact).

Parameters:

• rgb – the sRGB colour.

Returns:

the colour in linear rgb.

vec3 rgb_to_xyz(vec3 rgb)

Converts a color from linear RGB to XYZ space

vec3 xyz_to_rgb(vec3 xyz)

Converts a color from XYZ to linear RGB space

vec3 xyz_to_xyY(vec3 xyz)

Converts a color from XYZ to xyY space (Y is luminosity)

vec3 xyY_to_xyz(vec3 xyY)

Converts a color from xyY space to XYZ space

vec3 rgb_to_xyY(vec3 rgb)

Converts a color from linear RGB to xyY space

vec3 xyY_to_rgb(vec3 xyY)

Converts a color from xyY space to linear RGB

vec3 rgb_to_hcv(vec3 rgb)

Converts a value from linear RGB to HCV (Hue, Chroma, Value)

vec3 hue_to_rgb(float hue)

Converts from pure Hue to linear RGB

vec3 hsv_to_rgb(vec3 hsv)

Converts from HSV to linear RGB

vec3 hsl_to_rgb(vec3 hsl)

Converts from HSL to linear RGB

vec3 hcy_to_rgb(vec3 hcy)

Converts from HCY to linear RGB

vec3 rgb_to_hsv(vec3 rgb)

Converts from linear RGB to HSV

vec3 rgb_to_hsl(vec3 rgb)

Converts from linear rgb to HSL

vec3 rgb_to_hcy(vec3 rgb)

Converts from rgb to hcy (Hue, Chroma, Luminance)

vec3 rgb_to_ycbcr(vec3 rgb)

RGB to YCbCr, ranges [0, 1]

vec3 ycbcr_to_rgb(vec3 yuv)

YCbCr to RGB

vec3 xyz_to_srgb(vec3 xyz)

vec3 xyY_to_srgb(vec3 xyY)

vec3 hue_to_srgb(float hue)

vec3 hsv_to_srgb(vec3 hsv)

vec3 hsl_to_srgb(vec3 hsl)

vec3 hcy_to_srgb(vec3 hcy)

vec3 ycbcr_to_srgb(vec3 yuv)

vec3 srgb_to_xyz(vec3 srgb)

vec3 hue_to_xyz(float hue)

vec3 hsv_to_xyz(vec3 hsv)

vec3 hsl_to_xyz(vec3 hsl)

vec3 hcy_to_xyz(vec3 hcy)

vec3 ycbcr_to_xyz(vec3 yuv)

vec3 srgb_to_xyY(vec3 srgb)

vec3 hue_to_xyY(float hue)

vec3 hsv_to_xyY(vec3 hsv)

vec3 hsl_to_xyY(vec3 hsl)

vec3 hcy_to_xyY(vec3 hcy)

vec3 ycbcr_to_xyY(vec3 yuv)

vec3 srgb_to_hcv(vec3 srgb)

vec3 xyz_to_hcv(vec3 xyz)

vec3 xyY_to_hcv(vec3 xyY)

vec3 hue_to_hcv(float hue)

vec3 hsv_to_hcv(vec3 hsv)

vec3 hsl_to_hcv(vec3 hsl)

vec3 hcy_to_hcv(vec3 hcy)

vec3 ycbcr_to_hcv(vec3 yuv)

vec3 srgb_to_hsv(vec3 srgb)

vec3 xyz_to_hsv(vec3 xyz)

vec3 xyY_to_hsv(vec3 xyY)

vec3 hue_to_hsv(float hue)

vec3 hsl_to_hsv(vec3 hsl)

vec3 hcy_to_hsv(vec3 hcy)

vec3 ycbcr_to_hsv(vec3 yuv)

vec3 srgb_to_hsl(vec3 srgb)

vec3 xyz_to_hsl(vec3 xyz)

vec3 xyY_to_hsl(vec3 xyY)

vec3 hue_to_hsl(float hue)

vec3 hsv_to_hsl(vec3 hsv)

vec3 hcy_to_hsl(vec3 hcy)

vec3 ycbcr_to_hsl(vec3 yuv)

vec3 srgb_to_hcy(vec3 srgb)

vec3 xyz_to_hcy(vec3 xyz)

vec3 xyY_to_hcy(vec3 xyY)

vec3 hue_to_hcy(float hue)

vec3 hsv_to_hcy(vec3 hsv)

vec3 hsl_to_hcy(vec3 hsl)

vec3 ycbcr_to_hcy(vec3 yuv)

vec3 srgb_to_ycbcr(vec3 srgb)

vec3 xyz_to_ycbcr(vec3 xyz)

vec3 xyY_to_ycbcr(vec3 xyY)

vec3 hue_to_ycbcr(float hue)

vec3 hsv_to_ycbcr(vec3 hsv)

vec3 hsl_to_ycbcr(vec3 hsl)

vec3 hcy_to_ycbcr(vec3 hcy)

vec3 oklab_to_rgb(const vec3 lab)

Converts a colour from OKLAB space to linear RGB.

https://bottosson.github.io/posts/oklab/

Parameters:

• lab – the colour in OKLAB space.

Returns:

the colour in linear rgb.

vec3 rgb_to_oklab(const vec3 rgb)

Converts a colour from linear RGB space to OKLAB.

https://bottosson.github.io/posts/oklab/

Parameters:

• rgb – the colour in linear rgb.

Returns:

the colour in OKLAB space.

vec3 colmap_greys(float x)

Maps a value between [0-1] to a colour.

Maps from black to white.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_tinted(float x, vec3 oklabCol)

Maps a value between [0-1] to a colour.

Maps from oklabCol to white.

Parameters:

• x – the value to colour map.

• oklabCol – the base colour to use in OKLAB space.

Returns:

the colour mapped to the given value.

vec3 colmap_mix(float x, vec3 oklabColA, vec3 oklabColB)

Maps a value between [0-1] to a colour.

Maps from oklabColA to oklabColB (linear interpolation in OKLAB space).

Parameters:

• x – the value to colour map.

• oklabColA – the start colour to use in OKLAB space.

• oklabColB – the end colour to use in OKLAB space.

Returns:

the colour mapped to the given value.

vec3 colmap_mix_3(float x, vec3 oklabColA, vec3 oklabColB, vec3 oklabColC)

Maps a value between [0-1] to a colour.

Maps from oklabColA to oklabColB to oklabColC (linear interpolation in OKLAB space).

Parameters:

• x – the value to colour map.

• oklabColA – the start colour to use in OKLAB space.

• oklabColB – the middle colour to use in OKLAB space.

• oklabColC – the end colour to use in OKLAB space.

Returns:

the colour mapped to the given value.

vec3 colmap_purples(float x)

Maps a value between [0-1] to a colour.

Maps from purple to white.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_blues(float x)

Maps a value between [0-1] to a colour.

Maps from blue to white.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_greens(float x)

Maps a value between [0-1] to a colour.

Maps from green to white.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_oranges(float x)

Maps a value between [0-1] to a colour.

Maps from orange to white.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_reds(float x)

Maps a value between [0-1] to a colour.

Maps from red to white.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_PiYG(float x)

Maps a value between [0-1] to a colour.

Maps from pink to white to green.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_PRGn(float x)

Maps a value between [0-1] to a colour.

Maps from purple to white to green.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_PuOr(float x)

Maps a value between [0-1] to a colour.

Maps from orange to white to purple.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_RdBu(float x)

Maps a value between [0-1] to a colour.

Maps from red to white to blue.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_coolwarm(float x)

Maps a value between [0-1] to a colour.

Maps from blue to red.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_PurGnYl(float x)

Maps a value between [0-1] to a colour.

Maps from purple to green to yellow. Looks a bit like viridis.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_twilight(float x)

Maps a value between [0-1] to a colour.

Maps from white to blue to black to red and back to white.

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_viridis(float t)

Maps a value between [0-1] to a colour.

This is an approximation of the popular ‘viridis’ colormap taken from: https://www.shadertoy.com/view/WlfXRN

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_plasma(float t)

Maps a value between [0-1] to a colour.

This is an approximation of the popular ‘plasma’ colormap taken from: https://www.shadertoy.com/view/WlfXRN

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_magma(float t)

Maps a value between [0-1] to a colour.

This is an approximation of the popular ‘magma’ colormap taken from: https://www.shadertoy.com/view/WlfXRN

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

vec3 colmap_inferno(float t)

Maps a value between [0-1] to a colour.

This is an approximation of the popular ‘inferno’ colormap taken from: https://www.shadertoy.com/view/WlfXRN

Parameters:

• x – the value to colour map.

Returns:

the colour mapped to the given value.

Random Number Generation / Hashing

#include "random.glsl"

This file includes a number of functions related to random number generation, hashing, and screen space dithering.

float hash11(float p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a float.

Returns:

the hash of p as a float.

float hash12(vec2 p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec2.

Returns:

the hash of p as a float.

float hash13(vec3 p3)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec3.

Returns:

the hash of p as a float.

float hash14(vec4 p4)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec4.

Returns:

the hash of p as a float.

vec2 hash21(float p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a float.

Returns:

the hash of p as a vec2.

vec2 hash22(vec2 p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec2.

Returns:

the hash of p as a vec2.

vec2 hash23(vec3 p3)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec3.

Returns:

the hash of p as a vec2.

vec3 hash31(float p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a float.

Returns:

the hash of p as a vec3.

vec3 hash32(vec2 p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec2.

Returns:

the hash of p as a vec3.

vec3 hash33(vec3 p3)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec3.

Returns:

the hash of p as a vec3.

vec4 hash41(float p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a float.

Returns:

the hash of p as a vec4.

vec4 hash42(vec2 p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec2.

Returns:

the hash of p as a vec4.

vec4 hash43(vec3 p)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec3.

Returns:

the hash of p as a vec4.

vec4 hash44(vec4 p4)

Hashes the given input. Uses the “Hash without Sine” algorithm (https://www.shadertoy.com/view/4djSRW). Tends to fail with small changes in p.

Parameters:

• p – the input to the hash function as a vec4.

Returns:

the hash of p as a vec4.

uint pcg(uint v)

Hashes the given input. Uses the PCG algorithm (https://www.pcg-random.org/). This algorithm strikes a very good balance between performance and high quality hashing.

Parameters:

• v – the input to the hash function as a uint.

Returns:

the hash of p as a uint.

uvec2 pcg2d(uvec2 v)

Hashes the given input. Uses the PCG algorithm (https://www.pcg-random.org/). This algorithm strikes a very good balance between performance and high quality hashing.

Parameters:

• v – the input to the hash function as a uvec2.

Returns:

the hash of p as a uvec2.

uvec3 pcg3d(uvec3 v)

Hashes the given input. Uses the PCG algorithm (https://www.pcg-random.org/). This algorithm strikes a very good balance between performance and high quality hashing.

Parameters:

• v – the input to the hash function as a uvec3.

Returns:

the hash of p as a uvec3.

uvec4 pcg4d(uvec4 v)

Hashes the given input. Uses the PCG algorithm (https://www.pcg-random.org/). This algorithm strikes a very good balance between performance and high quality hashing.

Parameters:

• v – the input to the hash function as a uvec4.

Returns:

the hash of p as a uvec4.

vec3 _dither_col(vec3 col, vec2 p, const int bits)

Dithers the input colour using triangular distributed value noise.

Parameters:

• col – the colour to dither.

• p – the screen-space position in pixels.

• bits – how many least significant bits should be dithered.

Returns:

the dithered colour.

vec3 _dither_col_ordered(vec3 col, vec2 p, const int bits)

Dithers the input colour using Valve’s ordered dithering algorithm. http://alex.vlachos.com/graphics/Alex_Vlachos_Advanced_VR_Rendering_GDC2015.pdf

Parameters:

• col – the colour to dither.

• p – the screen-space position in pixels.

• bits – how many least significant bits should be dithered.

Returns:

the dithered colour.

vec3 dither_col(vec3 col, vec2 p)

Dithers the input colour using triangular distributed value noise. Dithers to 8 bit per pixel precision (256 values).

Parameters:

• col – the colour to dither.

• p – the screen-space position in pixels.

Returns:

the dithered colour.

vec3 dither_col_ordered(vec3 col, vec2 p)

Dithers the input colour using Valve’s ordered dithering algorithm. Dithers to 8 bit per pixel precision (256 values). http://alex.vlachos.com/graphics/Alex_Vlachos_Advanced_VR_Rendering_GDC2015.pdf

Parameters:

• col – the colour to dither.

• p – the screen-space position in pixels.

Returns:

the dithered colour.

Signed Distance Field Operators

#include "sdf_ops.glsl"

This file includes a number of functions related to signed distance field operations.

float op_not(float a)

Inverts a signed distance field. (Logical NOT)

Parameters:

• a – the sdf to invert.

Returns:

the new sdf.

float op_union(float a, float b)

Computes the union between two distance fields. (logical OR)

Parameters:

• a – the first sdf.

• b – the second sdf.

Returns:

the combined sdf.

float op_intersect(float a, float b)

Computes the intersection between two distance fields. (logical AND)

Parameters:

• a – the first sdf.

• b – the second sdf.

Returns:

the combined sdf.

float op_subtract(float a, float b)

Computes the difference between two distance fields. (logical SUBTRACT)

Parameters:

• a – the first sdf.

• b – the second sdf.

Returns:

the combined sdf.

float op_xor(float a, float b)

Computes the exclusive OR between two distance fields. (logical XOR)

Parameters:

• a – the first sdf.

• b – the second sdf.

Returns:

the combined sdf.

float op_sminCubic(float a, float b, float k)

float op_smaxCubic(float a, float b, float k)

float op_smoothUnion(float a, float b, float k)

Computes the union between two distance fields with a soft intersection. (logical OR)

Parameters:

• a – the first sdf.

• b – the second sdf.

• k – the amount of smoothing to apply to the intersection.

Returns:

the combined sdf.

float op_smoothIntersect(float a, float b, float k)

Computes the intersection between two distance fields with a soft intersection. (logical AND)

Parameters:

• a – the first sdf.

• b – the second sdf.

• k – the amount of smoothing to apply to the intersection.

Returns:

the combined sdf.

float op_smoothSubtract(float a, float b, float k)

Computes the difference between two distance fields with a soft intersection. (logical SUBTRACT)

Parameters:

• a – the first sdf.

• b – the second sdf.

• k – the amount of smoothing to apply to the intersection.

Returns:

the combined sdf.

float op_smoothXor(float a, float b, float k)

Computes the exclusive OR between two distance fields with a soft intersection. (logical XOR)

Parameters:

• a – the first sdf.

• b – the second sdf.

• k – the amount of smoothing to apply to the intersection.

Returns:

the combined sdf.

Text Rendering Utilities

#include "text.glsl"

This file includes a number of functions related to text drawing.

Internal Utilities

These glsl files are usually included automatically by the shader template.

Compiler Compatibility

#include "compat.glsl"

This file serves a compatibility layer allowing different GLSL compilers to be used; it relies on special preprocessor pragma to work. Including this, automatically defines the GLSL version, any needed compiler extensions, and the default precision.

Global Uniform Declarations

#include "global_uniforms.glsl"

This file declares all the built in uniforms set by pySSV and any uniforms declared dynamically by the preprocessor.

float uTime

The time in seconds since the canvas started running.

int uFrame

The current frame number, starting from 0.

vec4 uResolution

The resolution of the current render buffer in pixels.

vec2 uMouse

The coordinates of the mouse relative to the canvas in pixels.

bool uMouseDown

Whether the mouse button is pressed.

mat4x4 uViewMat

The main camera’s view matrix.

mat4x4 uProjMat

The main camera’s projection matrix.

vec3 uViewDir

The forward vector of the main camera.