Next Page >

Hide TOC

vDSP Correlation, Convolution, and Filtering Reference

Framework	Accelerate/vecLib
Declared in	vDSP.h

Overview

Describes the C API for the correlation, convolution, and filtering functions in vecLib.

Functions by Task

Correlation and Convolution

Windowing and Filtering

Functions

vDSP_blkman_window

Creates a single-precision Blackman window.

   void vDSP_blkman_window(
   float * C,
   vDSP_Length N,
   int FLAG);

Discussion

vDSP_blkman_window creates a single-precision Blackman window function C, which can be multiplied by a vector using vDSP_vmul. Specify the vDSP_HALF_WINDOW flag to create only the first (n+1)/2 points, or 0 (zero) for full size window.

See also vDSP_vmul.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_blkman_windowD

Creates a double-precision Blackman window.

   void vDSP_blkman_windowD (double * C,
   vDSP_Length N,
   int FLAG);

Discussion

vDSP_blkman_window creates a double-precision Blackman window function C, which can be multiplied by a vector using vDSP_vmulD . Specify the vDSP_HALF_WINDOW flag to create only the first (n+1)/2 points, or 0 (zero) for full size window.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_conv

Performs either correlation or convolution on two vectors; single precision.

   vDSP_conv (const float signal[],
   vDSP_Stride signalStride,
   const float filter[],
   vDSP_Stride strideFilter,
   float result[],
   vDSP_Stride strideResult,
   vDSP_Length lenResult,
   vDSP_Length lenFilter);

Discussion

If filterStride is positive, vDSP_conv performs correlation. If filterStride is negative,it performs convolution and *filtermust point to the last vector element. The function can run in place, but result cannot be in place with filter.

The value of lenFilter must be less than or equal to 2044. The length of vector signal must satisfy two criteria: it must be

equal to or greater than 12
equal to or greater than the sum of N-1 plus the nearest multiple of 4 that is equal to or greater than the value of lenFilter.

Criteria to invoke vectorized code:

The vectors signal and result must be relatively aligned.
The value of lenFilter must be between 4 and 256, inclusive.
The value of lenResult must be greater than 36.
The values of signalStride and resultStride must be 1.
The value of filterStride must be either 1 or -1.

If any of these criteria is not satisfied, the function invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_convD

Performs either correlation or convolution on two vectors; double precision.

   void vDSP_convD (const double signal[],
   vDSP_Stride signalStride,
   const double filter[],
   vDSP_Stride strideFilter,
   double result[],
   vDSP_Stride strideResult,
   vDSP_Length lenResult,
   vDSP_Length lenFilter);

Discussion

If filterStride is positive, vDSP_convD performs correlation. If filterStride is negative,it performs convolution and *filtermust point to the last vector element. The function can run in place, but result cannot be in place with filter.

The value of lenFilter must be less than or equal to 2044. The length of vector signal must satisfy two criteria: it must be

equal to or greater than 12
equal to or greater than the sum of N-1 plus the nearest multiple of 4 that is equal to or greater than the value of lenFilter.

Criteria to invoke vectorized code:

No Altivec support for double precision. On a PowerPC processor, this function always invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_desamp

Convolution with decimation; single precision.

   void vDSP_desamp (float * A,
   vDSP_Stride I,
   float * B,
   float * C,
   vDSP_Length N,
   vDSP_Length M);

Parameters

A: Single-precision real input vector, 8-byte aligned; length of A >= 12
I: Desampling factor
B: Single-precision input filter coefficients
C: Single-precision real output vector
N: Output count
M: Filter coefficient count

Discussion

Performs finite impulse response (FIR) filtering at selected positions of vector A. desampx can run in place, but C cannot be in place with B. Length of A must be >=(N-1)*I+(nearest multiple of 4 >=M).

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_desampD

Convolution with decimation; double precision.

   void vDSP_desampD (double * A,
   vDSP_Stride I,
   double * B,
   double * C,
   vDSP_Length N,
   vDSP_Length M);

Parameters

A: Double-precision real input vector, 8-byte aligned; length of A >= 12
I: Desampling factor
B: Double-precision input filter coefficients
C: Double-precision real output vector
N: Output count
M: Filter coefficient count

Discussion

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_f3x3

Filters an image by performing a two-dimensional convolution with a 3x3 kernel on the input matrix A. The resulting image is placed in the output matrix C; single precision.

   void vDSP_f3x3 (float * signal,
   vDSP_Length rows,
   vDSP_Length cols,
   float * filter,
   float * result);

Discussion

This performs the operation

The function pads the perimeter of the output image with a border of zeros of width 1.

B is the 3x3 kernel. M and N are the number of rows and columns, respectively, of the two-dimensional input matrix A. M must be greater than or equal to 3. N must be even and greater than or equal to 4.

Criteria to invoke vectorized code:

A, B, and C must be 16-byte aligned.
N must be greater than or equal to 18.

If any of these criteria is not satisfied, the function invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_f3x3D

Filters an image by performing a two-dimensional convolution with a 3x3 kernel on the input matrix A. The resulting image is placed in the output matrix C; double precision.

   void vDSP_f3x3D (double * signal,
   vDSP_Length rows,
   vDSP_Length cols,
   double * filter,
   double * result);

Discussion

This performs the operation

The function pads the perimeter of the output image with a border of zeros of width 1.

Criteria to invoke vectorized code:

A, B, and C must be 16-byte aligned.
N must be greater than or equal to 18.

If any of these criteria is not satisfied, the function invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_f5x5

Filters an image by performing a two-dimensional convolution with a 5x5 kernel on the input matrix signal. The resulting image is placed in the output matrix result; single precision.

   void vDSP_f5x5 (float * signal,
   vDSP_Length rows,
   vDSP_Length cols,
   float * filter,
   float * result);

Discussion

This performs the operation

The function pads the perimeter of the output image with a border of zeros of width 2.

B is the 3x3 kernel. M and N are the number of rows and columns, respectively, of the two-dimensional input matrix A. M must be greater than or equal to 5. N must be even and greater than or equal to 6.

Criteria to invoke vectorized code:

A, B, and C must be 16-byte aligned.
N must be greater than or equal to 20.

If any of these criteria is not satisfied, the function invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_f5x5D

Filters an image by performing a two-dimensional convolution with a 5x5 kernel on the input matrix signal. The resulting image is placed in the output matrix result; double precision.

   void vDSP_f5x5D (double * signal,
   vDSP_Length rows,
   vDSP_Length cols,
   double * filter,
   double * result);

Discussion

This performs the operation

The function pads the perimeter of the output image with a border of zeros of width 2.

Criteria to invoke vectorized code:

A, B, and C must be 16-byte aligned.
N must be greater than or equal to 20.

If any of these criteria is not satisfied, the function invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_hamm_window

Creates a single-precision Hamming window.

   void
   vDSP_hamm_window (float * C,
   vDSP_Length N,
   int FLAG);

Discussion

vDSP_hamm_window creates a single-precision Hamming window function C, which can be multiplied by a vector using vDSP_vmul . Specify the vDSP_HALF_WINDOW flag to create only the first (n+1)/2 points, or 0 (zero) for full size window.

See also vDSP_vmul.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_hamm_windowD

Creates a double-precision Hamming window.

   void
   vDSP_hamm_windowD (double * C,
   vDSP_Length N,
   int FLAG);

Discussion

vDSP_hamm_windowD creates a double-precision Hamming window function C, which can be multiplied by a vector using vDSP_vmulD . Specify the vDSP_HALF_WINDOW flag to create only the first (n+1)/2 points, or 0 (zero) for full size window.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_hann_window

Creates a single-precision Hanning window.

   void
   vDSP_hann_window (float * C,
   vDSP_Length N,
   int FLAG);

Discussion

vDSP_hann_window creates a single-precision Hanning window function C, which can be multiplied by a vector using vDSP_vmul .

The FLAG parameter can have the following values:

vDSP_HANN_DENORM creates a denormalized window.
vDSP_HANN_NORM creates a normalized window.
vDSP_HALF_WINDOW creates only the first (N+1)/2 points.

vDSP_HALF_WINDOW can be ORed with any of the other values (i.e., using the C operator |).

See also vDSP_vmul.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_hann_windowD

Creates a double-precision Hanning window.

   void
   vDSP_hann_windowD (double * C,
   vDSP_Length N,
   int FLAG);

Discussion

vDSP_hann_window creates a double-precision Hanning window function C, which can be multiplied by a vector using vDSP_vmul .

The FLAG parameter can have the following values:

vDSP_HANN_DENORM creates a denormalized window.
vDSP_HANN_NORM creates a normalized window.
vDSP_HALF_WINDOW creates only the first (N+1)/2 points.

vDSP_HALF_WINDOW can ORed with any of the other values (i.e., using the C operator |).

See also vDSP_vmul.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_imgfir

Filters an image by performing a two-dimensional convolution with a kernel; single precision.

   void vDSP_imgfir (float * signal,
   vDSP_Length numRow,
   vDSP_Length numCol,
   float * filter,
   float * result,
   vDSP_Length fnumRow,
   vDSP_Length fnumCol);

Parameters

signal: A complex vector signal input.
numRow: Single-precision input matrix
numCol: Single-precision filter kernel
filter: Number of rows in numRow and in fnumCol
result: The complex vector signal output.
fnumRow: Number of columns in numRow and in fnumCol
fnumCol: Single-precision result matrix

Discussion

The image is given by the input matrix numRow. It has filter rows and fnumRow columns. filter and fnumRow must both be odd and greater than or equal to 5.

numCol is the filter kernel. It has P rows and Q columns. P must be greater than or equal to Q.

filter must be even and greater than P. fnumRow must be even and greater than Q.

The filtered image is placed in the output matrix fnumCol. The functions pad the perimeter of the output image with a border of (P-1)/2 rows of zeros on the top and bottom and (Q-1)/2 columns of zeros on the left and right.

Criteria to invoke vectorized code:

The parameters numRow, numCol, and fnumCol must be 16-byte aligned.
fnumRow must be greater than or equal to 20.

If any of these criteria is not satisfied, the function invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_imgfirD

Filters an image by performing a two-dimensional convolution with a kernel; double precision.

   void vDSP_imgfirD (double * signal,
   vDSP_Length numRow,
   vDSP_Length numCol,
   double * filter,
   double * result,
   vDSP_Length fnumRow,
   vDSP_Length fnumCol);

Parameters

signal: A complex vector signal input.
numRow: Double-precision input matrix
numCol: Double-precision filter kernel
filter: Number of rows in numRow and in fnumCol
result: The complex vector signal output.
fnumRow: Number of columns in numRow and in fnumCol
fnumCol: Double-precision result matrix

Discussion

The image is given by the input matrix numRow. It has filter rows and fnumRow columns. filter and fnumRow must both be odd and greater than or equal to 5.

numCol is the filter kernel. It has P rows and Q columns. P must be greater than or equal to Q.

filter must be even and greater than P. fnumRow must be even and greater than Q.

Criteria to invoke vectorized code:

The parameters numRow, numCol, and fnumCol must be 16-byte aligned.
fnumRow must be greater than or equal to 20.

If any of these criteria is not satisfied, the function invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_wiener

Wiener-Levinson general convolution; single precision.

   void vDSP_wiener (vDSP_Length L,
   float * A,
   float * C,
   float * F,
   float * P,
   int IFLG,
   int * IERR);

Parameters

L: Input filter length
A: Single-precision real input vector: coefficients
C: Single-precision real input vector: input coefficients
F: Single-precision real output vector: filter coefficients
P: Single-precision real output vector: error prediction operators
IFLG: Not currently used, pass zero
IERR: Error flag

Discussion

Performs the operation

solves a set of single-channel normal equations described by:

 B[n] = C[0] * A[n] + C[1] * A[n-1] +, . . . ,+ C[N-1] * A[n-N+1]

 for n = {0, N-1}

where matrix A contains elements of the symmetric Toeplitz matrix shown below. This function can only be done out of place.

Note that A[-n] is considered to be equal to A[n].

vDSP_wiener solves this set of simultaneous equations using a recursive method described by Levinson. See Robinson, E.A., Multichannel Time Series Analysis with Digital Computer Programs. San Francisco: Holden-Day, 1967, pp. 43-46.

 |A[0]  A[1]  A[2] ... A[N-1] |    |C[0]  |   |B[0]  |

 |A[1]  A[0]  A[1] ... A[N-2] |    |C[1]  |   |B[1]  |

 |A[2]  A[1]  A[0] ... A[N-3] |  * |C[2]  | = |B[2]  |

 | ...   ...   ... ... ...    |    | ...  |   | ...  |

 |A[N-1]A[N-2]A[N-3] ... A[0] |    |C[N-1]|   |B[N-1]|

Typical methods for solving N equations in N unknowns have execution times proportional to N cubed, and memory requirements proportional to N squared. By taking advantage of duplicate elements, the recursion method executes in a time proportional to N squared and requires memory proportional to N. The Wiener-Levinson algorithm recursively builds a solution by computing the m+1 matrix solution from the m matrix solution.

With successful completion,vDSP_wiener returns zero in error flag IERR. If vDSP_wiener fails, IERR indicates in which pass the failure occurred.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_wienerD

Wiener-Levinson general convolution; double precision.

   void vDSP_wienerD (vDSP_Length L,
   double * A,
   double * C,
   double * F,
   double * P,
   int IFLG,
   int * IERR);

Parameters

L: Input filter length
A: Double-precision real input vector: coefficients
C: Double-precision real input vector: input coefficients
F: Double-precision real output vector: filter coefficients
P: Double-precision real output vector: error prediction operators
IFLG: Not currently used, pass zero
IERR: Error flag

Discussion

Performs the operation

solves a set of single-channel normal equations described by:

 B[n] = C[0] * A[n] + C[1] * A[n-1] +, . . . ,+ C[N-1] * A[n-N+1]

 for n = {0, N-1}

where matrix A contains elements of the symmetric Toeplitz matrix shown below. This function can only be done out of place.

Note that A[-n] is considered to be equal to A[n].

 |A[0]  A[1]  A[2] ... A[N-1] |    |C[0]  |   |B[0]  |

 |A[1]  A[0]  A[1] ... A[N-2] |    |C[1]  |   |B[1]  |

 |A[2]  A[1]  A[0] ... A[N-3] |  * |C[2]  | = |B[2]  |

 | ...   ...   ... ... ...    |    | ...  |   | ...  |

 |A[N-1]A[N-2]A[N-3] ... A[0] |    |C[N-1]|   |B[N-1]|

With successful completion,vDSP_wiener returns zero in error flag IERR. If vDSP_wiener fails, IERR indicates in which pass the failure occurred.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_zconv

Performs either correlation or convolution on two complex vectors; single precision.

   void vDSP_zconv (DSPSplitComplex * signal,
   vDSP_Stride signalStride,
   DSPSplitComplex * filter,
   vDSP_Stride strideFilter,
   DSPSplitComplex * result,
   vDSP_Stride strideResult,
   vDSP_Length lenResult,
   vDSP_Length lenFilter);

Discussion

A is the input vector, with stride I, and C is the output vector, with stride K and length N.

B is a filter vector, with stride I and length P. If Jis positive,the function performs correlation. If Jis negative, it performs convolution and Bmust point to the last element in the filter vector. The function can run in place, but Ccannot be in place with B.

The value of N must be less than or equal to 512.

Criteria to invoke vectorized code:

Both the real parts and the imaginary parts of vectors A and C must be relatively aligned.
The values of I and K must be 1.

If any of these criteria is not satisfied, the function invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_zconvD

Performs either correlation or convolution on two complex vectors; double precision.

   void vDSP_zconvD (DSPDoubleSplitComplex * signal,
   vDSP_Stride signalStride,
   DSPDoubleSplitComplex * filter,
   vDSP_Stride strideFilter,
   DSPDoubleSplitComplex * result,
   vDSP_Stride strideResult,
   vDSP_Length lenResult,
   vDSP_Length lenFilter);

Discussion

A is the input vector, with stride I, and C is the output vector, with stride K and length N.

B is a filter vector, with stride I and length P. If J is positive, the function performs correlation. If J is negative, it performs convolution and B must point to the last element in the filter vector. The function can run in place, but C cannot be in place with B.

The value of N must be less than or equal to 512.

Criteria to invoke vectorized code:

No Altivec support for double precision. On a PowerPC processor, this function always invokes scalar code.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_zrdesamp

Complex/real downsample with anti-aliasing; single precision.

   void vDSP_zrdesamp (DSPSplitComplex * A,
   vDSP_Stride I,
   float * B,
   DSPSplitComplex * C,
   vDSP_Length N,
   vDSP_Length M);

Parameters

A: Single-precision complex input vector.
I: Complex decimation factor.
B: Filter coefficient vector.
C: Single-precision complex output vector.
N: Length of output vector.
M: Length of real filter vector.

Discussion

Performs finite impulse response (FIR) filtering at selected positions of input vector A.

Length of A must be at least (N+M-1)*i. This function can run in place, but C cannot be in place with B.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

vDSP_zrdesampD

Complex/real downsample with anti-aliasing; double precision.

   void vDSP_zrdesampD (DSPDoubleSplitComplex * A,
   vDSP_Stride I,
   double * B,
   DSPDoubleSplitComplex * C,
   vDSP_Length N,
   vDSP_Length M);

Parameters

A: Double-precision complex input vector.
I: Complex decimation factor.
B: Filter coefficient vector.
C: Double-precision complex output vector.
N: Length of output vector.
M: Length of real filter vector.

Discussion

Performs finite impulse response (FIR) filtering at selected positions of input vector A.

Length of A must be at least (N+M-1)*i. This function can run in place, but C cannot be in place with B.

Availability

Available in Mac OS X v10.4 and later.

Declared In

vDSP.h

Next Page >

Hide TOC

Last updated: 2007-06-15

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice