
## How to use clip planes

You can clip the rendering of a scene by using one of the supported clip planes:

- `scene.clipPlane`
- `scene.clipPlane2`
- `scene.clipPlane3`
- `scene.clipPlane4`

Each clip plane is a BABYLON.Plane that you can define like this:

```
scene.clipPlane4 = new BABYLON.Plane(0, 1, 0, 0);
```

The 3 first parameters of the Plane constructor defines the normal of the plane and the last one defines the distance from (0,0,0).

You can find an interactive demo about clip planes here: <Playground id="#Y6W087" title="Clipping Planes Example 1" description="Simple example showing how to use clipping planes."/>

A maximum of 4 different clip planes can be used simultaneously for a specific rendering.

If you want to apply per mesh clip planes, you can rely on the following observables:

- `mesh.onBeforeRenderObservable`
- `mesh.onAfterRenderObservable`

Example:

```
sphere.onBeforeRenderObservable.add(function() {
    scene.clipPlane = new BABYLON.Plane(1, 0, 0, 0);
});

sphere.onAfterRenderObservable.add(function() {
    scene.clipPlane = null;
});    
```

Demo: <Playground id="#EHLHNX" title="Clipping Planes Example 2" description="Using 4 different clipping planes at the same time."/>


## How To Create a Custom Loading Screen

Starting with Babylon.js 2.3 the loading screen (the screen used when loading assets or a scene) can be changed by the developer.

To create a new loading screen, you will have to create a simple class, implementing the following interface:

```javascript
interface ILoadingScreen {
  //What happens when loading starts
  displayLoadingUI: () => void;
  //What happens when loading stops
  hideLoadingUI: () => void;
  //default loader support. Optional!
  loadingUIBackgroundColor: string;
  loadingUIText: string;
}
```

In plain JavaScript, your loader code will look like this:

```javascript
function CustomLoadingScreen( /* variables needed, for example:*/ text) {
  //init the loader
  this.loadingUIText = text;
}
CustomLoadingScreen.prototype.displayLoadingUI = function() {
  alert(this.loadingUIText);
};
CustomLoadingScreen.prototype.hideLoadingUI = function() {
  alert("Loaded!");
};
```

In TypeScript the same will look like this:

```javascript
class CustomLoadingScreen implements ILoadingScreen {
  //optional, but needed due to interface definitions
  public loadingUIBackgroundColor: string
  constructor(public loadingUIText: string) {}
  public displayLoadingUI() {
    alert(this.loadingUIText);
  }

  public hideLoadingUI() {
    alert("Loaded!");
  }
}
```

The usage is the same in both languages:

```javascript
var loadingScreen = new CustomLoadingScreen("I'm loading!!");
// replace the default loading screen
engine.loadingScreen = loadingScreen;
// show the loading screen
engine.displayLoadingUI();

/*
 * create your scene over here
 */

// hide the loading screen when you want to
engine.hideLoadingUI();
```

## Example

Here a playground using a custom loading screen:

<Playground id="#5Y2GIC#39" title="Custom Loading Screen Example" description="Simple example showing how to create and use a custom loading screen."/>

You might also be interested in a standalone html example:

```html
<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

    <title>Babylon.js custom loading screen example</title>
    <script src="https://code.jquery.com/pep/0.4.2/pep.min.js"></script>
    <script src="https://preview.babylonjs.com/babylon.js"></script>
    <script src="https://preview.babylonjs.com/loaders/babylonjs.loaders.js"></script>

    <style>
        html,
        body {
            overflow: hidden;
            width: 100%;
            height: 100%;
            margin: 0;
            padding: 0;
        }

        #renderCanvas {
            width: 100%;
            height: 100%;
            touch-action: none;
        }

        #loadingScreen {
            position: absolute;
            width: 100%;
            height: 100%;
            color: white;
            font-size: 50px;
            text-align: center;
            background-color: #BB464Bcc;
            z-index: 9999;
        }
    </style>
</head>

<body>
    <div id="loadingScreen">default div text</div>
    <canvas id="renderCanvas"></canvas>
    <script>
        var canvas = document.getElementById("renderCanvas");
        var engine = new BABYLON.Engine(canvas, true);

        var loadingScreenDiv = window.document.getElementById("loadingScreen");

        function customLoadingScreen() {
            console.log("customLoadingScreen creation")
        }
        customLoadingScreen.prototype.displayLoadingUI = function () {
            console.log("customLoadingScreen loading")
            loadingScreenDiv.innerHTML = "loading";
        };
        customLoadingScreen.prototype.hideLoadingUI = function () {
            console.log("customLoadingScreen loaded")
            loadingScreenDiv.style.display = "none";
        };
        var loadingScreen = new customLoadingScreen();
        engine.loadingScreen = loadingScreen;

        engine.displayLoadingUI();

        var delayCreateScene = function () {
            var scene = new BABYLON.Scene(engine);
            scene.createDefaultCamera(true, true, true);
            BABYLON.SceneLoader.ImportMesh(
                "",
                "http://models.babylonjs.com/CornellBox/",
                "cornellBox.glb",
                scene,
                function () {
                    scene.createDefaultCamera(true, true, true);
                    scene.createDefaultEnvironment();
                    scene.activeCamera.alpha = Math.PI / 2;

                    engine.hideLoadingUI();

                });
            return scene;
        };
        var scene = delayCreateScene();

        engine.runRenderLoop(function () {
            if (scene) {
                scene.render();
            }
        });
        window.addEventListener("resize", function () {
            engine.resize();
        });
    </script>
</body>
</html>
```

## Getting File Loading Rate

When loading files, you can get the [SceneLoaderProgressEvent](/typedoc/classes/babylon.sceneloader) sent in the `onProgress` callback.

Example using `BABYLON.SceneLoader.ImportMesh`:

```javascript
BABYLON.SceneLoader.ImportMesh(
    "",
    "http://models.babylonjs.com/CornellBox/",
    "cornellBox.glb",
    scene,
    function () {
        // onSuccess
        scene.createDefaultCamera(true, true, true);
        scene.activeCamera.alpha = Math.PI / 2;
        engine.hideLoadingUI();
    },
    function (evt) {
        // onProgress
        var loadedPercent = 0;
        if (evt.lengthComputable) {
            loadedPercent = (evt.loaded * 100 / evt.total).toFixed();
        } else {
            var dlCount = evt.loaded / (1024 * 1024);
            loadedPercent = Math.floor(dlCount * 100.0) / 100.0;
        }
        // assuming "loadingScreenPercent" is an existing html element
        document.getElementById("loadingScreenPercent").innerHTML = loadedPercent;
    }
);


```


Starting with Babylon.js v4.2, you have the opportunity to apply delta changes to a scene.
This means you can "record" all changes done to a scene and later on reapply these changes.

This is particularly useful when you load a scene from a .babylon or a .gltf file and you want to apply changes to it (without reexporting the scene from your DCC tool).

## Recording the changes

To record changes done to a scene, you simply have to create a new `SceneRecorder` and call its `track()` function:

```javascript
var recorder = new BABYLON.SceneRecorder();

recorder.track(scene);
```

This will mark the origin of the changes eg. the original state of your scene. Every changes (well, almost actually, please check the limitations chapter below) made after that call will be tracked and available in the delta file.

## Applying the changes

Once you're done with the changes you want to record, you can get the delta file with this call:

```javascript
var delta = recorder.getDelta();
```

The returned value is a JSON object that you can download or reuse later.

To donwload it, you can leverage the Tools class:

```javascript
BABYLON.Tools.Download(JSON.stringify(delta), "delta.json");
```

If you want to apply it to your scene, you can call that static function:

```javascript
BABYLON.SceneRecorder.ApplyDelta(delta, scene);
```

## Example

Let's have a look at an example to see it in action:

```javascript
var scene = new BABYLON.Scene(engine);
var camera = new BABYLON.FreeCamera("camera1", new BABYLON.Vector3(0, 5, -10), scene);
camera.setTarget(BABYLON.Vector3.Zero());
camera.attachControl(canvas, true);

var light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0), scene);
light.intensity = 0.7;

var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
sphere.position.y = 1;

var ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 6, height: 6 }, scene);

// Instantiate the recorder
var recorder = new BABYLON.SceneRecorder();

recorder.track(scene);

// Let's make some changes
sphere.position.y = 0;
scene.clearColor.r = 1;

light.intensity = 0;

var light2 = new BABYLON.HemisphericLight("light2", new BABYLON.Vector3(0, 1, 0), scene);

ground.dispose();

// Now we can get the delta file
let delta = recorder.getDelta();

// Just to see the changes, we are updating the value so we can see what the delta is doing
ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 6, height: 6 }, scene);
light2.dispose();
sphere.position.y = 2;
scene.clearColor.r = 0;
light.intensity = 1.0;

// Apply the delta
BABYLON.SceneRecorder.ApplyDelta(delta, scene);
```

You can play with this code on this Playground: <Playground id="#MPD4TQ#1" title="Delta System Example" description="Simple example showing how to save deltas and apply them to your scene."/>

## Using the Inspector

You can also use the Inspector to record your delta. To do so, jump to the Tools tab and select the [Start recording] button in the Replay section:

![Replay section](/img/how_to/scene/inspector-record.jpg)

When you are done with your recording, go to the same place and hit the [Generate delta file]:

![Replay section](/img/how_to/scene/inspector-generate.jpg)

This will download the file locally.

## Limitations

The recorder has some limitations listed here:

- It will only record simple values (array, colors, vectors, boolean, number)
- It will not record large state changes like:
  - Updating the material property of a mesh
  - Updating the skeleton property of a mesh
  - Updating mesh's geometry



## How To Fast Build a World

There are a number of helpers that, once you to have put models into a scene, add cameras, light and environment that adjust to the models automatically allowing you to quickly view them. You can then make adjustments as you need.

For beginners to Babylon.js these two sections [Fastest Build](/features/featuresDeepDive/scene/fastBuildWorld#fastest-build) and [Import and Fastest Build](/features/featuresDeepDive/scene/fastBuildWorld#import-and-fastest-build) will quickly give you a viewable world and are a good way of getting a look at models. As such they are level 1 material. It is worth considering working through Babylon101 and parts of the level 1 material in order to make the other information and details on this page more understandable.

## Helpers

The following is a list of the methods of the `scene` object that help in fast building a world, with a link to their API description:

-   [createDefaultCameraOrLight](/typedoc/classes/babylon.scene#createdefaultcameraorlight);
-   [createDefaultCamera](/typedoc/classes/babylon.scene#createdefaultcamera);
-   [createDefaultLight](/typedoc/classes/babylon.scene#createdefaultlight);
-   [createDefaultEnvironment](/typedoc/classes/babylon.scene#createdefaultenvironment);
-   [createDefaultSkybox](/typedoc/classes/babylon.scene#createdefaultskybox);

## Fastest Build

To build a world very quickly just use `createDefaultCameraOrLight` along with `createDefaultEnvironment` as in this example

```javascript
scene.createDefaultCameraOrLight(true, true, true);
scene.createDefaultEnvironment();
```

<Playground id="#MJNICE" title="The Quickest Way To Build A World" description="Simple example of creating a world with createDefaultEnviornment."/>

You can see how the camera automatically adjusts by adding a second box and re-positioning it

<Playground id="#MJNICE#3" title="Fast Build With Camera Adjust" description="Simple example of building a world quickly and adjusting the camera."/>

More information about these methods, including details about parameters, can be found in the individual sections below.

## Create Default Camera or Light

As can be seen in the _Fastest Build_ section the helper, `createDefaultCameraOrLight` creates both a camera and a light in one line. The three parameters it can take are the same as for the `createDefaultCamera` method, the second parameter also refers to the light and replaces any existing camera or light when true. The approach to accessing the camera or light is the same as for the individual methods.

## Create Default Camera

The `createDefaultCamera` takes three boolean parameters, all set to _false_ by default. They are

-   createArcRotateCamera: creates a free camera by default and an arc rotate camera when _true_;
-   replace: when _true_ the created camera will replace the existing active one;
-   attachCameraControls: when _true_ attaches control to the canvas.

This code will create an arc rotate camera, replace any existing camera and attach the camera control to the canvas

```javascript
scene.createDefaultCamera(true, true, true);
```

<Playground id="#MJNICE#4" title="Camera Helper Example (no light)" description="Simple example of the camera helper with no light."/>
<Playground id="#MJNICE#5" title="Camera Helper Example" description="Simple example of the camera helper."/>

For a free camera

```javascript
scene.createDefaultCamera(false, true, true);
```

<Playground id="#MJNICE#6" title="Camera Helper Example (Free Camera)" description="Simple example of the camera helper with a free camera."/>

The camera will adjust depending on the size and position of each mesh in the world.

<Playground id="#MJNICE#7" title="Camera Helper Adjusting" description="Simple example of the camera helper and adjusting to a large box."/>

### Accessing the Camera

Since creating the camera this way makes the helper created camera the active camera the simplest way to access it is using

```javascript
scene.createDefaultCamera(true, true, true);

var helperCamera = scene.activeCamera;
```

<Playground id="#MJNICE#11" title="Camera Helper With Active Camera Changes" description="Simple example of the camera helper and making changes to the active camera."/>

An alternative way to access the helper created camera immediately after creating it is, since it will be the last one in the `scene.cameras` array, to use

```javascript
scene.createDefaultCamera(true, true, true);

var helperCamera = scene.cameras[scene.cameras.length - 1];

//OR

var helperCamera = scene.cameras.pop();
scene.cameras.push(helperCamera);
```

<Playground id="#MJNICE#8" title="Camera Helper With Radius and Angle Changes" description="Simple example of the camera helper and making changes to the camera radius and angles."/>

## Create Default Light

The `createDefaultLight` takes just one boolean parameters, set to _false_ by default:

-   replace: when _true_ the created light will replace all the existing ones; when _false_ and there are no existing lights a hemispherical light is created; when _false_ and lights already exist, no change is made to the scene.

When this method is used before the creation of any other lights then it is usually sufficient to use

```javascript
scene.createDefaultLight();
```

### Accessing the Light

Provided you access the helper created light immediately after creating it, it will be the last one in the `scene.lights` array.

You can obtain it using

```javascript
scene.createDefaultLight();

var helperLight = scene.lights[scene.lights.length - 1];

//OR

var helperLight = scene.lights.pop();
scene.lights.push(helperLight);
```

<Playground id="#MJNICE#9" title="Light Helper With Direction and Color Change" description="Simple example of the light helper and changing the light's color and direction."/>

## Create Default Environment

The simple code

```javascript
scene.createDefaultEnvironment();
```

adds a skybox and ground to the scene, sets a wide range of environmental parameters and returns an [environmental helper](/typedoc/classes/babylon.environmenthelper) to the scene.

You will also find below a helper for [just a skybox](/features/featuresDeepDive/scene/fastBuildWorld#create-default-skybox).

When you look at the following playground

<Playground id="#MJNICE" title="Playground Fast Build" description="Simple example of creating the default enviornment in the playground."/>

it is not obvious that a skybox and ground have been added. The defaults have been set so as to be really subtle and help give a grounding feeling to the objects

Moving the camera further out shows that the skybox is constructed.

<Playground id="#MJNICE#1" title="Skybox Example" description="Simple example showing how to create a skybox."/>

You can also see the skybox and ground by using the options parameter and setting different values for the skybox texture and the ground color.

<Playground id="#MJNICE#10" title="Skybox and Ground Changes" description="Simple example of creating a skybox and ground and changing their properties."/>

### Options Parameters

As you can see in the above playground the `createDefaultEnvironment` method takes an options parameter. The full range of environmental helper options properties are available from the [API](/typedoc/interfaces/babylon.ienvironmenthelperoptions)

So, for example

to prevent the creation of the skybox:

```javascript
var helper = scene.createDefaultEnvironment({
    createSkybox: false,
});
```

to enable ground reflection:

```javascript
var helper = scene.createDefaultEnvironment({
    enableGroundMirror: true,
});
```

when you see z-fighting with the ground, modify the `groundYBias` to a larger number:

```javascript
var helper = scene.createDefaultEnvironment({
    groundYBias: 0.01,
});
```

### Applicable Methods

Since the `createDefaultEnvironment` method returns an `environmentalHelper` object then all the properties and methods of this object (as in the [API](/typedoc/classes/babylon.environmenthelper)) are available.

So, for example if the environment color is not your favorite choice you can modify it after creation

```javascript
var helper = scene.createDefaultEnvironment();
helper.setMainColor(BABYLON.Color3.Teal());
```

<Playground id="#MJNICE#12" title="Changing The Main Color" description="Simple example of changing the scene's main color."/>

or for instance should you wish to dispose of the ground after creation of the environment use

```javascript
var helper = scene.createDefaultEnvironment();
helper.ground.dispose();
```

or how about changing the options parameters

```javascript
var helper = scene.createDefaultEnvironment();
var options = {
    skyboxTexture: new BABYLON.CubeTexture("/textures/skybox", scene),
};
helper.updateOptions(options);
```

<Playground id="#MJNICE#13" title="Changing Scene Options" description="Simple example showcasing how to change options of the scene."/>

### Environmental Helper

NOTE: The environment helper relies exclusively on the [BackgroundMaterial](/features/featuresDeepDive/environment/backgroundMaterial) to be as efficient as possible.

## Create Default Skybox

The `createDefaultSkybox` method can be used when you do not want to create a full environment. The [parameters](/typedoc/classes/babylon.scene#createdefaultskybox) used determine how the skybox is created.

for example

```javascript
var texture = new BABYLON.CubeTexture("/assets/textures/SpecularHDR.dds", scene);
scene.createDefaultSkybox(texture, true, 100);
```

In this case the first two parameters used give the texture for the skybox and specify that [a PBRMaterial](/features/featuresDeepDive/materials/using/introToPBR) is to be used (second parameter, _true_) as opposed to a standard material (second parameter, _false_ - default value).

The third parameter defines the scale of your skybox (this value depends on the scale of your scene), the default value is _1000_.

<Playground id="#MJNICE#14" title="Skybox Scale Example" description="Simple example showing how to scale a skybox in the playground."/>

## Import and Fastest Build

To import models and build a world very quickly just use `createDefaultCameraOrLight` along with `createDefaultEnvironment` as in this example

<Playground id="#MJNICE#15" title="Importing Models and Quickly Building A World" description="Simple example showcasing how to import models and quickly build a world."/>

The camera adjusts its position automatically to make the world viewable depending on the scale and position of the models. More information on importing models with the scene helpers follows below.

## Importing Models for Your World

Since the `createDefault...` helpers take into account any models in the scene they can only be applied after the model is loaded and so are placed in the callback function. For example

```javascript
BABYLON.SceneLoader.Append("https://www.babylonjs.com/Assets/DamagedHelmet/glTF/", "DamagedHelmet.gltf", scene, function (meshes) {
    scene.createDefaultCameraOrLight(true, true, true);
    scene.createDefaultEnvironment();
});
```

There is then a problem. When creating a scene Babylon.js checks for a camera. When importing models, the existence of a camera will be checked for before the model has finished loading and so the scene will fail.

The solution is to replace the `createScene` function with the `delayCreateScene` function. Whether in a playground or in your own project this is a direct replacement.

**NOTE:** Other [scene loader](/features/featuresDeepDive/importers/loadingFileTypes) methods are available.

### Using Scene Helpers with Import

All the helper methods described earlier on this page behave in exactly the same way when importing models. Just remember to call them within the scene loader callback.

### Import Playground Examples

<Playground id="#10D6YT#33" title="Simple Import and Main Color Change" description="Simple example of importing a scene and changing the main color."/>
<Playground id="#10D6YT#35" title="Importing Blur, Reflections, and Shadow" description="Simple example showing how to import blur, reflections, and shadows."/>



## How floating-origin works

On traditional 3D rendering, objects will pass three stages until they're displayed on screen:

- World matrix: places, scales and rotates the object on the world;
- View matrix: will translate and rotate relative to camera;
- Projection matrix: will project vertices to screen.


This is well known and works perfectly.

Only problem is that our GPU's are still limited to 32 bits floating-point,
so when we have big coordinates -- objects and/or cameras very far from the world's origin,
for example at (10000000, 0, 10000000) -- we will notice jittering because the big numbers inside matrices will cause 32 bits floating-point imprecision on the GPU.

![Pic01](/img/how_to/floating_origin/pic01.jpg)

But there is a trick which is good to mitigate that problem: floating-origin, first described by Chris Thorne [^1].

The idea of floating-origin is very simple: we just keep the camera always fixed at world's origin
(0, 0, 0) and move the objects instead.

This does not mean that the camera cannot move, though! It "moves", but not directly. Here is
where lies the trick: instead of changing the real camera position, we use a separate, double precision [^*]
Vector3 which stores the camera position. The real camera position is kept always at origin (0, 0, 0).

We do the same for the objects: all of them get a separate, double precision Vector3 to store their coordinates. We don't set their real position directly; instead, we also set their separate coordinates.

Then, on a loop which happens every frame just before rendering, we subtract the double camera position from each object's double position, and that difference is copied to that object's real position.

The result is that the camera is indeed kept always at origin, and the objects float around, removing
huge coordinates from the objects that are close to the camera. That is, imprecision only happens very far
from the camera, and as they are very far anyway, we cannot see the jittering. =)

![Pic02](/img/how_to/floating_origin/pic02.jpg)

Let's use an example:

On a solar system, we have an asteroid located at (10000000, 0, 10000000).
Our camera is close to the asteroid, at (10000000, 0, 10000500).

Normally, that would certainly cause jittering, because both objects are very far from the world's origin. But with
our trick, the jittering does not happen -- remember, we subtract camera double position from the object double position
and then set the object real position at that offset, keeping the camera always at (0, 0, 0):

Object Position: (10000000, 0, 10000000)  
Camera Position: (10000000, 0, 10000500)  
Offset: (0, 0, -500)

The offset is small enough to be absolutely precise even with only 32 bits floating-point. The GPU is very happy with that
and we don't see any jittering.

We just need to set the object at (0, 0, -500) and it will have the same visual effect as if we used their real coordinates,
but with no jittering.

## Floating-origin examples

You can find a working playground example with OriginCamera and Entity classes here:  

<Playground id="#LHI514#3" title="Floating-Origin" description="A simple example of huge scene far from world's origin using floating-origin trick." image="/img/playgroundsAndNMEs/divingDeeperFloatingOrigin.jpg"/>


If you decide to use floating-origin, all your objects will have to use the same trick,
or your game won't work properly. You will need to create one instance of OriginCamera
and at least one instance of Entity.

OriginCamera is a special camera which has a separate position control stored as doublepos (and its target as doubletgt). 
You must stop using position and target from camera, and use their double precision counterparts doublepos and doubletgt.

All objects from scene must then be parented to a Entity instance. Entity also has doublepos property which is double precision coordinate. 
You must use its doublepos to set object position instead of position directly.

So, let's say that we want a sphere with double precision:

```javascript
// Create the OriginCamera
let camera = new OriginCamera("camera", new BABYLON.Vector3(10000000, 0, 10000500), scene);
camera.doubletgt = new BABYLON.Vector3(10000000, 0, 10000000);
camera.touchAngularSensibility = 10000;
camera.inertia = 0;
camera.speed = 1;
camera.keysUp.push(87);    		// W
camera.keysDown.push(83)   		// D
camera.keysLeft.push(65);  		// A
camera.keysRight.push(68); 		// S
camera.keysUpward.push(69);		// E
camera.keysDownward.push(81);     // Q
camera.minZ = 0.5;
camera.maxZ = 50000000;
camera.fov = 1;
camera.attachControl(canvas, true);

// Create an Entity for the sphere
let entSphere = new Entity("entSphere", scene);
camera.add(entSphere);

// Create the sphere and parent it to its Entity
let sphere = BABYLON.CreateSphere("sphere", {diameter:256});
sphere.parent = entSphere;

// Position the Entity
entSphere.doublepos = new BABYLON.Vector3(10000000, 0, 10000000);
```  

The OriginCamera extends UniversalCamera, so you can use the same features of that.

Finally, even on huge scenes you commonly will have objects spread into separate regions, so you 
most probably would not need one Entity instance for each object. If you think carefully, you
can have one Entity instance for each region of your scene, a region which does not extend for more
than let's say 10,000 units to avoid imprecision again. Then, you can add many objects that are
always in that region to just one Entity. Doing that, you can even move those objects by using
their positions directly, as you would do normally. And still, no imprecision will be seen anymore.

[^1]: Chris Thorne, 2005. Using a Floating Origin to Improve Fidelity and Performance of Large Distributed Virtual Worlds
[^*]: The original article by Chris Thorne uses single-precision floats.




## How to Interact with A Scene

There are three main ways for a user to interact with a scene, the keyboard, the [GUI](/features/featuresDeepDive/gui) and directly with a mouse, touch or gamepad. The use of keyboard and pointer interactions are described on this page.

## Keyboard Interactions

This is a code template to control reactions to different keys. Both the `ascii` code for the key and the key itself are available to you.

```javascript
scene.onKeyboardObservable.add((kbInfo) => {
  switch (kbInfo.type) {
    case BABYLON.KeyboardEventTypes.KEYDOWN:
      console.log("KEY DOWN: ", kbInfo.event.key);
      break;
    case BABYLON.KeyboardEventTypes.KEYUP:
      console.log("KEY UP: ", kbInfo.event.code);
      break;
  }
});
```

## Pointer Interactions

This is a code template for reacting to pointer events:

```javascript
scene.onPointerObservable.add((pointerInfo) => {
  switch (pointerInfo.type) {
    case BABYLON.PointerEventTypes.POINTERDOWN:
      console.log("POINTER DOWN");
      break;
    case BABYLON.PointerEventTypes.POINTERUP:
      console.log("POINTER UP");
      break;
    case BABYLON.PointerEventTypes.POINTERMOVE:
      console.log("POINTER MOVE");
      break;
    case BABYLON.PointerEventTypes.POINTERWHEEL:
      console.log("POINTER WHEEL");
      break;
    case BABYLON.PointerEventTypes.POINTERPICK:
      console.log("POINTER PICK");
      break;
    case BABYLON.PointerEventTypes.POINTERTAP:
      console.log("POINTER TAP");
      break;
    case BABYLON.PointerEventTypes.POINTERDOUBLETAP:
      console.log("POINTER DOUBLE-TAP");
      break;
  }
});
```

[PEP](https://github.com/jquery/PEP) is an option for supporting **touch** events in older browsers (ones that don't natively support [pointer events](https://caniuse.com/pointer)). To use PEP all that is necessary is to:

1. Install PEP

```javascript
<script src="https://code.jquery.com/pep/0.4.3/pep.js"></script>
```

2. Stop the default touch-action within the rendering canvas

```javascript
<canvas id="renderCanvas" touch-action="none"></canvas>
```

## Playground Examples

<Playground id="#0XYMA9#107" title="Scene Observables Template" description="Simple scene observables template." image="/img/playgroundsAndNMEs/divingDeeperInteractions1.jpg" isMain={true} category="Scene"/>
<Playground id="#7CBW04" title="Simple Drag Example" description="Simple example of a drag behavior." image="/img/playgroundsAndNMEs/divingDeeperInteractions2.jpg" isMain={true} category="Scene"/>
<Playground id="#XZ0TH6" title="Simple Keyboard Input Example" description="Simple example of keyboard input." image="/img/playgroundsAndNMEs/divingDeeperInteractions3.jpg" isMain={true} category="Scene"/>
<Playground id="#2SA7J8#7" title="Click+Drag to Multi Select" description="Simple example of how to multi-select objects in a scene using rectangular selection." isMain={true} category="Scene"/>

Remember to click in scene (to set focus) before using keyboard



# In-Depth layerMask

`layerMask` is a property you can find on many objects and may be a bit difficult to grasp at first. This page should give you a good understanding of how it works accross Babylon.js objects.

## layerMask meaning

`layerMask` is a value that can be assigned to different objects (like meshes, cameras, layers, particle systems, etc) and is used to determine the visibility of this object from another one (for eg, if a mesh is visible from a camera or if a layer should be displayed after a given camera is processed).

The only two things to understand with `layerMask` are that:
* it can be any number from 0 to 0xFFFFFFFF (or 4294967295, but it’s easier to write 0xFFFFFFFF)
* when computing a visibility flag, two values of `layerMask` are **AND**ed and if the result is different from 0 the flag is true

So, for eg, if `camera.layerMask = 35` and `mesh.layerMask = 2`, `35 & 2 == 2 != 0` so the mesh is visible from this camera. We often show these numbers in hexadecimal because doing the **AND** as a mental calculation is easier that way: `35=0x23` and `2=0x02` and `35 & 2 == 0x23 & 0x02` and from this latter representation it’s easier to see that the result is 2 (well, at least when you are a bit comfortable with hexadecimal!).

## Usage in Babylon.js

In Babylon, by default all `layerMask` properties are `0x0FFFFFFF` (for Camera, Mesh, Layer, …). So, when it comes to determine a visibility, `0x0FFFFFFF & 0x0FFFFFFF != 0` and everything is always visible (at least from the standpoint of the `layerMask` test).

As you can see, there are 4 bits not set by default in the `layerMask` (the leading `0` before the first `F`). It’s to ease the use of `layerMask`, as a common usage is to make some meshes hidden from a camera. To achieve that, you need to set a `layerMask` on the meshes so that the **AND** operation with the `layerMask` of the camera (`0x0FFFFFFF` by default) is 0: you can use `0x10000000`, `0x20000000`, `0x40000000` or `0x80000000`. Now you see why showing these numbers in hexadecimal helps: it’s a lot easier to see that `0x10000000 & 0x0FFFFFFF = 0` than `268435456 & 268435455`!

If the default value for `layerMask` was `0xFFFFFFFF`, you would also need to update the `layerMask` of your camera to have your meshes invisible from it because `0xFFFFFFFF` is a all-one 32 bit value. So the `0x0FFFFFFF` value is simply a default value that can help make your life a little easier, but in all generality you can put any value in the `layerMask` property of cameras, meshes, layers, etc (as in the `35 & 2` example above) and simply understand how it is used to compute visibility.



Starting with Babylon.js v4.1, it is now possible to use one engine on several canvases.

To do so, you need to create "views". A view is defined by a canvas (the target) and an optional camera (the definition of the view).

**Please note that when a view is registered, the canvas used to initialized the Engine becomes a "working" canvas and is no more supposed to be displayed directly.**

## Creating a view

To create a view, you need to register the combination of a canvas and a camera to the engine:

```
let view = engine.registerView(document.getElementById("renderCanvas1"), camera1);
```

Please note that you can also call the same code with no camera:
```
let view = engine.registerView(document.getElementById("renderCanvas1"));
```

If the camera is undefined the render loop will be executed to the view without changing anything on the active scenes.

## Removing a view

To remove a previously registered view, you can run the following code:
```
engine.unRegisterView(document.getElementById("renderCanvas1"));
```

## Cameras

If a view is defined with a camera, the system will use it as the active camera to render the scene.

A view cannot be rendered if it has a defined camera and the underlying scene is using multiple active cameras(eg. scene.activeCameras.length > 0).

## Multi scenes

You can use views to render multiple cameras from the same scene or from different scenes. As you control the render loop, it is up to you to test the `engine.activeView` to determine which view is currently rendered.

So your render loop could look like:
```
let myRenderLoop = () => {
   if (engine.activeView.camera === undefined) {
       mainScene.render();
   } else if (engine.activeView.target === view1) {
       scene1.render();
   }
}
```

## Events

By default, scenes will capture events from the main rendering canvas (the one used to create the Engine). You can change that behavior by setting the `engine.inputElement` to the DOM element you want to use for events.

This must be done before creating a scene or if you do it after you have to run the following code:
```
scene.detachControl();
engine.inputElement = myNewElement;
scene.attachControl();
```

## Performance

To ensure optimal performance, **multiple canvases on the same page should have the same size**, otherwise it forces a resize of the master canvas for each view, which is detrimental to performance.

From Babylon.js v5 views can also be disabled, for instance to improve performance when one or more canvases are offscreen.

```javascript
view.enabled = false;
```

## Demo
You can see a live demo here: https://www.babylonjs.com/Demos/Views

The initialization code for this page can be found here: https://github.com/BabylonJS/Website/blob/master/build/Demos/Views/index.html



## How to Use Multiple Scenes

To use multiple scenes create them with 

```javascript
var scene0 = new BABYLON.Scene(engine);
var scene1 = new BABYLON.Scene(engine);
``` 
then put the relevant camera, lights and meshes inside each scene and call them in the engine run render loop

```javascript
engine.runRenderLoop(function () {
  scene0.render();
  scene1.render();
});
```
When you want the meshes of both scenes to be visible at the same time then set the 'autoClear' of scene1 (the last rendered scene(s)) to false.

However there is a difference between writing multiple scenes within your own projects and trying them out in the playground.

In your own project it is easy enough to set up create scene functions for each scene and call them in the engine run render loop. For example

```javascript
var createScene0 = function () {
    var scene0 = new BABYLON.Scene(engine);

    //Add camera, light and meshes for scene0

	return scene0;
}

var createScene1 = function () {
    var scene1 = new BABYLON.Scene(engine);

    //Add camera, light and meshes for scene1

	return scene1;
}

//Any other code
var scene0 = createScene0();
var scene1 = createScene1();

engine.runRenderLoop(function () {
  scene0.render();
  scene1.render();
});
```

In the playground the create scene function is wrapped by the code running the playground and so the easiest method is just to create a new scene within the function and add a camera, light and meshes to it. Also the playground has its own engine run render loop which needs to be stopped before running your own version, the trick is to use a setTimeout. Putting these together playground code can look like this example

```javascript
var createScene = function () {
    var scene = new BABYLON.Scene(engine);

    //Add camera, light and meshes for scene

    ////////OTHER SCENE////////////////////
    var scene1 = new BABYLON.Scene(engine);

    //Add camera, light and meshes for scene

    ////////CONTROL ENGINE LOOP///////////
    setTimeout(function() {
        engine.stopRenderLoop();

        engine.runRenderLoop(function () {
            scene.render();
            scene1.render();
        });
    }, 500);

	return scene;
}
```


## Switch Scenes
You might want a user to be able to switch between scenes, remember that the Babylon GUI is a good way to set triggers for this to be possible. 

An example of one way to do this is

```javascript
var clicks = 0;
var showScene = 0;
var advancedTexture;
   

var createGUI = function(scene, showScene) {             
    switch (showScene) {
        case 0:            
            advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI", true, scene0);
        break
        case 1:            
            advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI", true, scene1);
        break
    }
    var button = BABYLON.GUI.Button.CreateSimpleButton("but", "Scene " + ((clicks + 1) % 2));
    button.width = 0.2;
    button.height = "40px";
    button.color = "white";
    button.background = "green";
    button.verticalAlignment = BABYLON.GUI.Control.VERTICAL_ALIGNMENT_TOP
    advancedTexture.addControl(button);

    
    button.onPointerUpObservable.add(function () {       
        clicks++;                   
    });
}  

createGUI(scene, showScene);

engine.runRenderLoop(function () {
    if(showScene != (clicks % 2)){
        showScene = clicks % 2;          
        switch (showScene) {
            case 0:                    
                advancedTexture.dispose();
                createGUI(scene0, showScene);
                scene0.render();
            break
            case 1:
                advancedTexture.dispose();
                createGUI(scene1, showScene);
                scene1.render();
            break
        }
    }
}); 
```

<Playground id="#MXCRPS#1" title="Switching Scenes" description="Simple example showing how to switch scenes."/>

## Overlay Multiple Scenes

Suppose you want a first person shooter type project with a 3D foreground representing the user and then a background scene representing what the user is tracking. In this case you want the meshes in both the foreground and background visible. To do this you want the foreground meshes drawn over the background, that is you do not want the render canvas cleared when rendering the foreground. In this case set 'autoClear' to false 

```javascript

//other code

var foregroundScene = new BABYLON.Scene(engine);
foregroundScene.autoClear = false;

//other code

engine.runRenderLoop(function () {
  backgroundScene.render();
  foregroundScene.render();
});
``` 

<Playground id="#L0IMUD#1" title="Overlaying Scenes" description="Simple example of overlaying scenes."/>


An offscreen canvas is a canvas that can be rendered off screen and on a different thread than the main UI thread.

It could be really interesting to do so if your main thread is already heavily used for other tasks.

You can see a page demonstrating this use case here: https://www.babylonjs.com/Demos/Offscreen

<Youtube id="zYrZNROQzKQ"/>

# Setting up the engine
Starting with Babylon.js v4.1, you can create an engine inside a worker by initializing it with an offscreen canvas.

First you need to create an offscreen canvas out of your regular canvas:
```
var canvas = document.getElementById("renderCanvas");
canvas.width = canvas.clientWidth;
canvas.height = canvas.clientHeight;
var offscreen = canvas.transferControlToOffscreen();
```

Then you need to spin off a new worker and send it the offscreen canvas

```
var worker = new Worker("worker.js"); 
worker.postMessage({canvas: offscreen}, [offscreen]);
```

The worker code will then listen to your message, get the offscreen canvas and start babylon.js as usual:

```
onmessage = function(evt) {
    canvas = evt.data.canvas;
    var engine = new BABYLON.Engine(canvas, true);

    // Your scene setup here
}
```

Then you can use your engine as usual.

# Caveats
The main caveat of using Babylon.js with an offscreen canvas in a worker thread is that you will need to do special work to communicate with the engine from the main thread. You will have to use the same messaging API we used before to communicate between threads.

Furthermore, Babylon.js will not be able to handle inputs for you and so APIs like `camera.attachControls()` will not work and you will have to message inputs to workers.

Here is an example of communication you will have to setup to support canvas resizing.

On main thread:
```
window.addEventListener("resize", () => {
    worker.postMessage({width: canvas.clientWidth, height:canvas.clientHeight});
});
```

On worker thread:
```

var engine;
onmessage = function(evt) {
    if (evt.data.width) {
        canvas.width = evt.data.width;
        canvas.height = evt.data.height;
    }
}
```

# Compatibility

Note that this feature is new and not yet compatible with every device or browser.
You can check current support of offscreen canvas here: https://caniuse.com/#feat=offscreencanvas

If you want to test the compatibility, you can add this condition before using offscreen canvas:
```
if ("OffscreenCanvas" in window && "transferControlToOffscreen" in canvas) { 
    // Ok to use offscreen canvas
}
```

# Resources
- https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
- https://developers.google.com/web/updates/2018/08/offscreen-canvas


# How To Optimize Using Cached Resources

By default, all texture contents are cached by the engine, so if you load the same texture twice, it will be instant (and resource will be shared to save memory).

Starting with the **1.4 release** of Babylon.JS, you can indicate that you want to **cache the resources associated with your scene/game** inside the local **IndexedDB** of the browser. It can enhance the gamer experience as the JSON and textures files can be directly loaded from the database rather than from the web.

## Usage

To enable offline support, the first thing you need to do is create a _**.manifest**_ file associated with your scene. It should be named _NameOfYourScene.babylon.manifest_.

**Starting with Babylon.js v4.0 you also have to turn the feature on with:**
```
BABYLON.Database.IDBStorageEnabled = true;
```

**Note:** by default, the Babylon engine is configured to use online resources. So if you don’t provide any .manifest file, it will assume that you want the resources to be loaded directly from the web all the time.

Inside this **.manifest** file, insert the following piece of JSON:

```javascript
{
  "version" : 1,
  "enableSceneOffline" : true,
  "enableTexturesOffline" : true
}
```

When you’re loading a scene using the Babylon engine, one of the first things it will try is loading this manifest file and checking this JSON description. If not found (404), it will directly load the resources from the web. If found, it will load the values. You can then change those values anytime, they will be verified every time the engine loads your scene.

You have 3 parameters to fill:

1. The first one is _**version**_ and must be an integer. It’s simply the current version of your assets. If you’re changing it, the Babylon engine will detect that change during the next reload of your scene. This will force a complete reload amp; update of all the assets into the browser’s database. This can be useful is you want to be sure that the client browser is using up-to-date textures or scene description recently put on your web server.

2. The second parameter _**enableSceneOffline**_ is a boolean. If set to true, you will be asking to load the JSON associated with your scene (the file with the .babylon extension) and store it into the local database of the user. Next time the user loads the game, the scene description will be directly loaded from the DB rather than from the hosting web server.

3. The third parameter _**enableTexturesOffline**_ is also a boolean. This time, you will be asking the Babylon engine to load all textures (PNG or JPG files) and store them into the local database of the user. Thus, the textures will be directly streamed from the database rather than the web server.

**Note:** images are loaded using XHR2 in the blob format. IE11, Firefox and Chrome 37+ support the storing of blob data into the IndexedDB. [More details](http://caniuse.com/#search=indexeddb)

## Exceptions
If you do not want to enable offline mode, you can set `engine.enableOfflineSupport = false`. This will completely turn off the feature.
If you want more fine-grained control, you can use the `scene.disableOfflineSupportExceptionRules` array:

```
scene.disableOfflineSupportExceptionRules.push(/dude\.babylon/gi);
```

## Samples

Most of the samples on our [website mainpage](https://www.babylonjs.com) are configured to use offline for their scene and textures. For instance, you can try the [Espilit scene](https://www.babylonjs.com/demos/glowingespilit/). The scene is described in _espilit.babylon_ and the associated manifest file is _espilit.babylon.manifest_.

One of the scenes is configured to only cache the texture. It’s the “[The Car](https://www.babylonjs.com/demos/thecar/)” scene. It’s because the JSON file, _TheCar.babylon_, is more than 93 MB. IE11 and Chrome can’t store a big file like that into their DB, so decision was made to avoid trying to cache it.


## How To Optimize Your Scene with Octrees
Octrees are a really powerful data structure that can quickly select entities based on space coordinates.
More on wikipedia: http://en.wikipedia.org/wiki/Octree

Babylon.js supports octrees through a class named ```BABYLON.Octree```. Dedicated functions are available to help you create these octrees when required:

## Optimizing Meshes Selection for Rendering
If your scene has a lot of meshes, it can be useful to create an octree to speed visible meshes selection (e.g. finding meshes the camera can see). To do so, just call this function:

```javascript
var octree = scene.createOrUpdateSelectionOctree(capacity, maxDepth)
```

You can call the function each time you want to update your octree. This function accepts two parameters:

* capacity: defines the maximum number of meshes you want on your octree's leaves. The default value is 64.
* maxDepth: defines the maximum depth (sub-levels) for your octree. Default value is 2, which means 8 * 8 * 8 = 512 blocks :) (This parameter takes precedence over capacity.)

**Warning: Octrees can be counterproductive if there are not enough meshes in your scene**

# Managing Dynamic Meshes
The main problem with octrees is that your meshes must be static. Indeed, an octree is not dynamic which means that it cannot take into account a mesh's movement.
If you want to have dynamic meshes while keeping your octree, you can just register a mesh as dynamic like this:

```javascript
octree.dynamicContent.push(mesh)
```

In this case, the octree will always select the dynamic mesh.

## Optimizing Collisions and Picking
Computing collisions or clicking-on complex meshes (more than 10k vertices for instance) can be really slow. You can speed things up by subdividing your mesh into submeshes using ```mesh.subdivide(x)``` where x is the number of submeshes you want.

Then you can optimize the selection of submeshes for collisions or picking by creating an octree on the mesh for its submeshes:

```javascript
mesh.createOrUpdateSubmeshesOctree(capacity, maxDepth)
```

You can even specify the usage of your octree independently:

* ```mesh.useOctreeForCollisions```
* ```mesh.useOctreeForPicking```
* ```mesh.useOctreeForRenderingSelection``` : Octree for submeshes can even be used during mesh selection based on camera field of view. Once a mesh is selected by the camera, if the mesh has submeshes, the camera has to select which one is visible. In this case, having an octree can be really helpful.

## GroundMesh
For the specific case of ground meshes, Babylon.js provides a class called ```BABYLON.GroundMesh``` that you can create using ```BABYLON.Mesh.CreateGround``` and ```BABYLON.Mesh.CreateGroundFromHeightMap```.

By calling ```groundMesh.optimize(chunkSize)``` where chunkSize defines the number of submeshes you want, the mesh will be optimized for rendering, picking and collisions by creating an internal octree (Be sure to select a correct chunkSize).

## Using Octrees Manually
You can also use octrees from your code to get a list of meshes or submeshes.

Here are the helpful functions you can find on an octree:

* ```select(frustumPlanes: Plane[], allowDuplicate: boolean)```
* ```intersects(sphereCenter: Vector3, sphereRadius: number, allowDuplicate: boolean)```
* ```intersectsRay(ray: Ray)```

These functions return a [SmartArray](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Misc/smartArray.ts) where duplicates are present or not according to ```allowDuplicate``` parameter/

## Demos
* <Playground id="#3YFJ5R#0" title="Octree Demo" description=""/>
* <Playground id="#0K8EYN#0" title="Instances Demo" description=""/>



## How To Optimize Your Scene

This tutorial will help you find some links and info on how you can improve your scene regarding rendering performance.

## Use TransformNode instead of AbstractMesh or empty meshes

If you need node containers or transform nodes, do not use meshes but TransformNode instead. Use meshes only when associated with content to render.

The meshes need to go through an evaluation process where the camera checks if they are in the frustum. This is an expensive process so reducing the number of candidates by using TransformNode when possible is a good practice.

## Reducing Shaders Overhead
Babylon.js uses an advanced and automatic shaders engine. This system will keep shaders up to date regarding material options. If you are using a static material (ie. an immutable material) then you can let it know to Babylon.js by using the following code:

```
material.freeze();
```

Once frozen, the shader will remain unchanged even if you change material's properties. You will have to unfreeze it to update the inner shader:

```
material.unfreeze();
```

## Reducing World Matrices Computation
Every mesh has a world matrix to specify its position / rotation / scaling. This matrix is evaluated on every frame. You can improve performances by freezing this matrix. Any subsequent changes to position / rotation / scaling will then be ignore:

```
mesh.freezeWorldMatrix();
```

You can unfreeze a mesh with:

```
mesh.unfreezeWorldMatrix();
```

## Freezing the active meshes
If you are CPU bound, you can decide to keep the list of active meshes unchanged and then free the time spent by the CPU to determine active meshes:

```
scene.freezeActiveMeshes();
```

You can unfreeze the active meshes with:

```
scene.unfreezeActiveMeshes();
```

Note that you can force a mesh to be in the active meshes before freezing the list with `mesh.alwaysSelectAsActiveMesh = true`.

Freezing active meshes list may cause some things on the scene to stop updating. One example is [RenderTargetTexture](/features/featuresDeepDive/postProcesses/renderTargetTextureMultiPass), if it's used by mesh materials. For that case RTT needs to be explicitly added to the list of active camera's custom render targets, which will guarantee that it ends up in the render list of the scene:

```javascript
camera.customRenderTargets.push(renderTargetTexture);
```

## Not updating the bounding info
In conjonction with `mesh.alwaysSelectAsActiveMesh` you can also decide to turn off bounding info synchronization. This way the world matrix computation will be faster as the bounding info will not be updated (this could be a problem if you want to use picking or collisions):

```
mesh.doNotSyncBoundingInfo = true;
```

## Not picking the scene on pointer move
On every pointer move, the scene is browsing the list of meshes to see if a mesh under the pointer may need to have an associated action / event raised. 
To avoid this process, you can set `scene.skipPointerMovePicking = true`.

Please note that by doing it, you will have no event over any mesh when the pointer will move (And `scene.meshUnderPointer` will not be updated even if `scene.constantlyUpdateMeshUnderPointer === true`.

## Reducing draw calls
As soon as you can please use [instances](/features/featuresDeepDive/mesh/copies/instances) as they are drawn with one single draw call.

If sharing the same material is a problem, you can then think about using clones which share the same geometry with `mesh.clone("newName")`

One remark regarding instances: If one of the instances has a world matrix with a different determinant (eg. one instance has a negative scale where others don't), babylon.js will be forced to remove the back face culling from their material.

## Reducing calls to gl.clear()
By default, Babylon.js automatically clears the color, depth, and stencil buffers before rendering the scene. It also clears the depth and stencil buffers after switching to a new camera and before rendering a new RenderingGroup. On systems with poor fill rates, these can add up quickly and have a significant impact on performance.

If your scene is set up in such a way that the viewport is always 100% filled with opaque geometry (if you're always inside a skybox, for instance), you can disable the default scene clearing behavior with:

```
scene.autoClear = false; // Color buffer
scene.autoClearDepthAndStencil = false; // Depth and stencil, obviously
```

If you know that the geometry in a particular RenderingGroup will always be positioned in front of geometry from other groups, you can disable buffer clearing for that group with the following:

```
scene.setRenderingAutoClearDepthStencil(renderingGroupIdx, autoClear, depth, stencil);
```
```autoClear```: ```true``` to enable auto clearing. If ```false```, overrides ```depth``` and ```stencil```

```depth```: Defaults to ```true``` to enable clearing of the depth buffer

```stencil```: Defaults to ```true``` to enable clearing of the stencil buffer

Go ahead and be aggressive with these settings. You'll know if it's not appropriate for your application if you see any smearing!

## Using depth pre-pass
When dealing with complex scenes, it could be useful to use depth pre-pass. This technique will render designated meshes only in the depth buffer to leverage early depth test rejection. This could be used for instance when a scene contains meshes with advanced shaders.
To enable a depth pre-pass for a mesh, just call `mesh.material.needDepthPrePass = true`.

## Using unindexed meshes
By default Babylon.js uses indexed meshes where vertices can be reuse by faces. When vertex reuse is low and when vertex structure is fairly simple (like just a position and a normal) then you may want to unfold your vertices and stop using indices:

```
mesh.convertToUnIndexedMesh();
```
For example this works very well for a cube where it is more efficient to send 32 positions instead of 24 positions and 32 indices.

## Turning AdaptToDeviceRatio Off/On
By default, Babylon.js does not adapt to device ratio anymore. It by default focuses on perf vs quality after receiving lots of community requests.

The drawback is that this could look low rea. You can turn it on with the fourth parameter of the Engine constructor:

```
var engine = new BABYLON.Engine(canvas, antialiasing, null, true);
```

## Blocking the dirty mechanism

By default the scene will keep all materials up to date when you change a property that could potentially impact them (alpha, texture update, etc...). To do so the scene needs to go through all materials and flag them as dirty. This could be a potential bottleneck if you have a lot of material.

To prevent this automatic update, you can execute:

```
scene.blockMaterialDirtyMechanism = true;
```

Do not forget to restore it to false when you are done with your batch changes.

## Using Animation Ratio
Babylon.js processes speed depending on the current frame rate.

On low-end devices animations or camera movement may differ from high-end devices. To compensate this you can use:

```
scene.getAnimationRatio();
```

The return value is higher on low frame rates.

## Handling WebGL context lost
Starting with version 3.1, Babylon.js can handle [WebGL context lost event](https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.14.13). This event is raised by the browser when the GPU needs to be taken away from your code. This can happen for instance when using WebVR in hybrid scenario (with multiple GPU). In this case, Babylon.js has to recreate ALL low level resources (including textures, shaders, program, buffers, etc.). The process is entirely transparent and done under the hood by Babylon.js.

As a developer you should not be concerned by this mechanism. However, to support this scenario, Babylon.js may need an additional amount of memory to keep track of resources creation. If you do not need to support WebGL context lost event, you can turn off the tracking by instantiating your engine with doNotHandleContextLost option set to true.

If you created resources that need to be rebuilt (like vertex buffers or index buffers), you can use the `engine.onContextLostObservable` and `engine.onContextRestoredObservable` observables to keep track of the context lost and context restored events.

## Scene with large number of meshes
If you have a large number of meshes in a scene, and need to reduce the time spent when adding/removing those meshes to/from the scene, There are several options of the `Scene` constructor that can help :
 - Setting the option `useGeometryIdsMap` to `true` will speed-up the addition and removal of `Geometry` in the scene.
 - Setting the option `useMaterialMeshMap` to `true` will speed-up the disposing of `Material` by reducing the time spent to look for bound meshes.
 - Setting the option `useClonedMeshMap` to `true` will speed-up the disposing of `Mesh` by reducing the time spent to look for associated cloned meshes.

For each of this options turned on, Babylon.js will need an additional amount of memory.

Also, If you are disposing a large number of meshes in a row, you can save unnecessary computation by turning the scene property `blockfreeActiveMeshesAndRenderingGroups` to true just before disposing the meshes, and set it back to `false` just after, like this :
````javascript

scene.blockfreeActiveMeshesAndRenderingGroups = true;
/*
 * Dispose all the meshes in a row here
 */
scene.blockfreeActiveMeshesAndRenderingGroups = false;

````
## Changing Mesh Culling Strategy
The culling is the process to select whether a mesh must be passed to the GPU to be rendered or not. It's done CPU side.  
If a mesh intersects the camera frustum in some way then it's passed to the GPU.  
Depending on its accuracy (checking mesh bouding boxes or bouding spheres only, trying to include or to exclude fast the mesh from the frustum), this process can be time consuming.   
In the other hand, reducing this process accuracy to make it faster can lead to some false positives : some meshes are passed to the GPU, are computed there and won't be finally visible in the viewport.   
By default, BABYLON applies "Bounding Sphere Only" exclusion test to check if a mesh is in the camera frustum.  
You can change this behaviour for any mesh of your scene at any time (and change it back then, if needed) this the property `mesh.cullingStrategy`.  
```javascript 
/**
* Possible values : 
         * - BABYLON.AbstractMesh.CULLINGSTRATEGY_STANDARD  
         * - BABYLON.AbstractMesh.CULLINGSTRATEGY_BOUNDINGSPHERE_ONLY  
         * - BABYLON.AbstractMesh.CULLINGSTRATEGY_OPTIMISTIC_INCLUSION  
         * - BABYLON.AbstractMesh.CULLINGSTRATEGY_OPTIMISTIC_INCLUSION_THEN_BSPHERE_ONLY  
*/

mesh.cullingStrategy = oneOfThePossibleValues;
```
* Standard : the more accurate and standard one (exclusion test)  
* Bounding Sphere Only : faster but less accurate (exclusion test)  
* Optimistic Inclusion : mesh center inclusion test then standard exclusion test, for meshes almost always expected in the frustum. Same accuracy than the standard test.  
* Optimistic Inclusion Then Bounding Sphere Only : mesh center inclusion test, then bounding sphere exclusion test only. Same accuracy than the bSphereOnly test, interesting for almost always in the frustum meshes.  

Optimistic Inclusion modes give a little gain. They keep the same accuracy than the basic mode on what they are applied (standard or bSphereOnly).  
BoundingSphereOnly modes, because they reduce a lot the accuracy, give a good perf gain. These should not be used with high poly meshes while sending false positives to the GPU has a real rendering cost. These can be very interesting for numerous low poly meshes instead. *Really useful if you are CPU bound**.  

## Performance Priority Modes

Starting with Babylon.js 5.22, you can now change how the scene will treat performance regarding backward compatibility and ease of use.

### Backward compatiblity mode (default)
By default, `scene.performancePriority` is set to `BABYLON.ScenePerformancePriority.BackwardCompatible`. In this mode, there is simply no change. The scene will keep prioritizing ease of use and backward compatibility.

### Intermediate mode
If you switch the `performancePriority` to `BABYLON.ScenePerformancePriority.Intermediate`, the scene will automatically:
* Freeze materials when they are ready. If you need to change something on a material, you will have to call `material.unfreeze()`, do your changes, and then call `material.freeze()` again
* New meshes will have their `alwaysSelectAsActiveMesh` property set to true. The system will then skip frustrum clipping for the mesh and always set it to active (saving complex CPU operations). Keep in mind to turn it off if your scene is GPU bound
* New meshes will have their `isPickable ` property set to false. Picking and action managers will not work anymore. You can always turn that property back on if you need picking for a specific mesh
* `scene.skipPointerMovePicking ` will be turned on (meaning that there will be no OnPointerMove events)
* `scene.autoClear` will be turned off

### Agressive mode
If you switch the `performancePriority` to `BABYLON.ScenePerformancePriority.Aggressive`, the scene will automatically:
* Enable all features of the `Intermediate` mode
* The scene will skip all the frustum clipping phase entirely (`scene.skipFrustumClipping` will be set to true)
* New meshes will have their `doNotSyncBoundingInfo` set to true
* The manager will not reset between frames (`scene.renderingManager.maintainStateBetweenFrames` is set to true). This means that if a mesh becomes invisible or transparent it will not be visible until this boolean is set to false again

 

** Please note that the `Intermediate` and `Aggressive` modes will not be backward compatible, which means that we will probably add more features in these modes in the future to support performance first**

You can see an example of how to use it here: https://playground.babylonjs.com/#6HWS9M

## Instrumentation
Instrumentation is a key tool when you want to optimize a scene. It will help you figure out where are the bottlenecks so you will be able to optimize what needs to be optimized.

### EngineInstrumentation
The EngineInstrumentation class allows you to get the following counters:
* *gpuFrameTimeCounter*: Time (in nanoseconds) spent by the GPU to render a single frame. Must be turned on with `instrumentation.captureGPUFrameTime = true`.
* *shaderCompilationTimeCounter*: Time (in milliseconds) spent by the CPU to compile all shaders. Must be turned on with `instrumentation.captureShaderCompilationTime = true`.

Here is an example of how to use engine instrumentation:
<Playground id="#HH8T00#1" title="Engine Instrumentation Example" description="Simple example of using engine instrumentation."/>

Please note that each counter is *PerfCounter* object which can provide multiple properties like average, total, min, max, count, etc.

The GPU timer requires a special extension (EXT_DISJOINT_TIMER_QUERY - also sometimes reported with the \_webgl2 prefix in WebGL2 context) in order to work. This extension had been disabled due to Spectre and Meltdown on all major browsers, but some have added it back, like Chrome and Edge. You can check if your browser supports this extension on the [Khronos SDK test page](https://www.khronos.org/registry/webgl/sdk/tests/conformance/extensions/ext-disjoint-timer-query.html) or on [WebGL report](https://webglreport.com/?v=2).

* Note: On Chrome mobile, this extension can be enabled at `chrome://flags#enable-webgl-developer-extensions` followed by a browser restart

### SceneInstrumentation
The SceneInstrumentation class allows you to get the following counters (per scene):
* *activeMeshesEvaluationTimeCounter*: Time (in milliseconds) spent to evaluate active meshes (based on active camera frustum). Must be turned on with `instrumentation.captureActiveMeshesEvaluationTime = true`.
* *renderTargetsRenderTimeCounter*: Time (in milliseconds) spent to render all render target textures. Must be turned on with `instrumentation.captureRenderTargetsRenderTime = true`.
* *drawCallsCounter*: Number of draw calls (actual calls to engine.draw) per frame. A good advice is to keep this number as small as possible.
* *frameTimeCounter*: Time (in milliseconds) spent to process an entire frame (including animations, physics, render targets, special fx, etc.). Must be turned on with `instrumentation.captureFrameTime = true`.
* *renderTimeCounter*: Time (in milliseconds) spent to render a frame. Must be turned on with `instrumentation.captureRenderTime = true`.
* *interFrameTimeCounter*: Time (in milliseconds) spent between two frames. Must be turned on with `instrumentation.captureInterFrameTime = true`.
* *particlesRenderTimeCounter*: Time (in milliseconds) spent rendering particles (including animations). Must be turned on with `instrumentation.captureParticlesRenderTime = true`.
* *spritesRenderTimeCounter*: Time (in milliseconds) spent rendering sprites. Must be turned on with `instrumentation.captureSpritesRenderTime = true`.
* *physicsTimeCounter*: Time (in milliseconds) spent simulating physics. Must be turned on with `instrumentation.capturePhysicsTime = true`.
* *cameraRenderTimeCounter*: Time (in milliseconds) spent to render a camera. Must be turned on with `instrumentation.captureCameraRenderTime = true`.

Those counters are all reset to 0 at the beginning of each frame. Therefore it is easier to access them in the onAfterRender callback or observable.

## Inspector

Starting with Babylon.js v4.0 you can use the Inspector to [analyze your scene](/toolsAndResources/inspector#inspector-pane) or turn on/off features or [debugging tools](/toolsAndResources/inspector#specific-debug-tools).

## VR/XR scenarios

When usingBabylon.js with WebVR or WebXR, enabling [Multiview](/features/featuresDeepDive/cameras/multiViewsPart1) is a quick way to almost double the rendering speed.



# How To reduce memory footprint

Babylon.js offers multiple options to reduce the memory usage of a scene:

## Turning off IndexedDB

By default, all assets are saved in the local indexedDB to reduce network calls when loading multiple time the same files.
This feature uses memory so you can turn it off at engine level with:

```
 engine.enableOfflineSupport = false;
```

## Turning off support for context lost / contest restore

Babylon.js will automatically recreate everything in a transparent way if the [WebGL context is lost](/features/featuresDeepDive/scene/optimize_your_scene#handling-webgl-context-lost).
While being handy, this feature consumes a lot of memory so you may want to turn if off when creating the engine with:

```
var engine = new BABYLON.Engine(canvas, true, {doNotHandleContextLost: true});
```

You can also turn it off after engine creation (but before creating any resources) with:

```
engine.doNotHandleContextLost = true;
```

## Removing cached vertex data

All vertex buffers keep a copy of their data on CPU memory to support collisions, picking, geometry edition or physics.
If you don't need to use these features, you can call this function to free associated memory:

```
scene.clearCachedVertexData();
```

## Removing cached texture buffers

In order to be able to serialize or rebuild them, all textures keep an internal buffer of the original source (could be a string if you used an url, but it could also be a buffer if you used a blob).
If you don't need to use these features, you can call this function to free associated memory:

```
scene.cleanCachedTextureBuffer();
```


You can find a demo here: <Playground id="#AS54U8#1" title="Reducing Memory Footprint Example" description="Simple example showing how to reduce the memory footprint of a scene."/>



## Render a scene and take a screenshot on a remote server

Capturing images of a Babylon scene (eg. GLTF model) from the server side can be useful for scenarios such as:
- Remote rendering of a scene to display on a device that does not support a browser
- Server side testing
- Creating a catalog of 3D model images

To get started follow the steps below:

## Setup a Babylon scene you would like to render

Create a local server hosting the scene or use a playground eg. <Playground id="#PN1NNI#1" title="Initial Setup" description="Simple example showing how to set up youur scene."/>

## Using Puppeteer
[Puppeteer](https://github.com/GoogleChrome/puppeteer) is an npm package that can be used to run and interact with a headless version of chrome. This way the same code written with Babylon to run in the browser should run the same way with puppeteer.

Create a browser instance and load a webpage
```
const browser = await puppeteer.launch({});
const page = await browser.newPage();
await page.goto("https://playground.babylonjs.com/frame.html#PN1NNI#1"); 
```

Inject JS into the webpage
```
page.evaluate("BABYLON.Engine.LastCreatedScene.activeCamera.alpha = 1.4;");
```

Take a screenshot of the webpage
```
await page.screenshot({path: './public/example.png'});
```
## Configuring to use the GPU
Typical server virtual machines do not provide access to a GPU and when they do provide access, setting up the proper drivers can be difficult to grant access to puppeteer. One method that has worked was using an [Azure NV virtual machine running Windows and installing grid drivers](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/n-series-driver-setup#nvidia-grid-drivers).

Once the VM is setup puppeteer must be configured to run in non-headless mode so that it utilizes the GPU renderer.
```
// Don't disable the gpu
var args = puppeteer.defaultArgs().filter(arg => arg !== '--disable-gpu');
// Run in non-headless mode
args = args.filter(arg => arg !== '--headless');
// Use desktop graphics
args.push("--use-gl=desktop")
// Lanch pupeteer with custom arguments
const browser = await puppeteer.launch({
    headless: false,
    ignoreDefaultArgs: true,
    args
});
```
After this initial setup, follow the same steps as described above

## Example
An example project can be found [here](https://github.com/TrevorDev/babylonServer)


# How To Render a Scene to a PNG

First you may ask why is it better than "ctrl + prt scr" screenshot or the Snippet app?

1. With a standard ctrl + print screen keypress, you can't create screenshots with higher resolutions than your screen resolution. WithBabylon.js screenshot feature, you can. There is no problem with creating a 1920x1080 screenshot on a 800x600 screen (provided the graphics card is powerful enough to compute it). However as you will see in the examples later there is no increase in pixel density.
2. The screenshot is of the rendered canvas only without further manipulation.
3. A sequence of screenshots can be taken that can be turned into an animated gif.

There are two methods available to do this using `BABYLON.Tools` which are `CreateScreenshot` and the more versatile `CreateScreenshotUsingRenderTarget`.

You also need to consider how you will trigger the screenshot. This can be done for example with a timer such as 'window.setTimeout' or by using the [Babylon.js action manager](/features/featuresDeepDive/events/actions) for a keyDown or onPointerDown trigger.

A major difference between `CreateScreenshot` and `CreateScreenshotUsingRenderTarget` is when you try to use them directly after creating a mesh or meshes. This is because they work differently.

For example

```javascript
var box = BABYLON.MeshBuilder.CreateBox("box", {}, scene);
BABYLON.Tools.CreateScreenshot(engine, camera, 400);
```

will produce an image of the box but

```javascript
var box = BABYLON.MeshBuilder.CreateBox("box", {}, scene);
BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, 400);
```

will only produce the scene background. This is because this method is activated before the box is actually rendered on the screen. If you want to use `CreateScreenshotUsingRenderTarget` in this way then you need to ensure the scene is rendered first as in this example.

```javascript
var box = BABYLON.MeshBuilder.CreateBox("box", {}, scene);
scene.render();
BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, 400);
```

However even this will not work if the scene is very complex and has not been rendered in time. It is best to use timing or an action.

## CreateScreenshot

It's done by simply calling this method: `BABYLON.Tools.CreateScreenshot(engine, camera, size)`.
You need to provide yourBabylon.js engine, the camera you want to use for the rendering, and a size.

Please note that the engine must be created with `preserveDrawingBuffer` option:

```javascript
var engine = new BABYLON.Engine(canvas, true, { preserveDrawingBuffer: true, stencil: true });
```

The size parameter is very versatile, it can be a simple number or an object.

### Examples of Results

Starting with a view of the part of the screen showing the canvas there then follows a sequence of images taken using `CreateScreenshot`

![Actual Screen](/img/how_to/scene/shss.png)  
View of Part of Screen Showing Canvas Used

![size = 200](/img/how_to/scene/sh200x200.png)  
`BABYLON.Tools.CreateScreenshot(engine, camera, 200)`

![size = 800](/img/how_to/scene/sh800x800.png)  
`BABYLON.Tools.CreateScreenshot(engine, camera, 800)`

![size = 1600](/img/how_to/scene/sh1600x1600.png)  
`BABYLON.Tools.CreateScreenshot(engine, camera, 1600)`

![size = \{width:800, height:400\}](/img/how_to/scene/sh800x400.png)  
`BABYLON.Tools.CreateScreenshot(engine, camera, {width:800, height:400})` canvas placed in the middle of image of given size

Precision can be used as a multiplier of the screen resolution.

![size = \{precision: 0.5\}](/img/how_to/scene/sh400p05.png)  
`BABYLON.Tools.CreateScreenshot(engine, camera, {precision: 0.5})`

![size = \{precision: 2\}](/img/how_to/scene/sh400p20.png)  
`BABYLON.Tools.CreateScreenshot(engine, camera, {precision: 2})`

## CreateScreenshotUsingRenderTarget

As for the other method it's done by simply calling this method: `BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, size)`.
You need to provide yourBabylon.js engine, the camera you want to use for the rendering, and a size.

Again the size parameter is very versatile and can be a simple number or an object. However you will see differences in the results using the same parameters as before.

_Hint:_ When using a camera other than the active camera, only objects located in the viewport of the active camera are visible. As a workaround, all meshes that should be visible can be explicitly set to `alwaysSelectAsActiveMesh = true`. In case of performance issues, the meshes can be set to `alwaysSelectAsActiveMesh = true` shortly before taking the screenshot and then to `alwaysSelectAsActiveMesh = false` again.

### Examples of Results

Starting with a view of the part of the screen showing the canvas there then follows a sequence of images taken using `CreateScreenshotUsingRenderTarget`

![Actual Screen](/img/how_to/scene/shss.png)  
View of Part of Screen Showing Canvas Used

![size = 200](/img/how_to/scene/rt200x200.png)  
`BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, 200)`

![size = 800](/img/how_to/scene/rt800x800.png)  
`BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, 800)`

![size = 1600](/img/how_to/scene/rt1600x1600.png)  
`BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, 1600)`

![size = \{width:800, height:400\}](/img/how_to/scene/rt800x400.png)  
`BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, {width:800, height:400})` canvas imaged sized as given.

Precision can be used as a multiplier of the screen resolution.

![size = \{precision: 0.5\}](/img/how_to/scene/rt400p05.png)  
`BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, {precision: 0.5})`

![size = \{precision: 2\}](/img/how_to/scene/rt400p20.png)  
`BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, {precision: 2})`

### Alternative Camera

The `CreateScreenshotUsingRenderTarget` has an extra facility, the camera used does not have to be the active camera.

While the active camera is showing the scene as in the above examples you can use this

```javascript
var camera2 = new BABYLON.FreeCamera("camera2", new BABYLON.Vector3(0, 200, 0), scene);
camera2.setTarget(BABYLON.Vector3.Zero());

BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera2, 400);
```

to produce

![secondcamera](/img/how_to/scene/fc.png)

## Pixel Density

The following image of the canvas on screen and the resulting screenshot using 'precision: 8' show that although the image is 8 times larger the pixel density stays the same.

![Screen Canvas](/img/how_to/scene/sbss.png)

![Enlarged Image](/img/how_to/scene/sbp80.png)

## Gif Creation

In order to create an animated Gif, you will usually need a set of static images to stick together.

Either of the following set of codes produces a series of images that you can turn into an animated gif:

```javascript
var imgNm = 0;
scene.registerAfterRender(function () {
  box.rotation.y += (2 * Math.PI) / 90;
  if (imgNm++ < 90) {
    BABYLON.Tools.CreateScreenshot(engine, camera, 200);
  }
});
```

```javascript
var imgNm = 0;
scene.registerAfterRender(function () {
  box.rotation.y += (2 * Math.PI) / 90;
  if (imgNm++ < 90) {
    BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, 200);
  }
});
```

Here is the result after stitching in your favorite external tool:

![Gif](/img/how_to/scene/ssanim.gif)

## Callback Function

There is a further parameter that can be added to both methods of obtaining screenshots. This is a callback function added after the size parameter. The methods become `BABYLON.Tools.CreateScreenshot(engine, camera, size, onSuccessCallback)` and `BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, size, onSuccessCallback)`.

This callback is a function that takes the image data provided by the method and instead of opening or saving the image allows you to manipulate it instead.

For example when you have rendered this scene

![Box and sky](/img/how_to/scene/bx1.png)

by triggering either of these

```javascript
BABYLON.Tools.CreateScreenshot(engine, camera, 200, function (data) {
  var mat = new BABYLON.StandardMaterial("mat", scene);
  mat.diffuseTexture = new BABYLON.Texture(data, scene);
  box.material = mat;
});

BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, 200, function (data) {
  var mat = new BABYLON.StandardMaterial("mat", scene);
  mat.diffuseTexture = new BABYLON.Texture(data, scene);
  box.material = mat;
});
```

you obtain

![Box with sky texture and sky](/img/how_to/scene/bx2.png)

## Specific resolution with CreateScreenshot

You may end up having to use `BABYLON.Tools.CreateScreenshot` because you may need to capture advanced effects (that are not captured by the RTT version), In this case, if you want to get a specific resolution you can use the following code (please note the direct use of the `ScreenshotTools` class):

Example:

```javascript
var currentCanvasSizeWidth = canvas.style.width;
var currentCanvasSizeHeight = canvas.style.height;
activeCanvas.style.width = renderWidth + "px";
activeCanvas.style.height = renderHeight + "px";
engine.resize(true);
BABYLON.ScreenshotTools.CreateScreenshotWithResizeAsync(engine, scene.activeCamera, renderWidth, renderHeight).then(() => {
  canvas.style.width = currentCanvasSizeWidth;
  canvas.style.height = currentCanvasSizeHeight;
  engine.resize(true);
});
```



## Record a Scene to a Video

First, you may ask why is it better than an external video capture tool?

Thanks to the Html5 standard being always in motion, we can now, in modern browsers, directly record a stream generated from a canvas. This ensures that no framerate drop will occur during the recording and it is all happening auto-magically in the browser.

## How to record with the inspector 
A new action has been added to the Tools tab of the inspector. You can find a Start Recording Video button in compatible browsers.

![InspectorTools](/img/how_to/scene/inspectorVideoRecorder.png)

This will by default records 7 seconds of video. You can press the button again anytime during the recording session to stop it earlier.

## How to record by code

### Check support
As the browser support is still not wide enough, recording the canvas should always be preceeded by a capability check. You can simply use this code to ensure the correct availability of the required APIs in your browser:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
}
```

### Simple Record
In order to record your currently displayed scene, you can simply use this code:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording();
}
```

You can see a <Playground id="#47H64G" title="Simple Video Recording Example" description="Simple example of recording a video of the current scene."/>

This will by default record 7 seconds of video to a file name "babylonjs.webm".

### Changing default File Name
You can pass the file name to the startRecording API:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording("test.webm");
}
```

You can see a live version here: <Playground id="#47H64G#1" title="Changing The Default Recorded Video Name" description="Simple example showing how to record a video of the current scene and change the default file name."/>

This will by default record 7 seconds of video to a file name "test.webm".

### Changing default Record Time
You can pass the default time in seconds to the startRecording API:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording("test.webm", 2);
}
```

You can see a live demo here: <Playground id="#47H64G#2" title="Chaning Default Record Time" description="Simple example showing how to change the default record time of recorded videos."/>

This will by default record 2 seconds of video to a file name "test.webm".

### Stop video before the Record Time
Once a record is in progress, you can stop it earlier by using the  `stopRecording` Api:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording();
    setTimeout(() => {
        recorder.stopRecording()
    }, 500);
}
```

You can see a live version here: <Playground id="#47H64G#3" title="Stopping Video Before Record Time" description="Simple example showing how to stop recording before the allotted time has completed."/>

This will record 500 milliseconds of video to a file name "babylonjs.webm".

### When does the record end
To detect the end of the recording (either reaching the record time or manually stopped), you can use the promise return by the `startRecording` API:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording().then(() => {
        alert("done");
    });
}
```

You can see a live version here: <Playground id="#47H64G#4" title="Detect Recording End" description="Simple example showing how to detect when a recording has ended."/>

This will record 7 seconds of video to a file name "babylonjs.webm" and display the "done" message.

### How to not download automatically the file
Passing the fileName to `null` will prevent the download to happen automatically and as in the previous topic, you can rely on the `startRecording` return promise to deal with the video data on your own:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording(null, 1).then((videoBlob) => {
        // Do Something with the videoBlob.
    });
}
```

You can see a live version here: <Playground id="#47H64G#5" title="Not Downloading The Recorded Video" description="Simple example showing how you can stop an automatic download of the recorded video."/>

This will record 1 second of video to a blob.

## Limitations
Video Recording is based on both MediaRecorder and Canvas.captureStream() APIs which are still not broadly supported. The recording support is then limited by the browser capability to record a canvas.

The second limitations is the file format you can record to seems to be curently limited to webm. You can not directly record to .mp4 or .mov with this method so far. 

Let's hope that wider browser and file format support will be added soon.


## How To Use **SceneOptimizer**

Rendering a scene on a browser is a great experience because you can reach a lot of different users and hardware. But the main associated caveat is that you can encounter very low-end devices.

The `SceneOptimizer` tool is designed to help you reach a specific framerate by gracefully degrading rendering quality at runtime.

----

## Basic usage

To start using the `SceneOptimizer`, you can create a new `BABYLON.SceneOptimizer` instance.
The `SceneOptimizer` constructor requires the current scene and a `BABYLON.SceneOptimizerOptions` object (we will get back to it later).

```javascript
var options = new BABYLON.SceneOptimizerOptions();
options.addOptimization(new BABYLON.HardwareScalingOptimization(0, 1));

// Optimizer
var optimizer = new BABYLON.SceneOptimizer(scene, options);
```

When creating the` SceneOptimizer` you can provide the following parameters:
- A `BABYLON.Scene` which will defines the scene to work on
- A `BABYLON.SceneOptimizerOptions` which will defines the options to use with the `SceneOptimizer`
- A `boolean` which will defines if priorities must be generated and not read from `SceneOptimization` property (true by default)
- A `boolean` which will defines if the optimizer will run in improvement mode (see below) (false by default)

The `SceneOptimizer` object allows you to set several properties:
- `optimizations`: This property contains the list of current optimizations
- `targetFrameRate`: This property defines the target frame rate to reach (60 by default)
- `trackerDuration`: This property defines the interval between two checks (2000ms by default)
- `currentFrameRate`: This property (read-only) gets the current frame rate checked by the `SceneOptimizer`
- `currentPriorityLevel`: This property (read-only) gets the current priority level (0 at start)
- `onSuccessObservable`: This property defines an observable called when the optimizer reaches the target frame rate
- `onNewOptimizationAppliedObservable`: This property defines an observable called when the optimizer enables an optimization
- `onFailureObservable`: This property defines an observable called when the optimizer is not able to reach the target frame rate

It also provides several functions:
- `start()`: used to start the overall optimization process
- `stop()`: used to stop the current process
- `reset()`: used to restore the current priority level to 0
- `dispose()`: used to release all resources

-----

## Helper

You can also decide to use a static helper that will create everything you need in one line. `BABYLON.SceneOptimizer.OptimizeAsync()`. You can call this function when you want to optimize your scene. The simplest call you can do is the following:

```javascript
BABYLON.SceneOptimizer.OptimizeAsync(scene),
```

You have to provide at least a scene. That previous code line is actually equivalent to this:

```javascript
BABYLON.SceneOptimizer.OptimizeAsync(scene, BABYLON.SceneOptimizerOptions.ModerateDegradationAllowed(),
function() {
   // On success
}, function() {
   // FPS target not reached
});
```

As you can see, you can provide success/fail callbacks and a set of options.
Please note that the `BABYLON.SceneOptimizer.OptimizeAsync()` function returns a `SceneOptimizer` object which is created with `autoGeneratePriorities` to false.

----

## Options

A set of options contains a list of optimizations to apply in a specific order. As soon as the target FPS is reached, the `SceneOptimizer` stops. There are different layers (or passes) that are applied one after another. The `SceneOptimizer` pauses between each layer to ensure a stable FPS and also for measuring. Create a  `BABYLON.SceneOptimizerOptions` like this:

```javascript
// With a target framerate of 50fps and a check|rate of 500ms
let optimizerOptions = new BABYLON.SceneOptimizerOptions(50, 500);
```

Here are the properties available on a `BABYLON.SceneOptimizerOptions` instance:

* `targetFrameRate`: a number defining the FPS you want to achieve (60 by default)
* `optimizations`: an array of `BABYLON.SceneOptimization` objects.
* `trackerDuration`: time in milliseconds between passes (2000 by default)

By default, there are 3 sets available:

```javascript
BABYLON.SceneOptimizerOptions.LowDegradationAllowed()
BABYLON.SceneOptimizerOptions.ModerateDegradationAllowed()
BABYLON.SceneOptimizerOptions.HighDegradationAllowed()
```

All these sets return a `BABYLON.SceneOptimizerOptions` object configured with progressive degradations.

Based on these optimizations, the basic sets are configured like this:

* **BABYLON.SceneOptimizerOptions.LowDegradationAllowed()**:

  

   * Level 0: `MergeMeshesOptimization`, `ShadowsOptimization` and `LensFlaresOptimization`
   * Level 1: `PostProcessesOptimization` and `ParticlesOptimization`
   * Level 2: `TextureOptimization(2, 1024)`

* **BABYLON.SceneOptimizerOptions.ModerateDegradationAllowed()**:

  

   * Level 0: `MergeMeshesOptimization`, `ShadowsOptimization` and `LensFlaresOptimization`
   * Level 1: `PostProcessesOptimization` and `ParticlesOptimization`
   * Level 2: `TextureOptimization`(2, 512)
   * Level 3: `RenderTargetsOptimization`
   * Level 4: `HardwareScalingOptimization`(4, 2)

* **BABYLON.SceneOptimizerOptions.HighDegradationAllowed()**:

  

   * Level 0: `MergeMeshesOptimization`, `ShadowsOptimization` and `LensFlaresOptimization`
   * Level 1: `PostProcessesOptimization` and `ParticlesOptimization`
   * Level 2: `TextureOptimization(2, 256)`
   * Level 3: `RenderTargetsOptimization`
   * Level 4: `HardwareScalingOptimization(4, 4)`

## The Built-in Optimizations.

 The `priority` of an optimization, is used by the `SceneOptimizer` to form a queue of optimizations. When performing optimizations, the `SceneOptimizer` starts with optimizations with lower `priority` then continues onwards to optimizations with higher `priorities`:



* `BABYLON.MergeMeshesOptimization(priority)`: This optimization will merge meshes with same material.
* `BABYLON.TextureOptimization(priority, maximumSize)`: This optimization tries to reduce the size of render textures.
* `BABYLON.HardwareScalingOptimization(priority, maximumScale)`: This optimization increments or decrements the value of hardware scaling. This is a really aggressive optimization that could really help if you are GPU bound.
* `BABYLON.ShadowsOptimization(priority)`: This optimization disables shadows (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.PostProcessesOptimization(priority)`: This optimization disables post-processes (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.LensFlaresOptimization(priority)`: This optimization disables lens flares (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.ParticlesOptimization(priority)`: This optimization disables particles (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.RenderTargetsOptimization(priority)`: This optimization disables render targets (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.CustomOptimization(priority)`: This optimization will call two callbacks when required: 
 * `onApply(scene, optimizer)`: A custom callback used to apply custom optimizations. It must return true if all optimizations where applied
 * `onGetDescription()`: This callback must return a string describing the action of the optimization

---

### Custom Optimizations.

You can create you own optimizations by extending the class `BABYLON.CustomOptimization`. The new class must provide two functions, `onApply` and `onGetDescription`. Every instance takes a `priority` , its only argument and also a number. For example:

```javascript
class MyCustomOptimization extends BABYLON.CustomOptimization{
    constructor(priority){
        super(priority)
    }

    onApply(){
        // Some optimizing code
    }
    onGetDescription(){
        // A desription of your optimization
        return "I make framerate go prrrr!";
    }
};

options.addOptimization(new MyCustomOptimization(2));
```

A much simpler shorthand is available, using the `addCustomOptimization` method, on a `BABYLON.SceneOptimizerOptions()` instance:

```javascript
// Using shorthand syntax, fn(onApply, onGetDescrition, priority)
options.addCustomOptimization(function () {
	// Some optimizing code
}, function () {
    return "Making optimizations...";
}, 0.6);
```

-----

## Advanced Usage

You can create your own set of options with the following code (please note that if `autoGeneratePriorities` is true, you don't need to define the priority value)

```javascript
var result = new BABYLON.SceneOptimizerOptions(60, 2000);

var priority = 0;
result.optimizations.push(new BABYLON.ShadowsOptimization(priority));
result.optimizations.push(new BABYLON.LensFlaresOptimization(priority));

// Next priority
priority++;
result.optimizations.push(new BABYLON.PostProcessesOptimization(priority));
result.optimizations.push(new BABYLON.ParticlesOptimization(priority));

// Next priority
priority++;
result.optimizations.push(new BABYLON.TextureOptimization(priority, 256));

// Next priority
priority++;
result.optimizations.push(new BABYLON.RenderTargetsOptimization(priority));

// Next priority
priority++;
result.optimizations.push(new BABYLON.HardwareScalingOptimization(priority, 4));

return result;
```

----

## Improvement Mode

When created in improvement mode (4th parameter of the constructor), the `SceneOptimizer` object will run all optimization while the current FPS is above the target frame rate. So, for instance if, the target FPS is 60, the optimizer will execute all optimizations in its list while the FPS remains at 60. It is a good tool to provide rendering improvements to a given scene.
Please note that when in improvement mode, the optimizations will adapt their behaviour automatically (for instance, the `ShadowsOptimization` will turn shadows on instead of off).

---

## Demos

<Playground id="#3Q8PCL" title="Scene Optimizer Example" description="Simple example of how to use the scene optimizer."/>

<Playground id="#WZNAU4#4" title="CustomOptimization Example" description="A Playground Example Of The CustomOptimization in action"/>




# The Scene

The scene is somewhat like the stage on which all the meshes are placed to be seen and the cameras and lights are placed that make them viewable. Of course there are more than meshes, cameras and lights that make a scene a good experience for your users, for example the user interface. Also there are special effects to be had to make the environment more realistic. Want to overlap two or more scenes that is possible as well. 

Want to build a scene with the minimum of code then fast build is for you. 

What else might you expect of your scene? You might expect to be able to

* have the scene react to clicks and touches;
* have your own design displayed when your scene is loading;
* optimise your scene to maintain a good speed;
* output images of particular views of your scene.


## How to use RenderTargetTexture and run multiple passes

Sometimes it's interesting to render a scene multiple times and compose the generated passes for the final image. There are multiple uses for that: you can generate a texture in real time, to make a car rearview mirror for example, or you can perform complex effects with multiple independent renders that are combined together. 

The PostProcess API doesn't let you render a scene twice. That's where RenderTargetTexture (RTT) comes into play. Several [games use multiple passes for their graphics](http://www.adriancourreges.com/blog/2016/09/09/doom-2016-graphics-study/).

## Creating a RenderTargetTexture

You need to create a RenderTargetTexture and attach it to the scene. It's pretty straightforward:

```    
var renderTarget = new BABYLON.RenderTargetTexture(
    'render to texture', // name 
    512, // texture size
    scene // the scene
);
scene.customRenderTargets.push(renderTarget); // add RTT to the scene
```

You also need to pick which objects will be rendered to that texture. This enables you to select only a few objects for a particular effect, or use simpler meshes for faster rendering.

```
let sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2, segments: 32}, scene); // create your mesh
renderTarget.renderList.push(sphere); // add it to the RTT
```

## Using the RTT in your scene as a regular texture

You can use the rendered image as the texture of an object in your main render. Just set it as the texture of a material:

```
var mat = new BABYLON.StandardMaterial("RTT mat", scene);
mat.diffuseTexture = renderTarget;
```

In the example we only add half of the spheres to the RTT, showing how you can selectively pick the objects rendered there.

Playground example: <Playground id="#69DRZ1" title="Render Target Texture" description="Simple example of using the render target texture."/>

## Making multiple passes and composing them

Another possibility, as mentioned, is making multiple render passes of the main camera and compose them. Let's do that, adding a simple effect on all meshes and compose it with the original material. One interesting effect to simulate with this technique is water caustics. We can render the scene applying a material that simulates caustics with a wave generator and mix it with the base texture.

Since v5.0 it's very easy to use a different material than the regular material (`mesh.material`) when a mesh is rendered into a render target texture: simply use `RenderTargetTexture.setMaterialForRendering(meshOrMeshes, material)`.

```javascript
const causticMaterial = new BABYLON.ShaderMaterial(
    'caustic shader material', // human name
    scene,
    'caustic', // shader path
    {
        attributes: ['position', 'normal', 'uv'],
        uniforms: ['world', 'worldView', 'worldViewProjection', 'view', 'projection', 'time', 'direction']
    }
);

// the render texture. We'll render the scene with caustic shader to this texture.
const renderTarget = new BABYLON.RenderTargetTexture('caustic texture', 512, scene);
scene.customRenderTargets.push(renderTarget);

renderTarget.setMaterialForRendering(ground, causticMaterial);
```

For the final pass we'll create a shader to merge the base render (which will be provided in the GLSL as `textureSampler`) and the caustic texture, which we declare here as `causticTexture`. 

```javascript
// create the final pass composer
var finalPass = new BABYLON.PostProcess(
    'Final compose shader', 
    'final', // shader name
    null, // attributes
    [ 'causticTexture' ], // textures
    1.0,  // options
    camera,
    BABYLON.Texture.BILINEAR_SAMPLINGMODE, // sampling
    engine // engine
);
finalPass.onApply = (effect) => {
    effect.setTexture('causticTexture', renderTarget); // pass the renderTarget as our second texture
};
```

Playground example: <Playground id="#TG2B18#60" title="Multiple Passes Example" description="Simple example showing how to run multiple passes with the render target texture."/>. On the left you'll see the base render, on the middle the caustic render, and on the right both combined together.

## Performance and tips

Remember that you'll be rendering your scene multiple times, one for each pass. This can significantly slow things down if you are not careful. There are a number of strategies to improve performance:

- reduce the RTT size.
- render as few objects as you can on the RTT.
- use a simple shader on the RTT pass.
- prefer simpler meshes.
- use instances. If you have a large amount of copies of the same object, instances are a good optimization. You only change the material of the base mesh.

Replacing materials is an expensive operation on Babylon, as it requires a resync from the CPU. If your meshes use materials, such as `ShaderMaterial` or a `PBRMaterial`, this might impact significantly on the FPS rate. The example above is simple to follow and understand the concept, but there's a way to achieve much better performance, by freezing materials. Here's how to do it.

Note that since v5.0 you don't need to add some complicated code in the `RTT.onBeforeRender` / `RTT.onAfterRender` observers to save/replace the effects manually, you just have to freeze the materials you know that they won't change and you are good to go!

First, create objects that will be in the RTT with a clone of the RTT shader material.

```javascript
// helper function to create clones of the caustic material
// we need that because we'll have different transforms on the shaders
let rttMaterials = [];
const getCausticMaterial = () => {
    let c = rttMaterial.clone();
    c.freeze(); // freeze because we'll only update uniforms
    rttMaterials.push(c);
    return c;
};

// some material for the ground.
var grass0 = new BABYLON.StandardMaterial("grass0", scene);
grass0.diffuseTexture = new BABYLON.Texture("textures/grass.png", scene);
grass0.freeze();

// Our built-in 'ground' shape.
var ground = BABYLON.MeshBuilder.CreateGround("ground", {width: 6, height: 6}, scene);
ground.material = grass0;
// add caustics
renderTarget.setMaterialForRendering(ground, getCausticMaterial());
renderTarget.renderList.push(ground);
```

Apply any uniforms on all material clones:

```javascript
scene.onBeforeRenderObservable.add(() => {
    // ... 
    rttMaterials.forEach((c) => c.setFloat('time', timeDiff));
});
```

The example has the complete code, including animated objects and instances. You could freeze some meshes with `scene.freezeActiveMeshes()` to improve the performance even further.

Playground example: <Playground id="#S1W87B#42" title="Performance Example" description="Example of managing performance when running multiple passes."/>


### Notes about your shader

Note that since you replace the material with a shader from the scratch for mesh instances, you need to handle effects such as animation or the instance transformation,and this will affect your vertex shader (and possibly your fragment shader as well). There are [several includes in Babylon](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Shaders/ShadersInclude) that help with that. Here's a sample vertex shader with support for bone animations and instances:

```glsl
precision highp float;

attribute vec3 position;
attribute vec2 uv;

uniform mat4 view;
uniform mat4 projection;
uniform mat4 worldViewProjection;

varying vec2 vUV;

#include<bonesDeclaration>
#include<instancesDeclaration>

void main() {
    vec3 positionUpdated = position;

    #include<instancesVertex>
    #include<bonesVertex>

    vec4 worldPos = finalWorld * vec4(positionUpdated, 1.0);

    vUV = uv;

    gl_Position = projection * view * worldPos;
}
```

### Debugging multiple passes

Your final composer might become a complicated shader, and each pass might be complicated in itself. You certainly will need to debug shaders along the way. One way to easily debug individual passes is to show only that pass to the screen, commenting the rest of the code.

```
varying vec2 vUV;
uniform sampler2D somePassTexture;

void main() {
    // comment other code
    vec4 debugColor = texture2D(someTexture, vUV);
    gl_FragColor = debugColor;
}
```

Testing passes in separate and then adding them one at a time to the composer will make it easier to debug any issues. You can use the technique from the playgrounds above, splitting the screen on columns, each with a different pass, as well.

Finally you can also check RT textures with the [Babylon inspector](/toolsAndResources/inspector).


Scene

Coming next

Scene

Learn how to quickly build a world in a "scene" within Babylon.js.

Interacting With Scenes

Begin learning about how to develop interactions for your Babylon.js scenes.

Using Multiple Scenes

Learn about using multiple scenes at the same time in Babylon.js.

Using Multiple Canvases

Learn about using multiple canvases at the same time in Babylon.js.

Applying Delta Changes To A Scene

Learn about using the delta system in Babylon.js to save and reload changes made to your scenes.

Creating Custom Loading Screens

Learn how to create custom loading screens in Babylon.js.

Optimizing Your Scene

Learn how to optimize your scene in Babylon.js.

The Scene Optimizer

Learn all about the scene optimizer in Babylon.js.

Optimizing With Octrees

Learn how to optimize your scene using octrees in Babylon.js.

Optimizing Using Cached Resources

Learn how to optimize your scene using cached resources in Babylon.js.

Floating Origin (Huge Scenes Support)

Learn how to manage huge scenes using floating-origin trick

Reducing Memory Footprint

Learn how to reduce the memory footprint of scenes in Babylon.js.

Offscreen Canvas

Learn all about the offscreen canvas in Babylon.js.

Render Scenes To .png Files

Learn how to render scenes to .png files.

Render Scenes To Video.

Learn how to render scenes to video files.

Using Clipping Planes

Learn all about clipping planes in Babylon.js.

Rendering Scenes On A Remote Server

Learn how to render scenes on a remote server and take screenshots.

In-Depth layerMask

Learn how the layerMask property work accross the library