Type Function Library graphics.* Return value Mask Revision Release 2024.3703 Keywords image mask, masking, clipping, bit mask See also Masking Images (guide) object:setMask() object.isHitTestMasked object.maskScaleX object.maskScaleY
Creates a bit mask from an image file. The image is converted internally to grayscale. The white pixels of the bit mask allow the covered image to be visible, while black pixels hide (mask) the covered image. The area outside of the mask must be filled with black pixels which mask off the area outside the mask image.
The function returns a Mask object that can be applied to any display object using object:setMask().
For a walkthrough on how to use image masks, see the Masking Images guide.
The mask image must have width and height dimensions that are divisible by 4.
The mask image must be bordered by at least 3 pixels of black space on all four sides. You may need to increase the overall size of your mask image to include this border.
If the mask image is smaller than the target image, the region outside of the mask bounds will be fully masked (transparent).
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.
Currently, mask images are not dynamically selected based on the device resolution, unlike images that are displayed using display.newImageRect(). Thus, if your masks are very detailed and you need to choose a mask image of the proper resolution for different devices, you should check display.imageSuffix and use the appropriate mask image based on its value. See the example below for more details.
graphics.newMask( filename [, baseDir] )
String. The name of the image file to create the mask from.
Constant. Specifies the directory path that contains the mask image. Can be one of the following:
system.ResourceDirectory (default)system.DocumentsDirectorysystem.ApplicationSupportDirectorysystem.TemporaryDirectorysystem.CachesDirectory-- 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 )
-- This example shows how to select a different mask image based on the dynamic image suffix
-- It ensures that higher-resolution masks are used when the device resolution warrants it
-- Create and position image to be masked
local image = display.newImageRect( "image.png", 768, 1024 )
image:translate( display.contentCenterX, display.contentCenterY )
-- Create up-value reference for mask
local mask
-- Check the image suffix values and pick the correct mask
if ( display.imageSuffix == "@4x" ) then
--print( "using @4x" )
mask = graphics.newMask( "[email protected]" )
image:setMask( mask )
image.maskScaleX = 0.25
image.maskScaleY = 0.25
elseif ( display.imageSuffix == "@2x" ) then
--print( "using @2x" )
mask = graphics.newMask( "[email protected]" )
image:setMask( mask )
image.maskScaleX = 0.5
image.maskScaleY = 0.5
else
--print( "using @1x" )
mask = graphics.newMask( "circlemask.png" )
image:setMask( mask )
end