WebGPU Shading Language

W3C Working Draft,

More details about this document
This version:
https://www.w3.org/TR/2024/WD-WGSL-20241127/
Latest published version:
https://www.w3.org/TR/WGSL/
Editor's Draft:
https://gpuweb.github.io/gpuweb/wgsl/
Previous Versions:
History:
https://www.w3.org/standards/history/WGSL/
Feedback:
public-gpu@w3.org with subject line “[WGSL] … message topic …” (archives)
GitHub
Editors:
(Google)
(Google)
Former Editors:
(Apple Inc.)
(Google)
Participate:
File an issue (open issues)
Tests:
WebGPU CTS shader/

Abstract

Shading language for WebGPU.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Feedback and comments on this specification are welcome. GitHub Issues are preferred for discussion on this specification. Alternatively, you can send comments to the GPU for the Web Working Group’s mailing-list, public-gpu@w3.org (archives). This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid.

This document was published by the GPU for the Web Working Group as a Working Draft using the Recommendation track. This document is intended to become a W3C Recommendation.

Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 03 November 2023 W3C Process Document.

1. Introduction

WebGPU Shading Language (WGSL) is the shader language for [WebGPU]. That is, an application using the WebGPU API uses WGSL to express the programs, known as shaders, that run on the GPU.

// A fragment shader which lights textured geometry with point lights.

// Lights from a storage buffer binding.
struct PointLight {
  position : vec3f,
  color : vec3f,
}

struct LightStorage {
  pointCount : u32,
  point : array<PointLight>,
}
@group(0) @binding(0) var<storage> lights : LightStorage;

// Texture and sampler.
@group(1) @binding(0) var baseColorSampler : sampler;
@group(1) @binding(1) var baseColorTexture : texture_2d<f32>;

// Function arguments are values from the vertex shader.
@fragment
fn fragmentMain(@location(0) worldPos : vec3f,
                @location(1) normal : vec3f,
                @location(2) uv : vec2f) -> @location(0) vec4f {
  // Sample the base color of the surface from a texture.
  let baseColor = textureSample(baseColorTexture, baseColorSampler, uv);

  let N = normalize(normal);
  var surfaceColor = vec3f(0);

  // Loop over the scene point lights.
  for (var i = 0u; i < lights.pointCount; i++) {
    let worldToLight = lights.point[i].position - worldPos;
    let dist = length(worldToLight);
    let dir = normalize(worldToLight);

    // Determine the contribution of this light to the surface color.
    let radiance = lights.point[i].color * (1 / pow(dist, 2));
    let nDotL = max(dot(N, dir), 0);

    // Accumulate light contribution to the surface color.
    surfaceColor += baseColor.rgb * radiance * nDotL;
  }

  // Return the accumulated surface color.
  return vec4(surfaceColor, baseColor.a);
}

1.1. Overview

WebGPU issues a unit of work to the GPU in the form of a GPU command. WGSL is concerned with two kinds of GPU commands:

Both kinds of pipelines use shaders written in WGSL.

A shader is the portion of a WGSL program that executes a shader stage in a pipeline. A shader comprises:

Note: A WGSL program does not require an entry point; however, such a program cannot be executed by the API because an entry point is required to create a GPUProgrammableStage.

When executing a shader stage, the implementation:

A WGSL program is organized into:

Note: A WGSL program is currently composed of a single WGSL module.

WGSL is an imperative language: behavior is specified as a sequence of statements to execute. Statements can:

WGSL is statically typed: each value computed by a particular expression is in a specific type, determined only by examining the program source.

WGSL has types describing booleans and numbers (integers and floating point). These types can be aggregated into composites (vectors, matrices, arrays, and structures). WGSL has special types (e.g. atomics) that provide unique operations. WGSL describes the types that can be stored in memory as memory views. WGSL provides commonly used rendering types in the form of textures and samplers. These types have associated built-in functions to expose commonly provided GPU hardware for graphics rendering.

WGSL does not have implicit conversions or promotions from concrete types, but does provide implicit conversions and promotions from abstract types. Converting a value from one concrete numeric or boolean type to another requires an explicit conversion, value constructor, or reinterpretation of bits; however, WGSL does provide some limited facility to promote scalar types to vector types. This also applies to composite types.

The work of a shader stage is partitioned into one or more invocations, each of which executes the entry point, but under slightly different conditions. Invocations in a shader stage share access to certain variables:

However, the invocations act on different sets of shader stage inputs, including built-in inputs that provide an identifying value to distinguish an invocation from its peers. Each invocation has its own independent memory space in the form of variables in the private and function address spaces.

Invocations within a shader stage execute concurrently, and may often execute in parallel. The shader author is responsible for ensuring the dynamic behavior of the invocations in a shader stage:

WGSL sometimes permits several possible behaviors for a given feature. This is a portability hazard, as different implementations may exhibit the different behaviors. The design of WGSL aims to minimize such cases, but is constrained by feasibility, and goals for achieving high performance across a broad range of devices.

Behavioral requirements are actions the implementation will perform when processing or executing a WGSL program. They describe the implementation’s obligations in the contract with the programmer. The specification explicitly states these obligations when they might not be otherwise obvious.

1.2. Syntax Notation

Following syntax notation describes the conventions of the syntactic grammar of WGSL:

1.3. Mathematical Terms and Notation

Angles:

A hyperbolic angle is a unitless area, not an angle in the traditional sense. Specifically:

Then the area a is a hyperbolic angle such that x is the hyperbolic cosine of a, and y is the hyperbolic sine of a.

Positive infinity, denoted by +∞, is a unique value strictly greater than all real numbers.

Negative infinity, denoted by −∞, is a unique value strictly lower than all real numbers.

The extended real numbers (also known as the affinely extended real numbers) is the set of real numbers together with +∞ and −∞. Computers use floating point types to approximately represent the extended reals, including values for both infinities. See § 14.6 Floating Point Evaluation.

An interval is a contiguous set of numbers with a lower and upper bound. Depending on context, they are sets of integers, floating point numbers, real numbers, or extended real numbers.

The floor expression is defined for extended real numbers x:

The ceiling expression is defined for extended real numbers x:

The truncate function is defined for extended real numbers x:

The roundUp function is defined for positive integers k and n as:

The transpose of an c-column r-row matrix A is the r-column c-row matrix AT formed by copying the rows of A as the columns of AT:

The transpose of a column vector is defined by interpreting the column vector as a 1-row matrix. Similarly, the transpose of a row vector is defined by interpreting the row vector as a 1-column matrix.

2. WGSL Module

A WGSL program is composed of a single WGSL module.

A module is a sequence of optional directives followed by module scope declarations and const_assert statements. A module is organized into:

translation_unit :

global_directive * global_decl *

global_decl :

';'

| global_variable_decl ';'

| global_value_decl ';'

| type_alias_decl ';'

| struct_decl

| function_decl

| const_assert_statement ';'

2.1. Shader Lifecycle

There are four key events in the lifecycle of a WGSL program and the shaders it may contain. The first two correspond to the WebGPU API methods used to prepare a WGSL program for execution. The last two are the start and end of execution of a shader.

The events are:

  1. Shader module creation

    • This occurs when the WebGPU createShaderModule() method is called. The source text for a WGSL program is provided at this time.

  2. Pipeline creation

    • This occurs when the WebGPU createComputePipeline() method or the WebGPU createRenderPipeline() method is invoked. These methods use one or more previously created shader modules, together with other configuration information.

    • Only the code forming the shader of the specified entry point of the GPUProgrammableStage is considered during pipeline creation. That is, code unrelated to the entry point is effectively stripped before compilation.

    • Note: Each shader stage is considered to be compiled separately and, thus, might include different portions of the module.

  3. Shader execution start

  4. Shader execution end

    • This occurs when all work in the shader completes:

      • all its invocations terminate, and

      • all accesses to resources complete, and

      • outputs, if any, are passed to downstream pipeline stages.

The events are ordered due to:

2.2. Errors

A WebGPU implementation may fail to process a shader for two reasons:

A processing error may occur during three phases in the shader lifecycle:

Note: For example, a data race may not be detectable.

Each requirement will be checked at the earliest opportunity. That is:

When unclear from context, this specification indicates whether failure to meet a particular requirement results in a shader-creation, pipeline-creation, or dynamic error.

The consequences of an error are as follows:

2.3. Diagnostics

An implementation can generate diagnostics during shader module creation or pipeline creation. A diagnostic is a message produced by the implementation for the benefit of the application author.

A diagnostic is created, or triggered, when a particular condition is met, known as the triggering rule. The place in the source text where the condition is met, expressed as a point or range in the source text, is known as the triggering location.

A diagnostic has the following properties:

The severity of a diagnostic is one of the following, ordered from greatest to least:

error

The diagnostic is an error. This corresponds to a shader-creation error or to a pipeline-creation error.

warning

The diagnostic describes an anomaly that merits the attention of the application developer, but is not an error.

info

The diagnostic describes a notable condition that merits attention of the application developer, but is not an error or warning.

off

The diagnostic is disabled. It will not be conveyed to the application.

The name of a triggering rule is either:

diagnostic_rule_name :

diagnostic_name_token

| diagnostic_name_token '.' diagnostic_name_token

2.3.1. Diagnostic Processing

Triggered diagnostics will be processed as follows:

  1. For each diagnostic D, find the diagnostic filter with the smallest affected range that contains D’s triggering location, and which has the same triggering rule.

    • If such a filter exists, apply it to D, updating D's severity.

    • Otherwise D remains unchanged.

  2. Discard diagnostics that have severity off.

  3. If at least one remaining diagnostic DI has severity info, then:

    • Other info diagnostics with same triggering rule may be discarded, leaving only the original diagnostic DI.

  4. If at least one remaining diagnostic DW has severity warning, then:

    • Other info or warning diagnostics with same triggering rule may be discarded, leaving only the original diagnostic DW.

  5. If at least one remaining diagnostic has error severity, then:

  6. If processing during shader module creation time, the remaining diagnostics populate the messages member of the WebGPU GPUCompilationInfo object.

  7. If processing during pipeline creation, error diagnostics result in WebGPU validation failure when validating GPUProgrammableStage.

Note: The rules allow an implementation to stop processing a WGSL module as soon as an error is detected. Additionally, an analysis for a particular kind of warning can stop on the first warning, and an analysis for a particular kind of info diagnostic can stop on the first occurrence. WGSL does not specify the order to perform different kinds of analyses, or an ordering within a single analysis. Therefore, for the same WGSL module, different implementations may report different instances of diagnostics with the same severity.

2.3.2. Filterable Triggering Rules

Most diagnostics are unconditionally reported to the WebGPU application. Some kinds of diagnostics can be filtered, in part by naming their triggering rule. The following table lists the standard set of triggering rules that can be filtered.

Filterable diagnostic triggering rules
Filterable Triggering Rule Default Severity Triggering Location Description
derivative_uniformity error The location of the call site for any builtin function that computes a derivative. That is, the location of a call to any of: A call to a builtin function computes derivatives, but uniformity analysis cannot prove that the call occurs in uniform control flow.

See § 14.2 Uniformity.

Using an unrecognized triggering rule consisting of a single diagnostic name-token should trigger a warning from the user agent.

An implementation may support triggering rules not specified here, provided they are spelled using the multiple-token form of diagnostic_rule_name. Using an unrecognized triggering rule spelled in the multiple-token form may itself trigger a diagnostic.

Future versions of this specification may remove a particular rule or weaken its default severity (i.e. replace its current default with a less severe default) and still be deemed as satisfying backward compatibility. For example, a future version of WGSL may change the default severity for derivative_uniformity from error to either warning or info. After such a change to the specification, previously valid programs would remain valid.

2.3.3. Diagnostic Filtering

Once a diagnostic with a filterable triggering rule is triggered, WGSL provides mechanisms to discard the diagnostic, or to modify its severity.

A diagnostic filter DF has three parameters:

Applying a diagnostic filter DF(AR,NS,TR) to a diagnostic D has the following effect:

A range diagnostic filter is a diagnostic filter whose affected range is a specified range of source text. A range diagnostic filter is specified as a @diagnostic attribute at the start of the affected source range, as specified in the following table. A @diagnostic attribute must not appear anywhere else.

Placement of a range diagnostic filter
Placement Affected Range
Beginning of a compound statement. The compound statement.
Beginning of a function declaration. The function declaration.
Beginning of an if statement. The if statement: the if_clause and all associated else_if_clause and else_clause clauses, including all controlling condition expressions.
Beginning of a switch statement. The switch statement: the selector expression and the switch_body.
Beginning of a switch_body. The switch_body.
Beginning of a loop statement. The loop statement.
Beginning of a while statement. The while statement: both the condition expression and the loop body.
Beginning of a for statement. The for statement: the for_header and the loop body.
Immediately before the opening brace ('{') of the loop body of a loop, while, or for loop. The loop body.
Beginning of a continuing_compound_statement. The continuing_compound_statement.

Note: The following are also compound statements: a function body, a case clause, a default-alone clause, the bodies of while and for loops, and the bodies of if_clause, else_if_clause, and else_clause.

EXAMPLE: Range diagnostic filter on texture sampling
var<private> d: f32;
fn helper() -> vec4<f32> {
  // Disable the derivative_uniformity diagnostic in the
  // body of the "if".
  if (d < 0.5) @diagnostic(off,derivative_uniformity) {
    return textureSample(t,s,vec2(0,0));
  }
  return vec4(0.0);
}

A global diagnostic filter can be used to apply a diagnostic filter to the entire WGSL module.

EXAMPLE: Global diagnostic filter for derivative uniformity
diagnostic(off,derivative_uniformity);
var<private> d: f32;
fn helper() -> vec4<f32> {
  if (d < 0.5) {
    // The derivative_uniformity diagnostic is disabled here
    // by the global diagnostic filter.
    return textureSample(t,s,vec2(0,0));
  } else {
    // The derivative_uniformity diagnostic is set to 'warning' severity.
    @diagnostic(warning,derivative_uniformity) {
      return textureSample(t,s,vec2(0,0));
    }
  }
  return vec4(0.0);
}

Two diagnostic filters DF(AR1,NS1,TR1) and DF(AR2,NS2,TR2) conflict when:

Diagnostic filters must not conflict.

Note: Multiple global diagnostic filters are permitted when they do not conflict.

WGSL’s diagnostic filters are designed so their affected ranges nest perfectly. If the affected range of DF1 overlaps with the affected range of DF2, then either DF1’s affected range is fully contained in DF2’s affected range, or the other way around.

The nearest enclosing diagnostic filter for source location L and triggering rule TR, if one exists, is the diagnostic filter DF(AR,NS,TR) where:

Because affected ranges nest, the nearest enclosing diagnostic:

2.4. Limits

A WGSL implementation will support shaders that satisfy the following limits. A WGSL implementation may support shaders that go beyond the specified limits.

Note: A WGSL implementation should issue an error if it does not support a shader that goes beyond the specified limits.

Quantifiable shader complexity limits
Limit Minimum supported value
Maximum number of members in a structure type 1023
Maximum nesting depth of a composite type 15
Maximum nesting depth of brace-enclosed statements in a function 127
Maximum number of parameters for a function 255
Maximum number of case selector values in a switch statement. The sum of, for each case statement, the number of case values, including the default clause. 1023
Maximum combined byte-size of all variables instantiated in the private address space that are statically accessed by a single shader 8192
Maximum combined byte-size of all variables instantiated in the function address space that are declared in a single function 8192
Maximum combined byte-size of all variables instantiated in the workgroup address space that are statically accessed by a single shader

For the purposes of this limit, a fixed-footprint array is treated as a creation-fixed footprint array when substituting the override value.

This maps the WebGPU maxComputeWorkgroupStorageSize limit into a standalone WGSL limit.

16384
Maximum number of elements in value constructor expression of array type 2047

3. Textual Structure

The text/wgsl media type is used to identify content as a WGSL module. See Appendix A: The text/wgsl Media Type.

A WGSL module is Unicode text using the UTF-8 encoding, with no byte order mark (BOM).

WGSL module text consists of a sequence of Unicode code points, grouped into contiguous non-empty sets forming:

The program text must not include a null code point (U+0000).

3.1. Parsing

To parse a WGSL module:

  1. Remove comments:

    • Replace the first comment with a space code point (U+0020).

    • Repeat until no comments remain.

  2. Find template lists, using the algorithm in § 3.9 Template Lists.

  3. Parse the whole text, attempting to match the translation_unit grammar rule. Parsing uses a LALR(1) parser (one token of lookahead) [DeRemer1969], with the following customization:

    • Tokenization is interleaved with parsing, and is context-aware. When the parser requests the next token:

A shader-creation error results if:

3.2. Blankspace and Line Breaks

Blankspace is any combination of one or more of code points from the Unicode Pattern_White_Space property. The following is the set of code points in Pattern_White_Space:

A line break is a contiguous sequence of blankspace code points indicating the end of a line. It is defined as the blankspace signalling a "mandatory break" as defined by UAX14 Section 6.1 Non-tailorable Line Breaking Rules LB4 and LB5. That is, a line break is any of:

Note: Diagnostics that report source text locations in terms of line numbers should use line breaks to count lines.

3.3. Comments

A comment is a span of text that does not influence the validity or meaning of a WGSL program, except that a comment can separate tokens. Shader authors can use comments to document their programs.

A line-ending comment is a kind of comment consisting of the two code points // (U+002F followed by U+002F) and the code points that follow, up until but not including:

A block comment is a kind of comment consisting of:

Note: Block comments can be nested. Since a block comment requires matching start and end text sequences, and allows arbitrary nesting, a block comment cannot be recognized with a regular expression. This is a consequence of the Pumping Lemma for Regular Languages.

EXAMPLE: Comments
const f = 1.5; // This is line-ending comment.
const g = 2.5; /* This is a block comment
                that spans lines.
                /* Block comments can nest.
                 */
                But all block comments must terminate.
               */

3.4. Tokens

A token is a contiguous sequence of code points forming one of:

3.5. Literals

A literal is one of:

literal :

int_literal

| float_literal

| bool_literal

3.5.1. Boolean Literals

EXAMPLE: boolean literals
const a = true;
const b = false;
bool_literal :

'true'

| 'false'

3.5.2. Numeric Literals

The form of a numeric literal is defined via pattern-matching.

An integer literal is:

Note: A leading zero on a non-zero integer literal (e.g. 012) is forbidden, so as to avoid confusion with other languages' leading-zero-means-octal notation.

int_literal :

decimal_int_literal

| hex_int_literal

decimal_int_literal :

/0[iu]?/

| /[1-9][0-9]*[iu]?/

EXAMPLE: decimal integer literals
const a = 1u;
const b = 123;
const c = 0;
const d = 0i;
hex_int_literal :

/0[xX][0-9a-fA-F]+[iu]?/

EXAMPLE: hexadecimal integer literals
const a = 0x123;
const b = 0X123u;
const c = 0x3f;

A floating point literal is either a decimal floating point literal or a hexadecimal floating point literal.

float_literal :

decimal_float_literal

| hex_float_literal

A floating point literal has two logical parts: a significand to represent a fraction, and an optional exponent. Roughly, the value of the literal is the significand multiplied by a base value raised to the given exponent. A significand digit is significant if it is non-zero, or if there are significand digits to its left and to its right that are both non-zero. Significant digits are counted from left-to-right: the N'th significant digit has N-1 significant digits to its left.

A decimal floating point literal is:

decimal_float_literal :

/0[fh]/

| /[1-9][0-9]*[fh]/

| /[0-9]*\.[0-9]+([eE][+-]?[0-9]+)?[fh]?/

| /[0-9]+\.[0-9]*([eE][+-]?[0-9]+)?[fh]?/

| /[0-9]+[eE][+-]?[0-9]+[fh]?/

EXAMPLE: decimal floating point literals
const a = 0.e+4f;
const b = 01.;
const c = .01;
const d = 12.34;
const f = .0f;
const g = 0h;
const h = 1e-3;
The mathematical value of a decimal floating point literal is computed as follows:

Note: The decimal significand is truncated after 20 decimal digits, preserving approximately log(10)/log(2)×20 ≈ 66.4 significant bits in the fraction.

A hexadecimal floating point literal is:

hex_float_literal :

/0[xX][0-9a-fA-F]*\.[0-9a-fA-F]+([pP][+-]?[0-9]+[fh]?)?/

| /0[xX][0-9a-fA-F]+\.[0-9a-fA-F]*([pP][+-]?[0-9]+[fh]?)?/

| /0[xX][0-9a-fA-F]+[pP][+-]?[0-9]+[fh]?/

EXAMPLE: hexadecimal floating point literals
const a = 0xa.fp+2;
const b = 0x1P+4f;
const c = 0X.3;
const d = 0x3p+2h;
const e = 0X1.fp-4;
const f = 0x3.2p+2h;
The mathematical value of a hexadecimal floating point literal is computed as follows:

Note: The hexadecimal significand is truncated after 16 hexadecimal digits, preserving approximately 4 ×16 = 64 significant bits in the fraction.

When a numeric literal has a suffix, the literal denotes a value in a specific concrete scalar type. Otherwise, the literal denotes a value one of the abstract numeric types defined below. In either case, the value denoted by the literal is its mathematical value after conversion to the target type, following the rules in § 14.6.6 Floating Point Conversion.

Mapping numeric literals to types
Numeric Literal Suffix Type Examples
integer literal i i32 42i
integer literal u u32 42u
integer literal AbstractInt 124
floating point literal f f32 42f 1e5f 1.2f 0x1.0p10f
floating point literal h f16 42h 1e5h 1.2h 0x1.0p10h
floating point literal AbstractFloat 1e5 1.2 0x1.0p10

A shader-creation error results if:

Note: The hexadecimal float value 0x1.00000001p0 requires 33 significand bits to be represented exactly, but f32 only has 23 explicit significand bits.

Note: If you want to use an f suffix to force a hexadecimal float literal to be of type, the literal must also use a binary exponent. For example, write 0x1p0f. In comparison, 0x1f is a hexadecimal integer literal.

3.6. Keywords

A keyword is a token which refers to a predefined language concept. See § 15.1 Keyword Summary for the list of WGSL keywords.

3.7. Identifiers

An identifier is a kind of token used as a name. See § 5 Declaration and Scope.

WGSL uses two grammar nonterminals to separate use cases:

ident :

ident_pattern_token _disambiguate_template

member_ident :

ident_pattern_token

The form of an identifier is based on the Unicode Standard Annex #31 for Unicode Version 14.0.0, with the following elaborations.

Identifiers use the following profile described in terms of UAX31 Grammar:

<Identifier> := <Start> <Continue>* (<Medial> <Continue>+)*

<Start> := XID_Start + U+005F
<Continue> := <Start> + XID_Continue
<Medial> :=

This means identifiers with non-ASCII code points like these are valid: Δέλτα, réflexion, Кызыл, 𐰓𐰏𐰇, 朝焼け, سلام, 검정, שָׁלוֹם, गुलाबी, փիրուզ.

With the following exceptions:

ident_pattern_token :

/([_\p{XID_Start}][\p{XID_Continue}]+)|([\p{XID_Start}])/u

Unicode Character Database for Unicode Version 14.0.0 includes non-normative listing with all valid code points of both XID_Start and XID_Continue.

Note: The return type for some built-in functions are structure types whose name cannot be used WGSL source. Those structure types are described as if they were predeclared with a name starting with two underscores. The result value can be saved into newly declared let or var using type inferencing, or immediately have one of its members immediately extracted by name. See example usages in the description of frexp and modf.

3.7.1. Identifier Comparison

Two WGSL identifiers are the same if and only if they consist of the same sequence of code points.

Note: This specification does not permit Unicode normalization of values for the purposes of comparison. Values that are visually and semantically identical but use different Unicode character sequences will not match. Content authors are advised to use the same encoding sequence consistently or to avoid potentially troublesome characters when choosing values. For more information, see [CHARMOD-NORM].

Note: A user agent should issue developer-visible warnings when the meaning of a WGSL module would change if all instances of an identifier are replaced with one of that identifier’s homographs. (A homoglyph is a sequence of code points that may appear the same to a reader as another sequence of code points. Examples of mappings to detect homoglyphs are the transformations, mappings, and matching algorithms mentioned in the previous paragraph. Two sequences of code points are homographs if the identifier can transform one into the other by repeatedly replacing a subsequence with its homoglyph.)

3.8. Context-Dependent Names

A context-dependent name is a token used to name a concept, but only in specific grammatical contexts. The spelling of the token may be the same as an identifier, but the token does not resolve to a declared object. This section lists the tokens used as context-dependent names. The token must not be a keyword or reserved word.

3.8.1. Attribute Names

See § 11 Attributes.

The attribute names are:

3.8.2. Built-in Value Names

A built-in value name-token is a token used in the name of a built-in value.

See § 12.3.1.1 Built-in Inputs and Outputs.

builtin_value_name :

ident_pattern_token

The built-in value names are:

3.8.3. Diagnostic Rule Names

A diagnostic name-token is a token used in the name of a diagnostic triggering rule.

See § 2.3 Diagnostics.

diagnostic_name_token :

ident_pattern_token

The pre-defined diagnostic rule names are:

3.8.4. Diagnostic Severity Control Names

The valid diagnostic filter severity control names are listed in § 2.3 Diagnostics but have the same form as an identifier:

severity_control_name :

ident_pattern_token

The diagnostic filter severity control names are:

3.8.5. Extension Names

The valid enable-extension names are listed in § 4.1.1 Enable Extensions but in general have the same form as an identifier:

enable_extension_name :

ident_pattern_token

The enable-extension names are:

The valid language extension names are listed in § 4.1.2 Language Extensions but in general have the same form as an identifier:

software_extension_name :

ident_pattern_token

The language extension names are:

3.8.6. Interpolation Type Names

An interpolation type name-token is a token used in the name of an interpolation type for interpolate_type_name.

See § 12.3.1.4 Interpolation.

The interpolation type names are:

3.8.7. Interpolation Sampling Names

An interpolation sampling name-token is a token used in the name of an interpolation sampling.

See § 12.3.1.4 Interpolation.

interpolate_sampling_name :

ident_pattern_token

The interpolation sampling names are:

3.8.8. Swizzle Names

The swizzle names are used in vector access expressions:

swizzle_name :

/[rgba]/

| /[rgba][rgba]/

| /[rgba][rgba][rgba]/

| /[rgba][rgba][rgba][rgba]/

| /[xyzw]/

| /[xyzw][xyzw]/

| /[xyzw][xyzw][xyzw]/

| /[xyzw][xyzw][xyzw][xyzw]/

3.9. Template Lists

Template parameterization is a way to specify parameters that modify a general concept. To write a template parameterization, write the general concept, followed by a template list.

Ignoring comments and blankspace, a template list is:

The form of a template parameter is implicitly defined by the template list discovery algorithm below. Generally, they are names, expressions, or types.

Note: For example, the phrase vec3<f32> is a template parameterization where vec3 is the general concept being modified, and <f32> is a template list containing one parameter, the f32 type. Together, vec3<f32> denotes a specific vector type.

Note: For example, the phrase var<storage,read_write> modifies the general var concept with template parameters storage and read_write.

Note:For example, the phrase array<vec4<f32>> has two template parameterizations:

The '<' (U+003C) and '>' (U+003E) code points that delimit a template list are also used when spelling:

The syntactic ambiguity is resolved in favour of template lists:

The template list discovery algorithm is given below. It uses the following assumptions and properties:

  1. A template parameter is an expression, and therefore does not start with either a '<' (U+003C) or a '=' (U+003D) code point.

  2. An expression does not contain code points ';' (U+003B), '{' (U+007B), or ':' (U+003A).

  3. An expression does not contain an assignment.

  4. The only time a '=' (U+003D) code point appears is as part of a comparison operation, i.e. in one of '<=', '>=', '==', or '!='. Otherwise, a '=' (U+003D) code point appears as part of an assignment.

  5. Template list delimiters respect nested expressions formed by parentheses '(...)', and array indexing '[...]'. The start and end of a template list must appear at the same nesting level.

Algorithm: Template list discovery

Input: The program source text.

Record types:

Let UnclosedCandidate be a record type containing:

Let TemplateList be a record type containing:

Output: DiscoveredTemplateLists, a list of TemplateList records.

Procedure:

Note:The algorithm can be modified to find the source ranges for template parameters, as follows:

Note: The algorithm explicitly skips past literals because some numeric literals end in a letter, for example 1.0f. The terminating f should not be mistaken as the start of an ident_pattern_token.

Note: In the phrase A ( B < C, D > ( E ) ), the segment < C, D > is a template list.

Note: The algorithm respects expression nesting: The start and end of a particular template list cannot appear at different expression nesting levels. For example, in array<i32,select(2,3,a>b)>, the template list has three parameters, where the last one is select(2,3,a>b). The '>' in a>b does not terminate the template list because it is enclosed in a parenthesized part of the expression calling the select function.

Note: Both ends of a template list must appear within the same indexing expression. For example a[b<d]>() does not contain a valid template list.

Note: In the phrase A<B<<C>, the phrase B<<C is parsed as B followed by the left-shift operator '<<' followed by C. The template discovery algorithm starts examining B then '<' (U+003C) but then sees that the next '<' (U+003C) code point cannot start a template argument, and so the '<' immediately after the B is not the start of a template list. The initial '<' and final '>' are the only template list delimiters, and it has template parameter B<<C.

Note: The phrase A<B<=C> is analyzed similarly to the previous note, so the phrase B<=C is parsed as B followed by the less-than-or-equal operator '<=' followed by C. The template discovery algorithm starts examining B then '<' (U+003C) but then sees that the next '=' (U+003D) code point cannot start a template argument, and so the '<' immediately after the B is not the start of a template list. The initial '<' and final '>' are the only template list delimiters, and it has template parameter B<=C.

Note: When examining the phrase A<(B>=C)>, there is one template list, starting at the first '<' (U+003C) code point and ending at the last '>' (U+003E) code point, and having template argument B>=C. After examining the first '>' (U+003C) code point (after B), the '=' (U+003D) code point needs to be recognized specially so it isn’t assumed to be part of an assignment.

Note: When examining the phrase A<(B!=C)>, there is one template list, starting at the first '<' (U+003C) code point and ending at the last '>' (U+003E) code point, and having template argument B!=C. After examining the '!' (U+0021) code point (after 'B'), the '=' (U+003D) code point needs to be recognized specially so it isn’t assumed to be part of an assignment.

Note: When examining the phrase A<(B==C)>, there is one template list, starting at the first '<' (U+003C) code point and ending at the last '>' (U+003E) code point, and having template argument B==C. After examining the first '=' (U+003D) code point (after 'B'), the second '=' (U+003D) code point needs to be recognized specially so neither are assumed to be part of an assignment.

After template list discovery completes, parsing will attempt to match each template list to the template_list grammar rule.

template_list :

_template_args_start template_arg_comma_list _template_args_end

template_arg_comma_list :

template_arg_expression ( ',' template_arg_expression ) * ',' ?

template_arg_expression :

expression

4. Directives

A directive is a token sequence which modifies how a WGSL program is processed by a WebGPU implementation.

Directives are optional. If present, all directives must appear before any declarations or const assertions.

global_directive :

diagnostic_directive

| enable_directive

| requires_directive

4.1. Extensions

WGSL is expected to evolve over time.

An extension is a named grouping of a coherent set of modifications to the WGSL specification, consisting of any combination of:

Hypothetically, extensions could:

There are two kinds of extensions: enable-extensions and language extensions.

4.1.1. Enable Extensions

An enable-extension is an extension whose functionality is available only if:

Enable-extensions are intended to expose hardware functionality that is not universally available.

An enable directive is a directive that turns on support for one or more enable-extensions. A shader-creation error results if the implementation does not support all the listed enable-extensions.

enable_directive :

'enable' enable_extension_list ';'

enable_extension_list :

enable_extension_name ( ',' enable_extension_name ) * ',' ?

Like other directives, if an enable directive is present, it must appear before all declarations and const assertions. Extension names are not identifiers: they do not resolve to declarations.

The valid enable-extensions are listed in the following table.

Enable-extensions
WGSL enable-extension WebGPU GPUFeatureName Description
f16 "shader-f16" The f16 type is valid to use in the WGSL module. Otherwise, using f16 (directly or indirectly) will result in a shader-creation error.
clip_distances "clip-distances" The built-in variable clip_distances is valid to use in the WGSL module. Otherwise, using clip_distances will result in a shader-creation error.
dual_source_blending "dual-source-blending" The attribute blend_src is valid to use in the WGSL module. Otherwise, using blend_src will result in a shader-creation error.
EXAMPLE: Using hypothetical enable-extensions
// Enable a hypothetical extension for arbitrary precision floating point types.
enable arbitrary_precision_float;
enable arbitrary_precision_float; // A redundant enable directive is ok.

// Enable a hypothetical extension to control the rounding mode.
enable rounding_mode;

// Assuming arbitrary_precision_float enables use of:
//    - a type f<E,M>
//    - as a type in function return, formal parameters and let-declarations
//    - as a value constructor from AbstractFloat
//    - operands to division operator: /
// Assuming @rounding_mode attribute is enabled by the rounding_mode enable directive.
@rounding_mode(round_to_even)
fn halve_it(x : f<8, 7>) -> f<8, 7> {
  let two = f<8, 7>(2);
  return x / 2; // uses round to even rounding mode.
}

4.1.2. Language Extensions

A language extension is an extension which is automatically available if the implementation supports it. The program does not have to explicitly request it.

Language extensions embody functionality which could reasonably be supported on any WebGPU implementation. If the feature is not universally available, that it is because some WebGPU implementation has not yet implemented it.

Note: For example, do-while loops could be a language extension.

The wgslLanguageFeatures member of the WebGPU GPU object lists the set of language extensions supported by the implementation.

A requires-directive is a directive that documents the program’s use of one or more language extensions. It does not change the functionality exposed by the implementation. A shader-creation error results if the implementation does not support one of the required extensions.

A WGSL module can use a requires-directive to signal the potential for non-portability, and to signal the intended minimum bar for portability.

Note: Tooling outside of a WebGPU implementation could check whether all the language extensions used by a program are covered by requires-directives in the program.

requires_directive :

'requires' software_extension_list ';'

software_extension_list :

software_extension_name ( ',' software_extension_name ) * ',' ?

Like other directives, if a requires-directive is present, it must appear before all declarations and const assertions. Extension names are not identifiers: they do not resolve to declarations.

Language extensions
WGSL language extension Description
readonly_and_readwrite_storage_textures Allows the use of read and read_write access modes with storage textures. Additionally, adds the textureBarrier built-in function.
packed_4x8_integer_dot_product Supports using 32-bit integer scalars packing 4-component vectors of 8-bit integers as inputs to the dot product instructions with dot4U8Packed and dot4I8Packed built-in functions. Additionally, adds packing and unpacking instructions with packed 4-component vectors of 8-bit integers with pack4xI8, pack4xU8, pack4xI8Clamp, pack4xU8Clamp, unpack4xI8, and unpack4xU8 built-in functions.
unrestricted_pointer_parameters Removes the following restrictions from user-defined functions:

For user-defined functions, a parameter of pointer type must be in one of the following address spaces:

Each argument of pointer type to a user-defined function must have the same memory view as its root identifier.

pointer_composite_access Supports composite-value decomposition expressions where the root expression is a pointer, yielding a reference.

For example, if p is a pointer to a structure with member m, then p.m is a reference to the memory locations for m inside the structure p points to.

Similarly, if pa is a pointer to an array, then pa[i] is a reference to the memory locations for the i’th element of the array pa points to.

Note: The intent is that, over time, WGSL will define language extensions embodying all functionality in language extensions commonly supported at that time. In a requires-directive, these serve as a shorthand for listing all those common features. They represent progressively increasing sets of functionality, and can be thought of as language versions, of a sort.

4.2. Global Diagnostic Filter

A global diagnostic filter is a diagnostic filter whose affected range is the whole WGSL module. It is a directive, thus appearing before any module-scope declarations. It is spelled like the attribute form, but without the leading @ (U+0040) code point, and with a terminating semicolon.

diagnostic_directive :

'diagnostic' diagnostic_control ';'

5. Declaration and Scope

A declaration associates an identifier with one of the following kinds of objects:

In other words, a declaration introduces a name for an object.

A declaration is at module scope if the declaration appears in the program source, but outside the text of any other declaration.

A function declaration appears at module-scope. A function declaration contains declarations for formal parameters, if it has any, and it may contain variable and value declarations inside its body. Those contained declarations are therefore not at module-scope.

Note: The only kind of declaration that contain another declaration is a function declaration.

Certain objects are provided by the WebGPU implementation, and are treated as if they have been declared before the start of the WGSL module source. We say such objects are predeclared. For example, WGSL predeclares:

The scope of a declaration is the set of program source locations where a declared identifier potentially denotes its associated object. We say the identifier is in scope (of the declaration) at those source locations.

Where a declaration appears determines its scope:

Two declarations in the same WGSL source program must not simultaneously:

Note: A predeclared object does not have a declaration in the WGSL source. So a user-specified declaration at module-scope or inside a function can have the same name as a predeclared object.

Identifiers are used as follows, distinguished by grammatical context:

When an ident token appears as a name denoting an object declared elsewhere, it must be in scope for some declaration. The object denoted by the identifier token is determined as follows:

When the above algorithm is used to map an identifier to a declaration, we say the identifier resolves to that declaration. Similarly, we also say the identifier resolves to the declared object.

It is a shader-creation error if any module scope declaration is recursive. That is, no cycles can exist among the declarations:

Consider the directed graph where:

This graph must not have a cycle.

Note: The function body is part of the function declaration, thus functions must not be recursive, either directly or indirectly.

Note: Non-module scope identifier declarations must precede their uses in the text.

EXAMPLE: Valid and invalid declarations
// Valid, user-defined variables can have the same name as a built-in function.
var<private> modf: f32 = 0.0;

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

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

// Valid, my_func_1 is in scope for the entire 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, modf resolves to the module-scope variable.
  let res = modf(foo);

  // Invalid, the scope of foo_2 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, foo_4 is in scope until the end of the compound statement.
    var foo : f32; // foo_4

    // 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
      // 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

  // Valid, later_def, a module scope declaration, is in scope for the entire program.
  var early_use : i32 = later_def;
}

// Invalid, bar_6 has the same 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 for the entire program.
fn my_foo( //my_foo_1
  // Valid, my_foo_2 is in scope until the end of the function.
  my_foo: i32 // my_foo_2
) { }

var<private> later_def : i32 = 1;
EXAMPLE: Shadowing predeclared objects
// This declaration hides the predeclared 'min' built-in function.
// Since this declaration is at module-scope, it is in scope over the entire
// source.  The built-in function is no longer accessible.
fn min() -> u32 { return 0; }

const rgba8unorm = 12; // This shadows the predeclared 'rgba8unorm' enumerant.

6. Types

Programs calculate values.

In WGSL, a type is a set of values, and each value belongs to exactly one type. A value’s type determines the syntax and semantics of operations that can be performed on that value.

For example, the mathematical number 1 corresponds to these distinct values in WGSL:

WGSL treats these as different because their machine representation and operations differ.

A type is either predeclared, or created in WGSL source via a declaration.

Some types are expressed as template parameterizations. A type-generator is a predeclared object which, when parameterized with a template list, denotes a type. For example, the type atomic<u32> combines the type-generator atomic with template list <u32>.

We distinguish between the concept of a type and the syntax in WGSL to denote that type. In many cases the spelling of a type in this specification is the same as its WGSL syntax. For example:

Some WGSL types are only used for analyzing a source program and for determining the program’s runtime behavior. This specification will describe such types, but they do not appear in WGSL source text.

Note: Reference types are not written in WGSL modules. See § 6.4.3 Reference and Pointer Types.

6.1. Type Checking

A WGSL value is computed by evaluating an expression. An expression is a segment of source text parsed as one of the WGSL grammar rules whose name ends with "expression". An expression E can contain subexpressions which are expressions properly contained in the outer expression E. A top-level expression is an expression that is not itself a subexpression. See § 8.18 Expression Grammar Summary.

The particular value produced by an expression evaluation depends on:

The values that may result from evaluating a particular expression will always belong to a specific WGSL type, known as the static type of the expression. The rules of WGSL are designed so that the static type of an expression depends only on the expression’s static context.

A type assertion is a mapping from some WGSL source expression to a WGSL type. The notation

e : T

is a type assertion meaning T is the static type of WGSL expression e.

Note: A type assertion is a statement of fact about the text of a program. It is not a runtime check.

Statements often use expressions, and may place requirements on the static types of those expressions. For example:

Type checking a successfully parsed WGSL module is the process of mapping each expression to its static type, and verifying that type requirements of each statement are satisfied. If type checking fails, a special case of a shader-creation error, called a type error, results.

Type checking can be performed by recursively applying type rules to syntactic phrases, where a syntactic phrase is either an expression or a statement. A type rule describes how the static context for a syntactic phrase determines the static type for expressions contained within that phrase. A type rule has two parts:

Type rules may have type parameters in their preconditions and conclusions. When a type rule’s conclusion or preconditions contain type parameters, we say it is parameterized. When they do not, we say the rule is fully elaborated. We can make a fully elaborated type rule from a parameterized one by substituting a type for each of its type parameters, using the same type for all occurrences of a given parameter in the rule. An assignment of types to a rule’s type parameters is called a substitution.

For example, here is the type rule for logical negation (an expression of the form !e):

Precondition Conclusion
e: T
T is bool or vecN<bool>
!e: T

This is a parameterized rule, because it contains the type parameter T, which can represent any one of four types bool, vec2<bool>, vec3<bool>, or vec4<bool>. Applying the substitution that maps T to vec3<bool> produces the fully elaborated type rule:

Precondition Conclusion
e: vec3<bool>
!e: vec3<bool>

Each fully elaborated rule we can produce from a parameterized rule by applying some substitution that meets the rule’s other conditions is called an overload of the parameterized rule. For example, the boolean negation rule has four overloads, because there are four possible ways to assign a type to its type parameter T.

Note: In other words, a parameterized type rule provides the pattern for a collection of fully elaborated type rules, each one produced by applying a different substitution to the parameterized rule.

A type rule applies to a syntactic phrase when:

A parameterized type rule applies to an expression if there exists a substitution producing a fully elaborated type rule that applies to the expression.

Consider the expression, 1u+2u. It has two literal subexpressions: 1u and 2u, both of type u32. The top-level expression is an addition. Referring to the rules in § 8.7 Arithmetic Expressions, the type rule for addition applies to the expression, because:

When analyzing a syntactic phrase, three cases may occur:

Continuing the example above, only one type rule applies to the expression 1u+2u, and so type checking accepts the conclusion of that type rule, which is that 1u+2u is of type u32.

A WGSL source program is well-typed when:

Otherwise there is a type error and the source program is not a valid WGSL module.

WGSL is a statically typed language because type checking a WGSL module will either succeed or discover a type error, while only having to inspect the program source text.

6.1.1. Type Rule Tables

The WGSL type rules for expressions are organized into type rule tables, with one row per type rule.

The semantics of an expression is the effect of evaluating that expression, and is primarily the production of a result value. The Description column of the type rule that applies to an expression will specify the expression’s semantics. The semantics usually depends on the values of the type rule parameters, including the assumed values of any subexpressions. Sometimes the semantics of an expression includes effects other than producing a result value, such as the non-result-value effects of its subexpressions.

EXAMPLE: Side-effect of an expression
fn foo(p : ptr<function, i32>) -> i32 {
  let x = *p;
  *p += 1;
  return x;
}

fn bar() {
  var a: i32;
  let x = foo(&a); // the call to foo returns a value
                   // and updates the value of a
}

6.1.2. Conversion Rank

When a type assertion e:T is used as a type rule precondition, it is satisfied when:

The rule is codified by the ConversionRank function over pairs of types, defined in the table below. The ConversionRank function expresses the preference and feasibility of automatically converting a value of one type (Src) to another type (Dest). Lower ranks are more desirable.

A feasible automatic conversion converts a value from type Src to type Dest, and is allowed when ConversionRank(Src,Dest) is finite. Such conversions are value-preserving, subject to limitations described in § 14.6 Floating Point Evaluation.

Note: Automatic conversions only occur in two kinds of situations. First, when converting a const-expression to its corresponding typed numeric value that can be used on the GPU. Second, when a load from a reference-to-memory occurs, yielding the value stored in that memory.

Note: A conversion of infinite rank is infeasible, i.e. not allowed.

Note: When no conversion is performed, the conversion rank is zero.

ConversionRank from one type to another
Src Dest ConversionRank(Src,Dest) Description
T T 0 Identity. No conversion performed.
ref<AS,T,AM>
for address space AS, and where access mode AM is read or read_write.
T 0 Apply the Load Rule to load a value from a memory reference.
AbstractFloat f32 1 See § 14.6.6 Floating Point Conversion
AbstractFloat f16 2 See § 14.6.6 Floating Point Conversion
AbstractInt i32 3 Identity if the value is in i32. Produces a shader-creation error otherwise.
AbstractInt u32 4 Identity if the value is in u32. Produces a shader-creation error otherwise.
AbstractInt AbstractFloat 5 See § 14.6.6 Floating Point Conversion
AbstractInt f32 6 Behaves as AbstractInt to AbstractFloat, and then AbstractFloat to f32
AbstractInt f16 7 Behaves as AbstractInt to AbstractFloat, and then AbstractFloat to f16
vecN<S> vecN<T> ConversionRank(S,T) Inherit conversion rank from component type.
matCxR<S> matCxR<T> ConversionRank(S,T) Inherit conversion rank from component type.
array<S,N> array<T,N> ConversionRank(S,T) Inherit conversion rank from component type. Note: Only fixed-size arrays may have an abstract component type.
__frexp_result_abstract __frexp_result_f32 1
__frexp_result_abstract __frexp_result_f16 2
__frexp_result_vecN_abstract __frexp_result_vecN_f32 1
__frexp_result_vecN_abstract __frexp_result_vecN_f16 2
__modf_result_abstract __modf_result_f32 1
__modf_result_abstract __modf_result_f16 2
__modf_result_vecN_abstract __modf_result_vecN_f32 1
__modf_result_vecN_abstract __modf_result_vecN_f16 2
S T
where above cases don’t apply
infinity There are no automatic conversions between other types.

The type T is the concretization of type S if:

The concretization of a value e of type T is the value resulting from applying, to e, the feasible conversion that maps T to the concretization of T.

Note: Conversion to f32 is always preferred over f16, therefore automatic conversion will only ever produce an f16 if extension is enabled in the module.

6.1.3. Overload Resolution

When more than one type rule applies to a syntactic phrase, a tie-breaking procedure is used to determine which one should take effect. This procedure is called overload resolution, and assumes type checking has already succeeded in finding static types for subexpressions.

Consider a syntactic phrase P, and all type rules that apply to P. The overload resolution algorithm calls these type rules overload candidates. For each candidate:

Overload resolution for P proceeds as follows, with the goal of finding a single most preferable overload candidate:

  1. For each candidate C, enumerate conversion ranks for subexpressions in the syntactic phrase. The candidate’s preconditions have been met, and so for the i’th subexpression in the P:

    • Its static type has been computed.

    • There is a feasible automatic conversion from the expression’s static type to the type required by the corresponding type assertion in the preconditions. Let C.R(i) be the ConversionRank of that conversion.

  2. Eliminate any candidate where one of its subexpressions resolves to an abstract type after feasible automatic conversions, but another of the candidate’s subexpressions is not a const-expression.

    Note: As a consequence, if any subexpression in the phrase is not a const-expression, then all subexpressions in the phrase must have a concrete type.

  3. Rank candidates: Given two overload candidates C1 and C2, C1 is preferred over C2 if:

    • For each expression position i in P, C1.R(i) ≤ C2.R(i).

      • That is, each expression conversion required to apply C1 to P is at least as preferable as the corresponding expression conversion required to apply C2 to P.

    • There is at least one expression position i where C1.R(i) < C2.R(i).

      • That is, there is at least one expression conversion required to apply C1 that is strictly more preferable than the corresponding conversion required to apply C2.

  4. If there is a single candidate C which is preferred over all the others, then overload resolution succeeds, yielding the candidate type rule C. Otherwise, overload resolution fails.

6.2. Plain Types

Plain types are types for the machine representation of boolean values, numbers, vectors, matrices, or aggregations of such values.

A plain type is either a scalar type, an atomic type, or a composite type.

Note: Plain types in WGSL are similar to Plain-Old-Data types in C++, but also include atomic types and abstract numeric types.

6.2.1. Abstract Numeric Types

These types cannot be spelled in WGSL source. They are only used by type checking.

Certain expressions are evaluated at shader-creation time, and with a numeric range and precision that may be larger than directly implemented by the GPU.

WGSL defines two abstract numeric types for these evaluations:

An evaluation of an expression in one of these types must not overflow or produce an infinite or NaN value.

A type is abstract if it is an abstract numeric type or contains an abstract numeric type. A type is concrete if it is not abstract.

A numeric literal without a suffix denotes a value in an abstract numeric type:

Example: The expression log2(32) is analyzed as follows:

Example: The expression 1 + 2.5 is analyzed as follows:

Example: let x = 1 + 2.5;

Example: 1u + 2.5 results in a shader-creation error:

Example: -1 * i32(-2147483648) does not result in a shader-creation error:

EXAMPLE: Type inference for literals
// Explicitly-typed unsigned integer literal.
var u32_1 = 1u; // variable holds a u32

// Explicitly-typed signed integer literal.
var i32_1 = 1i; // variable holds a i32

// Explicitly-typed floating point literal.
var f32_1 = 1f; // variable holds a f32

// Explicitly-typed unsigned integer literal cannot be negated.
var u32_neg = -1u; // invalid: unary minus does not support u32

// When a concrete type is required, but no part of the statement or
// expression forces a particular concrete type, an integer literal is
// interpreted as an i32 value:
//   Initializer for a let-declaration must be constructible (or pointer).
//   The most preferred automatic conversion from AbstractInt to a constructible type
//   is AbstractInt to i32, with conversion rank 2.  So '1' is inferred as i32.
let some_i32 = 1; // like let some_i32: i32 = 1i;

// Inferred from declaration type.
var i32_from_type : i32 = 1; // variable holds i32.  AbstractInt to i32, conversion rank 2
var u32_from_type : u32 = 1; // variable holds u32.  AbstractInt to u32, conversion rank 3

// Unsuffixed integer literal can convert to floating point when needed:
//   Automatically convert AbstractInt to f32, with conversion rank 5.
var f32_promotion : f32 = 1; // variable holds f32

// Invalid: no feasible conversion from floating point to integer
var i32_demotion : i32 = 1.0; // Invalid

// Inferred from expression.
var u32_from_expr = 1 + u32_1; // variable holds u32
var i32_from_expr = 1 + i32_1; // variable holds i32

// Values must be representable.
let u32_too_large   : u32 = 1234567890123456890; // invalid, overflow
let i32_too_large   : i32 = 1234567890123456890; // invalid, overflow
let u32_large : u32 = 2147483649; // valid
let i32_large : i32 = 2147483649; // invalid, overflow
let f32_out_of_range1 = 0x1p500; // invalid, out of range
let f32_hex_lost_bits = 0x1.0000000001p0; // invalid, not exactly representable in f32

// Minimum integer: unary negation over AbstractInt, then infer i32.
// Most preferred conversion from AbstractInt to a constructible type (with lowest
// conversion rank) is AbstractInt to i32.
let i32_min = -2147483648;  // has type i32

// Invalid.  Select AbstractInt to i32 as above, but the value is out of
// range, producing shader-creation error.
let i32_too_large_2 = 2147483648; // Invalid.

// Subexpressions can resolve to AbstractInt and AbstractFloat.
// The following examples are all valid and the value of the variable is 6u.
var u32_expr1 = (1 + (1 + (1 + (1 + 1)))) + 1u;
var u32_expr2 = 1u + (1 + (1 + (1 + (1 + 1))));
var u32_expr3 = (1 + (1 + (1 + (1u + 1)))) + 1;
var u32_expr4 = 1 + (1 + (1 + (1 + (1u + 1))));

// Inference based on built-in function parameters.

// Most-preferred candidate is clamp(i32,i32,i32)->i32
let i32_clamp = clamp(1, -5, 5);
// Most preferred candidate is clamp(u32,u32,u32).
// Literals use automatic conversion AbstractInt to u32.
let u32_clamp = clamp(5, 0, u32_from_expr);
// Most preferred candidate is clamp(f32,f32,f32)->f32
// literals use automatic conversion AbstractInt to f32.
let f32_clamp = clamp(0, f32_1, 1);

// The following examples all promote to f32 with an initial value of 10f.
let f32_promotion1 = 1.0 + 2 + 3 + 4;
let f32_promotion2 = 2 + 1.0 + 3 + 4;
let f32_promotion3 = 1f + ((2 + 3) + 4);
let f32_promotion4 = ((2 + (3 + 1f)) + 4);

// Type rule violations.

// Invalid, the initializer can only resolve to f32:
// No feasible automatic conversion from AbstractFloat to u32.
let mismatch : u32 = 1.0;

// Invalid. There is no overload of clamp that allows mixed sign parameters.
let ambiguous_clamp = clamp(1u, 0, 1i);

// Inference completes at the statement level.

// Initializer for a let-declaration must be constructible (or pointer).
// The most preferred automatic conversion from AbstractInt to a constructible type
// is AbstractInt to i32, with conversion rank 2.  So '1' is inferred as i32.
let some_i32 = 1; // like let some_i32: i32 = 1i;

let some_f32 : f32 = some_i32; // Type error: i32 cannot be assigned to f32

// Another overflow case
let overflow_u32 = (1 -2) + 1u; // invalid, -1 is out of range of u32

// Ideal value out of range of 32-bits, but brought back into range
let out_and_in_again = (0x1ffffffff / 8);

// Similar, but invalid
let out_of_range = (0x1ffffffff / 8u); // requires computation is done in 32-bits,
                                       // making 0x1ffffffff out of range.

6.2.2. Boolean Type

The bool type contains the values true and false.

Boolean literal type rules
Precondition Conclusion Description
true: bool The true value.
false: bool The false value.

6.2.3. Integer Types

The u32 type is the set of 32-bit unsigned integers.

The i32 type is the set of 32-bit signed integers. It uses the two’s complement representation, with the sign bit in the most significant bit position.

Expressions on concrete integer types that overflow produce a result that is modulo 2bitwidth

Extreme values for integer types
Type Lowest value Highest value
i32 i32(-2147483648) 2147483647i
i32(-0x80000000) 0x7fffffffi
u32 0u 4294967295u
0x0u 0xffffffffu

Note: AbstractInt is also an integer type.

6.2.4. Floating Point Types

The f32 type is the set of 32-bit floating point values of the IEEE-754 binary32 (single precision) format. See § 14.6 Floating Point Evaluation for details.

The f16 type is the set of 16-bit floating point values of the IEEE-754 binary16 (half precision) format. It is a shader-creation error if the f16 type is used unless the program contains the enable f16; directive to enable the f16 extension. See § 14.6 Floating Point Evaluation for details.

The following table lists certain extreme values for floating point types. Each has a corresponding negative value.

Extreme values for floating point types
Type Smallest positive subnormal Smallest positive normal Largest positive finite Largest finite power of 2
f32 1.40129846432481707092e-45f 1.17549435082228750797e-38f 3.40282346638528859812e+38f 0x1p+127f
0x1p-149f 0x1p-126f 0x1.fffffep+127f
f16 5.9604644775390625e-8h 0.00006103515625h 65504.0h 0x1p+15h
0x1p-24h 0x1p-14h 0x1.ffcp+15h

Note: AbstractFloat is also a floating point type.

6.2.5. Scalar Types

The scalar types are bool, AbstractInt, AbstractFloat, i32, u32, f32, and f16.

The numeric scalar types are AbstractInt, AbstractFloat, i32, u32, f32, and f16.

The integer scalar types are AbstractInt, i32, and u32.

A scalar conversion maps a value in one scalar type to a value in a different scalar type. Generally the result value is close to the original value, within the limitations of the destination type. Scalar conversions occur either:

6.2.6. Vector Types

A vector is a grouped sequence of 2, 3, or 4 scalar components.

Type Description
vecN<T> Vector of N components of type T. N must be in {2, 3, 4} and T must be one of the scalar types. We say T is the component type of the vector.

A vector is a numeric vector if its component type is a numeric scalar.

Key use cases of a vector include:

Many operations on vectors (and matrices) act component-wise, i.e. the result is formed by operating on each scalar component independently.

EXAMPLE: Vector
vec2<f32>  // is a vector of two f32s.
EXAMPLE: Component-wise addition
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]

WGSL also predeclares the following type aliases:

Predeclared alias Original type Restrictions
vec2i vec2<i32>
vec3i vec3<i32>
vec4i vec4<i32>
vec2u vec2<u32>
vec3u vec3<u32>
vec4u vec4<u32>
vec2f vec2<f32>
vec3f vec3<f32>
vec4f vec4<f32>
vec2h vec2<f16> Requires the f16 extension.
vec3h vec3<f16>
vec4h vec4<f16>

6.2.7. Matrix Types

A matrix is a grouped sequence of 2, 3, or 4 floating point vectors.

Type Description
matCxR<T> Matrix of C columns and R rows of type T, where C and R are both in {2, 3, 4}, and T must be f32, f16, or AbstractFloat. Equivalently, it can be viewed as C column vectors of type vecR<T>.

The key use case for a matrix is to embody a linear transformation. In this interpretation, the vectors of a matrix are treated as column vectors.

The product operator (*) is used to either:

See § 8.7 Arithmetic Expressions.

EXAMPLE: Matrix
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 also predeclares the following type aliases:

Predeclared alias Original type Restrictions
mat2x2f mat2x2<f32>
mat2x3f mat2x3<f32>
mat2x4f mat2x4<f32>
mat3x2f mat3x2<f32>
mat3x3f mat3x3<f32>
mat3x4f mat3x4<f32>
mat4x2f mat4x2<f32>
mat4x3f mat4x3<f32>
mat4x4f mat4x4<f32>
mat2x2h mat2x2<f16> Requires the f16 extension.
mat2x3h mat2x3<f16>
mat2x4h mat2x4<f16>
mat3x2h mat3x2<f16>
mat3x3h mat3x3<f16>
mat3x4h mat3x4<f16>
mat4x2h mat4x2<f16>
mat4x3h mat4x3<f16>
mat4x4h mat4x4<f16>

6.2.8. Atomic Types

An atomic type encapsulates a concrete integer scalar type such that:

Type Description
atomic<T> Atomic of type T. T must be either u32 or i32.

An expression must not evaluate to an atomic type.

Atomic types may only be instantiated by variables in the workgroup address space or by storage buffer variables with a read_write access mode. The memory scope of operations on the type is determined by the address space it is instantiated in. Atomic types in the workgroup address space have a memory scope of Workgroup, while those in the storage address space have a memory scope of QueueFamily.

An atomic modification is any operation on an atomic object which sets the content of the object. The operation counts as a modification even if the new value is the same as the object’s existing value.

In WGSL, atomic modifications are mutually ordered, for each object. That is, during execution of a shader stage, for each atomic object A, all agents observe the same order of modification operations applied to A. The ordering for distinct atomic objects may not be related in any way; no causality is implied. Note that variables in workgroup space are shared within a workgroup, but are not shared between different workgroups.

6.2.9. Array Types

An array is an indexable sequence of element values.

Type Description
array<E,N> A fixed-size array with N elements of type E.
N is called the element count of the array.
array<E> A runtime-sized array of elements of type E. These may only appear in specific contexts.

The first element in an array is at index 0, and each successive element is at the next integer index. See § 8.5.3 Array Access Expression.

An expression must not evaluate to a runtime-sized array type.

The element count expression N of a fixed-size array is subject to the following constraints:

Note: The element count value is fully determined at pipeline creation time if N depends on any override-declarations, and shader module creation otherwise.

Note: To qualify for type-equivalency, any override expression that is not a const expression must be an identifier. See Workgroup variables sized by overridable constants

The number of elements in a runtime-sized array is determined by the size of buffer binding associated with the corresponding storage buffer variable. See § 12.3.4 Buffer Binding Determines Runtime-Sized Array Element Count.

An array element type must be one of:

Note: The element type must be a plain type.

Two array types are the same if and only if all of the following are true:

EXAMPLE: Example fixed-size array types, non-overridable element count
// array<f32,8> and array<i32,8> are different types:
// different element types
var<private> a: array<f32,8>;
var<private> b: array<i32,8>;
var<private> c: array<i32,8u>;  // array<i32,8> and array<i32,8u> are the same type

const width = 8;
const height = 8;

// array<i32,8>, array<i32,8u>, and array<i32,width> are the same type.
// Their element counts evaluate to 8.
var<private> d: array<i32,width>;

// array<i32,height> and array<i32,width> are the same type.
var<private> e: array<i32,width>;
var<private> f: array<i32,height>;

Note: The only valid use of an array type sized by an overridable constant is as a memory view in the workgroup address space. This includes the store type of a workgroup variable. See § 7 Variable and Value Declarations.

EXAMPLE: Workgroup variables sized by overridable constants
override blockSize = 16;

var<workgroup> odds: array<i32,blockSize>;
var<workgroup> evens: array<i32,blockSize>; // Same type

// None of the following have the same type as 'odds' and 'evens'.

// Different type: Not the identifier 'blockSize'
var<workgroup> evens_0: array<i32,16>;
// Different type: Uses arithmetic to express the element count.
var<workgroup> evens_1: array<i32,(blockSize * 2 / 2)>;
// Different type: Uses parentheses, not just an identifier.
var<workgroup> evens_2: array<i32,(blockSize)>;

// An invalid example, because the overridable element count may only occur
// at the outer level.
// var<workgroup> both: array<array<i32,blockSize>,2>;

// An invalid example, because the overridable element count is only
// valid for workgroup variables.
// var<private> bad_address_space: array<i32,blockSize>;

6.2.10. Structure Types

A structure is a named grouping of named member values.

Type Description
struct AStructName {
  M1 : T1,
  ...
  MN : TN,
}
A declaration of a structure type named by the identifier AStructName and having N members, where member i is named by the identifier Mi and is of the type Ti.

N must be at least 1.

Two members of the same structure type must not have the same name.

Structure types are declared at module scope. Elsewhere in the program source, a structure type is denoted by its identifier name. See § 5 Declaration and Scope.

Two structure types are the same if and only if they have the same name.

A structure member type must be one of:

Note: All user-declared structure types are concrete.

Note: Each member type must be a plain type.

Some consequences of the restrictions structure member and array element types are:

EXAMPLE: Structure
// A structure with three members.
struct Data {
  a: i32,
  b: vec2<f32>,
  c: array<i32,10>, // last comma is optional
}

// Declare a variable storing a value of type Data.
var<private> some_data: Data;
struct_decl :

'struct' ident struct_body_decl

struct_body_decl :

'{' struct_member ( ',' struct_member ) * ',' ? '}'

struct_member :

attribute * member_ident ':' type_specifier

The following attributes can be applied to structure members:

Attributes builtin, location, blend_src, interpolate, and invariant are IO attributes. An IO attribute on a member of a structure S has effect only when S is used as the type of a formal parameter or return type of an entry point. See § 12.3.1 Inter-stage Input and Output Interface.

Attributes align and size are layout attributes, and may be required if the structure type is used to define a uniform buffer or a storage buffer. See § 13.4 Memory Layout.

EXAMPLE: Structure declaration
struct my_struct {
  a: f32,
  b: vec4<f32>
}
EXAMPLE: Structure used to declare a buffer
// Runtime Array
alias RTArr = array<vec4<f32>>;
struct S {
  a: f32,
  b: f32,
  data: RTArr
}
@group(0) @binding(0) var<storage> buffer: S;

6.2.11. Composite Types

A type is composite if it has internal structure expressed as a composition of other types. The internal parts do not overlap, and are called components. A composite value may be decomposed into its components. See § 8.5 Composite Value Decomposition Expressions.

The composite types are:

For a composite type T, the nesting depth of T, written NestDepth(T) is:

6.2.12. Constructible Types

Many kinds of values can be created, loaded, stored, passed into functions, and returned from functions. We call these constructible.

A type is constructible if it is one of:

Note: All constructible types have a creation-fixed footprint.

Note: Atomic types and runtime-sized array types are not constructible. Composite types containing atomics and runtime-sized arrays are not constructible.

6.2.13. Fixed-Footprint Types

The memory footprint of a variable is the number of memory locations used to store the contents of the variable. The memory footprint of a variable depends on its store type and becomes finalized at some point in the shader lifecycle. Most variables are sized very early, at shader creation time. Some variables may be sized later, at pipeline creation time, and others as late as the start of shader execution.

A type has a creation-fixed footprint if its concretization has a size that is fully determined at shader creation time.

A type has a fixed footprint if its size is fully determined at pipeline creation time.

Note: All concrete creation-fixed footprint and fixed footprint types are storable.

Note: Pipeline creation depends on shader creation, so a type with creation-fixed footprint also has fixed footprint.

The types with creation-fixed footprint are:

Note: A constructible type has a creation-fixed footprint.

The plain types with fixed footprint are any of:

Note: The only valid use of a fixed-size array with an element count that is an override-expression that is not a const-expression is as a memory view in the workgroup address space. This includes the store type of a workgroup variable.

Note: A fixed-footprint type may contain an atomic type, either directly or indirectly, while a constructible type cannot.

Note: Fixed-footprint types exclude runtime-sized arrays, and any structure that contains a runtime-sized array.

6.3. Enumeration Types

An enumeration type is a limited set of named values. An enumeration is used to distinguish among the set of possibilities for a specific concept, such as the set of valid texel formats.

An enumerant is one of the named values in an enumeration. Each enumerant is distinct from all other enumerants, and distinct from all other kinds of values.

There is no mechanism for declaring new enumerants or new enumeration types in WGSL source.

Note: Enumerants are used as template parameters.

Note: There is no way to copy or to create an alternative name for an enumerant:

6.3.1. Predeclared enumerants

The following table lists the enumeration types in WGSL, and their predeclared enumerants. The enumeration types exist, but cannot be spelled in WGSL source.

Predeclared enumerants
Enumeration
(Cannot be spelled in WGSL)
Predeclared enumerant
access mode read
write
read_write
address space

Note: The handle address space is never written in a WGSL source.

function
private
workgroup
uniform
storage
texel format rgba8unorm
rgba8snorm
rgba8uint
rgba8sint
rgba16uint
rgba16sint
rgba16float
r32uint
r32sint
r32float
rg32uint
rg32sint
rg32float
rgba32uint
rgba32sint
rgba32float
bgra8unorm

6.4. Memory Views

In addition to calculating with plain values, a WGSL program will also often read values from memory or write values to memory, via memory access operations. Each memory access is performed via a memory view.

A memory view comprises:

The access mode of a memory view must be supported by the address space. See § 7 Variable and Value Declarations.

6.4.1. Storable Types

The value contained in a variable must be of a storable type. A storable type may have an explicit representation defined by WGSL, as described in § 13.4.4 Internal Layout of Values, or it may be opaque, such as for textures and samplers.

A type is storable if it is both concrete and one of:

Note: That is, the storable types are the concrete plain types, texture types, and sampler types.

6.4.2. Host-shareable Types

Host-shareable types are used to describe the contents of buffers which are shared between the host and the GPU, or copied between host and GPU without format translation. When used for this purpose, the type may additionally have layout attributes applied as described in § 13.4 Memory Layout. As described in § 7.3 var Declarations, the store type of uniform buffer and storage buffer variables must be host-shareable.

A type is host-shareable if it is both concrete and one of:

Note: Restrictions on the types of inter-stage inputs and outputs are described in § 12.3.1 Inter-stage Input and Output Interface and subsequent sections. Those types are also sized, but the counting differs.

Note: Textures and samplers can also be shared between the host and the GPU, but their contents are opaque. The host-shareable types in this section are specifically for use in storage and uniform buffers.

6.4.3. Reference and Pointer Types

WGSL has two kinds of types for representing memory views: reference types and pointer types.

Constraint Type Description
AS is an address space,
T is a storable type,
AM is an access mode
ref<AS,T,AM> The reference type identified with the set of memory views for memory locations in AS holding values of type T, supporting memory accesses described by mode AM.

Here, T is the store type.

Reference types are not written in WGSL source; instead they are used to analyze a WGSL module.

AS is an address space,
T is a storable type,
AM is an access mode
ptr<AS,T,AM> The pointer type identified with the set of memory views for memory locations in AS holding values of type T, supporting memory accesses described by mode AM.

Here, T is the store type.

Pointer types may appear in WGSL source.

Two pointer types are the same if and only if they have the same address space, store type, and access mode.

When analyzing a WGSL module, reference and pointer types are fully parameterized by an address space, a storable type, and an access mode. In code examples in this specification, the comments show this fully parameterized form.

However, in WGSL source text:

EXAMPLE: Pointer type
fn my_function(
  /* 'ptr<function,i32,read_write>' is the type of a pointer value that references
     memory for keeping an 'i32' value, using memory locations in the 'function'
     address space.  Here 'i32' is the store type.
     The implied access mode is 'read_write'.
     See "Address Space" section for defaults. */
  ptr_int: ptr<function,i32>,

  // 'ptr<private,array<f32,50>,read_write>' is the type of a pointer value that
  // refers to memory for keeping an array of 50 elements of type 'f32', using
  // memory locations in the 'private' address space.
  // Here the store type is 'array<f32,50>'.
  // The implied access mode is 'read_write'.
  // See the "Address space section for defaults.
  ptr_array: ptr<private, array<f32, 50>>
) { }

Reference types and pointer types are both sets of memory views: a particular memory view is associated with a unique reference value and also a unique pointer value:

Each pointer value p of type ptr<AS,T,AM> corresponds to a unique reference value r of type ref<AS,T,AM>, and vice versa, where p and r describe the same memory view.

6.4.4. Valid and Invalid Memory References

A reference value is either valid or invalid.

References are formed as described in detail in § 6.4.8 Forming Reference and Pointer Values. Generally, a valid reference is formed by:

Generally, an invalid memory reference is formed by:

A valid pointer is a pointer that corresponds to a valid reference. An invalid pointer is a pointer that corresponds to an invalid memory reference.

6.4.5. Originating Variable

The originating variable for a reference value R is defined as follows:

The originating variable of a pointer value is defined as the originating variable of the corresponding reference value.

Note: The originating variable is a dynamic concept. The originating variable for a formal parameter of a function depends on the call sites for the function. Different call sites may supply pointers into different originating variables.

A valid reference always corresponds to a non-empty memory view for some or all of the memory locations for some variable.

Note: A reference can correspond to memory locations inside a variable, and still be invalid. This can occur when an index is too large for the type being indexed, but the referenced locations would be inside a subsequent sibling data member.

In the following example, the reference the_particle.position[i] is valid if and only if i is 0 or 1. When i is 2, the reference will be an invalid memory reference, but would otherwise correspond the memory locations for the_particle.color_index.

EXAMPLE: Invalid memory reference still inside a variable
struct Particle {
   position: vec2f,
   velocity: vec2f,
   color_index: i32,
}

@group(0) @binding(0)
var<storage,read_write> the_particle: Particle;

fn particle_velocity_component(p: Particle, i: i32) -> f32 {
  return the_particle.velocity[i]; // A valid reference when i is 0 or 1.
}

6.4.6. Out-of-Bounds Access

An operation that accesses an invalid memory reference is an out-of-bounds access.

An out-of-bounds access is a program defect, because if it were performed as written, it would typically:

For this reason, an implementation will not perform the access as written. Executing an out-of-bounds access generates a dynamic error.

Note: An example of interpreting the store type incorrectly occurs in the example from the previous section. When i is 2, the expression the_particle.velocity[i] has type ref<storage,f32,read_write>, meaning it is a memory view with f32 as its store type. However, the memory locations are allocated to for the color_index member, so the stored value is actually of type i32.

Note:An out-of-bounds access causes a dynamic error, which allows for many possible outcomes.

Those outcomes include, but are not limited to, the following:

Trap

The shader invocation immediately terminates, and shader stage outputs are set to zero values.

Invalid Load

Loads from an invalid reference may return one of:

Invalid Store

Stores to an invalid reference may do one of:

A data race may occur if an invalid load or store is redirected to access different locations inside a variable in a shared address space. For example, the accesses of several concurrently executing invocations may be redirected to the first element in an array. If at least one access is a write, and they are not otherwise synchronized, then the result is a data race, and hence a dynamic error.

An out-of-bounds access invalidates the assumptions of uniformity analysis. For example, if an invocation terminates early due to an out-of-bounds access, then it can no longer particpate in collective operations. In particular, a call to workgroupBarrier may hang the shader, and derivatives may yield invalid results.

6.4.7. Use Cases for References and Pointers

References and pointers are distinguished by how they are used:

Defining references in this way enables simple idiomatic use of variables:

EXAMPLE: Reference types enable simple use of variables
@compute @workgroup_size(1)
fn main() {
  // 'i' has reference type ref<function,i32,read_write>
  // The memory locations for 'i' store the i32 value 0.
  var i: i32 = 0;

  // 'i + 1' can only match a type rule where the 'i' subexpression is of type i32.
  // So the expression 'i + 1' has type i32, and at evaluation, the 'i' subexpression
  // evaluates to the i32 value stored in the memory locations for 'i' at the time
  // of evaluation.
  let one: i32 = i + 1;

  // Update the value in the locations referenced by 'i' so they hold the value 2.
  i = one + 1;

  // Update the value in the locations referenced by 'i' so they hold the value 5.
  // The evaluation of the right-hand-side occurs before the assignment takes effect.
  i = i + 3;
}
EXAMPLE: Returning a reference returns the value loaded via the reference
var<private> age: i32;
fn get_age() -> i32 {
  // The type of the expression in the return statement must be 'i32' since it
  // must match the declared return type of the function.
  // The 'age' expression is of type ref<private,i32,read_write>.
  // Apply the Load Rule, since the store type of the reference matches the
  // required type of the expression, and no other type rule applies.
  // The evaluation of 'age' in this context is the i32 value loaded from the
  // memory locations referenced by 'age' at the time the return statement is
  // executed.
  return age;
}

fn caller() {
  age = 21;
  // The copy_age constant will get the i32 value 21.
  let copy_age: i32 = get_age();
}

Defining pointers in this way enables two key use cases:

EXAMPLE: Using a pointer as a short name for part of a variable
struct Particle {
  position: vec3<f32>,
  velocity: vec3<f32>
}
struct System {
  active_index: i32,
  timestep: f32,
  particles: array<Particle,100>
}
@group(0) @binding(0) var<storage,read_write> system: System;

@compute @workgroup_size(1)
fn main() {
  // Form a pointer to a specific Particle in storage memory.
  let active_particle: ptr<storage,Particle> =
      &system.particles[system.active_index];

  let delta_position: vec3<f32> = (*active_particle).velocity * system.timestep;
  let current_position: vec3<f32>  = (*active_particle).position;
  (*active_particle).position = delta_position + current_position;
}
EXAMPLE: Using a pointer as a formal parameter
fn add_one(x: ptr<function,i32>) {
  /* Update the locations for 'x' to contain the next higher integer value,
     (or to wrap around to the largest negative i32 value).
     On the left-hand side, unary '*' converts the pointer to a reference that
     can then be assigned to. It has a read_write access mode, by default.
     /* On the right-hand side:
        - Unary '*' converts the pointer to a reference, with a read_write
          access mode.
        - The only matching type rule is for addition (+) and requires '*x' to
          have type i32, which is the store type for '*x'.  So the Load Rule
          applies and '*x' evaluates to the value stored in the memory for '*x'
          at the time of evaluation, which is the i32 value for 0.
        - Add 1 to 0, to produce a final value of 1 for the right-hand side. */
     Store 1 into the memory for '*x'. */
  *x = *x + 1;
}

@compute @workgroup_size(1)
fn main() {
  var i: i32 = 0;

  // Modify the contents of 'i' so it will contain 1.
  // Use unary '&' to get a pointer value for 'i'.
  // This is a clear signal that the called function has access to the memory
  // for 'i', and may modify it.
  add_one(&i);
  let one: i32 = i;  // 'one' has value 1.
}

6.4.8. Forming Reference and Pointer Values

A reference value is formed in one of the following ways:

In all cases, the access mode of the result is the same as the access mode of the original reference.

EXAMPLE: Component reference from a composite reference
struct S {
    age: i32,
    weight: f32
}
var<private> person: S;
// Elsewhere, 'person' denotes the reference to the memory underlying the variable,
// and will have type ref<private,S,read_write>.

fn f() {
    var uv: vec2<f32>;
    // For the remainder of this function body, 'uv' denotes the reference
    // to the memory underlying the variable, and will have type
    // ref<function,vec2<f32>,read_write>.

    // Evaluate the left-hand side of the assignment:
    //   Evaluate 'uv.x' to yield a reference:
    //   1. First evaluate 'uv', yielding a reference to the memory for
    //      the 'uv' variable. The result has type ref<function,vec2<f32>,read_write>.
    //   2. Then apply the '.x' vector access phrase, yielding a reference to
    //      the memory for the first component of the vector pointed at by the
    //      reference value from the previous step.
    //      The result has type ref<function,f32,read_write>.
    // Evaluating the right-hand side of the assignment yields the f32 value 1.0.
    // Store the f32 value 1.0 into the storage memory locations referenced by uv.x.
    uv.x = 1.0;

    // Evaluate the left-hand side of the assignment:
    //   Evaluate 'uv[1]' to yield a reference:
    //   1. First evaluate 'uv', yielding a reference to the memory for
    //      the 'uv' variable. The result has type ref<function,vec2<f32>,read_write>.
    //   2. Then apply the '[1]' array index phrase, yielding a reference to
    //      the memory for second component of the vector referenced from
    //      the previous step.  The result has type ref<function,f32,read_write>.
    // Evaluating the right-hand side of the assignment yields the f32 value 2.0.
    // Store the f32 value 2.0 into the storage memory locations referenced by uv[1].
    uv[1] = 2.0;

    var m: mat3x2<f32>;
    // When evaluating 'm[2]':
    // 1. First evaluate 'm', yielding a reference to the memory for
    //    the 'm' variable. The result has type ref<function,mat3x2<f32>,read_write>.
    // 2. Then apply the '[2]' array index phrase, yielding a reference to
    //    the memory for the third column vector pointed at by the reference
    //    value from the previous step.
    //    Therefore the 'm[2]' expression has type ref<function,vec2<f32>,read_write>.
    // The 'let' declaration is for type vec2<f32>, so the declaration
    // statement requires the initializer to be of type vec2<f32>.
    // The Load Rule applies (because no other type rule can apply), and
    // the evaluation of the initializer yields the vec2<f32> value loaded
    // from the memory locations referenced by 'm[2]' at the time the declaration
    // is executed.
    let p_m_col2: vec2<f32> = m[2];

    var A: array<i32,5>;
    // When evaluating 'A[4]'
    // 1. First evaluate 'A', yielding a reference to the memory for
    //    the 'A' variable. The result has type ref<function,array<i32,5>,read_write>.
    // 2. Then apply the '[4]' array index phrase, yielding a reference to
    //    the memory for the fifth element of the array referenced by
    //    the reference value from the previous step.
    //    The result value has type ref<function,i32,read_write>.
    // The let-declaration requires the right-hand-side to be of type i32.
    // The Load Rule applies (because no other type rule can apply), and
    // the evaluation of the initializer yields the i32 value loaded from
    // the memory locations referenced by 'A[4]' at the time the declaration
    // is executed.
    let A_4_value: i32 = A[4];

    // When evaluating 'person.weight'
    // 1. First evaluate 'person', yielding a reference to the memory for
    //    the 'person' variable declared at module scope.
    //    The result has type ref<private,S,read_write>.
    // 2. Then apply the '.weight' member access phrase, yielding a reference to
    //    the memory for the second member of the memory referenced by
    //    the reference value from the previous step.
    //    The result has type ref<private,f32,read_write>.
    // The let-declaration requires the right-hand-side to be of type f32.
    // The Load Rule applies (because no other type rule can apply), and
    // the evaluation of the initializer yields the f32 value loaded from
    // the memory locations referenced by 'person.weight' at the time the
    // declaration is executed.
    let person_weight: f32 = person.weight;

    // Alternatively, references can also be formed from pointers using
    // the same syntax.

    let uv_ptr = &uv;
    // For the remainder of this function body, 'uv_ptr' denotes a pointer
    // to the memory underlying 'uv', and will have the type
    // ptr<function,vec2<f32>,read_write>.

    // Evaluate the left-hand side of the assignment:
    //   Evaluate '*uv_ptr' to yield a reference:
    //   1. First evaluate 'uv_ptr', yielding a pointer to the memory for
    //      the 'uv' variable. The result has type ptr<function,vec2<f32>,read_write>.
    //   2. Then apply the indirection expression operator, yielding a
    //      reference to memory for 'uv'.
    // Evaluating the right-hand side of the assignment yields the vec2<f32> value (1.0, 2.0).
    // Store the value (1.0, 2.0) into the storage memory locations referenced by uv.
    *uv_ptr = vec2f(1.0, 2.0);

    // Evaluate the left-hand side of the assignment:
    //   Evaluate 'uv_ptr.x' to yield a reference:
    //   1. First evaluate 'uv_ptr', yielding a pointer to the memory for
    //      the 'uv' variable. The result has type ptr<function,vec2<f32>,read_write>.
    //   2. Then apply the '.x' vector access phrase, yielding a reference to
    //      the memory for the first component of the vector pointed at by the
    //      reference value from the previous step.
    //      The result has type ref<function,f32,read_write>.
    // Evaluating the right-hand side of the assignment yields the f32 value 1.0.
    // Store the f32 value 1.0 into the storage memory locations referenced by uv.x.
    uv_ptr.x = 1.0;

    // Evaluate the left-hand side of the assignment:
    //   Evaluate 'uv_ptr[1]' to yield a reference:
    //   1. First evaluate 'uv_ptr', yielding a pointer to the memory for
    //      the 'uv' variable. The result has type ptr<function,vec2<f32>,read_write>.
    //   2. Then apply the '[1]' array index phrase, yielding a reference to
    //      the memory for second component of the vector referenced from
    //      the previous step.  The result has type ref<function,f32,read_write>.
    // Evaluating the right-hand side of the assignment yields the f32 value 2.0.
    // Store the f32 value 2.0 into the storage memory locations referenced by uv[1].
    uv_ptr[1] = 2.0;

    let m_ptr = &m;
    // When evaluating 'm_ptr[2]':
    // 1. First evaluate 'm_ptr', yielding a pointer to the memory for
    //    the 'm' variable. The result has type ptr<function,mat3x2<f32>,read_write>.
    // 2. Then apply the '[2]' array index phrase, yielding a reference to
    //    the memory for the third column vector pointed at by the reference
    //    value from the previous step.
    //    Therefore the 'm[2]' expression has type ref<function,vec2<f32>,read_write>.
    // The 'let' declaration is for type vec2<f32>, so the declaration
    // statement requires the initializer to be of type vec2<f32>.
    // The Load Rule applies (because no other type rule can apply), and
    // the evaluation of the initializer yields the vec2<f32> value loaded
    // from the memory locations referenced by 'm[2]' at the time the declaration
    // is executed.
    let p_m_col2: vec2<f32> = m_ptr[2];

    let A_Ptr = &A;
    // When evaluating 'A[4]'
    // 1. First evaluate 'A', yielding a pointer to the memory for
    //    the 'A' variable. The result has type ptr<function,array<i32,5>,read_write>.
    // 2. Then apply the '[4]' array index phrase, yielding a reference to
    //    the memory for the fifth element of the array referenced by
    //    the reference value from the previous step.
    //    The result value has type ref<function,i32,read_write>.
    // The let-declaration requires the right-hand-side to be of type i32.
    // The Load Rule applies (because no other type rule can apply), and
    // the evaluation of the initializer yields the i32 value loaded from
    // the memory locations referenced by 'A[4]' at the time the declaration
    // is executed.
    let A_4_value: i32 = A_ptr[4];

    let person_ptr = &person;
    // When evaluating 'person.weight'
    // 1. First evaluate 'person_ptr', yielding a pointer to the memory for
    //    the 'person' variable declared at module scope.
    //    The result has type ptr<private,S,read_write>.
    // 2. Then apply the '.weight' member access phrase, yielding a reference to
    //    the memory for the second member of the memory referenced by
    //    the reference value from the previous step.
    //    The result has type ref<private,f32,read_write>.
    // The let-declaration requires the right-hand-side to be of type f32.
    // The Load Rule applies (because no other type rule can apply), and
    // the evaluation of the initializer yields the f32 value loaded from
    // the memory locations referenced by 'person.weight' at the time the
    // declaration is executed.
    let person_weight: f32 = person_ptr.weight;
}

A pointer value is formed in one of the following ways:

In all cases, the access mode of the result is the same as the access mode of the original pointer.

EXAMPLE: Pointer from a variable
// Declare a variable in the private address space, for storing an f32 value.
var<private> x: f32;

fn f() {
    // Declare a variable in the function address space, for storing an i32 value.
    var y: i32;

    // The name 'x' resolves to the module-scope variable 'x',
    // and has reference type ref<private,f32,read_write>.
    // Applying the unary '&' operator converts the reference to a pointer.
    // The access mode is the same as the access mode of the original variable, so
    // the fully specified type is ptr<private,f32,read_write>.  But read_write
    // is the default access mode for function address space, so read_write does not
    // have to be spelled in this case
    let x_ptr: ptr<private,f32> = &x;

    // The name 'y' resolves to the function-scope variable 'y',
    // and has reference type ref<private,i32,read_write>.
    // Applying the unary '&' operator converts the reference to a pointer.
    // The access mode defaults to 'read_write'.
    let y_ptr: ptr<function,i32> = &y;

    // A new variable, distinct from the variable declared at module scope.
    var x: u32;

    // Here, the name 'x' resolves to the function-scope variable 'x' declared in
    // the previous statement, and has type ref<function,u32,read_write>.
    // Applying the unary '&' operator converts the reference to a pointer.
    // The access mode defaults to 'read_write'.
    let inner_x_ptr: ptr<function,u32> = &x;
}

6.4.9. Comparison with References and Pointers in Other Languages

This section is informative, not normative.

References and pointers in WGSL are more restricted than in other languages. In particular:

Note: From the above rules, it is not possible to form a "dangling" pointer, i.e. a pointer that does not reference the memory for a "live" originating variable. A memory view may be an invalid memory reference, but it will never access memory locations not associated with the originating variable or buffer.

6.5. Texture and Sampler Types

A texel is a scalar or vector used as the smallest independently accessible element of a texture. The word texel is short for texture element.

A texture is a collection of texels supporting special operations useful for rendering. In WGSL, those operations are invoked via texture builtin functions. See § 16.7 Texture Built-in Functions for a complete list.

A WGSL texture corresponds to a WebGPU GPUTexture.

A texture has the following features:

texel format

The data representation of each texel. See § 6.5.1 Texel Formats.

dimensionality

The number of dimensions in the grid coordinates, and how the coordinates are interpreted. The number of dimensions is 1, 2, or 3. Most textures use cartesian coordinates. Cube textures have six square faces, and are sampled with a three dimensional coordinate interpreted as a direction vector from the origin toward the cube centered on the origin.

See GPUTextureViewDimension.

size

The extent of grid coordinates along each dimension. This is a function of mip level.

mip level count

The mip level count is at least 1 for sampled textures and depth textures, and equal to 1 for storage textures.
Mip level 0 contains a full size version of the texture. Each successive mip level contains a filtered version of the previous mip level at half the size (within rounding) of the previous mip level.
When sampling a texture, an explicit or implicitly-computed level-of-detail is used to select the mip levels from which to read texel data. These are then combined via filtering to produce the sampled value.

arrayed

Whether the texture is arrayed.

  • A non-arrayed texture is a grid of texels.

  • An arrayed texture is a homogeneous array of grids of texels.

array size

The number of homogeneous grids, if the texture is arrayed.

sample count

The number of samples, if the texture is multisampled.

Each texel in a texture is associated with a unique logical texel address, which is an integer tuple having:

A texture’s physical organization is typically optimized for rendering operations. To achieve this, many details are hidden from the programmer, including data layouts, data types, and internal operations that cannot be expressed directly in the shader language.

As a consequence, a shader does not have direct access to the texel memory within a texture variable. Instead, access is mediated through an opaque handle:

In this way, the set of supported operations for a texture type is determined by the availability of texture built-in functions having a formal parameter with that texture type.

Note: The handle stored by a texture variable cannot be changed by the shader. That is, the variable is read-only, even if the underlying texture to which it provides access may be mutable (e.g. a write-only storage texture).

The texture types are the set of types defined in:

A sampler is an opaque handle that controls how texels are accessed from a sampled texture or a depth texture.

A WGSL sampler maps to a WebGPU GPUSampler.

Texel access is controlled via several properties of the sampler:

addressing mode

Controls how texture boundaries and out-of-bounds coordinates are resolved. The addressing mode for each texture dimension can be set independently. See WebGPU GPUAddressMode.

filter mode

Controls which texels are accessed to produce the final result. Filtering can either use the nearest texel or interpolate between multiple texels. Multiple filter modes can be set independently. See WebGPU GPUFilterMode.

LOD clamp

Controls the min and max levels of details that are accessed.

comparison

Controls the type of comparison done for comparison sampler. See WebGPU GPUCompareFunction.

max anisotropy

Controls the maximum anisotropy value used by the sampler.

Samplers cannot be created in WGSL modules and their state (e.g. the properties listed above) are immutable within a shader and can only be set by the WebGPU API.

It is a pipeline-creation error if a filtering sampler (i.e. any sampler using interpolative filtering) is used with texture that has a non-filterable format.

Note: The handle stored by a sampler variable cannot be changed by the shader.

6.5.1. Texel Formats

In WGSL, certain texture types are parameterized by texel format.

A texel format is characterized by:

channels

Each channel contains a scalar. A texel format has up to four channels: r, g, b, and a, normally corresponding to the concepts of red, green, blue, and alpha channels.

channel format

The number of bits in the channel, and how those bits are interpreted.

Each texel format in WGSL corresponds to a WebGPU GPUTextureFormat with the same name.

Only certain texel formats are used in WGSL source code. The channel formats used to define those texel formats are listed in the Channel Formats table. The second last column specifies the conversion from the stored channel bits to the value used in the shader. This is also known as the channel transfer function, or CTF. The last column specifies the conversion from the shader value to the stored channel bits. This is also known as the inverse channel transfer function, or ICTF.

Note: The channel transfer function for 8unorm maps {0,...,255} to the floating point interval [0.0, 1.0].

Note: The channel transfer function for 8snorm maps {-128,...,127} to the floating point interval [-1.0, 1.0].

Channel Formats
Channel format Number of stored bits Interpretation of stored bits Shader type Shader value (Channel Transfer Function) Write value T (Inverse Channel Transfer Function)
8unorm 8 unsigned integer v ∈ {0,...,255} f32 v ÷ 255 max(0, min(1, T))
8snorm 8 signed integer v ∈ {-128,...,127} f32 v ÷ 127 max(-1, min(1, T))
8uint 8 unsigned integer v ∈ {0,...,255} u32 v min(255, T)
8sint 8 signed integer v ∈ {-128,...,127} i32 v max(-128, min(127, T))
16uint 16 unsigned integer v ∈ {0,...,65535} u32 v min(65535, T)
16sint 16 signed integer v ∈ {-32768,...,32767} i32 v max(-32768, min(32767, T))
16float 16 IEEE-754 binary16 16-bit floating point value v f32 v quantizeToF16(T)
32uint 32 32-bit unsigned integer value v u32 v T
32sint 32 32-bit signed integer value v i32 v T
32float 32 IEEE-754 binary32 32-bit floating point value v f32 v T

The texel formats listed in the Texel Formats for Storage Textures table correspond to the WebGPU plain color formats which support the WebGPU STORAGE_BINDING usage with at least one access mode. These texel formats are used to parameterize the storage texture types defined in § 6.5.5 Storage Texture Types.

When the texel format does not have all four channels, then:

The last column in the table below uses the format-specific channel transfer function from the channel formats table.

Texel Formats for Storage Textures
Texel format Channel format Channels in memory order Corresponding shader value
rgba8unorm 8unorm r, g, b, a vec4<f32>(CTF(r), CTF(g), CTF(b), CTF(a))
rgba8snorm 8snorm r, g, b, a vec4<f32>(CTF(r), CTF(g), CTF(b), CTF(a))
rgba8uint 8uint r, g, b, a vec4<u32>(CTF(r), CTF(g), CTF(b), CTF(a))
rgba8sint 8sint r, g, b, a vec4<i32>(CTF(r), CTF(g), CTF(b), CTF(a))
rgba16uint 16uint r, g, b, a vec4<u32>(CTF(r), CTF(g), CTF(b), CTF(a))
rgba16sint 16sint r, g, b, a vec4<i32>(CTF(r), CTF(g), CTF(b), CTF(a))
rgba16float 16float r, g, b, a vec4<f32>(CTF(r), CTF(g), CTF(b), CTF(a))
r32uint 32uint r vec4<u32>(CTF(r), 0u, 0u, 1u)
r32sint 32sint r vec4<i32>(CTF(r), 0, 0, 1)
r32float 32float r vec4<f32>(CTF(r), 0.0, 0.0, 1.0)
rg32uint 32uint r, g vec4<u32>(CTF(r), CTF(g), 0.0, 1.0)
rg32sint 32sint r, g vec4<i32>(CTF(r), CTF(g), 0.0, 1.0)
rg32float 32float r, g vec4<f32>(CTF(r), CTF(g), 0.0, 1.0)
rgba32uint 32uint r, g, b, a vec4<u32>(CTF(r), CTF(g), CTF(b), CTF(a))
rgba32sint 32sint r, g, b, a vec4<i32>(CTF(r), CTF(g), CTF(b), CTF(a))
rgba32float 32float r, g, b, a vec4<f32>(CTF(r), CTF(g), CTF(b), CTF(a))
bgra8unorm 8unorm b, g, r, a vec4<f32>(CTF(r), CTF(g), CTF(b), CTF(a))

WGSL predeclares an enumerant for each of the texel formats in the table.

6.5.2. Sampled Texture Types

A sampled texture is capable of being accessed in conjunction with a sampler. It can also be accessed without the use of a sampler. Sampled textures only allow read accesses.

The texel format is the format attribute of the GPUTexture bound to the texture variable. WebGPU validates compatibility between the texture, the sampleType of the bind group layout, and the sampled type of the texture variable.

The texture is parameterized by a sampled type and must be f32, i32, or u32.

Type Dimensionality Arrayed
texture_1d<T> 1D No
texture_2d<T> 2D No
texture_2d_array<T> 2D Yes
texture_3d<T> 3D No
texture_cube<T> Cube No
texture_cube_array<T> Cube Yes

6.5.3. Multisampled Texture Types

A multisampled texture has a sample count of 1 or more. Despite the name, it cannot be used with a sampler. It effectively stores multiple texels worth of data per logical texel address if the sample index is ignored.

The texel format is the format attribute of the GPUTexture bound to the texture variable. WebGPU validates compatibility between the texture, the sampleType of the bind group layout, and the sampled type of the texture variable.

The texture is parameterized by a sampled type and must be f32, i32, or u32.

Type Dimensionality Arrayed
texture_multisampled_2d<T> 2D No
texture_depth_multisampled_2d 2D No

6.5.4. External Sampled Texture Types

An External texture is an opaque two-dimensional float-sampled texture type similar to texture_2d<f32> but potentially with a different representation. It can be read using textureLoad or textureSampleBaseClampToEdge built-in functions, which handle these different representations.

See WebGPU § 6.4 GPUExternalTexture.

Type Dimensionality Arrayed
texture_external 2D No

6.5.5. Storage Texture Types

A storage texture supports accessing individual texel values without the use of a sampler.

A storage texture type must be parameterized by one of the texel formats for storage textures. The texel format determines the conversion function as specified in § 6.5.1 Texel Formats.

When writing texels to a storage texture the inverse of the conversion function is used to convert the shader value to the stored texel.

Type Dimensionality Arrayed
texture_storage_1d<Format, Access> 1D No
texture_storage_2d<Format, Access> 2D No
texture_storage_2d_array<Format, Access> 2D Yes
texture_storage_3d<Format, Access> 3D No

6.5.6. Depth Texture Types

A depth texture is capable of being accessed in conjunction with a sampler_comparison. It can also be accessed without the use of a sampler. Depth textures only allow read accesses.

The texel format of the texture is defined in the GPUTextureBindingLayout.

Type Dimensionality Arrayed
texture_depth_2d 2D No
texture_depth_2d_array 2D Yes
texture_depth_cube Cube No
texture_depth_cube_array Cube Yes

6.5.7. Sampler Type

A sampler mediates access to a sampled texture or a depth texture, by performing a combination of:

A sampler types are:

Type Description
sampler Sampler. Mediates access to a sampled texture.
sampler_comparison Comparison sampler. Mediates access to a depth texture.

Samplers are parameterized when created in the WebGPU API. They cannot be modified by a WGSL module.

Samplers can only be used by the texture built-in functions.

sampler
sampler_comparison

6.6. AllTypes Type

The AllTypes type is the set of all WGSL types.

There is no way to write the AllTypes type in WGSL source.

See § 6.9 Predeclared Types and Type-Generators Summary for the list of all predeclared types and type-generators.

Note:A type is not a value in an ordinary sense. It is not data that is manipulated by a shader at runtime.

Instead, the AllTypes type exists so type checking rules will apply to any phrase that may contain an ordinary value. WGSL makes the rules consistent by defining a type to be a kind of value, and allowing an expression to denote a type.

The motivating case is a template parameter, which in various contexts may denote several kinds of things, including a type, an enumerant, or a plain value. In particular, the template_arg_expression grammar rule expands to the expression grammar nonterminal.

6.7. Type Aliases

A type alias declares a new name for an existing type. The declaration must appear at module scope, and its scope is the entire program.

When type T is defined as a type alias for a structure type S, all properties of the members of S, including attributes, carry over to the members of T.

type_alias_decl :

'alias' ident '=' type_specifier

EXAMPLE: Type Alias
alias Arr = array<i32, 5>;

alias RTArr = array<vec4<f32>>;

alias single = f32;     // Declare an alias for f32
const pi_approx: single = 3.1415;
fn two_pi() -> single {
  return single(2) * pi_approx;
}

6.8. Type Specifier Grammar

See § 8.17 Type Expressions.

type_specifier :

template_elaborated_ident

template_elaborated_ident :

ident _disambiguate_template template_list ?

Note: An expression can also denote a type, by expanding via the primary_expression grammar rule to template_elaborated_ident, and via parenthesization.

6.9. Predeclared Types and Type-Generators Summary

The predeclared types that can be spelled in WGSL source are:

WGSL also predeclares the return types for the frexp, modf, and atomicCompareExchangeWeak built-in functions. However, they cannot be spelled in WGSL source.

The predeclared type-generators are listed in the following table:

Predeclared type generators
Predeclared type-generator Cross-reference
array See § 6.2.9 Array Types
atomic See § 6.2.8 Atomic Types
mat2x2 See § 6.2.7 Matrix Types, which also lists predeclared aliases for matrix types.

Note: These are also used in value constructor expressions to create matrices.

mat2x3
mat2x4
mat3x2
mat3x3
mat3x4
mat4x2
mat4x3
mat4x4
ptr See § 6.4.3 Reference and Pointer Types
texture_1d See § 6.5.2 Sampled Texture Types
texture_2d
texture_2d_array
texture_3d
texture_cube
texture_cube_array
texture_multisampled_2d See § 6.5.3 Multisampled Texture Types
texture_storage_1d See § 6.5.5 Storage Texture Types
texture_storage_2d
texture_storage_2d_array
texture_storage_3d
vec2 See § 6.2.6 Vector Types, which also lists predeclared aliases for vector types.

Note: These are also used in value constructor expressions to create vectors.

vec3
vec4

7. Variable and Value Declarations

Variable and value declarations provide names for data values.

A value declaration creates a name for a value, and that value is immutable once it has been declared. The four kinds of value declarations are const, override, let, and formal parameter declarations, further described below (see § 7.2 Value Declarations).

A variable declaration creates a name for memory locations for storing a value; the value stored there may be updated, if the variable has a read_write access mode. There is one kind of variable declaration, var, but it has options for address space and access modes in various combinations, described below (see § 7.3 var Declarations).

Note: A value declaration does not have associated memory locations. For example, no WGSL expression can form a pointer to the value.

A declaration appearing outside of any function definition is at module scope. Its name is in scope for the entire program.

A declaration appearing within a function definition is in function scope. The name is available for use in the statement immediately after its declaration until the end of the brace-delimited list of statements immediately enclosing the declaration. A function-scope declaration is a dynamic context.

NOTE:
Variable and value declarations have a similar overall syntax. The following non-normative illustration shows the general form of variable and value declarations, where [...] denotes optional parts, ...* denotes zero or more repetitions of the preceding, and ...+ denotes one or more repetitions of the preceding. For specific syntactic rules, see the respective sections for the elements.
// Specific value declarations.
             const    name [: type]  = initializer ;
[attribute]* override name [: type] [= initializer];
             let      name [: type]  = initializer ;

// General variable form.
[attribute]* var[<address_space[, access_mode]>] name [: type] [= initializer];

// Specific variable declarations.
// Function scope.
             var[<function>] name [: type] [= initializer];

// Module scope.
             var<private>    name [: type] [= initializer];
             var<workgroup>  name : type;
[attribute]+ var<uniform>    name : type;
[attribute]+ var             name : texture_type;
[attribute]+ var             name : sampler_type;
[attribute]+ var<storage[, access_mode]> name : type;

Each such declaration must have an explicitly specified type or an initializer. Both a type and an initializer may be specified. Each such declaration determines the type for the associated data value, known as the effective-value-type for the declaration. The effective-value-type of the declaration is:

Each kind of value or variable declaration may place additional constraints on the form of the initializer expression, if present, and on the effective-value-type.

Variable and Value Declaration Feature Summary.
Declaration Mutability Scope Effective-value-type1 Initializer Support Initializer Expression2 Part of Resource Interface
const Immutable Module or function Constructible (Concrete or abstract) Required const-expression No
override Immutable Module Concrete scalar Optional3 const-expression or override-expression No4
let Immutable Function Concrete constructible or pointer type Required const-expression, override-expression, or runtime expression No
var<storage, read>
var<storage>
Immutable Module Concrete host-shareable Disallowed Yes.
storage buffer
var<storage, read_write>5,6 Mutable Module Concrete host-shareable Disallowed Yes.
storage buffer
var<uniform> Immutable Module Concrete constructible host-shareable Disallowed Yes.
uniform buffer
var6 Immutable7 Module Texture Disallowed Yes.
texture resource
var Immutable Module Sampler Disallowed Yes.
sampler resource
var<workgroup>6,8 Mutable Module Concrete plain type with a fixed footprint9 Disallowed10 No
var<private> Mutable Module Concrete constructible Optional10 const-expression or override-expression No
var<function>
var
Mutable Function Concrete constructible Optional10 const-expression, override-expression, or runtime expression No
  1. Only const-declarations can be abstract types, and only when the type is not explicitly specified.

  2. The type of the expression must be feasibly converted to the effective-value-type.

  3. If an initializer is not specified, a value must be provided at pipeline-creation time.

  4. Override-declarations are part of the shader interface, but are not bound resources.

  5. Storage buffers and storage textures with an access mode other than read cannot be statically accessed in a vertex shader stage. See WebGPU createBindGroupLayout().

  6. Atomic types can only appear in mutable storage buffers or workgroup variables.

  7. The data in storage textures with a write or read_write access mode is mutable, but can only be modified via textureStore built-in function. The variable itself cannot be modified.

  8. Variables in the workgroup address space can only be statically accessed in a compute shader stage.

  9. The element count of the outermost array may be an override-expression.

  10. If there is no initializer, the variable is default initialized.

7.1. Variables vs Values

Variable declarations are the only mutable data in a WGSL module. Value declarations are always immutable. Variables can be the basis of reference and pointer values because variables have associated memory locations, whereas a value declaration cannot be the basis of a pointer or reference value.

Using variables is generally more expensive than using value declarations, because using a variable requires extra operations to read or write to the memory locations associated with the variable.

Generally speaking, an author should prefer using declarations in the following order, with the most preferred option listed first:

This will generally result in the best overall performance of a shader.

7.2. Value Declarations

When an identifier resolves to a value declaration, the identifier denotes that value.

WGSL provides multiple kinds of value declarations. The value for each kind of declaration is fixed at a different point in the shader lifecycle. The different kinds of value declarations and when their values are fixed are:

Note: Formal parameters are described in § 10 Functions.

7.2.1. const Declarations

A const-declaration specifies a name for a data value that is fixed at shader-creation time. Each const-declaration requires an initializer. A const-declaration can be declared in module or function scope. The initializer expression must be a const-expression. The type of a const-declaration must be a concrete or abstract constructible type. const-declarations are the only declarations where the effective-value-type may be abstract.

Note: Since abstract numeric types cannot be spelled in WGSL, they can only be used via type inference.

EXAMPLE: const-declarations at module scope
const a = 4;                  // AbstractInt with a value of 4.
const b : i32 = 4;            // i32 with a value of 4.
const c : u32 = 4;            // u32 with a value of 4.
const d : f32 = 4;            // f32 with a value of 4.
const e = vec3(a, a, a);      // vec3 of AbstractInt with a value of (4, 4, 4).
const f = 2.0;                // AbstractFloat with a value of 2.
const g = mat2x2(a, f, a, f); // mat2x2 of AbstractFloat with a value of:
                              // ((4.0, 2.0), (4.0, 2.0)).
                              // The AbstractInt a converts to AbstractFloat.
                              // An AbstractFloat cannot convert to AbstractInt.
const h = array(a, f, a, f);  // array of AbstractFloat with 4 components:
                              // (4.0, 2.0, 4.0, 2.0).

7.2.2. override Declarations

An override-declaration specifies a name for a pipeline-overridable constant value. An override-declaration must only be declared at module scope. The value of a pipeline-overridable constant is fixed at pipeline-creation time. The value is one provided by the WebGPU pipeline-creation method, if specified, and otherwise is the value of its concretized initializer expression. The effective-value-type of an override-declaration must be a concrete scalar type.

An initializer expression is optional. If present, it must be an override-expression and represents the pipeline-overridable constant default value. If no initializer is specified, it is a pipeline-creation error if a value is not provided at pipeline-creation time.

If the declaration has an id attribute applied, the literal operand is known as the pipeline constant ID, and must be a unique integer between 0 and 65535 inclusive. That is, two override-declarations must not use the same pipeline constant ID.

The application can specify its own value for an override-declaration at pipeline-creation time. The pipeline creation API accepts a mapping from overridable constants to a value of the constant’s type. The constant is identified by a pipeline-overridable constant identifier string, which is the base-10 representation of the pipeline constant ID if specified, and otherwise the declared name of the constant.

EXAMPLE: Module constants, pipeline-overrideable
@id(0)    override has_point_light: bool = true;  // Algorithmic control
@id(1200) override specular_param: f32 = 2.3;     // Numeric control
@id(1300) override gain: f32;                     // Must be overridden
          override width: f32 = 0.0;              // Specified at the API level using
                                                  // the name "width".
          override depth: f32;                    // Specified at the API level using
                                                  // the name "depth".
                                                  // Must be overridden.
          override height = 2 * depth;            // The default value
                                                  // (if not set at the API level),
                                                  // depends on another
                                                  // overridable constant.

7.2.3. let Declarations

A let-declaration specifies a name for a value that is fixed each time the statement is executed at runtime. A let-declaration must only be declared in function scope, and as such, is a dynamic context. A let-declaration must have an initializer expression. The value is the concretized value of the initializer. The effective-value-type of a let-declaration must be either a concrete constructible type or a pointer type.

EXAMPLE: let-declared constants at function scope
// 'blockSize' denotes the i32 value 1024.
let blockSize: i32 = 1024;

// 'row_size' denotes the u32 value 16u.  The type is inferred.
let row_size = 16u;

7.3. var Declarations

A variable is a named reference to memory that can contain a value of a particular storable type.

Two types are associated with a variable: its store type (the type of value that may be placed in the referenced memory) and its reference type (the type of the variable itself). If a variable has store type T, address space AS, and access mode AM, then its reference type is ref<AS,T,AM>. The store type of a variable is always concrete.

A variable declaration:

When an identifier resolves to a variable declaration, the identifier is an expression denoting the reference memory view for the variable’s memory, and its type is the variable’s reference type. See § 8.11 Variable Identifier Expression.

If the address space or access mode for a variable declaration are specified in program source, they are written as a template list after the var keyword:

Variables in the private, storage, uniform, workgroup, and handle address spaces must only be declared in module scope, while variables in the function address space must only be declared in function scope. The address space must be specified for all address spaces except handle and function. The handle address space must not be specified. Specifying the function address space is optional.

The access mode always has a default value, and except for variables in the storage address space, must not be specified in the WGSL source. See § 13.3 Address Spaces.

A variable in the uniform address space is a uniform buffer variable. Its store type must be a host-shareable constructible type, and must satisfy the address space layout constraints.

A variable in the storage address space is a storage buffer variable. Its store type must be a host-shareable type and must satisfy the address space layout constraints. The variable may be declared with a read or read_write access mode; the default is read.

A texture resource is a variable whose effective-value-type is a texture type. It is declared at module scope. It holds an opaque handle which is used to access the underlying grid of texels in a texture. The handle itself is in the handle address space and is always read-only. In many cases the underlying texels are read-only, and we say the texture variable immutable. For write-only storage textures and read-write storage textures, the underlying texels are mutable, and by convention we say the texture variable is mutable.

A sampler resource is a variable whose effective-value-type is a sampler type. It is declared at module scope, exists in the handle address space, and is immutable.

As described in § 12.3.2 Resource Interface, uniform buffers, storage buffers, textures, and samplers form the resource interface of a shader.

The lifetime of a variable is the period during shader execution for which the memory locations are associated with the variable. The lifetime of a module scope variable is the entire execution of the shader stage. There is an independent version of a variable in the private and function address spaces for each invocation. Function-scope variables are a dynamic context. The lifetime of a function-scope variable is determined by its scope:

Two resource variables may have overlapping memory locations, but it is a dynamic error if either of those variables is mutable. Other variables with overlapping lifetimes will not have overlapping memory locations. When a variable’s lifetime ends, its memory may be used for another variable.

Note: WGSL ensures the contents of a variable are only observable during the variable’s lifetime.

When a variable in the private, function, or workgroup address spaces is created, it will have an initial value. If no initializer is specified the initial value is the default initial value. The initial values are computed as follows:

Variables in other address spaces are resources set by bindings in the draw command or dispatch command.

Consider the following snippet of WGSL:

EXAMPLE: Variable initial values
var i: i32;         // Initial value is 0.  Not recommended style.
loop {
  var twice: i32 = 2 * i;   // Re-evaluated each iteration.
  i++;
  if i == 5 { break; }
}
The loop body will execute six times. Variable i will take on values 0, 1, 2, 3, 4, 5, and variable twice will take on values 0, 2, 4, 6, and 8.

Consider the following snippet of WGSL:

EXAMPLE: Reading a variable multiple times
var x: f32 = 1.0;
let y = x * x + x + 1;
Because x is a variable, all accesses to it turn into load and store operations. However, it is expected that either the browser or the driver optimizes this intermediate representation such that the redundant loads are eliminated.
EXAMPLE: Module scope variable declarations
var<private> decibels: f32;
var<workgroup> worklist: array<i32,10>;

struct Params {
  specular: f32,
  count: i32
}

// Uniform buffer. Always read-only, and has more restrictive layout rules.
@group(0) @binding(2)
var<uniform> param: Params;    // A uniform buffer

// A storage buffer, for reading and writing
@group(0) @binding(0)
var<storage,read_write> pbuf: array<vec2<f32>>;

// Textures and samplers are always in "handle" space.
@group(0) @binding(1)
var filter_params: sampler;
EXAMPLE: Access modes for buffers
// 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.

struct ParamsTable {weight: f32}

// Uniform buffer. Always read-only, and has more restrictive layout rules.
@group(0) @binding(2)
var<uniform> params: ParamsTable;     // Can read, cannot write.
EXAMPLE: Function scope variables and constants
fn f() {
   var<function> count: u32;  // A variable in function address space.
   var delta: i32;            // Another variable in the function address space.
   var sum: f32 = 0.0;        // A function address space variable with initializer.
   var pi = 3.14159;          // Infer the f32 store type from the initializer.
}

7.4. Variable and Value Declaration Grammar Summary

variable_or_value_statement :

variable_decl

| variable_decl '=' expression

| 'let' optionally_typed_ident '=' expression

| 'const' optionally_typed_ident '=' expression

variable_decl :

'var' _disambiguate_template template_list ? optionally_typed_ident

optionally_typed_ident :

ident ( ':' type_specifier ) ?

global_variable_decl :

attribute * variable_decl ( '=' expression ) ?

global_value_decl :

'const' optionally_typed_ident '=' expression

| attribute * 'override' optionally_typed_ident ( '=' expression ) ?

8. Expressions

Expressions specify how values are computed.

The different kinds of value expressions provide a tradeoff between when they are evaluated and how expressive they can be. The sooner the evaluation, the more constrained the operations, but also the more places the value can be used. This tradeoff leads to different flexibility with each kind of value declaration. const-expressions and override-expressions are evaluated prior to execution on the GPU, so only the result of the computation of the expression is necessary in the final GPU code. Additionally, because const-expressions are evaluated at shader-creation time they can be used in more situations than override-expressions, for example, to size arrays in function scope variables. A runtime expression is an expression that is neither a const-expression nor an override-expression. A runtime expression is computed on the GPU during shader execution. While runtime expressions can be used by fewer grammar elements, they can be computed from a larger class of expressions, for example, other runtime values.

8.1. Early Evaluation Expressions

WGSL defines two types of expressions that can be evaluated before runtime:

8.1.1. const Expressions

Expressions that can be evaluated at shader-creation time are called const-expressions. An expression is a const-expression if all its identifiers resolve to:

The type of a const expression must resolve to a type with a creation-fixed footprint.

Note: Abstract types can be the inferred type of a const-expression.

A const-expression E will be evaluated if and only if:

Note: The evaluation rule implies that short-circuiting operators && and || guard evaluation of their right-hand side subexpressions unless there is a subexpression that requires evaluation to determine a static type.

A const-expression may be evaluated by the CPU implementing the WebGPU API methods. Therefore accuracy requirements for operations on AbstractFloat values are no more strict than required for common WebGPU runtime environments, such as WebAssembly [WASM-CORE-2] and ECMAScript [ECMASCRIPT]. Accuracy requirements for concrete floating point types (such as f32) are specified in § 14.6.4.1 Accuracy of Concrete Floating Point Expressions.

Example: (42) is analyzed as follows:

Example: -5 is analyzed as follows:

Example: -2147483648 is analyzed as follows:

Example: const minint = -2147483648; is analyzed as follows:

Example: let minint = -2147483648; is analyzed as follows:

Example: false && (10i < i32(5 * 1000 * 1000 * 1000)) is analyzed as follows:

Example: false && array<u32, 1 + 2>(0, 1, 2)[0] == 0

8.1.2. override Expressions

Expressions that can be evaluated at pipeline creation time are called override-expressions. An expression is an override-expression if all its identifiers resolve to:

Note: All const-expressions are also override-expressions.

Override-expressions are only validated or evaluated after any API-provided values are substituted for override-declarations. If an override-declaration has its value substituted via the API, its initializer expression, if present, will not be evaluated. Otherwise, an override-expression E will be evaluated if and only if:

Note: Not all override-expressions may be usable as the initializer for an override-declaration, because such initializers must resolve to a concrete scalar type.

Example: override x = 42; is analyzed as follows:

Example: let y = x + 1; is analyzed as follows:

Example: vec3(x,x,x) is analyzed as follows:

EXAMPLE: Shader-creation errors from override-expressions
override a : i32 = 0;
override b = a / 0; // shader-creation error,
                    // regardless of attempting to override c
EXAMPLE: Pipeline-creation errors from override-expressions
override a : i32 = 0;
override b = 1 / a;

// b is a part of the frag1 shader. When compiling frag1 into a pipeline
// the following cases may occur:
// * if b is overridden, no error occurs.
// * if a is overridden to a non-zero value, no error occurs.
// * if a is 0 and b is not overridden, a pipeline-creation error occurs.
@fragment
fn frag1() {
  _ = b;
}

// b is not part of the frag2 shader. When compiling frag2 into a pipeline
// no errors occur even if b is not overridden and the value of a is 0.
@fragment
fn frag2() {
}

8.2. Indeterminate values

In limited cases, an evaluation of a runtime expression can occur using unsupported values for its subexpressions.

In such a case, the result of that evaluation is an indeterminate value of the expression’s static type, meaning some arbitrary implementation-chosen value of the static type.

A distinct value may be produced for each unique dynamic context in which the expression is evaluated. For example, if the evaluation occurs once per iteration of a loop, a distinct value may be computed for each loop iteration.

Note: If the type is a floating point type and the implementation supports NaN values, then the indeterminate value produced at runtime may be a NaN value.

EXAMPLE: Indeterminate value example
fn fun() {
   var extracted_values: array<i32,2>;
   const v = vec2<i32>(0,1);

   for (var i: i32 = 0; i < 2 ; i++) {
      // A runtime-expression used to index a vector, but outside the
      // indexing bounds of the vector, produces an indeterminate value
      // of the vector component type.
      let extract = v[i+5];

      // Now 'extract' is any value of type i32.

      // Save it for later.
      extracted_values[i] = extract;

      if extract == extract {
         // This is always executed
      }
      if extract < 2 {
         // This might be executed, but might not be executed.
         // Even though the original vector components are 0 and 1,
         // the extracted value might not be either of those values.
      }
   }
   if extracted_values[0] == extracted_values[1] {
      // This might be executed, but might not be executed.
   }
}

fn float_fun(runtime_index: u32) {
   const v = vec2<f32>(0,1); // A vector of floating point values

   // As in the previous example, 'float_extract' is an indeterminate value.
   // Since it is a floating point type, it may be a NaN.
   let float_extract: f32 = v[runtime_index+5];

   if float_extract == float_extract {
      // This *might not* be executed, because:
      //  -  'float_extract' may be NaN, and
      //  -  a NaN is never equal to any other floating point number,
      //     even another NaN.
   }
}

8.3. Literal Value Expressions

Scalar literal type rules
Precondition Conclusion Description
true: bool true boolean value.
false: bool false boolean value.
e is an integer literal with no suffix e: AbstractInt Abstract integer literal value.
e is a floating point literal with no suffix e: AbstractFloat Abstract float literal value.
e is an integer literal with i suffix e: i32 32-bit signed integer literal value.
e is an integer literal with u suffix e: u32 32-bit unsigned integer literal value.
e is an floating point literal with f suffix e: f32 32-bit floating point literal value.
e is an floating point literal with h suffix e: f16 16-bit floating point literal value.

8.4. Parenthesized Expressions

Parenthesized expression type rules
Precondition Conclusion Description
e : T ( e ) : T Evaluates to e.
Use parentheses to isolate an expression from the surrounding text.

8.5. Composite Value Decomposition Expressions

This section describes expressions for getting a component of a composite value, and for getting a reference to a component from a memory view to the containing composite value. For this discussion, the composite value, or the memory view to the composite value, is known as the base.

There are two ways of doing so:

named component expression

The expression for the base B is followed by a period '.' (U+002D), and then the name of the component.

  • This is supported when B is of vector or structure type, or a memory view to a vector or structure type.

  • The valid names depend on B's type.

indexing expression

The expression for the base is followed by '[' (U+005B), then the expression for an index then ']' (U+005D).

Syntactically, these two forms are embodied by uses of the component_or_swizzle_specifier grammar rule.

The index value i of an indexing expression is an in-bounds index if 0 ≤ i < N, where N is the number of components (elements) of the composite type:

The index value is an out-of-bounds index when it is not an in-bounds index. An out-of-bounds index is often a programming defect, and will often cause a error. See below for details.

Additionally, vector types support a swizzling syntax for creating a new vector value from the components of another vector.

8.5.1. Vector Access Expression

Accessing components of a vector can be done either:

The convenience names are accessed using the . notation. (e.g. color.bgra).

The convenience letterings must not be mixed. For example, you cannot use .rybw.

A convenience letter must not access a component past the end of the vector.

The convenience letterings can be applied in any order, including duplicating letters as needed. The provided number of letters must be between 1 and 4. That is, using convenience letters can only produce a scalar type or a valid vector type.

The result type depends on the number of letters provided. Assuming a vec4<f32>

Accessor Result type
r f32
rg vec2<f32>
rgb vec3<f32>
rgba vec4<f32>
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
8.5.1.1. Vector Single Component Selection
Vector decomposition: single component selection
Precondition Conclusion Description
e: vecN<T>
e.x: T
e.r: T
Select the first component of e

This is a single-letter swizzle.

e: vecN<T>
e.y: T
e.g: T
Select the second component of e

This is a single-letter swizzle.

e: vecN<T>
N is 3 or 4
e.z: T
e.b: T
Select the third component of e

This is a single-letter swizzle.

e: vec4<T> e.w: T
e.a: T
Select the fourth component of e

This is a single-letter swizzle.

e: vecN<T>
i: i32 or u32
T is concrete
e[i]: T Select the ith component of vector
The first component is at index i=0.

If i is outside the range [0,N-1]:

e: vecN<T>
i: i32 or u32
T is abstract
i is a const-expression
e[i]: T Select the ith component of vector
The first component is at index i=0.

It is a shader-creation error if i is outside the range [0,N-1].

Note: When an abstract vector value e is indexed by an expression that is not a const-expression, then the vector is concretized before the index is applied.

8.5.1.2. Vector Multiple Component Selection

The expressions in this section are all multi-letter swizzles. Each forms a vector from the components of another vector.

A multi-letter swizzle cannot appear on the left-hand side of an assignment: The left-hand side of an assignment must be of reference type, but a multi-letter swizzle expression always yields a value of vector type.

Vector decomposition: multiple component selection
Precondition Conclusion Description
e: vecN<T> or ptr<AS,vecN<T,AM>>
I is the letter x, y, z, or w
J is the letter x, y, z, or w
AM is read or read_write
e.IJ: vec2<T>
Computes the two-component vector with first component e.I, and second component e.J.
Letter z is valid only when N is 3 or 4.
Letter w is valid only when N is 4.

If e is a pointer, an indirection is first applied and then the load rule is invoked.
e: vecN<T> or ptr<AS,vecN<T,AM>>
I is the letter r, g, b, or a
J is the letter r, g, b, or a
AM is read or read_write
e.IJ: vec2<T>
Computes the two-component vector with first component e.I, and second component e.J.
Letter b is valid only when N is 3 or 4.
Letter a is valid only when N is 4.

If e is a pointer, an indirection is first applied and then the load rule is invoked.
e: vecN<T> or ptr<AS,vecN<T,AM>>
I is the letter x, y, z, or w
J is the letter x, y, z, or w
K is the letter x, y, z, or w
AM is read or read_write
e.IJK: vec3<T>
Computes the three-component vector with first component e.I, second component e.J, and third component e.K.
Letter z is valid only when N is 3 or 4.
Letter w is valid only when N is 4.

If e is a pointer, an indirection is first applied and then the load rule is invoked.
e: vecN<T> or ptr<AS,vecN<T,AM>>
I is the letter r, g, b, or a
J is the letter r, g, b, or a
K is the letter r, g, b, or a
AM is read or read_write
e.IJK: vec3<T>
Computes the three-component vector with first component e.I, second component e.J, and third component e.K.
Letter b is only valid when N is 3 or 4.
Letter a is only valid when N is 4.

If e is a pointer, an indirection is first applied and then the load rule is invoked.
e: vecN<T> or ptr<AS,vecN<T,AM>>
I is the letter x, y, z, or w
J is the letter x, y, z, or w
K is the letter x, y, z, or w
L is the letter x, y, z, or w
AM is read or read_write
e.IJKL: vec4<T>
Computes the four-component vector with first component e.I, second component e.J, third component e.K, and fourth component e.L.
Letter z is valid only when N is 3 or 4.
Letter w is valid only when N is 4.

If e is a pointer, an indirection is first applied and then the load rule is invoked.
e: vecN<T> or ptr<AS,vecN<T,AM>>
I is the letter r, g, b, or a
J is the letter r, g, b, or a
K is the letter r, g, b, or a
L is the letter r, g, b, or a
AM is read or read_write
e.IJKL: vec4<T>
Computes the four-component vector with first component e.I, second component e.J, third component e.K, and fourth component e.L.
Letter b is only valid when N is 3 or 4.
Letter a is only valid when N is 4.

If e is a pointer, an indirection is first applied and then the load rule is invoked.

Note: In the table above, reference types are implicitly handled via the load rule.

8.5.1.3. Component Reference from Vector Memory View

The expressions in this section form a memory view of a single component of a vector from the memory view of the whole vector.

The WGSL type rules imply that such expressions can appear:

A write access to component of a vector may access all of the memory locations associated with that vector.

Note: This means accesses to different components of a vector in memory by different invocations must be synchronized if at least one access is a write access. See § 16.11 Synchronization Built-in Functions.

Getting a reference to a component from a memory view to a vector
Precondition Conclusion Description
r: ref<AS,vecN<T>,AM> or
ptr<AS,vecN<T>,AM>
r.x: ref<AS,T,AM>
r.r: ref<AS,T,AM>
Compute a reference to the first component of the vector referenced by the memory view r.
The originating variable of the resulting reference is the same as the originating variable of r.
r: ref<AS,vecN<T>,AM> or
ptr<AS,vecN<T>,AM>
r.y: ref<AS,T,AM>
r.g: ref<AS,T,AM>
Compute a reference to the second component of the vector referenced by the memory view r.
The originating variable of the resulting reference is the same as the originating variable of r.
r: ref<AS,vecN<T>,AM> or
ptr<AS,vecN<T>,AM>
N is 3 or 4
r.z: ref<AS,T,AM>
r.b: ref<AS,T,AM>
Compute a reference to the third component of the vector referenced by the memory view r.
The originating variable of the resulting reference is the same as the originating variable of r.
r: ref<AS,vec4<T>,AM> or
ptr<AS,vec4<T>,AM>
r.w: ref<AS,T,AM>
r.a: ref<AS,T,AM>
Compute a reference to the fourth component of the vector referenced by the memory view r.
The originating variable of the resulting reference is the same as the originating variable of r.
r: ref<AS,vecN<T>,AM> or
ptr<AS,vecN<T>,AM>
i: i32 or u32
r[i] : ref<AS,T,AM>
Compute a reference to the ith component of the vector referenced by the memory view r.

If i is outside the range [0,N-1]:

The originating variable of the resulting reference is the same as the originating variable of r.

8.5.2. Matrix Access Expression

Column vector extraction
Precondition Conclusion Description
e: matCxR<T>
i: i32 or u32
T is concrete
e[i]: vecR<T> The result is the ith column vector of e.

If i is outside the range [0,C-1]:

e: matCxR<T>
i: i32 or u32
T is abstract
i is a const-expression
e[i]: vecR<T> The result is the ith column vector of e.

It is a shader-creation error if i is outside the range [0,C-1].

Note: When an abstract matrix value e is indexed by an expression that is not a const-expression, then the matrix is concretized before the index is applied.

Getting a reference to a column vector from a memory view to a matrix
Precondition Conclusion Description
r: ref<AS,matCxR<T>,AM> or
ptr<AS,matCxR<T>,AM>
i: i32 or u32
r[i] : ref<AS,vecR<T>,AM> Compute a reference to the ith column vector of the matrix referenced by the memory view r.

If i is outside the range [0,C-1]:

The originating variable of the resulting reference is the same as the originating variable of r.

8.5.3. Array Access Expression

Array element extraction
Precondition Conclusion Description
e: array<T,N>
i: i32 or u32
T is concrete
e[i] : T The result is the value of the ith element of the array value e.

If i is outside the range [0,N-1]:

e: array<T,N>
i: i32 or u32
T is abstract
i is a const-expression
e[i] : T The result is the value of the ith element of the array value e.

It is a shader-creation error if i is outside the range [0,N-1].

Note: When an abstract array value e is indexed by an expression that is not a const-expression, then the array is concretized before the index is applied.

Getting a reference to an array element from a memory view to an array
Precondition Conclusion Description
r: ref<AS,array<T,N>,AM> or
ptr<AS,array<T,N>,AM>
i: i32 or u32
r[i] : ref<AS,T,AM> Compute a reference to the ith element of the array referenced by the memory view r.

If i is outside the range [0,N-1]:

The originating variable of the resulting reference is the same as the originating variable of r.

r: ref<AS,array<T>,AM> or
ptr<AS,array<T>,AM>
i: i32 or u32
r[i] : ref<AS,T,AM> Compute a reference to the ith element of the runtime-sized array referenced by the memory view r.

If at runtime the array has N elements, and i is outside the range [0,N-1], then the expression evaluates to an invalid memory reference.

If i is a signed integer, and i is less than 0:

The originating variable of the resulting reference is the same as the originating variable of r.

8.5.4. Structure Access Expression

Structure member extraction
Precondition Conclusion Description
S is a structure type
M is the identifier name of a member of S, having type T
e: S
e.M: T The result is the value of the member with name M from the structure value e.
Getting a reference to a structure member from a memory view to a structure
Precondition Conclusion Description
S is a structure type
M is the identifier name of a member of S, having type T
r: ref<AS,S,AM> or
ptr<AS,S,AM>
r.M: ref<AS,T,AM> Given a memory view to a structure, the result is a reference to the structure member with identifier name M.
The originating variable of the resulting reference is the same as the originating variable of r.

8.6. Logical Expressions

Unary logical operations
Precondition Conclusion Description
e: T
T is bool or vecN<bool>
!e: T Logical negation. The result is true when e is false and false when e is true. Component-wise when T is a vector.
Binary logical expressions
Precondition Conclusion Description
e1: bool
e2: bool
e1 || e2: bool Short-circuiting "or". Yields true if either e1 or e2 are true; evaluates e2 only if e1 is false.
e1: bool
e2: bool
e1 && e2: bool Short-circuiting "and". Yields true if both e1 and e2 are true; evaluates e2 only if e1 is true.
e1: T
e2: T
T is bool or vecN<bool>
e1 | e2: T Logical "or". Component-wise when T is a vector. Evaluates both e1 and e2.
e1: T
e2: T
T is bool or vecN<bool>
e1 & e2: T Logical "and". Component-wise when T is a vector. Evaluates both e1 and e2.

8.7. Arithmetic Expressions

Unary arithmetic expressions
Precondition Conclusion Description
e: T
T is AbstractInt, AbstractFloat, i32, f32, f16, vecN<AbstractInt>, vecN<AbstractFloat>, vecN<i32>, vecN<f32>, or vecN<f16>
-e: T Negation. Component-wise when T is a vector. If T is an integer scalar type and e evaluates to the largest negative value, then the result is e.
Binary arithmetic expressions
Precondition Conclusion Description
e1 : T
e2 : T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
e1 + e2 : T Addition. Component-wise when T is a vector.

If T is a floating point type, the scalar domain is the set of all pairs of extended reals (x,y) except:

  • (−∞,+∞)

  • (+∞,−∞)

e1 : T
e2 : T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
e1 - e2 : T Subtraction Component-wise when T is a vector.

If T is a floating point type, the scalar domain is the set of all pairs of extended reals (x,y) except:

  • (−∞,−∞)

  • (+∞,+∞)

e1 : T
e2 : T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
e1 * e2 : T Multiplication. Component-wise when T is a vector.

If T is a floating point type, the scalar domain is the set of all pairs of extended reals (x,y) except:

  • (0,−∞)

  • (0,+∞)

  • (−∞, 0)

  • (+∞, 0)

e1 : T
e2 : T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
e1 / e2 : T Division. Component-wise when T is a vector.

If T is a signed integer scalar type, evaluates to:

Note: The need to ensure truncation behavior may require an implementation to perform more operations than when computing an unsigned division. Use unsigned division when both operands are known to have the same sign.

If T is an unsigned integer scalar type, evaluates to:

If T is a floating point type, the scalar domain is the set of all pairs of extended reals (x,y) except:

  • (0,0)

  • (−∞,−∞)

  • (−∞,+∞)

  • (+∞,−∞)

  • (+∞,+∞)

e1 : T
e2 : T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
e1 % e2 : T Remainder. Component-wise when T is a vector.

If T is a signed integer scalar type, evaluates e1 and e2 once, and evaluates to:

Note: When non-zero, the result has the same sign as e1.

Note: The need to ensure consistent behavior may require an implementation to perform more operations than when computing an unsigned remainder.

If T is an unsigned integer scalar type, evaluates to:

If T is a floating point type, the result is equal to:
e1 - e2 * trunc(e1 / e2).

If T is a floating point type, the scalar domain is the set of all pairs of extended reals (x,y) except:

  • Cases outside the domain of x / y:

    • (0,0)

    • (−∞,−∞)

    • (−∞,+∞)

    • (+∞,−∞)

    • (+∞,+∞)

  • Additional cases outside the domain of y * trunc(x / y):

    • y is infinite, and x is finite, implying trunc(x / y) is 0.

    • y is 0, and x is infinite, implying trunc(x / y) is infinite.

Binary arithmetic expressions with mixed scalar and vector operands
Preconditions Conclusions Semantics
S is one of AbstractInt, AbstractFloat, f32, f16, i32, u32
V is vecN<S>
es: S
ev: V
ev + es: V ev + V(es)
es + ev: V V(es) + ev
ev - es: V ev - V(es)
es - ev: V V(es) - ev
ev * es: V ev * V(es)
es * ev: V V(es) * ev
ev / es: V ev / V(es)
es / ev: V V(es) / ev
ev % es: V ev % V(es)
es % ev: V V(es) % ev
Matrix arithmetic
Preconditions Conclusions Semantics
e1, e2: matCxR<T>
T is AbstractFloat, f32, or f16
e1 + e2: matCxR<T>
Matrix addition: results are computed component-wise, column i of the result is e1[i] + e2[i]
e1 - e2: matCxR<T> Matrix subtraction: results are computed component-wise, column i of the result is e1[i] - e2[i]
m: matCxR<T>
s: T
T is AbstractFloat, f32, or f16
m * s: matCxR<T>
Component-wise scaling: (m * s)[i][j] is m[i][j] * s
s * m: matCxR<T>
Component-wise scaling: (s * m)[i][j] is m[i][j] * s
m: matCxR<T>
v: vecC<T>
T is AbstractFloat, f32, or f16
m * v: vecR<T>
Linear algebra matrix-column-vector product: Component i of the result is dot(transpose(m)[i],v)
m: matCxR<T>
v: vecR<T>
T is AbstractFloat, f32, or f16
v * m: vecC<T>
Linear algebra row-vector-matrix product:
transpose(transpose(m) * transpose(v))
e1: matKxR<T>
e2: matCxK<T>
T is AbstractFloat, f32, or f16
e1 * e2: matCxR<T>
Linear algebra matrix product.

8.8. Comparison Expressions

Comparisons
Precondition Conclusion Description
e1: T
e2: T
S is AbstractInt, AbstractFloat, bool, i32, u32, f32, or f16
T is S or vecN<S>
TB is vecN<bool> if T is a vector,
otherwise TB is bool
e1 == e2: TB Equality. Component-wise when T is a vector.
e1: T
e2: T
S is AbstractInt, AbstractFloat, bool, i32, u32, f32, or f16
T is S or vecN<S>
TB is vecN<bool> if T is a vector,
otherwise TB is bool
e1 != e2: TB Inequality. Component-wise when T is a vector.
e1: T
e2: T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
TB is vecN<bool> if T is a vector,
otherwise TB is bool
e1 < e2: TB Less than. Component-wise when T is a vector.
e1: T
e2: T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
TB is vecN<bool> if T is a vector,
otherwise TB is bool
e1 <= e2: TB Less than or equal. Component-wise when T is a vector.
e1: T
e2: T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
TB is vecN<bool> if T is a vector,
otherwise TB is bool
e1 > e2: TB Greater than. Component-wise when T is a vector.
e1: T
e2: T
S is AbstractInt, AbstractFloat, i32, u32, f32, or f16
T is S, or vecN<S>
TB is vecN<bool> if T is a vector,
otherwise TB is bool
e1 >= e2: TB Greater than or equal. Component-wise when T is a vector.

8.9. Bit Expressions

Unary bitwise operations
Precondition Conclusion Description
e: T
S is AbstractInt, i32, or u32
T is S or vecN<S>
~e : T Bitwise complement on e. Each bit in the result is the opposite of the corresponding bit in e. Component-wise when T is a vector.
Binary bitwise operations
Precondition Conclusion Description
e1: T
e2: T
S is AbstractInt, i32, or u32
T is S or vecN<S>
e1 | e2: T Bitwise-or. Component-wise when T is a vector.
e1: T
e2: T
S is AbstractInt, i32, or u32
T is S or vecN<S>
e1 & e2: T Bitwise-and. Component-wise when T is a vector.
e1: T
e2: T
S is AbstractInt, i32, or u32
T is S or vecN<S>
e1 ^ e2: T Bitwise-exclusive-or. Component-wise when T is a vector.
Bit shift expressions
Precondition Conclusion Description
e1: T
e2: TS
S is i32 or u32
T is S or vecN<S>
TS is u32 when T is S, otherwise TS is vecN<u32>
e1 << e2: T Shift left (shifted value is concrete):

Shift e1 left, inserting zero bits at the least significant positions, and discarding the most significant bits.

The number of bits to shift is the value of e2, modulo the bit width of e1.
If e2 is greater than or equal to the bit width of e1, then:

When both e1 and e2 are known before shader execution start, the result must not overflow:

Component-wise when T is a vector.

e1: T
e2: TS
T is AbstractInt or vecN<AbstractInt>
TS is u32 when T is AbstractInt, otherwise TS is vecN<u32>
e1 << e2: T Shift left (shifted value abstract):

Shift e1 left, inserting zero bits at the least significant positions, and discarding the most significant bits.

The number of bits to shift is the value of e2.

The e2+1 most significant bits of e1 must have the same bit value. Otherwise overflow would occur.

Note: This condition means all the discarded bits must be the same as the sign bit of the original value, and the same as the sign bit of the final value.

Component-wise when T is a vector.

e1: T
e2: TS
S is i32 or u32
T is S or vecN<S>
TS is u32 when T is S, otherwise TS is vecN<u32>
e1 >> e2: T Shift right (shifted value is concrete).

Shift e1 right, discarding the least significant bits.

If S is an unsigned type, insert zero bits at the most significant positions.

If S is a signed type:

  • If e1 is negative, each inserted bit is 1, and so the result is also negative.

  • Otherwise, each inserted bit is 0.

The number of bits to shift is the value of e2, modulo the bit width of e1.

If e2 is greater than or equal to the bit width or e1, then:

Component-wise when T is a vector.

e1: T
e2: TS
T is AbstractInt or vecN<AbstractInt>
TS is u32 when T is AbstractInt, otherwise TS is vecN<u32>
e1 >> e2: T Shift right (abstract).

Shift e1 right, discarding the least significant bits.

If e1 is negative, each inserted bit is 1, and so the result is also negative. Otherwise, each inserted bit is 0.

The number of bits to shift is the value of e2.

Component-wise when T is a vector.

8.10. Function Call Expression

A function call expression executes a function call where the called function has a return type. If the called function does not return a value, a function call statement should be used instead. See § 9.5 Function Call Statement.

8.11. Variable Identifier Expression

Getting a reference from a variable name
Precondition Conclusion Description
v is an identifier resolving to an in-scope variable declared in address space AS with store type T and access mode AM v: ref<AS,T,AM> Result is a reference to the memory for the named variable v.

8.12. Formal Parameter Expression

Getting the value of an identifier declared as a formal parameter to a function
Precondition Conclusion Description
a is an identifier resolving to an in-scope formal parameter declaration with type T a: T Result is the value supplied for the corresponding function call operand at the call site invoking this instance of the function.

8.13. Address-Of Expression

The address-of operator converts a reference to its corresponding pointer.

Getting a pointer from a reference
Precondition Conclusion Description
r: ref<AS,T,AM> &r: ptr<AS,T,AM> Result is the pointer value corresponding to the same memory view as the reference value r.

If r is an invalid memory reference, then the resulting pointer is also an invalid memory reference.

It is a shader-creation error if AS is the handle address space.

It is a shader-creation error if r is a reference to a vector component.

8.14. Indirection Expression

The indirection operator converts a pointer to its corresponding reference.

Getting a reference from a pointer
Precondition Conclusion Description
p: ptr<AS,T,AM> *p: ref<AS,T,AM> Result is the reference value corresponding to the same memory view as the pointer value p.

If p is an invalid memory reference, then the resulting reference is also an invalid memory reference.

8.15. Identifier Expressions for Value Declarations

Getting the value of a const-, override-, or let-declared identifiers
Precondition Conclusion Description
c is an identifier resolving to an in-scope const-declaration with type T c: T Result is the value computed for the initializer expression. The expression is a const-expression, and is evaluated at shader-creation time.
c is an identifier resolving to an in-scope override-declaration with type T c: T If pipeline creation specified a value for the constant ID, then the result is that value. This value may be different for different pipeline instances.

Otherwise, the result is the value computed for the initializer expression. Pipeline-overridable constants appear at module-scope, so evaluation occurs before the shader begins execution.

Note: Pipeline creation fails if no initial value was specified in the API call and the let-declaration has no initializer expression.

c is an identifier resolving to an in-scope let-declaration with type T c: T Result is the value computed for the initializer expression. A let-declaration appears inside a function body, and its initializer is evaluated each time control flow reaches the declaration.

8.16. Enumeration Expressions

Enumeration expressions
Precondition Conclusion Description
e is an identifier resolving to a predeclared enumerant belonging to enumeration type E e : E See § 6.3.1 Predeclared enumerants

8.17. Type Expressions

Type expressions
Precondition Conclusion Description
t is an identifier resolving to a predeclared type t : AllTypes See § 6.9 Predeclared Types and Type-Generators Summary
a is an identifier resolving to a type alias. a : AllTypes Additionally, a denotes the type to which it is aliased.
s is an identifier resolving to the declaration of a structure type. s : AllTypes Additionally, s denotes the structure type.
tg is an identifier resolving to a type-generator

e1: T1
...
eN: TN

tg _template_args_start
e1,
...,
eN
_template_args_end
: AllTypes
Each type-generator has its own requirements on the template parameters it requires and accepts, and defines how the template parameters help determine the resulting type.

The expressions e1 through eN are the template parameters for the type-generator.

For example, the type expression vec2<f32> is the vector of two f32 elements.

See § 6.9 Predeclared Types and Type-Generators Summary for the list of predeclared type-generators.

Note: The two variants here differ only in whether they have a trailing comma after eN.

tg _template_args_start
e1,
...,
eN,
_template_args_end
: AllTypes

8.18. Expression Grammar Summary

When an identifier is the first token in a call_phrase, it is one of:

Declaration and scope rules ensure those names are always distinct.

primary_expression :

template_elaborated_ident

| call_expression

| literal

| paren_expression

call_expression :

call_phrase

Note: The call_expression rule exists to ensure type checking applies to the call expression.

call_phrase :

template_elaborated_ident argument_expression_list

paren_expression :

'(' expression ')'

argument_expression_list :

'(' expression_comma_list ? ')'

expression_comma_list :

expression ( ',' expression ) * ',' ?

component_or_swizzle_specifier :

'[' expression ']' component_or_swizzle_specifier ?

| '.' member_ident component_or_swizzle_specifier ?

| '.' swizzle_name component_or_swizzle_specifier ?

unary_expression :

singular_expression

| '-' unary_expression

| '!' unary_expression

| '~' unary_expression

| '*' unary_expression

| '&' unary_expression

singular_expression :

primary_expression component_or_swizzle_specifier ?

lhs_expression :

core_lhs_expression component_or_swizzle_specifier ?

| '*' lhs_expression

| '&' lhs_expression

core_lhs_expression :

ident _disambiguate_template

| '(' lhs_expression ')'

multiplicative_expression :

unary_expression

| multiplicative_expression multiplicative_operator unary_expression

multiplicative_operator :

'*'

| '/'

| '%'

additive_expression :

multiplicative_expression

| additive_expression additive_operator multiplicative_expression

additive_operator :

'+'

| '-'

shift_expression :

additive_expression

| unary_expression _shift_left unary_expression

| unary_expression _shift_right unary_expression

relational_expression :

shift_expression

| shift_expression _less_than shift_expression

| shift_expression _greater_than shift_expression

| shift_expression _less_than_equal shift_expression

| shift_expression _greater_than_equal shift_expression

| shift_expression '==' shift_expression

| shift_expression '!=' shift_expression

short_circuit_and_expression :

relational_expression

| short_circuit_and_expression '&&' relational_expression

short_circuit_or_expression :

relational_expression

| short_circuit_or_expression '||' relational_expression

binary_or_expression :

unary_expression

| binary_or_expression '|' unary_expression

binary_and_expression :

unary_expression

| binary_and_expression '&' unary_expression

binary_xor_expression :

unary_expression

| binary_xor_expression '^' unary_expression

bitwise_expression :

binary_and_expression '&' unary_expression

| binary_or_expression '|' unary_expression

| binary_xor_expression '^' unary_expression

expression :

relational_expression

| short_circuit_or_expression '||' relational_expression

| short_circuit_and_expression '&&' relational_expression

| bitwise_expression

8.19. Operator Precedence and Associativity

This entire subsection is non-normative.

Operator precedence and associativity in right-hand side WGSL expressions emerge from their grammar in summary. Right-hand expressions group operators to organize them, as illustrated by the following diagram:

Operator precedence and associativity graph

To promote readability through verbosity, the following groups do not associate with other groups:

And the following groups do not associate with themselves:

Associating both group sections above requires parentheses to set the relationship explicitly. The following exemplifies where these rules render expressions invalid in comments:

EXAMPLE: Operator precedence corner cases
let a = x & (y ^ (z | w)); // Invalid: x & y ^ z | w
let b = (x + y) << (z >= w); // Invalid: x + y << z >= w
let c = x < (y > z); // Invalid: x < y > z
let d = x && (y || z); // Invalid: x && y || z

Emergent precedence controls the implicit parentheses of an expression, where the stronger binding operator will act as if it is surrounded by parentheses when together with operators of weaker precedence. For example, stronger binding multiplicative operators than additive will infer (a + (b * c)) from a + b * c expression. Similarly, the emergent associativity controls the direction of these implicit parentheses. For example, a left-to-right association will infer ((a + b) + c) from a + b + c expression, whereas a right-to-left association will infer (* (* a)) from * * a expression.

The following table summarizes operator precedence, associativity, and binding, sorting by starting with strongest to weakest. The binding column contains the stronger expression of the given operator, meaning, for example, if "All above" is the value, then this operator can include any of the stronger expressions. But, for example, if "Unary" is the value, then anything weaker than unary but stronger than the operator at row would require parentheses to bind with this operator. This column is necessary for linearly listing operators.

Operator precedence, associativity, and binding for right-hand side expressions, sorted from strong to weak
Name Operators Associativity Binding
Parenthesized (...)
Primary a(), a[], a.b Left-to-right
Unary -a, !a, ~a, *a, &a Right-to-left All above
Multiplicative a*b, a/b, a%b Left-to-right All above
Additive a+b, a-b Left-to-right All above
Shift a<<b, a>>b Requires parentheses Unary
Relational a<b, a>b, a<=b, a>=b, a==b, a!=b Requires parentheses All above
Binary AND a&b Left-to-right Unary
Binary XOR a^b Left-to-right Unary
Binary OR a|b Left-to-right Unary
Short-circuit AND a&&b Left-to-right Relational
Short-circuit OR a||b Left-to-right Relational

9. Statements

A statement is a program fragment that controls execution. Statements are generally executed in sequential order; however, control flow statements may cause a program to execute in non-sequential order.

9.1. Compound Statement

A compound statement is a brace-enclosed sequence of zero or more statements. When a declaration is one of those statements, its identifier is in scope from the start of the next statement until the end of the compound statement.

compound_statement :

attribute * '{' statement * '}'

The continuing_compound_statement is a special form of compound statement that forms the body of a continuing statement, and allows an optional break-if statement at the end.

9.2. Assignment Statement

An assignment evaluates an expression, and optionally stores it in memory (thus updating the contents of a variable).

assignment_statement :

lhs_expression ( '=' | compound_assignment_operator ) expression

| '_' '=' expression

The text to the left of the operator token is the left-hand side, and the expression to the right of the operator token is the right-hand side.

9.2.1. Simple Assignment

An assignment is a simple assignment when the left-hand side is an expression, and the operator is the equal ('=') token. In this case the value of the right-hand side is written to the memory referenced by the left-hand side.

Precondition Statement Description
e: T,
T is a concrete constructible type,
r: ref<AS,T,AM>,
AS is a writable address space,
access mode AM is write or read_write
r = e Evaluates r, then evaluates e, then writes the value computed for e into the memory locations referenced by r.

Note: If the reference is an invalid memory reference, the write may not execute, or may write to a different memory location than expected.

In the simplest case, the left hand side is the name of a variable. See § 6.4.8 Forming Reference and Pointer Values for other cases.

EXAMPLE: Assignments
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 sibling: S;
    // Copy the contents of the 'person' variable into the 'sibling' variable.
    sibling = person;
}

9.2.2. Phony Assignment

An assignment is a phony assignment when the left-hand side is the underscore ('_') token. In this case the right-hand side is evaluated, and then ignored.

Precondition Statement Description
e: T,
T is constructible, a pointer type, a texture type, or a sampler type
_ = e Evaluates e.

Note: The resulting value is not stored. The _ token is not an identifier, and therefore cannot be used in an expression.

A phony-assignment is useful for:

EXAMPLE: Using phony-assignment to throw away an un-needed function result
var<private> counter: i32;

fn increment_and_yield_previous() -> i32 {
  let previous = counter;
  counter = counter + 1;
  return previous;
}

fn user() {
  // Increment the counter, but don't use the result.
  _ = increment_and_yield_previous();
}
EXAMPLE: Using phony-assignment to occupy bindings without using them
struct BufferContents {
    counter: atomic<u32>,
    data: array<vec4<f32>>
}
@group(0) @binding(0) var<storage> buf: BufferContents;
@group(0) @binding(1) var t: texture_2d<f32>;
@group(0) @binding(2) var s: sampler;

@fragment
fn shade_it() -> @location(0) vec4<f32> {
  // Declare that buf, t, and s are part of the shader interface, without
  // using them for anything.
  _ = &buf;
  _ = t;
  _ = s;
  return vec4<f32>();
}

9.2.3. Compound Assignment

An assignment is a compound assignment when the left-hand side is an expression, and the operator is one of the compound_assignment_operators.

compound_assignment_operator :

'+='

| '-='

| '*='

| '/='

| '%='

| '&='

| '|='

| '^='

| _shift_right_assign

| _shift_left_assign

The type requirements, semantics, and behavior of each statement is defined as if the compound assignment expands as in the following table, except that:

Statement Expansion
e1 += e2 e1 = e1 + (e2)
e1 -= e2 e1 = e1 - (e2)
e1 *= e2 e1 = e1 * (e2)
e1 /= e2 e1 = e1 / (e2)
e1 %= e2 e1 = e1 % (e2)
e1 &= e2 e1 = e1 & (e2)
e1 |= e2 e1 = e1 | (e2)
e1 ^= e2 e1 = e1 ^ (e2)
e1 >>= e2 e1 = e1 >> (e2)
e1 <<= e2 e1 = e1 << (e2)

Note: The syntax does not allow a compound assignment to also be a phony assignment.

Note: Even though the reference e1 is evaluated once, its underlying memory is accessed twice: first a read access gets the old value, and then a write access stores the updated value.

EXAMPLE: Compound assignment
var<private> next_item: i32 = 0;

fn advance_item() -> i32 {
   next_item += 1;   // Adds 1 to next_item.
   return next_item - 1;
}

fn bump_item() {
  var data: array<f32,10>;
  next_item = 0;
  // Adds 5.0 to data[0], calling advance_item() only once.
  data[advance_item()] += 5.0;
  // next_item will be 1 here.
}

fn precedence_example() {
  var value = 1;
  // The right-hand side of a compound assignment is its own expression.
  value *= 2 + 3; // Same as value = value * (2 + 3);
  // 'value' now holds 5.
}
Note: A compound assignment can rewritten as different WGSL code that uses a simple assignment instead. The idea is to use a pointer to hold the result of evaluating the reference once.

For example, when e1 is not a reference to a component inside a vector, then

e1+=e2;
can be rewritten as
{ let p = &(e1); *p = *p + (e2); }
where the identifier p is chosen to be different from all other identifiers in the program.

When e1 is a reference to a component inside a vector, the above technique needs to be modified because WGSL does not allow taking the address in that case. For example, if ev is a reference to a vector, the statement

ev[c] += e2;
can be rewritten as
{ let p = &(ev); let c0 = c; (*p)[c0] = (*p)[c0] + (e2); }
where identifiers c0 and p are chosen to be different from all other identifiers in the program.

9.3. Increment and Decrement Statements

An increment statement adds 1 to the contents of a variable. A decrement statement subtracts 1 from the contents of a variable.

increment_statement :

lhs_expression '++'

decrement_statement :

lhs_expression '--'

The expression must evaluate to a reference with a concrete integer scalar store type and read_write access mode.

Precondition Statement Description
r : ref<AS,T,read_write>,
T is a concrete integer scalar
r++ Adds 1 to the contents of memory referenced by r.
Same as r += T(1)
r : ref<AS,T,read_write>,
T is a concrete integer scalar
r-- Subtracts 1 from the contents of memory referenced by r.
Same as r -= T(1)
EXAMPLE: Increment and decrement
fn f() {
    var a: i32 = 20;
    a++;
    // Now a contains 21
    a--;
    // Now a contains 20
}

9.4. Control Flow

Control flow statements may cause the program to execute in non-sequential order.

9.4.1. If Statement

An if statement conditionally executes at most one compound statement based on the evaluation of condition expressions.

An if statement has an if clause, followed by zero or more else if clauses, followed by an optional else clause.

if_statement :

attribute * if_clause else_if_clause * else_clause ?

if_clause :

'if' expression compound_statement

else_if_clause :

'else' 'if' expression compound_statement

else_clause :

'else' compound_statement

Type rule precondition: The expression in each if and else if clause must be of bool type.

An if statement is executed as follows:

9.4.2. Switch Statement

A switch statement transfers control to one of a set of case clauses, or to the default clause, depending on the evaluation of a selector expression.

switch_statement :

attribute * 'switch' expression switch_body

switch_body :

attribute * '{' switch_clause + '}'

switch_clause :

case_clause

| default_alone_clause

case_clause :

'case' case_selectors ':' ? compound_statement

default_alone_clause :

'default' ':' ? compound_statement

case_selectors :

case_selector ( ',' case_selector ) * ',' ?

case_selector :

'default'

| expression

A case clause is the 'case' token followed by a comma-separated list of case selectors and a body in the form of a compound statement.

A default-alone clause is the 'default' token followed by a body in the form of a compound statement.

A default clause is either:

Each switch statement must have exactly one default clause.

The 'default' token must not appear more than once in a single case_selector list.

Type rule precondition: For a single switch statement, the selector expression and all case selector expressions must be of the same concrete integer scalar type.

The expressions in the case_selectors must be const-expressions.

Two different case selector expressions in the same switch statement must not have the same value.

If the selector value equals the value of an expression in a case_selector list, then control is transferred to the body of that case clause. If the selector value does not equal any of the case selector values, then control is transferred to the body of the default clause.

When control reaches the end of the body of a clause, control transfers to the first statement after the switch statement.

When one of the statements in the body of a clause is a declaration, it follows the normal scope and lifetime rules of a declaration in a compound statement. That is, the body is a sequence of statements, and if one of those is a declaration then the scope of that declaration extends from the start of the next statement in the sequence until the end of the body. The declaration executes when it is reached, creating a new instance of the variable or value, and initializes it.

EXAMPLE: WGSL Switch
var a : i32;
let x : i32 = generateValue();
switch x {
  case 0: {      // The colon is optional
    a = 1;
  }
  default {      // The default need not appear last
    a = 2;
  }
  case 1, 2, {   // Multiple selector values can be used
    a = 3;
  }
  case 3, {      // The trailing comma is optional
    a = 4;
  }
  case 4 {
    a = 5;
  }
}
EXAMPLE: WGSL Switch with default combined
const c = 2;
var a : i32;
let x : i32 = generateValue();
switch x {
  case 0: {
    a = 1;
  }
  case 1, c {       // Const-expression can be used in case selectors
    a = 3;
  }
  case 3, default { // The default keyword can be used with other clauses
    a = 4;
  }
}

9.4.3. Loop Statement

loop_statement :

attribute * 'loop' attribute * '{' statement * continuing_statement ? '}'

A loop statement repeatedly executes a loop body; the loop body is specified as a compound statement. Each execution of the loop body is called an iteration.

This repetition can be interrupted by a break, or return statement.

Optionally, the last statement in the loop body may be a continuing statement.

A dynamic error occurs if the loop would execute an unbounded number of iterations. This may result in early termination of the loop, other non-local effects, or even device loss.

When one of the statements in the loop body is a declaration, it follows the normal scope and lifetime rules of a declaration in a compound statement. That is, the loop body is a sequence of statements, and if one of those is a declaration then the scope of that declaration extends from the start of the next statement in the sequence until the end of the loop body. The declaration executes each time it is reached, so each new iteration creates a new instance of the variable or value, and re-initializes it.

Note: The loop statement is a specialized construct, you probably want the for or while statements. The loop statement is one of the biggest differences from other shader languages.

This design directly expresses loop idioms commonly found in compiled code. In particular, placing the loop update statements at the end of the loop body allows them to naturally use values defined in the loop body.

EXAMPLE: for loop
var a: i32 = 2;
for (var i: i32 = 0; i < 4; i++) {
  a *= 2;
}
EXAMPLE: loop
var a: i32 = 2;
var i: i32 = 0;      // <1>
loop {
  if i >= 4 { break; }

  a = a * 2;

  i++;
}
EXAMPLE: for loop with continue
var a: i32 = 2;
let step: i32 = 1;
for (var i: i32 = 0; i < 4; i += step) {
  if (i % 2 == 0) { continue; }
  a *= 2;
}
EXAMPLE: loop with continue
var a: i32 = 2;
var i: i32 = 0;
loop {
  if i >= 4 { break; }

  let step: i32 = 1;

  i = i + step;
  if i % 2 == 0 { continue; }

  a = a * 2;
}
EXAMPLE: loop with continue and continuing
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;
  }
}

9.4.4. For Statement

for_statement :

attribute * 'for' '(' for_header ')' compound_statement

for_header :

for_init ? ';' expression ? ';' for_update ?

for_init :

variable_or_value_statement

| variable_updating_statement

| func_call_statement

for_update :

variable_updating_statement

| func_call_statement

The for statement takes the form for (initializer; condition; update_part) { body } and is syntactic sugar on top of a loop statement with the same body. Additionally:

The initializer of a for loop is executed once prior to executing the loop. When a declaration appears in the initializer, its identifier is in scope until the end of the body. Unlike declarations in the body, the declaration is not re-initialized each iteration.

The condition, body and update_part execute in that order to form a loop iteration. The body is a special form of compound statement. The identifier of a declaration in the body is in scope from the start of the next statement until the end of the body. The declaration is executed each time it is reached, so each new iteration creates a new instance of the variable or constant, and re-initializes it.

EXAMPLE: For to Loop transformation: before
var a: i32 = 2;
for (var i: i32 = 0; i < 4; i++) {
  if a == 0 {
    continue;
  }
  a = a + 2;
}

Converts to:

EXAMPLE: For to Loop transformation: after
var a: i32 = 2;
{ // Introduce new scope for loop variable i
  var i: i32 = 0;
  loop {
    if !(i < 4) {
      break;
    }

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

    continuing {
      i++;
    }
  }
}

A dynamic error occurs if the for loop would execute an unbounded number of iterations. This may result in early termination of the loop, other non-local effects, or even device loss.

9.4.5. While Statement

while_statement :

attribute * 'while' expression compound_statement

The while statement is a kind of loop parameterized by a condition. At the start of each loop iteration, a boolean condition is evaluated. If the condition is false, the while loop ends execution. Otherwise, the rest of the iteration is executed.

Type rule precondition: The condition must be of bool type.

A while loop can be viewed as syntactic sugar over either a loop or for statement. The following statement forms are equivalent:

A dynamic error occurs if the while loop would execute an unbounded number of iterations. This may result in early termination of the loop, other non-local effects, or even device loss.

9.4.6. Break Statement

break_statement :

'break'

A break statement transfers control to immediately after the body of the nearest-enclosing loop or switch statement, thus ending execution of the loop or switch statement.

A break statement must only be used within loop, for, while, and switch statements.

A break statement must not be placed such that it would exit from a loop’s continuing statement. Use a break-if statement instead.

EXAMPLE: WGSL Invalid loop break from a continuing clause
var a: i32 = 2;
var i: i32 = 0;
loop {
  let step: i32 = 1;

  if i % 2 == 0 { continue; }

  a = a * 2;

  continuing {
    i = i + step;
    if i >= 4 { break; } // Invalid.  Use break-if instead.
  }
}

9.4.7. Break-If Statement

break_if_statement :

'break' 'if' expression ';'

A break-if statement evaluates a boolean condition; If the condition is true, control is transferred to immediately after the body of the nearest-enclosing loop statement, ending execution of that loop.

Type rule precondition: The condition must be of bool type.

Note: A break-if statement may only appear as the last statement in the body of a continuing statement.

EXAMPLE: WGSL Valid loop break-if from a continuing clause
var a: i32 = 2;
var i: i32 = 0;
loop {
  let step: i32 = 1;

  if i % 2 == 0 { continue; }

  a = a * 2;

  continuing {
    i = i + step;
    break if i >= 4;
  }
}

9.4.8. Continue Statement

continue_statement :

'continue'

A continue statement transfers control in the nearest-enclosing loop:

A continue statement must only be used in a loop, for or while statement. A continue statement must not be placed such that it would transfer control to an enclosing continuing statement. (It is a forward branch when branching to a continuing statement.)

A continue statement must not be placed such that it would transfer control past a declaration used in the targeted continuing statement.

Note: A continue can only be used in a continuing statement if it is used for transferring control flow within another loop nested in the continuing statement. That is, a continue cannot be used to transfer control to the start of the currently executing continuing statement.

EXAMPLE: Invalid continue bypasses declaration
var i: i32 = 0;
loop {
  if i >= 4 { break; }
  if i % 2 == 0 { continue; } // <3>

  let step: i32 = 2;

  continuing {
    i = i + step;
  }
}

9.4.9. Continuing Statement

continuing_statement :

'continuing' continuing_compound_statement

continuing_compound_statement :

attribute * '{' statement * break_if_statement ? '}'

A continuing statement specifies a compound statement to be executed at the end of a loop iteration. The construct is optional.

The compound statement must not contain a return at any compound statement nesting level.

9.4.10. Return Statement

return_statement :

'return' expression ?

A return statement ends execution of the current function. If the function is an entry point, then the current shader invocation is terminated. Otherwise, evaluation continues with the next expression or statement after the evaluation of the call site of the current function invocation.

If the function does not have a return type, then the return statement is optional. If the return statement is provided for such a function, it must not supply a value. Otherwise the expression must be present, and is called the return value. In this case the call site of this function invocation evaluates to the return value. The type of the return value must match the return type of the function.

9.4.11. Discard Statement

A discard statement converts the invocation into a helper invocation and throws away the fragment. The discard statement must only be used in a fragment shader stage.

More precisely, executing a discard statement will:

Only statements executed prior to the discard statement will have observable effects.

Note: A discard statement may be executed by any function in a fragment stage and the effect is the same: the fragment will be thrown away.

EXAMPLE: Using the discard statement to throw away a fragment
@group(0) @binding(0)
var<storage, read_write> will_emit_color : u32;

fn discard_if_shallow(pos: vec4<f32>) {
  if pos.z < 0.001 {
    // If this is executed, then the will_emit_color variable will
    // never be set to 1 because helper invocations will not write
    // to shared memory.
    discard;
  }
  will_emit_color = 1;
}

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

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

9.5. Function Call Statement

func_call_statement :

call_phrase

A function call statement executes a function call.

A shader-creation error results if the called function has the must_use attribute.

Note: If the function returns a value, and the function does not have the must_use attribute, that value is ignored.

9.6. Const Assertion Statement

A const assertion statement produces a shader-creation error if the expression evaluates to false. The expression must be a const-expression. The statement can satisfy static access conditions in a shader, but otherwise has no effect on the compiled shader. This statement can be used at module scope and within functions.

Type rule precondition: The expression must be of bool type.

const_assert_statement :

'const_assert' expression

EXAMPLE: Static assertion examples
const x = 1;
const y = 2;
const_assert x < y; // valid at module-scope.
const_assert(y != 0); // parentheses are optional.

fn foo() {
  const z = x + y - 2;
  const_assert z > 0; // valid in functions.
  let a  = 3;
  const_assert a != 0; // invalid, the expression must be a const-expression.
}

9.7. Statements Grammar Summary

The statement rule matches statements that can be used in most places inside a function body.

statement :

';'

| return_statement ';'

| if_statement

| switch_statement

| loop_statement

| for_statement

| while_statement

| func_call_statement ';'

| variable_or_value_statement ';'

| break_statement ';'

| continue_statement ';'

| 'discard' ';'

| variable_updating_statement ';'

| compound_statement

| const_assert_statement ';'

variable_updating_statement :

assignment_statement

| increment_statement

| decrement_statement

Additionally, certain statements may only be used in very specific contexts:

9.8. Statements Behavior Analysis

9.8.1. Rules

Some statements affecting control-flow are only valid in some contexts. For example, continue is invalid outside of a loop, for, or while. Additionally, the uniformity analysis (see § 14.2 Uniformity) needs to know when control flow can exit a statement in multiple different ways.

Both goals are achieved by a system for summarizing execution behaviors of statements. Behavior analysis maps each statement to the set of possible ways execution proceeds after evaluation of the statement completes. As with type analysis for values and expressions, behavior analysis proceeds bottom up: first determine behaviors for certain basic statements, and then determine behavior for higher level constructs by applying combining rules.

A behavior is a set, whose elements may be:

Each of those correspond to a way to exit a compound statement: either through a keyword, or by falling to the next statement ("Next").

We note "s: B" to say that s respects the rules regarding behaviors, and has behavior B.

For each function:

We assign a behavior to each function: it is its body’s behavior (treating the body as a regular statement), with any "Return" replaced by "Next". As a consequence of the rules above, a function behavior is always one of {}, or {Next}.

Behavior analysis must be able to determine a non-empty behavior for each statement, and function.

Rules for analyzing and validating the behaviors of statements
Statement Preconditions Resulting behavior
empty statement {Next}
{s} s: B B
s1 s2

Note: s1 often ends in a semicolon.

s1: B1
Next in B1
s2: B2
(B1∖{Next}) ∪ B2
s1: B1
Next not in B1
s2: B2
B1
var x:T; {Next}
let x = e; {Next}
var x = e; {Next}
x = e; {Next}
_ = e; {Next}
f(e1, ..., en); f has behavior B B
return; {Return}
return e; {Return}
discard; {Next}
break; {Break}
break if e; {Break, Next}
continue; {Continue}
const_assert e; {Next}
if e s1 else s2 s1: B1
s2: B2
B1B2
loop {s1 continuing {s2}} s1: B1
s2: B2
None of {Continue, Return} are in B2
Break is not in (B1B2)
(B1B2)∖{Continue, Next}
s1: B1
s2: B2
None of {Continue, Return} are in B2
Break is in (B1B2)
(B1B2 ∪ {Next})∖{Break, Continue}
switch e {case c1: s1 ... case cn: sn} s1: B1
...
sn: Bn
Break is not in (B1 ∪ ... ∪ Bn)
B1 ∪ ... ∪ Bn
s1: B1
...
sn: Bn
Break is in (B1 ∪ ... ∪ Bn)
(B1 ∪ ... ∪ Bn ∪ {Next})∖Break

Note: ∪ is a set union operation and ∖ is a set difference operation.

Note: The empty statement case occurs when a loop has an empty body, or when a for loop lacks an initialization or update statement.

For the purpose of this analysis:

Each built-in function has a behavior of {Next}. And each operator application not listed in the table above has the same behavior as if it were a function call with the same operands and with a function’s behavior of {Next}.

The behavior of a function must satisfy the rules given above.

Note: It is unnecessary to analyze the behavior of expressions because they will always be {Next} or a previously analyzed function will have produced a error.

9.8.2. Notes

This section is informative, non-normative.

Behavior analysis can cause a program to be rejected in the following ways (restating requirements from above):

This analysis can be run in linear time, by analyzing the call-graph bottom-up (since the behavior of a function call can depend on the function’s code).

9.8.3. Examples

Here are some examples showing this analysis in action:

EXAMPLE: Trivially dead code is allowed
fn simple() -> i32 {
  var a: i32;
  return 0;  // Behavior: {Return}
  a = 1;     // Valid, statically unreachable code.
             //   Statement behavior: {Next}
             //   Overall behavior (due to sequential statements): {Return}
  return 2;  // Valid, statically unreachable code. Behavior: {Return}
} // Function behavior: {Return}
EXAMPLE: Compound statements are supported
fn nested() -> i32 {
  var a: i32;
  {             // The start of a compound statement.
    a = 2;      // Behavior: {Next}
    return 1;   // Behavior: {Return}
  }             // The compound statement as a whole has behavior {Return}
  a = 1;        // Valid, statically unreachable code.
                //   Statement behavior: {Next}
                //   Overall behavior (due to sequential statements): {Return}
  return 2;     // Valid, statically unreachable code. Behavior: {Return}
}
EXAMPLE: if/then behaves as if there is an empty else
fn if_example() {
  var a: i32 = 0;
  loop {
    if a == 5 {
      break;      // Behavior: {Break}
    }             // Behavior of the whole if compound statement: {Break, Next},
                  //   as the if has an implicit empty else
    a = a + 1;    // Valid, as the previous statement had "Next" in its behavior
  }
}
EXAMPLE: if/then/else has the behavior of both sides
fn if_example() {
  var a: i32 = 0;
  loop {
    if a == 5 {
      break;      // Behavior: {Break}
    } else {
      continue;   // Behavior: {Continue}
    }             // Behavior of the whole if compound statement: {Break, Continue}
    a = a + 1;    // Valid, statically unreachable code.
                  //   Statement behavior: {Next}
                  //   Overall behavior: {Break, Continue}
  }
}
EXAMPLE: if/else if/else behaves like a nested if/else
fn if_example() {
  var a: i32 = 0;
  loop {
    // if e1 s1 else if e2 s2 else s3
    // is identical to
    // if e1 else { if e2 s2 else s3 }
    if a == 5 {
      break;      // Behavior: {Break}
    } else if a == 42 {
      continue;   // Behavior: {Continue}
    } else {
      return;     // Behavior {Return}
    }             // Behavior of the whole if compound statement:
                  //   {Break, Continue, Return}
  }               // Behavior of the whole loop compound statement {Next, Return}
}                 // Behavior of the whole function {Next}
EXAMPLE: Break in switch becomes Next
fn switch_example() {
  var a: i32 = 0;
  switch a {
    default: {
      break;   // Behavior: {Break}
    }
  }            // Behavior: {Next}, as switch replaces Break by Next
  a = 5;       // Valid, as the previous statement had Next in its behavior
}
EXAMPLE: Obviously infinite loops
fn invalid_infinite_loop() {
  loop { }     // Behavior: { }.  Invalid because it's empty.
}
EXAMPLE: Discard will not terminate a loop
fn invalid_infinite_loop() {
  loop {
    discard; // Behavior { Next }.
  }          // Invalid, behavior of the whole loop is { }.
}
EXAMPLE: A conditional continue with continuing statement
fn conditional_continue() {
  var a: i32;
  loop {
    if a == 5 { break; } // Behavior: {Break, Next}
    if a % 2 == 1 {      // Valid, as the previous statement has Next in its behavior
      continue;          // Behavior: {Continue}
    }                    // Behavior: {Continue, Next}
    a = a * 2;           // Valid, as the previous statement has Next in its behavior
    continuing {         // Valid as the continuing statement has behavior {Next}
                         //  which does not include any of:
                         //  {Break, Continue, Return}
      a = a + 1;
    }
  }                      // The loop as a whole has behavior {Next},
                         //  as it absorbs "Continue" and "Next",
                         //  then replaces "Break" with "Next"
}
EXAMPLE: A redundant continue with continuing statement
fn redundant_continue_with_continuing() {
  var a: i32;
  loop {
    if a == 5 { break; }
    continue;   // Valid. This is redundant, branching to the next statement.
    continuing {
      a = a + 1;
    }
  }
}
EXAMPLE: A continue at the end of a loop body
fn continue_end_of_loop_body() {
  for (var i: i32 = 0; i < 5; i++ ) {
    continue;   // Valid. This is redundant,
                //   branching to the end of the loop body.
  }             // Behavior: {Next},
                //   as loops absorb "Continue",
                //   and "for" loops always add "Next"
}
for loops desugar to loop with a conditional break. As shown in a previous example, the conditional break has behavior {Break, Next}, which leads to adding "Next" to the loop’s behavior.
EXAMPLE: return required in functions that have a return type
fn missing_return () -> i32 {
  var a: i32 = 0;
  if a == 42 {
    return a;       // Behavior: {Return}
  }                 // Behavior: {Next, Return}
}                   // Error: Next is invalid in the body of a
                    //   function with a return type
EXAMPLE: continue must be in a loop
fn continue_out_of_loop () {
  var a: i32 = 0;
  if a > 0  {
    continue;       // Behavior: {Continue}
  }                 // Behavior: {Next, Continue}
}                   // Error: Continue is invalid in the body of a function
The same example would also be invalid for the same reason if continue was replaced by break.

10. Functions

A function performs computational work when invoked.

A function is invoked in one of the following ways:

Functions in WGSL may be defined in any order, including later in the source than they are used. Because of this, function prototypes or forward declarations are not needed, and there is no way to do so.

There are two kinds of functions:

10.1. Declaring a User-defined Function

A function declaration creates a user-defined function, by specifying:

A function declaration must only occur at module scope. A function name is in scope for the entire program.

Note: Each user-defined function only has one overload.

A formal parameter declaration specifies an identifier name and a type for a value that must be provided when invoking the function. A formal parameter may have attributes. See § 10.2 Function Calls. The scope of the identifier is the function body. Two formal parameters for a given function must not have the same name.

Note: Some built-in functions may allow parameters to be abstract numeric types; however, this functionality is not currently supported for user-declared functions.

The return type, if specified, must be constructible.

WGSL defines the following attributes that can be applied to function declarations:

WGSL defines the following attributes that can be applied to function parameters and return types:

function_decl :

attribute * function_header compound_statement

function_header :

'fn' ident '(' param_list ? ')' ( '->' attribute * template_elaborated_ident ) ?

param_list :

param ( ',' param ) * ',' ?

param :

attribute * ident ':' type_specifier

EXAMPLE: Simple functions
// Declare the add_two function.
// It has two formal parameters, 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 add_two function, and captures
// the resulting value in the named value 'six'.
@compute @workgroup_size(1)
fn main() {
   let six: i32 = add_two(4, 5.0);
}

10.2. Function Calls

A function call is a statement or expression which invokes a function.

The function containing the function call is the calling function, or caller. The function being invoked is the called function, or callee.

The function call:

The function call must supply the same number of argument values as there are formal parameters in the called function. Each argument value must evaluate to the same type as the corresponding formal parameter, by position.

In summary, when calling a function:

  1. Execution of the calling function is suspended.

  2. The called function executes until it returns.

  3. Execution of the calling function resumes.

A called function returns as follows:

In detail, when a function call is executed the following steps occur:

  1. Function call argument values are evaluated. The relative order of evaluation is left-to-right.

  2. Execution of the calling function is suspended. All function scope variables and constants maintain their current values.

  3. If the called function is user-defined, memory is allocated for each function scope variable in the called function.

  4. Values for the formal parameters of the called function are determined by matching the function call argument values by position. For example, the first formal parameter of the called function will have the value of the first argument at the call site.

  5. Control is transferred to the called function. If the called function is user-defined, execution proceeds starting from the first statement in the body.

  6. The called function is executed, until it returns.

  7. Control is transferred back to the calling function, and the called function’s execution is unsuspended. If the called function returns a value, that value is supplied for the value of the function call expression.

The location of a function call is referred to as a call site, specifically the location of the first token in the parsed instance of the call_phrase grammar rule. Call sites are a dynamic context. As such, the same textual location may represent multiple call sites.

Note: It is possible that a function call in a fragment shader never returns if all of the invocations in a quad are discarded. In such a case, control will not be tranferred back to the calling function.

10.3. const Functions

A function declared with a const attribute can be evaluated at shader-creation time. These functions are called const-functions. Calls to these functions can be part of const-expressions.

It is a shader-creation error if the function contains any expressions that are not const-expressions, or any declarations that are not const-declarations.

Note: The const attribute cannot be applied to user-declared functions.

EXAMPLE: const-functions
const first_one = firstLeadingBit(1234 + 4567); // Evaluates to 12
                                                // first_one has the type i32, because
                                                // firstLeadingBit cannot operate on
                                                // AbstractInt

@id(1) override x : i32;
override y = firstLeadingBit(x); // const-expressions can be
                                 // used in override-expressions.
                                 // firstLeadingBit(x) is not a
                                 // const-expression in this context.

fn foo() {
  var a : array<i32, firstLeadingBit(257)>; // const-functions can be used in
                                            // const-expressions if all their
                                            // parameters are const-expressions.
}

10.4. Restrictions on Functions

Note: Recursion is disallowed because cycles are not permitted among any kinds of declarations.

EXAMPLE: Valid and invalid pointer arguments
fn bar(p : ptr<function, f32>) {
}

fn baz(p : ptr<private, i32>) {
}

fn bar2(p : ptr<function, f32>) {
  let a = &*&*(p);

  bar(p); // Valid
  bar(a); // Valid
}

fn baz2(p : ptr<storage, f32>) {
}

struct S {
  x : i32
}

@group(0) @binding(0)
var<storage> ro_storage : f32;
@group(0) @binding(1)
var<storage, read_write> rw_storage : f32;

var usable_priv : i32;
var unusable_priv : array<i32, 4>;
fn foo() {
  var usable_func : f32;
  var unusable_func : S;
  var i32_func : i32;

  let a_priv = &usable_priv;
  let b_priv = a_priv;
  let c_priv = &*&usable_priv;
  let d_priv = &(unusable_priv.x);
  let e_priv = d_priv;

  let a_func = &usable_func;
  let b_func = &unusable_func;
  let c_func = &(*b_func)[0];
  let d_func = c_func;
  let e_func = &*a_func;

  baz(&usable_priv); // Valid, address-of a variable.
  baz(a_priv);       // Valid, effectively address-of a variable.
  baz(b_priv);       // Valid, effectively address-of a variable.
  baz(c_priv);       // Valid, effectively address-of a variable.
  baz(d_priv);       // Valid, memory view has changed.
  baz(e_priv);       // Valid, memory view has changed.
  baz(&i32_func);    // Invalid, address space mismatch.

  bar(&usable_func); // Valid, address-of a variable.
  bar(c_func);       // Valid, memory view has changed.
  bar(d_func);       // Valid, memory view has changed.
  bar(e_func);       // Valid, effectively address-of a variable.

  baz2(&ro_storage); // Valid, address-of a variable.
  baz2(&rw_storage); // Invalid, access mode mismatch.
}

10.4.1. Alias Analysis

10.4.1.1. Root Identifier

Memory locations can be accessed during the execution of a function using memory views. Within a function, each memory view has a particular root identifier, which names the variable or formal parameter that first provides access to that memory in that function.

Locally derived expressions of reference or pointer type may introduce new names for a particular root identifier, but each expression has a statically determinable root identifier.

Given an expression E of pointer or reference type, the root identifier is the originating variable or formal parameter of pointer type found as follows:

10.4.1.2. Aliasing

While the originating variable of a root identifier is a dynamic concept that depends on the call sites for the function, WGSL modules can be statically analyzed to determine the set of all possible originating variables for each root identifier.

Two root identifiers alias when they have the same originating variable. Execution of a WGSL function must not potentially access memory through aliased root identifiers, where one access is a write and the other is a read or a write. This is determined by analyzing the program from the leaves of the callgraph upwards (i.e. topological order). For each function the analysis records the following sets:

At each call site of a function, it is a shader-creation error if any of the following occur:

EXAMPLE: Alias analysis
var<private> x : i32 = 0;

fn f1(p1 : ptr<function, i32>, p2 : ptr<function, i32>) {
  *p1 = *p2;
}

fn f2(p1 : ptr<function, i32>, p2 : ptr<function, i32>) {
  f1(p1, p2);
}

fn f3() {
  var a : i32 = 0;
  f2(&a, &a);  // Invalid. Cannot pass two pointer parameters
               // with the same root identifier when one or
               // more are written (even by a subfunction).
}

fn f4(p1 : ptr<function, i32>, p2 : ptr<function, i32>) -> i32 {
  return *p1 + *p2;
}

fn f5() {
  var a : i32 = 0;
  let b = f4(&a, &a); // Valid. p1 and p2 in f4 are both only read.
}

fn f6(p : ptr<private, i32>) {
  x = *p;
}

fn f7(p : ptr<private, i32>) -> i32 {
  return x + *p;
}

fn f8() {
  let a = f6(&x); // Invalid. x is written as a global variable and
                  // read as a parameter.
  let b = f7(&x); // Valid. x is only read as both a parameter and
                  // a variable.
}

11. Attributes

An attribute modifies an object. WGSL provides a unified syntax for applying attributes. Attributes are used for a variety of purposes such as specifying the interface with the API.

Generally speaking, from the language’s point-of-view, attributes can be ignored for the purposes of type and semantic checking. Additionally, the attribute name is a context-dependent name, and some attribute parameters are also context-dependent names.

attribute :

'@' ident_pattern_token argument_expression_list ?

| align_attr

| binding_attr

| blend_src_attr

| builtin_attr

| const_attr

| diagnostic_attr

| group_attr

| id_attr

| interpolate_attr

| invariant_attr

| location_attr

| must_use_attr

| size_attr

| workgroup_size_attr

| vertex_attr

| fragment_attr

| compute_attr

Unless explicitly permitted in an attribute’s description, an attribute must not be specified more than once per object or type.

11.1. align

align_attr :

'@' 'align' '(' expression ',' ? ')'

align Attribute
Description Constrains the placement of a structure member in memory.

Must only be applied to a member of a structure type.

This attribute influences how a value of the enclosing structure type can appear in memory: it constrains the byte addresses at which the structure itself and its component members can appear.

If align(n) is applied to a member of S with type T, and S can be the store type for a variable in address space AS, where AS is not uniform, then n must satisfy:
n = k × RequiredAlignOf(T,AS) for some positive integer k.

The rules for alignment and size are mutually recursive. However, the above constraint is well defined because it depends on the required alignment of a nested type, and types have bounded nesting depth.

See § 13.4 Memory Layout.

Parameters Must be a const-expression that resolves to an i32 or u32.
Must be positive.
Must be a power of 2.

11.2. binding

binding_attr :

'@' 'binding' '(' expression ',' ? ')'

binding Attribute
Description Specifies the binding number of the resource in a bind group. See § 12.3.2 Resource Interface.

Must only be applied to a resource variable.

Parameters Must be a const-expression that resolves to an i32 or u32.
Must be non-negative.

11.3. blend_src

blend_src_attr :

'@' 'blend_src' '(' expression ',' ? ')'

blend_src Attribute
Description Specifies a part of the fragment output when the feature dual_source_blending is enabled. See § 12.3.1.3 Input-output Locations.

Must only be applied to a member of a structure type with a location attribute. Must only be applied to declarations of objects with numeric scalar or numeric vector type. Must not be included in a shader stage input. Must not be included in a shader stage output, except for the fragment shader stage.

Parameters Must be a const-expression that resolves to an i32 or u32 with value of 0 or 1.

11.4. builtin

builtin_attr :

'@' 'builtin' '(' builtin_value_name ',' ? ')'

builtin Attribute
Description Specifies that the associated object is a built-in value, as denoted by the specified token. See § 12.3.1.1 Built-in Inputs and Outputs.

Must only be applied to an entry point function parameter, entry point return type, or member of a structure.

Parameters Must be a built-in value name-token for a built-in value.

11.5. const

const_attr :

'@' 'const'

const Attribute
Description Specifies that the function can be used as a const-function. This attribute must not be applied to a user-defined function.

Must only be applied to function declarations.

Note: This attribute is used as a notational convention to describe which built-in functions can be used in const-expressions.

Parameters None

11.6. diagnostic

diagnostic_attr :

'@' 'diagnostic' diagnostic_control

diagnostic_control :

'(' severity_control_name ',' diagnostic_rule_name ',' ? ')'

diagnostic Attribute
Description Specifies a range diagnostic filter. See § 2.3 Diagnostics.

More than one diagnostic attribute may be specified on a syntactic form, but they must specify different triggering rules.

Parameters The first parameter is a severity_control_name.

The second parameter is a diagnostic_rule_name token specifying a triggering rule.

11.7. group

group_attr :

'@' 'group' '(' expression ',' ? ')'

group Attribute
Description Specifies the binding group of the resource. See § 12.3.2 Resource Interface.

Must only be applied to a resource variable.

Parameters Must be a const-expression that resolves to an i32 or u32.
Must be non-negative.

11.8. id

id_attr :

'@' 'id' '(' expression ',' ? ')'

id Attribute
Description Specifies a numeric identifier as an alternate name for a pipeline-overridable constant.

Must only be applied to an override-declaration of scalar type.

Parameters Must be a const-expression that resolves to an i32 or u32.
Must be non-negative.

11.9. interpolate

interpolate_attr :

'@' 'interpolate' '(' interpolate_type_name ',' ? ')'

| '@' 'interpolate' '(' interpolate_type_name ',' interpolate_sampling_name ',' ? ')'

interpolate_type_name :

ident_pattern_token

interpolate Attribute
Description Specifies how the user-defined IO must be interpolated. The attribute is only significant on user-defined vertex outputs and fragment inputs. See § 12.3.1.4 Interpolation.

Must only be applied to a declaration that has a location attribute applied.

Parameters The first parameter must be an interpolation type name-token for an interpolation type.

The second parameter, if present, must be an interpolation sampling name-token for the interpolation sampling.

11.10. invariant

invariant_attr :

'@' 'invariant'

invariant Attribute
Description When applied to the position built-in output value of a vertex shader, the computation of the result is invariant across different programs and different invocations of the same entry point. That is, if the data and control flow match for two position outputs in different entry points, then the result values are guaranteed to be the same. There is no effect on a position built-in input value.

Must only be applied to the position built-in value.

Note: This attribute maps to the precise qualifier in HLSL, and the invariant qualifier in GLSL.

Parameters None

11.11. location

location_attr :

'@' 'location' '(' expression ',' ? ')'

location Attribute
Description Specifies a part of the user-defined IO of an entry point. See § 12.3.1.3 Input-output Locations.

Must only be applied to an entry point function parameter, entry point return type, or member of a structure type. Must only be applied to declarations of objects with numeric scalar or numeric vector type. Must not be included in compute shader stage inputs.

Parameters Must be a const-expression that resolves to an i32 or u32.
Must be non-negative.

11.12. must_use

must_use_attr :

'@' 'must_use'

must_use Attribute
Description Specifies that a call to this function must be used as an expression. That is, a call to this function must not be the entirety of a function call statement.

Must only be applied to the declaration of a function with a return type.

Note: Many functions return a value and do not have side effects. It is often a programming defect to call such a function as the only thing in a function call statement. Built-in functions with these properties are declared as @must_use. User-defined functions can also have the @must_use attribute.

Note: To deliberately work around the @must_use rule, use a phony assignment or declare a value using the function call as the initializer.

Parameters None

11.13. size

size_attr :

'@' 'size' '(' expression ',' ? ')'

size Attribute
Description Specifies the number of bytes reserved for a structure member.

This number must be at least the byte-size of the type of the member:

If size(n) is applied to a member with type T, then SizeOf(T) ≤ n.

See § 13.4 Memory Layout.

Must only be applied to a member of a structure type. The member type must have creation-fixed footprint.

Parameters Must be a const-expression that resolves to an i32 or u32.
Must be positive.

11.14. workgroup_size

workgroup_size_attr :

'@' 'workgroup_size' '(' expression ',' ? ')'

| '@' 'workgroup_size' '(' expression ',' expression ',' ? ')'

| '@' 'workgroup_size' '(' expression ',' expression ',' expression ',' ? ')'

workgroup_size Attribute
Description Specifies the x, y, and z dimensions of the workgroup grid for the compute shader.

The first parameter specifies the x dimension. The second parameter, if provided, specifies the y dimension, otherwise is assumed to be 1. The third parameter, if provided, specifies the z dimension, otherwise is assumed to be 1.

Must only be applied to a compute shader entry point function. Must not be applied to any other object.

Parameters Takes one, two, or three parameters.

Each parameter must be a const-expression or an override-expression. All parameters must be the same type, either i32 or u32.

A shader-creation error results if any specified parameter is a const-expression that evaluates to a non-positive value.

A pipeline-creation error results if any specified parameter evaluates to a non-positive value or exceeds an upper bound specified by the WebGPU API, or if the product of the parameter values exceeds the upper bound specified by the WebGPU API (see WebGPU § 3.6.2 Limits).

11.15. Shader Stage Attributes

The shader stage attributes below designate a function as an entry point for a particular shader stage. These attributes must only be applied to function declarations, and at most one may be present on a given function. They take no parameters.

11.15.1. vertex

vertex_attr :

'@' 'vertex'

The vertex attribute declares the function to be an entry point for the vertex shader stage of a render pipeline.

11.15.2. fragment

fragment_attr :

'@' 'fragment'

The fragment attribute declares the function to be an entry point for the fragment shader stage of a render pipeline.

11.15.3. compute

compute_attr :

'@' 'compute'

The compute attribute declares the function to be an entry point for the compute shader stage of a compute pipeline.

12. Entry Points

An entry point is a user-defined function that performs the work for a particular shader stage.

12.1. Shader Stages

WebGPU issues work to the GPU in the form of draw or dispatch commands. These commands execute a pipeline in the context of a set of shader stage inputs, outputs, and attached resources.

A pipeline describes the work to be performed on the GPU, as a sequence of stages, some of which are programmable. In WebGPU, a pipeline is created before scheduling a draw or dispatch command for execution. There are two kinds of pipelines: GPUComputePipeline, and GPURenderPipeline.

A dispatch command uses a GPUComputePipeline to run a compute shader stage over a logical grid of points with a controllable amount of parallelism, while reading and possibly updating buffer and image resources.

A draw command uses a GPURenderPipeline to run a multi-stage process with two programmable stages among other fixed-function stages:

The WebGPU specification describes pipelines in greater detail.

WGSL defines three shader stages, corresponding to the programmable parts of pipelines:

Each shader stage has its own set of features and constraints, described elsewhere.

12.2. Entry Point Declaration

To create an entry point, declare a user-defined function with a shader stage attribute.

When configuring a pipeline in the WebGPU API, the entry point’s function name maps to the entryPoint attribute of the WebGPU GPUProgrammableStage object.

The entry point’s formal parameters denote the stage’s shader stage inputs. The entry point’s return value, if specified, denotes the stage’s shader stage outputs.

The type of each formal parameter, and the entry point’s return type, must be one of:

A structure type can be used to group user-defined inputs with each other and optionally with built-in inputs. A structure type can be used as the return type to group user-defined outputs with each other and optionally with built-in outputs.

Note: The bool case is forbidden for user-defined inputs and outputs. It is only permitted for the front_facing builtin value.

Note: Compute entry points never have a return type.

EXAMPLE: Entry Point
@vertex
fn vert_main() -> @builtin(position) vec4<f32> {
  return vec4<f32>(0.0, 0.0, 0.0, 1.0);
}

@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);
}

@compute @workgroup_size(1)
fn comp_main() { }

The set of functions in a shader stage is the union of:

The union is applied repeatedly until it stabilizes. It will stabilize in a finite number of steps.

12.2.1. Function Attributes for Entry Points

WGSL defines the following attributes that can be applied to entry point declarations:

EXAMPLE: workgroup_size Attribute
@compute @workgroup_size(8,4,1)
fn sorter() { }

@compute @workgroup_size(8u)
fn reverser() { }

// Using an pipeline-overridable constant.
@id(42) override block_width = 12u;
@compute @workgroup_size(block_width)
fn shuffler() { }

// Error: workgroup_size must be specified on compute shader
@compute
fn bad_shader() { }

12.3. Shader Interface

The shader interface is the set of objects through which the shader accesses data external to the shader stage, either for reading or writing, and the pipeline-overridable constants used to configure the shader. The interface includes:

A declaration D is statically accessed by a shader when:

Note:Static access is recursively defined, taking into account the following:

We can now precisely define the interface of a shader as consisting of:

12.3.1. Inter-stage Input and Output Interface

A shader stage input is a datum provided to the shader stage from upstream in the pipeline. Each datum is either a built-in input value, or a user-defined input.

A shader stage output is a datum the shader provides for further processing downstream in the pipeline. Each datum is either a built-in output value, or a user-defined output.

IO attributes are used to establish an object as a shader stage input or a shader stage output, or to further describe the properties of an input or output. The IO attributes are:

12.3.1.1. Built-in Inputs and Outputs

A built-in input value provides access to system-generated control information. An entry point must not contain duplicated built-in inputs.

A built-in input for stage S with name X and type TX is accessed via a formal parameter to an entry point for shader stage S, in one of two ways:

  1. The parameter has attribute builtin(X) and is of type TX.

  2. The parameter has structure type, where one of the structure members has attribute builtin(X) and is of type TX.

Conversely, when a parameter or member of a parameter for an entry point has a builtin attribute, the corresponding builtin must be an input for the entry point’s shader stage.

A built-in output value is used by the shader to convey control information to later processing steps in the pipeline. An entry point must not contain duplicated built-in outputs.

A built-in output for stage S with name Y and type TY is set via the return value for an entry point for shader stage S, in one of two ways:

  1. The entry point return type has attribute builtin(Y) and is of type TY.

  2. The entry point return type has structure type, where one of the structure members has attribute builtin(Y) and is of type TY.

Conversely, when the return type or member of a return type for an entry point has a builtin attribute, the corresponding builtin must be an output for the entry point’s shader stage.

Note: The position built-in is both an output of a vertex shader, and an input to the fragment shader.

Collectively, built-in input and built-in output values are known as built-in values.

The following table summarizes the available built-in values. Each is a built-in value name token for a built-in value. Each is described in detail in subsequent sections.

Built-in input and output values
Name Stage Direction Type Extension
vertex_index vertex input u32
instance_index vertex input u32
clip_distances vertex output array<f32, N> (N8) clip_distances
position vertex output vec4<f32>
fragment input vec4<f32>
front_facing fragment input bool
frag_depth fragment output f32
sample_index fragment input u32
sample_mask fragment input u32
fragment output u32
local_invocation_id compute input vec3<u32>
local_invocation_index compute input u32
global_invocation_id compute input vec3<u32>
workgroup_id compute input vec3<u32>
num_workgroups compute input vec3<u32>
EXAMPLE: Declaring built-in values
 struct VertexOutput {
   @builtin(position) my_pos: vec4<f32>,
   @builtin(clip_distances) my_clip_distances: array<f32, 8>,
 }

 @vertex
 fn vs_main(
   @builtin(vertex_index) my_index: u32,
   @builtin(instance_index) my_inst_index: u32,
 ) -> VertexOutput {}

 struct FragmentOutput {
   @builtin(frag_depth) depth: f32,
   @builtin(sample_mask) mask_out: u32
 }

 @fragment
 fn fs_main(
   @builtin(front_facing) is_front: bool,
   @builtin(position) coord: vec4<f32>,
   @builtin(sample_index) my_sample_index: u32,
   @builtin(sample_mask) mask_in: u32,
 ) -> FragmentOutput {}

 @compute @workgroup_size(64)
 fn cs_main(
   @builtin(local_invocation_id) local_id: vec3<u32>,
   @builtin(local_invocation_index) local_index: u32,
   @builtin(global_invocation_id) global_id: vec3<u32>,
) {}
12.3.1.1.1. clip_distances
Name clip_distances
Stage vertex
Type array<f32, N>
Direction Output
Description Each value in the array represents a distance to a user-defined clip plane. A clip distance of 0 means the vertex is on the plane, a positive distance means the vertex is inside the clip half-space, and a negative distance means the vertex is outside the clip half-space. The array size of clip_distances must be ≤ 8. See WebGPU § 23.2.4 Primitive Clipping.
12.3.1.1.2. frag_depth
Name frag_depth
Stage fragment
Type f32
Direction Output
Description Updated depth of the fragment, in the viewport depth range.

See WebGPU § 3.3 Coordinate Systems.

12.3.1.1.3. front_facing
Name front_facing
Stage fragment
Type bool
Direction Input
Description True when the current fragment is on a front-facing primitive. False otherwise.
12.3.1.1.4. global_invocation_id
Name global_invocation_id
Stage compute
Type vec3<u32>
Direction Input
Description The current invocation’s global invocation ID, i.e. its position in the compute shader grid. The value of global_invocation_id is equal to workgroup_id * workgroup_size + local_invocation_id.
12.3.1.1.5. instance_index
Name instance_index
Stage vertex
Type u32
Direction Input
Description Instance index of the current vertex within the current API-level draw command.

The first instance has an index equal to the firstInstance argument of the draw, whether provided directly or indirectly. The index is incremented by one for each additional instance in the draw.

12.3.1.1.6. local_invocation_id
Name local_invocation_id
Stage compute
Type vec3<u32>
Direction Input
Description The current invocation’s local invocation ID, i.e. its position in the workgroup grid.
12.3.1.1.7. local_invocation_index
Name local_invocation_index
Stage compute
Type u32
Direction Input
Description The current invocation’s local invocation index, a linearized index of the invocation’s position within the workgroup grid.
12.3.1.1.8. num_workgroups
Name num_workgroups
Stage compute
Type vec3<u32>
Direction Input
Description The dispatch size, vec3<u32>(group_count_x, group_count_y, group_count_z), of the compute shader dispatched by the API.
12.3.1.1.9. position
Name position
Stage vertex
Type vec4<f32>
Direction Output
Description The clip position of the current vertex, in clip space coordinates.

An output value (x,y,z,w) will map to (x/w, y/w, z/w) in WebGPU normalized device coordinates.

See WebGPU § 3.3 Coordinate Systems and WebGPU § 23.2.4 Primitive Clipping.

A dynamic error occurs if the w coordinate is zero.

Name position
Stage fragment
Type vec4<f32>
Direction Input
Description
Input position of the current fragment.

Let fp be the input position of the fragment.
Let rp be the RasterizationPoint for the fragment.
Let vp be the [[viewport]] in effect for the draw command.

Then schematically:

fp.xy = rp.destination.position
fp.z = rp.depth
fp.w = rp.perspectiveDivisor

In more detail:

  • fp.x and fp.y are the interpolated x and y coordinates of the position the current fragment in the framebuffer.

    The framebuffer is a two-dimensional grid of pixels with the top-left at (0.0,0.0) and the bottom right at (vp.width, vp.height). Each pixel has an extent of 1.0 unit in each of the x and y dimensions, and pixel centers are at (0.5,0.5) offset from integer coordinates.

  • fp.z is the interpolated depth of the current fragment. For example:

  • fp.w is the perspective divisor for the fragment, which is the interpolation of 1.0 ÷ vertex_w, where vertex_w is the w component of the position output of the vertex shader.

See WebGPU § 3.3 Coordinate Systems and WebGPU § 23.2.5 Rasterization.

12.3.1.1.10. sample_index
Name sample_index
Stage fragment
Type u32
Direction Input
Description Sample index for the current fragment. The value is least 0 and at most sampleCount-1, where sampleCount is the MSAA sample count specified for the GPU render pipeline. When this attribute is applied, if the effects of the fragment shader would vary based on the value of sample_index, the fragment shader will be invoked once per sample.

See WebGPU § 10.3 GPURenderPipeline.

12.3.1.1.11. sample_mask
Name sample_mask
Stage fragment
Type u32
Direction Input
Description Sample coverage mask for the current fragment. It contains a bitmask indicating which samples in this fragment are covered by the primitive being rendered.

See WebGPU § 23.2.11 Sample Masking.

Name sample_mask
Stage fragment
Type u32
Direction Output
Description Sample coverage mask control for the current fragment. The last value written to this variable becomes the shader-output mask. Zero bits in the written value will cause corresponding samples in the color attachments to be discarded.

See WebGPU § 23.2.11 Sample Masking.

12.3.1.1.12. vertex_index
Name vertex_index
Stage vertex
Type u32
Direction Input
Description Index of the current vertex within the current API-level draw command, independent of draw instancing.

For a non-indexed draw, the first vertex has an index equal to the firstVertex argument of the draw, whether provided directly or indirectly. The index is incremented by one for each additional vertex in the draw instance.

For an indexed draw, the index is equal to the index buffer entry for the vertex, plus the baseVertex argument of the draw, whether provided directly or indirectly.

12.3.1.1.13. workgroup_id
Name workgroup_id
Stage compute
Type vec3<u32>
Direction Input
Description The current invocation’s workgroup ID, i.e. the position of the workgroup in overall compute shader grid.

All invocations in the same workgroup have the same workgroup ID.

Workgroup IDs span from (0,0,0) to (group_count_x - 1, group_count_y - 1, group_count_z - 1).

12.3.1.2. User-defined Inputs and Outputs

User-defined data can be passed as input to the start of a pipeline, passed between stages of a pipeline or output from the end of a pipeline.

Each user-defined input datum and user-defined output datum must:

A compute shader must not have user-defined inputs or outputs.

12.3.1.3. Input-output Locations

Each input-output location can store a value up to 16 bytes in size. The byte size of a type is defined using the SizeOf column in § 13.4.1 Alignment and Size. For example, a four-component vector of floating-point values occupies a single location.

IO locations are specified via the location attribute.

Each user-defined input and output must have an explicitly specified IO location. Each structure member in the entry point IO must be one of either a built-in value (see § 12.3.1.1 Built-in Inputs and Outputs), or assigned a location.

For each entry point defined in a WGSL module, let inputs be its set of shader stage inputs (i.e. locations for its formal parameters, or for the members of its formal parameters of structure type).
For each structure type S defined in a WGSL module (not just those used in shader stage inputs or outputs), let members be the set of members of S that have location attributes.

Note: Location numbering is distinct between inputs and outputs: Location numbers for an entry point’s shader stage inputs do not conflict with location numbers for the entry point’s shader stage outputs.

Note: No additional rule is required to prevent location overlap within an entry point’s outputs. When the output is a structure, the first rule above prevents overlap. Otherwise, the output is a scalar or a vector, and can have only a single location assigned to it.

Note: The number of available locations for an entry point is defined by the WebGPU API.

EXAMPLE: Applying location attributes
struct A {
  @location(0) x: f32,
  // Despite locations being 16-bytes, x and y cannot share a location
  @location(1) y: f32
}

// in1 occupies locations 0 and 1.
// in2 occupies location 2.
// The return value occupies location 0.
@fragment
fn fragShader(in1: A, @location(2) in2: f32) -> @location(0) vec4<f32> {
 // ...
}

User-defined IO can be mixed with built-in values in the same structure. For example,

EXAMPLE: Mixing builtins and user-defined IO
// Mixed builtins and user-defined inputs.
struct MyInputs {
  @location(0) x: vec4<f32>,
  @builtin(front_facing) y: bool,
  @location(1) @interpolate(flat) z: u32
}

struct MyOutputs {
  @builtin(frag_depth) x: f32,
  @location(0) y: vec4<f32>
}

@fragment
fn fragShader(in1: MyInputs) -> MyOutputs {
  // ...
}
EXAMPLE: Invalid location assignments
struct A {
  @location(0) x: f32,
  // Invalid, x and y cannot share a location.
  @location(0) y: f32
}

struct B {
  @location(0) x: f32
}

struct C {
  // Invalid, structures with user-defined IO cannot be nested.
  b: B
}

struct D {
  x: vec4<f32>
}

@fragment
// Invalid, location cannot be applied to a structure type.
fn fragShader1(@location(0) in1: D) {
  // ...
}

@fragment
// Invalid, in1 and in2 cannot share a location.
fn fragShader2(@location(0) in1: f32, @location(0) in2: f32) {
  // ...
}

@fragment
// Invalid, location cannot be applied to a structure.
fn fragShader3(@location(0) in1: vec4<f32>) -> @location(0) D {
  // ...
}
12.3.1.4. Interpolation

Authors can control how user-defined IO data is interpolated through the use of the interpolate attribute. WGSL offers two aspects of interpolation to control: the type of interpolation, and the sampling of the interpolation.

The interpolation type must be one of the following interpolation type name tokens:

perspective

Values are interpolated in a perspective correct manner.

linear

Values are interpolated in a linear, non-perspective correct manner.

flat

Values are not interpolated.

The interpolation sampling must be one of the following interpolation sampling name tokens:

center

Interpolation is performed at the center of the pixel.

centroid

Interpolation is performed at a point that lies within all the samples covered by the fragment within the current primitive. This value is the same for all samples in the primitive.

sample

Interpolation is performed per sample. The fragment shader is invoked once per sample when this attribute is applied.

first

The value is provided by the first vertex of the primitive.

either

The value is provided by the first vertex or last vertex of the primitive. Whether the value comes from the first or last vertex is implementation dependent.

For user-defined IO of scalar or vector floating-point type:

User-defined vertex outputs and fragment inputs of scalar or vector integer type must always be specified with interpolation type flat.

Interstage interface validation checks that, within a render pipeline, the interpolation properties of each user-defined fragment input match the interpolation properties of a vertex output with the same location assignment. If not, a pipeline-creation error will result.

12.3.2. Resource Interface

A resource is an object which provides access to data external to a shader stage, and which is not an override-declaration and not a shader stage input or output. Resources are shared by all invocations of the shader.

There are four kinds of resources:

The resource interface of a shader is the set of module-scope resource variables statically accessed by functions in the shader stage.

Each resource variable must be declared with both group and binding attributes. Together with the shader’s stage, these identify the binding address of the resource on the shader’s pipeline. See WebGPU § 8.3 GPUPipelineLayout.

Two different resource variables in a shader must not have the same group and binding values, when considered as a pair.

12.3.3. Resource Layout Compatibility

WebGPU requires that a shader’s resource interface match the layout of the pipeline using the shader.

It is a pipeline-creation error if a WGSL variable in a resource interface is bound to an incompatible WebGPU binding resource type or binding type, where compatibility is defined by the following table.

WebGPU binding type compatibility
WGSL resource WebGPU
resource type
WebGPU binding member WebGPU binding type
uniform buffer GPUBufferBinding buffer GPUBufferBindingType "uniform"
storage buffer with read_write access "storage"
storage buffer with read access "read-only-storage"
sampler GPUSampler sampler GPUSamplerBindingType "filtering"
"non-filtering"
sampler_comparison "comparison"
sampled texture, depth texture, or multisampled texture GPUTextureView texture GPUTextureSampleType "float"
"unfilterable-float"
"sint"
"uint"
"depth"
write-only storage texture GPUTextureView storageTexture GPUStorageTextureAccess "write-only"
read-write storage texture "read-write"
read-only storage texture "read-only"
external texture GPUExternalTexture externalTexture (not applicable)

See the WebGPU API specification for interface validation requirements.

12.3.4. Buffer Binding Determines Runtime-Sized Array Element Count

When a storage buffer variable contains a runtime-sized array, then the number of elements in that array is determined from the size of the corresponding GPUBufferBinding:

In more detail, the NRuntime for a runtime-size array of type RAT is:

truncate((EBBS − array_offset) ÷ array_stride), where:

A shader can compute NRuntime via the arrayLength builtin function.

Note: This algorithm is unambiguous: When a runtime-sized array is part of a larger type, it may only appear as the last element of a structure, which itself cannot be part of an enclosing array or structure.

NRuntime is determined by the size of the corresponding buffer binding, and that can be different for each draw or dispatch command.

WebGPU validation rules ensure that 1 ≤ NRuntime.

In the following code sample:
EXAMPLE: number of elements in a simple runtime sized array
@group(0) @binding(1) var<storage> weights: array<f32>;

The following table shows examples of NRuntime for the weights variable, based on the corresponding effective buffer binding size.

Example number of elements for simple runtime-sized array
Effective buffer binding size NRuntime for weights variable Calculation
1024 256 truncate( 1024 ÷ 4 )
1025 256 truncate( 1025 ÷ 4 )
1026 256 truncate( 1026 ÷ 4 )
1027 256 truncate( 1027 ÷ 4 )
1028 257 truncate( 1028 ÷ 4 )
In the following code sample:
EXAMPLE: number of elements in a complex runtime sized array
struct PointLight {                          //             align(16) size(32)
  position : vec3f,                          // offset(0)   align(16) size(12)
  // -- implicit member alignment padding -- // offset(12)            size(4)
  color : vec3f,                             // offset(16)  align(16) size(12)
  // -- implicit struct size padding --      // offset(28)            size(4)
}

struct LightStorage {                        //             align(16)
  pointCount : u32,                          // offset(0)   align(4)  size(4)
  // -- implicit member alignment padding -- // offset(4)             size(12)
  point : array<PointLight>,                 // offset(16)  align(16) elementsize(32)
}

@group(0) @binding(1) var<storage> lights : LightStorage;

The following table shows examples of NRuntime for the point member of the lights variable.

Example number of elements for complex runtime-sized array
Effective buffer binding size NRuntime for point member of lights variable Calculation
1024 31 truncate( ( 1024 - 16 ) ÷ 32) )
1025 31 truncate( ( 1025 - 16 ) ÷ 32) )
1039 31 truncate( ( 1039 - 16 ) ÷ 32) )
1040 32 truncate( ( 1040 - 16 ) ÷ 32) )

13. Memory

In WGSL, a value of storable type may be stored in memory, for later retrieval. This section describes the structure of memory, and the semantics of operations accessing memory. See § 6.4 Memory Views for the types of values that can be placed in memory, and the types used to perform memory accesses.

13.1. Memory Locations

Memory consists of a set of distinct memory locations. Each memory location is 8-bits in size. An operation affecting memory interacts with a set of one or more memory locations. Memory operations on composites will not access padding memory locations. Therefore, the set of memory locations accessed by an operation may not be contiguous.

Two sets of memory locations overlap if the intersection of their sets of memory locations is non-empty.

13.2. Memory Access Mode

A memory access is an operation that acts on memory locations.

A single operation can read, write, or both read and write.

Particular memory locations may support only certain kinds of accesses, expressed as the memory’s access mode.

Access Modes
Access mode Supported accesses
read Supports read accesses, but not writes.
write Supports write accesses, but not reads.
read_write Supports both read and write accesses.

WGSL predeclares the enumerants read, write, and read_write.

13.3. Address Spaces

Memory locations are partitioned into address spaces. Each address space has unique properties determining mutability, visibility, the values it may contain, and how to use variables with it. See § 7 Variable and Value Declarations for more details.

The access mode of a given memory view is often determined by context:

The storage address spaces supports both read and read_write access modes. Each other address space supports only one access mode. The default access mode for each address space is described in the following table.

Address Spaces
Address space Sharing among invocations Default access mode Notes
function Same invocation only read_write
private Same invocation only read_write
workgroup Invocations in the same compute shader workgroup read_write The element count of an outermost array may be a pipeline-overridable constant.
uniform Invocations in the same shader stage read For uniform buffer variables
storage Invocations in the same shader stage read For storage buffer variables
handle Invocations in the same shader stage read For sampler and texture variables.

WGSL predeclares an enumerant for each address space, except for the handle address space.

Variables in the workgroup address space must only be statically accessed in a compute shader stage.

Variables in the storage address space (storage buffers) can only be statically accessed by a vertex shader stage if the access mode is read. Variables whose store type is a storage texture with a write or