Class

CIContext

An evaluation context for rendering image processing results and performing image analysis.

Declaration

@interface CIContext : NSObject

Overview

The CIContext class provides an evaluation context for Core Image processing with Quartz 2D, Metal, or OpenGL. You use CIContext objects in conjunction with other Core Image classes, such as CIFilter, CIImage, and CIColor, to process images using Core Image filters. You also use a Core Image context with the CIDetector class to analyze images—for example, to detect faces or barcodes.

CIContext and CIImage objects are immutable, so multiple threads can use the same CIContext object to render CIImage objects. However, CIFilter objects are mutable and thus cannot be shared safely among threads. Each thread must create its own CIFilter objects, but you can pass a filter’s immutable input and output CIImage objects between threads.

Topics

Creating a Context Without Specifying a Destination

+ context

Creates a context without a specific rendering destination, using default options.

- init

Initializes a context without a specific rendering destination, using default options.

+ initWithOptions:

Initializes a context without a specific rendering destination, using the specified options.

Creating a Context for CPU-Based Rendering

+ contextWithCGContext:options:

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

Creating a Context for GPU-Based Rendering with OpenGL

+ contextWithCGLContext:pixelFormat:colorSpace:options:

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

Deprecated
+ contextWithCGLContext:pixelFormat:options:

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

Deprecated
+ contextWithEAGLContext:

Creates a Core Image context from an EAGL context.

Deprecated
+ contextWithEAGLContext:options:

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

Deprecated
+ contextForOfflineGPUAtIndex:

Creates an OpenGL-based Core Image context using a GPU that is not currently driving a display.

Deprecated
+ contextForOfflineGPUAtIndex:colorSpace:options:sharedContext:

Creates an OpenGL-based Core Image context using a GPU that is not currently driving a display, with the specified options.

Deprecated

Creating a Context for GPU-Based Rendering with Metal

+ contextWithMTLDevice:

Creates a Core Image context using the specified Metal device.

+ contextWithMTLDevice:options:

Creates a Core Image context using the specified Metal device and options.

Rendering Images

- createCGImage:fromRect:

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

- createCGImage:fromRect:format:colorSpace:

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

- createCGImage:fromRect:format:colorSpace:deferred:

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

- createCGLayerWithSize:info:

Creates a CGLayer object from the provided parameters.

Deprecated
- render:toCVPixelBuffer:

Renders an image into a pixel buffer.

- render:toCVPixelBuffer:bounds:colorSpace:

Renders a region of an image into a pixel buffer.

- render:toIOSurface:bounds:colorSpace:

Renders a region of an image into an IOSurface object.

- render:toMTLTexture:commandBuffer:bounds:colorSpace:

Renders a region of an image to a Metal texture.

Drawing Images

- drawImage:atPoint:fromRect:

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

Deprecated
- drawImage:inRect:fromRect:

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

Determining the Allowed Extents for Images Used by a Context

- inputImageMaximumSize

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

- outputImageMaximumSize

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

Managing Resources

- clearCaches

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

- reclaimResources

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

+ offlineGPUCount

Returns the number of GPUs not currently driving a display.

workingColorSpace

The working color space of the Core Image context.

workingFormat

The working pixel format of the Core Image context.

Rendering Images for Data or File Export

- TIFFRepresentationOfImage:format:colorSpace:options:

Renders the image and exports the resulting image data in TIFF format.

- JPEGRepresentationOfImage:colorSpace:options:

Renders the image and exports the resulting image data in JPEG format.

- PNGRepresentationOfImage:format:colorSpace:options:

Renders the image and exports the resulting image data in PNG format.

- HEIFRepresentationOfImage:format:colorSpace:options:

Renders the image and exports the resulting image data in HEIF format.

- writeTIFFRepresentationOfImage:toURL:format:colorSpace:options:error:

Renders the image and exports the resulting image data as a file in TIFF format.

- writeJPEGRepresentationOfImage:toURL:colorSpace:options:error:

Renders the image and exports the resulting image data as a file in JPEG format.

- writePNGRepresentationOfImage:toURL:format:colorSpace:options:error:

Renders the image and exports the resulting image data as a file in PNG format.

- writeHEIFRepresentationOfImage:toURL:format:colorSpace:options:error:

Renders the image and exports the resulting image data as a file in HEIF format.

kCIImageRepresentationAVDepthData

options dictionary key for image export methods to represent data as AVDepthData.

kCIImageRepresentationDepthImage

options dictionary key for image export methods to output depth data.

kCIImageRepresentationDisparityImage

options dictionary key for image export methods to output disparity data.

Constants

Keys to be used in the options dictionary when creating a CIContext object.

kCIContextOutputColorSpace

A key for the color space to use for images before they are rendered to the context.

kCIContextWorkingColorSpace

A key for the color space to use for image operations.

kCIContextWorkingFormat

An option for the color format to use for intermediate results when rendering with the context.

kCIContextHighQualityDownsample

An option controlling the quality of image downsampling operations performed by the context.

kCIContextOutputPremultiplied

An option for whether output rendering by the context produces alpha-premultiplied pixels.

kCIContextCacheIntermediates

An option for whether the context caches the contents of any intermediate pixel buffers it uses during rendering.

kCIContextUseSoftwareRenderer

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

kCIContextPriorityRequestLow

A key for enabling low-priority GPU use.

Customizing Render Destination

- prepareRender:fromRect:toDestination:atPoint:error:

An optional call to warm up a CIContext so that subsequent calls to render with the same arguments run more efficiently.

- startTaskToClear:error:

Fills the entire destination with black or clear depending on its alphaMode.

- startTaskToRender:fromRect:toDestination:atPoint:error:

Renders a portion of an image to a point of destination.

- startTaskToRender:toDestination:error:

Renders an image to a destination so that point (0, 0) of the image maps to point (0, 0) of the destination.

Relationships

Inherits From

See Also

First Steps

Processing an Image Using Built-in Filters

Apply effects such as sepia tint, highlight strengthening, and scaling to images.

CIImage

A representation of an image to be processed or produced by Core Image filters.

CIFilter

An image processor that produces an image by manipulating one or more input images or by generating new image data.

Basic Data Types

Colors, vectors, and other types used in applying or creating image filters.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software