Hot Material

:art: Hot shader replacement and in-browser error handling (Webpack only)

Requirements / Recommandations

• webpack >= 3
• @internet/hmr webpack loader to wrap your shaders in a hmr special object
• glslify-loader is recommended to load your shader
• three.js and regl are officialy supported but you can easily use it with another webgl library

Module Installation

# using npm
$ npm install --save @internet/hotmaterial

# using yarn
$ yarn add @internet/hotmaterial

Usage

three.js

import hotmaterial from '@internet/hotmaterial/three' // import the three implementation

const program = hotmaterial(
  // Your vertex shader - use the @internet/hmr loader as inline loader
  require('@internet/hmr!./shader.vert'),

  // Your fragment shader - use the @internet/hmr loader as inline loader
  require('@internet/hmr!./shader.frag'),

  // Options (see below)
  {}
)

const geometry = new THREE.PlaneBufferGeometry()

// Decorate your three Material with the program function
// Do not declare vertexShader and fragmentShader in the Three Material.
// hotmaterial will automatically set and reload shader source
const material = program(new THREE.RawShaderMaterial({
  uniforms: {
    time: { type: 'f', value: 0 }
  }
}))

const mesh = new THREE.Mesh(geometry, material)

regl

import regl from 'regl'
import hotmaterial from '@internet/hotmaterial'

const program = hotmaterial(
  // Your vertex shader - use the @internet/hmr loader as inline loader
  require('@internet/hmr!./shader.vert'),

  // Your fragment shader - use the @internet/hmr loader as inline loader
  require('@internet/hmr!./shader.frag'),

  // Options (see below)
  {}
)

const draw = regl({
  frag: program.frag, // frag is a function returning the current fragment shader source
  vert: program.vert, // vert is a function returning the current vertex shader source

  attributes: {
    position: [
      -2, 0,
      0, -2,
      2, 2
    ]
  },
  count: 3
})

API

hotmaterial(vertexHMRObject, fragmentHMRObject, options)

Return `{ vert, frag }

• vert is a function returning the current vertex shader source
• frag is a function returning the current fragment shader source

Options

production (Boolean)

• Default: false
• Set it to true to disable all reloading / code validation features.

willUpdate (Function)

• Default: null
• Called before any shader updates, with the shader source as first argument
• Use this to return a modified shaded content before the validation step

didUpdate (Function)

• Default: null
• Called after a valid shader update, with vertex and fragment shader as first and second args.
• DidUpdate is only called when shaders are valids (and just after setup)
• You can use it for custom implementations of hot material

vertWillUpdate (Function)

• Same as willUpdate property but called only before a vertex shader update

fragWillUpdate (Function)

• Same as willUpdate property but called only before a fragment shader update

vertDidUpdate (Function)

• Same as didUpdate property but called only after a fragment shader update

fragDidUpdate (Function)

• Same as didUpdate property but called only after a vertex shader update

Middlewares

Use willUpdate, fragWillUpdate and vertWillUpdate to customize shader code before any update from hotmaterial

Example: inject #define statements into shader source

import injectDefines from 'glsl-inject-defines'
import hotmaterial from 'hotmaterial'

const program = hotmaterial(
  require('@internet/hmr!./shader.vert'),
  require('@internet/hmr!./shader.frag'),
  {
    fragWillUpdate: (fragment) => injectDefines(fragment, { PI: 3.14 })
  }
)

Running Examples

$ npm run example:regl
$ npm run example:three

License

MIT.

hotmaterial is a package of the @internet npm scope.

@internet is a collection of opinionated and interoperables front-end npm ES6 modules, with minimal external dependencies.