
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 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/divingDeeper/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);
});
```



# 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/divingDeeper/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."/>


Offscreen Canvas