Function

CGImageCreateWithMask

Creates a bitmap image from an existing image and an image mask.

Declaration

CGImageRef CGImageCreateWithMask(CGImageRef image, CGImageRef mask);

Parameters

image

The image to apply the mask parameter to. This image must not be an image mask and may not have an image mask or masking color associated with it.

mask

A mask. If the mask is an image, it must be in the DeviceGray color space, must not have an alpha component, and may not itself be masked by an image mask or a masking color. If the mask is not the same size as the image specified by the image parameter, the mask is scaled to fit the image.

Return Value

An image created by masking image with mask. You are responsible for releasing this object by calling CGImageRelease.

Discussion

The resulting image depends on whether the mask parameter is an image mask or an image. If the mask parameter is an image mask, then the source samples of the image mask act as an inverse alpha value. That is, if the value of a source sample in the image mask is S, then the corresponding region in image is blended with the destination using an alpha value of (1-S). For example, if S is 1, then the region is not painted, while if S is 0, the region is fully painted.

If the mask parameter is an image, then it serves as an alpha mask for blending the image onto the destination. The source samples of mask' act as an alpha value. If the value of the source sample in mask is S, then the corresponding region in image is blended with the destination with an alpha of S. For example, if S is 0, then the region is not painted, while if S is 1, the region is fully painted.

See Also

Creating Bitmap Images

CGImageCreate

Creates a bitmap image from data supplied by a data provider.

CGImageCreateCopy

Creates a copy of a bitmap image.

CGImageCreateCopyWithColorSpace

Creates a copy of a bitmap image, replacing its colorspace.

CGImageCreateWithJPEGDataProvider

Creates a bitmap image using JPEG-encoded data supplied by a data provider.

CGImageCreateWithPNGDataProvider

Creates a bitmap image using PNG-encoded data supplied by a data provider.

CGImageCreateWithImageInRect

Creates a bitmap image using the data contained within a subregion of an existing bitmap image.

CGImageCreateWithMaskingColors

Creates a bitmap image by masking an existing bitmap image with the provided color values.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software