
This class implements a cache of GPU bind groups to avoid recreating them each frame.

## Cache implementation
The cache is a node tree:
```typescript
class WebGPUBindGroupCacheNode {
    public values: { [id: number]: WebGPUBindGroupCacheNode };
    public bindGroups: GPUBindGroup[];

    constructor() {
        this.values = {};
    }
}

export class WebGPUCacheBindGroups {
    private static _Cache: WebGPUBindGroupCacheNode = new WebGPUBindGroupCacheNode();
    ...
}
```
The `id` key in the `values` object is the ID of a bind group resource: a uniform or storage buffer, a sampler, or a texture. The `id` value for the uniform or storage buffer and texture is simply the `uniqueId` property of the corresponding class (`DataBuffer.uniqueId` and `InternalTexture.uniqueId / ExternalTexture.uniqueId`, respectively). For the sampler, it is the sampler hash code, computed by `WebGPUCacheSampler.GetSamplerHashCode()`. The cache is traversed and built by looping over all the buffers, samplers, and textures used by a shader, which is encapsulated in a `WebGPUPipelineContext`, in that order.

## Limits of the implementation
The location of a resource, meaning the group and binding indices in the `[[group(G), binding(B)]]` syntax, is not factored into the ID, and the IDs are not *globally* unique because they do not come from the same pool: there is a separate pool for the buffer and texture `uniqueId` property. So, theoretically, collisions could occur where two sets of resources point to the same cache entry. In practice, this is very unlikely to happen. Making the cache foolproof would also make it slower, and the WebGPU implementation already pays a significant cost for managing caches for some objects, mainly bind groups and render pipelines.

Also note that all uniform buffers have an offset of 0 in Babylon, and we do not have a use case where the same buffer would be used with different capacity values. That means we only need to take the buffer ID into account in the cache, not its offset or size.

## Optimization
The cache includes an optimization that simply returns the existing bind groups if the draw and material contexts have not changed since the last cache query. The draw context holds the list of uniform and storage buffers, and the material context holds the list of textures and samplers used by the shader. If those lists have not changed, the previously created bind groups are still valid.

## Monitoring the performances
Cache performance can be assessed by looking at these properties. Each property should be prefixed by `BABYLON.WebGPUCacheBindGroups.`:

| property | description |
| ---------| ----------- |
| NumBindGroupsCreatedTotal | Total of bind groups created since the start of the program |
| NumBindGroupsCreatedLastFrame | Number of bind groups created during the last frame - for best cache usage this value should be 0 on average |
| NumBindGroupsLookupLastFrame | Number of bind groups retrieved by traversing the cache |
| NumBindGroupsNoLookupLastFrame | Number of bind groups retrieved without traversing the cache because no changes in buffers/textures/samplers occurred since the last cache query for this shader |



This class implements a cache of GPU render pipelines to avoid recreating them each frame.

## Cache implementation
The cache is a node tree with the same structure as the bind group cache:
```typescript
class NodeState {
    public values: { [id: number]: NodeState };
    public pipeline: GPURenderPipeline;

    constructor() {
        this.values = {};
    }
}

export class WebGPUCacheRenderPipelineTree {
    private static _Cache: NodeState = new NodeState();
    ...
}
```
The difference is that the IDs encode the pipeline state. Because a pipeline is defined by many states, we need several IDs. Currently, the list is:
```javascript
enum StatePosition {
    StencilReadMask = 0,
    StencilWriteMask = 1,
    DepthBias = 2,
    DepthBiasSlopeScale = 3,
    DepthStencilState = 4,
    MRTAttachments1 = 5,
    MRTAttachments2 = 6,
    RasterizationState = 7,
    ColorStates = 8,
    ShaderStage = 9,
    TextureStage = 10,
    VertexState = 11, // vertex state will consume positions 11, 12, ... depending on the number of vertex inputs

    NumStates = 12
}
```
So, the first node (`_Cache.values`) holds the stencil read mask values, the second node (`_Cache.values[stencilReadMaskValue]`) holds the stencil write mask values, the third node (`_Cache.values[stencilReadMaskValue].values[stencilWriteMaskValue]`) holds the depth bias values, and so on.

To find a pipeline in the cache, we simply start from the root node, look up the `values` property with the current `stencilReadMask` value, then look up the `values` property of that node with the current `stencilWriteMask` value, and so on until we have traversed all the states.

## Optimization
The state positions are ordered so that the states least likely to change from one pipeline to another are listed first. This is because we maintain a pointer, `_stateDirtyLowestIndex`, that contains the lowest index of all the states that have been dirtied, meaning the states that have changed since the last pipeline lookup. Before querying the cache, we traverse it from this index instead of from 0. So, the higher `_stateDirtyLowestIndex` is, the better the performance, because we traverse fewer nodes to find the pipeline in the cache.

Note that we tried an implementation where render pipelines were recorded in a hash map and the lookup key was a string concatenation of the state values, see the class `WebGPUCacheRenderPipelineString`. We dropped it because the node-tree implementation was faster, around 2x faster at the time the comparison was made. The code has changed since then, so we should probably run new tests, but I still think the node tree is faster than the hash map.

One last note: the `values` property is a regular object, not a `Map`, because in our tests with Chrome, using an object was faster.

## Monitoring the performances
Cache performance can be assessed by looking at these properties. Each property should be prefixed by `BABYLON.WebGPUCacheRenderPipeline.`:

| property | description |
| ---------| ----------- |
| NumCacheHitWithoutHash | Number of times a render pipeline has been retrieved without even traversing the cache because there were no state changes since the last lookup: the last pipeline has been returned |
| NumCacheHitWithHash | Number of times a render pipeline has been retrieved by traversing the cache |
| NumCacheMiss | Number of times a new render pipeline has been created because it was not existing in the cache yet |
| NumPipelineCreationLastFrame | Number of render pipelines created during the last frame - new pipelines should not be created continuously so on average this value should be 0 |



## Validation tests
These validation tests are excluded from WebGPU because some features are not yet implemented in Babylon.js:
* **GLTF Mesh Primitive Mode (0)** and **GLTF Mesh Primitive Mode (1)**: line loop / triangle fan not implemented yet
* **GLTF Buggy with Meshopt Compression**: formats other than `float` for the vertex buffers (*position*, *normal*, *uv*, ...) are not supported yet

When the features are implemented, the corresponding validation tests should be re-enabled.

The **Self shadowing** validation test generates rendering errors, but it is still acceptable because there are fewer than 2.5% errors. This happens because it uses an exponential shadow map whose parameters, especially `depthScale`, depend on the precision of the depth map. In WebGL, we use a 32-bit float texture, but in WebGPU it is only a half-float texture because linear filtering of 32-bit float textures is not supported, at least for the time being:

![WebGPU chart](/img/extensions/webgpu/webgpuValidationTestSelfShadowing.webp)

**Note to core developers: YOU SHOULD RUN THE VALIDATION TESTS LOCALLY OFTEN BECAUSE THEY ARE NOT RUN ON THE AZURE SERVERS!**

Run both the:
* WebGPU tests: http://localhost:1338/tests/validation/?list=webgpu&engine=webgpu
* Standard tests: http://localhost:1338/tests/validation/?list=config&engine=webgpu

You should also run them in the "check resource creation" mode: see [Check Resource Creation - WebGPU only
](/contribute/toBabylon/validationTests#check-resource-creation---webgpu-only).

## TintWASM
You should update the **TWGSL** (Tint WASM) module regularly so that it stays in sync with the **Tint** source code.

* TintWASM module: https://github.com/syntheticmagus/twgsl
* Tint repository: https://dawn.googlesource.com/tint



This section explains how WebGPU has been implemented in Babylon.js. It may be useful for users who want to contribute to the engine or simply understand what is going on under the hood.


Here are some miscellaneous tips for optimizing WebGPU for speed.

## Avoid creating too many resources each frame
If you call `engine.enableEffect()`, make sure to pass a `DrawWrapper` to it, not an `Effect`. Otherwise, some WebGPU resources will be created each frame.

To check that you are not creating unnecessary resources, once your application is running and has stabilized, meaning you did not create new objects in the last frame, check `engine.countersLastFrame` and make sure `numEnableEffects` is 0. `numEnableEffects` is greater than 0 when you call `engine.enableEffect()` with an `Effect` instead of a `DrawWrapper`. Only `numEnableDrawWrapper` should be nonzero.

## Optimize post processes
If you set the `textureSampler` property manually in an `onApply` observer, set `externalTextureSamplerBinding = true` on the post-process to improve performance.

If possible, do not set the `reusable` parameter of the `PostProcess` constructor to `true`. Otherwise, there will be continuous swapping between the two textures used as the render target of the post-process, which is especially bad in non-compatibility mode because the cached render bundle will be recreated each frame.


WebGPU Internals

Coming next

WebGPU Internals - Bind Group Cache

Learn how the WebGPU engine has been implemented in Babylon.js

WebGPU Internals - Overview

Learn how the WebGPU engine has been implemented in Babylon.js

WebGPU Internals - Render Pipeline Cache

Learn how the WebGPU engine has been implemented in Babylon.js

WebGPU Internals - Miscellaneous

Learn how the WebGPU engine has been implemented in Babylon.js