CGBitmapContext Reference

Derived from
CGContextRef
Framework
ApplicationServices/ApplicationServices.h
Companion guide
Quartz 2D Programming Guide
Declared in
CGBitmapContext.h

Overview

The CGBitmapContext.h header file defines functions that create and operate on a Quartz bitmap graphics context. A bitmap graphics context is a type of CGContextRef that you can use for drawing bits to memory. The functions in this reference operate only on Quartz bitmap graphics contexts created using the function CGBitmapContextCreate.

The number of components for each pixel in a bitmap graphics context is specified by a color space (defined by a CGColorSpaceRef, which includes RGB, grayscale, and CMYK, and which also may specify a destination color profile). The bitmap graphics context specifies whether the bitmap should contain an alpha channel, and how the bitmap is generated.

Functions by Task

Creating Bitmap Contexts

Getting Information About Bitmap Contexts

These functions return the values of attributes specified when a bitmap context is created.

Functions

CGBitmapContextCreate

Creates a bitmap graphics context.

CGContextRef CGBitmapContextCreate (
   void *data,
   size_t width,
   size_t height,
   size_t bitsPerComponent,
   size_t bytesPerRow,
   CGColorSpaceRef colorspace,
   CGBitmapInfo bitmapInfo
);
Parameters
data

A pointer to the destination in memory where the drawing is to be rendered. The size of this memory block should be at least (bytesPerRow*height) bytes.

In iOS 4.0 and later, and OS X v10.6 and later, you can pass NULL if you want Quartz to allocate memory for the bitmap. This frees you from managing your own memory, which reduces memory leak issues.

width

The width, in pixels, of the required bitmap.

height

The height, in pixels, of the required bitmap.

bitsPerComponent

The number of bits to use for each component of a pixel in memory. For example, for a 32-bit pixel format and an RGB color space, you would specify a value of 8 bits per component. For the list of supported pixel formats, see “Supported Pixel Formats” in the “Graphics Contexts” chapter of Quartz 2D Programming Guide.

bytesPerRow

The number of bytes of memory to use per row of the bitmap.

colorspace

The color space to use for the bitmap context. Note that indexed color spaces are not supported for bitmap graphics contexts.

bitmapInfo

Constants that specify whether the bitmap should contain an alpha channel, the alpha channel’s relative location in a pixel, and information about whether the pixel components are floating-point or integer values. The constants for specifying the alpha channel information are declared with the CGImageAlphaInfo type but can be passed to this parameter safely. You can also pass the other constants associated with the CGBitmapInfo type. (See CGImage Reference for a description of the CGBitmapInfo and CGImageAlphaInfo constants.)

For an example of how to specify the color space, bits per pixel, bits per pixel component, and bitmap information using the CGBitmapContextCreate function, see “Creating a Bitmap Graphics Context” in the “Graphics Contexts” chapter of Quartz 2D Programming Guide.

Return Value

A new bitmap context, or NULL if a context could not be created. You are responsible for releasing this object using CGContextRelease.

Discussion

When you call this function, Quartz creates a bitmap drawing environment—that is, a bitmap context—to your specifications. When you draw into this context, Quartz renders your drawing as bitmapped data in the specified block of memory.

The pixel format for a new bitmap context is determined by three parameters—the number of bits per component, the color space, and an alpha option (expressed as a Image Bitmap Information constant). The alpha value determines the opacity of a pixel when it is drawn.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
CGBitmapContext.h

CGBitmapContextCreateImage

Creates and returns a Quartz image from the pixel data in a bitmap graphics context.

CGImageRef CGBitmapContextCreateImage (
   CGContextRef c
);
Parameters
c

A bitmap graphics context.

Return Value

A CGImage object that contains a snapshot of the bitmap graphics context or NULL if the image is not created.

Discussion

The CGImage object returned by this function is created by a copy operation. Subsequent changes to the bitmap graphics context do not affect the contents of the returned image. In some cases the copy operation actually follows copy-on-write semantics, so that the actual physical copy of the bits occur only if the underlying data in the bitmap graphics context is modified. As a consequence, you may want to use the resulting image and release it before you perform additional drawing into the bitmap graphics context. In this way, you can avoid the actual physical copy of the data.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CGBitmapContext.h

CGBitmapContextCreateWithData

Creates a bitmap graphics context with the specified callback function.

CGContextRef CGBitmapContextCreateWithData(
   void *data,
   size_t width,
   size_t height,
   size_t bitsPerComponent,
   size_t bytesPerRow,
   CGColorSpaceRef space,
   CGBitmapInfo bitmapInfo,
   CGBitmapContextReleaseDataCallback releaseCallback,
   void *releaseInfo
);
Parameters
data

A pointer to the destination in memory where the drawing is to be rendered. The size of this memory block should be at least (bytesPerRow*height) bytes.

In iOS 4.0 and later, and OS X v10.6 and later, you can pass NULL if you do not care where the data is stored. This frees you from managing your own memory, which reduces memory leak issues. Quartz has more flexibility when it manages data storage for you. For example, it’s possible for Quartz to use OpenGL for rendering if it takes care of the memory. Do not pass NULL if you are running on earlier operating systems.

width

The width, in pixels, of the required bitmap.

height

The height, in pixels, of the required bitmap.

bitsPerComponent

The number of bits to use for each component of a pixel in memory. For example, for a 32-bit pixel format and an RGB color space, you would specify a value of 8 bits per component. For the list of supported pixel formats, see “Supported Pixel Formats” in the “Graphics Contexts” chapter of Quartz 2D Programming Guide.

bytesPerRow

The number of bytes of memory to use per row of the bitmap.

colorspace

The color space to use for the bitmap context. Note that indexed color spaces are not supported for bitmap graphics contexts.

bitmapInfo

Constants that specify whether the bitmap should contain an alpha channel, the alpha channel’s relative location in a pixel, and information about whether the pixel components are floating-point or integer values. The constants for specifying the alpha channel information are declared with the CGImageAlphaInfo type but can be passed to this parameter safely. You can also pass the other constants associated with the CGBitmapInfo type. (See CGImage Reference for a description of the CGBitmapInfo and CGImageAlphaInfo constants.)

For an example of how to specify the color space, bits per pixel, bits per pixel component, and bitmap information using the CGBitmapContextCreate function, see “Creating a Bitmap Graphics Context” in the Graphics Contexts chapter of Quartz 2D Programming Guide.

releaseCallback

The custom release function to call when it is time to release the bitmap data. For the syntax of this function, see the description of the CGBitmapContextReleaseDataCallback data type. You may specify NULL for this parameter.

releaseInfo

A pointer to any data you want passed to the your custom release callback.

Return Value

A new bitmap context, or NULL if a context could not be created. You are responsible for releasing this object using CGContextRelease.

Discussion

When you call this function, Quartz creates a bitmap drawing environment—that is, a bitmap context—to your specifications. When you draw into this context, Quartz renders your drawing as bitmapped data in the specified block of memory.

The pixel format for a new bitmap context is determined by three parameters—the number of bits per component, the color space, and an alpha option (expressed as a Image Bitmap Information constant). The alpha value determines the opacity of a pixel when it is drawn.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGBitmapContext.h

CGBitmapContextGetAlphaInfo

Returns the alpha information associated with the context, which indicates how a bitmap context handles the alpha component.

CGImageAlphaInfo CGBitmapContextGetAlphaInfo (
   CGContextRef c
);
Parameters
context

A bitmap context.

Return Value

A bitmap information constant. If the specified context is not a bitmap context, kCGImageAlphaNone is returned. See CGImageAlphaInfo (renamed to CGBitmapInfo in OS X v10.4) for more information about values.

Discussion

Every bitmap context contains an attribute that specifies whether the bitmap contains an alpha component, and how it is generated. The alpha component determines the opacity of a pixel when it is drawn.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGBitmapContext.h

CGBitmapContextGetBitmapInfo

Obtains the bitmap information associated with a bitmap graphics context.

CGBitmapInfo CGBitmapContextGetBitmapInfo (
   CGContextRef c
);
Parameters
c

A bitmap graphics context.

Return Value

The bitmap info of the bitmap graphics context or 0 if c is not a bitmap graphics context. See CGImage Reference for a description of the Image Bitmap Information constants that can be returned.

Discussion

The CGBitmapInfo data returned by the function specifies whether the bitmap contains an alpha channel and how the alpha channel is generated, along with whether the components are floating-point or integer.

Availability
  • Available in OS X v10.4 and later.
Declared In
CGBitmapContext.h

CGBitmapContextGetBitsPerComponent

Returns the bits per component of a bitmap context.

size_t CGBitmapContextGetBitsPerComponent (
   CGContextRef c
);
Parameters
context

The bitmap context to examine.

Return Value

The number of bits per component in the specified context, or 0 if the context is not a bitmap context.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGBitmapContext.h

CGBitmapContextGetBitsPerPixel

Returns the bits per pixel of a bitmap context.

size_t CGBitmapContextGetBitsPerPixel (
   CGContextRef c
);
Parameters
context

The bitmap context to examine.

Return Value

The number of bits per pixel in the specified context, or 0 if the context is not a bitmap context.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGBitmapContext.h

CGBitmapContextGetBytesPerRow

Returns the bytes per row of a bitmap context.

size_t CGBitmapContextGetBytesPerRow (
   CGContextRef c
);
Parameters
context

The bitmap context to examine.

Return Value

The number of bytes per row of the specified context, or 0 if the context is not a bitmap context.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGBitmapContext.h

CGBitmapContextGetColorSpace

Returns the color space of a bitmap context.

CGColorSpaceRef CGBitmapContextGetColorSpace (
   CGContextRef c
);
Parameters
context

The bitmap context to examine.

Return Value

The color space of the specified context, or NULL if the context is not a bitmap context. You are responsible for retaining and releasing this object as necessary.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGBitmapContext.h

CGBitmapContextGetData

Returns a pointer to the image data associated with a bitmap context.

void * CGBitmapContextGetData (
   CGContextRef c
);
Parameters
context

The bitmap context to examine.

Return Value

A pointer to the specified bitmap context’s image data, or NULL if the context is not a bitmap context.

Discussion

If you provided the memory for the bitmap data, you can use this method to get that data pointer. If you passed NULL for the data pointer when creating your bitmap context, it is safe to get the data pointer in iOS 4.0 and later and OS X v10.6 and later only. In earlier versions of the operating system, passing NULL for the data parameter is not supported and may lead to crashes when attempting to access this data using this function.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
CGBitmapContext.h

CGBitmapContextGetHeight

Returns the height in pixels of a bitmap context.

size_t CGBitmapContextGetHeight (
   CGContextRef c
);
Parameters
context

The bitmap context to examine.

Return Value

The height in pixels of the specified context, or 0 if the context is not a bitmap context.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
CGBitmapContext.h

CGBitmapContextGetWidth

Returns the width in pixels of a bitmap context.

size_t CGBitmapContextGetWidth (
   CGContextRef c
);
Parameters
context

The bitmap context to examine.

Return Value

The width in pixels of the specified context, or 0 if the context is not a bitmap context.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
CGBitmapContext.h

Data Types

CGBitmapContextReleaseDataCallback

A callback function used to release data associate with the bitmap context. 

typedef void (*CGBitmapContextReleaseDataCallback)(void *releaseInfo,   void *data);
Discussion

The releaseInfo parameter contains the contextual data that you passed to the CGBitmapContextCreateWithData function. The data parameter contains a pointer to the bitmap data for you to release.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGBitmapContext.h


© 2003, 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-08-03)

Did this document help you? Yes It's good, but... Not helpful...