
Here are listed some miscellaneous tips to optimize WebGPU for speed.

## Avoid creating too many resources each frame
If you call `engine.enableEffect()`, make sure to pass a `DrawWrapper` to it and not an `Effect`. Else some WebGPU resources will be created each frame.

To check you are not creating unnecessary resources, when your application is running and is "stabilized" (meaning you are not creating new objects in the last frame) check `engine.countersLastFrame` and make sure `numEnableEffects` is 0. `numEnableEffects` is > 0 when you call `engine.enableEffect()` with an `Effect` and not a `DrawWrapper`: only `numEnableDrawWrapper` should be non 0.

## Optimize post processes
If setting manually the `textureSampler` property in a `onApply` observer, set `externalTextureSamplerBinding = true` for the post process to optimize performances.

If possible, don't set the `reusable` parameter of the constructor of `PostProcess` to `true`. Else there will be a continuous swapping between two textures used as the render target of the post process, which will be especially bad when in non compatibility mode as the cached render bundle will be recreated each frame.



WebGPU can be run in a **non compatibility mode** (NCM - also called **fast path**) that can allow for better performances, depending on your scene.

The `WebGPUEngine.compatibilityMode` property is a switch which is `true` by default. In this mode, the WebGPU engine is in a full **compatibility mode** (CM) with WebGL, meaning all scenes that can be rendered with WebGL can also be rendered by WebGPU without any changes on your side.

When setting this property to `false` you switch to the **non compatibility mode** (NCM), allowing the engine to use another code path which may improve performances at the cost of some possible re-organisation of your code.

## Description
What this mode does is that it builds an object called a **bundle** which holds the commands to draw a mesh (more precisely a submesh) in a given context and then reuse this bundle each time the mesh must be drawn in this context. Building this bundle has a cost, so the bundle must have a lifetime long enough to compensate for this cost: if the bundle is recreated on each frame you will actually suffer a performance penalty by using the NCM!

A bundle must be recreated when a number of things happen: you change the material, you change some global context directly on the engine, you update some vertices data, etc. You can know how many bundles are recreated and how many are reused for the last frame by looking at the `engine.countersLastFrame` property:
```javascript
> engine.countersLastFrame
> {numEnableEffects: 0, numEnableDrawWrapper: 2, numBundleCreationNonCompatMode: 0, numBundleReuseNonCompatMode: 2}
```
What you are interested in are the two `numBundleXXX` counters:
* `numBundleReuseNonCompatMode` is the number of bundles that have been reused in the last frame
* `numBundleCreationNonCompatMode` is the number of bundles that have been created in the last frame

The lower `numBundleCreationNonCompatMode` is the better: the best case is when this counter is 0. Of course, depending on what you are doing, it won't be possible to have this counter always equal to 0 but you should try to have it as low as possible.

**Note**: if both counters are 0 it means you are not in NCM, you should do `engine.compatibilityMode = false` to switch to NCM.

See last section of this page for things to watch for that could lead to bundle (re)creations and how to modify your code to avoid this.

## Caveats
When in NCM mode, theoritically it *may* be possible that some things don't work as expected (for eg. that changing a material would not work), in which case calling `scene.resetDrawCache()` would fix the problem (or `mesh.resetDrawCache()` if the problem only impacts a single mesh).

However, this should happen only very infrequently (see next section) in practice: if it does, please report to the forum so we can analyze the case and see if it can be made to work automatically without having to call `resetDrawCache`.

Also, even if you are able to achieve low (or even 0) bundle recreations each frame you may not see a performance improvement over the **compatibility mode**. It will depend on your scene and you should do some benchmarking to see if NCM improves things for you.

## Do/Don't in non compatibility mode (NCM)
* if two or more cameras are rendering into the same RTT (using the `Camera.outputRenderTarget` property), set `rtt.renderPassId = undefined` so that `camera.renderPassId` is used for each camera instead of `rtt.renderPassId` for both cameras, leading to bundles recreation.
* if you are using skeletons, make sure a material won't be linked to several different skeletons, meaning a material won't be used by several meshes which are not all using the same skeleton. In that case, clone the material as many times as necessary. Same thing with morph targets.
* `Material.needDepthPrePass` does work in NCM but will always create new bundles each frame.
* If you update one of these material properties after you switched to the NCM you must reset the draw cache for these changes to take effect (either by calling `mesh.resetDrawCache()` or `scene.resetDrawCache()`): `sideOrientation`, `disableDepthWrite`, `forceDepthWrite`, `depthFunction`, `disableColorWrite`, `zOffset`, `stencil`
* If you update the `samples` property of a post process/RTT, you must call `scene.resetDrawCache()` afterwards to avoid a rendering with the new value (but the old bundles created with the old `samples` value), else you will get an error like `Attachment state of renderBundles[0] ([RenderBundle]) is not compatible with attachment state of [RenderPassEncoder].`.
* Not working in NCM (meaning: don't switch to NCM if you want to use them else your program won't work as expected):
  * Occlusion queries. They don't work because the order of the draws and the queries must be preserved, something not possible in NCM because all draws are postponed to the end of the frame when calling `executeBundles()` whereas queries are executed at the point they are called.
  * `Material.separateCullingPass = true` does not work because of the way it is currently implemented.

## Case analysis
Below is a list of all the playgrounds from our validation test suite that recreated one or more bundles each frame when we first tested them in the **non compatibility mode**. We explain why they were creating bundles and how we fixed them (when that was possible). You can see the fixed code by appending the PG number (given inside the parenthesis after the PG name) to the Playground url (https://playground.babylonjs.com/).

### WebGPU list (webgpu.json)

* **sphere with custom shader to display wireframe using glow layer** (#Y05E2C#6)
    * why: a property of a material is changed two times in a frame, to change the color depending on where the mesh is drawn (the glow layer or the regular rendering)
    * solution: use two materials, one for each case
* **particle system matrix like** (#WL44T7)
    * why: a new particle system is recreated to replace one that has reached its time to live
    * solution: none. New particle systems are recreated regularly as part as the normal working of the PG, so it's expected that bundles are created regularly too

### Default list (config.json)

* **Nested BBG, Chibi Rex, Yeti, Bones, GLTF Serializer Morph Target Animation Group** (#ZG0C8B#5, #QATUCH#18, #QATUCH#19, #7EC27T#3, #T087A8#29)
    * why: use same material for different meshes that are using different skeletons
    * solution: use as many materials as the number of skeletons
* **Solid particle system** (#WCDZS#92)
    * why: SPS mesh is pickable. When the mesh is pickable, the vertex attributes (position, normal) are updated by calling `mesh.updateVerticesData` which dirtifies the material and ends-up recreating the bundle used by the fast path code
    * solution: sets the mesh as not pickable
* **Ribbon morphing** (#ACKC2#1)
    * why: updating the position attribute each frame
    * solution: none at the time, the `CreateTube` (and all functions of `MeshBuilder`) are using `getVerticesData` / `updateVerticesData` to update an existing instance, the latter method triggering a `markAsAttributeDirty` call on the material. We would need to update the GPU buffer directly without using `updateVerticesData`, but by doing so we would loose the baking CPU array which is necessary for the mesh builder methods to work (the `Buffer.updateDirectly` method is clearing the `_data` property but `getVerticesData` works only if this property is not `null`)
* **Custom render target** (#TQCEBF#3)
    * why: changing the material used by a `RenderTargetTexture` in `onBeforeRender` and reseting it in `onAfterRender`
    * solution: use `RenderTargetTexture.setMaterialForRendering` instead of `onBeforeRender` / `onAfterRender`
* **Advanced shadows, Advanced shadows (right handed), Reverse depth buffer and shadows** (#SLV8LW#3, #B48X7G#64, #WL4Q8J#20)
    * why: the same material is used for the 8 floors (for **Reverse depth buffer and shadows** it's the boxes/sphere/knot which are reusing the same material). Each floor + box is lit by a specific light which has its own shader generator. When a floor is drawn, the shadow sampler corresponding to the shadow generator is bound to the shader, and because all floors are using the same material, setting a new shadow sampler resets the cache
    * solution: use a different (cloned) material for each floor
* **Motion Blur, Instances + GBR + motion blur** (#E5YGEL#20, #YB006J#403)
    * why: the number of spheres (of trees in **Instances + GBR + motion blur**) visible each frame is never the same because they are moving. The `LeftOver` uniform buffer that stores the motion blur parameters for each sphere has a number of GPU buffers internally, one per sphere. When the fast path bundle is created, one buffer is associated to the bundle (buffer #0 for first sphere displayed, #1 for second sphere and so on). However, the next frame, the GPU buffer that will be used for a given sphere may be different because the buffers are reused starting from the first one: the first buffer is used for the first sphere displayed, second buffer is used for the second sphere displayed, etc. So, if the spheres are not displayed in the same order, the bundle(s) will be recreated
    * solution: none at the time. For the PG, we simply set `alwaysSelectAsActiveMesh=true` so that the number of spheres handled by the system does not vary
* **Thin instances + motion blur + manual** (#HJGC2G#132)
    * why: `thinInstanceSetBuffer` was called each frame, which is (re)creating a vertex buffer, which in turn is flagging the material as "attribute dirty"
    * solution: use `thinInstanceBufferUpdated` instead
* **Multi cameras and output render target** (#BCYE7J#31)
    * why: `cameraRTT1` and `cameraRTT2` are rendering into the same RTT (using their `outputRenderTarget` property), but when rendering in a RTT the render pass id which is used is `RTT.renderPassId`, meaning the meshes are rendered two times (because two cameras) with the same `renderPassId`, leading to bundle recreations (because the scene ubo is not the same in both cases as it stores the camera view/projection)
    * solution: remove the `RTT.renderPassID` property (`RTT.renderPassID = undefined`) => in that case, the `camera.renderPassId` value will be used instead
* **Order independent transparency** (#1PLV5Z#104)
    * why: not using `useRenderPasses = true` on the depth peeling renderer
    * solution: set `scene.depthPeelingRenderer.useRenderPasses = true;`



**Snapshot rendering** is a new rendering mode available starting with Babylon.js v5.0. Only WebGPU supports it: activating this mode in WebGL has no effect.

## Description
The snapshot rendering (SR) feature improves performances in some specific scenarios described below.

It works by recording the draw calls during one frame and by replaying this recording for all subsequent frames. So, the scene should be mostly static for this mode to work as expected. Note that this mode can be enabled or disabled whenever you want. So, if at some point something must change in the scene that is not supported by SR, you can disable the mode, apply the changes and re-enable SR afterwards.

Note that the performance improvement is on the javascript side only: the GPU perf will be more or less the same with or without SR enabled (you could still see some small GPU perf improvements, though, depending on the browser).

The perf improvements can be quite large, especially when using the fast SR mode (see below for explanations regarding the SR modes). Here are some figures collected with the first PG listed in the **Examples** section:

| SR disabled | Standard mode | Fast mode | 
|-------------|---------------|-----------|
| ![SR disabled](/img/resources/snapshot_rendering/sr_disabled.png) | ![SR disabled](/img/resources/snapshot_rendering/sr_standard.png!241x247) | ![SR disabled](/img/resources/snapshot_rendering/sr_fast.png!245x243) |

## Enabling snapshot rendering mode
The snapshot rendering mode is enabled by setting:
```javascript
engine.snapshotRendering = true;
```
When doing this, the next frame will be recorded (and of course also displayed as usual!) and the recorded snapshot will be replayed in all subsequent frames until you either disable the mode or use `engine.snapshotRenderingReset()`. If calling the latter, a new snapshot will be created the next frame that will replace the current snapshot.

Calling `engine.snapshotRenderingReset()` is the way to apply changes not supported by the SR current mode (see available modes in the next section): apply your changes and call this function. That will destroy the current snapshot and instruct the system to create a new snapshot by recording the draw calls of the next frame (which will contain your changes). In effect, it is the same than doing `engine.snapshotRendering = false; engine.snapshotRendering = true;`. The first assignment will stop/destroy the current snapshot and the second will ask the system to record the draw calls when rendering the next frame. Of course, for this to work, your changes should be in effect right at the next frame! If, for eg., you import a new mesh, it will probably take more than a frame to be added to the scene. So, you should make sure to call `engine.snapshotRenderingReset()` once you know the next frame will render the scene with the new state.

## Standard and Fast modes
There are two different modes available when SR is enabled:
* Standard mode (`Constants.SNAPSHOTRENDERING_STANDARD`). In this mode, the uniform buffers are still updated so some kind of `dynamicity` are still supported: you can update some parameters of a material, for eg, and it will work.
* Fast mode (`Constants.SNAPSHOTRENDERING_FAST`). In this mode, only the scene uniform buffer is updated automatically by the system (meaning moving the camera works as expected). You can still update the uniform buffers of meshes "by hand", so moving/rotating meshes are also supported (see examples below).

Whatever the mode, as the draw calls of a given frame are recorded and replayed for all subsequent frames, adding or removing meshes won't work. You will need to disable the SR mode if you want to add/remove meshes and re-enable it afterwards.

## Caveats

### Always set `alwaysSelectAsActiveMesh` to `true`
Given how SR works, you will probably always want to set `alwaysSelectAsActiveMesh = true` to all your meshes because if this property is `false` (default value) and the mesh is not displayed when recording the snapshot, no draw calls will be recorded for this mesh, meaning that if you move the camera later on that should make this mesh visible, it still won't be visible.

### Statistics in the Inspector
In the fast SR mode, most of the regular javascript code is skipped, so the statistics display by the inspector in the **COUNT** section won't be accurate: all the **Active XXX** counters as well as **Total vertices** will stay at 0.

### When to use
It's hard to list everything that will work/won't work depending on the mode, so the easiest way to use this new feature is to enable it and see if everything works as expected once enabled (try first fast mode, then stardard mode). As explained above, if you need to update something at some point in time and the current SR mode can't handle it, you can always disable SR, apply the changes and re-enable SR.

eCommerce sites may greatly benefit from this feature as the scene is normally quite small with everything visible on screen. Also, there's generally not a lot dynamicity and when something needs to be updated it's a "one shot" update, so either calling `snapshotRenderingReset` or disabling temporarily the feature should work.

### Enable the snapshot rendering mode at the right time
Make sure everything is ready in your scene to be rendered the next frame after you set `engine.snapshotRendering = true`! Indeed, once you set the `snapshotRendering` to `true`, the next frame is recorded and replayed afterwards. If some textures (for eg) were not ready at that time, the mesh won't be rendered in the frame that is recorded and so won't never be visible. You should probably always set `engine.snapshotRendering = true` inside a `scene.executeWhenReady(...)` callback.

## Examples
Here's a PG that demonstrates using the snapshot rendering feature: <Playground id="#SYQW69#1092" engine="webgpu" title="Snapshot rendering" description="Demonstrate how to use the snapshot rendering modes"/>

You can choose to disable or enable standard / fast SR mode. Depending on the mode, you will see the javascript time it takes to render a frame (**Frame total**) and the virtual fps (the fps you would have if there was no GPU rendering / the fps was not capped by the browser - it is simply `1000/Frame total`).

In fast mode, animating light / updating the bias would not work for the reasons explained above. When you update:
* the **bias**, the PG calls `engine.snapshotRenderingReset()` so that the bias is taken into account for the next frame and the snapshot is recreated at that time too
* the **Animate light** checkbox, the PG switches to standard SR mode until you uncheck the box. It happens moving the light does work in standard SR mode: had it not work, we would have switched to SR disabled mode instead.

Note also that in the fast SR mode you must handle the update of the position of the sky yourselves because the uniform buffers are not updated by the system (except for the scene buffer). See the **Advanced usages for the fast mode** section for more detail.

Here's another PG using the glow layer: <Playground id="#LRFB2D#182" engine="webgpu" title="Snapshot rendering with glow layer" description="Demonstrate how to use the snapshot rendering standard mode with glow layer"/>

This PG is using the standard SR mode because the fast mode does not work (try to set the fast mode and see for yourself - however, see next section for a way to make it work). Also, when a resize kicks in, we need to disable the SR mode and re-enable it only when the glow layer had time to recreate its internal texture with the new size. That's why we use a `setTimeout(..., 1)` to re-enable the SR mode.

## Advanced usages for the fast SR mode
The fast SR mode is the most interesting mode as your scene can be handled several order of magnitude faster than with SR disabled (or even using the standard SR mode).

Here are a number of ways to overcome some of its limitations.

### Updating position/rotation/scaling/visibility properties of meshes
The world matrix and the `visibility` property of a mesh is stored in a specific `Mesh` uniform buffer. In the fast SR mode, this uniform buffer is not updated automatically, so if you update the `position`/`rotation`/`scaling` or the `visibility` property it won't have any effect on the screen.

You should call `mesh.transferToEffect(world)` to update the uniform buffer.

Here's an example: <Playground id="#7YW416#7" engine="webgpu" title="Update mesh matrix in fast SR mode" description="Demonstrates how to update the position/rotation/scaling/visibility properties of a mesh in fast snapshot rendering mode" image="/img/playgroundsAndNMEs/pg-7YW416-3.png"/>

### Using the glow layer
As demonstrated in the **Examples** section above the glow layer does not work out of the box in the fast SR mode. With a bit of manual work it can be made to work, though:

<Playground id="#LRFB2D#218" engine="webgpu" title="Use glow layer in fast SR mode" description="Demonstrates how to make the glow layer work in fast snapshot rendering mode"/>

You will need to call the `updateEffectLayer` method each time the camera or the meshes of the glow layer move/rotate. If only a subset of the meshes are in the glow layer, you can change the method to loop through this reduced list instead of looping over all the meshes of the scene.

### Animating bones
To make skeleton animations work in the fast SR mode, you simply need to call the `prepare` method on the skeletons you want to animate:

<Playground id="#WGZLGJ#4072" engine="webgpu" title="Use bones in fast SR mode" description="Demonstrates how to make bones work in fast snapshot rendering mode"/>



This section will show you how you can use some specific features to optimize your scenes when using the WebGPU engine.


Here are listed the current limitations of the WebGPU specification/implementation as of 2022/01/16.

## Non linear-filterable 32 bits float texture 
32 bits float textures are not linear-filterable (see [List of texture formats](https://www.w3.org/TR/webgpu/#plain-color-formats)), meaning you can't use the bi/tri linear filtering with them, for eg. You will need to use 16 bits float textures instead, until the spec (or an extension) adds support for it.

## Low number of varying support
Chrome (which is the only browser supported by Babylon.js at this time because of the other browsers lagging behind in term of the WebGPU spec implementation) only supports 14 "varyings", meaning variables that are created in the vertex shader and reused in the fragment shader.

That means that the `kernelBlur` shader is more limited than in WebGL in case your GPU would support more than 14 varyings (for eg, the GTX1080 supports up to 30 of them).

It also limits the complexity of node materials: some materials that would work in WebGL won't work in WebGPU because of that.


WebGPU Optimizations

Coming next

WebGPU Non Compatibility Mode

Learn how to use the non compatibility mode for faster scene display

WebGPU Snapshot Rendering

Learn how to use snapshot rendering for faster scene display

WebGPU Miscellaneous Optimizations

Learn how to optimize WebGPU for speed