# Changelog for WebGPU in Chromium / Dawn 98

Chromium's WebGPU implementation and Dawn's API try to closely follow changes to the WebGPU specification. When the WebGPU IDL changes, Chromium and Dawn will try to support both the deprecated and the new version of the IDL at the same time so prototypes can be updated. In JavaScript, uses of the deprecated path will result in a console warning, while when using Dawn directly, the deprecated path will print a warning to stderr.

Note that all changes to Dawn's API make it closer to [`webgpu.h`](https://github.com/webgpu-native/webgpu-headers/blob/master/webgpu.h) that we hope will allow applications to target both [Dawn](https://dawn.googlesource.com/dawn), and [wgpu](https://github.com/gfx-rs/wgpu/) in native before being compiled in WASM. Emscripten will also be updated from the "old" to the "new" API but won't have a smooth transition since developers control which version of emscripten they use.

Items deprecated in this changelog will be removed in the next branched version of Chromium. They will also be removed in Chromium Canary and top of tree Dawn two weeks after this changelog is published in Canary and top of tree Dawn (so starting 2022-01-05).

Previous PSAs / changelogs:

- [Changelog for WebGPU in Chromium / Dawn 96](https://hackmd.io/cHOIruemQpe4f1zI9o6mQg)
- [Changelog for WebGPU in Chromium / Dawn 94](https://hackmd.io/OxDovqjoTXqC_r_WY-aM1Q)
- [PSA for Chromium / Dawn WebGPU API updates 2021-04-07](https://hackmd.io/BtRPZXulQICjbcZi4tLCdg)
- [PSA for Chromium / Dawn WebGPU API updates 2020-10-19](https://hackmd.io/uH1MI9cnQBG9GGOZG20COw)
- [PSA for Chromium / Dawn WebGPU API updates 2020-07-28](https://hackmd.io/szV68rOVQ56GYzPJMBko8A)
- [PSA for Chromium / Dawn WebGPU API updates 2020-04-28](https://hackmd.io/Et7xlhoaThmi8dEX_s-xSw)

## New deprecations

### `GPUQueue.copyImageBitmapToTexture` -> `GPUQueue.copyExternalImageToTexture`

[First WebGPU PR](https://github.com/gpuweb/gpuweb/pull/1581)

`copyImageBitmapToTexture` has been deprecated for a while but `copyExternalImageToTexture` wasn't a superset until recently. Now it is a superset so `copyImageBitmapToTexture` will be removed soon.

In JavaScript `copyExternalImageToTexture` is used like so:

queue.copyExternalImageToTexture(
    {source: imageBitmap}, // or a canvas
    {texture: destinationTexture},
    [16, 16]
);

There are more options to control many aspects of the copy, including color space conversion, premultiplied alpha, etc. See the [relevant section of the spec](https://gpuweb.github.io/gpuweb/#dom-gpuqueue-copyexternalimagetotexture).

### WGSL: `ignore()` is replaced with phony-assignment

[WebGPU PR](https://github.com/gpuweb/gpuweb/issues/2127)

The `ignore` builtin was useful to ignore the return value of functions and to statically reference bindings without using them. It has been replaced with the "phony assignement" using `_` as an identifier.

WGSL code needs to be updated like the following:

-ignore(myTexture);
+let _ = myTexture;

### WGSL: `modf` and `frexp` overloads taking are deprecated

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/1973)

These two builtins return a structure containing two members instead of returning one by value and one through a pointer.

WGSL code needs to be updated like the following:

-var exponent : i32;
-let significand = frexp(value, &exponent);
+let result = frexp(value);
+// use result.sig and result.exp

-var whole : i32;
-let fractional = modf(value, &whole)
+let result = modf(value);
+// use result.fract and result.whole

### WGSL: Readonly storage texture declaration are deprecated

Readonly storage textures are already removed from the API, but it will now become invalid to declare readonly storage textures in WGSL code as well, even if they are not statically used.

### WGSL: `isNan`, `isInf`, `isFinite` and `isNormal` are deprecated

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2311). They will be removed in M101

GPUs don't need to have floating points that are strictly IEE-754 compliant and in particular might not support infinities, NaNs and denormal floating pointer numbers. This means that a driver might optimize `isNan` and `isInf` (resp `isFinite` and `isNormal`) to always return `true` (resp. `false`).

It means that these builtins can't be relied upon and they have been removed.

### WGSL: taking the address of a vector component is an error

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2225)

This is a limitation coming from the Metal Shading Language. The following WGSL now produces an error:

var foo vec4<f32>;
&foo.x; // Error, taking the address of a vector's component.

### WGSL: Module-scope declarations can no longer alias a builtin name

It is no longer possible to shadow a builtin function's name with a user-defined function. The following WGSL now produces an error:

fn mix() {} // Error, shadows the mix builtin.
let mix = 1; // Error, shadows the mix builtin.

### WGSL: Using `discard` inside a loop `continuing` block is an error

This is aprt of the WGSL [behavior rules](https://gpuweb.github.io/gpuweb/wgsl/#behaviors-rules).

Prviously it was an error to use `discard` inside a loop continuing block, and now with the behavior rules it is also an error to call a function that may potentially discard. The following WGSL now produces an error:

fn mayDiscard() {
    if (someCondition) { discard; }
}

loop {
    // Stuff ...
    continuing {
        // Error, `continuing` blocks can't have the `discard behavior.
        mayDiscard();
    }
}

## New features and improvements

### `GPUAdapter.limits` are now supported

For portability, WebGPU has conservative values for many limits such as `maxTextureDimension2D`. Previously Chromium forced these limits to the minimum required limits in the specification. It now exposes the `GPUAdapter` limits on the object and allows configuring them when requesting a device.

Note that for privacy reasons, Chromium doesn't expose the exact limits of every device to JavaScript and instead buckets them. The definition of the buckets or even the bucket mechanism are likely to change in the future but a couple buckets are exposed at the moment for limits such as `maxComputeWorkgroupStorageSize` and `maxStorageBufferBindingSize` which were very conservative.

In JavaScript requesting limits is done like the following:

const adapter = navigator.gpu.requestAdapter();

// We could use storage buffer bindings up to 1GB so request
// that if possible.
const requiredLimits = {};
if (adapter.limits.maxStorageBufferBindingSize > (1 << 30) {
    requiredLimits['maxStorageBufferBindingSize'] = 1 << 30;
}

const device = await adapter.requestDevice({requiredLimits});

When using Dawn's C++ API similar mechanisms are available but they are being reimplemented to match `webgpu.h` so they aren't described here.

### `GPUComputePassEncoder.dispatchIndirect`

This method is like `GPUComputePassEncoder.dispatch` except that instead of taking the `x`, `y`, `z` arguments directly, it takes them from a `GPUBuffer`. It allows previous GPU operations to choose how many workgroups to dispatch without doing a roundtrip to the CPU, allowing more powerful GPU-centric algorithms.

In JavaScript it can be used like so:

const indirectBuffer = device.createBuffer(
    size: 1000,
    usage: GPUBufferUsage.INDIRECT | GPUBufferUsage.STORAGE,
);

const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass();

// Do some operations that fills `indirectBuffer`

// Set up the indirect dispatch, then
pass.dispatchIndirect(indirectBuffer, 20/*offset, defaults to 0*/);

pass.endPass();
queue.submit([encoder.finish()])

Likewise when using Dawn's C++ API:

wgpu::BufferDescriptor bufferDesc;
bufferDesc.size = 1000;
bufferDesc.usage = wgpu::BufferUsage::Indirect | wgpu::BufferUsage::Storage;
wgpu::Buffer indirectBuffer = device.CreateBuffer(&bufferDesc);

wgpu::CommandEncoder encoder = device.CreateCommandEncoder();
wgpu::ComputePass pass = encoder.BeginComputePass();

// Do some operations that fills `indirectBuffer`

// Set up the indirect dispatch, then
pass.DispatchIndirect(indirectBuffer, 20/*offset, defaults to 0*/);

pass.EndPass();
wgpu::CommandBuffer commands = encoder.Finish();
queue.Submit(1, &commands);

### `GPURenderEncoderBase.drawIndexedIndirect`

This is very similar to `GPUComputePassEncoder.dispatchIndirect`, except that it is the indirect version of `GPURenderEncoderBase.drawIndexed`.

### ASTC and ETC texture compression optional features

When available on the system, Chromium will now expose the `texture-compression-etc` and `texture-compression-astc` optional features. This means that on all systems, one of the BC, ETC(2) or ASTC optional features are exposed so there is always some form of texture compression available.

These compressed formats are usable like the previously available BC formats. See the [list of format support](https://gpuweb.github.io/gpuweb/#packed-formats) in the WebGPU specification for more information.

### `depth16unorm`

This small depth format is now supported. It is the only non-optional depth format that's supported as both a source and destination of copies (the `depth24plus`). See the list of [depth stencil format support](https://gpuweb.github.io/gpuweb/#depth-formats) in the WebGPU specification for more information.

### WebCodec `VideoFrame` support in `GPUDevice.importTexture` (Web-only)

[WebCodec PR](https://github.com/w3c/webcodecs/pull/412)

`GPUExternalTexture` is an object that provides optimized access to a frame of an external video object. It previously only supported being created from an `HTMLVideoElement`. It is now also possible to create a `GPUExternalTexture` from a WebCodec [`VidoFrame`](https://www.w3.org/TR/webcodecs/#videoframe-interface) object. This allows working in an optimized manner with WebCodec streams of video.

Note that the implementation isn't completely optimized yet, and that in the future closing the `VideoFrame` will destroy the `GPUExternalTexture`.

### More destination formats for `copyExternalImageToTexture` (Web-only)

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2142)

`GPUQueue.copyExternalImageToTexture` has been extended to support more destination texture formats. This is what makes it a strict superset of `copyImageBitmapToTexture` now.

### `stripIndexFormat` is validated at draw time

`stripIndexFormat` was required to be specified for all pipelines that had a strip primitive topology. This is now only required if the pipeline is used in a indexed draw operations. The following JavaScript code used to produce an error but is now value.

// Used to produce an error, now valid!
const pipeline = device.createRenderPipeline({
    primitive: {
        topology: 'triangle-strip',
        // stripIndexFormat no set
    }
});

const pass = beginSomeRenderPass();
pass.setPipeline(pipeline);
// This is valid
pass.draw(3);

// This is an error
pass.drawIndexed(3);

### WebGPU `<canvas>` readbacks

Various APIs that read the content of canvases now work with WebGPU canvases. For example `HTMLCanvasElement.toDataURL`. Note however that due to an implementation issue, the content read back from the canvas may be from some past frame. This is a known issue that requires complex changes in Chromium to fix and won't be solved immediately.

### WGSL: Improved control flow analysis

The WGSL specification now has control flow analysis built-in in the [behavior rule section](https://gpuweb.github.io/gpuweb/wgsl/#behaviors). It lifts the requirement that a function returning a value must end with a return, as long as all control flow paths return. For example the following WGSL code used to produce an error but is now valid:

fn foo() -> u32 {
    if (some_condition) {
        return 0u;
    } else {
        return 42u;
    }
    // Used to be an error and you had to add a dummy return here.
    // return 0u;
}

Note that unreachable statements now produce a warning, instead of an error as required by the specification. This allows WGSL code that had the dummy returns to be updated. These warnings may become errors in the future.

### WGSL: `textureGather[Compare]` builtins

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2341)

Given a component index (0 for R, 1 for G, etc), `textureGather(component, texture, sampler, coords)` return the component of the four texels that would be sampled by the a `textureSample` operation. It is a common way to reduce memory traffic in shaders that care about a single component of multiple texels. The `component` argument must be a compile time constant.

The WGSL example from the specification is:

[[group(0),binding(0)]] var t: texture_2d<f32>;
[[group(0),binding(1)]] var dt: texture_depth_2d;
[[group(0),binding(2)]] var s: sampler;

fn gather_x_components(c: vec2<f32>) -> vec4<f32> {
    return textureGather(0, t, s, c);
}
fn gather_y_components(c: vec2<f32>) -> vec4<f32> {
    return textureGather(1, t, s, c);
}
fn gather_z_components(c: vec2<f32>) -> vec4<f32> {
    return textureGather(2, t, s, c);
}
fn gather_depth_components(c: vec2<f32>) -> vec4<f32> {
    return textureGather(dt, s, c);
}

### WGSL: support for shadowing between lexical scopes

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/1561)

Previously WebGPU didn't allow shadowing identifiers in an outer scope with identifiers in an inner scope. This is now allowed and makes the following WGSL code valid (one of many other shadowing cases):

let foo = 1;

// previsouly would be an error because foo is redefiend
fn bar(foo : u32) { }

### WGSL: identifier can start with a single _

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2326 )

But identifiers reserved for the WGSL specification and implementations are now prefixed with double underscores, so these are not allowed. But `_my_identifier` is allowed.

### WGSL: Function return values can be ignored

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2148)

WGSL no longer requires that the return value of functions are used. The following WGSL code is now valid:

[[block]] struct S {
    counter: atomic<u32>; 
};
[[group(0), binding(0)]] var<storage> s : S;

fn increment() {
    atomicAdd(&s.counter, 1u);
    // Previsouly had to be wrapped in ignore()
}

### WGSL: Matrix constructors from scalar elements

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2001)

Matrices can be constructed by giving their scalars in column-major order.

mat2x2<f32>(0.0, 1.0, 2.0, 3.0);
// Is the same as
max2x2<f32>(vec2<f32>(0.0, 1.0), vec2<f32>(2.0, 3.0));

### WGSL: Interpolation attributes on integral user-defined IO.

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2183)

It is not possible to specify `[[interpolate(flat)]]` on integral user-defiend IO. It will eventually become an error to define integral user-defined IO without this attribute. For example:

fn fragment([[location(0), interpolate(flat)]] triangle_id : u32) {
    // ...
}

### WGSL: `dot` buitin variants for integer vector types

[WebGPU PR](https://github.com/gpuweb/gpuweb/pull/2249)

The dot product builtin can now act on vectors of `i32` and `u32`, and returns that same type.

### WGSL: `any(bool)` and `all(bool)`

These were missed in the initial implementation and are added from completeness. They just return their argument.