A Grunt taks for wrapping GLSL Shader code in Javascript packages, ready to be used in Three.js

This plugin requires Grunt ~0.4.4

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-glsl-threejs --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-glsl-threejs');

This Grunt script tries to generate automatic Three.js wrapper code for all the uniforms used in yourt Fragment and Vertex Shaders, please note this part of the script is the most experimental one and there are many areas where it falls short in regard to this.

In case you find the automatically generated uniforms are incorrect, you can always specify the right ones in your JS code just before passing the Shader code in your ShaderMaterial.

A special syntax has been introduced in GLSL Comments in order to include Raw Javascript code in case you need it

Example:

//#UNIFORMLIB THREE.UniformsLib["common"]

Use this at the beginning of your Vertex Shader in order to include a Three.js uniform Library in your shader, this will affect the Uniform Declaration in the produced JS in this way:

THREE.MyShader = {
  uniforms: THREE.UniformsUtils.merge([
    THREE.UniformsLib["common"],
    {
      "generatedUniform": {type: "v3",value: new THREE.Vector3(1, 1, 1)},
    [...]
    }
  ]),
  [...]

Example:

//#UNIFORM "ambient": {type: "c",value: new THREE.Color(0xffffff)}

Use this at the beginning of your Vertex Shader in order to include an additional Uniform (in addition to the automatically generated ones).

this will affect the Uniform Declaration in the produced JS in this way:

THREE.MyShader = {
  uniforms: THREE.UniformsUtils.merge([
    {
      "ambient": {type: "c",value: new THREE.Color(0xffffff)},
      "generatedUniform": {type: "c",value: new THREE.Color(0xffffff)},
    [...]
    }
  ]),
  [...]

Example:

//#THREE.ShaderChunk["map_vertex"]

Use this whenever you need a to insert a THREE ShaderChunk in your code

In your project's Gruntfile, add a section named glsl_threejs to the data object passed into grunt.initConfig().

grunt.initConfig({
  glsl_threejs: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },\
});

Type: String Default value: '\n'

Specify a Line Ending style for the source files, can be \n (Windows Style) or \n\r (*NIX Style)

Type: String Default value: 'THREE'

A Package name where your shaders will be stored.

In this example, the default options are used to create an unified shaders.js file containing both the Vertex and Fragment Shader.

grunt.initConfig({
  glsl_threejs: {
    options: {},
    files: {
      'dest/shaders.js': ['src/MyShader.vert', 'src/MyShader.frag'],
    },
  },
});

the result will be:

THREE.MyShader = {
  uniforms: { ... },
  vertexShader: { ... },
  fragmentShader: { ... }
}

In this example, custom options are used to compile all VErtex and Fragment shaders contained in a specified folder into a single shaders.js file

grunt.initConfig({
  glsl_threejs: {
    options: {
      jsPackage: 'MYPACKAGE',
      lineEndings: '\n\r',
    },
    files: {
      'dest/shaders.js': ['src/*.vert', 'src/*.frag'],
    },
  },
});

the result will be:

MYPACKAGE.MyShader1 = {
  uniforms: { ... },
  vertexShader: { ... },
  fragmentShader: { ... }
},
MYPACKAGE.MyShader2 = {
  uniforms: { ... },
  vertexShader: { ... },
  fragmentShader: { ... }
}

MyShader is an example simple shader with no light support. Based on the default Three.js Lambert Shader.

MyShader.vert

//#UNIFORMLIB THREE.UniformsLib["common"]
//#UNIFORMLIB THREE.UniformsLib["fog"]
//#UNIFORM "ambient": {type: "c",value: new THREE.Color(0xffffff)}
//#UNIFORM "emissive": {type: "c",value: new THREE.Color(0x000000)}
//#UNIFORM "wrapRGB": {type: "v3",value: new THREE.Vector3(1, 1, 1)}


//#THREE.ShaderChunk["map_pars_vertex"]

void main() {

  //#THREE.ShaderChunk["map_vertex"]
  //#THREE.ShaderChunk["default_vertex"]
  //#THREE.ShaderChunk["worldpos_vertex"]
}

MyShader.frag

uniform float opacity;
//#THREE.ShaderChunk["map_pars_fragment"]

void main() {
  gl_FragColor = vec4( vec3 ( 1.0 ), opacity );

  #ifdef USE_MAP
    vec4 texelColor = texture2D( map, vUv );
    #ifdef GAMMA_INPUT
      texelColor.xyz *= texelColor.xyz;
    #endif

    gl_FragColor = gl_FragColor * texelColor;
  #endif
  //#THREE.ShaderChunk["alphatest_fragment"]
  //#THREE.ShaderChunk["linear_to_gamma_fragment"]
  //#THREE.ShaderChunk["fog_fragment"]
}

• The Automatic Uniforms Generator cannot understand the difference between a Color vec3/vec4 and a normal one. Generated uniforms will always be mapped to THREE.Vector3 objects.
• The Automatic Uniforms Generator has not been tested with all possible uniform types (especially Vectors of Matrices and similar), if you find a bug please let me know using the bug tracker.

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

• 2014-04-08   v0.1.4   updated devDependencies
• 2014-04-08   v0.1.3   Now escaping quotes from glsl, comments with quotes will not break the js. Added jsunit test cases.
• 2014-03-18   v0.1.2   Fixed task name
• 2014-03-18   v0.1.1   First stable Version