Custom Shaders in q5 WebGPU

What's a shader?

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

WGSL is a C-like, low-level, statically-typed shading language. It's a superior alternative to WebGL's 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
• the fragment function, which computes the color of every pixel

Take Google's Tour of WGSL to learn more.

How does q5 make writing shaders easier?

q5's shader creation functions add 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 members
  • 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/shaders/shapes.wgsl

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/shaders/image.wgsl

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

Functions:

• applyTint: applies the tint color to the sampled texture color

Text Shader

Source: https://github.com/q5js/q5.js/blob/main/src/shaders/text.wgsl

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

Functions:

• calcPos: calculates the vertex position in canvas pixel coordinates
• calcUV: calculates the UV mapping coordinates of the character in the texture
• calcDist: calculates the distance to the nearest edge of the glyph using the MSDF technique