Canvas API

The Canvas API, available in THEOplayer version 2.12.0 and onward, allows you to draw the current frame of the player to a 2D or WebGL context. This allows for advanced usages of the images, like transformations, drawing and cropping. 

Methods

The following methods are accessible via player.canvas:

Method name Arguments Description
drawImage context2D: CanvasRenderingContext2D, dx : number, dy : number

Draws the current frame to a 2D Canvas context, if possible. (If the video hasn't loaded yet, nothing will be drawn.)

The first argument is the destination 2D context for the draw operation. The other arguments are passed to the native CanvasRenderingContext2D.drawImage method. (Learn more)

 

context2D: CanvasRenderingContext2D, dx : number, dy : number, dWidth : number, dHeight  : number
context2D: CanvasRenderingContext2D, sx : number, sy : number, sWidth : number, sHeight : number, dx : number, dy : number, dWidth : number, dHeight : number
texImage2D contextWebGL: WebGLRenderingContext, target : GLenum, level : GLint, internalformat : GLint, format : GLenum, type : GLenum

Draws the current frame as a 2D texture to a WebGL (3D) context, if possible. (If the video hasn't loaded yet, nothing will be drawn.)

The first argument is the destination WebGL context for the draw operation. The other arguments are passed to the native WebGLRenderingContext.texImage2D method. (Learn more)

Considerations

Cross-origin restrictions

Browsers place additional security restrictions for cross-origin video content drawn to a canvas. When you draw video content retrieved without proper cross-origin settings to a canvas, the canvas becomes "tainted". A tainted canvas can still be used, but will throw errors when attempting to read pixel data from it (for example when calling getImageData or toBlob).

In order to avoid tainting the canvas, the video content must be retrieved with the proper CORS settings. Set crossOrigin to "anonymous" or "use-credentials" in the TypedSource of your SourceDescription when loading the video source into THEOplayer. This ensures that the content is always retrieved with CORS-enabled HTTP requests, and will not taint the canvas when drawn.

Drawing cross-origin content to WebGL context on iOS 10 and lower

iOS version 10 and lower has a bug that prevents drawing cross-origin video content to a WebGLRenderingContext, even when the proper CORS settings are provided (WebKit bug #135379). In particular, cross-origin 360° videos (using the THEOplayer VR API) only render correctly in iOS 11 and higher.

If you need to support iOS 10 and below, we recommend loading the stream from the same origin as the web page.

DRM protected content

It is not possible to render DRM protected content to a canvas.