object.canvas

Type GroupObject
Object SnapshotObject
Library display.*
Revision Release 2022.3683
Keywords canvas
See also display.newSnapshot()
snapshot:invalidate()

Overview

This group is a special offscreen group that enables you to draw on the snapshot's texture without redrawing the objects in snapshot.group.

Syntax

snapshot.canvas

Canvas-style Invalidation

Normally, snapshot invalidates causes the texture to be cleared prior to rendering the snapshot group's children to a texture.

In contrast, when the canvas is invalidated, they render to the texture without clearing the texture first.

To invalidate the canvas, simply pass the "canvas" parameter to snapshot:invalidate() as shown in the example below.

Children

By default, when a canvas is invalidated, the children of the canvas are appended to the snapshot's group upon the next render pass. At this point, the canvas will be empty.

You can change this so that the children of the canvas are discarded by setting the canvasMode to "discard".

Canvas Properties

Properties of the canvas will be ignored and will not effect on the rendered result.

Instead, for rendering purposes, the properties of snapshot.group will be used instead.

For example, properties like position (or rotation, scale, alpha, etc) will be taken from the snapshot's group property, instead of from the canvas property.

In addition, changes to the snapshot.canvas will be reset to the corresponding value of snapshot.group just prior to when the canvas objects are drawn.

Canvas Groups vs Normal Groups

The canvas group behaves just like a normal group except:

Example

local w,h = display.contentWidth,display.contentHeight 
local snapshot = display.newSnapshot( w, h )

local brush = display.newImage( "brush.png" )
snapshot.canvas:insert( brush )

snapshot:invalidate( "canvas" )