Mac Developer Library

Developer

Core Image Reference Collection 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. 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 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.

  1. kernel vec4 do_nothing(sampler image) {
  2. vec2 dc = destCoord();
  3. return sample(image, samplerTransform(image, dc));
  4. }

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.

  • Creates a single kernel object.

    Declaration

    Swift

    convenience init?(string string: String)

    Objective-C

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

    Availability

    Available in OS X v10.10 and later.

  • Creates and returns and array of CIKernel objects.

    Declaration

    Swift

    class func kernelsWithString(_ string: String) -> [CIKernel]?

    Objective-C

    + (NSArray<CIKernel *> *)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. 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.

    Availability

    OS X v10.4 and later.

  • name name Property

    The name of the kernel routine. (read-only)

    Declaration

    Swift

    var name: String { get }

    Objective-C

    @property(atomic, readonly) NSString *name

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

    1. kernel vec4 moveUpTwoPixels (sampler image) {
    2. vec2 dc = destCoord();
    3. vec2 offset = vec2(0.0, 2.0);
    4. return sample (image, samplerTransform (image, dc + offset));
    5. }

    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(_ method: 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:

    1. - (CGRect)regionOf:(int)sampler destRect:(CGRect)r userInfo:params
    2. {
    3. float scale = fabs ([params X]);
    4. return CGRectInset (r, scale * -1.3333, scale * -1.3333);
    5. }

    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.

    Availability

    Available in OS X v10.4 and later.

  • Creates a new image using the kernel and specified arguments.

    Declaration

    Swift

    func applyWithExtent(_ extent: CGRect, roiCallback callback: CIKernelROICallback, arguments args: [AnyObject]?) -> CIImage?

    Objective-C

    - (CIImage *)applyWithExtent:(CGRect)extent roiCallback:(CIKernelROICallback)callback arguments:(NSArray<id> *)args

    Parameters

    extent

    The extent of the output image.

    callback

    A block or closure that computes the region of interest for a given rectangle of destination image pixels. See CIKernelROICallback.

    args

    An array of arguments to pass to the kernel routine. The type of each object in the array must be compatible with the corresponding parameter declared in the kernel routine source code. For details, see Core Image Kernel Language Reference.

    Return Value

    A new image object describing the result of applying the kernel.

    Discussion

    This method is analogous to the CIFilter method apply:arguments:options:, but it does not require construction of a CIFilter object, and it allows you to specify a callback for determining the kernel’s region of interest as a block or closure. As with the similar CIFilter method, calling this method does not execute the kernel code—filters and their kernel code are evaluated only when rendering a final output image.

    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. Core Image calls your callback block or closure to determine the ROI when rendering the filter output. Core Image automatically splits large images into smaller tiles for rendering, so your callback may be called multiple times.

    Availability

    Available in OS X v10.11 and later.

Data Types

  • The signature for a block that computes the region of interest (ROI) for a given area of destination image pixels. Core Image calls this block when applying the kernel. You specify this block when using the applyWithExtent:roiCallback:arguments: method.

    Declaration

    Swift

    typealias CIKernelROICallback = (Int32, CGRect) -> CGRect

    Objective-C

    typedef CGRect (^CIKernelROICallback)(int index, CGRect rect);

    Discussion

    The block takes the following parameters:

    index

    For a general-purpose kernel or color kernel routine that supports multiple input images, the index of the source image for which Core Image is requesting ROI information. For all other kernel routines, this parameter is always zero.

    rect

    The rectangle in destination image pixels for which Core Image is requesting ROI information.

    The block returns a CGRect structure describing the region of interest for the specified rectangle.

    When applying a filter kernel, the region of interest 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.) For example, a kernel that applies a blur effect in a ten-pixel radius must sample source image pixels ten pixels away in each direction from every output pixel. Thus, its region of interest is a rectangle ten pixels larger on each side than the destination rectangle:

    1. CIKernelROICallback callback = ^(int index, CGRect rect) {
    2. return CGRectInset(rect, -10, -10);
    3. };

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

    Import Statement

    Objective-C

    @import CoreImage;

    Swift

    import CoreImage

    Availability

    Available in OS X v10.11 and later.