# Core Image Kernel Language

The following sections list the symbols provided by the Core Image Kernel Language:

You can use these symbols together with any of the OpenGL Shading Language routines that Core Image supports. See Unsupported Items for those you can’t use.

## Functions

This section describes the following functions:

### compare

`genType compare (genType x, genType y, genType z)`

For each component, returns

`x < 0 ? y : z`

. Note that`genType`

is a placeholder for an arbitrary vector type.

### cos_

`genType cos_ (genType x)`

Similar to

`cos (x)`

except that`x`

must be in the [`–pi`

,`pi`

] range. Note that`genType`

is a placeholder for an arbitrary vector type.

### cossin

`vec2 cossin (float x)`

Returns

`vec2 (cos (x), sin (x))`

.

### cossin_

`vec2 cossin_ (float x)`

Returns

`vec2 (cos (x), sin (x))`

. This function expects`x`

to be in the [`–pi`

,`pi`

] range.

### destCoord

`varying vec2 destCoord ()`

Returns the position, in working space coordinates, of the pixel currently being computed. The destination space refers to the coordinate space of the image you are rendering.

### premultiply

`vec4 premultiply (vec4 color)`

Multiplies the red, green, and blue components of the

`color`

parameter by its alpha component.

### sample

`vec4 sample (uniform sampler src, vec2 point)`

Returns the pixel value produced from sampler

`src`

at the position`point`

, where`point`

is specified in sampler space.

### samplerCoord

`varying vec2 samplerCoord (uniform sampler src)`

Returns the position, in sampler space, of the sampler

`src`

that is associated with the current output pixel (that is, after any transformation matrix associated with`src`

is applied). The sample space refers to the coordinate space of that you are texturing from.Note that if your source data is tiled, the sample coordinate will have an offset (dx/dy). You can convert a destination location to the sampler location using the

`samplerTransform`

function.

### samplerExtent

`uniform vec4 samplerExtent (uniform sampler src)`

Returns the extent of the sampler in world coordinates, as a four-element vector [x, y, width, height].

### samplerOrigin

`uniform vec2 samplerOrigin (uniform sampler src)`

Equivalent to

`samplerExtent (src).xy`

.

### samplerSize

`uniform vec2 samplerSize (uniform sampler src)`

Equivalent to

`samplerExtent (src).zw`

.

### samplerTransform

`vec2 samplerTransform (uniform sampler src, vec2 point)`

Returns the position in the coordinate space of the source (the first argument) that is associated with the position defined in working-space coordinates (the second argument). (Keep in mind that the working space coordinates reflect any transformations that you applied to the working space.)

For example, if you are modifying a pixel in the working space, and you need to retrieve the pixels that surround this pixel in the original image, you would make calls similar to the following, where

`d`

is the location of the pixel you are modifying in the working space, and`image`

is the image source for the pixels.samplerTransform(image, d + vec2(-1.0,-1.0));

samplerTransform(image, d + vec2(+1.0,-1.0));

samplerTransform(image, d + vec2(-1.0,+1.0));

samplerTransform(image, d + vec2(+1.0,+1.0));

### sin_

`genType sin_ (genType x)`

Similar to

`sin (x)`

except that`x`

must be in the [`–pi`

,`pi`

] range. Note that`genType`

is a placeholder for an arbitrary vector type.

### sincos

`vec2 sincos (float x)`

Returns

`vec2 (sin (x), cos (x))`

.

### sincos_

`vec2 sincos_ (float x)`

Returns

`vec2 (sin (x), cos (x))`

. This function expects`x`

to be in the [`–pi`

,`pi`

] range.

### tan_

`genType tan_ (genType x)`

Similar to

`tan (x)`

except that`x`

must be in the [`–pi`

,`pi`

] range. Note that`genType`

is a placeholder for an arbitrary vector type.

### unpremultiply

`vec4 unpremultiply (vec4 color)`

If the alpha component of the

`color`

parameter is greater than 0, divides the red, green and blue components by alpha. If alpha is 0, this function returns`color`

.

## Data Types

`sampler`

Specifies a sampler passed in from CISampler that is used to get samples from data.

`__color`

Specifies a type for kernel parameters that need to be color matched to the current CIContext working color space.

`__table`

Specifies a flag for a sampler that fetches values from a lookup table.

The

`__table`

flag must precede the`sampler`

type. The flag ensures that Core Image does not sample the table values using world coordinates.For example, to use a lookup table sampler in a kernel named

`shadedmaterial`

, the kernel declaration would be:`kernel vec4 shadedmaterial(sampler heightfield, __table sampler envmap, float surfaceScale, vec2 envscaling)`

Using the

`__table`

flag prevents the`envmap`

sampler values from being transformed, even if the shaded material kernel gets inserted into a filter chain with an affine transform. If you don’t tag the sampler this way and you chain the shaded material filter to an affine transform for rotation, then looking up values in the environment map results in getting rotated values, which is not correct because the lookup table is simply a data collection.

## Keywords

`kernel`

Specifies a kernel routine. Kernel routines are extracted and compiled by the CIKernel class. A kernel encapsulates the computation required to compute a single pixel in the output image.

Each kernel is tagged by the

`kernel`

keyword in its return type. The underlying return type of the kernel must be`vec4`

. Core Image requires this type in order to return the output pixel for the input pixel currently being evaluated.All parameters to the kernel are implicitly marked

`uniform`

. Parameters marked`out`

and`inout`

are not allowed.You can pass the following types to a kernel routine:

`sampler`

: Requires a CISampler object when applied.`__table`

: A qualifier for a`sampler`

type.`float`

,`vec2`

,`vec3`

,`vec4`

: Requires an NSNumber or CIVector.`__color`

: A color that will be matched to the CIContext working color space when passed into the program. It requires a CIColor object when applied. To the kernel program it appears to be a`vec4`

type in premultiplied RGBA format.

## Unsupported Items

Core Image does not support the OpenGL Shading Language source code preprocessor. In addition, the following are not implemented:

Data types:

`mat2`

,`mat3`

,`mat4`

,`struct`

,`arrays`

Statements:

`continue`

,`break`

,`discard`

. Other flow control statements (`if`

,`for`

,`while`

,`do while`

) are supported only when the loop condition can be inferred at the time the code compiles.Expression operators:

`% << >> | & ^ || && ^^ ~`

Built-in functions:

`ftransform`

,`matrixCompMult`

,`dfdx`

,`dfdy`

,`fwidth`

,`noise1`

,`noise2`

,`noise3`

,`noise4`

,`refract`

Copyright © 2015 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2015-01-12