Canvas Layers

Benefits of layers

The HTML canvas element is a 2D graphics surface with a quite powerful set of drawing methods, but when a canvas is used for animation, the entire contents must be completely redrawn for each animation frame, even if only one item in the drawing has changed.

A far more efficient animation technique is to use a stack of transparent layers overlaying a background image, with the items to be animated each being drawn on a separate layer. Only the layers that change on each frame are redrawn and the other layers are left unchanged. The graphics engine can sort out the exposed areas to be redrawn from underlying layers without user code being required.

CanvasStack

A stack of canvas layers suitable for animation on a web page can be created and managed using a the CanvasStack object. This provides an array (initially empty) of transparent canvas layers directly overlaying an existing canvas along with methods for creating new layers or deleting existing layers.

An existing canvas element becomes the background layer to the canvas stack. Each new layer added is a transparent canvas the same size as the background canvas and positioned directly over it. The canvas layer may be drawn onto with the same methods as the background or any canvas element. Those areas left blank are transparent and the underlying canvas content will be visible.

In cases where the canvas dimensions have been styled to change with any resize of its containing element, a resize event handler ensures that layers track the background canvas dimensions.

Creating the CanvasStack requires a HTML canvas element to exist on the page, after the document is loaded the CanvasStack constructor is called passing the ID of the background canvas. The CanvasStack object creates an (empty) array for the overlay canvases. Each subsequent calls to the CanvasStack method createLayer will create a new transparent overlay canvas.

Getting started

Firstly download the library CanvasStack-2v01.js or the minified version CanvasStack-2v01-min.js and ensure that it will be loaded by including in the document header the following:

  <script src="[source directory/]CanvasStack-2v01-min.js"></script>

To insert a CanvasStack over a canvas element, make sure the background canvas element has a unique ID. The following HTML snippet shows and example. The width and height attributes set the number of drawing pixels on the canvas:

  <canvas id="cvs1" width="500" height="300"></canvas>

  ...
  var cvsStk = new CanvasStack("cvsId");

The returned CanvasStack object has the following methods:

Multiple CanvasStack instances can be created that refer to the same background. The stack properties are stored as properties of the background canvas itself to avoid conflict among CanvasStack instances

Creating a new layer

To create a CanvasStack layer, call the cvsStk.createLayer method, the ID of the HTML canvas element created will be automatically generated and returned as a string. The new transparent canvas will be placed on top of all the other layers already in the stack. A typical call to create a layer is as follows:

  var layer1_ID = cvsStk.createLayer();  // create a new layer, its ID string is returned

Once the new layer has been created a graphics context must be created to draw into the new canvas. To create a native canvas context, a reference to the canvas element is used as follows:

  var L1_ctx = document.getElementById(layer1_ID).getContext('2D');

If drawing with the Cango3D library the call is:

  var cgoL1 = new Cango3D(layer1_ID);

CanvasStack example

Figure 1 shows a spinning plate demo copied from the Canvas 3D Graphics page. In this demonstration two layers have been used, the background canvas holds the animation of a plate spinning on a stick, every 50 msec the plate is rotated, the background canvas layer is cleared and the plate and stick redrawn in their new orientations.

Here is the code snippet to create the stick and plate:

var ovlyID;
function drawPlate(cvsID)
{
  const stick = new Path3D(["M",0,0,0,"C",0,33,0,-5,66,0,-15,100,0], 
                      {y:-100, strokeColor:"sienna", lineWidth:3}),
        plate = new Shape3D(svgToCgo3D(shapeDefs.circle(50)), 
                      {xRot:-75, fillColor:"lime", backColor:"lime"}),
        plateNstick = new Group3D(stick, plate);
  let angle = 0;

  function turnPlate()
  {
    angle += 20;
    if (angle > 360)
      angle -= 360;

    plateNstick.rotateY(angle);  // apply matrix to Group3D
    g.render(plateNstick);
  }

  g = new Cango3D(cvsID),
  g.setWorldCoords3D(-50, -110, 100);
  g.setLightSource(0, 500, 200);
  ovlyID = cvsStk.createLayer(); // create a canvas layer

  setInterval(turnPlate, 50)     // keep doing this forever
}

To demonstrate the independence of the layers in the CanvasStack, the code above created an overlay canvas with ID saved as a global. We can write "Hullo World" on this overlay right across the spinning plate. The spinning plate is erased and redrawn every 50msec but the "hullo World" written on the overlay canvas is unaffected. We can clear the overlay canvas to erase "Hullo World" and not affect the pinning plate animation.

To try this code, click here. It will draw "Hullo World" over the spinning plate animation in Fig 1. Click here to erase the "Hullo World".

The source code for drawing 'Hullo World' is shown below.

function drawHullo()
{
  const oCtx = new Cango3D(ovlyID);  
  oCtx.setWorldCoords3D(-150, -150, 300);
  const txt = new Text3D("Hullo World", {
    zRot: 20,
    y:125,
    strokeColor:"blue",
    fontSize: 24,
    lorg:5,
    fontWeight: 600});
  oCtx.render(txt);
}

function clearHullo()
{
  const oCtx = new Cango3D(ovlyID); 
  oCtx.clearCanvas();
}

CanvasStack

CanvasStack constructor

Syntax:

var cvsStk = new CanvasStack(canvasID, [stackLimit]);

Description:

Creates a new CanvasStack object and an array initially holding only a reference to the background canvas as layer[0] if it doesn't already exist. As layers are created references are stored in the array. The array is unique to the background canvas. It is stored as a property of the canvas object so each background canvas can only host one CanvasStack instance.

Parameters:

Returns:

Object - Reference to the CanvasStack object just created. This object has a set of methods, described below.

CanvasStack methods