Type GroupObject
Object SnapshotObject
Library display.*
Revision Release 2024.3703
Keywords canvas
See also display.newSnapshot()


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



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.


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:


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" )