glslify

What is glslify?

glslify is a module system for GLSL (OpenGL Shading Language) that allows you to write modular shader code. It enables you to import and export GLSL code, making it easier to manage and reuse shader code across different projects.

What are glslify's main functionalities?

Importing GLSL Modules

This feature allows you to import GLSL code from other files, making it easier to manage and reuse shader code. The `glslify` function takes the path to a GLSL file and returns the shader code as a string.

const glslify = require('glslify');
const shader = glslify('./shader.glsl');

Using GLSL Modules

You can use `glslify` to import both vertex and fragment shaders, allowing you to modularize your shader code. This makes it easier to maintain and update your shaders.

const glslify = require('glslify');
const vertexShader = glslify('./vertex.glsl');
const fragmentShader = glslify('./fragment.glsl');

Inlining GLSL Code

You can also inline GLSL code directly within your JavaScript files using template literals. This is useful for small shaders or for quick prototyping.

const glslify = require('glslify');
const shader = glslify(`
  precision mediump float;
  void main() {
    gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
  }
`);

Transforming GLSL Code

glslify supports transforming GLSL code using plugins. In this example, the `glslify-hex` plugin is used to transform the GLSL code. This allows you to extend the functionality of glslify with custom transformations.

const glslify = require('glslify');
const shader = glslify('./shader.glsl', { transform: ['glslify-hex'] });

Other packages similar to glslify

shader-loader

shader-loader is a Webpack loader that allows you to import GLSL shaders into your JavaScript code. It is similar to glslify in that it helps manage and import shader code, but it is specifically designed to work with Webpack.

glslify-loader

glslify-loader is a Webpack loader that integrates glslify with Webpack. It allows you to use glslify's module system within a Webpack build process. This makes it easier to use glslify in projects that are already using Webpack.

README

glslify

a module system for GLSL and a transform enabling easy access to GLSL Shaders in JavaScript.

As a Browserify transform:

$ npm install --save glslify
$ browserify entry.js -t glslify > bundle.js

glslify will find and replace all instances of glslify({vertex: path, fragment: path}) with a function that takes a webgl context and returns a shader instance.

Recommended usage:

var glslify = require('glslify')    // requiring `glslify` is safe in this context.
                                    // if the program is run without the transform,
                                    // it'll output a helpful error message.
var shell = require('gl-now')()

var createShader = glslify({
    vertex: './vertex.glsl'
  , fragment: './fragment.glsl'
})

var program

shell.on('gl-init', function() {
  program = createShader(shell.gl)
})

As part of the transform, the program will be analyzed for its uniforms and attributes, so once you have a program instance, the following will work:

// given a glsl program containing:
//
//   uniform vec2 color;
//   uniform mat4 view;

program.bind()
program.uniforms.color = [0.5, 1.0]
program.uniforms.view = [
  1, 0, 0, 0
, 0, 1, 0, 0
, 0, 0, 1, 0
, 0, 0, 0, 1
]

The following options may be passed into glslify's transformed constructor:

• fragment: the fragment shader to use.
• vertex: the vertex shader to use.
• inline: instead of loading the vertex/fragment shaders from a file path, use the string values of these options directly to generate the shaders.
• transform: a string or array of strings naming browserify-transform stream modules you would like to use to transform these shaders.

As a GLSL module system:

glslify can be run as a standalone command as well:

$ glslify my-module.glsl > output.glsl

glslify allows you to write GLSL modules that export a local function, variable, or type, and require those modules to bring that export into another module.

Lookups work like node's require -- that is, it'll work relatively to the file first, and then work from the file's directory on up to the root directory looking for a package in node_modules/.

example files

main.glsl	file1.glsl	file2.glsl

main.glsl

back to file list

// main.glsl
precision highp float;
uniform float time;
uniform vec2 mouse;
uniform vec2 resolution;

// require a function from another file!
#pragma glslify: program_one = require(./file1)

// require a function from another file, and replace
// `local_value` in that file with `resolution.x` from
// this scope.
#pragma glslify: program_two = require(./file2, local_value=resolution.x)

int modulo(float x, float y) {
  return int(x - y * floor(x / y));
}

void main(void) {
  ivec2 m = ivec2(modulo(gl_FragCoord.x, 2.), modulo(gl_FragCoord.y, 2.));

  if(m.x == 0 || m.y == 0) {
    program_one();
  } else { 
    program_two();
  }
}

file1.glsl

back to file list

// file1.glsl
void main(void) {
  gl_FragColor = vec4(1., 0., 0., 1.);
}

#pragma glslify: export(main)

file2.glsl

back to file list

// file2.glsl

uniform float local_value;

void main(void) {
  gl_FragColor = vec4(0., 0., local_value, 1.);
}

#pragma glslify: export(main)

GLSL API

GLSLify works by mangling top-level identities in non-root modules.

Exported variables will be aliased on requirement.

#pragma glslify: VARIABLE = require(MODULE[, NAME=EXPR])

Import a module and assign it the name VARIABLE in the local program.

MODULE may be located within node_modules/ or relative to the current file.

Quotes are not allowed.

If the target module defines attribute, varying, or uniform global variables, you may map those to a local definition or expression:

attribute vec4 position;
#pragma glslify: x = require(./takes_vec2, module_variable=position.xy)

If a mapping is not defined, those requirements are forwarded on to the module requiring the current module -- if no mappings are found for a definition, an error is raised.

#pragma glslify: export(NAME)

Exports a local name from the current module. If the current module is the root, this is a no-op. There may be only one exported NAME per module. The NAME may represent a type, function, or variable.

With ThreeJS

You can use the sourceOnly option to integrate glslfiy with ThreeJS and other WebGL frameworks. This will return an object with vertex and fragment shader source, which you can then compile yourself.

In ThreeJS it might look like this:

var myShader = glslify({
    vertex: './vertex.glsl',
    fragment: './fragment.glsl',
    sourceOnly: true
});

//optionally do something with our uniforms/attribs
console.log( myShader.uniforms, myShader.attributes );

//setup custom ThreeJS material...
var mat = new THREE.ShaderMaterial({
    vertexShader: myShader.vertex,
    fragmentShader: myShader.fragment
    uniforms: { 
      // setup your uniforms..
    }
});

License

MIT