WebGPU Shading Language

https://www.w3.org/TR/2021/WD-WGSL-20210713/
Admin
WebGPU Shading Language (WGSL) is the shader language for WebGPU, allowing applications to express...
Tokens:90,603
Snippets:548
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example using hypothetical extensions

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Example showing the enable directive for hypothetical f16 and rounding_mode_f16 extensions, including a redundant enable directive and an attribute enabled by the extension.

```wgsl
// Enable a hypothetical IEEE binary16 floating point extension.
enable f16;

// Assuming the f16 extension enables use of the f16 type:
//    - as function return value
//    - as the type for let declaration
//    - as a type constructor, with an i32 argument
//    - as operands to the division operator: /
fn halve_it(x: f16) -> f16 {
   let two: f16 = f16(2);
   return x / two;
};

enable f16; // A redundant enable directive is ok.
// Enable a hypothetical extension adding syntax for controlling
// the rounding mode on f16 arithmetic.
enable rounding_mode_f16;

[[round_to_even_f16]] // Attribute enabled by the rounding_mode_f16 extension
fn triple_it(x: f16) -> f16 {
   return x * f16(3); // Uses round-to-even.
};

```

--------------------------------

### WGSL simple functions example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Example of a user-defined function 'add_two' with two parameters and a return type, and a compute shader entry point 'main' that calls it.

```wgsl
// Declare the add_two function.
// It has two formal paramters, i and b.
// It has a return type of i32.
// It has a body with a return statement.
fn add_two(i: i32, b: f32) -> i32 {
  return i + 2;  // A formal parameter is available for use in the body.
}

// A compute shader entry point function, 'main'.
// It has no specified return type.
// It invokes the ordinary_two function, and captures
// the resulting value in the named value 'two'.
[[stage(compute)]] fn main() {
   let six: i32 = add_two(4, 5.0);
}

```

--------------------------------

### WGSL vector access example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows how to access vector components using convenience names and array subscripting. Demonstrates that swizzles can be reordered and duplicated, and that array indexing starts at zero.

```wgsl
var a: vec3<f32> = vec3<f32>(1., 2., 3.);
var b: f32 = a.y;          // b = 2.0
var c: vec2<f32> = a.bb;   // c = (3.0, 3.0)
var d: vec3<f32> = a.zyx;  // d = (3.0, 2.0, 1.0)
var e: f32 = a[1];         // e = 2.0

```

--------------------------------

### For to Loop Transformation Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows a for loop and its equivalent loop statement transformation. The for loop initializer runs once, the condition is checked at the start of each iteration, and the continuing statement runs at the end of the body.

```wgsl
for(var i: i32 = 0; i < 4; i = i + 1) {
  if (a == 0) {
    continue;
  }
  a = a + 2;
}

```

```wgsl
{ // Introduce new scope for loop variable i
  var i: i32 = 0;
  var a: i32 = 0;
  loop {
    if (!(i < 4)) {
      break;
    }

    if (a == 0) {
      continue;
    }
    a = a + 2;

    continuing {
      i = i + 1;
    }
  }
}

```

--------------------------------

### Pointer Type Example with Comments

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Illustrates pointer type declarations in WGSL source, showing the fully parameterized form in comments. The example includes pointers to i32 and array<f32,50> in different storage classes, with implied read_write access mode.

```wgsl
fn my_function(
  // 'ptr<function,i32,read_write>' is the type of a pointer value that references
  // storage for keeping an 'i32' value, using memory locations in the 'function'
  // storage class.  Here 'i32' is the pointee type.
  // The implied access mode is 'read_write'. See below for access mode defaults.
  ptr_int: ptr<function,i32>,

  // 'ptr<private,array<f32,50>,read_write>' is the type of a pointer value that
  // refers to storage for keeping an array of 50 elements of type 'f32', using
  // memory locations in the 'private' storage class.
  // Here the pointee type is 'array<f32,50>'.
  // The implied access mode is 'read_write'. See below for access mode defaults.
  ptr_array: ptr<private, array<f32, 50>>
) { }
```

--------------------------------

### Zero-valued arrays example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows how to create a zero-valued array using the type followed by empty parentheses, and the equivalent explicit constructor with zero elements.

```wgsl
array<bool, 2>()               // The zero-valued array of two booleans.
array<bool, 2>(false, false)   // The same value, written explicitly.

```

--------------------------------

### Variable decorations example in WGSL

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows how group and binding attributes map to SPIR-V decorations DescriptorSet and Binding. The example uses group(4) and binding(3).

```wgsl
[[group(4), binding(3)]]
   OpDecorate %variable DescriptorSet 4
   OpDecorate %variable Binding 3
```

--------------------------------

### Component-wise addition example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Illustrates component-wise addition of two vec3<f32> vectors, with comments showing each component result.

```wgsl
let x : vec3<f32> = a + b; // a and b are vec3<f32>
// x[0] = a[0] + b[0]
// x[1] = a[1] + b[1]
// x[2] = a[2] + b[2]

```

--------------------------------

### Zero-valued vectors example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows how to create zero-valued vectors using the type followed by empty parentheses, and the equivalent explicit constructor with zero elements.

```wgsl
vec2<f32>()                 // The zero-valued vector of two f32 elements.
vec2<f32>(0.0, 0.0)         // The same value, written explicitly.

vec3<i32>()                 // The zero-valued vector of three i32 elements.
vec3<i32>(0, 0, 0)          // The same value, written explicitly.

```

--------------------------------

### Type Declarations Example with SPIR-V

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Examples of WGSL type declarations and their corresponding SPIR-V instructions, showing how identifiers, scalars, vectors, arrays, and matrices map to SPIR-V types.

```wgsl
identifier
  Allows to specify types created by the type command

bool
   %1 = OpTypeBool

f32
   %2 = OpTypeFloat 32

i32
   %3 = OpTypeInt 32 1

u32
   %4 = OpTypeInt 32 0

vec2<f32>
    %7 = OpTypeVector %float 2

array<f32, 4>
   %uint_4 = OpConstant %uint 4
        %9 = OpTypeArray %float %uint_4

[[stride(32)]] array<f32, 4>
             OpDecorate %9 ArrayStride 32
   %uint_4 = OpConstant %uint 4
        %9 = OpTypeArray %float %uint_4

array<f32>
   %rtarr = OpTypeRuntimeArray %float

mat2x3<f32>
   %vec = OpTypeVector %float 3
     %6 = OpTypeMatrix %vec 2

```

--------------------------------

### WGSL Loop with continue Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

The equivalent WGSL loop using continue to skip even iterations.

```wgsl
var a: i32 = 2;
var i: i32 = 0;
loop {
  if (i >= 4) { break; }

  let step: i32 = 1;

  i = i + 1;
  if (i % 2 == 0) { continue; }

  a = a * 2;
}

```

--------------------------------

### Vector type example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows a vector of two f32 components.

```wgsl
vec2<f32>  // is a vector of two f32s.

```

--------------------------------

### Type Alias Grammar and Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Grammar rule for type aliases and an example showing two type alias declarations: one for a fixed-size array and one for a runtime-sized array with a stride attribute.

```wgsl
type_alias
  : TYPE IDENT EQUAL type_decl

```

```wgsl
type Arr = array<i32, 5>;

type RTArr = [[stride(16)]] array<vec4<f32>>;

```

--------------------------------

### SPIR-V examples for constants

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows how WGSL constant expressions map to SPIR-V instructions. Each line pairs a WGSL constant with its corresponding SPIR-V OpConstant or OpConstantComposite instruction.

```spirv
-1
   %a = OpConstant %int -1

2
   %b = OpConstant %uint 2

3.2
   %c = OpConstant %float 3.2

true
    %d = OpConstantTrue

false
    %e = OpConstant False

vec4<f32>(1.2, 2.3, 3.4, 2.3)
    %f0 = OpConstant %float 1.2
    %f1 = OpConstant %float 2.3
    %f2 = OpConstant %float 3.4
     %f = OpConstantComposite %v4float %f0 %f1 %f2 %f1

```

--------------------------------

### GLSL Loop with continue Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

A GLSL for loop that uses continue to skip even iterations.

```glsl
int a = 2;
let int step = 1;
for (int i = 0; i < 4; i += step) {
  if (i % 2 == 0) continue;
  a *= 2;
}

```

--------------------------------

### Zero-valued structures example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Defines a Student structure and demonstrates three ways to create its zero value: using Student(), explicit zero arguments, and zero-valued members.

```wgsl
struct Student {
  grade: i32;
  GPA: f32;
  attendance: array<bool,4>;
};

fn func() {
  var s: Student;

  // The zero value for Student
  s = Student();

  // The same value, written explicitly.
  s = Student(0, 0.0, array<bool,4>(false, false, false, false));

  // The same value, written with zero-valued members.
  s = Student(i32(), f32(), array<bool,4>());
}

```

--------------------------------

### Assignment examples

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Examples of assignment statements in WGSL, including variable assignment, struct field assignment, vector component assignment, pointer dereference assignment, and copying a struct.

```wgsl
struct S {
    age: i32;
    weight: f32;
};
var<private> person: S;

fn f() {
    var a: i32 = 20;
    a = 30;           // Replace the contents of 'a' with 30.

    person.age = 31;  // Write 31 into the age field of the person variable.

    var uv: vec2<f32>;
    uv.y = 1.25;      // Place 1.25 into the second component of uv.

    let uv_x_ptr: ptr<function,f32> = &uv.x;
    *uv_x_ptr = 2.5;   // Place 2.5 into the first component of uv.

    var friend: S;
    // Copy the contents of the 'person' variable into the 'friend' variable.
    friend = person;
}

```

--------------------------------

### GLSL Loop Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

A simple GLSL for loop that doubles a variable four times.

```glsl
int a = 2;
for (int i = 0; i < 4; i++) {
  a *= 2;
}

```

--------------------------------

### Matrix type example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows a 2-column, 3-row matrix of 32-bit floats, equivalent to two column vectors of type vec3<f32>.

```wgsl
mat2x3<f32>  // This is a 2 column, 3 row matrix of 32-bit floats.
             // Equivalently, it is 2 column vectors of type vec3<f32>.

```

--------------------------------

### WGSL structure with runtime array and block attribute

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

WGSL example showing a runtime-sized array with stride attribute and a block-decorated structure containing it.

```WGSL
// Runtime Array
type RTArr = [[stride(16)]] array<vec4<f32>>;
[[block]] struct S {
  a: f32;
  b: f32;
  data: RTArr;
};

```

--------------------------------

### WGSL structure layout example with implicit member sizes, alignments, and strides

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows a WGSL struct 'A' with members of types f32 and vec2<f32>. The comments indicate the alignment and size of the struct and each member, including implicit padding at the end. This example illustrates the structure layout rules defined in section 4.3.7.2.

```wgsl
struct A {                                     //             align(8)  size(24)
    u: f32;                                    // offset(0)   align(4)  size(4)
    v: f32;                                    // offset(4)   align(4)  size(4)
    w: vec2<f32>;                              // offset(8)   align(8)  size(8)
    x: f32;                                    // offset(16)  align(4)  size(4)
    // -- implicit struct size padding --      // offset(20)            size(4)
};
```

--------------------------------

### Pipeline-overridable constants example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Demonstrates `let` declarations with the `override` attribute. Shows explicit pipeline constant IDs, optional initializers, and the requirement that constants without initializers must be overridden at pipeline creation time.

```wgsl
[[override(0)]]    let has_point_light: bool = true;  // Algorithmic control
[[override(1200)]] let specular_param: f32 = 2.3;     // Numeric control
[[override(1300)]] let gain: f32;                     // Must be overridden
[[override]]       let width: f32 = 0.0;              // Specifed at the API level using
                                                      // the name "width".
[[override]]       let depth: f32;                    // Specifed at the API level using
                                                      // the name "depth".
                                                      // Must be overridden.

```

--------------------------------

### WGSL Loop Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

The equivalent WGSL loop using a loop statement with an explicit break condition.

```wgsl
let a: i32 = 2;
var i: i32 = 0;      // <1>
loop {
  if (i >= 4) { break; }

  a = a * 2;

  i = i + 1;
}

```

--------------------------------

### WGSL structure with f32 and vec4 members

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Simple WGSL structure example with two members: a f32 and a vec4<f32>.

```WGSL
struct my_struct {
  a: f32;
  b: vec4<f32>;
};

```

--------------------------------

### Sample translation for reading a variable multiple times

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

SPIR-V representation of the previous WGSL example, showing each variable access as an OpLoad and arithmetic operations.

```spirv
%temp_1 = OpLoad %float %x
%temp_2 = OpLoad %float %x
%temp_3 = OpFMul %float %temp_1 %temp_2
%temp_4 = OpLoad %float %x
%temp_5 = OpFAdd %float %temp_3 %temp_4
%y      = OpFAdd %float %temp_5 %one

```

--------------------------------

### Module constants example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows two module-scope `let` declarations: one with explicit type `f32` and one with inferred type `vec3<i32>`. The initializer is required when no attributes are present.

```wgsl
// The golden ratio.
let golden: f32 = 1.61803398875;

// The second unit vector for three dimensions, with inferred type.
let e2 = vec3<i32>(0,1,0);

```

--------------------------------

### WGSL Entry Point Example: vertex, fragment, and compute shaders

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows three entry point declarations: a vertex shader returning a builtin position, a fragment shader taking a builtin position and returning a location 0 color, and a compute shader with no return type. Each includes SPIR-V comments showing the expected OpEntryPoint and decorations.

```wgsl
[[stage(vertex)]]
fn vert_main() -> [[builtin(position)]] vec4<f32> {
  return vec4<f32>(0.0, 0.0, 0.0, 1.0);
}
   // OpEntryPoint Vertex %vert_main "vert_main" %return_value
   // OpDecorate %return_value BuiltIn Position
   // %float = OpTypeFloat 32
   // %v4float = OpTypeVector %float 4
   // %ptr = OpTypePointer Output %v4float
   // %return_value = OpVariable %ptr Output

[[stage(fragment)]]
fn frag_main([[builtin(position)]] coord_in: vec4<f32>) -> [[location(0)]] vec4<f32> {
  return vec4<f32>(coord_in.x, coord_in.y, 0.0, 1.0);
}
   // OpEntryPoint Fragment %frag_main "frag_main" %return_value %coord_in
   // OpDecorate %return_value Location 0
   // %float = OpTypeFloat 32
   // %v4float = OpTypeVector %float 4
   // %ptr = OpTypePointer Output %v4float
   // %return_value = OpVariable %ptr Output

[[stage(compute)]]
fn comp_main() { }
   // OpEntryPoint GLCompute %comp_main "comp_main"
```

--------------------------------

### Discard Statement Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Example of using the discard statement in a fragment shader to terminate the invocation and prevent the fragment from being processed downstream. The helper function discards if the position is too shallow, and the main function sets a flag and emits red only if the discard was not executed.

```wgsl
var<private> will_emit_color: bool = false;

fn discard_if_shallow(pos: vec4<f32>) {
  if (pos.z < 0.001) {
    // If this is executed, then the will_emit_color flag will
    // never be set to true.
    discard;
  }
  will_emit_color = true;
}

[[stage(fragment)]]
fn main([[builtin(position)]] coord_in: vec4<f32>)
  -> [[location(0)]] vec4<f32>
{
  discard_if_shallow(coord_in);

  // Set the flag and emit red, but only if the helper function
  // did not execute the discard statement.
  will_emit_color = true;
  return vec4<f32>(1.0, 0.0, 0.0, 1.0);
}

```

--------------------------------

### Access Modes for Buffers Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Shows how to declare storage and uniform buffers with different access modes. Storage buffers default to read-only, while read_write allows both read and write. Uniform buffers are always read-only and have more restrictive layout rules.

```wgsl
// Storage buffers
[[group(0), binding(0)]]
var<storage,read> buf1: Buffer;       // Can read, cannot write.
[[group(0), binding(0)]]
var<storage> buf2: Buffer;            // Can read, cannot write.
[[group(0), binding(1)]]
var<storage,read_write> buf3: Buffer; // Can both read and write.

// Uniform buffer. Always read-only, and has more restrictive layout rules.
struct ParamsTable {};
[[group(0), binding(2)]]
var<uniform> params: ParamsTable;     // Can read, cannot write.

```

--------------------------------

### WGSL declaration and scope example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

This example demonstrates valid and invalid WGSL declarations, illustrating scope rules for variables, functions, and parameters. It shows that reusing built-in function names (like 'modf') is invalid, and that declarations with the same end scope are not allowed. The comments in the code indicate the scope of each declared identifier.

```wgsl
// Invalid, cannot reuse built-in function names.
var<private> modf: f32 = 0.0;

// Valid, foo_1 is in scope until the end of the program.
var<private> foo: f32 = 0.0; // foo_1

// Valid, bar_1 is in scope until the end of the program.
var<private> bar: u32 = 0u; // bar_1

// Valid, my_func_1 is in scope until the end of the program.
// Valid, foo_2 is in scope until the end of the function.
fn my_func(foo: f32) { // my_func_1, foo_2
  // Any reference to 'foo' resolves to the function parameter.

  // Invalid, the scope of foo_3 ends at the of the function.
  var foo: f32; // foo_3

  // Valid, bar_2 is in scope until the end of the function.
  var bar: u32; // bar_2
  // References to 'bar' resolve to bar_2
  {
    // Valid, bar_3 is in scope until the end of the compound statement.
    var bar: u32; // bar_3
    // References to 'bar' resolve to bar_3

    // Invalid, bar_4 has the same end scope as bar_3.
    var bar: i32; // bar_4

    // Valid, i_1 is in scope until the end of the for loop
    for (var i: i32 = 0; i < 10; i = i + 1) { // i_1
      // Invalid, i_2 has the same end scope as i_1.
      var i: i32 = 1; // i_2.
    }
  }

  // Invalid, bar_5 has the same end scope as bar_2.
  var bar: u32; // bar_5
}

// Invalid, bar_6 has the same end scope as bar_1.
var<private> bar: u32 = 1u; // bar_6

// Invalid, my_func_2 has the same end scope as my_func_1.
fn my_func() { } // my_func_2

// Valid, my_foo_1 is in scope until the end of the program.
fn my_foo(
  // Valid, my_foo_2 is in scope until the end of the function.
  my_foo: i32 // my_foo_2
) { }

```

--------------------------------

### Mapping workgroupBarrier and storageBarrier to SPIR-V

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

Example showing how storageBarrier and workgroupBarrier map to SPIR-V OpControlBarrier instructions, including execution scope, memory scope, and memory semantics. Also shows that consecutive barriers can be combined into a single OpControlBarrier.

```wgsl
storageBarrier();
// Maps to:
// Execution Scope is Workgroup = %uint_2
// Memory Scope is Device = %uint_1
// Memory Semantics are AcquireRelease | UniformMemory (0x8 | 0x40) = %uint_72
// OpControlBarrier %uint_2 %uint_1 %uint_72

workgroupBarrier();
// Maps to:
// Execution and Memory Scope are Workgroup = %uint_2
// Memory semantics are AcquireRelease | WorkgroupMemory (0x8 | 0x100) = %uint_264
// OpControlBarrier %uint_2 %uint_2 %uint_264

workgroupBarrier();
storageBarrier();
// Or, equivalently:
storageBarrier();
workgroupBarrier();
// Could be mapped to a single OpControlBarrier:
// Execution scope is Workgroup = %uint_2
// Memory Scope is Device = %uint_1
// Memory semantics are AcquireRelease | UniformMemory | WorkgroupMemory
//   (0x8 | 0x40 | 0x100) = %uint_328
// OpControlBarrier %uint_2 %uint_1 %uint_328

```

--------------------------------

### WGSL Loop with continue and continuing Example

Source: https://www.w3.org/TR/2021/WD-WGSL-20210713

A WGSL loop that uses a continuing construct to update the loop variable.

```wgsl
var a: i32 = 2;
var i: i32 = 0;
loop {
  if (i >= 4) { break; }

  let step: i32 = 1;

  if (i % 2 == 0) { continue; }

  a = a * 2;

  continuing {   // <2>
    i = i + step;
  }
}

```
Tokens:
Raw