Tour of WGSL

WGSL expressions are evaluated at different stages of a shader's lifecycle. Understanding these phases is critical for knowing when a value is finalized and what types of sub-expressions are available to you.

1. Shader creation time: Finalizes const-expressions. These include literals, @const function calls, and values declared as const.
2. Pipeline creation time: Finalizes override-expressions. These include everything in a const-expression, plus override-declared values and values provided via GPUProgrammablestage.constants.
3. Shader execution time: Finalizes runtime-expressions. These include everything in an override-expression, plus let-declared values, any function call, variable contents, and references or pointers to variables.

To prevent data races when multiple shader invocations access shared memory, you must follow two rules:

1. Use atomic types: Declare the memory locations with an atomic type. The WGSL type system will prevent ordinary (non-atomic) accesses to these locations.
2. Use atomic operations: Only access these memory words using atomic builtin functions.

Important Note on Ordering: Atomic operations guarantee that accesses to a single memory word occur in a consistent, sequential order from the perspective of all invocations. However, this ordering is not guaranteed across different memory words; causality may appear violated when comparing the order of operations on different words.

To populate the shader textbox on a specific page with a pre-defined shader, add a shader key to the document's frontmatter (the YAML block between --- delimiters at the top of the Markdown file).

Example frontmatter:

---
title: "My Shader Page"
shader: "path/to/your/shader.wgsl"
---

---
shader: <path to shader>
---

WGSL shaders execute with high parallelism and concurrency. Multiple invocations share variables in the workgroup, storage, and uniform address spaces. While uniform buffers are read-only, storage buffers with read_write access and workgroup variables can be both read and written.

A data race occurs when there are conflicting concurrent accesses to the same memory word (where at least one access is a write). Data races lead to unpredictable results with non-local effects and must be avoided.

To run the Tour of WGSL locally, you need Hugo Extended (v0.111.3 or newer) and Node.js. Follow these steps in the source directory:

1. Install Hugo Extended: Download the appropriate prebuilt package from Hugo Releases.
   • Example (Debian/Linux): Download hugo_extended_0.111.3_linux-amd64.deb and run dpkg -i hugo_extended_0.111.3_linux-amd64.deb.
2. Install dependencies: Run npm ci to install Node dependencies.
3. Start the server: Run npm run serve.

The site will be available at localhost:1313/tour-of-wgsl. Editing pages will trigger an auto-reload.

# Install dependencies
npm ci

# Run the Hugo webserver
npm run serve

To use the Inter fonts in your project:

1. Install the font files you want to use (either the variable font or the specific static files).
2. Use your application's font picker to view the font family and all available styles.

The tour requires WebGPU support. For Chrome, you must use version 113.xxx or newer (currently available via Chrome Canary).

To enable WebGPU:

1. Open chrome://flags/#enable-unsafe-webgpu.
2. Set Unsafe WebGPU to enabled.

Linux Users: If rendering issues persist (e.g., triangles not appearing), you may need to enable Vulkan support by setting Vulkan to enabled in chrome://flags/#enable-vulkan.

The tour includes an interactive editor for experimenting with WGSL shaders. The editor provides the following capabilities:

• Automatic Execution: Shaders are automatically executed as you type.
• Inline Error Messages: Compilation errors are displayed directly in the editor. You can also check the browser's developer console for detailed error logs.
• Documentation Lookup: While the cursor is on an attribute (e.g., @builtin) or a builtin function (e.g., sin), press ctrl-o to view documentation for that specific element.

You can add new content pages using the Hugo CLI or by manually creating Markdown files in the content/ directory.

To add a page via CLI: hugo new <path/to/file>.md

hugo new basics/for-loops.md

In WGSL, matrices support multiplication with other matrices, vectors, and scalars. This specific implementation demonstrates various multiplication combinations using a mat2x3f (a 2x3 matrix of 32-bit floats).

Supported operations shown in this module include:

• Matrix by Matrix
• Matrix by Scalar
• Scalar by Matrix
• Vector by Matrix
• Matrix by Vector
• Matrix by Matrix (different dimensions)

// The shader used for this demonstration is located at:
// ./multiplication.wgsl

The evaluation phases of a WGSL shader correspond directly to specific WebGPU device methods in your application flow:

The Inter font family is provided in two formats: a single variable font file and a collection of static font files.

Variable Font

If your application supports variable fonts, use the single file containing all styles. This allows you to select intermediate styles along the axes.

• File: Inter-VariableFont_slnt,wght.ttf
• Available Axes: slnt (slant) and wght (weight)

Static Fonts

If your application does not support variable fonts, use the individual static files for specific styles:

• static/Inter-Thin.ttf
• static/Inter-ExtraLight.ttf
• static/Inter-Light.ttf
• static/Inter-Regular.ttf
• static/Inter-Medium.ttf
• static/Inter-SemiBold.ttf
• static/Inter-Bold.ttf
• static/Inter-ExtraBold.ttf
• `static/Inter-Black.ttf