Mac Developer Library

Developer

ApplicationServices Framework Reference CGBitmapContext Reference

Options
Deployment Target:

On This Page
Language:

CGBitmapContext Reference

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

  • Creates a bitmap graphics context.

    Declaration

    Swift

    func CGBitmapContextCreate(_ data: UnsafeMutablePointer<Void>, _ width: UInt, _ height: UInt, _ bitsPerComponent: UInt, _ bytesPerRow: UInt, _ colorspace: CGColorSpace!, _ bitmapInfo: CGBitmapInfo) -> CGContext!

    Objective-C

    CGContextRef CGBitmapContextCreate ( void *data, size_t width, size_t height, size_t bitsPerComponent, size_t bytesPerRow, CGColorSpaceRef space, 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. If the data parameter is NULL, passing a value of 0 causes the value to be calculated automatically.

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

  • Creates a bitmap graphics context with the specified callback function.

    Declaration

    Swift

    func CGBitmapContextCreateWithData(_ data: UnsafeMutablePointer<Void>, _ width: UInt, _ height: UInt, _ bitsPerComponent: UInt, _ bytesPerRow: UInt, _ colorspace: CGColorSpace!, _ bitmapInfo: CGBitmapInfo, _ releaseCallback: CGBitmapContextReleaseDataCallback, _ releaseInfo: UnsafeMutablePointer<Void>) -> CGContext!

    Objective-C

    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. If the data parameter is NULL, passing a value of 0 causes the value to be calculated automatically.

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func CGBitmapContextCreateImage(_ c: CGContext!) -> CGImage!

    Objective-C

    CGImageRef CGBitmapContextCreateImage ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

  • Obtains the bitmap information associated with a bitmap graphics context.

    Declaration

    Swift

    func CGBitmapContextGetBitmapInfo(_ c: CGContext!) -> CGBitmapInfo

    Objective-C

    CGBitmapInfo CGBitmapContextGetBitmapInfo ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGBitmapContextGetAlphaInfo(_ context: CGContext!) -> CGImageAlphaInfo

    Objective-C

    CGImageAlphaInfo CGBitmapContextGetAlphaInfo ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the bits per component of a bitmap context.

    Declaration

    Swift

    func CGBitmapContextGetBitsPerComponent(_ context: CGContext!) -> UInt

    Objective-C

    size_t CGBitmapContextGetBitsPerComponent ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the bits per pixel of a bitmap context.

    Declaration

    Swift

    func CGBitmapContextGetBitsPerPixel(_ context: CGContext!) -> UInt

    Objective-C

    size_t CGBitmapContextGetBitsPerPixel ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the bytes per row of a bitmap context.

    Declaration

    Swift

    func CGBitmapContextGetBytesPerRow(_ context: CGContext!) -> UInt

    Objective-C

    size_t CGBitmapContextGetBytesPerRow ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the color space of a bitmap context.

    Declaration

    Swift

    func CGBitmapContextGetColorSpace(_ context: CGContext!) -> CGColorSpace!

    Objective-C

    CGColorSpaceRef CGBitmapContextGetColorSpace ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func CGBitmapContextGetData(_ context: CGContext!) -> UnsafeMutablePointer<Void>

    Objective-C

    void * CGBitmapContextGetData ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the height in pixels of a bitmap context.

    Declaration

    Swift

    func CGBitmapContextGetHeight(_ context: CGContext!) -> UInt

    Objective-C

    size_t CGBitmapContextGetHeight ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Returns the width in pixels of a bitmap context.

    Declaration

    Swift

    func CGBitmapContextGetWidth(_ context: CGContext!) -> UInt

    Objective-C

    size_t CGBitmapContextGetWidth ( CGContextRef context );

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

Data Types

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

    Declaration

    Swift

    typealias CGBitmapContextReleaseDataCallback = CFunctionPointer<((UnsafeMutablePointer<Void>, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.6 and later.