glslify

When requiring a module, you can explicitly map internal names used by the module to local names declared in your current shader. This is useful for providing dependencies like constants or functions that the required module expects to exist.

const int M = 500;
float add(float a, float b){ return a+b; }

#pragma glslify: sum500 = require('./accumulator.glsl',N=M,map=add)

Source transforms allow you to modify GLSL source at build time. There are three types of transforms:

1. Local transforms: Applied per-file and only to a single package. Defined in a package's package.json or via CLI -t.
2. Global transforms: Applied to every file after local transforms, regardless of whether it is a dependency.
3. Post transforms: Applied to the entire bundled output file once it's finished.

glslify can be used as a Browserify transform to automatically replace glsl calls with bundled GLSL strings at build time.

Via command line: Pass glslify using the -t or --transform flag:

browserify -t glslify index.js -o bundle.js

Via package.json: Include it in your browserify.transform array:

{
  "name": "my-app",
  "dependencies": {
    "glslify": "^2.0.0"
  },
  "browserify": {
    "transform": ["glslify"]
  }
}

Depending on your use case, install glslify either globally for CLI usage or locally for use as a Browserify transform.

To install the CLI globally:

npm install -g glslify

To install for use as a Browserify transform:

npm install glslify

For other build tools, use the following specialized modules:

• Webpack: Use glslify-loader to bundle shaders through glslify.
• Babel: Use glslify-babel as a plugin to support ES6 features like import statements and tagged template strings.

Note on Babel Import/Export: If using Babel presets that transpile ES6 import/export to CommonJS require(), glslify may fail to statically analyze the code. To fix this, use babel-plugin-import-to-require in your .babelrc to map glslify directly to CommonJS statements.

GLSL modules are stored on npm and typically follow the naming convention glsl-*. They contain an index.glsl file instead of index.js. You can install them using standard npm commands to make them available in your node_modules for glslify to resolve.

npm install glsl-noise

When calling compile or file, you can pass a transform array in the opts object to apply custom transformations to the shader code.

Transform entries can be defined as:

1. An array: [transformName, transformOptions]
2. A single transform name (string).

If a transform has a post: true option, it will be executed after the initial bundling process (a 'post-transform').

The preferred way to enable local transforms is via the glslify.transform property in your package.json. You can pass simple strings for transform names or arrays containing the name and an options object.

{
  "name": "my-project",
  "dependencies": {
    "glslify-hex": "^2.0.0",
    "glslify": "^2.0.0"
  },
  "glslify": {
    "transform": [
      ["glslify-hex", {
        "option-1": true,
        "option-2": 42
      }]
    ]
  }
}

You can apply transforms (like glslify-hex) to your shader bundle using the -t or --transform flag. This is useful for processing shader source code during the bundling process. For example, to use glslify-hex, you must first install it via npm.

npm install glslify-hex
glslify index.glsl -t glslify-hex -o output.glsl

You can import GLSL modules into your shader using the #pragma glslify: require syntax. This works similarly to Node.js require, resolving paths through node_modules.

#pragma glslify: noise = require(glsl-noise/simplex/2d)

void main() {
  float brightness = noise(gl_FragCoord.xy);
  gl_FragColor = vec4(vec3(brightness), 1.);
}

The glslify module provides several methods to compile shaders from strings or files. These methods accept an optional opts object.

Methods

• glsl(file, opts): Convenience method that calls glsl.file() or glsl.compile() depending on whether the first argument is a filename or a shader string.
• glsl.compile(src, opts): Compiles a shader string from the provided src string.
• glsl.file(filename, opts): Compiles a shader from the provided filename.

Options (opts)

• opts.basedir: The directory used to resolve relative paths within the shader.
• opts.transform: An array of transform functions, transform module names, or [trname, tropts] pairs.