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 that we hope will allow applications to target both Dawn, and 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
• Changelog for WebGPU in Chromium / Dawn 94
• PSA for Chromium / Dawn WebGPU API updates 2021-04-07
• PSA for Chromium / Dawn WebGPU API updates 2020-10-19
• PSA for Chromium / Dawn WebGPU API updates 2020-07-28
• PSA for Chromium / Dawn WebGPU API updates 2020-04-28

New deprecations

GPUQueue.copyImageBitmapToTexture -> GPUQueue.copyExternalImageToTexture

First WebGPU PR

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.

WGSL: ignore() is replaced with phony-assignment

WebGPU PR

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

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

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.

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 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 in the WebGPU specification for more information.

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

WebCodec PR

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

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

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

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

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

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

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

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

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.