A new build of Corona SDK is now available to subscribers. Not a subscriber? Subscribe now.
CoronaSDK 2013.1126 | Released: 24 May 2013, 1:59am | What's New | Download Now
You will be redirected to the new docs in a few seconds.
If you are certain you want to see the old docs, click cancel.
Cancel | Continue to new docs
object:setMask( )
Description:
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's x and y position, x-scale and y-scale factors, and rotation (see related properties below).
Note: Starting with build 2011.505, bit masks can now be applied to text objects and display groups. Masks can be nested (masked groups of groups or other masked display objects within masked groups). Some platforms (e.g. Android) may have a mask nesting limit.
Syntax:
object:setMask( mask )
Example:
This sample code uses images from the Graphics/Flashlight sample in the Corona SDK. It applies a mask to the image and then scales the mask to twice its original size.
-- 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
Here is an example of how to add a bit mask to a 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 ) image:translate( display.contentCenterX, display.contentCenterY ) local mask = graphics.newMask("circlemask.png") g:setMask(mask) -- Center the mask over the Display Group g:setReferencePoint( display.CenterReferencePoint ) g.maskX = g.x g.maskY = g.y
Parameters:
mask
The mask object created with graphics.newMask(). Set to nil to remove the mask.
Returns:
Nothing.
Remarks:
There is currently a problem when applying bit masks to groups. Because a display group has the reference point at TopLeftReference (instead of CenterReference), the mask is also centered at TopLeft when it should be centered over a group as it is for vector objects. The workaround to the problem is to add the following code after creating and applying the mask to the group (g):
g:setReferencePoint( display.CenterReferencePoint ) g.maskX = g.x g.maskY = g.y
Supported on operating systems and platforms for build numbers shown:
- Mac OS X:Build 2011.268
- Windows:Build 2011.288
- iOS:Build 2011.268
- Android:Build 2011.288
Replies
How does the display object's reference point affect the mask when shifting maskX, and maskY?
For those looking for more info about masks: http://developer.anscamobile.com/reference/bitmap-mask
Thanks!
Mask is skewed when you use big assets.
http://developer.anscamobile.com/forum/2011/02/07/mask-trouble#comment-30527