object:setMask()

Overview

Associates a mask with a display object. To remove an object’s mask, use object:setMask( nil ). You can modify a display object’s mask x and y position (object.maskX, object.maskY), x-scale and y-scale factors (object.maskScaleX, object.maskScaleY), and rotation (object.maskRotation).

For a walkthrough on how to use image masks, see the Masking Images guide.

Gotchas

• There is a nested masking limit of 3, so care must be taken when inserting masked objects into other masked objects which act as containers, including display.newContainer, widget.newScrollView, widget.newTableView, or a masked display group. Other display objects that utilize masks include display.newText, display.newEmbossedText, and any other masked display object. For example, a text object (one mask) inside a container (one mask) inside yet another container (one mask) would reach but not exceed the limit of 3 nested masks.

• Masks can be applied to display groups as well as individual display objects. Just remember that the group’s origin is at 0,0 (top left). The group mask will be centered over the group but you need to translate the group to center the group on the screen. See the example below.

Syntax

object:setMask( mask )

Examples

-- Create and position image to be masked
local image = display.newImageRect( "image.png", 768, 1024 )
image:translate( display.contentCenterX, display.contentCenterY )
 
-- Create mask and apply to image
local mask = graphics.newMask( "circlemask.png" )
image:setMask( mask )
 
-- Transform mask
image.maskScaleX, image.maskScaleY = 2,2

local g = display.newGroup()
-- Create and position image to be masked, and insert into group
local image = display.newImageRect( g, "image.png", 768, 1024 )

-- Center the Display Group
g:translate( display.contentCenterX, display.contentCenterY )
 
local mask = graphics.newMask("circlemask.png")
g:setMask(mask)