Class

CIContext

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

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

init()

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

init(options: [String : Any]? = nil)

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

Creating a Context for CPU-Based Rendering

init(cgContext: CGContext, options: [String : Any]? = nil)

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

Creating a Context for GPU-Based Rendering with OpenGL

init(cglContext: CGLContextObj, pixelFormat: CGLPixelFormatObj?, colorSpace: CGColorSpace?, options: [String : Any]? = nil)

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

init(eaglContext: EAGLContext)

Creates a Core Image context from an EAGL context.

init(eaglContext: EAGLContext, options: [String : Any]? = nil)

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

init?(forOfflineGPUAt: UInt32)

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

init?(forOfflineGPUAt: UInt32, colorSpace: CGColorSpace?, options: [String : Any]? = nil, sharedContext: CGLContextObj?)

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

Creating a Context for GPU-Based Rendering with Metal

init(mtlDevice: MTLDevice)

Creates a Core Image context using the specified Metal device.

init(mtlDevice: MTLDevice, options: [String : Any]? = nil)

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

Rendering Images

func createCGImage(CIImage, from: CGRect)

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

func createCGImage(CIImage, from: CGRect, format: CIFormat, colorSpace: CGColorSpace?)

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

func createCGImage(CIImage, from: CGRect, format: CIFormat, colorSpace: CGColorSpace?, deferred: Bool)

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

func createCGLayer(with: CGSize, info: CFDictionary?)

Creates a CGLayer object from the provided parameters.

Deprecated

func render(CIImage, toBitmap: UnsafeMutableRawPointer, rowBytes: Int, bounds: CGRect, format: CIFormat, colorSpace: CGColorSpace?)

Renders to the given bitmap.

func render(CIImage, to: CVPixelBuffer)

Renders an image into a pixel buffer.

func render(CIImage, to: CVPixelBuffer, bounds: CGRect, colorSpace: CGColorSpace?)

Renders a region of an image into a pixel buffer.

func render(CIImage, to: IOSurfaceRef, bounds: CGRect, colorSpace: CGColorSpace?)

Renders a region of an image into an IOSurface object.

func render(CIImage, to: MTLTexture, commandBuffer: MTLCommandBuffer?, bounds: CGRect, colorSpace: CGColorSpace)

Renders a region of an image to a Metal texture.

Drawing Images

func draw(CIImage, in: CGRect, from: CGRect)

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

Determining the Allowed Extents for Images Used by a Context

func inputImageMaximumSize()

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

func outputImageMaximumSize()

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

Managing Resources

func clearCaches()

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

func reclaimResources()

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

class func offlineGPUCount()

Returns the number of GPUs not currently driving a display.

var workingColorSpace: CGColorSpace?

The working color space of the Core Image context.

var workingFormat: CIFormat

The working pixel format of the Core Image context.

Rendering Images for Data or File Export

func tiffRepresentation(of: CIImage, format: CIFormat, colorSpace: CGColorSpace, options: [AnyHashable : Any] = [:])

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

func jpegRepresentation(of: CIImage, colorSpace: CGColorSpace, options: [AnyHashable : Any] = [:])

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

func pngRepresentation(of: CIImage, format: CIFormat, colorSpace: CGColorSpace, options: [AnyHashable : Any] = [:])

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

func heifRepresentation(of: CIImage, format: CIFormat, colorSpace: CGColorSpace, options: [AnyHashable : Any] = [:])

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

func writeTIFFRepresentation(of: CIImage, to: URL, format: CIFormat, colorSpace: CGColorSpace, options: [AnyHashable : Any] = [:])

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

func writeJPEGRepresentation(of: CIImage, to: URL, colorSpace: CGColorSpace, options: [AnyHashable : Any] = [:])

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

func writePNGRepresentation(of: CIImage, to: URL, format: CIFormat, colorSpace: CGColorSpace, options: [AnyHashable : Any] = [:])

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

func writeHEIFRepresentation(of: CIImage, to: URL, format: CIFormat, colorSpace: CGColorSpace, options: [AnyHashable : Any] = [:])

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

let kCIImageRepresentationAVDepthData: String

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

let kCIImageRepresentationDepthImage: String

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

let kCIImageRepresentationDisparityImage: String

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.

let kCIContextOutputColorSpace: String

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

let kCIContextWorkingColorSpace: String

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

let kCIContextWorkingFormat: String

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

let kCIContextHighQualityDownsample: String

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

let kCIContextOutputPremultiplied: String

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

let kCIContextCacheIntermediates: String

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

let kCIContextUseSoftwareRenderer: String

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

let kCIContextPriorityRequestLow: String

A key for enabling low-priority GPU use.

Customizing Render Destination

func prepareRender(CIImage, from: CGRect, to: CIRenderDestination, at: CGPoint)

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

func startTask(toClear: CIRenderDestination)

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

func startTask(toRender: CIImage, from: CGRect, to: CIRenderDestination, at: CGPoint)

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

func startTask(toRender: CIImage, to: CIRenderDestination)

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

NSObject