Intel® Integrated Performance Primitives Developer Guide and Reference

ID 790148
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

FIRMR

Performs multi-rate FIR filtering of a source vector.

Syntax

IppStatus ippsFIRMR_32f(const Ipp32f* pSrc, Ipp32f* pDst, int numIters, IppsFIRSpec_32f* pSpec, const Ipp32f* pDlySrc, Ipp32f* pDlyDst, Ipp8u* pBuf);

IppStatus ippsFIRMR_64f(const Ipp64f* pSrc, Ipp64f* pDst, int numIters, IppsFIRSpec_64f* pSpec, const Ipp64f* pDlySrc, Ipp64f* pDlyDst, Ipp8u* pBuf);

IppStatus ippsFIRMR_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int numIters, IppsFIRSpec_32fc* pSpec, const Ipp32fc* pDlySrc, Ipp32fc* pDlyDst, Ipp8u* pBuf);

IppStatus ippsFIRMR_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int numIters, IppsFIRSpec_64fc* pSpec, const Ipp64fc* pDlySrc, Ipp64fc* pDlyDst, Ipp8u* pBuf);

IppStatus ippsFIRMR_16s(const Ipp16s* pSrc, Ipp16s* pDst, int numIters, IppsFIRSpec_32f* pSpec, const Ipp16s* pDlySrc, Ipp16s* pDlyDst, Ipp8u* pBuf);

IppStatus ippsFIRMR_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int numIters, IppsFIRSpec_32fc* pSpec, const Ipp16sc* pDlySrc, Ipp16sc* pDlyDst, Ipp8u* pBuf);

Include Files

ipps.h

Domain Dependencies

Headers: ippcore.h, ippvm.h

Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc

Pointer to the source vector.

pDst

Pointer to the destination vector.

numIters

Number of iterations associated with the number of samples to be filtered by the function. The (numIters*downFactor) elements of the source vector are filtered and the resulting (numIters*upFactor) samples are stored in the destination array.

pSpec

Pointer to the internal specification structure.

pDlySrc

Pointer to the array containing values for the source delay lines. The value can be NULL. If not NULL, the array length is defined as (tapsLen+upFactor-1)/upFactor.

pDlyDst

Pointer to the array containing values for the destination delay line. The value can be NULL. If not NULL, the array length is defined as (tapsLen+upFactor-1)/upFactor.

pBuf

Pointer to the work buffer.

Description

Before using this function, you need to initialize the internal constant specification structure using the ippsFIRMR_Init function.

This function filters the source vector pSrc using the multi-rate FIR filter and stores the result in pDst. Filtering is performed by the following formula:



where

  • x(0)...x(numIters) is the source vector
  • h(0)...h(tapsLen-1) are the FIR filter coefficients

The values of filter coefficients (taps) are specified in the tapsLen-length array pTaps, which is passed during initialization of the FIR filter specification structure. The pDlySrc and pDlyDst arrays specify the delay line values. The input array contains (numIters*downFactor) samples, and the output array stores the resulting (numIters*upFactor) samples. The multi-rate filtering is considered as a sequence of three operations: upsampling, filtering with a single-rate FIR filter, and downsampling. The algorithm is implemented as a single operation including the mentioned above three steps.

The parameter upFactor is the factor by which the filtered signal is internally upsampled (see the ippsSampleUp function description for more details). That is, upFactor-1 zeros are inserted between each sample of the input signal.

The parameter upPhase is the parameter that determines where a non-zero sample lies within the upFactor-length block of upsampled input signal.

The parameter downFactor is the factor by which the FIR response, which is obtained by filtering an upsampled input signal, is internally downsampled (see the ippsSampleDown function description for more details). That is, downFactor-1 output samples are discarded from each downFactor-length output block of the upsampled filter response.

The parameter downPhase is the parameter which determines where non-discarded sample lies within a block of upsampled filter response.

To compute the y(0)...y(tapsLen-1) destination vector, the function uses the pDlySrc array of the delay line.

The first tapsLen-1 elements of the function are:

y(0)=h(tapsLen-1)*d(0)+h(tapsLen-2)*d(1)+...+h(1)*d(tapsLen-2)+h(0)*x(0)

y(0)=h(tapsLen-1)*d(1)+h(tapsLen-2)*d(2)+...+h(1)*x(0)+h(0)*x(1)

y(tapsLen-1)=h(tapsLen-1)*x(0)+...+h(1)*x(tapsLen-2)+h(0)*x(tapsLen-1)

where

d(0), d(1), d(2), and d(tapsLen-2) are the elements of the pDlySrc array

The last tapsLen-1 elements of the source vector are copied to the non-zero pDlyDst buffer for the next call of the FIR filter.

The arrays pDlySrc and pDlyDst support NULL values:

  • if pDlySrc is NULL, the function uses the delay line with zero values
  • if pDlyDst is NULL, the function does not copy any data to the destination delay line

Return Values

ippStsNoErr

Indicates no error.

ippStsNullPtrErr

Indicates an error when any of the specified pointers is NULL.

Example

The code example below demonstrates how to use the FIRMRGetSize, FIRMRInit, and FIRMR functions.

int firmr()
{
    IppsFIRSpec_32f *pSpec;
    Ipp32f pTaps[8] = { 0.125,0.125,0.125,0.125,0.125,0.125,0.125,0.125};
    int i;
    int numIters = 33;
    int tapsLen = 8;
    int upFactor = 2;
    int upPhase = 0;
    int downFactor = 3;
    int downPhase = 0;
    int specSize, bufSize;
    Ipp32f pSrc[downFactor*numIters];
    Ipp32f pDst[upFactor *numIters];
    Ipp32f pDlySrc[(tapsLen + upFactor - 1  ) / upFactor];
    Ipp32f pDlyDst[(tapsLen + upFactor - 1  ) / upFactor];
    Ipp8u* pBuf;
    IppStatus status;
    status = ippsFIRMRGetSize(tapsLen, upFactor, downFactor, ipp32f,  &specSize,  &bufSize );
    printf("ippsFIRMRGetSize / status = %s\n", ippGetStatusString(status));
    pSpec = (IppsFIRSpec_32f*)ippsMalloc_8u(specSize);
    pBuf  = ippsMalloc_8u(bufSize);
    status = ippsFIRMRInit_32f ( pTaps, tapsLen, upFactor, upPhase, downFactor, downPhase, pSpec);
    printf("ippsFIRMRInit_32f / status = %s\n", ippGetStatusString(status));
    if( ippStsNoErr != status){
        return -1;
    }
    for(i=0;i<downFactor*numIters;i++){
        pSrc[i] = 1;
    }
    status = ippsFIRMR_32f( pSrc, pDst, numIters, pSpec, NULL, pDlyDst, pBuf);
    printf("ippsFIRMR_32f / status = %s\n", ippGetStatusString(status));
    if( ippStsNoErr != status){
        return -1;
    }
    printf("src\n");
    for(i=0;i<numIters*downFactor;i++){
        printf("%6f ", pSrc[+i]);
    }
    printf("\ndst\n");
    for(i=0;i<numIters*upFactor;i++){
        printf("%6f ", pDst[i]);
    }
    printf("\n");
    return 0;
}

See Also