Function

CGImageCreate

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

Declaration

CGImageRef CGImageCreate(size_t width, size_t height, size_t bitsPerComponent, size_t bitsPerPixel, size_t bytesPerRow, CGColorSpaceRef space, CGBitmapInfo bitmapInfo, CGDataProviderRef provider, const CGFloat *decode, bool shouldInterpolate, CGColorRenderingIntent intent);

Parameters

width

The width, in pixels, of the required image.

height

The height, in pixels, of the required image

bitsPerComponent

The number of bits for each component in a source pixel. For example, if the source image uses the RGBA-32 format, you would specify 8 bits per component.

bitsPerPixel

The total number of bits in a source pixel. This value must be at least bitsPerComponent times the number of components per pixel.

bytesPerRow

The number of bytes of memory for each horizontal row of the bitmap.

colorspace

The color space for the image. The color space is retained; on return, you may safely release it.

bitmapInfo

A constant that specifies whether the bitmap should contain an alpha channel and its relative location in a pixel, along with whether the components are floating-point or integer values.

provider

The source of data for the bitmap. For information about supported data formats, see the discussion below. The provider is retained; on return, you may safely release it.

decode

The decode array for the image. If you do not want to allow remapping of the image’s color values, pass NULL for the decode array. For each color component in the image’s color space (including the alpha component), a decode array provides a pair of values denoting the upper and lower limits of a range. For example, the decode array for a source image in the RGB color space would contain six entries total, consisting of one pair each for red, green, and blue. When the image is rendered, Core Graphics uses a linear transform to map the original component value into a relative number within your designated range that is appropriate for the destination color space.

shouldInterpolate

A Boolean value that specifies whether interpolation should occur. The interpolation setting specifies whether Core Graphics should apply a pixel-smoothing algorithm to the image. Without interpolation, the image may appear jagged or pixelated when drawn on an output device with higher resolution than the image data.

intent

A rendering intent constant that specifies how Core Graphics should handle colors that are not located within the gamut of the destination color space of a graphics context. The rendering intent determines the exact method used to map colors from one color space to another. For descriptions of the defined rendering-intent constants, see CGColorRenderingIntent.

Return Value

A new bitmap image. You are responsible for releasing this object by calling CGImageRelease.

Discussion

The data provider should provide raw data that matches the format specified by the other input parameters. To use encoded data (for example, from a file specified by a URL-based data provider), see CGImageCreateWithJPEGDataProvider and CGImageCreateWithPNGDataProvider.

For information on supported pixel formats, see Quartz 2D Programming Guide.

See Also

Creating Bitmap Images

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.

CGImageCreateWithMask

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

CGImageCreateWithMaskingColors

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