OffscreenCanvas

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

The OffscreenCanvas interface provides a canvas that can be rendered off screen. It is available in both, the window and in a worker context.

Note: This API is currently implemented for WebGL1 and WebGL2 contexts only. See bug 801176 for Canvas 2D API support from workers.

Constructors

OffscreenCanvas()
OffscreenCanvas constructor. Creates a new OffscreenCanvas object.

Properties

OffscreenCanvas.height
The height of the offscreen canvas.
OffscreenCanvas.width
The width of the offscreen canvas.

Methods

OffscreenCanvas.getContext()
Returns a rendering context for the offscreen canvas.
OffscreenCanvas.toBlob()
Creates a Blob object representing the image contained in the canvas.
OffscreenCanvas.transferToImageBitmap()
Creates an ImageBitmap object from the most recently rendered image of the OffscreenCanvas.

Examples

Synchronous display of frames produced by an OffscreenCanvas

One way to use the OffscreenCanvas API, is to use a RenderingContext that has been obtained from an OffscreenCanvas object to generate new frames. Once a new frame has finished rendering in this context,  the transferToImageBitmap() method can be called to save the most recent rendered image. This method returns an ImageBitmap object, which can be used in a variety of Web APIs and also in a second canvas without creating a transfer copy.

To display the ImageBitmap, you can use a ImageBitmapRenderingContext context, which can be created by calling canvas.getContext("bitmaprenderer") on a (visible) canvas element. This context only provides functionality to replace the canvas's contents with the given ImageBitmap. A call to ImageBitmapRenderingContext.transferImageBitmap() with the previously rendered and saved ImageBitmap from the OffscreenCanvas, will display the ImageBitmap on the canvas and transfer its ownership to the canvas. A single OffscreenCanvas may transfer frames into an arbitrary number of other ImageBitmapRenderingContext objects.

Given these two <canvas> elements

<canvas id="one"></canvas>
<canvas id="two"></canvas>

the following code will provide the rendering using an OffscreenCanvas as described above.

var one = document.getElementById("one").getContext("bitmaprenderer"); 
var two = document.getElementById("two").getContext("bitmaprenderer");

var offscreen = new OffscreenCanvas(256, 256);
var gl = offscreen.getContext('webgl');

// ... some drawing for the first canvas using the gl context ...

// Commit rendering to the first canvas
var bitmapOne = offscreen.transferToImageBitmap();
one.transferImageBitmap(bitmapOne);

// ... some more drawing for the second canvas using the gl context ...

// Commit rendering to the second canvas 
var bitmapTwo = offscreen.transferToImageBitmap();
two.transferImageBitmap(bitmapTwo);

Asynchronous display of frames produced by an OffscreenCanvas

Another way to use the OffscreenCanvas API, is to call transferControlToOffscreen() on a <canvas> element, either on a worker or the main thread, which will return an OffscreenCanvas object from an HTMLCanvasElement object from the main thread. Calling getContext() will then obtain a RenderingContext from that OffscreenCanvas.

In order to make frames visible, you can call commit() on that RenderingContext, so that frames will be pushed back to the original <canvas> element.

Note that, in Firefox, this API is currently only implemented for the WebGL context (WebGLRenderingContext.commit()). For Canvas 2D API support from workers, see bug 801176.

main.js (main thread code):

var htmlCanvas = document.getElementById("canvas");
var offscreen = htmlCanvas.transferControlToOffscreen();

var worker = new Worker("offscreencanvas.js"); 
worker.postMessage({canvas: offscreen}, [offscreen]);

offscreencanvas.js (worker code):

onmessage = function(evt) {
  var canvas = evt.data.canvas.
  var gl = canvas.getContext("webgl");

  // ... some drawing using the gl context ...

  // Push frames back to the original HTMLCanvasElement
  gl.commit();
};

Specifications

Currently drafted as a proposal: OffscreenCanvas.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support Not supported 44 (44) [1] Not supported Not supported Not supported
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support Not supported 44.0 (44) [1] Not supported Not supported Not supported

[1] This feature is behind a feature preference setting. In about:config, set gfx.offscreencanvas.enabled to true.

See also

Document Tags and Contributors

 Contributors to this page: fscholz
 Last updated by: fscholz,