Skip to main content

ShaderModule

In luma.gl, reusable shader modules are defined by objects that conform to the ShaderModule type. For more information see Shader Module System Guide.

ShaderModules are used by the luma.gl shader assembler. The shader assembler imports chunks of reusable shader code from the module into your shader program source code.

Usage​

To define a new shader module, you create a descriptor object that brings together all the necessary pieces:

type ModuleProps = {
  radius: number;
}

export const MY_SHADER_MODULE: ShaderModule<ModuleProps> = {
  name: 'my-shader-module',
  vs: '...',
  fs: '...',
  inject: {},
  dependencies: [],
  deprecations: [],
};

Fields​

name​

  • name (string) - The name of the shader module.

vs​

  • vs? - (string | null)

fs​

  • fs - (string | null)

uniformTypes (Object) - Uniform shader types​

The uniformTypes map describes the shader-facing uniform layout for the module. Primitive uniform leaves use string shader types such as 'f32', 'vec3<f32>', and 'mat4x4<f32>'.

From-v9.3

luma.gl also supports composite uniform descriptors:

  • structs use object literals
  • fixed-size arrays use [elementType, length]

See Core Shader Types for the descriptor syntax, TypeScript inference, array handling, and how nested values flow through ShaderInputs and uniform-buffer packing.

uniformPropTypes (Object) - Uniform JS prop types​

defaultUniforms (Object) - Default uniform values​

getUniforms (function) - Function that maps props to uniforms & bindings. When not provided it is assumed that the names of the uniforms and bindings match those of the provided props​

defines (Object) - Constant defines to be injected into shader​

inject (Object) - injections the module will make into shader hooks, see below​

dependencies (Array) - a list of other shader modules that this module is dependent on​

deprecations (Array) - a list of deprecated APIs.​

If deprecations is supplied, assembleShaders will scan shader source code for the deprecated constructs and issue a console warning if found. 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.

Statically defining Uniforms​

If the uniforms of this module can be directly pulled from user props, they may declaratively defined by a defaultUniforms object:

{
  name: 'my-shader-module',
  defaultUniforms: {center: [0.5, 0.5], strength: 0.9},
  uniformTypes: {center: 'vec2<f32>', strength: 'f32'}
}

At runtime, this map will be used to generate the uniforms needed by the shaders. If either strength or center is present in the user's module props, then the user's value will be used; otherwise, the default value in the original definition will be used.

Dynamically defining Uniforms​

The shader module may want to perform more complex logic when mapping the user's module props to uniforms. This can be achieved using getUniforms():

{
  name: 'my-shader-module',
  uniformTypes: {center: 'vec2<f32>', strength: 'f32'},
  getUniforms: ({intensity}) => {
    return {
      strength: Math.sqrt(intensity),
      center: intensity > 0 ? [0.5, 0.5] : [0, 0]
    };
  }
}

Defining Injections​

A map of hook function signatures to either the injection code string, or an object containing the injection code and an order option indicating ordering within the hook function. See assembleShaders documentation for more information on shader hooks.

For example:

{
  picking: {
    'vs:VERTEX_HOOK_FUNCTION': 'picking_setPickingColor(color.rgb);',
    'fs:FRAGMENT_HOOK_FUNCTION': {
      injection: 'color = picking_filterColor(color);',
      order: Number.POSITIVE_INFINITY
    },
    'fs:#main-end': 'gl_FragColor = picking_filterColor(gl_FragColor);'
  }
}

Functions​

getShaderModuleUniforms()​

getShaderModuleUniforms(module: ShaderModule)
  • JavaScript function that maps JavaScript parameter keys to uniforms used by this module

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 props 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.

getShaderModuleDependencies()​

getShaderModuleDependencies(module: ShaderModule): ShaderModule[]

TODO​

caution

This page is not complete:

  • Describe props to uniforms mapping system
  • Better documentation of getShaderModuleUniforms
  • Describe all functions working on shader modules
  • Better reference information for injections