Custom Shaders in q5 WebGPU

What's a shader?

Shaders are programs written in WGSL (WebGPU Shading Language).

WGSL is a C-like, low-level, statically-typed shading language that's a superior alternative to GLSL because WebGPU provides more helpful error messages and better performance.

The primary components of a shader are the vertex function, which is run for every vertex, and the fragment function, which computes the color of every pixel drawn on the canvas.

Take Google's Tour of WGSL to learn more.

How does q5 make writing shaders easier?

q5's shader creation functions adds code from q5's default shaders to your custom vertex and/or fragment functions. This makes it easier to get started with WGSL programming, without having to create the pipelines, data buffers, and all the other WebGPU stuff required to run shaders.

When using q5's shader creation functions, be sure to start your shader code excerpts with "@vertex" or "@fragment".

Shaders created with q5 can access the following data, which is updated every frame:

• q struct variable with q5 instance data
  • width, height, halfWidth, halfHeight, frameCount, time, deltaTime, mouseX, mouseY, mouseIsPressed, keyCode, keyIsPressed
• transforms array of 4x4 transformation matrices
• colors array of colors in [r, g, b, a] float format

Additionally, the transformVertex helper function can apply a transformation matrix to a vertex, then convert it from canvas pixel coordinates to normalized device coordinates (NDC).

Shapes Shader

Source: https://github.com/q5js/q5.js/blob/main/src/q5-webgpu-shapes.js

Vertex parameters:

• vertexIndex: index of the vertex
• pos: vertex position in canvas pixel coordinates
• colorIndex: index of the color in the colors array
• matrixIndex: index of the transformation matrix in the transforms array

Fragment parameters:

• position: fragment position in NDC
• color: fragment color in [r, g, b, a] float format

Image Shader

Source: https://github.com/q5js/q5.js/blob/main/src/q5-webgpu-image.js

Vertex parameters:

• vertexIndex: index of the vertex
• pos: vertex position in canvas pixel coordinates
• texCoord: texture coordinate in [u, v] float format
• tintIndex: index of the tint color in the colors array
• matrixIndex: index of the transformation matrix in the transforms array
• imageAlpha: alpha value to apply to the image

Fragment parameters:

• position: fragment position in NDC
• texCoord
• tintColor: tint color in [r, g, b, a] float format
• imageAlpha

Data:

• samp: sampler to use
• tex: texture to sample

Text Shader

Source: https://github.com/q5js/q5.js/blob/main/src/q5-webgpu-text.js

Vertex parameters:

• vertexIndex: index of the vertex
• instanceIndex: index of the text character

Fragment parameters:

• position: fragment position in NDC
• texCoord: texture coordinate in [u, v] float format
• fillColor: fill color in [r, g, b, a] float format
• strokeColor: stroke color in [r, g, b, a] float format
• strokeWeight: stroke weight

Data:

• textChars: array of characters to render
• textMetadata: array of text metadata
  • pos: position of the text
  • scale: scale of the text
  • fillIndex: index of the fill color in the colors array
  • strokeIndex: index of the stroke color in the colors array
  • strokeWeight: stroke weight
• fontChars: array of font character data
  • size: size of the character
  • offset: offset of the character
  • texExtent: size of the character in the texture
  • texOffset: position of the character in the texture