object:setMask()

Type Function
Object DisplayObject
Library display.*
Return value none
Revision Release 2024.3703
Keywords setMask, image mask, masking, clipping, bit mask
See also Masking Images (guide)
graphics.newMask()

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

Syntax

object:setMask( mask )
mask (required)

Mask. The mask object created with graphics.newMask(). Set to nil to remove the object's current mask.

Examples

Mask on Image
-- 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
Mask on Display Group
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)