External Libraries

Overview

In addition to the built in SSF library, Synesthesia includes some external libraries to help create your scenes. These libraries are not compiled by default -- you need to include the files in your main.glsl file to use them.

So far, there are two external libraries available in Synesthesia: lygia and hg_sdf.

Custom Library

You can create your own GLSL library by adding a folder called glsl in your user data folder. Any .glsl files in this folder can be included in your shader. Here is the location of your user data folder:

Windows: C:\Users\{username}\AppData\Local\Synesthesia\Data
Mac: ~/Library/Application Support/com.gravitycurrent.synesthesia/Data

For example, if you create the file glsl/lib.glsl within this Data folder, you could add #include "lib.glsl" at the top of your shader and use any functions from the file.

NOTE: if you plan to share a scene that uses custom library code, you'll need to copy paste the library code into your shader, since other users won't have these library files.

lygia

Lygia is an open-source library by Patricio Gonzalez Vivo, creator of many incredible shader resources including The Book of Shaders.

The library includes a wide array of functions that touch nearly every aspect of shader programming. It is very granular -- each function has its own file. There are also some files that group multiple functions. For example:

// include a single function
#include "lygia/math/rotate3d.glsl"
#include "lygia/space/displace.glsl"
#include "lygia/color/tonemap.glsl"

#include "lygia/math.glsl"                  // all math functions
#include "lygia/sdf.glsl"                   // all sdf functions
#include "lygia/color/blend.glsl"       // all blend functions

To learn more about the library and all its functions/files, check out the github or website.

Here are links to documentation for each section of the library (copied from the website). NOTE: Synesthesia includes Lygia version 1.1.4.

math/: general math functions and constants: PI, SqrtLength(), etc.
space/: general spatial operations: scale(), rotate(), etc.
color/: general color operations: luma(), saturation(), blend modes, palettes, color space conversion, and tonemaps.
animation/: animation operations: easing
generative/: generative functions: random(), noise(), etc.
sdf/: signed distance field functions.
draw/: drawing functions like digits(), stroke(), fill, etc/.
sample/: sample operations
filter/: typical filter operations: different kind of blurs, mean and median filters.
distort/: distort sampling operations
simulate/: simulate sampling operations
lighting/: different lighting models and functions for foward/deferred/raymarching rendering
geometry/: operation related to geometries: intersections and AABB accelerating structures.
morphological/: morphological filters: dilation, erosion, alpha and poisson fill.

hg_sdf

hg_sdf is an open-source library that provides a powerful toolset for creating raymarched scenes with signed distance functions (sdf). The following documentation is provided by the Mercury team. For more information, check out their website.

NOTE: to use hg_sdf, add this include line to the top of your main.glsl file:

#include "hg_sdf.glsl"

Helper Functions and Macros

`sgn()`

Sign function that doesn't return 0

float signedValue = sgn(float x);
vec2 signedValue = sgn(vec2 v);

Params

x float | vec2 - the value to be signed

Returns: float - 1 or -1

`square()`

square the value

float squared = square(float x);
vec2 squared = square(vec2 x);
vec3 squared = square(vec3 x);
vec4 squared = square(vec4 x);

Params

x float | vec2 | vec3 | vec4- the value to be squared

Returns: float - squared value

`lengthSqr()`

float squared = lengthSqr(vec2 x);
float squared = lengthSqr(vec3 x);

Params

x vec2 | vec3 - a vector to find the square of its length

Returns: float - squared length value

`vmax()`

Maximum components of a vector

float vectorMax = vmax(vec2 v);
float vectorMax = vmax(vec3 v);
float vectorMax = vmax(vec4 v);

Params

v vec2 | vec3 | vec4 - the vector to be evaluated

Returns: float - the largest component of the vector

`vmin()`

Minimum components of a vector

float vectorMin = vmin(vec2 v);
float vectorMin = vmin(vec3 v);
float vectorMin = vmin(vec4 v);

Params

v vec2 | vec3 | vec4- the vector to be evaluated

Returns: float - the smallest component of the vector

Primitive Objects

Conventions: Everything that is a distance function is called fSomething. The first argument is always a point in 2 or 3-space called p. Unless otherwise noted, (if the object has an intrinsic "up" side or direction) the y axis is "up" and the object is centered at the origin.