CIContext Class Reference

Inherits from
Conforms to
Framework
Library/Frameworks/CoreImage.framework
Availability
Available in iOS 5.0 and later.
Declared in
CIContext.h
Companion guides
Core Image Programming Guide
Image Unit Tutorial
Related sample code

Overview

The CIContext class provides an evaluation context for rendering a CIImage object through Quartz 2D or OpenGL. You use CIContext objects in conjunction with other Core Image classes, such as CIFilter, CIImage, and CIColor, to take advantage of the built-in Core Image filters when processing images.

CIContext and CIImage objects are immutable, which means each can be shared safely among threads. Multiple threads can use the same GPU or CPU CIContext object to render CIImage objects. However, this is not the case for CIFilter objects, which are mutable. A CIFilter object cannot be shared safely among threads. If you app is multithreaded, each thread must create its own CIFilter objects. Otherwise, your app could behave unexpectedly.

Tasks

Creating a Context

Rendering Images

Determining the Allowed Extents for Images Used by a Context

Class Methods

contextWithEAGLContext:

Creates a Core Image context from an EAGL context.

+ (CIContext *)contextWithEAGLContext:(EAGLContext *)eaglContext
Parameters
eaglContext

The EAGL context to render to.

Return Value

A Core Image context that targets OpenGL ES.

Discussion

The OpenGL ES context must support OpenGL ES 2.0. All drawing performed using the drawImage:atPoint:fromRect: method or the drawImage:inRect:fromRect: method is rendered directly into the context.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

contextWithEAGLContext:options:

Creates a Core Image context from an EAGL context using the specified options.

+ (CIContext *)contextWithEAGLContext:(EAGLContext *)eaglContext options:(NSDictionary *)dict
Parameters
eaglContext

The EAGL context to render to.

options

A dictionary that contains options for creating a CIContext object. You can pass any of the keys defined in “Context Options” along with the appropriate value.

Return Value

A Core Image context that targets OpenGL ES.

Discussion

The OpenGL ES context must support OpenGL ES 2.0. All drawing performed using the drawImage:atPoint:fromRect: method or the drawImage:inRect:fromRect: method is rendered directly into the context.

You should use this method if you want to get real-time performance on a device. One of the advantages of using an EAGL context is that the rendered image stays on the GPU and does not get copied to CPU memory.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

contextWithOptions:

Creates a CPU-based Core Image context using the specified options.

+ (CIContext *)contextWithOptions:(NSDictionary *)dict
Parameters
dict

A dictionary that contains options for the context. You can pass any of the keys defined in “Context Options” along with the appropriate value.

Return Value

A Core Image context.

Discussion

You can create a CPU-based context by providing the key kCIContextUseSoftwareRenderer. A CPU-based context supports larger input and output images than a GPU-based context. It also allows your app to perform processing in the background, such as when saving the rendered output to the Photo Library.

GPU rendering is faster than CPU rendering, but the resulting image is not displayed on the device until after is it copied to CPU memory and converted to another image type, such as a UIImage object.

Availability
  • Available in iOS 5.0 and later.
Related Sample Code
Declared In
CIContext.h

Instance Methods

createCGImage:fromRect:

Creates a Quartz 2D image from a region of a Core Image image object.

- (CGImageRef)createCGImage:(CIImage *)im fromRect:(CGRect)r
Parameters
im

A Core Image image object.

r

The region of the image to render.

Return Value

A Quartz 2D image. You are responsible for releasing the returned image when you no longer need it.

Discussion

Renders a region of an image into a temporary buffer using the context, then creates and returns a Quartz 2D image with the results.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

createCGImage:fromRect:format:colorSpace:

Creates a Quartz 2D image from a region of a Core Image image object.

- (CGImageRef)createCGImage:(CIImage *)im fromRect:(CGRect)r format:(CIFormat)f colorSpace:(CGColorSpaceRef)cs
Parameters
im

A Core Image image object.

r

The region of the image to render.

f

The format of the image.

cs

The color space of the image.

Return Value

A Quartz 2D image. You are responsible for releasing the returned image when you no longer need it.

Discussion

Renders a region of an image into a temporary buffer using the context, then creates and returns a Quartz 2D image with the results.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

drawImage:inRect:fromRect:

Renders a region of an image to a rectangle in the context destination.

- (void)drawImage:(CIImage *)im inRect:(CGRect)dest fromRect:(CGRect)src
Parameters
im

A CIImage object.

dest

The rectangle in the context destination to draw into. The image is scaled to fill the destination rectangle.

src

The subregion of the image that you want to draw into the context, with the origin and target size defined by the dest parameter. This rectangle is always in pixel dimensions.

Discussion

On iOS, this method draws the CIImage object into a renderbuffer for the OpenGL ES context. Use this method only if the CIContext object is created with contextWithEAGLContext: and if you are rendering to a CAEAGLayer.

On OS X, you need to be aware of whether the CIContext object is created with a CGContextRef or a CGLContext object. If you create the CIContext object with a CGContextRef, the dimensions of the destination rectangle are in points. If you create the CIContext object with a CGLContext object, the dimensions are in pixels.

On iOS 5, this method is synchronous. On iOS 6, this method is asynchronous. For apps linked on iOS 5, this method will continue to be synchronous.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

inputImageMaximumSize

Returns the maximum size allowed for any image rendered into the context.

- (CGSize)inputImageMaximumSize
Discussion

Some contexts limit the maximum size of an image that can be rendered into them. For example, the maximum size might reflect a limitation in the underlying graphics hardware.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

outputImageMaximumSize

Returns the maximum size allowed for any image created by the context.

- (CGSize)outputImageMaximumSize
Discussion

Some contexts limit the maximum size of an image that can be created by them. For example, the maximum size might reflect a limitation in the underlying graphics hardware.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

render:toBitmap:rowBytes:bounds:format:colorSpace:

Renders to the given bitmap.

- (void)render:(CIImage *)im toBitmap:(void *)data rowBytes:(ptrdiff_t)rb bounds:(CGRect)r format:(CIFormat)f colorSpace:(CGColorSpaceRef)cs
Parameters
im

A Core Image image object.

data

Storage for the bitmap data.

rb

The bytes per row.

r

The bounds of the bitmap data.

f

The format of the bitmap data.

cs

The color space for the data. Pass NULL if you want to use the output color space of the context.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

render:toCVPixelBuffer:

Renders an image into a pixel buffer.

- (void)render:(CIImage *)image toCVPixelBuffer:(CVPixelBufferRef)buffer
Parameters
image

A Core Image image object.

buffer

The destination pixel buffer.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

render:toCVPixelBuffer:bounds:colorSpace:

Renders a region of an image into a pixel buffer.

- (void)render:(CIImage *)image toCVPixelBuffer:(CVPixelBufferRef)buffer bounds:(CGRect)r colorSpace:(CGColorSpaceRef)cs
Parameters
image

A Core Image image object.

buffer

The destination pixel buffer.

r

The rectangle in the destination pixel buffer to draw into.

cs

The color space of the destination pixel buffer.

Availability
  • Available in iOS 5.0 and later.
Declared In
CIContext.h

Constants

Context Options

Keys in the options dictionary for a CIContext object.

extern NSString *kCIContextOutputColorSpace;
extern NSString *kCIContextWorkingColorSpace;
extern NSString *kCIContextUseSoftwareRenderer;
Constants
kCIContextOutputColorSpace

A key for the color space to use for images before they are rendered to the context. By default, Core Image uses the GenericRGB color space, which leaves color matching to the system. You can specify a different output color space by providing a Quartz 2D CGColorSpace object (CGColorSpaceRef). (See Quartz 2D Programming Guide for information on creating and using CGColorSpace objects.)

Available in iOS 5.0 and later.

Declared in CIContext.h.

kCIContextWorkingColorSpace

A key for the color space to use for image operations. By default, Core Image assumes that processing nodes are 128 bits-per-pixel, linear light, premultiplied RGBA floating-point values that use the GenericRGB color space. You can specify a different working color space by providing a Quartz 2D CGColorSpace object (CGColorSpaceRef). Note that the working color space must be RGB-based. If you have YUV data as input (or other data that is not RGB-based), you can use ColorSync functions to convert to the working color space. (See Quartz 2D Programming Guide for information on creating and using CGColorSpace objects.)

Available in iOS 5.0 and later.

Declared in CIContext.h.

kCIContextUseSoftwareRenderer

A key for enabling software renderer use. If the associated NSNumber object is YES, then the software renderer is required.

Available in iOS 5.0 and later.

Declared in CIContext.h.

Discussion

For a discussion of when to use options and color management, see Core Image Programming Guide.

Declared In
CIContext.h