
## 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



Starting with Babylon.js v3.1, we introduced the NullEngine, which is a version of the main Babylon.js engine that does not require a WebGL-capable device.

The NullEngine does not produce any rendering and can therefore be used in a Node.js or server-side environment.

It can be used to:

- Run tests
- Run a server-side version of your application or game
- Use specific Babylon.js services, such as glTF loaders

## General

To use a headless version of Babylon.js, just run:

```javascript
var engine = new BABYLON.NullEngine();
var scene = new BABYLON.Scene(engine);
```

If you want to use it in a Node.js environment, you may need to add some additional resources, such as support for XHR:

First install babylonjs and babylonjs-loaders: `npm install babylonjs babylonjs-loaders`

Then use this code:

```javascript
var BABYLON = require("babylonjs");
var LOADERS = require("babylonjs-loaders");
global.XMLHttpRequest = require("xhr2").XMLHttpRequest;

var engine = new BABYLON.NullEngine();
var scene = new BABYLON.Scene(engine);

var light = new BABYLON.PointLight("Omni", new BABYLON.Vector3(20, 20, 100), scene);

var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0.8, 100, BABYLON.Vector3.Zero(), scene);

BABYLON.ImportMeshAsync("https://playground.babylonjs.com/scenes/skull.babylon", scene).then(function ({ meshes }) {
  camera.target = meshes[0];

  console.log("Meshes loaded from babylon file: " + meshes.length);
  for (let index = 0; index < meshes.length; index++) {
    console.log(meshes[index].toString());
  }

  BABYLON.ImportMeshAsync("https://www.babylonjs.com/assets/DamagedHelmet/glTF/DamagedHelmet.gltf", scene).then(function ({ meshes }) {
    console.log("Meshes loaded from gltf file: " + meshes.length);
    for (let index = 0; index < meshes.length; index++) {
      console.log(meshes[index].toString());
    }
  });

  console.log("render started");
  engine.runRenderLoop(function () {
    scene.render();
  });
});
```

## Configuration

You can specify some options in the `NullEngine` constructor:

```javascript
const engine = new BABYLON.NullEngine({
    renderWidth: 512,
    renderHeight: 256,
    textureSize: 512
});
```

With `renderWidth` and `renderHeight`, you can define the size of the virtual canvas used to simulate the render surface.
With `textureSize`, you can define the size of all textures, which will all be black, used by the NullEngine.

## Troubleshooting

While the goal of the NullEngine is to completely replace the `Engine` class, some features cannot be used server-side:

- `camera.attachControl` cannot be used as it requires an HTML element
- `DynamicTexture` cannot be used as it relies on HTML canvas

Furthermore, as mentioned earlier, you need to provide an implementation of the `XMLHttpRequest` class.



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 |


WebGPU Internals - Miscellaneous

Validation tests

TintWASM