GLSL Imports

Use #include to import GLSL functions from NPM packages, your files, or URLs. You do not need to copy shader code between nodes.

#include works in glsl, swgl, regl, and hydra inside setFunction. It also works in three through the await glsl tagged template.

How It Works

Before shader compilation, #include inserts GLSL source code at the include site. Patchies resolves the path, gets the source, and inserts it.

#include <lygia/generative/snoise>

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
  float n = snoise(vec3(uv * 4.0, iTime));
  fragColor = vec4(vec3(n), 1.0);
}

This example gets the snoise function from the lygia shader library. Patchies resolves includes automatically.

Import Sources

You can import GLSL code from three sources:

NPM Packages

Use angle brackets to import from shader libraries, such as lygia:

#include <lygia/generative/snoise>
#include <lygia/lighting/pbr>
#include <lygia/color/space/hsv2rgb>

The .glsl extension is optional. <lygia/generative/snoise> and <lygia/generative/snoise.glsl> are equivalent.

Your Files

Use double quotes and a user:// path to import from Virtual Filesystem files:

#include "user://my-shaders/utils.glsl"
#include "user://sdf-functions.glsl"

Add .glsl files in the sidebar (Ctrl/Cmd + B > Files). Then include them in any shader node.

URLs

Use double quotes and a complete URL to import GLSL from the web:

#include "https://raw.githubusercontent.com/stegu/psrdnoise/main/src/psrdnoise2.glsl"

Patchies caches URL imports in memory for the session. It gets each URL once.

Supported Objects

#include works in five visual objects. Most of them preprocess your shaders automatically.

Hydra Usage

Use #include inside setFunction to add external GLSL to the Hydra shader pipeline:

osc()
  .setFunction({
    type: "frag",
    glsl: `
      #include <lygia/generative/snoise>

      vec4 myEffect(vec4 color, vec2 uv) {
        float n = snoise(vec3(uv * 4.0, time));
        return vec4(vec3(n), 1.0);
      }
    `,
  })
  .out()

Three.js Usage

Three.js nodes cannot preprocess shaders because Patchies does not control THREE.ShaderMaterial. Use the await glsl tagged template:

const material = new THREE.ShaderMaterial({
  fragmentShader: await glsl`
    #include <lygia/generative/snoise>

    void main() {
      float n = snoise(vec3(vUv * 4.0, time));
      gl_FragColor = vec4(vec3(n), 1.0);
    }
  `,
})

All JavaScript visual objects provide the glsl tag and processIncludes() function.

Try It

Exercise — Use Lygia Noise in a GLSL Shader

1. Create a glsl object (Enter > type glsl).
2. Paste this code:

#include <lygia/generative/snoise>

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
  float n = snoise(vec3(uv * 5.0, iTime * 0.5));
  fragColor = vec4(vec3(n * 0.5 + 0.5), 1.0);
}

3. Connect the object to bg.out. You should see animated simplex noise.

Exercise — Share a Utility Across Nodes

1. Open the sidebar (Ctrl/Cmd + B > Files).
2. Create a file named utils.glsl.
3. Add this helper function:

vec3 palette(float t) {
  return 0.5 + 0.5 * cos(6.28318 * (t + vec3(0.0, 0.33, 0.67)));
}

4. In a glsl object, include and use the file:

#include "user://utils.glsl"

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
  fragColor = vec4(palette(uv.x + iTime * 0.2), 1.0);
}

5. Create a second glsl object.
6. Include the same file. Both nodes share the function.

Nested Includes

Included files can contain #include directives. Patchies resolves includes up to 32 levels deep. Circular includes produce an error.

Caching

• NPM packages: Patchies gets packages from a CDN and caches them for the session.
• VFS files: Patchies reads files again after they change.
• URLs: Patchies caches URLs for the session. Reload the page to get them again.

Licensing: Lygia Shader Library

Lygia uses the Prosperity License and the Lygia Patron License.

Lygia is free for non-commercial use, including personal use and use in non-commercial organizations. For commercial use, purchase a license from Patricio Gonzalez Vivo on GitHub Sponsors.

These requirements do not apply if your shaders do not import Lygia with #include <lygia/...>. You can use Patchies without importing Lygia.

See Also

• glsl — Create fragment shaders with Shadertoy-compatible uniforms.
• swgl — Create SwissGL shaders.
• regl — Use WebGL with REGL.
• three — Create Three.js scenes.
• Virtual Filesystem — Manage files for user:// imports.