Voxel tunnel by lsdlives

License: CC BY-SA-NC

<shaderview>

A Web Component for rendering WebGL shaders

Using Shaderview in a build tool / bundler:

If you're building on top of a framework or use build tooling such as Vite or Rollup, you can install the module as a dependency:

npm install git+https://github.com/keithclark/shaderview

You can now import the element from the module and define it in the component registry using your preferred tag name:

import ShaderviewElement from '@keithclark/shaderview';
customElements.define('kc-shaderview', ShaderviewElement);

Using Shaderview directly in a browser:

Method 1: Use a local copy of the files:

Download the minified JavaScript module, save it locally, import the element and register it:

<script type="module">
  import ShaderviewElement from './path/to/element.js';
  customElements.define('kc-shaderview', ShaderviewElement);
</script>

Method 2: Load from a CDN:

Import the component directly from a CDN and register it:

<script type="module">
  import ShaderviewElement from 'https://cdn.jsdelivr.net/gh/keithclark/shaderview@1.2.0/dist/shaderview.min.js';
  customElements.define('kc-shaderview', ShaderviewElement);
</script>

Embedding a shader into a web page

Adding a shader to your page is as simple as dropping in the new element and defining the shader source(s).

<kc-shaderview>
  <script type="x-shader/x-fragment"></script>

  <!-- optional -->
  <script type="x-shader/x-vertex"></script>

  <!-- optional -->
  <img src="fallback.web" alt="Fallback image description">                  
</kc-shaderview>

Setting the shader source code

A shader source is embedded by adding child <script> elements to the shaderview. The type attribute determines which shader type is the script is defining. For a fragment shader, use x-shader/x-fragment and for a vertex shader use x-shader/x-vertex. In the majority of cases you won't need to provide a vertex shader as shaderview will set a default for you.

Shader source code can be declared in one of two ways; externally referenced by URL, or inline. To load an external shader from a URL, set the src attribute of the relevant <script> element. (Note: CORS restrictions apply):

<kc-shaderview autoplay>
  <script type="x-shader/x-fragment" src="cubed.glsl"></script>
</kc-shaderview>

To embed the shader directly in your document simply omit the src attribute and supply the source code as text content:

<kc-shaderview autoplay>
  <script type="x-shader/x-fragment">
    // Shader by kishimisu | CC BY-SA-NC
    // https://www.shadertoy.com/view/mtyGWy
    precision mediump float;
    uniform float uTime;
    uniform vec2 uResolution;
    
    // https://iquilezles.org/articles/palettes/
    vec3 palette( float t ) {
      vec3 a = vec3(0.5, 0.5, 0.5);
      vec3 b = vec3(0.5, 0.5, 0.5);
      vec3 c = vec3(1.0, 1.0, 1.0);
      vec3 d = vec3(0.263,0.416,0.557);
      return a + b*cos( 6.28318*(c*t+d) );
    }
    
    void main() {
      vec2 uv = (gl_FragCoord.xy * 2.0 - uResolution.xy) / uResolution.y;
      vec2 uv0 = uv;
      vec3 finalColor = vec3(0.0);
      for (float i = 0.0; i < 4.0; i++) {
        uv = fract(uv * 1.5) - 0.5;
        float d = length(uv) * exp(-length(uv0));
        vec3 col = palette(length(uv0) + i*.4 + uTime*.4);
        d = sin(d*8. + uTime)/8.;
        d = abs(d);
        d = pow(0.01 / d, 1.2);
        finalColor += col * d;
      }
      gl_FragColor = vec4(finalColor, 1.0);
    }
  </script>
</kc-shaderview>

Autoplay

The shaders in the previous examples are automatically playing because the boolean autoplay attribute is set on the <kc-shaderview> element. Autoplay starts playback as soon as the shader has finshed compiling and is ready to render. If you prefer to control playback with JavaScript, you can remove the autoplay attribute and use the ShaderviewElement API instead.

Fallback Content

Any child content not directly controlling shader input (i.e. <script type="x-shader/*"> elements) will be hidden once the shaderview component is defined and a WebGL context has been established. If either of these fail then the fallback content will be rendered instead. An <img> element showing a frame from the shader works well.

Controlling Shaders using Uniforms

Uniforms allow shaders to receive values from JavaScript through the WebGL API. Shaderview exposes two uniform values to the attached fragment and vertex shaders:

uResolution

A vec2 containing the element dimensions. This value can be used to calculate the aspect ratio of your shader. Its value is not accessible via the ShaderviewElement API.

uTime

A float containing the current playback time. This value can be set using ShaderviewElement API, via the time property. Changing this value will cause the next frame to render from the new time. If the shader is playing, this value will automatically increment every animation frame.

In the following example, the shader element is paused and a range input is used to set the time property — drag it to see the effect.

<kc-shaderview id="shader">
  <script type="x-shader/x-fragment" src="mandala.glsl"></script>
</kc-shaderview>

<script>
  const shader = document.getElementById('shader');
  const input = document.getElementById('range');
  input.oninput = () => shader.time = input.valueAsNumber;
</script>

Besided the built-in uniforms, the ShaderviewElement API exposes a setUniform method for setting the values of other uniforms defined in the shader.

In the following example, a uniform is used to pass the current pointer position to the shader, which draws a smiley/emoji that tracks the pointer around the viewport. The original version of the shader animated between two facial expressions but, for this example, the distance of the pointer from the shader is fed to the time property to control the facial animation. Notice how the expressiong changes from intrigue to excitement as the pointer gets closer?

<kc-shaderview id="smiley">
  <script type="x-shader/x-fragment" src="smiley.glsl"></script>
</kc-shaderview>

<script>
  customElements.whenDefined('kc-shaderview').then(() => {
    window.addEventListener('pointermove', (e) => {
      const b = smiley.getBoundingClientRect();

      // Set the position uniform. The shader expects 
      // uPosition to be a `vec2` type.
      const x = e.clientX - b.left - b.width / 2;
      const y = e.clientY - b.top - b.height / 2; 
      smiley.setUniform('uPosition', x, y);

      // Use pointer distance to change facial expression
      smiley.time = 3 - Math.sqrt(x * x + y * y) / 300;
    });
  });
</script>

Below is a simpler example. This shader draws a crosshair at the coordinates specified by the uPosition uniform. The fragment shader source code has been inlined to demonstrate how the uPosition uniform is declared and how its value assigned from JavaScript. Here's how it works:

• uPosition is declared in the fragment shader as a vec2, which has an x and y component.
• A pointermove event handler is registered on the <kc-shaderview> element, allowing the pointer position to be tracked as it moves across the element.
• In the event handler, the pointer x and y coordinates are localised so they are relative to the elements bounding box. Finally, shaderview.setUniform('uPosition', x, y) is called, which updates the vec2 uniform with the new values and triggers a re-render.

<kc-shaderview id="crosshair">
  <script type="x-shader/x-fragment">
    precision highp float;
    uniform vec2 uPosition;

    void main() {
      vec3 color = vec3(0.7, 0.2, 1.0);
      color *= 1.25 - min(
        abs(gl_FragCoord.x - uPosition.x),
        abs(gl_FragCoord.y - uPosition.y)
      ) / 12.0;
      gl_FragColor = vec4(color, 1.0);
    }
  </script>
</kc-shaderview>

<script>
  customElements.whenDefined('kc-shaderview').then(() => {
    crosshair.addEventListener('pointermove', (e) => {
      const b = crosshair.getBoundingClientRect();

      // Set the position uniform 
      // Note: Y-axis is inverted in GLSL
      const x = e.clientX - b.left;
      const y = b.bottom - e.clientY; 
      crosshair.setUniform('uPosition', x, y);
    });
  });
</script>

Cubed! by Keith Clark

License: CC BY-SA-NC

JavaScript API

Methods

pause()

Pauses playback of the shader. Once playback stops, a pause event is dispatched. This event does not bubble and cannot be cancelled.

play()

Starts playback of the shader once it is ready. Returns a Promise that resolves when playback starts. Failure to begin playback for any reason will result in the promise being rejected.

Once playback begins, a playing event is dispatched. This event does not bubble and cannot be cancelled.

await myShader.play();

setUniform(name, ...values)

Sets a named uniform in the shader program to a new value.

myShader.setUniform('myFloat', 1.5);           // set a float to 1.5
myShader.setUniform('myVec2', 1, 2);           // set a vec2 to x=1, y=2
myShader.setUniform('myVec3', 1, 2, 3);        // set a vec3 to x=1, y=2, z=3
myShader.setUniform('myVec4', 1, 2, 3, 4);     // set a vec4 to x=1, y=2, z=3, w=4

Properties

autoplay

A boolean property that reflects the autoplay HTML attribute, indicating whether playback should begin automatically once the shader is ready.

fragmentShader Read only

Returns the HTMLScriptElement used as the fragment shader source or null if no shader is configured.

paused Read only

Returns a boolean that indicates whether the shader is paused.

time

Gets or sets the current playback time, in seconds.

vertexShader Read only

Returns the HTMLScriptElement used as the vertex shader source or null if no shader is configured.

Events

error

Triggered if one or more shaders cannot be loaded or if a shader could not be compiled.

load

Triggered when the shader element has succesfully compiled the shader and is ready.

pause

Triggered when playback pauses. This event does not bubble and cannot be cancelled.

playing

Triggered when playback starts. This event does not bubble and cannot be cancelled.