CIContext Class Reference

Inherits from
Conforms to
Framework
Library/Frameworks/CoreImage.framework
Availability
Available in OS X v10.4 and later.
Declared in
CIContext.h
Companion guides
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

Managing Resources

Class Methods

contextWithCGContext:options:

Creates a Core Image context from a Quartz context, using the specified options.

+ (CIContext *)contextWithCGContext:(CGContextRef)ctx options:(NSDictionary *)dict
Parameters
ctx

A Quartz graphics context (CGContextRef object) either obtained from the system or created using a Quartz function such as CGBitmapContextCreate. See Quartz 2D Programming Guide for information on creating Quartz graphics contexts.

dict

A dictionary that contains color space information. You can pass any of the keys defined in “Context Options” along with the appropriate value.

Discussion

After calling this method, Core Image draws content to the specified Quartz graphics context.

When you create a CIContext object using a Quartz graphics context, any transformations that are already set on the Quartz graphics context affect drawing to that context.

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

contextWithCGLContext:pixelFormat:colorSpace:options:

Creates a Core Image context from a CGL context, using the specified options, color space, and pixel format object.

+ (CIContext *)contextWithCGLContext:(CGLContextObj)ctx pixelFormat:(CGLPixelFormatObj)pf colorSpace:(CGColorSpaceRef)space options:(NSDictionary *)dict
Parameters
ctx

A CGL context obtained by calling the CGL function CGLCreateContext.

pf

A CGL pixel format object either obtained from the system or created by calling a CGL function such as CGLChoosePixelFormat. This parameter must be the same pixel format object used to create the CGL context. The pixel format object must be valid for the lifetime of the Core Image context. Don’t release the pixel format object until after you release the Core Image context.

space

A color space object encapsulating color space information that is used to specify how color values are interpreted.

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.

Discussion

After calling this method, Core Image draws content into the surface (drawable object) attached to the CGL context. A CGL context is an OS X OpenGL context. For more information, see OpenGL Programming Guide for Mac.

When you create a CIContext object using a CGL context, all OpenGL states set for the CGL context affect rendering to that context. That means that coordinate and viewport transformations set on the CGL context, as well as the vertex color, affect drawing to that context.

For best results, follow these guidelines when you use Core Image to render into an OpenGL context:

  • Ensure that a single unit in the coordinate space of the OpenGL context represents a single pixel in the output device.

  • The Core Image coordinate space has the origin in the bottom-left corner of the screen. You should configure the OpenGL context in the same way.

  • The OpenGL context blending state is respected by Core Image. If the image you want to render contains translucent pixels, it’s best to enable blending using a blend function with the parameters GL_ONE, GL_ONE_MINUS_SRC_ALPHA, as shown in the following code example.

Some typical initialization code for a view with width W and height H is:

    glViewport (0, 0, W, H);
    glMatrixMode (GL_PROJECTION);
    glLoadIdentity ();
    glOrtho (0, W, 0, H, -1, 1);
    glMatrixMode (GL_MODELVIEW);
    glLoadIdentity ();
    glBlendFunc (GL_ONE, GL_ONE_MINUS_SRC_ALPHA);
    glEnable (GL_BLEND);
Availability
  • Available in OS X v10.6 and later.
Declared In
CIContext.h

Instance Methods

clearCaches

Frees any cached data, such as temporary images, associated with the context and runs the garbage collector.

- (void)clearCaches
Discussion

You can use this method to remove textures from the texture cache that reference deleted images.

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

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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.5 and later.
Declared In
CIContext.h

createCGLayerWithSize:info:

Creates a CGLayer object from the provided parameters.

- (CGLayerRef)createCGLayerWithSize:(CGSize)size info:(CFDictionaryRef)d
Parameters
size

The size, in default user space units, of the layer relative to the graphics context.

d

A dictionary, which is passed to CGLayerCreateWithContext as the auxiliaryInfo parameter. Pass NULL because this parameter is reserved for future use.

Return Value

A CGLayer object.

Discussion

After calling this method, Core Image draws content into the CGLayer object. Core Image creates a CGLayer object by calling the Quartz 2D function CGLayerCreateWithContext, whose prototype is:

CGLayerRef CGLayerCreateWithContext (
   CGContextRef context,
   CGSize size,
   CFDictionaryRef auxiliaryInfo
);

Core Image passes the CIContext object as the context parameter, the size as the size parameter, and the dictionary as the auxiliaryInfo parameter. For more information on CGLayer objects, see Quartz 2D Programming Guide and CGLayer Reference.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
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 OS X v10.4 and later.
Related Sample Code
Declared In
CIContext.h

reclaimResources

Runs the garbage collector to reclaim any resources that the context no longer requires.

- (void)reclaimResources
Discussion

The system calls this method automatically after every rendering operation. You can use this method to remove textures from the texture cache that reference deleted images.

Availability
  • Available in OS X v10.4 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 OS X v10.5 and later.
Declared In
CIContext.h

render:toIOSurface:bounds:colorSpace:

Renders a region of an image into an IOSurface object.

- (void)render:(CIImage *)image toIOSurface:(IOSurfaceRef)surface bounds:(CGRect)r colorSpace:(CGColorSpaceRef)cs
Parameters
image

A Core Image image object.

surface

The destination IOSurface object.

r

The rectangle in the destination IOSurface object to draw into.

cs

The color space of the destination IOSurface object.

Availability
  • Available in OS X v10.6 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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