
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

If you still want to use out-of-bounds values, you can use a material plugin like in this PG: <Playground id="#IIBY03#31" 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.



Currently, most of the main shaders used by **Babylon.js** are written in [WGSL](https://gpuweb.github.io/gpuweb/wgsl/) (the only shader language that WebGPU knows about). That being said, we keep an active compatibility with [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language).

If you decide to write a shader with [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language), **Babylon.js** will detect it and will use internal tools to compile it to [WGSL](https://gpuweb.github.io/gpuweb/wgsl/). It will take some time and will download a WASM library to do the conversion.

It is recommended to write your shaders directly in [WGSL](https://gpuweb.github.io/gpuweb/wgsl/) for faster startup time and smaller download sizes.

For some specific materials like `CustomMaterial` or `PBRCustomMaterial`, to protect backward compatibility, you will need to inject your custom shader code in [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language).

## Using ShaderMaterial to write WGSL code
You can use the `ShaderMaterial` class to write WGSL code in much the same way you use it to write [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) but with some small differences.

Note: if you use the "color" attribute in your shader code, don't add it to the **attributes** property passed to the `ShaderMaterial` constructor! This attribute will be automatically added if a vertex buffer named "color" is attached to the mesh. If you add "color" to the **attributes** array, you will get an error like "Attribute shader location (1) is used more than once".

### Setting the right shader language
You must set the `shaderLanguage` property to `BABYLON.ShaderLanguage.WGSL` in the `options` parameter you pass to the constructor.
For eg:
```javascript
const mat = new BABYLON.ShaderMaterial("shader", scene, {
        vertex: "myShader",
        fragment: "myShader",
    },
    {
        attributes: ["position", "uv", "normal"],
        uniformBuffers: ["Scene", "Mesh"],
        shaderLanguage: BABYLON.ShaderLanguage.WGSL,
    }
);
```

### Using the WGSL shader store
If using the shader store, you must put your WGSL code in `BABYLON.ShaderStore.ShadersStoreWGSL` instead of `BABYLON.ShaderStore.ShadersStore`.

For eg:
```javascript
BABYLON.ShaderStore.ShadersStoreWGSL["myShaderVertexShader"]=`   
    #include<sceneUboDeclaration>
    #include<meshUboDeclaration>
    ...
`;

BABYLON.ShaderStore.ShadersStoreWGSL["myShaderFragmentShader"]=`
    varying vPositionW : vec3<f32>;
    varying vUV : vec2<f32>;
    ...
`;
```

### Declaration of the entry points
You must also declare the entry point for the vertex and fragment shader in a special way.

Vertex:
```wgsl
@vertex
fn main(input : VertexInputs) -> FragmentInputs {
    ...
}

```
Fragment:
```wgsl
@fragment
fn main(input : FragmentInputs) -> FragmentOutputs {
    ...
}
```

### Using pre-defined uniforms
To use the pre-defined uniforms of the scene (`view`, `viewProjection`, `projection`, `vEyePosition`) and mesh (`world`, `visibility`), you must include the appropriate file(s) in the shader code:
```wgsl
#include<sceneUboDeclaration>
#include<meshUboDeclaration>
```
and add the uniform buffer name(s) to the `uniformBuffers` option of the `ShaderMaterial` class constructor:
```javascript
const mat = new BABYLON.ShaderMaterial("shader", scene, {
        vertex: "myShader",
        fragment: "myShader",
    },
    {
        attributes: ["position", "uv", "normal"],
        uniformBuffers: ["Scene", "Mesh"],
        shaderLanguage: BABYLON.ShaderLanguage.WGSL,
    }
);
```

In the WGSL code, you access a uniform by prefixing its name by `scene.` or `mesh.` for the scene or mesh uniforms, respectively:
```wgsl
@vertex
fn main(input : VertexInputs) -> FragmentInputs {
    vertexOutputs.position = scene.viewProjection * mesh.world * vec4<f32>(vertexInputs.position, 1.0);
}    
```

## Special syntax used in WGSL code
Unlike compute shaders that use ordinary WGSL code, the shader code you write for `ShaderMaterial` must use special syntax to work with the existing workflow. To make it easier for developers, the declaration of variables is the same as that used in [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language):
* declaring a varying variable:
```wgsl
varying varName : varType;
```
* declaring an attribute variable:
```wgsl
attribute varName : varType;
```
* declaring a uniform variable:
```wgsl
uniform varName : varType;
```

Contrary to [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language), the inputs and outputs of the vertex/fragment shader are not declared as separate global variables internally, but are defined in some structures which are managed by the engine for you. However, it means that you need a special syntax to access these variables. Here is the mapping between the [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) syntax and the WGSL syntax:
* In the vertex shader:
  * an attribute must be referenced by `vertexInputs.attributeName`
  * `gl_VertexID` => `vertexInputs.vertexIndex`
  * `gl_InstanceID` => `vertexInputs.instanceIndex`
  * a varying must be referenced by `vertexOutputs.varName`
  * `gl_Position` => `vertexOutputs.position`
* In the fragment shader:
  * a varying must be referenced by `fragmentInputs.varName`
  * `gl_FragCoord` => `fragmentInputs.position`
  * `gl_FrontFacing` => `fragmentInputs.frontFacing`
  * `gl_FragColor` => `fragmentOutputs.color`
  * `gl_FragDepth` => `fragmentOutputs.fragDepth`

Notes:
* When using the `uniform varName : varType` syntax, you access the variable by doing `uniforms.varName`, not simply `varName`. The variables declared that way can be set from the javascript code by using the regular methods of the `ShaderMaterial` class (`setFloat`, `setInt`, etc) as with [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language)
* `varType` must use a WGSL syntax, not [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language)! For eg: `varying vUV : vec2<f32>;`
* you must **NOT** add the `@group(X) @binding(Y)` decoration! The system will add them automatically

## Using new objects available in WGSL
You can use the standard WGSL syntax to declare:
* custom uniform buffers:
```wgsl
struct MyUBO {
    scale: f32,
};

var<uniform> myUBO: MyUBO;
```
* storage textures:
```wgsl
var storageTexture : texture_storage_2d<rgba8unorm,write>;
```
* storage buffers:
```wgsl
struct Buffer {
    items: array<f32>,
};
var<storage,read_write> storageBuffer : Buffer;
```
* external textures:
```wgsl
var videoTexture : texture_external;
```

Again, you must **NOT** add the `@group(X) @binding(Y)` decoration! The system will add them automatically.

On the javascript side, you have the corresponding methods to set a value to these variables:
* uniform buffer: `setUniformBuffer(name, buffer)`
* storage texture: same method as for regular textures (`setTexture(name, texture)`)
* storage buffer: `setStorageBuffer(name, buffer)`
* external texture: `setExternalTexture(name, buffer)`

## Important difference from GLSL
The [normalized device coordinates](https://gpuweb.github.io/gpuweb/#coordinate-systems) (NDC) in WebGPU is slightly different from WebGL's. In GLSL, NDC for the z-axis lies in the -1.0 ≤ z ≤ 1.0 range. In WGSL, NDC for the z-axis lies in the 0.0 ≤ z ≤ 1.0 range. If you are using NDC in your shader, please ensure you make the necessary adjustments for the z-axis. There are no differences for the xy axes.

## Examples
This playground is a basic example of using WGSL in a `ShaderMaterial`: <Playground id="#6GFJNR#178" image="/img/playgroundsAndNMEs/pg-6GFJNR-164.png" engine="webgpu" title="Basic example of WGSL with ShaderMaterial" description="Demonstrate how to write WGSL code with the ShaderMaterial class"/>

As when using [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language), `ShaderMaterial` supports morphs, bones and instancing in WGSL. You will need to add the appropriate includes in your code to support these features. See how it is done in this playground (this example also demonstrates how to use a storage texture and a storage buffer): <Playground id="#8RU8Q3#155" image="/img/playgroundsAndNMEs/pg-8RU8Q3-126.png" engine="webgpu" title="Advanced usage of the ShaderMaterial class" description="Demonstrate how to write WGSL code with the ShaderMaterial class to support bones, morphs and instances"/>

You can also use the new in 5.0 baked vertex animation feature as well as clip planes. See: <Playground id="#8RU8Q3#156" image="/img/playgroundsAndNMEs/pg-8RU8Q3-106.png" engine="webgpu" title="Using BVA and clip planes in WGSL" description="Demonstrate how to write WGSL code with the ShaderMaterial class to support baked vertex animations and clip planes"/>

WebGPU uses a special texture object for fast video playback (an "external texture"). Our [VideoTexture](/typedoc/classes/babylon.videotexture) class takes advantage of this, but if you want to do it yourself, this playground shows how to use the `ShaderMaterial` class to implement video playback with `texture_external`: <Playground id="#6GFJNR#179" image="/img/playgroundsAndNMEs/pg-6GFJNR-163.png" engine="webgpu" title="Video playing with the ShaderMaterial class" description="Demonstrate how to play videos using external texture in WGSL"/>



*Note that we will use Chrome Canary as our gauge browser for WebGPU features as other browsers are still lagging in terms of feature support as of this writing (2024/10/25).*

## 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
* [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 / Chrome Canary don't support all WebGPU features yet (or some others are not fully functional yet), 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.
