vecLib

Overview

The vecLib framework contains nine C header files (not counting vecLib.h which merely includes the others). Two of them, vDSP.h and vDSP_translate.h, are covered in vDSP Programming Guide and vDSP.

Three of the header files are Apple’s versions of well-known libraries which are described in detail in external references:

This document describes the functions declared in the remaining header files: vecLibTypes.h, vfp.h, vForce.h, vBasicOps.h, vectorOps.h, and vBigNum.h. These files support the vector mathematical functions library (also called “vMathLib”), which runs on vector processing hardware if available.

This library abstracts the vector processing capability so that code written for it will execute appropriate instructions for the processor available at runtime. For this reason, unless you are writing specialized code that targets a single CPU, you should generally use these functions rather than directly using vector instructions. By using these functions, your code does not have to deal with subtle differences in vector instruction availability between different microarchitectures, freeing you to focus on the problem you are trying to solve. Also, code written using vecLib tends to be easier to port to different CPU architectures (porting your core libraries to ARM on iOS, for example).

vecLibTypes.h

The vecLibTypes.h header file defines a set of vector data types (vFloat, vUInt32, etc.), which represent 128-bit vectors containing values of type float, UInt32, etc. The vBasicOps.h and vfp.h headers make use of these types.

The type names all begin with the letter “v,” followed by a mnemonic for the scalar data type used for elements of the vector. For example, vUInt32, vSInt16, vFloat, etc.

vBasicOps.h

vBasicOps.h declares a set of basic arithmetic and logical functions on 128-bit vectors, using the integer types from vecLibTypes.h.

The function names begin with “v,” followed by a mnemonic for the type of operation, e.g. “S” or “U” for signed or unsigned, then the width of the operation, then the name of the operation. For example, vS8Divide performs division of signed 8-bit values packed into 128-bit vectors.

vfp.h

vfp.h declares a set of floating-point arithmetic, transcendental and trigonometric functions, on 128-bit vectors, using the floating-point types from vecLibTypes.h.

These functions are named with their customary mathematical names, prefixed with the letter “v”, and all except vtablelookup() have the suffix “f” to indicate that they work with single-precision floating-point data. For example, vcosf is the single-precision cosine function.

vForce.h

vForce.h declares a set of trigonometric and transcendental functions in terms of C arrays (double * or float *), which can be of any desired length. Internally, the C arrays are converted piecewise into collections of 128-bit vectors, if appropriate for the current architecture.

The functions declared in vForce.h are named with the customary mathematical names, but with the prefix “vv.” Each mathematical function is available in two variants: one for single-precision floating-point data and one for double-precision data. The single-precision forms have the suffix “f”, while the double-precision forms have no suffix. For example, vvcosf is the single-precision cosine function, while vvcos is the double-precision variant.

All of the vForce.h functions follow a common format:

  • The return type is void.

  • The first parameter points to an array to hold the results. (The only exceptions are vvsincosf() and vvsincos(), which have two result arrays pointed to by the first two parameters.)

  • One or more parameters point to operand arrays, the same length as the result array.

  • The last parameter is the array length.

vectorOps.h

vectorOps.h declares a set of vector and matrix BLAS functions on arrays of 128-bit vectors containing single-precision floating-point values. The arrays can be of any desired length, but the number of float elements must be a multiple of 4.

vBigNum.h

vBigNum.h provides arithmetic and logical operations on large integers, which may be 128, 256, 512, or 1024 bits in length. It defines types for these values, and internally processes them as collections of 128-bit vectors.

vBigNum.h defines its own set of data types to represent large integer quantities, such as vS128 for a signed, 128-bit integer or vU1024 for an unsigned, 1024-bit integer. The function names begin with the data type name, followed by the name of the operation. For example, vS512Add performs addition of two 128-bit signed integers.

The functions perform logical and arithmetic operations on scalar values that may be 128, 256, 512, or 1024 bits in width. These values are implemented as structures of one, two, four, or eight 128-bit vectors, and the operations execute on the available vector-processing hardware if possible.

The functions have names that are compatible with those in vBasicOps.h.

Threading Model

In versions of vecLib prior to OS X v10.7, many vecLib routines used multiple POSIX threads to improve performance. In some cases, this could cause performance problems in applications that use large numbers of POSIX threads.

An application can limit the number of threads used by vecLib by setting the environment variable VECLIB_MAXIMUM_THREADS as follows:

 
    #include <stdlib.h>
 
    setenv("VECLIB_MAXIMUM_THREADS", "1", true);

To remove the limit, you can unset the environment variable as follows:

    unsetenv("VECLIB_MAXIMUM_THREADS");

In OS X v10.7, these routines use Grand Central Dispatch, so the use of this environment variable should no longer be necessary.

For More Information

For information about membership in Apple’s developer program, go to this URL:

http://developer.apple.com/membership/

For information about the Velocity Engine, go to this URL:

http://developer.apple.com/hardwaredrivers/ve/index.html

For general technical support from Apple, go to this URL:

https://developer.apple.com/support/

Symbols

Array-Oriented Arithmetic and Auxiliary Functions (from vForce.h)

func vvceil(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the ceiling of x.

func vvceilf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the ceiling of x.

func vvfloor(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the floor of x.

func vvfloorf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the floor of x.

func vvfmod(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

Sets each element y[i] to the floating point remainder of (y[i]/x[i]) for i in 0..n-1.

func vvint(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the integer truncation of x.

func vvintf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the integer truncation of x.

func vvnextafter(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

Sets each element z[i] to the next machine-representable value from y[i] towards x[i] for i in 0..n-1.

func vvnextafterf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

Sets each element z[i] to the next machine-representable value from y[i] towards x[i] for i in 0..n-1.

func vvnint(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the nearest integer to x.

func vvnintf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the nearest integer to x.

func vvrsqrt(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the reciprocal of the square root of x.

func vvrsqrtf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the reciprocal of the square root of x.

func vvsqrt(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the square root of x.

func vvsqrtf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the square root of x.

func vvrec(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the reciprocal of y.

func vvrecf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the reciprocal of y.

func vvremainder(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

Sets z[i] to the remainder relative to a round-to-even division of y[i]/x[i] for each i in 0..n-1.

Array-Oriented Exponential and Logarithmic Functions (from vForce.h)

func vvexp(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the exponential of x.

func vvexpf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the exponential of x.

func vvexp2(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

Sets each element y[i] to 2 raised to (x[i]) for i in 0..n-1.

func vvexp2f(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

Sets each element y[i] to 2 raised to (x[i]) for i in 0..n-1.

func vvlog(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the natural logarithm of x.

func vvlogf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the natural logarithm of x.

func vvlog2(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

Sets each element y[i] to the base-2 logarithm of x[i] for i in 0..n-1.

func vvlog2f(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

Sets each element y[i] to the base 2 logarithm of x[i] for i in 0..n-1.

func vvlog10(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the base 10 logarithm of x.

func vvlog10f(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the base 10 logarithm of x.

func vvlogb(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

Sets each element y[i] to the exponent of x[i] for i in 0..n-1.

func vvlogbf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

Sets each element y[i] to the exponent of x[i] for i in 0..n-1.

Array-Oriented Power Functions (from vForce.h)

func vvpowf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets z to x raised to the power of y.

func vvpow(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets z to x raised to the power of y.

Array-Oriented Trigonometric Functions (from vForce.h)

func vvsin(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the sine of x.

func vvsinf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the sine of x.

func vvcos(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the cosine of x.

func vvcosf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the cosine of x.

func vvcospi(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

Sets each element y[i] to the sin(pi * x[i]) for i in 0..n-1.

func vvcospif(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

Sets each element y[i] to the sin(pi * x[i]) for i in 0..n-1.

func vvcosisin(OpaquePointer, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets the real part of C to the cosine of x and the imaginary part of C to the sine of x, for n elements.

func vvcosisinf(OpaquePointer, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets the real part of C to the cosine of x and the imaginary part of C to the sine of x, for n elements.

func vvsincos(UnsafeMutablePointer<Double>, UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets z to the sine of x and y to the cosine of x.

func vvsincosf(UnsafeMutablePointer<Float>, UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets z to the sine of x and y to the cosine of x.

func vvtan(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the tangent of x.

func vvtanf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the tangent of x.

func vvasin(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the arcsine of x.

func vvasinf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the arcsine of x.

func vvacos(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the arccosine of x.

func vvacosf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the arccosine of x.

func vvatan(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the arctangent of x.

func vvatanf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the arctangent of x.

func vvatan2f(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets z to the arctangent of y/x.

Array-Oriented Hyperbolic Functions (from vForce.h)

func vvsinhf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the hyperbolic sine of x.

func vvsinh(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the hyperbolic sine of x.

func vvcoshf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the hyperbolic cosine of x.

func vvcosh(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the hyperbolic cosine of x.

func vvtanhf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the hyperbolic tangent of x.

func vvtanh(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the hyperbolic tangent of x.

func vvasinhf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the inverse hyperbolic sine of x.

func vvasinh(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the inverse hyperbolic sine of x.

func vvacoshf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the inverse hyperbolic cosine of x.

func vvacosh(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the inverse hyperbolic cosine of x.

func vvatanhf(UnsafeMutablePointer<Float>, UnsafePointer<Float>, UnsafePointer<Int32>)

For each single-precision array element, sets y to the inverse hyperbolic tangent of x.

func vvatanh(UnsafeMutablePointer<Double>, UnsafePointer<Double>, UnsafePointer<Int32>)

For each double-precision array element, sets y to the inverse hyperbolic tangent of x.

Shift and Rotate Functions on Big Numbers (from vBigNum.h)

Arithmetic Functions on Big Numbers (from vBigNum.h)

func vU256HalfMultiply(UnsafePointer<vU256>, UnsafePointer<vU256>, UnsafeMutablePointer<vU256>)

Unsigned 256-bit multiplication; result is the same width as multiplicands.

func vS256HalfMultiply(UnsafePointer<vS256>, UnsafePointer<vS256>, UnsafeMutablePointer<vS256>)

Signed 256-bit multiplication; result is the same width as multiplicands.

func vU512HalfMultiply(UnsafePointer<vU512>, UnsafePointer<vU512>, UnsafeMutablePointer<vU512>)

Unsigned 512-bit multiplication; result is the same width as multiplicands.

func vS512HalfMultiply(UnsafePointer<vS512>, UnsafePointer<vS512>, UnsafeMutablePointer<vS512>)

Signed 512-bit multiplication; result is the same width as multiplicands.

func vU1024HalfMultiply(UnsafePointer<vU1024>, UnsafePointer<vU1024>, UnsafeMutablePointer<vU1024>)

Unsigned 1024-bit multiplication; result is the same width as multiplicands.

func vS1024HalfMultiply(UnsafePointer<vS1024>, UnsafePointer<vS1024>, UnsafeMutablePointer<vS1024>)

Signed 1024-bit multiplication; result is the same width as multiplicands.

func vU128FullMultiply(UnsafePointer<vU128>, UnsafePointer<vU128>, UnsafeMutablePointer<vU256>)

Unsigned 128-bit multiplication; result is twice as wide as multiplicands.

func vS128FullMultiply(UnsafePointer<vS128>, UnsafePointer<vS128>, UnsafeMutablePointer<vS256>)

Signed 128-bit multiplication; result is twice as wide as multiplicands.

func vU256FullMultiply(UnsafePointer<vU256>, UnsafePointer<vU256>, UnsafeMutablePointer<vU512>)

Unsigned 256-bit multiplication; result is twice as wide as multiplicands.

func vS256FullMultiply(UnsafePointer<vS256>, UnsafePointer<vS256>, UnsafeMutablePointer<vS512>)

Signed 256-bit multiplication; result is twice as wide as multiplicands.

func vU512FullMultiply(UnsafePointer<vU512>, UnsafePointer<vU512>, UnsafeMutablePointer<vU1024>)

Unsigned 512-bit multiplication; result is twice as wide as multiplicands.

func vS512FullMultiply(UnsafePointer<vS512>, UnsafePointer<vS512>, UnsafeMutablePointer<vS1024>)

Signed 512-bit multiplication; result is twice as wide as multiplicands.

Vector-Scalar Linear Algebra Functions (from vectorOps.h)

func vIsamax(Int32, OpaquePointer)

Finds the position of the first vector element having the largest absolute value.

func vIsamin(Int32, OpaquePointer)

Finds the position of the first vector element having the smallest absolute value.

func vIsmax(Int32, OpaquePointer)

Finds the position of the first vector element having the maximum value.

func vIsmin(Int32, OpaquePointer)

Finds the position of the first vector element having the minimum value.

func vSasum(Int32, OpaquePointer)

Finds the sum of the absolute values of the elements in a vector.

func vSsum(Int32, OpaquePointer)

Finds the sum of the values of the elements in a vector.

func vSaxpy(Int32, Float, OpaquePointer, OpaquePointer)

Multiplies a vector by a scalar , adds it to a second vector , and stores the result in the second vector.

func vSnaxpy(Int32, Int32, OpaquePointer, OpaquePointer, OpaquePointer)

Performs the computation of vSaxpy n times, using a different multiplier each time.

func vSdot(Int32, OpaquePointer, OpaquePointer)

Computes the dot product of two vectors.

func vSndot(Int32, Int32, UnsafeMutablePointer<Float>, Int32, OpaquePointer, OpaquePointer)

Computes the dot products of n pairs of vectors, accumulating or storing the results in an array of n float values.

func vSnrm2(Int32, OpaquePointer)

Finds the Euclidean length of a vector.

func vSnorm2(Int32, OpaquePointer)

Finds the Euclidean length of a vector.

func vSrot(Int32, OpaquePointer, OpaquePointer, Float, Float)

Applies planar rotation to a set of n points whose x and y coordinates are contained in two arrays of vectors.

func vSswap(Int32, OpaquePointer, OpaquePointer)

Interchanges the elements of two vectors.

func vSyax(Int32, Float, OpaquePointer, OpaquePointer)

Multiplies each element of a vector and stores the results in a second vector.

func vSzaxpy(Int32, Float, OpaquePointer, OpaquePointer, OpaquePointer)

Multiplies a vector by a scalar, adds it to a second vector, and stores the result in a third vector.

Matrix-Vector Linear Algebra Functions (from vectorOps.h)

func vSgemv(Int8, Int32, Int32, Float, OpaquePointer, OpaquePointer, Float, OpaquePointer)

Multiplies a vector by a scalar. Multiplies a matrix by another scalar, then by a second vector, and adds the resulting vector to the first vector. This function can also perform the calculation with the transpose of the original matrix instead of the matrix itself. A selector parameter determines whether the transpose is used.

func vSgemx(Int32, Int32, Float, OpaquePointer, OpaquePointer, OpaquePointer)

Multiplies a matrix by a scalar and then by a vector, and adds the resulting vector to a second vector.

func vSgemtx(Int32, Int32, Float, OpaquePointer, OpaquePointer, OpaquePointer)

Forms the transpose of a matrix, multiplies it by a scalar and then by a vector, and adds the resulting vector to a second vector.

Matrix Operations (from vectorOps.h)

func vSgemm(Int32, Int32, Int32, OpaquePointer, Int8, OpaquePointer, Int8, OpaquePointer, Float, Float, OpaquePointer)

Multiples two general matrices or their transposes, then scales and adds a third.

func vSgetmi(Int32, OpaquePointer)

Transposes a matrix in place.

func vSgevv(Int32, Int32, OpaquePointer, OpaquePointer, OpaquePointer)

Produces the outer product of two vectors and places the results into a matrix.

Data Types

All data structures passed to vecLib must be naturally aligned. For example, a 32-bit floating-point value must be aligned to a four-byte boundary. Many routines in vecLib generate exceptions on unaligned data.

vU128

A union containing one vUInt32 vector or four 32-bit integers, representing a 128-bit unsigned integer.

vS128

A union containing one vSInt32 vector or four 32-bit integers, representing a 128-bit signed integer.

vU256

A union containing an array or structure of two vUInt32 vectors or eight 32-bit integers, representing a 256-bit unsigned integer.

vS256

A union containing an array or structure of two vUInt32 vectors or eight 32-bit integers, representing a 256-bit signed integer.

vU512

A union containing an array or structure of four vUInt32 vectors or sixteen 32-bit integers, representing a 256-bit unsigned integer.

vS512

A union containing an array or structure of four vUInt32 vectors or sixteen 32-bit integers, representing a 256-bit signed integer.

vU1024

A union containing an array or structure of eight vUInt32 vectors or thirty-two 32-bit integers, representing a 1024-bit unsigned integer.

vS1024

A union containing an array or structure of eight vUInt32 vectors or thirty-two 32-bit integers, representing a 1024-bit signed integer.