FIRDown

Directly filters a source vector through an FIR filter with downsampling or decimation.

Syntax

Intel IPP style:

IppStatus ippsqFIRDownDirect_32f (const Ipp32f *pSrc, Ipp32f *pDst, Ipp32u srcLen, const Ipp32f* pTaps, Ipp32u tapsLen, Ipp32u downFactor, Ipp32f* pDlyLine);

IppStatus ippsqFIRDownDirectQ15_16s_Rms (const Ipp16s *pSrc, Ipp16s *pDst, Ipp32u srcLen, const Ipp16s* pTaps, Ipp32u tapsLen, Ipp32u downFactor, Ipp16s* pDlyLine);

IppStatus ippsqFIRDownDirectFastQ15_16s_Rms (const Ipp16s *pSrc, Ipp16s *pDst, Ipp32u srcLen, const Ipp16s* pTaps, Ipp32u tapsLen, Ipp32u downFactor, Ipp16s* pDlyLine);

IppStatus ippsqFIRDownDirectQ31_32s_Rm (const Ipp32s *pSrc, Ipp32s *pDst, Ipp32u srcLen, const Ipp32s* pTaps, Ipp32u tapsLen, Ipp32u downFactor, Ipp32s* pDlyLine);

IppStatus ippsqFIRDownDirectFastQ31_32s_Rm (const Ipp32s *pSrc, Ipp32s *pDst, Ipp32u srcLen, const Ipp32s* pTaps, Ipp32u tapsLen, Ipp32u downFactor, Ipp32s* pDlyLine);

DSP style:

typedef struct {
    Ipp8u   M;
    Ipp16u  numTaps;
    Ipp32f *pCoeffs;
    Ipp32f *pState;
} ippsq_fir_decimate_instance_f32;

ippsq_status ippsq_fir_decimate_init_f32 (ippsq_fir_decimate_instance_f32 *S, uint16_t numTaps, uint8_t M, float32_t *pCoeffs, float32_t *pState, uint32_t blockSize);

void ippsq_fir_decimate_f32 (const ippsq_fir_decimate_instance_f32 *S, float32_t *pSrc, float32_t *pDst, uint32_t blockSize);

typedef struct {
    Ipp8u   M;
    Ipp16u  numTaps;
    Ipp16s *pCoeffs;
    Ipp16s *pState;
} ippsq_fir_decimate_instance_q15;

ippsq_status ippsq_fir_decimate_init_q15 (ippsq_fir_decimate_instance_q15 *S, uint16_t numTaps, uint8_t M, q15_t *pCoeffs, q15_t *pState, uint32_t blockSize);

void ippsq_fir_decimate_q15 (const ippsq_fir_decimate_instance_q15 *S, q15_t *pSrc, q15_t *pDst, uint32_t blockSize);

void ippsq_fir_decimate_fast_q15 (const ippsq_fir_decimate_instance_q15 *S, q15_t *pSrc, q15_t *pDst, uint32_t blockSize);

typedef struct {
    Ipp8u   M;
    Ipp16u  numTaps;
    Ipp32s *pCoeffs;
    Ipp32s *pState;
} ippsq_fir_decimate_instance_q31;

ippsq_status ippsq_fir_decimate_init_q31 (ippsq_fir_decimate_instance_q31 *S, uint16_t numTaps, uint8_t M, q31_t *pCoeffs, q31_t *pState, uint32_t blockSize);

void ippsq_fir_decimate_q31 (const ippsq_fir_decimate_instance_q31 *S, q31_t *pSrc, q31_t *pDst, uint32_t blockSize);

void ippsq_fir_decimate_fast_q31 (ippsq_fir_decimate_instance_q31 *S, q31_t *pSrc, q31_t *pDst, uint32_t blockSize);

Include Files

ippsq.h

dsp.h

Parameters

pSrc

Pointer to the source vector.

pDst

Pointer to the destination vector. The length of the pDst array must be at least srcLen / downFactor.

srcLen, blockSize

Number of elements in the source vector. The value must be a multiple of the decimation factor downFactor (or M for DSP); can be zero.

pTaps, pCoeffs

Pointer to the array containing the tap values. The number of elements in the array is tapsLen.

tapsLen, numTaps

Number of elements in the array containing the tap values.

downFactor, M

Downsampling or decimation factor.

pDlyLine, pState

Pointer to the array containing the delay line values.

Description

This function passes a source vector pSrc through a downsampling filter, and stores the resulting samples in pDst. The values of filter coefficients (taps) are specified in the tapsLen -length array pTaps . The pDlyLine array specifies the delay line values. The input array pSrc contains srcLen samples, and the output array pDst stores the resulting (srcLen / downFactor) samples.

The algorithm is implemented as a single operation that includes two steps: filtering with a single-rate FIT filter and downsampling. The FIR response obtained by filtering an input signal is downsampled by the decimation factor downFactor.

The srcLen value must be a multiple of the decimation factor downFactor, otherwise, you need to care about the position of non-discarded sample within a block of filter response. The length of the delay line array pDlyLine is defined as (tapsLen + downFactor - 1).

Note

Parameters in the above description have Intel IPP-style names. For the corresponding DSP-style parameter names, refer to the Parameters section.

Intel IPP style:

When using Intel IPP-style APIs, you do not need to call any initialization functions. Intel IPP-style functions directly get all necessary parameters as arguments.

Initialize pDlyLine with zeros.

Function flavors with the _Rm suffix round down the resulting value.

Function flavors with the _Rms suffix round down the resulting value and perform saturation if the resulting value exceeds the data range.

DSP style: Each function type (f32, q15, and q31) has its own state structure, which must be initialized with the corresponding initialization function. The initialization function copies arguments into the state structure and sets the pState array to zero. The number of elements in the pState array should be at least numTaps + blockSize – 1.

Scaling, Truncation, Saturation

Intel IPP style:

Function Description
ippsqFIRDownDirectQ15_16s_Rms

The pSrc, pDst, pTaps, and pDlyLine values are represented in Q15 format. The function uses a 64-bit internal accumulator in Q34.30 format, so it preserves full precision of intermediate calculations and avoids internal overflow. In the end, the function shifts the accumulator right by 15 bits and saturates it in the [IPP_MIN_16S, IPP_MAX_16S] range.

ippsqFIRDownDirectFastQ15_16s_Rms

The pSrc, pDst, pTaps, and pDlyLine values are represented in Q15 format. The function uses a 32-bit internal accumulator in Q2.30 format and provides only one guard bit. The function is not protected from internal overflow. In the end, the function shifts the accumulator right by 15 bits and does not perform saturation.

ippsqFIRDownDirectQ31_32s_Rm

The pSrc, pDst, pTaps, and pDlyLine values are represented in Q31 format. The function uses a 64-bit internal accumulator in Q2.62 format and provides only one guard bit. The function is not protected from internal overflow. In the end, the function shifts the accumulator right by 31 bits and does not perform saturation.

ippsqFIRDownDirectFastQ31_32s_Rm

The pSrc, pDst, pTaps, and pDlyLine values are represented in Q31 format. The function uses a 32-bit internal accumulator in Q2.30 format. The function shifts right the result of multiplication of Q31 numbers, truncates it to Q2.30 format, and adds it to the accumulator. The function is not protected from internal overflow and provides less precision because it discards low 32 bits after multiplication. In the end, the function shifts the accumulator left by 1 bit and does not perform saturation.

DSP style:

Function Description
ippsq_fir_decimate_q15

The pSrc, pDst, pCoeffs, and pState values are represented in Q15 format. The function uses a 64-bit internal accumulator in Q34.30 format, so it preserves full precision of intermediate calculations and avoids internal overflow. In the end, the function shifts the accumulator right by 15 bits and saturates it in the [IPP_MIN_16S, IPP_MAX_16S] range.

ippsq_fir_decimate_fast_q15

The pSrc, pDst, pCoeffs, and pState values are represented in Q15 format. The function uses a 32-bit internal accumulator in Q2.30 format and provides only one guard bit. The function is not protected from internal overflow. In the end, the function shifts the accumulator right by 15 bits and does not perform saturation.

ippsq_fir_decimate_q31

The pSrc, pDst, pCoeffs, and pState values are represented in Q31 format. The function uses a 64-bit internal accumulator in Q2.62 format and provides only one guard bit. The function is not protected from internal overflow. In the end, the function shifts the accumulator right by 31 bits and does not perform saturation.

ippsq_fir_decimate_fast_q31

The pSrc, pDst, pCoeffs, and pState values are represented in Q31 format. The function uses a 32-bit internal accumulator in Q2.30 format. The function shifts right the result of multiplication of Q31 numbers, truncates it to Q2.30 format, and adds it to the accumulator. The function is not protected from internal overflow and provides less precision because it discards low 32 bits after multiplication. In the end, the function shifts the accumulator left by 1 bit and does not perform saturation.

Return Values

ippStsNoErr

Indicates no error.

ippStsSizeErr

Indicates an error when tapsLen is equal to zero.

ippStsNullPtrErr

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

IPPSQ_MATH_LENGTH_ERROR

DSP style:Indicates an error when blockSize is not a multiple of the decimation factor M.

For more complete information about compiler optimizations, see our Optimization Notice.