# PSA for Chromium / Dawn WebGPU API updates 2020-04-28

Chromium's WebGPU implementation and Dawn's API try to closely follow changes to the WebGPU specification. When the WebGPU IDL changes, as best as possible Chromium and Dawn will support both the "old" and the "new" version of the IDL at the same time so prototypes can be updated. In JS, uses of the "old" path will result in a console warning, while when using Dawn directly, the "old" 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 the smooth transition since developers control which version of emscripten they use.

A couple weeks after an update like this one, the "old" version will be removed. This means that the "old" version of the items below will start being removed from Chromium/Dawn starting on 2020-05-12.

## Breaking changes

### `GPUDevice` `.createQueue()` -> `.defaultQueue`

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

No changes for JS: `.createQueue()` was already removed from Chromium so this is only a Dawn API change.

-wgpu::Queue queue = device.CreateQueue();
+wgpu::Queue queue = device.GetDefaultQueue();

### `BindGroup[Layout]Binding` -> `BindGroup[Layout]Entry`

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

No changes for JS.

The name of structure has been updated in Dawn's API. The only change needed is replacing references to `wgpu::BindGroupLayoutBinding` to `wgpu::BindGroupLayoutEntry` and references to `wgpu::BindGroupBinding` to `wgpu::BindGroupEntry`.

### `BindGroup[Layout]Descriptor` `.bindings` -> `.entries`

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

In JS the dictionary member name needs to be updated:

 const layout = device.createBindGroupLayout({
-    bindings: [ ... ],
+    entries: [ ... ],
 });
 const bindgroup = device.createBindGroup({
     layout,
-    bindings: [ ... ],
+    entries: [ ... ],
 });

Likewise when using Dawn's API changes are needed:

 wgpu::BindGroupLayoutDescriptor layoutDesc;
-layoutDesc.bindingCount = 1;
-layoutDesc.bindings = &myLayoutEntry;
+layoutDesc.entryCount = 1;
+layoutDesc.entries = &myLayoutEntry;
 wgpu::BindGroupLayout layout = device.CreateBindGroupLayout(&layoutDesc);

 wgpu::BindGroupDescriptor bgDesc;
 bgDesc.layout = layout;
-bgDesc.bindingCount = 1;
-bgDesc.bindings = &myBgEntry;
+bgDesc.entryCount = 1;
+bgDesc.entries = &myBgEntry;
 wgpu::BindGroup bg = device.CreateBindGroup(&bgDesc);

### `BindGroupLayoutEntry.textureDimension` -> `viewDimension`

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

In JS the dictionary member name needs to be updated:

 const layout = device.createBindGroupLayout({
     entries: [{
         binding: 0,
         type: "sampled-texture",
-        textureDimension: "3d",
+        viewDimension: "3d",
     }]
 });

Likewise when using Dawn's API changes are needed:

 wgpu::BindGroupEntry entry;
 entry.binding = 0;
 entry.type = wgpu::BindingType::SampledTexture;
-entry.textureDimension = wgpu::TextureDimension::e3D;
+entry.viewDimension = wgpu::TextureDimension::e3D;

### Renames of `rowPitch` and `imageHeight`

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

They are now called `bytesPerRow` and `rowsPerImage` respectively. In JS the member of dictionaries needs to be updated.

 commandEncoder.copyBufferToTexture({
     buffer: textureDataBuffer,
-    rowPitch: myRowPitch,
-    imageHeight: myImageHeight,
+    bytesPerRow: myBytesPerRow,
+    rowsPerImage: myRowsPerImage,
 }, ...);

Likewise in Dawn's API uses of `wgpu::BufferCopyView` must be updated:

 wgpu::BufferCopyView bufferView;
 bufferView.buffer = buffer;
-bufferView.rowPitch = myRowPitch;
-bufferView.imageHeight = myImageHeight;
+bufferView.bytesPerRow = myBytesPerRow;
+bufferView.rowsPerImage = myRowsPerImage;

 encoder.CopyBufferToTexture(&bufferView, ...);

### Usages of sub-descriptors for `wgpu::ShaderModuleDescriptor`

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

Dawn is looking to support both SPIR-V and WGSL at the same time. This will be done by using the "chained structure" extension mechanism. Ingestion of SPIR-V will be moved to a chained structure.

-wgpu::ShaderModuleDescriptor desc;
-desc.codeSize = spirv.size();
-desc.code = spirv.data();

+wgpu::ShaderModuleSPIRVDescriptor chainedDesc;
+chainedDesc.codeSize = spirv.size();
+chainedDesc.code = spirv.data();

+wgpu::ShaderModuleDescriptor desc;
+desc.nextInChain = &chainedDesc;

 wgpu::ShaderModule module = device.CreateShaderModule(&desc);

## Less breaking changes

### Draw defaults

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

Defaults were added to the draw commands so that in JS `pass.draw(3, 1, 0, 0)` can be written `pass.draw(3)` and `pass.drawIndexed(3, 1, 0, 0, 0)` can be written `pass.drawIndexed(3)`. Similar defaults are added to Dawn's C++ API.

### Comparison samplers

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

`GPUSamplerDescriptor.compare` is now optional and must be set if and only if the sampler is a comparison sampler meant to be used with the new `"comparison-sampler"` binding type. Likewise in Dawn's C++ API where `wgpu::SamplerDescriptor::compare` default to `wgpu::CompareFunction::Undefined` which represents the member not being set.

### Optional `size` for `GPURenderEncoderBase.set[Vertex|Index]Buffer`

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

Calls to `GPURenderEncoderBase.setVertexBuffer` and `GPURenderEncoderBase.setIndexBuffer` now take an additional and optional size argument. If left to the default value of 0, `size` represents the entire length of the buffer after `offset`. Similar defaults are added to Dawn's C++ API.

### Addition of storage textures

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

This adds a couple new `GPUBindingType` and `GPUBindGroupLayoutEntry.storageTextureFormat`. No changes needed to update your code.

## Upcoming IDL changes

### `GPUBuffer.setSubData` removal

We're waiting for discussions around `writeBuffer` to finish in the group before removing `GPUBuffer.setSubData` in Chromium and `wgpu::Buffer::SetSubData` in Dawn.

### `GPUShaderModuleDescriptor.code` being WGSL instead of SPIRV

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

Chromium's WGSL implementation isn't complete enough to be useful to write applications so `GPUShaderModuleDescriptor.code` still only allows `Uint32Array` containing SPIRV.

### Merging `GPUTextureDescriptor.arrayLayerCount` in `size.depth`

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

This isn't implemented in Dawn yet. In JS texture creation needs to be updated (but there will be another PSA before the "old" path is removed).

 const texture = device.createTexture({
     format: "rgba8-unorm",
     usage: GPUTextureUsage.OUTPUT_ATTACHMENT,
-    size: {width: 16, height:16, depth: 1},
-    arrayLayerCount: 4,
+    size: {width: 16, height:16, depth: 4},
 });

### Query APIs

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

They aren't implemented in Chromium/Dawn yet.

### Object label getters and setters

They aren't implemented in Chromium/Dawn yet.