
## Validation tests
These validation tests are excluded from WebGPU because some features are not implemented in Babylon.js yet:
* **GLTF Mesh Primitive Mode (0)** and **GLTF Mesh Primitive Mode (1)**: line loop / triangle fan not implemented yet
* **GLTF Buggy with Meshopt Compression**: formats others 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 is still ok because there are less than 2.5% errors) because it uses exponential shadow map whose parameters (`depthScale` especially) depend on the precision of the depth map. In WebGL we are using a 32 bits float texture but in WebGPU it's only a half-float texture because linear filtering of 32 bits float textures are not supported (for the time being at least):

![WebGPU chart](/img/extensions/webgpu/webgpuValidationTestSelfShadowing.jpg)

**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 but with no need for a WebGL capable device.

The NullEngine will not produce any rendering and thus can be used in a Node.js / server side environment.

It can be used to:
- Run tests
- Run a server side version of your application / game
- Use specific Babylon.js services (like glTF loaders for instance)

## General

To use a headless version of Babylon.js, just run:

```
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 (like support for xhr):

```
var BABYLON = require("../../dist/preview release/babylon.max");
var LOADERS = require("../../dist/preview release/loaders/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.SceneLoader.ImportMesh("", "https://playground.babylonjs.com/scenes/", "skull.babylon", scene, function (newMeshes) {
    camera.target = newMeshes[0];

    console.log("Meshes loaded from babylon file: " + newMeshes.length);
    for (let index = 0; index < newMeshes.length; index++) {
        console.log(newMeshes[index].toString());
    }

    BABYLON.SceneLoader.ImportMesh("", "https://www.babylonjs.com/Assets/DamagedHelmet/glTF/", "DamagedHelmet.gltf", scene, 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 specifiy some options in the `NullEngine` constructor:

```
var 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 be all 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 we already 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 than 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. As there are numerous states that define a pipeline, 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 starts from the root node, lookup the `values` property with the `stencilReadMask` current value, then lookup the `values` property of this node with the `stencilWriteMask` current value and so on, until we traverse all the states.

## Optimization
The state positions are ordered so that states that are less likely to change from one pipeline to another are listed first. That's because we maintain a pointer (`_stateDirtyLowestIndex`) that contains the lowest index of all the states that have been dirtyfied (meaning the states that have changed since the last pipeline lookup) before querying the cache and we will traverse the cache from this index and not from 0 to lookup the pipeline. So, the higher `_stateDirtyLowestIndex` is the better the performances are: we will traverse less nodes to find the pipeline in the cache.

Note we tried an implementation where render pipelines where recorded in a hash map and the lookup key was a string concatenation of the state values (see the class `WebGPUCacheRenderPipelineString`) but it was dropped because the node tree implementation was faster (around 2x at the time the comparison was made - the code has changed since then so we should probably perform some new testings but I still think the node tree is faster than the hash map).

Last note: the `values` property is a regular object and not a `Map` because in our testings (with Chrome) using an object was faster.

## Monitoring the performances
Performance of the cache can be assessed by looking at these properties (the 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