Mac Developer Library

Developer

QuartzCore Framework Reference CIKernel Class Reference

Options
Deployment Target:

On This Page
Language:

CIKernel

An CIKernel object manages a GPU-based image processing routine used to create custom Core Image filters. In OS X, use the CIKernel class for any filter that includes custom GPU-based image processing. In iOS, to ensure the best performance, use the subclasses CIColorKernel and CIWarpKernel when implementing filters that operate only on color or geometry information, and use the CIKernel class directly only when implementing general-purpose filters that use both color and geometry information together.

The kernel language routine for a general-purpose filter kernel in iOS (or any filter kernel in OS X) has the following characteristics:

  • Its return type is vec4; that is, it returns a pixel color for the output image.

  • It may use zero or more input images. Each input image is represented by a parameter of type sampler.

A kernel routine typically produces its output by calculating source image coordinates (using the destCoord and samplerTransform functions or the samplerTransform function), samples from the source images (using the sample function), and computes a final pixel color (output using the return keyword). For example, the Core Image Kernel Language source below implements a filter that passes through its input image unchanged.

  • kernel vec4 do_nothing(sampler image) {
  • vec2 dc = destCoord();
  • return sample(image, samplerTransform(image, dc));
  • }

The Core Image Kernel Language is a dialect of the OpenGL Shading Language. See Core Image Kernel Language Reference and Core Image Programming Guide for more details.

Inheritance


Conforms To


Import Statement


Swift

import QuartzCore

Objective-C

@import QuartzCore;

Availability


Available in OS X v10.4 and later.
  • Creates a single kernel object.

    Declaration

    Swift

    init!(string string: String!) -> CIKernel

    Objective-C

    + (CIKernel *)kernelWithString:(NSString *)string

    Parameters

    string

    A program in the Core Image Kernel Language that contains a single routine marked using the kernel keyword.

    Return Value

    A new kernel object. In iOS, the class of the returned object can be CIKernel, CIColorKernel, or CIWarpKernel depending on the type of routine specified in the Core Image Kernel Language source code string.

    Discussion

    The Core Image Kernel Language is a dialect of the OpenGL Shading Language. See Core Image Kernel Language Reference and Core Image Programming Guide for more details.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.10 and later.

  • Creates and returns and array of CIKernel objects.

    Declaration

    Swift

    class func kernelsWithString(_ s: String!) -> [AnyObject]!

    Objective-C

    + (NSArray *)kernelsWithString:(NSString *)s

    Parameters

    s

    A program in the Core Image Kernel Language that contains one or more routines, each of which is marked using the kernel keyword.

    Return Value

    An array of CIKernel objects. The array contains one CIKernel objects for each kernel routine in the supplied string. In iOS, each object in the array can be of class CIKernel, CIColorKernel, or CIWarpKernel depending on the corresponding routine specified in the Core Image Kernel Language source code string.

    Discussion

    The Core Image Kernel Language is a dialect of the OpenGL Shading Language. See Core Image Kernel Language Reference and Core Image Programming Guide for more details.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    OS X v10.4 and later.

  • Returns the name of a kernel routine.

    Declaration

    Swift

    func name() -> String!

    Objective-C

    - (NSString *)name

    Return Value

    The name of the kernel routine.

    Discussion

    The name of a kernel routine is the identifier used to declare it in the Core Image Kernel Language source code. For example, if you use the kernelWithString: method to create a kernel from the source code below, the name of the returned CIKernel object is “moveUpTwoPixels”.

    • kernel vec4 moveUpTwoPixels (sampler image) {
    • vec2 dc = destCoord();
    • vec2 offset = vec2(0.0, 2.0);
    • return sample (image, samplerTransform (image, dc + offset));
    • }

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Sets the selector Core Image uses to query the region of interest for image processing with the kernel.

    Declaration

    Swift

    func setROISelector(_ aMethod: Selector)

    Objective-C

    - (void)setROISelector:(SEL)aMethod

    Parameters

    aMethod

    A selector name.

    Discussion

    When applying a filter kernel, the region of interest (ROI) is the area of source image pixels that must be processed to produce a given area of destination image pixels. For a more detailed definition, see The Region of Interest.

    The aMethod argument must use the signature that is defined for the regionOf:destRect:userInfo: method, which is as follows:

    - (CGRect) regionOf:(int)samplerIndex destRect:(CGRect)r userInfo:obj;

    where:

    • samplerIndex defines the sampler to query

    • destRect is the extent of the region, in working space coordinates, to render.

    • userInfo is the object associated with the kCIApplyOptionUserInfo option when the kernel is applied to its arguments (with the apply:arguments:options: method of a CIFilter object using the kernel). The userInfo is important because instance variables can’t be used by the defining class. Instance variables must be passed through the userInfo argument.

    The regionOf:destRect:userInfo: method of the CIFilter object is called by the framework. This method returns the rectangle that contains the region of the sampler that the kernel needs to render the specified destination rectangle.

    A sample regionOf:destRect:userInfo: method might look as follows:

    • - (CGRect)regionOf:(int)sampler destRect:(CGRect)r userInfo:params
    • {
    • float scale = fabs ([params X]);
    • return CGRectInset (r, scale * -1.3333, scale * -1.3333);
    • }

    If your kernel does not need the image at index to produce output in the rectangle rect, your method should return CGRectNull.

    In the filter code, you set the selector using the following:

    [kernel setROISelector:@selector(regionOf:destRect:userInfo:)]

    Alternatively, use the applyWithExtent:roiCallback:arguments: method to directly apply a kernel to create an output image, specifying the ROI callback as a block or closure.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.