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 thatgenType
is a placeholder for an arbitrary vector type.
cos_
genType cos_ (genType x)
Similar to
cos (x)
except thatx
must be in the [–pi
,pi
] range. Note thatgenType
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 expectsx
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 positionpoint
, wherepoint
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 withsrc
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, andimage
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 thatx
must be in the [–pi
,pi
] range. Note thatgenType
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 expectsx
to be in the [–pi
,pi
] range.
tan_
genType tan_ (genType x)
Similar to
tan (x)
except thatx
must be in the [–pi
,pi
] range. Note thatgenType
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 returnscolor
.
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 thesampler
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 theenvmap
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 bevec4
. 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 markedout
andinout
are not allowed.You can pass the following types to a kernel routine:
sampler
: Requires a CISampler object when applied.__table
: A qualifier for asampler
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 avec4
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