vImage Transform Reference
Transformation functions alter the values of pixels in the image. Unlike convolutions, transformation functions do not depend on the values of nearby pixels. The vImage transformation functions fall into four broad categories:
Gamma correction functions correct the brightness profile of an image by multiplying each pixel by the value of the function. Gamma correction prepares an image for display or printing on a particular device.
Lookup table functions are like the piecewise polynomial functions, but instead of applying a polynomial they use a lookup table that you supply.
Matrix multiplication functions have a variety of uses, such as to convert between color spaces (RGB and YUV, for example), change a color image to a grayscale one, and for “color twisting.”
Piecewise functions are similar to the gamma correction functions, but instead of applying a predefined gamma function they apply one or more polynomials that you supply. The number of polynomials must be an integer power of 2, and they must all be of the same order.
Transformation functions use a vImage buffer structure (vImage_Buffer
—see vImage Data Types and Constants Reference) to receive and supply image data. This buffer contains a pointer to image data, the height and width (in pixels) of the image data, and the number of row bytes. You actually pass a pointer to a vImage buffer structure.
Some transformation functions “work in place”. That is, the source and destination images can occupy the same memory if the they are strictly aligned pixel for pixel. For these, you can can provide a pointer to the same vImage buffer structure for one of the source images and the destination image.

Uses a lookup table to transform an image in Planar8 format to an image in PlanarF format.
Declaration
Swift
func vImageLookupTable_Planar8toPlanarF(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _table
: UnsafePointer<Pixel_F>, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageLookupTable_Planar8toPlanarF ( const vImage_Buffer *src, const vImage_Buffer *dest, const Pixel_F table[256], vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.table
A lookup table that contains 256 values.
flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
For each pixel, the 8bit value from the source Planar8 image is used as an index to get a floatingpoint value from the table. This value is used as the corresponding pixel in the PlanarF result image.
Availability
Available in OS X v10.4 and later.

Uses a lookup table to transform an image in PlanarF format to an image in Planar8 format.
Declaration
Swift
func vImageLookupTable_PlanarFtoPlanar8(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _table
: UnsafePointer<Pixel_8>, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageLookupTable_PlanarFtoPlanar8 ( const vImage_Buffer *src, const vImage_Buffer *dest, const Pixel_8 table[4096], vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.table
A lookup table that contains 4096 values.
flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
The table contains 4096 values; it is entered with an integer index derived from a pixel value in the source image, to look up an 8bit value for the destination image.
For each pixel, the floatingpoint value from the source PlanarF image is first clipped to the range 0.0 ... 1.0, and then converted to an integer in the range 0 ... 4095. The conversion calculation is equivalent to
if (realValue < 0.0f) realValue = 0.0f;
if (realValue > 1.0f) realValue = 1.0f;
intValue = (int)(realValue * 4095.0f + 0.5f);
This integer is used as an index to get an 8bit value from the table. This value is used as the corresponding pixel in the Planar8 result image.
Availability
Available in OS X v10.4 and later.

Uses a lookup table to transform an image in PlanarF format to an image in PlanarF format.
Declaration
Swift
func vImageInterpolatedLookupTable_PlanarF(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _table
: UnsafePointer<Pixel_F>, _tableEntries
: vImagePixelCount, _maxFloat
: Float, _minFloat
: Float, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageInterpolatedLookupTable_PlanarF ( const vImage_Buffer *src, const vImage_Buffer *dest, const Pixel_F *table, vImagePixelCount tableEntries, float maxFloat, float minFloat, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.table
A lookup table of floatingpoint values.
tableEntries
A value of type
vImagePixelCount
, giving the number of values in the array.maxFloat
A value of type
float
.minFloat
A value of type
float
.flags
The options to use when performing the transformation. Pass
kvImageDoNotTile
if you plan to perform your own tiling or use multithreading.Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
It will work in place. The table contains an arbitrary number of values; it is entered with an index interpolated from a value from the source image, to look up a floatingpoint value for the destination image.
The input pixel is first clipped to the range
minFloat
...maxFloat
. The result is then calculated asfloat clippedPixel =MAX(MIN(src_pixel, maxFloat), minFloat);
float fIndex = (float) (tableEntries  1) * (clippedPixel  minFloat)
/ (maxFloat  minFloat);
float fract = fIndex  floor(fIndex);
unsigned long i = fIndex;
float result = table[i] * (1.0f  fract) + table[i + 1] * fract;
Availability
Available in OS X v10.4 and later.

Applies a set of piecewise polynomials to an image in PlanarF format.
Declaration
Swift
func vImagePiecewisePolynomial_PlanarF(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _coefficients
: UnsafeMutablePointer<UnsafePointer<Float>>, _boundaries
: UnsafePointer<Float>, _order
: UInt32, _log2segments
: UInt32, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImagePiecewisePolynomial_PlanarF ( const vImage_Buffer *src, const vImage_Buffer *dest, const float **coefficients, const float *boundaries, uint32_t order, uint32_t log2segments, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.coefficients
A pointer to an array of polynomial coefficient arrays. Each polynomial coefficient array contains the coefficients for one polynomial. Note that a polynomial of order R has R+1 coefficients. All the polynomial coefficient arrays must be the same size, R+1, and in each array the coefficients must be ordered from the 0thorder term to the highestorder term.
boundaries
A pointer to an array of boundary values, in increasing order, for separating adjacent ranges of pixel values. The first boundary value is the lowest in the range; input values lower than this are clipped to this value. The last boundary value is the highest in the range; input values higher than this are clipped to this value. The boundary values between the first and last separate the subranges from each other.
log2segments
The number of polynomials represented as a base2 logarithm. If you pass a noninteger poweroftwo number of polynomials (for example, 5), you must round up to the next integer power of 2 (for the example of 5, that would be 8), and simply repeat the last polynomial the appropriate number of times.
flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
You can approximate many different correction functions by carefully choosing the polynomials and the ranges of input values they operate on. The number of polynomials must be a nonnegative integer power of 2.
Suppose that you want to use N polynomials of order R to process N contiguous ranges of pixel values. For each pixel in the image, the range of usable values is divided into segments by the values passed in the
boundaries
array. Each segment is processed by the corresponding polynomial. Since there are N polynomials, then there must be N segments, so you must supply N+1 boundaries.You must order the boundaries by increasing value. The ith segment is the set of pixel values that fall in the range:
boundary[i] <= value < boundary{i+1}
where i ranges from 0 to N. Values in this segment are processed by the ith polynomial.
From a performance standpoint, it costs much more to resolve additional polynomials than to work with higherorder polynomials. You typically achieve better performance with one 9thorder polynomial that covers the whole range of values you are interested in than with many lowerorder polynomials covering the range piecewise.
This function uses singleprecision floatingpoint arithmetic. As a result, polynomials with large highorder coefficients may cause significant rounding error.
Availability
Available in OS X v10.4 and later.

vImagePiecewisePolynomial_Planar8toPlanarF(_:_:_:_:_:_:_:) vImagePiecewisePolynomial_Planar8toPlanarF
Applies a set of piecewise polynomials to transform an image in Planar8 format to an image in PlanarF format.
Declaration
Swift
func vImagePiecewisePolynomial_Planar8toPlanarF(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _coefficients
: UnsafeMutablePointer<UnsafePointer<Float>>, _boundaries
: UnsafePointer<Float>, _order
: UInt32, _log2segments
: UInt32, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImagePiecewisePolynomial_Planar8toPlanarF ( const vImage_Buffer *src, const vImage_Buffer *dest, const float **coefficients, const float *boundaries, uint32_t order, uint32_t log2segments, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.coefficients
A pointer to an array of polynomial coefficient arrays. Each polynomial coefficient array contains the coefficients for one polynomial. Note that a polynomial of order R has R+1 coefficients. All the polynomial coefficient arrays must be the same size, R+1, and in each array the coefficients must be ordered from the 0thorder term to the highestorder term.
boundaries
A pointer to an array of boundary values, in increasing order, for separating adjacent ranges of pixel values. The first boundary value is the lowest in the range; input values lower than this are clipped to this value. The last boundary value is the highest in the range; input values higher than this are clipped to this value. The boundary values between the first and last separate the subranges from each other.
log2segments
The number of polynomials represented as a base2 logarithm. If you pass a noninteger poweroftwo number of polynomials (for example, 5), you must round up to the next integer power of 2 (for the example of 5, that would be 8), and simply repeat the last polynomial the appropriate number of times.
flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
You can approximate many different correction functions by carefully choosing the polynomials and the ranges of input values they operate on. The number of polynomials must be a nonnegative integer power of 2.
Suppose that you want to use N polynomials of order R to process N contiguous ranges of pixel values. For each pixel in the image, the range of usable values is divided into segments by the values passed in the
boundaries
array. Each segment is processed by the corresponding polynomial. Since there are N polynomials, then there must be N segments, so you must supply N+1 boundaries.You must order the boundaries by increasing value. The ith segment is the set of pixel values that fall in the range:
boundary[i] <= value < boundary{i+1}
where i ranges from 0 to N. Values in this segment are processed by the ith polynomial.
From a performance standpoint, it costs much more to resolve additional polynomials than to work with higherorder polynomials. You typically achieve better performance with one 9thorder polynomial that covers the whole range of values you are interested in than with many lowerorder polynomials covering the range piecewise.
This function uses singleprecision floatingpoint arithmetic. As a result, polynomials with large highorder coefficients may cause significant rounding error.
Availability
Available in OS X v10.4 and later.
See Also

vImagePiecewisePolynomial_PlanarFtoPlanar8(_:_:_:_:_:_:_:) vImagePiecewisePolynomial_PlanarFtoPlanar8
Applies a set of piecewise polynomials to transform an image in PlanarF format to an image in Planar8 format.
Declaration
Swift
func vImagePiecewisePolynomial_PlanarFtoPlanar8(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _coefficients
: UnsafeMutablePointer<UnsafePointer<Float>>, _boundaries
: UnsafePointer<Float>, _order
: UInt32, _log2segments
: UInt32, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImagePiecewisePolynomial_PlanarFtoPlanar8 ( const vImage_Buffer *src, const vImage_Buffer *dest, const float **coefficients, const float *boundaries, uint32_t order, uint32_t log2segments, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.coefficients
A pointer to an array of polynomial coefficient arrays. Each polynomial coefficient array contains the coefficients for one polynomial. Note that a polynomial of order R has R+1 coefficients. All the polynomial coefficient arrays must be the same size, R+1, and in each array the coefficients must be ordered from the 0thorder term to the highestorder term.
boundaries
A pointer to an array of boundary values, in increasing order, for separating adjacent ranges of pixel values. The first boundary value is the lowest in the range; input values lower than this are clipped to this value. The last boundary value is the highest in the range; input values higher than this are clipped to this value. The boundary values between the first and last separate the subranges from each other.
log2segments
The number of polynomials represented as a base2 logarithm. If you pass a noninteger poweroftwo number of polynomials (for example, 5), you must round up to the next integer power of 2 (for the example of 5, that would be 8), and simply repeat the last polynomial the appropriate number of times.
flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
You can approximate many different correction functions by carefully choosing the polynomials and the ranges of input values they operate on. The number of polynomials must be a nonnegative integer power of 2.
Suppose that you want to use N polynomials of order R to process N contiguous ranges of pixel values. For each pixel in the image, the range of usable values is divided into segments by the values passed in the
boundaries
array. Each segment is processed by the corresponding polynomial. Since there are N polynomials, then there must be N segments, so you must supply N+1 boundaries.You must order the boundaries by increasing value. The ith segment is the set of pixel values that fall in the range:
boundary[i] <= value < boundary{i+1}
where i ranges from 0 to N. Values in this segment are processed by the ith polynomial.
From a performance standpoint, it costs much more to resolve additional polynomials than to work with higherorder polynomials. You typically achieve better performance with one 9thorder polynomial that covers the whole range of values you are interested in than with many lowerorder polynomials covering the range piecewise.
This function uses singleprecision floatingpoint arithmetic. As a result, polynomials with large highorder coefficients may cause significant rounding error.
Availability
Available in OS X v10.4 and later.
See Also

Applies a piecewise rational expression to an image in PlanarF format.
Declaration
Swift
func vImagePiecewiseRational_PlanarF(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _topCoefficients
: UnsafeMutablePointer<UnsafePointer<Float>>, _bottomCoefficients
: UnsafeMutablePointer<UnsafePointer<Float>>, _boundaries
: UnsafePointer<Float>, _topOrder
: UInt32, _bottomOrder
: UInt32, _log2segments
: UInt32, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImagePiecewiseRational_PlanarF ( const vImage_Buffer *src, const vImage_Buffer *dest, const float **topCoefficients, const float **bottomCoefficients, const float *boundaries, uint32_t topOrder, uint32_t bottomOrder, uint32_t log2segments, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.topCoefficients
An array of pointers to polynomial coefficient arrays The array of pointers has length 2^{log2segments}. Each array pointed to has length
topOrder
+1.Each polynomial coefficient array contains the coefficients for one polynomial. Note that a polynomial of order R has R+1 coefficients. All the polynomial coefficient arrays must be the same size, R+1, and in each array the coefficients must be ordered from the 0thorder term to the highestorder term.
bottomCoefficients
An array of pointers to polynomial coefficient arrays The array of pointers has length 2^{log2segments}. Each array pointed to has length
bottomOrder
+1.Each polynomial coefficient array contains the coefficients for one polynomial. Note that a polynomial of order R has R+1 coefficients. All the polynomial coefficient arrays must be the same size, R+1, and in each array the coefficients must be ordered from the 0thorder term to the highestorder term. These do not need to be the same order as the top polynomials.
boundaries
An array of floatingpoint values with size (2^{log2segments})+1, in increasing order, for separating adjacent ranges of pixel values. The first boundary value is the lowest in the range; input values lower than this are clipped to this value. The last boundary value is the highest in the range; input values higher than this are clipped to this value. The boundary values between the first and last separate the subranges from each other. The boundaries must be the same for both the top and bottom polynomials.
topOrder
The order of the top polynomial. Make sure you pass the order (that is, the highest power of x), not the number of coefiicients.
bottomOrder
The order of the bottom polynomial. Make sure you pass the order (that is, the highest power of x), not the number of coefiicients.
log2segments
The number of rationals represented as a base2 logarithm. If you pass a noninteger poweroftwo number of rational (for example, 5), you must round up to the next integer power of 2 (for the example of 5, that would be 8), and simply repeat the last rational the appropriate number of times.
flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
This function is similar to
vImagePiecewisePolynomial_PlanarF
except that it evaluates a piecewise rational expression in the form of:Each polynomial has its own set of coefficients and its own polynomial order. The two polynomials share the same set of segment boundaries. If the polynomials are split then all the top polynomials must be of the same order, and all the bottom polynomials must be of the same order. However, regardless of whether the polynomial is split or not, the top polynomials do not need to be the same order as the bottom polynomials.
This function does not deliver IEEE754 correct division. The divide does not round per the IEEE754 current rounding mode. It incurs up to 2 ULPs (Units in the Last Place) of error. Edge cases involving denormals, infinities, NaNs and division by zero return undefined results. (They will not crash, but NaN is a likely result in such cases.) Denormals can be rescued on AltiVec enabled machines by turning off the NonJava bit in the VSCR, at the expense of taking a manythousand cycle kernel exception every time a denormal number is encountered. Since you can predict ahead of time whether a given set of bounded polynomials is going to encounter these conditions, this problem should be avoidable by wise choice of polynomials. Developers who require IEEE754 correct results should call the polynomial evaluator above twice and do the division themselves.
The approximate cost of evaluating a rational (in the same units as polynomial above) is:
time = (base cost to touch all the data) + top polynomial order
+ bottom polynomial order + 4 + 4 * log2segments
With data not in cache, the time may be significantly different. For sufficiently small polynomials, the cost may be a fixed cost, dependent only on how much data is touched, and not on polynomial order.
This performance behavior is provided to help you evaluate speed tradeoffs. It is not a guaranteed. It is subject to change in future operating system revisions, and may be different on different hardware within the same or different operating system revisions.
Availability
Available in OS X v10.4 and later.

Operates on a set of 8bit source image planes, multiplying each pixel by the provided matrix to produce a set of 8bit destination image planes.
Declaration
Swift
func vImageMatrixMultiply_Planar8(_
srcs
: UnsafeMutablePointer<UnsafePointer<vImage_Buffer>>, _dests
: UnsafeMutablePointer<UnsafePointer<vImage_Buffer>>, _src_planes
: UInt32, _dest_planes
: UInt32, _matrix
: UnsafePointer<Int16>, _divisor
: Int32, _pre_bias
: UnsafePointer<Int16>, _post_bias
: UnsafePointer<Int32>, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageMatrixMultiply_Planar8 ( const vImage_Buffer *srcs[], const vImage_Buffer *dests[], uint32_t src_planes, uint32_t dest_planes, const int16_t matrix[], int32_t divisor, const int16_t *pre_bias, const int32_t *post_bias, vImage_Flags flags );
Parameters
srcs
A pointer to an array of vImage buffer structures, one buffer for each source plane.
dests
A pointer to an array of pointers to vImage buffer data structures, one buffer structure for each destination plane. You are responsible for filling out the
height
,width
, androwBytes
fields of these structures, and for allocating data buffers of the appropriate size. On return, the data buffers in these structures contains the destination image data for each plane. When you no longer need the data buffers, you must deallocate the memory.src_planes
The number of source planes.
dest_planes
The number of destination planes.
matrix
A 1dimensional array whose values represent a matrix with dimensions
dest_planes
x
src_planes
. vImage multiplies each source pixel by this matrix to produce a destination pixel.divisor
A divisor for normalization after performing the matrix multiplication.
pre_bias
A packed array of bias values, one for each source plane. vImage adds the appropriate bias value to each source value prior to matrix multiplication. Pass
NULL
if you do not want to apply a preprocessing bias value.post_bias
A packed array of bias values, one for each destination plane. vImage adds the appropriate bias value to each destination value after matrix multiplication. Pass
NULL
if you do not want to apply a preprocessing bias value.flags
The options to use when performing the transformation. Pass
kvImageDoNotTile
if you plan to perform your own tiling or use multithreading.Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
Be aware that 32bit signed accumulators are used. If the sum over any matrix column is greater than ±223, overflow may occur. Generally speaking this will not happen because the matrix elements are 16bit integers, so it would take more than 256 source planes before trouble could arise.
Availability
Available in OS X v10.4 and later.

Operates upon a set of floatingpoint source image planes, multiplying each pixel by the provided matrix to produce a set of floatingpoint destination image planes.
Declaration
Swift
func vImageMatrixMultiply_PlanarF(_
srcs
: UnsafeMutablePointer<UnsafePointer<vImage_Buffer>>, _dests
: UnsafeMutablePointer<UnsafePointer<vImage_Buffer>>, _src_planes
: UInt32, _dest_planes
: UInt32, _matrix
: UnsafePointer<Float>, _pre_bias
: UnsafePointer<Float>, _post_bias
: UnsafePointer<Float>, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageMatrixMultiply_PlanarF ( const vImage_Buffer *srcs[], const vImage_Buffer *dests[], uint32_t src_planes, uint32_t dest_planes, const float matrix[], const float *pre_bias, const float *post_bias, vImage_Flags flags );
Parameters
srcs
A pointer to an array of vImage buffer structures, one buffer for each source plane.
dests
A pointer to an array of pointers to vImage buffer data structures, one buffer structure for each destination plane. You are responsible for filling out the
height
,width
, androwBytes
fields of these structures, and for allocating data buffers of the appropriate size. On return, the data buffers in these structures contains the destination image data for each plane. When you no longer need the data buffers, you must deallocate the memory.src_planes
The number of source planes.
dest_planes
The number of destination planes.
matrix
A 1dimensional array whose values represent a matrix with dimensions
dest_planes
x
src_planes
. vImage multiplies each source pixel by this matrix to produce a destination pixel.pre_bias
A packed array of bias values, one for each source plane. vImage adds the appropriate bias value to each source value prior to matrix multiplication. Pass
NULL
if you do not want to apply a preprocessing bias value.post_bias
A packed array of bias values, one for each destination plane. vImage adds the appropriate bias value to each destination value after matrix multiplication. Pass
NULL
if you do not want to apply a preprocessing bias value.flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
The operation is the same as
vImageMatrixMultiply_Planar8
except that floatingpoint values are used and there is no divisor.Availability
Available in OS X v10.4 and later.

Operates upon an interleaved 8bit source image, multiplying each pixel by the provided matrix to produce an interleaved 8bit destination image.
Declaration
Swift
func vImageMatrixMultiply_ARGB8888(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _matrix
: UnsafePointer<Int16>, _divisor
: Int32, _pre_bias
: UnsafePointer<Int16>, _post_bias
: UnsafePointer<Int32>, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageMatrixMultiply_ARGB8888 ( const vImage_Buffer *src, const vImage_Buffer *dest, const int16_t matrix[16], int32_t divisor, const int16_t *pre_bias, const int32_t *post_bias, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.matrix
A 1dimensional array whose values represent a 4
x
4 matrix. vImage multiplies each source pixel by this matrix to produce a destination pixel.divisor
A divisor for normalization after performing the matrix multiplication.
pre_bias
A packed array of bias values, one for each source plane. vImage adds the appropriate bias value to each source value prior to matrix multiplication. Pass
NULL
if you do not want to apply a preprocessing bias value.post_bias
A packed array of bias values, one for each destination plane. vImage adds the appropriate bias value to each destination value after matrix multiplication. Pass
NULL
if you do not want to apply a preprocessing bias value.flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
Be aware that 32bit signed accumulators are used. If the sum over any matrix column is greater than ±223, overflow may occur. Generally speaking this will not happen because the matrix elements are 16bit integers, so it would take more than 256 source planes before trouble could arise.
Availability
Available in OS X v10.4 and later.

Operates upon an interleaved floatingpoint source image, multiplying each pixel by the provided matrix to produce an interleaved floatingpoint destination image.
Declaration
Swift
func vImageMatrixMultiply_ARGBFFFF(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _matrix
: UnsafePointer<Float>, _pre_bias
: UnsafePointer<Float>, _post_bias
: UnsafePointer<Float>, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageMatrixMultiply_ARGBFFFF ( const vImage_Buffer *src, const vImage_Buffer *dest, const float matrix[16], const float *pre_bias, const float *post_bias, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.matrix
A 1dimensional array whose values represent a 4
x
4 matrix. vImage multiplies each source pixel by this matrix to produce a destination pixel.pre_bias
A packed array of bias values, one for each source plane. vImage adds the appropriate bias value to each source value prior to matrix multiplication. Pass
NULL
if you do not want to apply a preprocessing bias value.post_bias
A packed array of bias values, one for each destination plane. vImage adds the appropriate bias value to each destination value after matrix multiplication. Pass
NULL
if you do not want to apply a preprocessing bias value.flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Discussion
The operation is the same as
vImageMatrixMultiply_ARGB8888
except that floatingpoint values are used and there is no divisor.Be aware that 32bit signed accumulators are used. If the sum over any matrix column is greater than ±223, overflow may occur. Generally speaking this will not happen because the matrix elements are 16bit integers, so it would take more than 256 source planes before trouble could arise.
Availability
Available in OS X v10.4 and later.

Returns a gamma function object.
Declaration
Swift
func vImageCreateGammaFunction(_
gamma
: Float, _gamma_type
: Int32, _flags
: vImage_Flags) > GammaFunctionObjectiveC
GammaFunction vImageCreateGammaFunction ( float gamma, int gamma_type, vImage_Flags flags );
Parameters
gamma
The exponent of a power function for calculating fullprecision gamma correction.
gammatype
A selector for the type of gamma correction to use. Pass one of the full or halfprecision type constants defined in Gamma Function Types.
flags
Pass
kvImageDoNotTile
if you plan to perform your own tiling or use multithreading.Return Value
A gamma function object that encapsulates a gamma value, a gamma function type, and option flags.
Discussion
You can pass a gamma function object to any of the three gamma correction functions:
vImageGamma_Planar8toPlanarF
,vImageGamma_PlanarFtoPlanar8
,vImageGamma_PlanarF
.The gammatype parameter determines the type of calculation to be used. The simplest calculation is:
if (value == 0) result = 0;
else {
if (value < 0)
sign = 1.0f;
else
sign = 1.0f;
result = pow( fabs( value ), gamma) * sign;
}
This calculation results in symmetric gamma curves about 0, and makes sure that only wellbehaved values are used in
pow()
.You can use an equivalent calculation that uses a more efficient method, depending on the desired precision.
In addition to the fullprecision gamma correction, there is a faster halfprecision option that provides 12bit precision.
f your data will ultimately be converted to 8bit integer data, consider using halfprecision. The halfprecision variants work correctly only for floatingpoint input values in the range 0.0 ... 1.0, though outofrange values produce results that clamp appropriately to 0 or 255 on conversion back to 8bit. In addition, there are restrictions on the range of the exponent: it must be positive, in the range 0.1 to 10.0.
Finally, there is a set of still faster halfprecision options that use predefined gamma values, ignoring the value set in
vImageCreateGammaFunction
. These options have the same restrictions on input values as stated previously.Availability
Available in OS X v10.4 and later.

Destroys a gamma function object created.
Declaration
Swift
func vImageDestroyGammaFunction(_
f
: GammaFunction)ObjectiveC
void vImageDestroyGammaFunction ( GammaFunction f );
Parameters
f
A gamma function object created with the function
vImageCreateGammaFunction
.Availability
Available in OS X v10.4 and later.

Applies a gamma function to a Planar8 image to produce a PlanarF image.
Declaration
Swift
func vImageGamma_Planar8toPlanarF(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _gamma
: GammaFunction, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageGamma_Planar8toPlanarF ( const vImage_Buffer *src, const vImage_Buffer *dest, const GammaFunction gamma, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.gamma
A gamma function object, created with by calling the function
vImageCreateGammaFunction
.flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Availability
Available in OS X v10.4 and later.

Applies a gamma function to an image in PlanarF format to an image in Planar8 format.
Declaration
Swift
func vImageGamma_PlanarFtoPlanar8(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _gamma
: GammaFunction, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageGamma_PlanarFtoPlanar8 ( const vImage_Buffer *src, const vImage_Buffer *dest, const GammaFunction gamma, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.gamma
A gamma function object, created with by calling the function
vImageCreateGammaFunction
.flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Availability
Available in OS X v10.4 and later.

Applies a gamma function to a PlanarF image.
Declaration
Swift
func vImageGamma_PlanarF(_
src
: UnsafePointer<vImage_Buffer>, _dest
: UnsafePointer<vImage_Buffer>, _gamma
: GammaFunction, _flags
: vImage_Flags) > vImage_ErrorObjectiveC
vImage_Error vImageGamma_PlanarF ( const vImage_Buffer *src, const vImage_Buffer *dest, const GammaFunction gamma, vImage_Flags flags );
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You are responsible for filling out the
height
,width
, androwBytes
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer pointed to by this structure contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.gamma
A gamma function object, created with by calling the function
vImageCreateGammaFunction
.flags
Reserved for future use; pass 0.
Return Value
kvImageNoError
, otherwise one of the error codes described in vImage Data Types and Constants Reference.Availability
Available in OS X v10.4 and later.

Types of full or halfprecision gamma functions.
Declaration
Swift
var kvImageGamma_UseGammaValue: Int { get } var kvImageGamma_UseGammaValue_half_precision: Int { get } var kvImageGamma_5_over_9_half_precision: Int { get } var kvImageGamma_9_over_5_half_precision: Int { get } var kvImageGamma_5_over_11_half_precision: Int { get } var kvImageGamma_11_over_5_half_precision: Int { get } var kvImageGamma_sRGB_forward_half_precision: Int { get } var kvImageGamma_sRGB_reverse_half_precision: Int { get } var kvImageGamma_11_over_9_half_precision: Int { get } var kvImageGamma_9_over_11_half_precision: Int { get } var kvImageGamma_BT709_forward_half_precision: Int { get } var kvImageGamma_BT709_reverse_half_precision: Int { get }
ObjectiveC
enum { kvImageGamma_UseGammaValue = 0, kvImageGamma_UseGammaValue_half_precision = 1, kvImageGamma_5_over_9_half_precision = 2, kvImageGamma_9_over_5_half_precision = 3, kvImageGamma_5_over_11_half_precision = 4, kvImageGamma_11_over_5_half_precision = 5, kvImageGamma_sRGB_forward_half_precision = 6, kvImageGamma_sRGB_reverse_half_precision = 7, kvImageGamma_11_over_9_half_precision = 8, kvImageGamma_9_over_11_half_precision = 9, kvImageGamma_BT709_forward_half_precision = 10, kvImageGamma_BT709_reverse_half_precision = 11 };
Constants

kvImageGamma_UseGammaValue
kvImageGamma_UseGammaValue
Fullprecision calculation using the gamma value set in
vImageCreateGammaFunction
.Available in OS X v10.4 and later.

kvImageGamma_UseGammaValue_half_precision
kvImageGamma_UseGammaValue_half_precision
Halfprecision calculation using the gamma value set in
vImageCreateGammaFunction
.Available in OS X v10.4 and later.

kvImageGamma_5_over_9_half_precision
kvImageGamma_5_over_9_half_precision
Halfprecision calculation using a gamma value of 5/9 or 1/1.8.
Available in OS X v10.4 and later.

kvImageGamma_9_over_5_half_precision
kvImageGamma_9_over_5_half_precision
Halfprecision calculation using a gamma value of 9/5 or 1.8.
Available in OS X v10.4 and later.

kvImageGamma_5_over_11_half_precision
kvImageGamma_5_over_11_half_precision
Halfprecision calculation using a gamma value of 5/11 or 1/2.2.
Available in OS X v10.4 and later.

kvImageGamma_11_over_5_half_precision
kvImageGamma_11_over_5_half_precision
Halfprecision calculation using a gamma value of 11/5 or 2.2. On exit, gamma is 5/11.
Available in OS X v10.4 and later.

kvImageGamma_sRGB_forward_half_precision
kvImageGamma_sRGB_forward_half_precision
Halfprecision calculation using the sRGB standard gamma value of 2.2.
Available in OS X v10.4 and later.

kvImageGamma_sRGB_reverse_half_precision
kvImageGamma_sRGB_reverse_half_precision
Halfprecision calculation using the sRGB standard gamma value of 1/2.2.
Available in OS X v10.4 and later.

kvImageGamma_11_over_9_half_precision
kvImageGamma_11_over_9_half_precision
Halfprecision calculation using a gamma value of 11/9 or (11/5)/(9/5).
Available in OS X v10.4 and later.

kvImageGamma_9_over_11_half_precision
kvImageGamma_9_over_11_half_precision
Halfprecision calculation using a gamma value of 9/11 or (9/5)/(11/5).
Available in OS X v10.4 and later.

kvImageGamma_BT709_forward_half_precision
kvImageGamma_BT709_forward_half_precision
ITUR BT.709 standard. This is like kvImageGamma_sRGB_forward_half_precision above but without the 1.125 viewing gamma for computer graphics:
x<0.081? x/4.5: pow((x+0.099)/1.099, 1/0.45)
.Available in OS X v10.4 and later.

kvImageGamma_BT709_reverse_half_precision
kvImageGamma_BT709_reverse_half_precision
ITUR BT.709 standard reverse. This is like kvImageGamma_sRGB_reverse_half_precision above but without the 1.125 viewing gamma for computer graphics:
x<0.018? 4.5*x: 1.099*pow(x,0.45)  0.099
.Available in OS X v10.4 and later.

Copyright © 2016 Apple Inc. All rights reserved. Terms of Use  Privacy Policy  Updated: 20111012