

## Make it work: Current status of the port
The implementation in WebGPU is complete and, besides a few exceptions, all features are available both in WebGPU and WebGL:

### Features with incomplete support
* [Point Cloud System](/typedoc/classes/babylon.pointscloudsystem)
  * WebGPU does not support a point size different from 1, so setting the point size to a value other than 1 will not be taken into account
* [WebGPU in WebXR](/features/featuresDeepDive/webXR/webGPUXR)
  * WebGPU-XR is experimental and requires browser support for `XRGPUBinding` projection layers and `XRGPUSubImage.prototype.getViewDescriptor`
  * WebGPU-XR multiview, Raw Camera Access, Space Warp, and GPU-optimized Depth Sensing are not currently supported
  * Quad layers require the runtime to expose the optional `XRGPUBinding.createQuadLayer` and `XRGPUBinding.getSubImage` methods

### Features not working because not implemented yet
* Support for triangle fan / line loop drawing mode
  * WebGPU does not support those modes, so we will need to emulate them with triangle strip and line strip

## 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 / Chrome Canary do not support all WebGPU features yet, and some others are not fully functional, so here are some caveats:
* GPU timing in the **Inspector** does not work because timestamp queries are currently disabled in Chrome. You can start Chrome with the `--enable-dawn-features=allow_unsafe_apis` flag if you want to enable them. You can also add the `--enable-webgpu-developer-features` flag for more precise timing.



This page describes the breaking changes and differences in behavior between WebGL and WebGPU.

We try to avoid breaking changes in the core library as much as possible, but sometimes we cannot avoid them. With the major change that WebGPU introduces as a new engine, you need to be aware of a number of things when porting 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. As a result, all methods that read pixels from textures, even in WebGL mode, 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, a [flushFramebuffer](/typedoc/classes/babylon.thinengine#flushframebuffer) call is automatically performed before reading a texture to make sure you get up-to-date data. However, if you know your texture is already up to date when you call a **readPixels** method, you can avoid this flush, and save a small amount of performance, 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 do not need to flush, because this observer runs after the flush for the current frame has been done.

Note also that **readPixels** is currently slow if `width` is not divisible by 64. It is also very slow when reading data from half-float textures, so use full-float textures instead when possible. Improving these cases 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 the browser supports it, or a WebGL engine otherwise:

```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 you can use the `EngineFactory` helper. It first tries to create a WebGPU engine if supported, then a WebGL engine, and finally a null engine:

```javascript
async function createEngine() {
  return BABYLON.EngineFactory.CreateAsync(document.getElementById("renderCanvas"));
}
```

### WebGPU engines intended for WebXR

WebGPU has no post-creation operation that makes an adapter XR-compatible. If the engine may enter WebXR, pass `xrCompatible: true` when constructing it:

```javascript
const engine = new BABYLON.WebGPUEngine(canvas, { xrCompatible: true });
await engine.initAsync();
```

WebGPU-XR additionally requires the experimental `XRGPUBinding` projection path, `XRGPUSubImage.prototype.getViewDescriptor`, and the WebXR Layers feature. Babylon does not replace an existing WebGPU engine or scene with WebGL if XR entry fails. Applications that offer a fallback must select WebGL before scene and resource creation, or fully dispose and rebuild/reload the application with WebGL. See [WebGPU in WebXR](/features/featuresDeepDive/webXR/webGPUXR).

## Shader code differences

### Array of textures

Arrays of textures in shader code cannot be accessed with a varying index; the index must be an immediate value. For example, `myTextures[0]` and `myTextures[1]` work, but `myTextures[i]` does not, where `i` is a loop variable.

### Passing samplers to functions

In shaders, you cannot 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 that replaces a function call with the code of the function itself. You need to tag the function or functions to be inlined with `#define inline` for the inliner to process them:

```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 bound value, even if you do not use that variable. If you get a warning message like "**numBindings mismatch**", it probably means you defined a uniform sampler variable in the shader code but did not bind a value to it by calling something like **setTexture("myvar", texture)** on the shader or material.

### ShaderMaterial

If you use a custom attribute in a [ShaderMaterial](/typedoc/classes/babylon.shadermaterial), [CustomMaterial](/typedoc/classes/babylon.custommaterial), or [PBRCustomMaterial](/typedoc/classes/babylon.pbrcustommaterial), it must be declared in the list of attributes used by that shader. For example, 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 that side effect is not really supported.

In WebGL, you could list the same attribute several times when creating a [ShaderMaterial](/typedoc/classes/babylon.shadermaterial), and it would work as if you had provided the attribute only once. In WebGPU, this fails.

## Miscellaneous

Unlike WebGL, the viewport cannot extend outside the framebuffer or texture. 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

If you still want to use out-of-bounds values, you can use a material plugin like in this PG: <Playground id="#IIBY03#33" engine="webgpu" title="Viewport out-of-bounds values" description="Demonstrate how to support a viewport with out-of-bounds values in WebGPU"/>

The `TEXTUREFORMAT_LUMINANCE` format is not supported in WebGPU.



## Introduction
Since the Babylon.js 5.0 release in May 2022, WebGPU support has been available and backward compatible with the WebGL implementation of the engine. It was a huge milestone after many iterations on the specification from the [GPU for the Web Working Group](https://github.com/gpuweb/gpuweb), along with close collaboration with the teams implementing WebGPU in browsers. In 2024, we also rewrote all core engine shaders in native WGSL to avoid the use of TintWASM in full WGSL applications.

![Inspector](/img/extensions/WebGPU.webp)

### Benefits of WebGPU
The promise behind [WebGPU](https://developer.chrome.com/en/docs/web-platform/webgpu/#what) is a faster API, provided through lower-level control over system graphics resources from JavaScript, along with new capabilities. We hope to bring these improvements to developers so they can 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).

The current implementation of WebGPU is merged in the main branch of the Babylon.js [GitHub repository](https://github.com/BabylonJS/Babylon.js).

WebGPU is also supported by [Node Material and can be defined in the editor](/features/featuresDeepDive/materials/node_material/nodeMaterial#using-node-material-with-webgl-and-webgpu).

## Migration of Existing Games and Apps
Because backward compatibility is one of our pillars, the only difference is that engine initialization must be asynchronous:

```javascript
const engine = new BABYLON.WebGPUEngine(canvas);
await engine.initAsync();
```

## Canvas tone mapping and output color space

The [`WebGPUEngineOptions`](/typedoc/interfaces/BABYLON.WebGPUEngineOptions) interface can pass tone-mapping and color-space settings to the browser's WebGPU canvas:

- `canvasToneMapping` accepts `{ mode: "standard" }` or `{ mode: "extended" }`. If you omit it, the browser uses standard tone mapping.
- `canvasColorSpace` accepts `"srgb"` or `"display-p3"`. If you omit it, the browser uses sRGB.

The following example requests extended tone mapping and Display P3 output:

```javascript
const engine = new BABYLON.WebGPUEngine(canvas, {
    swapChainFormat: "rgba16float",
    canvasToneMapping: { mode: "extended" },
    canvasColorSpace: "display-p3",
});
await engine.initAsync();
```

Extended tone mapping can present HDR output, but the canvas setting alone does not create an HDR image. It requires the `"rgba16float"` swap-chain format, support from the browser and display, and a rendering pipeline that keeps color values above 1. It does not replace tone mapping in materials or post-processes.

Display P3 changes how the browser interprets output color values. It does not convert the scene's colors to Display P3. The rendering pipeline must produce the correct values for that color space.

Babylon.js uses these settings again whenever it configures the canvas context. Existing applications that omit them keep the browser's standard tone-mapping and sRGB defaults.

## Is WebGL still supported?
Yes! Support for WebGL and WebGPU is maintained side by side for the foreseeable future.

## WebXR support

Babylon.js supports experimental WebGPU-backed WebXR through `XRGPUBinding`. WebGPU support alone does not imply WebGPU-XR support: check the target immersive session mode and `WebXRSessionManager.IsWebGPUXRSupported` separately. The WebGPU-XR getter verifies both the projection binding APIs and `XRGPUSubImage.prototype.getViewDescriptor`, which Babylon requires when creating projection texture views.

A WebGPU engine intended for XR must be created with `new WebGPUEngine(canvas, { xrCompatible: true })`, and the WebXR Layers feature must be enabled before entering XR. Because Babylon cannot swap an existing WebGPU scene to WebGL, choose the engine before creating the scene and its resources. See [WebGPU in WebXR](/features/featuresDeepDive/webXR/webGPUXR) for setup, fallback guidance, and current limitations.

## Testing WebGPU
You can refer to [this page](https://github.com/gpuweb/gpuweb/wiki/Implementation-Status) for detailed information on browser support.

Assuming you are using a browser that supports WebGPU, you can try it out yourself in the [Playground](https://playground.babylonjs.com/).

![WebGPU](/img/extensions/webGPUPlayground.webp)

All demo code is available on [GitHub](https://github.com/BabylonJS/Website/tree/master/build/Demos/WebGPU), so you can compare the WebGL and WebGPU versions and note that there are currently no differences besides 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