By passing your shaders to the assembleShaders function, the shadertools module adds platform detection and portability your shaders. In addition it also enables you to "inject" shader code (GLSL code) that has been packaged into reusable, composable "modules". And naturally, shadertools also allows you to create your own reusable shader modules.

Usage

Note that assembleShaders is integrated into the Model class. Your shaders will automatically be passed to assembleShaders if you supply modules parameter.

const model = new Model(gl, {
  fs: '...',
  vs,
  modules: [],
});

To use the shader module system directly to add/inject modules into your shaders, just call assembleShaders:

const {vs, fs, getUniforms, moduleMap} = assembleShaders(gl, {
  fs: '...',
  vs: '...',
  modules: [...],
  defines: {...}
})

To create a new shader module, you need to create the following object

const module = {
  name: 'my-mnodule',
  vs: ....
  fs: null,
  dependencies: [],
  deprecations: [],
  getUniforms
};

This object can be used as shader module directly, or you can register it so that it can be referred to by name.

new Model(gl, {..., modules: [module]});
registerShaderModules([module]);
new Model(gl, {..., modules: ['my-module']});

Concepts

A shader module is either:

Generic - a set of generic GLSL functions that can be included either in a fragment shader or a vertex shader (or both). The fp64 module is a good example of this type of module.
Functional - Contains specific vertex and/or fragment shader "chunks", often set up so that the vertex shader part sets up a varying used by the fragment shader part.

To define a shader module, you must specify the following fields:

name (String) - the name of the shader module
dependencies (Array) - a list of other shader modules that this module is dependent on
deprecations (Array) - a list of deprecated APIs. If supplied, assembleShaders will scan the source for usage and issue a console warning. Each API is described in the following format:
- type: uniform <type> or function
- old: name of the deprecated uniform/function
- new: name of the new uniform/function
- deprecated: whether the old API is still supported
getUniforms JavaScript function that maps JavaScript parameter keys to uniforms used by this module
vs
fs

GLSL Code

The GLSL code for a shader module typically contains:

a mix of uniform and varying declarations
one or more GLSL function definitions

getUniforms

Each shader module provides a method to get a map of uniforms for the shader. This function will be called with two arguments:

opts - the module settings to update. This argument may not be provided when getUniforms is called to generate a set of default uniform values.
context - the uniforms generated by this module's dependencies.

The function should return a JavaScript object with keys representing uniform names and values representing uniform values.

The function should expect the shape of the dependency uniforms to vary based on what's passed in opts. This behavior is intended because we only want to recalculate a uniform if the uniforms that it depends on are changed. An example is the project and project64 modules in deck.gl. When opts.viewport is provided, project64 will receive the updated projection matrix generated by the project module. If opts.viewport is empty, then the project module generates nothing and so should project64.

Platform Detection

Also does some platform detection and injects #define statements enabling your shader to conditionally use code.

API

`assembleShaders`

Takes the source code of a vertex shader and a fragment shader, and a list of modules, and generates combined source code for both shaders.

vs - vertex shader source
fs - fragment shader source code
modules=[] - list of shader modules (either objects defining the module, or names of previously registered modules)
id - id for the shader, will be used to inject shader names (using #define SHADER_NAME) if not already present in the source.
defines={} (Object) - a map of key/value pairs representing custom #defines to be injected into the shader source

Returns:

vs - the resolved vertex shader
fs - the resolved fragment shader
getUniforms - a combined getUniforms function covering all modules.
moduleMap - a map with all resolved modules, keyed by name

Remarks:

Will inject platform prologue, with defines identifying GPU driver to enable bug workarounds
Will inject a GLSL feature detection prologue, simplifying writing code that works with GLSL extensions and across GLSL versions (WebGL1 and WebGL2)
Will follow module dependencies and inject dependency tree in correct order
Version directive (like #version 300 es) must be the very first line in vs and fs shader if it exists, assembleShaders will make sure it is still the very first line in resolved shader.

`registerShaderModules`

Can be used to "name" shader modules, making them available to assembleShaders using module names rather than the module definitions.

Note: Can defeat three-shaking of unused shader modules (affects size of application JavaScript bundle).

`getModuleUniforms`

Takes a list of shader module names and an object with options, and creates a combined uniform object that contains all necessary uniforms for all the modules injected into your shader

Remarks

No Vertex Attributes - At the moment shader modules are not expected to use attributes. It is up to the root application shaders to define attributes and call GLSL functions from the imported shader modules with the appropriate attributes. This is just a convention, not a hard limitation.