
*Note that we will use Chrome Canary as our gauge browser for WebGPU features as other browsers are still lagging in term of feature support as of this writing (2022/01/16).*

## Make it work: Current status of the port
Most of the features of Babylon.js are now available in WebGPU. Here's a detailed list of what is not working / is partially working.

### Features with incomplete support
* [Point Cloud System](/typedoc/classes/babylon.pointscloudsystem)
  * WebGPU does not support a point size different from 1, so setting a value different from 1 for the point size won't be taken into account

### Features not working because not implemented yet
* Support for triangle fan / line loop drawing mode
  * WebGPU does not support those modes, we will need to emulate them with triangle strip and line strip
* Support types other than `float` for the vertex buffers (position, normal, uv, ...)
  * Contrary to WebGL, in WebGPU there's no automatic conversion from the type of the vertex buffer to the type used by shader
* Handle context lost/restore
* [Multiview / WebXR](/features/featuresDeepDive/cameras/multiViewsPart1)
  * Not implemented yet but not supported by Chrome / WebGPU specifications neither

## Make it fast: Optimizations
The most important optimizations have now been done (see [Optimizations](/setup/support/webGPU/webGPUOptimization)), others could be considered:
* Use compute shaders to perform some conversions when reading data from buffers
* Use compute shaders to generate mipmaps

## Other "nice-to-have" features 
* Use `CreatePipelineAsync` for asynchronous pipeline creations

## Browser Caveats
Chrome Canary does not support all WebGPU features yet (or some others are not fully functional yet), so here are some caveats:
* No WebGPU capabilities (caps) returned by the browser
  * For the time being, we have set some hard values for the caps
* GPU timing in the **Inspector** does not work because timestamp queries are currently disabled in Chrome. You can start Chrome with the `--disable-dawn-features=disallow_unsafe_apis` flag if you want to enable them.



This page is describing the breaking changes and differences in behaviour between WebGL and WebGPU.

We try to avoid breaking changes as much as possible in the core library, but sometimes we can't avoid them, and with the big new evolution that supporting WebGPU as a new engine is you need to be aware of a number of things if trying to port your existing projects to WebGPU.

## readPixels is now asynchronous

Probably the biggest change between WebGPU and WebGL is that reading from a texture is asynchronous in WebGPU, no way around it. So, all methods (even in WebGL mode) reading pixels from textures now return a promise:

- [BaseTexture.readPixels](/typedoc/classes/babylon.basetexture#readpixels)
- [ProceduralTexture.getContent](/typedoc/classes/babylon.proceduraltexture#getcontent)
- [ThinEngine.readPixels](/typedoc/classes/babylon.thinengine#readpixels)
- [CubeMapToSphericalPolynomialTools.ConvertCubeMapTextureToSphericalPolynomial](/typedoc/classes/babylon.cubemaptosphericalpolynomialtools#convertcubemaptexturetosphericalpolynomial)
- [CopyTools.GenerateBase64StringFromTexture](/typedoc/classes/babylon.copytools#generatebase64stringfromtexture)

To match how WebGL works there is a [flushFramebuffer](/typedoc/classes/babylon.thinengine#flushframebuffer) call that is automatically performed before reading a texture to be sure you get up to date data. However, if you know your texture is up to date when you call a **readPixels** method, you can avoid this flush (save some tiny bit of perf) by passing the appropriate parameter to the function call (_flushRenderer_ = _false_, see docs). Note that if you are doing the read in **engine.onEndFrameObservable** you don't need to flush, as this observer triggers after the flushing for the current frame has been done.

Note also that currently **readPixels** is slow if `width` is not divisible by 64! Also, it is very slow when reading data from half float textures: use full float textures instead if possible. Speeding those things up is on our roadmap.

## Creation of the WebGPU engine is asynchronous

Creating the engine is also asynchronous in WebGPU. You can do something like this to create a WebGPU engine if supported by the browser, or else a WebGL engine:

```javascript
async function createEngine() {
  const webGPUSupported = await BABYLON.WebGPUEngine.IsSupportedAsync;
  if (webGPUSupported) {
    const engine = new BABYLON.WebGPUEngine(document.getElementById("renderCanvas"));
    await engine.initAsync();
    return engine;
  }
  return new BABYLON.Engine(document.getElementById("renderCanvas"), true);
}
```

Or using the `EngineFactory` helper (it will try first to create a WebGPU engine if supported, then a WebGL engine then a null engine):

```javascript
async function createEngine() {
  return BABYLON.EngineFactory.CreateAsync(document.getElementById("renderCanvas"));
}
```

## Shader code differences

### Array of textures

Array of textures in shader code can't be accessed with a varying index, it must be an immediate value. For eg, `myTextures[0]` / `myTextures[1]` does work but not `myTextures[i]` (i being a variable loop for instance).

### Passing samplers to functions

In shaders, you can't pass samplers to functions:

```javascript
vec4 getPixel(sampler2D sampler, vec2 uv) {
    return texture2D(sampler, uv);
}
```

Calling this function will fail with a compilation error in WebGPU.

To simplify porting existing code we have added a pre-pass shader code inliner which will replace a function call by the code of the function itself. You need to tag the function(s) to be inlined with `#define inline` for the inliner to perform its processing:

```javascript
#define inline
vec4 getPixel(sampler2D sampler, vec2 uv) {
    return texture2D(sampler, uv);
}
```

### Binding values to samplers

WebGPU is less forgiving than WebGL, all sampler variables declared in a shader must have a value bound, even if you don't use that variable, contrary to WebGL. If you get a warning message like "**numBindings mismatch**", it means that you probably defined a uniform sampler variable in the shader code but didn't bind a value to it (by calling something like **setTexture("myvar", texture)** on the shader/material).

### ShaderMaterial

If using a custom attribute in a [ShaderMaterial](/typedoc/classes/babylon.shadermaterial) (or [CustomMaterial](/typedoc/classes/babylon.custommaterial) / [PBRCustomMaterial](/typedoc/classes/babylon.pbrcustommaterial)), it must be declared in the list of attributes used by that shader. For eg, for [ShaderMaterial](/typedoc/classes/babylon.shadermaterial), you must pass its name in the _attributes_ array of the options passed to the constructor. In WebGL you can omit this declaration and it will still work (but as a side-effect, it is not really supported).

In WebGL you could list several times the same attribute when creating a [ShaderMaterial](/typedoc/classes/babylon.shadermaterial) and it would work (it was as if you gave this attribute a single time), but in WebGPU it will fail.

## Miscellaneous

The viewport can't spread outside the framebuffer/texture, contrary to WebGL. So, if you call something like:

```javascript
new BABYLON.Viewport(x, y, w, h);
```

- x, y, w, h must be >= 0 and &lt;= 1.
- x + w must be &lt;= 1
- y + h must be &lt;= 1

The stride of an attribute in a vertex buffer can't be less than 4 bytes, contrary to WebGL. Also, for the time being, position vertex kind must be number/float, it can't be char/int (Int8Array/Int32Array). Try this PG, which works in WebGL but not in WebGPU: <Playground id="#U1CZV3#4" title="Stride of 3 bytes" description="Demonstrate using a byte buffer for position"/>

The `TEXTUREFORMAT_LUMINANCE` format is not supported in WebGPU.



## Introduction
Following the specification from the [GPU for the Web Working Group](https://github.com/gpuweb/gpuweb), we have begun the journey to support this new technology. Our plan is to deliver support with WebGPU and WebGL feature parity in Babylon 5.

![Inspector](/img/extensions/WebGPU.png)

### Benefits of WebGPU
The promise behind [WebGPU](https://developer.chrome.com/en/docs/web-platform/webgpu/#what) is an exceptionally faster API provided through lower level control to system graphics resources from JavaScript. We hope to bring these extra performance improvements to developers in order to create even higher quality 3D web games and experiences through a tool they are already familiar with: Babylon.js.

Some features WebGPU brings to the table are:
* Compute shaders
* Ray tracing ([in-progress](https://github.com/gpuweb/gpuweb/issues/535))
* Improved performance across the board
* and more...

## Progress

See the [dedicated progress page](/setup/support/webGPU/webGPUStatus).

You can also follow our progress on out [GitHub dedicated issue](https://github.com/BabylonJS/Babylon.js/issues/6443).

The current implementation of WebGPU is now merged in the main branch of the Babylon.js [GitHub repository](https://github.com/BabylonJS/Babylon.js).

We are putting in a big effort alongside our next release to implement full support. Every contribution is more than welcome, so feel free to create a PR if you are interested in contributing to the future of high performance game development on the web.

## Potential Issues
Even if we are now far into the development process, we are still subject to potential changes as well as specification uncertainties. We will handle these changes one at a time but as a result we may have to adjust the release schedule accordingly.

We have the full support from the amazing teams implementing the WebGPU into the browsers, so we can work together as needed to make development smoother for all.

## Migration of Existing Games and Apps
As backwards compatibility is one of our pillars, the only difference we wish to have is with the engine initialization which needs to be asynchronous:

```javascript
const engine = new BABYLON.WebGPUEngine(canvas);
await engine.initAsync();
```

## Will WebGL still be supported?
Yes! Support for WebGL and WebGPU will be maintained side by side for the foreseeable future.

## Testing WebGPU
You can refer to [this page](https://github.com/gpuweb/gpuweb/wiki/Implementation-Status) for detailed information on browser support.

Assuming you're using a browser that supports WebGPU, you can try it out yourself in the [Playground](https://playground.babylonjs.com/) 

![WebGPU](/img/extensions/webGPUPlayground.jpg)

Follow the status from the dedicated [Chrome Status Platform Page](https://www.chromestatus.com/feature/6213121689518080).

All demo code is available on [Github](https://github.com/BabylonJS/Website/tree/master/build/Demos/WebGPU), so you can compare both the WebGL and WebGPU versions and take notice that there are currently no differences beside initialization. We will try to keep it this way. :-)

WebGPU Status

Make it work: Current status of the port

Features with incomplete support

Features not working because not implemented yet

Make it fast: Optimizations

Other "nice-to-have" features

Browser Caveats