@internet/hotmaterial

0.2.0 • Public • Published

Hot Material

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

Readme

Keywords

none

Package Sidebar

Install

npm i @internet/hotmaterial

Weekly Downloads

0

Version

0.2.0

License

MIT

Unpacked Size

19.3 kB

Total Files

18

Last publish

Collaborators

  • pqml