iOS Developer Library

Developer

CoreImage Framework Reference CIContext Class Reference

Options
Deployment Target:

On This Page
Language:

CIContext

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. More...

Inheritance


Conforms To


Import Statement


import CoreImage @import CoreImage;

Availability


Available in iOS 5.0 and later.
  • Creates a Core Image context from an EAGL context.

    Declaration

    Swift

    init!(EAGLContext eaglContext: EAGLContext!) -> CIContext

    Objective-C

    + (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    init!(EAGLContext eaglContext: EAGLContext!, options options: [NSObject : AnyObject]!) -> CIContext

    Objective-C

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

    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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    init!(options dict: [NSObject : AnyObject]!) -> CIContext

    Objective-C

    + (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func createCGImage(_ im: CIImage!, fromRect r: CGRect) -> CGImage!

    Objective-C

    - (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func createCGImage(_ im: CIImage!, fromRect r: CGRect, format f: CIFormat, colorSpace cs: CGColorSpace!) -> CGImage!

    Objective-C

    - (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

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

    Deprecation Statement

    Instead use drawImage:inRect:fromRect:.

    Declaration

    Objective-C

    - (void)drawImage:(CIImage *)im atPoint:(CGPoint)p fromRect:(CGRect)src

    Parameters

    im

    A Core Image image object.

    p

    The point in the context destination to draw to.

    src

    The region of the image to draw.

    Discussion

    This method because it is ambiguous as to the units of the dimensions and won’t work as expected in a high-resolution environment which is why you should use drawImage:inRect:fromRect: instead.

    On iOS platforms, this method draws the image onto a render buffer for the OpenGL ES context. Use this method only if the CIContext object is created with contextWithEAGLContext:, and hence, you are rendering to a CAEAGLLayer.

    Import Statement

    Availability

    Available in iOS 5.0 and later.

    Deprecated in iOS 6.0.

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

    Declaration

    Swift

    func drawImage(_ im: CIImage!, inRect dest: CGRect, fromRect src: CGRect)

    Objective-C

    - (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

  • Renders to the given bitmap.

    Declaration

    Swift

    func render(_ im: CIImage!, toBitmap data: UnsafeMutablePointer<Void>, rowBytes rb: Int, bounds r: CGRect, format f: CIFormat, colorSpace cs: CGColorSpace!)

    Objective-C

    - (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

  • Renders an image into a pixel buffer.

    Declaration

    Swift

    func render(_ image: CIImage!, toCVPixelBuffer buffer: CVPixelBuffer!)

    Objective-C

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

    Parameters

    image

    A Core Image image object.

    buffer

    The destination pixel buffer.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

  • Renders a region of an image into a pixel buffer.

    Declaration

    Swift

    func render(_ image: CIImage!, toCVPixelBuffer buffer: CVPixelBuffer!, bounds r: CGRect, colorSpace cs: CGColorSpace!)

    Objective-C

    - (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func inputImageMaximumSize() -> CGSize

    Objective-C

    - (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func outputImageMaximumSize() -> CGSize

    Objective-C

    - (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.

    Import Statement

    import CoreImage

    Availability

    Available in iOS 5.0 and later.

  • Keys in the options dictionary for a CIContext object.

    Declaration

    Swift

    let kCIContextOutputColorSpace: NSString! let kCIContextWorkingColorSpace: NSString! let kCIContextUseSoftwareRenderer: NSString!

    Objective-C

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

    Constants

    • kCIContextOutputColorSpace

      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.)

      To request that Core Image perform no color management, specify the NSNull object as the value for this key. Use this option for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

      Available in iOS 5.0 and later.

    • kCIContextWorkingColorSpace

      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.)

      To request that Core Image perform no color management, specify the NSNull object as the value for this key. Use this option for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

      Available in iOS 5.0 and later.

    • kCIContextUseSoftwareRenderer

      kCIContextUseSoftwareRenderer

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

      Available in iOS 5.0 and later.

    Discussion

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

    Import Statement