luruke / magicshader

🔮 Tiny helper for three.js to debug and write shaders

🔮 MagicShader

⚠️ probably won't work with modern version of threejs, last time I tested was with r114
pr is welcome

A thin wrapper on top of RawShaderMaterial, that allows to easily create new uniforms and live-edit them via dat.gui.

No need to create the uniforms manually and bind them with dat.gui.
Just write some comments in your GLSL, and everything will work magically ✨

🕵️‍♂️ How to use

Install via npm

npm i -D magicshader

and just use it instead of RawShaderMaterial:

import MagicShader from 'magicshader';

const material = new MagicShader({...})

The parameters are exactly the same.

🤷‍♀️ Ok...where the magic is?

Now you can add the // ms({}) magic comment after your uniforms.

Example:

const material = new MagicShader({
  vertexShader: `
    precision highp float;
    
    attribute vec3 position;
    uniform mat4 modelViewMatrix;
    uniform mat4 projectionMatrix;
    
    void main() {
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    precision highp float;

    uniform vec3 color; // ms({ value: '#ff0000' })

    void main() {
      gl_FragColor = vec4(color, 1.0);
    }
  `
});

This will give you:

No need to init your uniform or bind dat.gui.
You can just work on your GLSL files.

👨‍💻 What else?

const material = new MagicShader({
  name: 'Cube Shader!',
  vertexShader: `
    precision highp float;
    
    attribute vec3 position;
    uniform mat4 modelViewMatrix;
    uniform mat4 projectionMatrix;

    uniform vec3 translate; // ms({ value: [0, 0, 0], step: 0.01 })
    uniform float scale; // ms({ value: 0.5, options: { small: 0.5, medium: 1, big: 2 } })
    uniform mat4 aMatrix4; // ms({ value: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] })

    void main() {
      vec3 pos = position + translate;
      pos *= scale;

      gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
    }
  `,
  fragmentShader: `
    precision highp float;
    
    uniform vec3 color; // ms({ value: '#ff0000' })
    uniform float brightness; // ms({ value: 0, range: [0, 0.5], step: 0.1 })
    uniform vec2 dummyValue; // ms({ value: [1024, 768], range: [[0, 2000], [0, 1500]] })
    uniform bool visible; // ms({ value: 1, name: 'Visibility' })
    uniform int test; // ms({ value: 0 })

    void main() {
      gl_FragColor = vec4(color + brightness, 1.0);
    }
  `
});

Will result in:

🕵️‍ SpectorJS

With the SpectorJS extension enabled, you can live-edit the shaders. You can even add and modify "magic" uniforms on the fly.

💅 Ok, cool. Just finished my app and I'm ready to deploy

Then you can hide the dat.gui UI

import MagicShader, { gui } from 'magicshader';
gui.destroy();

😴 TODO

• Do more tests...
• add support for sampler2D and FBO?
• check if it works with firefox/safari shader editor
• inspect/edit threejs default uniforms (like projectionMatrix)

magicshader's Issues

.destroy doesn't clean .listen dat gui?

Only to three.js or generic webgl thing?

Check if it will be easy to extend this comment logic thing to WebGL in general without target just three.js...

Program don't compile on r111

I get this error with MagicShader on the r111 :

Uncaught TypeError: Cannot read property 'getUniforms' of undefined
    at setProgram (three.module.js:25208)
    at Renderer.WebGLRenderer.renderBufferDirect (three.module.js:24204)
    at renderObject (three.module.js:24973)
    at renderObjects (three.module.js:24943)
    at Renderer.WebGLRenderer.render (three.module.js:24720)
    at WebGL.onTick (WebGL.js:79)

It seems to refer to this line on the WebGLRenderer : https://github.com/mrdoob/three.js/blob/r111/src/renderers/WebGLRenderer.js#L1721

Maybe it's linked with the change of Material.needsUpdate and the new Material.version introduced in r111 :https://github.com/mrdoob/three.js/wiki/Migration-Guide#r110--r111

I would be happy to help! Also, thanks for this library it's awesome!

Add shadername `#define SHADER_NAME`

Only dat.gui?

Just an idea... give binding for other UI/Debug libraries?

Uniform not detected when after `;` there is no space

Fix clone material

Do not show tab in dat gui if there are no uniforms

Apply to all threejs shaders?

Just an idea, we could plug and use the magic comments everywhere on three.js without even using the MagicShader class...