---------------------Page 1---------------------

 

 
Intel  ® Integrated Performance
Primitives

Reference Manual, Volume 1: Signal Processing

    8.1
 
 
 
Document Number: A24968-039US
Legal Information
---------------------Page 2---------------------

    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Legal Information

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE,
EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS
GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR
SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL DISCLAIMS ANY EXPRESS OR
IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR
WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT
OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
A "Mission Critical Application" is any application in which failure of the Intel Product could result, directly or
indirectly, in personal injury or death. SHOULD YOU PURCHASE OR USE INTEL'S PRODUCTS FOR ANY SUCH
MISSION CRITICAL APPLICATION, YOU SHALL INDEMNIFY AND HOLD INTEL AND ITS SUBSIDIARIES,
SUBCONTRACTORS AND AFFILIATES, AND THE DIRECTORS, OFFICERS, AND EMPLOYEES OF EACH,
HARMLESS AGAINST ALL CLAIMS COSTS, DAMAGES, AND EXPENSES AND REASONABLE ATTORNEYS' FEES
ARISING OUT OF, DIRECTLY OR INDIRECTLY, ANY CLAIM OF PRODUCT LIABILITY, PERSONAL INJURY, OR
DEATH ARISING IN ANY WAY OUT OF SUCH MISSION CRITICAL APPLICATION, WHETHER OR NOT INTEL OR
ITS SUBCONTRACTOR WAS NEGLIGENT IN THE DESIGN, MANUFACTURE, OR WARNING OF THE INTEL
PRODUCT OR ANY OF ITS PARTS.
Intel may make changes to specifications and product descriptions at any time, without notice. Designers
must not rely on the absence or characteristics of any features or instructions marked "reserved" or
"undefined". Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts
or incompatibilities arising from future changes to them. The information here is subject to change without
notice. Do not finalize a design with this information.
The products described in this document may contain design defects or errors known as errata which may
cause the product to deviate from published specifications. Current characterized errata are available on
request. Contact your local Intel sales office or your distributor to obtain the latest specifications and before
placing your product order. Copies of documents which have an order number and are referenced in this
document, or other Intel literature, may be obtained by calling 1-800-548-4725, or go to: http://
www.intel.com/design/literature.htm
MPEG-1, MPEG-2, MPEG-4, H.261, H.263, H.264, MP3, DV, VC-1, MJPEG, AC3, AAC, G.711, G.722, G.722.1,
G.722.2, AMRWB, Extended AMRWB (AMRWB+), G.167, G.168, G.169, G.723.1, G.726, G.728, G.729, G.
729.1, GSM AMR, GSM FR are international standards promoted by ISO, IEC, ITU, ETSI, 3GPP and other
organizations. Implementations of these standards, or the standard enabled platforms may require licenses
from various entities, including Intel Corporation.
Software and workloads used in performance tests may have been optimized for performance only on Intel
microprocessors. Performance tests, such as SYSmark and MobileMark, are measured using specific
computer systems, components, software, operations and functions. Any change to any of those factors may
cause the results to vary. You should consult other information and performance tests to assist you in fully
evaluating your contemplated purchases, including the performance of that product when combined with
other products.
BlueMoon, BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Inside, Cilk, Core Inside, E-GOLD,
Flexpipe, i960, Intel, the Intel logo, Intel AppUp, Intel Atom, Intel Atom Inside, Intel CoFluent, Intel Core,
Intel Inside, Intel Insider, the Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel
SingleDriver, Intel SpeedStep, Intel Sponsors of Tomorrow., the Intel Sponsors of Tomorrow. logo, Intel
StrataFlash, Intel vPro, Intel Xeon Phi, Intel XScale, InTru, the InTru logo, the InTru Inside logo, InTru
soundmark, Itanium, Itanium Inside, MCS, MMX, Pentium, Pentium Inside, Puma, skoool, the skoool logo,
SMARTi, Sound Mark, Stay With It, The Creators Project, The Journey Inside, Thunderbolt, Ultrabook, vPro
Inside, VTune, Xeon, Xeon Inside, X-GOLD, XMM, X-PMU and XPOSYS are trademarks of Intel Corporation in
the U.S. and/or other countries.
*Other names and brands may be claimed as the property of others.

    2
---------------------Page 3---------------------

                                                                                           Legal Information   
Microsoft, Windows, and the Windows logo are trademarks, or registered trademarks of Microsoft Corporation
in the United States and/or other countries.
Java is a registered trademark of Oracle and/or its affiliates.
Copyright© 2000-2014, Intel Corporation. All rights reserved.

                                                                                                         3
---------------------Page 4---------------------

 1    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Volume Overview                                                                           1

This manual describes the structure, operation and functions of the Intel® Integrated Performance Primitives
(Intel®    ) for Intel® architecture that operate on one-dimensional signals. The manual explains the
concepts of Intel    , as well as specific data type definitions and operation models used in the signal
processing domain, and provides detailed descriptions of the Intel     signal processing functions. The
functions are combined in groups by their functionality. Each group of functions is described in a separate
chapter (chapters 3 through 14).
For more information about signal processing concepts and algorithms, refer to the books and papers listed
in the Bibliography.

What's New
This Reference Manual documents Intel® Integrated Performance Primitives (Intel®    ) 8.1 release.

Notational Conventions
The code and syntax used in this manual for function and variable declarations are written in the ANSI C
style. However, versions of Intel     for different processors or operating systems may, of necessity, vary
slightly.
This manual uses the following notational conventions:
 Convention                         Explanation                       Example
 THIS TYPE STYLE                   Used in the text for the Intel     IPPI_MAX_64S
                                   constant identifiers.
 This type style                   Mixed with the uppercase in        IppLibraryVersion   ,
                                   structure names; also used in      void ippsFree()
                                   function names, code examples
                                   and call statements.
 This type style                   Parameters in function prototypes  value, srcStep
                                   and parameters description.
 x(n)  and x[n                     Used to represent a discrete 1D    x[n], 0 ≤ n< len
                                   signal. The notation x(n) refers
                                                                      Typically, the number of
                                   to a conceptual signal, while the
                                                                      elements in vectors is denoted by
                                   notation x[n] refers to an actual
                                                                      len. Vector names contain
                                   vector. Both of these are
                                                                      square brackets as distinct from
                                   annotated to indicate a specific
                                                                      vector elements with current
                                   finite range of values.
                                                                      index n.
                                                                      The expression pDst[n] =
                                                                      pSrc[n] + val  implies that each
                                                                      element pDst[n ] of the vector
                                                                      pDst is computed for each n in
                                                                      the range from 0 to len-1.
                                                                      Special cases are regarded and
                                                                      described separately.

    4
---------------------Page 5---------------------

                                                                             Volume Overview  1    

 Convention                       Explanation                      Example

 Ipp<data-domain>   and Ipp       All structures and enumerators,  IppsROI, IppLibraryVersion
 prefixes                         specific for a particular data-
                                  domain have the Ipp<data-
                                  domain>  prefix, while those
                                  common for entire Intel    
                                  software have the Ipp prefix.

See Also
Function Naming

                                                                                             5
---------------------Page 6---------------------

 2    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Intel® Integrated Performance

Primitives Concepts                                                                     2

This chapter explains the structure of the Intel® Integrated Performance Primitives (Intel®    ) software and
some of the basic concepts used in the signal processing part of Intel    . It also defines function naming
conventions in the manual, describes the supported data formats and operation modes.

Function Naming
Naming conventions for the Intel     functions are similar for all covered domains.
Function names in Intel     have the following general format:
ipp<data-domain   ><name>_<  datatype>[_<descriptor    >](<parameters>)
The elements of this format are explained in the sections that follow.

      NOTE
      In this manual, each function is introduced by its short name (without the ipps prefix and modifiers)
      and a brief description of its purpose.
      The ipps prefix in function names is always used in the code examples. In the text, this prefix is
      usually omitted when referring to the function group.

Data-Domain
The data-domain  element is a single character that denotes the group of functionality to which a given
function belongs. The main distinction among these groups is the type of input data. Intel     supports the
following data-domains:
 s              signal processing (input data is a 1D signal)
 i              images and video processing (input data is a 2D image)
 m              small matrix operations (input data is a matrix)
 r              realistic rendering functionality and 3D data processing (type of input data type depends
                on supported rendering techniques)
 g              operations on signals of the fixed length
For example, function names that begin with ipps signify that respective functions are used for signal
processing.

Name
The name element identifies what function does and has the following format:
<name > = <operation  >[_modifier  ]
The operation  component is one ore more words, acronyms, and abbreviations that describe the core
operation.
The modifier  component, if present, is a word or abbreviation that denotes a slight modification or variation
of the given function.

    6
---------------------Page 7---------------------

                                                     Intel® Integrated Performance Primitives Concepts  2 

For example, names without modifiers: Add, Threshold, FirGenLowPass  ; with modifiers:
ippsFFTInv_CToC  , Threshold_LT  .

Data Types
The datatype  field indicates data types used by the function, in the following format:
<bit depth><bit interpretation>     ,
where
bit depth = <1|8|16|32|64>
and
bit interpretation<u|    s|f>[  c]
Here u indicates “unsigned integer”, s indicates “signed integer”, f indicates “floating point”, and c indicates
“complex”.
Intel     supports the data types of the source and destination for signal processing functions listed in the
table below.

      NOTE
      In the lists of function parameters, the Ipp prefix is added to the data type. For example, 8-bit signed
      data is denoted as Ipp8s type. These Intel    -specific data types are defined in the respective library
      header files.

Data Types Supported by Intel     for Signal Processing
 Type            Usual C Type                                            Intel     Type
 8u             unsigned char                                            Ipp8u
 8s             signed char                                              Ipp8s
 16u            unsigned short                                           Ipp16u
 16s            signed short                                             Ipp16s
 16sc           complex short                                            Ipp16sc
 32u            unsigned int                                             Ipp32u
 32s            signed int                                               Ipp32s
 32f            float                                                    Ipp32f
 32fc           complex float                                            Ipp32fc
 64s            __int64   (Windows*) or long long (Linux*)               Ipp64s
 64f            double                                                   Ipp64f
 64fc           complex double                                           Ipp64fc
For functions that operate on a single data type, the datatype field contains only one of the values listed
above.
If a function operates on source and destination signals that have different data types, the respective data
type identifiers are listed in the function name in order of source and destination as follows:
<datatype> = <src1Datatype>[src2Datatype][dstDatatype]
For example, the function ippsDotProd_16s16sc_Sfs   computes the dot product of 16-bit short and 16-bit
complex short source vectors and stores the result in a 16-bit complex short destination vector. The
dstDatatype  modifier is not present in the name because the second operand and the result are of the
same type. The result is scaled and saturated.
There are several data types, namely 24u, 24s and 16f that are not supported by Intel    , but can be
readily converted to the supported data types for further processing by the library functions.

                                                                                                 7
---------------------Page 8---------------------

 2    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

For the unsigned 24u data, each vector element consists of three consecutive bytes represented as Ipp8u
data types. It has a little-endian byte order when a lower order byte is at the lower address. These data may
be converted to and from 32u  or 32f data types by using the appropriate flavors of the Intel     function
ippsConvert  .
For the signed 24s data, each vector element consists of three consecutive bytes represented as Ipp8u data
types. It has a little-endian byte order when a lower order byte is at the lower address. The sign is
represented by the most significant bit of the highest order byte. These data may be converted to and from
32s or 32f data types by using the appropriate flavors of the Intel     function ippsConvert.
For the 16f format, 16-bit floating point data (half type) can represent positive and negative numbers,
whose magnitude is between roughly  6.1e -5 and 6.5e 4, with a relative error of 9.8e-4 ; numbers smaller
than 6.1e-5 can be represented with an absolute error of 6.0e-8 . All integers from -2048 to +2048 can be
represented exactly.
The figure below illustrates the bit-layout for a half number:

 

 
s is the sign-bit, e is the exponent, and m is the significand.
These data may be converted to and from  16s  and 32f data types by using the appropriate flavors of the
Intel     function ippsConvert.

Descriptors
The descriptors   element further describes the operation. Descriptors are individual characters that indicate
additional details of the operation.
The following descriptors are used in signal processing functions:
 Descriptor            Description                                              Example

 I                                                                             ippsAdd_16s_I
                      Operation is in-place (default is not-in-place).

 Sfs                                                                           ippsConvert_16s8s_Sfs
                      Saturation and fixed scaling mode (default is saturation
                      and no scaling).

 P                                                                             ippsIIR_32f _P
                      Operation is performed for the specified number of
                      vectors.

If the function has more than one descriptor, they are presented in the function name in alphabetical order.
Many functions have no descriptors listed above. Such functions operate with the default behavior.

Parameters
The parameters   element specifies the function parameters (arguments).
The order of parameters is as follows:
•  All source operands. Constants follow vectors.
•  All destination operands. Constants follow vectors.

    8
---------------------Page 9---------------------

                                                      Intel® Integrated Performance Primitives Concepts  2 

• Other, operation-specific parameters.
A parameter name has the following conventions:
• All parameters defined as pointers start with p, defined as double pointers start with pp, for example,
  pPhase  , pSrc, ppState. All parameters defined as values start with a lowercase letter, for example, val,
  src , srcLen .
• Each new part of a parameter name starts with an uppercase character, without underscore; for example,
  pSrc , lenSrc , pDlyLine .
• Each parameter name specifies its functionality. Source parameters are named pSrc or src, in some
  cases followed by names or numbers, for example,  pSrc2 , srcLen. Output parameters are named  pDst
  or dst  followed by names or numbers, for example, pDst2 , dstLen. For in-place operations, the input/
  output parameter contains the name  pSrcDst  or srcDst .

Structures and Enumerators

This section describes the structures and enumerators used by Intel     for signal processing.

Library Version Structure
The IppLibraryVersion    structure describes the current Intel     software version. The main fields of this
structure are:
• integer fields major and minor, containing version numbers;
• integer field majorBuild, containing update number;
• integer field build, containing build revision number;
• string field Name, containing the Intel     version name, for example, “ippSB SSE4.1”;
• string field Version, containing the version description, for example, “7.1.0 (r93873)”.
• string field BuildDate, containing the build date.

Complex Data Structures
Complex numbers in Intel     are described by the structures that contains two numbers of the respective
data type. They are real and imaginary parts of the complex number. For example, a single precision
complex number is described by the Ipp32fc  structure as follows:
typedef struct {
     Ipp32f   re;
     Ipp32f  im;
 } Ipp32fc; 
The following complex data types are defined: Ipp16sc, Ipp32fc, Ipp64fc .

Function Context Structures
Some Intel     functions use special structures to store function-specific (context) information. For example,
the IppsFFTSpec  structure stores twiddle factors and bit reverse indexes needed in the fast Fourier
transform.
Two different kinds of structures are used:
• specification structures that are not modified during function operation; they have the suffix Spec in their
  names
• state structures that are modified during operation; they have the suffix State in their names.

                                                                                                  9
---------------------Page 10---------------------

 2    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

The function context interpretation is processor dependent. Therefore, these context-related structures are
not defined in the public headers, and their fields are not accessible. Intel     provides no option of
modifying these structures or creating a function context as an automatic variable.

Enumerators
The IppStatus  constant enumerates the status values returned by the Intel     functions, indicating
whether the operation is error-free. See section Error Reporting in this chapter for more information on the
set of valid status values and corresponding error messages for signal processing functions.
The IppCmpOp  enumeration defines the type of relational operator to be used by threshold functions:
    typedef enum {
        ippCmpLess,
        ippCmpLessEq,
        ippCmpEq,
        ippCmpGreaterEq,
        ippCmpGreater
    } IppCmpOp;

The IppRoundMode  enumeration defines the rounding mode to be used by conversion functions:
typedef enum {
    ippRndZero,
    ippRndNear,
    ippRndFinancial
} IppRoundMode;

The IppHintAlgorithm   enumeration defines the type of code to be used in some operations: faster but less
accurate, or vice-versa, more accurate but slower. For more information on using this enumeration, see Hint
Arguments.
typedef enum {
    ippAlgHintNone,
    ippAlgHintFast,
    ippAlgHintAccurate
} IppHintAlgorithm;

The IppCpuType  enumerates processor types returned by the ippGetCpuType function:
typedef enum {
 /* Enumeration:           Processor:                                */
    ippCpuUnknown = 0x0,
    ippCpuPP,           /* Intel(R) Pentium(R) processor             */
    ippCpuPMX,          /* Pentium(R) processor  
                           with MMX(TM) technology                   */
    ippCpuPPR,          /* Pentium(R) Pro processor                  */
    ippCpuPII,          /* Pentium(R) II  processor                  */
    ippCpuPIII,         /* Pentium(R) III processor 
                           and Pentium(R)III Xeon(R) processor       */
    ippCpuP4,           /* Pentium(R) 4 processor
                           and Intel(R) Xeon(R) processor            */
    ippCpuP4HT,         /* Pentium(R) 4 processor with HT Technology */
    ippCpuP4HT2,        /* Pentium(R) 4 processor with 
                                     Streaming SIMD Extensions 3     */
    ippCpuCentrino,     /* Intel(R) Centrino(R) processor technology   */
    ippCpuCoreSolo,     /* Intel(R) Core(TM) Solo processor          */
    ippCpuCoreDuo,      /* Intel(R) Core(TM) Duo processor           */
    ippCpuITP   = 0x10, /* Intel(R) Itanium(R) processor             */
    ippCpuITP2          /* Intel(R) Itanium(R) 2 processor           */
    ippCpuEM64T = 0x20, /* Intel(R) 64 Instruction Set 
                                         Architecture(ISA)           */
    ippCpuC2D,          /* Intel(R) Core(TM) 2 Duo processor         */

   10
---------------------Page 11---------------------

                                                   Intel® Integrated Performance Primitives Concepts  2 

    ippCpuC2Q,          /* Intel(R) Core(TM) 2 Quad processor        */
    ippCpuPenryn,     /* Intel(R) Core(TM) 2 processor with 
                                    Intel(R) SSE4.1                  */
    ippCpuBonnell,                  /* Intel(R) Atom (TM) processor */
    ippCpuNehalem,      /* Intel (R) Core(TM) i7 processor
    ippCpuNext,
    ippCpuSSE   = 0x40, /* Processor supports Pentium(R) III 
                           processor instruction set                 */
    ippCpuSSE2,         /* Processor supports Streaming SIMD 
                           Extensions 2 instruction set              */
    ippCpuSSE3,         /* Processor supports Streaming SIMD 
                            Extensions 3 instruction set             */
    ippCpuSSSE3,        /* Processor supports Supplemental Streaming
                           SIMD Extensions 3 instruction set         */
    ippCpuSSE41,        /* Processor supports Streaming SIMD 
                            Extensions 4.1 instruction set           */
    ippCpuSSE42,        /* Processor supports Streaming SIMD 
                            Extensions 4.2 instruction set           */
    ippCpuAVX,        /* Processor supports Intel(R) Advanced Vector 
                            Extensions instruction set               */
    ippCpuAES,        /* Processor supports Intel(R) AES 
                            new instructions                         */
ippCpuX8664 = 0x60,   /* Processor supports 64 bit extension         */
} IppCpuType; 

 Optimization Notice

 Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for
 optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and
 SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or
 effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-
 dependent optimizations in this product are intended for use with Intel microprocessors. Certain
 optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to
 the applicable product User and Reference Guides for more information regarding the specific instruction
 sets covered by this notice.
 Notice revision #20110804

The IppWinType  enumeration defines the type of window to be used by the FIR filter coefficient generating
functions:
typedef enum {
    ippWinBartlett,
    ippWinBlackman,
    ippWinHamming,
    ippWinHann,
    ippWinRect
} IppWinType;

The IppLZ77ComprLevel   enumeration defines the compression level to be used by the ZLIB data
compression functions:
typedef enum { 
    IppLZ77FastCompr,
    IppLZ77AverageCompr,
    IppLZ77BestCompr
} IppLZ77ComprLevel;

                                                                                             11
---------------------Page 12---------------------

 2    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

The IppLZ77Chcksm  enumeration defines what algorithm is used to compute the checksum by the ZLIB data
compression functions:
typedef enum {

    IppLZ77NoChcksm,

    IppLZ77Adler32,

    IppLZ77CRC32

} IppLZ77Chcksm;

The IppLZ77Flush  enumeration defines what encoding mode is used by the ZLIB data compression
functions:
typedef enum {

    IppLZ77NoFlush,

    IppLZ77SyncFlush,

    IppLZ77FullFlush,

    IppLZ77FinishFlush

} IppLZ77Flush;

The IppLZ77DeflateStatus   enumeration defines the encoding status that is used by the ZLIB data
compression functions:
typedef enum {

    IppLZ77StatusInit,

    IppLZ77StatusLZ77Process,

    IppLZ77StatusHuffProcess,

    IppLZ77StatusFinal

} IppLZ77DeflateStatus;

The IppLZ77InflateStatus   enumeration defines the decoding status that is used by the ZLIB data
compression functions:
typedef enum {

    IppLZ77InflateStatusInit,

    IppLZ77InflateStatusHuffProcess

    IppLZ77InflateStatusLZ77Process,

    IppLZ77InflateStatusFinal

} IppLZ77InflateStatus;

The IppLZ77HuffMode  enumeration defines the encoding mode that is used by the ZLIB data compression
functions:
typedef enum {

    IppLZ77UseFixed,

    IppLZ77UseDynamic,

    IppLZ77UsedStored

} IppLZ77HuffMode;

   12
---------------------Page 13---------------------

                                                   Intel® Integrated Performance Primitives Concepts  2 

The IppInflateState  enumeration defines the decoding parameters that are used by the ZLIB data
compression functions:
typedef struct IppInflateState {

  const Ipp8u* pWindow;        // pointer to the sliding window

                                 // (the dictionary for the LZ77 algorithm)

  unsigned int winSize;          // size of the sliding window

  unsigned int tableType;       // type of Huffman code tables

                                 // (for example, 0 - tables for 
Fixed                                                  //  Huffman codes)

  unsigned int tableBufferSize;  //(ENOUGH = 2048) * (sizeof(code) = 4) -

                                              // sizeof(IppInflateState)

} IppInflateState;

The IppInflateMode  enumeration defines the decode mode that is used by the ZLIB data compression
functions:
typedef enum {

  ippTYPE,

  ippLEN,

  ippLENEXT

} IppInflateMode;

The IppGITStrategyHint   enumeration defines which strategy of encoding is used in some operations by
the GIT data compression functions:
typedef enum {

    ippGITNoStrategy,

    ippGITLeftReorder,

    ippGITRightReorder,

    ippGITFixedOrder

} IppGITStrategyHint;

The IppAffinityType  enumeration defines which affinity type is used by the core function ippSetAffinity:
typedef enum {

    ippAffinityCompactFineCore,

    ippAffinityCompactFineHT,

    ippAffinityCompactAllEnabled,

    ippAffinityCompactRestore,

    ippTstAffinityCompactFineCore,

    ippTstAffinityCompactFineHT

} IppAffinityType;

The IppEnum enumeration defines the configuration of the algorithm for some functions:
typedef int IppEnum;

                                                                                            13
---------------------Page 14---------------------

 2    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

The IppAlgType  enumeration defines the type of the algorithm implementation:
typedef enum {
    ippAlgAuto     = 0x00000000, // default
    ippAlgDirect   = 0x00000001,
    ippAlgFFT      = 0x00000002,
    ippAlgMask    = 0x000000FF,
} IppAlgType;

The IppsNormOp  enumeration defines the type of normalization that should be applied to the output data:
typedef enum {
    ippsNormNone  = 0x00000000,// default
    ippsNormA        = 0x00000100,// biased normalization
    ippsNormB        = 0x00000200,// unbiased normalization
    ippsNormMask  = 0x0000FF00,
} IppsNormOp;

Data Ranges

The range of values that can be represented by each data type lies between the lower and upper bounds.
The following table lists data ranges and constant identifiers used in Intel     to denote the respective range
bounds:
Data Types and Ranges
 Data      Lower Bound                                  Upper Bound
 Type
           Identifier          Value                    Identifier          Value
 8s        IPP_MIN_8S          -128                    IPP_MAX_8S          127
 8u                            0                       IPP_MAX_8U          255
 16s       IPP_MIN_16S         -32768                  IPP_MAX_16S         32767
 16u                           0                       IPP_MAX_16U         65535
 32s       IPP_MIN_32S         -231                    IPP_MAX_32S         231 -1
 32u                           0                       IPP_MAX_32U         232 -1
 32f †     IPP_MINABS_32F      1.175494351e-38         IPP_MAXABS_32F      3.402823466e38
 64s       IPP_MIN_64S         -263                    IPP_MAX_64S         263 -1
 64f †     IPP_MINABS_64F      2.2250738585072014e-308 IPP_MAXABS_64F      1.7976931348623158e308

† The range for absolute values.

Data Alignment

Intel     is built using the compiler option /Zp16, which aligns the structure fields on the field size or 16
bytes if the size is greater than 16.
You can also use the ippsMalloc function to align the allocated memory pointer on 32 bytes.

Rounding Mode

General signal processing functions use rounding. The default rounding mode is nearest even, that is the
fixed point number x=N + α, 0 ≤ α < 1, where N is an integer number, is rounded as given by:
 

   14
---------------------Page 15---------------------

                                                       Intel® Integrated Performance Primitives Concepts  2 

 
For example, 1.5 will be rounded to 2 and 2.5 to 2.
Some functions have additional rounding modes, which are set by the parameter roundMode  .

      Important
      •     Functions for data compression, data integrity, string processing and fixed-accuracy arithmetic do
         not perform rounding.
      •     Functions for speech coding have special rounding modes.

See Also
Rounding Modes for Speech Codecs

Integer Scaling

Some signal processing functions operating on integer data use scaling of the internally computed output
results by the integer scaleFactor, which is specified as one of the function parameters. These functions
have the Sfs descriptor in their names.
The scale factor can be negative, positive, or zero. Scaling is applied because internal computations are
generally performed with a higher precision than the data types used for input and output signals.

      NOTE
      The result of integer operations is always saturated to the destination data type range.

Scaling of an integer result is done by multiplying the output vector values by 2-scaleFactor before the
function returns. This helps retain either the output data range or its precision. Usually the scaling with a
positive factor is performed by the shift operation. The result is rounded off to the nearest even integer
number (see "Rounding Mode").
For example, the integer Ipp16s result of the square operation ippsSqr for the input value 200 is equal to
32767 instead of 40000, that is, the result is saturated and the exact value can not be restored.
The scaling of the output value with the factor scaleFactor = 1 yields the result 20000, which is not
saturated, and the exact value can be restored as 20000*2. Thus, the output data range is retained.
The following example shows how the precision can be partially retained by means of scaling.
The integer square root operation ippsSqrt (without scaling) for the input value 2 gives the result equal to
1 instead of 1.414. Scaling of the internally computed output value with the factor scaleFactor = -3 gives
the result 11, and permits to restore the more precise value as 11*2 -3 = 1.375.

See Also
Rounding Mode

Error Reporting

The Intel     functions return the status of the performed operation to report errors and warnings to the
calling program. The last value of the error status is not stored, and you need to decide whether to check it
or not as the function returns. The status values are of the IppStatus type and are global constant integers.
The following table lists status codes and corresponding messages reported by Intel     for signal processing.
Error Status Values and Messages 
 Status                                          Message
 ippStsCpuNotSupportedErr                        The target cpu is not supported.
 ippStsPointAtInfinity                           Point at infinity is detected.

                                                                                                    15
---------------------Page 16---------------------

 2    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

 ippStsI18nUnsupportedErr                       Internationalization (i18n) is not supported.
 ippStsI18nMsgCatalogOpenErr                    Message Catalog cannot be opened. For detailed information,
                                                use errno  on Linux* OS and GetLastError  on Windows*
                                                OS.
 ippStsI18nMsgCatalogCloseErr                   Message Catalog cannot be closed. For detailed information, use
                                                errno   on Linux* OS and GetLastError  for Windows* OS.
 ippStsUnknownStatusCodeErr                     Unknown status code.
 ippStsOFBSizeErr                               Wrong value for crypto OFB block size.
 ippStsLzoBrokenStreamErr                       LZO safe decompression function cannot decode LZO stream.
 ippStsRoundModeNotSupportedErr                 Rounding mode is not supported.
 ippStsMaxLenHuffCodeErr                        Huff: Max length of the Huffman code is more than the expected
                                                one.
 ippStsCodeLenTableErr                          Huff: Invalid codeLenTable.
 ippStsFreqTableErr                             Huff: Invalid freqTable.
 ippStsRegExpOptionsErr                         RegExp: Options for the pattern are incorrect.
 ippStsRegExpErr                                RegExp: The structure pRegExpState  contains wrong data.
 ippStsRegExpMatchLimitErr                      RegExp: The match limit has been exhausted.
 ippStsRegExpQuantifierErr                      RegExp: Incorrect quantifier.
 ippStsRegExpGroupingErr                        RegExp: Incorrect grouping.
 ippStsRegExpBackRefErr                         RegExp: Incorrect back reference.
 ippStsRegExpChClassErr                         RegExp: Incorrect character class.
 ippStsRegExpMetaChErr                          RegExp: Icnorrect metacharacter.
 ippStsMP3FrameHeaderErr                        Error in fields of the IppMP3FrameHeader structure.
 ippStsMP3SideInfoErr                           Error in fields of the IppMP3SideInfo structure.
 ippStsAacPrgNumErr                             AAC: Invalid number of elements for one program.
 ippStsAacSectCbErr                             AAC: Invalid section codebook.
 ippStsAacSfValErr                              AAC: Invalid scalefactor value.
 ippStsAacCoefValErr                            AAC: Invalid quantized coefficient value.
 ippStsAacMaxSfbErr                             AAC: Invalid coefficient index.
 ippStsAacPredSfbErr                            AAC: Invalid predicted coefficient index.
 ippStsAacPlsDataErr                            AAC: Invalid pulse data attributes.
 ippStsAacGainCtrErr                            AAC: Gain control is not supported.
 ippStsAacSectErr                               AAC: Invalid number of sections.
 ippStsAacTnsNumFiltErr                         AAC: Invalid number of TNS filters.
 ippStsAacTnsLenErr                             AAC: Invalid length of TNS region.
 ippStsAacTnsOrderErr                           AAC: Invalid order of TNS filter.
 ippStsAacTnsCoefResErr                         AAC: Invalid bit-resolution for TNS filter coefficients.
 ippStsAacTnsCoefErr                            AAC: Invalid coefficients of TNS filter.
 ippStsAacTnsDirectErr                          AAC: Invalid direction of TNS filter.
 ippStsAacTnsProfileErr                         AAC: Invalid TNS profile.
 ippStsAacErr                                   AAC: Internal error.
 ippStsAacBitOffsetErr                          AAC: Invalid current bit offset in bitstream.
 ippStsAacAdtsSyncWordErr                       AAC: Invalid ADTS syncword.
 ippStsAacSmplRateIdxErr                        AAC: Invalid sample rate index.
 ippStsAacWinLenErr                             AAC: Invalid window length (not short or long).
 ippStsAacWinGrpErr                             AAC: Invalid number of groups for current window length.
 ippStsAacWinSeqErr                             AAC: Invalid window sequence range.
 ippStsAacComWinErr                             AAC: Invalid common window flag.
 ippStsAacStereoMaskErr                         AAC: Invalid stereo mask.
 ippStsAacChanErr                               AAC: Invalid channel number.
 ippStsAacMonoStereoErr                         AAC: Invalid mono-stereo flag.
 ippStsAacStereoLayerErr                        AAC: Invalid Stereo Layer flag.

   16
---------------------Page 17---------------------

                                                       Intel® Integrated Performance Primitives Concepts  2 

ippStsAacMonoLayerErr                            AAC: Invalid Mono Layer flag.
ippStsAacScalableErr                             AAC: Invalid scalable object flag.
ippStsAacObjTypeErr                              AAC: Invalid audio object type.
ippStsAacWinShapeErr                             AAC: Invalid window shape.
ippStsAacPcmModeErr                              AAC: Invalid PCM output interleaving indicator.
ippStsVLCUsrTblHeaderErr                         VLC: Invalid header inside table.
ippStsVLCUsrTblUnsupportedFmtErr                 VLC: Table format is not supported.
ippStsVLCUsrTblEscAlgTypeErr                     VLC: Ecs-algorithm is not supported.
ippStsVLCUsrTblEscCodeLengthErr                  VLC: Esc-code length inside table header is incorrect.
ippStsVLCUsrTblCodeLengthErr                     VLC: Code length inside table is incorrect.
ippStsVLCInternalTblErr                          VLC: Invalid internal table.
ippStsVLCInputDataErr                            VLC: Invalid input data.
ippStsVLCAACEscCodeLengthErr                     VLC: Invalid AAC-Esc code length.
ippStsIncorrectLSPErr                            Incorrect values for linear spectral pair.
ippStsNoRootFoundErr                             No roots are found for equation.
ippStsLengthErr                                  Incorrect value for string length.
ippStsFBankFreqErr                               Incorrect value for the filter bank frequency parameter.
ippStsFBankFlagErr                               Incorrect value for the filter bank parameter.
ippStsFBankErr                                   Filter bank is not correctly initialized.
ippStsNegOccErr                                  Ocupation count is negative.
ippStsCdbkFlagErr                                Incorrect value for the codebook flag parameter.
ippStsSVDCnvgErr                                 No convergence of the SVD algorithm.
ippStsToneMagnErr                                Tone magnitude is less than or equal to zero.
ippStsToneFreqErr                                Tone frequency is negative, or greater than or equal to 0.5.
ippStsTonePhaseErr                               Tone phase is negative, or greater than or equal to 2*PI.
ippStsTrnglMagnErr                               Triangle magnitude is less than or equal to zero.
ippStsTrnglFreqErr                               Triangle frequency is negative, or greater than or equal to 0.5.
ippStsTrnglPhaseErr                              Triangle phase is negative, or greater than or equal to 2*PI.
ippStsTrnglAsymErr                               Triangle asymmetry is less than -PI, or greater than or equal to
                                                 PI.
ippStsHugeWinErr                                 The Kaiser window is too big.
ippStsJaehneErr                                  Magnitude value is negative.
ippStsStepErr                                    Step value is not valid.
ippStsDlyLineIndexErr                            Invalid value for the delay line sample index.
ippStsStrideErr                                  Stride value is less than length of the row.
ippStsEpsValErr                                  Negative epsilon value.
ippStsScaleRangeErr                              Scale bounds are out of range.
ippStsThresholdErr                               Invalid threshold bounds.
ippStsWtOffsetErr                                Invalid offset value for wavelet filter.
ippStsAnchorErr                                  Anchor point is outside the mask.
ippStsMaskSizeErr                                Invalid mask size.
ippStsShiftErr                                   Shift value is less than zero.
ippStsSampleFactorErr                            Sampling factor is less than or equal to zero.
ippStsSamplePhaseErr                             Phase value is out of range, 0 ≤ phase < factor.
ippStsFIRMRFactorErr                             MR FIR sampling factor is less than or equal to zero.
ippStsFIRMRPhaseErr                              MR FIR sampling phase parameter is negative, or greater than
                                                 or equal to the sampling factor.
ippStsRelFreqErr                                 Relative frequency value is out of range.
ippStsFIRLenErr                                  Length of the FIR filter is less than or equal to zero.
ippStsIIROrderErr                                Order of the IIR filter is not valid.
ippStsResizeFactorErr                            Resize factor(s) is less than or equal to zero.
ippStsDivByZeroErr                               An attempt to divide by zero.

                                                                                                     17
---------------------Page 18---------------------

 2    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

 ippStsInterpolationErr                           Invalid interpolation mode.
 ippStsMirrorFlipErr                              Invalid flip mode.
 ippStsMoment00ZeroErr                            Moment value M(0,0) is too small to continue calculations.
 ippStsThreshNegLevelErr                          Negative value of the level in the threshold operation.
 ippStsContextMatchErr                            Context parameter does not match the operation.
 ippStsFftFlagErr                                 Invalid value for the FFT flag parameter.
 ippStsFftOrderErr                                Invalid value for the FFT order parameter.
 ippStsMemAllocErr                                Not enough memory for the operation.
 ippStsNullPtrErr                                 Null pointer error.
 ippStsSizeErr                                    Incorrect value for data size.
 ippStsBadArgErr                                  Incorrect argument/parameter of the function.
 ippStsErr                                        Unknown/unspecified error.
 ippStsNoErr                                      No errors.
 ippStsNoOperation                                No operation has been executed.
 ippStsMisalignedBuf                              Misaligned pointer in operation in which it must be aligned.
 ippStsSqrtNegArg                                 Negative value(s) of the argument in the function Sqrt.
 ippStsInvByZero                                  INF result. Zero value was met by InvThresh with zero level.
 ippStsEvenMedianMaskSize                         Even size of the Median Filter mask was replaced by the odd
                                                  one.
 ippStsDivByZero                                  Zero value(s) of the divisor in the function Div.
 ippStsLnZeroArg                                  Zero value(s) of the argument in the function Ln.
 ippStsLnNegArg                                   Negative value(s) of the argument in the function Ln.
 ippStsNanArg                                     Argument value is not a number.
 ippStsResFloor                                   All result values are floored.
 ippStsOverflow                                   Overflow in the operation.
 ippStsZeroOcc                                    Zero occupation count.
 ippStsUnderflow                                  Underflow in the operation.
 ippStsSingularity                                Singularity in the operation.
 ippStsDomain                                     Argument is out of the function domain.
 ippStsNotIntelCpu                                The target cpu is not Genuine Intel.
 ippStsCpuMismatch                                Cannot set the library for the given cpu.
 ippStsNotIppFunctionFound                        Application does not contain     function calls.
 ippStsDllNotFoundBestUsed                        Dispatcher cannot find the newest version of     DLLs.
 ippStsNoOperationInDll                           The function does nothing in the dynamic version of the library.
 ippStsOvermuchStrings                            Number of destination strings is more than expected.
 ippStsOverlongString                             Length of one of the destination strings is more than expected.
 ippStsSrcSizeLessExpected                        DC: The size of source buffer is less than the expected one.
 ippStsDstSizeLessExpected                        DC: The size of destination buffer is less than the expected one.
 ippStsNotSupportedCpu                            The CPU is not supported.
 ippStsUnkhownCacheSize                           The CPU is supported, but the size of the cache is unknown.
 ippStsAlgTypeErr                                 The algorithm type is not supported.

*)

 Optimization Notice

 Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for
 optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and
 SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or
 effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-
 dependent optimizations in this product are intended for use with Intel microprocessors. Certain
 optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to
 the applicable product User and Reference Guides for more information regarding the specific instruction
 sets covered by this notice.

    18
---------------------Page 19---------------------

                                                     Intel® Integrated Performance Primitives Concepts  2 

 Optimization Notice

 Notice revision #20110804

The status codes ending with Err (except for the ippStsNoErr status) indicate an error; the integer values
of these codes are negative. When an error occurs, the function execution is interrupted. All other status
codes indicate warnings. When a specific case is encountered, the function execution is completed and the
corresponding warning status is returned.
For example, if the integer function ippsDiv_8u meets an attempt to divide a positive value by zero, the
function execution is not interrupted. The result of the operation is set to the maximum value that can be
represented by the source data type, and the function returns the warning status ippStsDivByZero. This is
the case for the vector-vector operation ippsDiv. For the vector-scalar division operation ippsDivC, the
function behavior is different: if the constant divisor is zero, then the function stops execution and returns
immediately with the error status ippStsDivByZeroErr.

Code Examples

The manual contains a number of code examples that use the Intel     functions. These examples show both
some particular features of the primitives and how the primitives can be called. Many of these code examples
output result data together with the status code and associated messages in case of an error or a warning
condition.
To keep the example code simpler, special definitions of print statements are used that get output strings
look exactly the way it is needed for better representation of results of different format, as well as print
status codes and messages.
The code definitions given below make it possible to build the examples contained in the manual by
straightforward copying and pasting the example code fragments.
/// the functions providing simple output of the result
/// they are for real and complex data

#define genPRINT(TYPE,FMT) \
void printf_##TYPE(const char* msg, Ipp##TYPE* buf, int len, IppStatus st ) { \
   int n; \
   if( st > ippStsNoErr ) \
      printf( "-- warning %d, %s\n", st, ippGetStatusString( st )); \
   else if( st < ippStsNoErr ) \
      printf( "-- error %d, %s\n", st, ippGetStatusString( st )); \
   printf(" %s ", msg ); \
   for( n=0; n<len; ++n ) printf( FMT, buf[n] ); \
   printf("\n" ); \
}

#define genPRINTcplx(TYPE,FMT) \
void printf_##TYPE(const char* msg, Ipp##TYPE* buf, int len, IppStatus st ) { \
   int n; \
   if( st > ippStsNoErr ) \
      printf( "-- warning %d, %s\n", st, ippGetStatusString( st )); \
   else if( st < ippStsNoErr ) \
      printf( "-- error %d, %s\n", st, ippGetStatusString( st )); \
   printf(" %s ", msg ); \
   for( n=0; n<len; ++n ) printf( FMT, buf[n].re, buf[n].im ); \
   printf("\n" ); \
}
genPRINT( 64f, " %f" )
genPRINT( 32f, " %f" )
genPRINT( 16s, " %d" )

                                                                                                19
---------------------Page 20---------------------

 2    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing
genPRINTcplx( 64fc, " {%f,%f}" )
genPRINTcplx( 32fc, " {%f,%f}" )
genPRINTcplx( 16sc, " {%d,%d}" )

   20
---------------------Page 21---------------------

Support Functions                                                                        3

This chapter describes Intel®
                               support functions. Use these functions to:
•     Retrieve information about the current Intel     software version
•     Allocate and free memory that is needed for the operation of other Intel     functions
•     Retrieve information about the processor and perform specific auxiliary operations
•     Perform internationalization

Version Information Functions
These functions return the version number and other information about the active Intel     software.

GetLibVersion
Returns information about the active version of the
Intel     signal processing software.

Syntax
const IppLibraryVersion* ippsGetLibVersion(void);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Description
This function returns a pointer to a static data structure IppLibraryVersion that contains information
about the current version of the Intel     software for signal processing. There is no need for you to release
memory referenced by the returned pointer, as it points to a static variable. The following fields of the
IppLibraryVersion   structure are available:
major                         Major number of the current library version.

minor                         Minor number of the current library version.

majorBuild                    Update number.

build                         Build revision number.

Name                          Name of the current library version.

Version                       Library version string.

BuildDate                     Library version actual build date.

For example, if the library version is “7.1 ”, build revision number is “93873”, library name is “ippAC
SSE4.1”, and build date is “Apr 2 2012”, then the fields in this structure are set as:

                                                                                                21
---------------------Page 22---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

major = 7, minor = 1, Name = ippAC SSE4.1”, Version = “7.1.0 (r93873)”, BuildDate = “Apr 2 2012”

     NOTE
     Each sub-library in the signal processing domain has its own similar function to retrieve information
     about the active library version. Version information functions for sub-libraries have the same
     interface as ippsGetLibVersion .

The following table provides the list of version information functions and respective header files where these
functions are declared:
 Function Name                                     Header File

 ippGetLibVersion                                 ippcore.h

 ippacGetLibVersion                               ippac.h

 ippccGetLibVersion                               ippcc.h

 ippcvGetLibVersion                               ippcv.h

 ippchGetLibVersion                               ippch.h

 ippdcGetLibVersion                               ippdc.h

 ippdiGetLibVersion                               ippdi.h

 ippgenGetLibVersion                              ippgen.h

 ippscGetLibVersion                               ippsc.h

 ipprGetLibVersion                                ippr.h

 ippvmGetLibVersion                               ippvm.h

 ippmGetLibVersion                                ippm.h

 ippvcGetLibVersion                               ippvc.h

     NOTE
     Functions ippdiGetLibVersion  , ipprGetLibVersion  , and ippgenGetLibVersion  are deprecated.
     These functions are obsolete and will be removed in a future release. Use the following link for details:
     http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.

Example
The following example shows how to use the ippsGetLibVersion function :
void libinfo(void) {
       const IppLibraryVersion*
lib = ippsGetLibVersion();
       printf(“%s %s %d.%d.%d.%d\n”,
lib->Name, lib->Version, 
           lib->major,
lib->minor, lib->majorBuild, lib->build); 
}
Output: 
    ippsv8_1.lib 7.0 build 205.68

   22
---------------------Page 23---------------------

                                                                         Support Functions  3 

Memory Allocation Functions

This section describes the Intel     signal processing functions that allocate aligned memory blocks for data
of required type or free the previously allocated memory. The size of allocated memory is specified by the
number of allocated elements len.

     NOTE
     Use the ippsFree() to free memory allocated by ippsMalloc(). Use free to free memory allocated
     by malloc or calloc.

Malloc
Allocates memory aligned to 64-byte boundary.

Syntax
Ipp8u* ippsMalloc_8u(int len );
Ipp16u* ippsMalloc_16u(int len  );
Ipp32u* ippsMalloc_32u(int len  );
Ipp8s* ippsMalloc_8s(int len );
Ipp16s* ippsMalloc_16s(int len  );
Ipp32s* ippsMalloc_32s(int len  );
Ipp64s* ippsMalloc_64s(int len  );
Ipp32f* ippsMalloc_32f(int len  );
Ipp64f* ippsMalloc_64f(int len  );
Ipp8sc* ippsMalloc_8sc(int len  );
Ipp16sc* ippsMalloc_16sc(int len  );
Ipp32sc* ippsMalloc_32sc(int len  );
Ipp64sc* ippsMalloc_64sc(int len  );
Ipp32fc* ippsMalloc_32fc(int len  );
Ipp64fc* ippsMalloc_64fc(int len  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

len                         Number of elements to allocate.

Description
This function allocates memory block aligned to 64-byte boundary for elements of different data types.

                                                                                        23
---------------------Page 24---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Example
The following example shows how to use theippsMalloc_8u function:
void func_malloc(void) 
{    
    Ipp8u* pBuf = ippsMalloc_8u(8*sizeof(Ipp8u));
    if(NULL == pBuf)
      // not enough memory

    ippsFree(pBuf); 
}

Return Values
The return value of ippsMalloc is a pointer to an aligned memory block. If no memory is available in the
system, then the NULL value is returned. To free this block, use the ippsFree function.

See Also
Free Frees memory allocated by the function  ippsMalloc .

Free
Frees memory allocated by the function ippsMalloc.

Syntax
void ippsFree(void* ptr   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

ptr                          Pointer to a memory block to be freed. The memory block pointed to
                             with ptr  is allocated by the function ippsMalloc.

Description
This function frees the aligned memory block allocated by the function ippsMalloc.

     NOTE
     Use the ippsFree()  to free memory allocated by ippsMalloc(). Use free to free memory allocated
     by malloc  or calloc.

Common Functions

This section describes the Intel     functions that perform special operations common for all domains. All
these functions are grouped in the separate sub-library called ippcore.

   24
---------------------Page 25---------------------

                                                                               Support Functions  3  

GetStatusString
Translates a status code into a message.

Syntax
const char* ippGetStatusString(IppStatus stsCode       );

Include Files
ippcore.h

Parameters

stsCode                       Code that indicates the status type (see Error Status Values and
                              Messages).

Description
This function returns a pointer to the text string associated with a status code of IppStatus type . Use this
function to produce error and warning messages for users. The returned pointer is a pointer to an internal
static buffer and does not need to be released.

Example
The following code example shows how to use the function ippGetStatusString. If you call an Intel    
function ippsAddC_16s_I  with a NULL pointer, it returns an error code -8. The status information function
translates this code into the corresponding message “Null Pointer Error”.
void statusinfo(void) {
       IppStatus st = ippsAddC_16s_I (3, 0, 0);
       printf(“%d : %s\n”, st, ippGetStatusString(st)); 
}    
Output:
-8, Null Pointer Error

GetCpuType
Returns a processor type.

Syntax
IppCpuType ippGetCpuType (void);

Include Files
ippcore.h

Description
This function detects the processor type used in your computer system and returns an appropriate
IppCpuType  variable value. The following table lists possible values and their meaning.

      NOTE
      This function returns only the type of the processor. If you need more information about processor
      features use the function GetCpuFeatures instead.

                                                                                               25
---------------------Page 26---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Processor Type Detected in Intel    
 Returned Variable Value                             Processor Type

 ippCpuPP                                                ®        ®
                                                     Intel  Pentium  processor
 ippCpuPMX                                               ®        ®
                                                     Intel  Pentium  processor with MMXTM technology
 ippCpuPPR                                               ®        ®
                                                     Intel  Pentium  Pro processor
 ippCpuPII                                               ®        ®
                                                     Intel  Pentium  II processor
 ippCpuPIII                                              ®        ®                    ®        ®
                                                     Intel  Pentium  III processor or Intel  Pentium  III
                                                         ®
                                                     Xeon  processor
 ippCpuP4                                                ®        ®                  ®     ®
                                                     Intel  Pentium 4 processor or Intel  Xeon  processor
 ippCpuP4HT                                              ®        ®
                                                     Intel  Pentium 4 processor with Hyper-Threading
                                                     Technology
 ippCpuP4HT2                                             ®        ®                    ®
                                                     Intel  Pentium 4 processor with Intel  Streaming
                                                     SIMD Extensions 3
 ippCpuCentrino                                          ®        ®
                                                     Intel  Centrino  processor technology
 ippCpuCoreSolo                                          ®
                                                     Intel  CoreTM Solo processor
 ippCpuCoreDuo                                           ®
                                                     Intel  CoreTM Duo processor
 ippCpuITP                                               ®        ®
                                                     Intel  Itanium  processor
 ippCpuITP2                                              ®        ®
                                                     Intel  Itanium 2 processor
 ippCpuEM64T                                             ®
                                                     Intel  64 instruction set architecture
 ippCpuC2D                                               ®
                                                     Intel  CoreTM2 Duo processor
 ippCpuC2Q                                               ®
                                                     Intel  CoreTM2 Quad processor
 ippCpuPenryn                                            ®                           ®
                                                     Intel  CoreTM2 processor with Intel  Streaming
                                                     SIMD Extensions 4.1
 ippCpuBonnell                                           ®
                                                     Intel  AtomTM processor
 ippCpuNehalem                                           ®
                                                     Intel  CoreTM i7 processor
 ippCpuSSE                                                             ®
                                                     Processor with Intel  Streaming SIMD Extensions
                                                     instruction set
 ippCpuSSE2                                                            ®
                                                     Processor with Intel  Streaming SIMD Extensions 2
                                                     instruction set
 ippCpuSSE3                                                            ®
                                                     Processor with Intel  Streaming SIMD Extensions 3
                                                     instruction set
 ippCpuSSSE3                                                                         ®
                                                     Processor with Supplemental Intel  Streaming SIMD
                                                     Extensions 3 instruction set
 ippCpuSSE41                                                           ®
                                                     Processor with Intel  Streaming SIMD Extensions
                                                     4.1instruction set
 ippCpuSSE42                                                           ®
                                                     Processor with Intel  Streaming SIMD Extensions
                                                     4.2 instruction set

   26
---------------------Page 27---------------------

                                                                              Support Functions  3   

 Returned Variable Value                           Processor Type
 ippCpuAVX                                                               ®
                                                   Processor supports Intel  Advanced Vector
                                                   Extensions instruction set
 ippCpuX8664                                       Processor supports 64 bit extension
 ippCpuUnknown                                     Unknown processor

GetCpuClocks
Returns a current value of the time stamp counter
(TSC) register.

Syntax
Ipp64u ippGetCpuClocks (void);

Include Files
ippcore.h

Description
This function reads the current state of the TSC register and returns its value.

GetCpuFreqMhz
Estimates the processor operating frequency.

Syntax
IppStatus ippGetCpuFreqMhz(int* pMhz     );

Include Files
ippcore.h

Parameters

pMhz                          Pointer to the result.

Description
This function estimates the processor operating frequency and returns its value, in MHz as an integer stored
in pMhz. The estimated value can vary depending on the processor workload.

      NOTE
      To improve precision of the return value, this function accumulates CPU clocks. This operation takes
      several seconds and may result in long execution time.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error condition when the  pMhz  pointer is NULL.

                                                                                              27
---------------------Page 28---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

GetCpuFeatures
Retrieves the processor features.

Syntax
IppStatus ippGetCpuFeatures(Ipp64u* pFeaturesMask, Ipp32u pCpuidInfoRegs[4]           );

Include Files
ippcore.h

Parameters

pFeaturesMask                 Pointer to the features mask. Possible value is ippCPUID_GETINFO_A   .

pCpuidInfoRegs                Pointer to the vector with four elements to store the data from the
                              registers eax, ebx, ecx, edx of the function CPUID.1.

Description
This function retrieves some of the CPU features returned by the function CPUID.1 and stores them
consecutively in the mask pFeaturesMask. The following table lists the features stored in the mask.
If pFeaturesMask  does not have any input value, then the function retrieves the features in accordance with
eax=1 and ecx=0 . If pFeaturesMask is set to ippCPUID_GETINFO_A , then the function retrieves the
features in accordance with the input values of the registers eax and ecx that are specified in this case by
the pCpuidInfoRegs [0] and pCpuidInfoRegs  [2] respectively.
 Mask Value             Bit Name                         Feature                Mask Bit Number
 1
                       ippCPUID_MMX                      MMX TM technology     0

 2                                                           ®
                       ippCPUID_SSE                      Intel  Streaming      1
                                                         SIMD Extensions
 4                                                           ®
                       ippCPUID_SSE2                     Intel  Streaming      2
                                                         SIMD Extensions 2
 8                                                           ®
                       ippCPUID_SSE3                     Intel  Streaming      3
                                                         SIMD Extensions 3
 16                                                                       ®
                       ippCPUID_SSSE3                    Supplemental Intel    4
                                                         Streaming SIMD
                                                         Extensions
 32
                       ippCPUID_MOVBE                    MOVBE instruction is  5
                                                         supported
 64                                                          ®
                       ippCPUID_SSE41                    Intel  Streaming      6
                                                         SIMD Extensions 4.1
 128                                                         ®
                       ippCPUID_SSE42                    Intel  Streaming      7
                                                         SIMD Extensions 4.2
 256
                       ippCPUID_AVX                      The processor supports8
                                                             ®
                                                         Intel  Advanced Vector
                                                                       ®
                                                         Extensions (Intel  AVX)
                                                         instruction set
 512
                       ippAVX_ENABLEDBYOS                The operating system  9
                                                                    ®
                                                         supports Intel  AVX

   28
---------------------Page 29---------------------

                                                                                Support Functions  3   

 Mask Value             Bit Name                          Feature                Mask Bit Number
 1024
                        ippCPUID_AES                      Advanced Encryption    10
                                                          Standard (AES)
                                                          instructions are
                                                          supported
 2048
                        ippCPUID_CLMUL                    PCLMULQDQ              11
                                                          instruction is
                                                          supported

All features returned by the function CPUID.1 can be stored in the vector with four elements
pCpuidInfoRegs   where each element contains data from one of the registers eax, ebx, ecx, edx
respectively. If these data are not required, the pointer pCpuidInfoRegs must be set to NULL.

      NOTE
          ®        ®
      Intel  Itanium  processors are not supported.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error condition when the   pFeaturesMask   pointer is
                                    NULL .
ippStsNotSupportedCpu               Indicates that the processor is not supported.

GetEnabledCpuFeatures
Returns a features mask for enabled processor
features.

Syntax
Ipp64u ippGetEnabledCpuFeatures (void);

Include Files
ippcore.h

Description
This function detects the enabled CPU features for the currently loaded libraries and returns the
corresponding features mask.

 Optimization Notice

 Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for
 optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and
 SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or
 effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-
 dependent optimizations in this product are intended for use with Intel microprocessors. Certain
 optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to
 the applicable product User and Reference Guides for more information regarding the specific instruction
 sets covered by this notice.
 Notice revision #20110804

                                                                                                 29
---------------------Page 30---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

See Also
GetCpuFeatures Retrieves the processor features.

GetNumCoresOnDie
DEPRECATED. Returns the number of cores for multi-
core processors.

Syntax
int ippGetNumCoresOnDie (void)     ;

Include Files
ippcore.h

Description
The ippGetNumCoresOnDie    function is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function retrieves the number of cores for multi-core processors. Use this function to distinguish physical
cores from hyper threading (HT) on systems with multithreading support.

GetMaxCacheSizeB
Returns maximum size of the L2 and L3 caches of the
processor.

Syntax
IppStatus ippGetMaxCacheSizeB(int* pSizeByte);

Include Files
ippcore.h

Parameters

pSizeByte                     Pointer to the output result.

Description
This function finds the maximum size (in bytes) of the L2 and L3 caches of the processor used on your
computer system. The result is stored in the pSizeByte.

      NOTE
      Intel® Itanium® processors are not supported.

If the processor is not supported, or size of cache is unknown, the result is 0, and the function returns
corresponding warning message.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error condition when the  pSizeByte   pointer is
                                    NULL.

   30
---------------------Page 31---------------------

                                                                              Support Functions  3  

ippStsNotSupportedCpu              Indicates that the processor is not supported.

ippStsUnknownCacheSize             Indicates that the size of the cache is unknown.

SetFlushToZero
Enables or disables flush-to-zero (FTZ) mode.

Syntax
IppStatus ippSetFlushToZero(int value, unsigned int* pUMask        );

Include Files
ippcore.h

Parameters

value                         Switch to set or clear the corresponding bit of the MXCSR register.
                              •  When value  is not equal to zero, flush-to-zero (FTZ) mode is enabled
                              •  When value  is set to zero, FTZ mode is disabled

pUMask                        Pointer to the current underflow exception mask; may be set to
                              NULL.

Description
This function enables FTZ mode for processors that support Streaming SIMD Extensions (SSE) instructions.
The FTZ mode controls the masked response to a SIMD floating-point underflow condition. Use this function
to improve performnace of applications where underflows are common and rounding the underflow result to
zero is acceptable.
FTZ mode is possible only when the mask register is in a certain state. The ippSetFlushToZero function
checks and changes this state if necessary. After disabling the FTZ mode, you can restore the initial mask
register state. To do this, declare a variable of unsigned integer type in your application and point to it
the parameter pUMask of the ippSetFlushToZero  function. The initial state of mask register is saved in this
location and can be restored later. If you do not need to restore the initial mask state, then the pointer
pUMask may be set to NULL.

Return Values

ippStsNoErr                        Indicates no error.

ippStsCpuNotSupportedErr           Indicates an error condition when the FTZ mode is not
                                   supported by the processor.

See Also
Bibliography: Casey08

SetDenormAreZeros
Enables or disables denormals-are-zero (DAZ) mode.

Syntax
IppStatus ippSetDenormAreZeros(int value     );

Include Files
ippcore.h

                                                                                              31
---------------------Page 32---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

value                          Switch to set or clear the corresponding bit of the MXCSR register.
                               •     When value is not equal to zero, denormals-are-zero (DAZ) mode is
                                  enabled
                               •     When value is set to zero, DAZ mode is disabled

Description
This function enables the DAZ mode for processors that support Streaming SIMD Extensions (SSE)
instructions. The DAZ mode controls the processor response to a SIMD floating-point denormal operand
condition. When the DAZ flag is set, the processor converts all denormal source operands to zero with the
sign of the original operand before performing any computations on source data. Use this function to improve
processor performance of applications such as streaming media processing, where rounding a denormal
operand to zero does not noticeably affect the quality of the processed data.

Return Values

ippStsNoErr                         Indicates no error.

ippStsCpuNotSupportedErr            Indicates an error condition when the DAZ mode is not
                                    supported by the processor.

See Also
Bibliography: Casey08

AlignPtr
Aligns a pointer to the specified number of bytes.

Syntax
void* ippAlignPtr(void* ptr, int alignBytes       );

Include Files
ippcore.h

Parameters

ptr                            Aligned pointer.

alignBytes                     Number of bytes to align. Possible values are the powers of 2, that
                               is, 2, 4, 8, 16 and so on.

Description
This function returns a pointer ptr aligned to the specified number of bytes alignBytes. Possible values of
alignBytes  are powers of two. The function does not check the validity of this parameter.

      NOTE
      Do not free the pointer returned by the function, but free the original pointer.

   32
---------------------Page 33---------------------

                                                                               Support Functions  3   

SetNumThreads
DEPRECATED. Sets the number of threads in the
multithreading environment.

Syntax
IppStatus ippSetNumThreads(int numThr      );

Include Files
ippcore.h

Parameters

numThr                        Number of threads, should be more than zero.

Description
The ippSetNumThreads   function is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function sets the number of OpenMP* threads. A number of established threads may be less than
specified numThr.

Return Values

ippStsNoErr                        Indicates no error.

ippStsSizeErr                      Indicates an error condition if numThr is less than or equal to
                                   zero.
ippStsNoOperation                  Indicates that there is no such operation in the static version of
                                   the library.

GetNumThreads
DEPRECATED. Returns the number of existing threads
in the multithreading environment.

Syntax
IppStatus ippGetNumThreads(int* pNumThr      );

Include Files
ippcore.h

Parameters

pNumThr                       Pointer to the number of threads.

Description
The ippGetNumThreads   function is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function returns the number of OpenMP* threads specified by the user previously. If it is not specified,
the function returns the initial number of threads that depends on the number of logical processors.

                                                                                               33
---------------------Page 34---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error condition when the   pMhz pointer is NULL.

ippStsNoOperation                   Indicates that there is no such operation in the static version of
                                    the library.

SetAffinity
Binds OpenMP* threads to OS processors.

Syntax
IppStatus ippSetAffinity(IppAffinityType aType, int offset          );

Include Files
ippcore.h

Parameters

aType                          Type of affinity settings, possible values:

                               ippAffinityCompactFineCore

                               ippAffinityCompactFineHT

                               ippAffinityAllEnabled

                               ippAffinityRestore

                               ippTstAffinityCompactFineCore

                               ippTstAffinityCompactFineHT

offset                         Starting position for thread assignment.

Description
This function sets OpenMP* thread affinity for all OpenMP* parallel regions in the current context.

      NOTE
      Thread affinity is supported on systems running Windows* OS and those versions of Linux* OS that
      have kernel support for thread affinity.

 
The function ippSetAffinity  increases performance of threaded functions on homogeneous systems. Use
this function to:
•     Set threads to cores that share the same last level cache (LLC). This is useful for sharing the same data
  at the same cache level (for example, FFT functions).
•     Set threads to cores that do not share the same LLC. This is useful when each thread works with a
  separate piece of data (for example, 2D filtering functions).
•     Disable hyper threading (HT) and dispatch code only to physical cores, without hardware resources. This
  is useful for highly optimized functions. HT is not effective for highly optimized functions.

   34
---------------------Page 35---------------------

                                                                                 Support Functions  3   

Once the function ippSetAffinity   sets affinity such that the number of threads equal the number of OS
processors [ICCC] on the machine, then each thread remains bound to the corresponding OS processor,
unless reset via a subsequent call to ippSetAffinity.
This function uses Intel OpenMP* low-level affinity application programming interface (API), and it takes
effect if OMP_AFFINITY environment variable is not set to disabled.
In accordance with the values of the parameter aType, the following thread affinity types are possible:

• ippAffinityCompactFineCore      - if HT is enabled, and OpenMP* parallel regions do not use all available
  OpenMP* threads, the adjacent threads use the shared cache on two cores. In this case, the adjacent
  threads do not compete for resources on the same core, leaving other core not used. This is equal to the
  following OpenMP* settings: KMP_AFFINITY=granularity=fine,compact,1,offset          [ICCC]. If HT is
  disabled, two adjacent threads are bound to cores with one shared cache.
• ippAffinityCompactFineHT      - OpenMP* thread  <n>+1 is assigned to the free thread from the OS thread
  context closest to those OS thread context, where the OpenMP* thread <n> is assigned. This is equal to
  the following OpenMP* settings: KMP_AFFINITY=granularity=fine,compact,0,offset         [ICCC].
• ippAffinityAllEnabled     - all OpenMP* threads have access to all OS processors. This is equal to the
  following OpenMP* settings: KMP_AFFINITY=respect     [ICCC].
• ippAffinityRestore     - sets thread affinity, which is set before machine topology initialization.
• ippTstAffinityCompactFineCore       - test mode for the affinity type ippAffinityCompactFineCore .
• ippTstAffinityCompactFineHT       - test mode for the affinity type ippAffinityCompactFineHT

Return Values

ippStsNoErr                         Indicates that OpenMP* thread affinity is set.

ippStsLLADisable                    Indicates a warning that the OpenMP* low level affinity is disabled.

ippStsNotSupportedCpu               Indicates a warning that the processor is not supported, or the
                                    operating system does not support thread affinity.

 Optimization Notice

 Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for
 optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and
 SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or
 effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-
 dependent optimizations in this product are intended for use with Intel microprocessors. Certain
 optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to
 the applicable product User and Reference Guides for more information regarding the specific instruction
 sets covered by this notice.
 Notice revision #20110804

Malloc
Allocates memory aligned to 64-byte boundary.

Syntax
void* ippMalloc(int length    );

Include Files
ippcore.h

                                                                                                  35
---------------------Page 36---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

len                           Size (in bytes) of the allocated block.

Description
This function allocates a memory block aligned to a 64-byte boundary.

Return Values
The return value of ippMalloc is a pointer to an aligned memory block. To free this block, use the ippFree
function.

See Also
Free Frees memory allocated by the function  ippMalloc  .

Free
Frees memory allocated by the function ippMalloc.

Syntax
void ippFree(void* ptr   );

Include Files
ippcore.h

Parameters

ptr                           Pointer to a memory block to be freed.

Description
This function frees an aligned memory block previously allocated by the function ippMalloc.

     NOTE
     Use the ippFree()  to free memory allocated by ippMalloc(). Use free to free memory allocated by
     malloc  or calloc.

Dispatcher Control Functions
This section describes Intel     functions that control the dispatchers of the merged static libraries.

StaticInit
DEPRECATED. Automatically initializes static code that
is the most appropriate for the current processor type.

Syntax
IppStatus ippStaticInit(void);

Include Files
ippcore.h

   36
---------------------Page 37---------------------

                                                                                Support Functions  3   

Description
This function is deprecated and will be removed in a future release. Use the ippInit function instead.
This function detects the processor type used and sets the most appropriate processor-specific static code of
the Intel     software.

      NOTE
      This function operates only in the static version of the library.

      NOTE
      You cannot use any other Intel     function while the function ippStaticInit continues execution.

Return Values

ippStsNoErr                         Indicates that the most appropriate static code of the Intel    
                                    software is successfully set.
ippStsNonIntelCpu                   Indicates that the static version of generic code for Intel
                                    Architecture is set.
ippStsNoOperationInDll              Indicates that there is no operation in the dynamic version of
                                    the library.

Init
Automatically initializes the library code that is most
appropriate for the current processor type.

Syntax
IppStatus ippInit(void)    );

Include Files
ippcore.h

Description
This function detects the processor type used in the user computer system and sets the processor-specific
code of the Intel     library most appropriate for the current processor type.

      NOTE
      You can not use any other Intel     function while the function ippInit continues execution.

Return Values

ippStsNoErr                         Indicates that the required processor-specific code is
                                    successfully set.
ippStsNotSupportedCpu               Indicates that the CPU is not supported.

ippStsNonIntelCpu                   Indicates that the target CPU is not Genuine Intel.

                                                                                                37
---------------------Page 38---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

InitCpu
Initializes the version of the library code for the
specified processor type.

Syntax
IppStatus ippInitCpu(IppCpuType cpu      );

Include Files
ippcore.h

Parameters

cpu                            Processor type.

Description
This function sets the processor-specific code of the Intel     library according to the processor type specified
in cpu.

      NOTE
      You cannot use any other Intel     function while the function ippInitCpu continues execution.

Return Values

ippStsNoErr                         Indicates that the required processor-specific code is
                                    successfully set.
ippStsCpuMismatch                   Indicates that the specified processor type is not valid; the
                                    previously set code is used.

EnableCpu
DEPRECATED. Enables automatic dispatching for the
specified processor type.

Syntax
IppStatus ippEnableCpu(IppCpuType cpu      );

Include Files
ippcore.h

Parameters

cpu                            Processor type.

Description
The ippEnableCpu   function is deprecated. This function is obsolete and will be removed in a future release.
Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
                                                                                  ®
This function enables automatic dispatching of the library code for processors with Intel Advanced Vector
                        ®
Extensions (AVX) on Intel AVX enabled hardware or simulators. To do this the function ippEnableCpu must
be called with the parameter cpu=ippCpuAVX  before the function ippInit.

   38
---------------------Page 39---------------------

                                                                            Support Functions  3 

Return Values

ippStsNoErr                       Indicates that the required processor-specific code is
                                  successfully set.

Internationalization Functions
This section describes auxiliary functions for adapting Intel     software to different languages and regional
differences.

MessageCatalogOpenI18n
DEPRECATED. Opens an internationalization message
catalog.

Syntax
IppStatus ippMessageCatalogOpenI18n(IppMsgCatalog** ppMsgCatalog       );

Include Files
ippcore.h

Parameters

ppMsgCatalog                 Double pointer to the message catalog

Description
The ippMessageCatalogOpenI18n   function is deprecated. This function is obsolete and will be removed in a
future release. For more information about the deprecation process use the following link: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function opens the internationalization message catalog ppMsgCatalog containing the translated
strings.

     NOTE
     This function allocates memory that can be freed only by the function
     ippMessageCatalogCloseI18n   . Use the function ippMessageCatalogCloseI18n  after opening the
     message catalog regardless of the returned status value.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error condition when the ppMsgCatalog  pointer is
                                  NULL.
ippStsMemAllocErr                 Indicates an error condition when no memory allocated.

ippStsI18nUnsupportedErr          Indicates an error condition when the internationalization i18n
                                  is not supported.
ippStsI18nMsgCatalogOpenErr       Indicates an error condition when the message catalog cannot
                                  be opened; to get extended information use  errno  on Linux*
                                  OS and  GetLastError  on Windows* OS.

                                                                                           39
---------------------Page 40---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

See Also
Message Catalog
MessageCatalogCloseI18n DEPRECATED. Closes the opened i18n message catalog.

MessageCatalogCloseI18n
DEPRECATED. Closes the opened i18n message
catalog.

Syntax
IppStatus ippMessageCatalogCloseI18n(IppMsgCatalog* pMsgCatalog      );

Include Files
ippcore.h

Parameters

pMsgCatalog                  Pointer to the message catalog.

Description
The ippMessageCatalogCloseI18n   function is deprecated. This function is obsolete and will be removed in
a future release. For more information about the deprecation process use the following link: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function closes the message catalog pMsgCatalog, which is opened by the function
ippMessageCatalogOpenI18n  . Use the function ippMessageCatalogCloseI18n after opening the
message catalog to free memory allocated by the function ippMessageCatalogOpenI18n.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error condition when the pMsgCatalog  pointer is
                                 NULL .
ippStsContextMatchErr            Indicates an error condition when the catalog identifier is not
                                 correct.
ippStsI18nMsgCatalogCloseErr     Indicates an error condition when the message catalog cannot
                                 be closed; to get extended information use errno  on Linux* OS
                                 and  GetLastError  on Windows* OS.
ippStsI18nUnsupportedErr         Indicates an error condition when internationalization is not
                                 supported.

See Also
MessageCatalogOpenI18n DEPRECATED. Opens an internationalization message catalog.

GetMessageStatusI18n
DEPRECATED. Returns the translation of the status
message.

Syntax
IppStatus ippGetMessageStatusI18n(const IppMsgCatalog* pMsgCatalog, IppStatus stsCode,
IppMsg* pMsg );

   40
---------------------Page 41---------------------

                                                                            Support Functions  3  

Include Files
ippcore.h

Parameters

pMsgCatalog                  Pointer to the message catalog.

stsCode                      Code of Intel     status.

pMsg                         Pointer to the string containing the translated status message.

Description
The ippGetMessageStatusI18n   function is deprecated. This function is obsolete and will be removed in a
future release. For more information about the deprecation process use the following link: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function returns the string pMsg containing the translation of the status message corresponding to
stsCode. The translated message is encoded in UTF16 on Windows* OS, and UTF8 on Linux* OS. The
messages are stored in the message catalog pMsgCatalog. On Linux* OS the binary message catalog is
generated using the gencat utility. On Windows* OS the binary message catalog is generated using the
message compiler (mc) and resource compiler (rc) utilities of the Microsoft* SDK Tools.
To open the message catalog pMsgCatalog, use the function ippMessageCatalogOpenI18n. The returned
pMsg is freed by the function ippMessageCatalogCloseI18n.
If the translation is not available, the function returns not translated status message.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error condition when one of the specified pointers
                                  is NULL.
ippStsMemAllocErr                 Indicates an error condition when no memory allocated.

ippStsContextMatchErr             Indicates an error condition when the catalog identifier is not
                                  correct.
ippStsUnknownStatusCodeErr        Indicates an error condition when stsCode  has unknown value.

ippStsI18nMsgCatalogInvalid       Indicates a warning when the message catalog is not valid; a
                                  status message in English is returned.
ippStsI18nGetMessageFail          Indicates a warning when the function cannot return the
                                  translated message; the status message in English is returned.
                                  To get extended information use  errno  on Linux* OS and
                                  GetLastError   on Windows* OS.

See Also
MessageCatalogOpenI18n DEPRECATED. Opens an internationalization message catalog.
MessageCatalogCloseI18n DEPRECATED. Closes the opened i18n message catalog.

StatusToMessageIdI18n
DEPRECATED. Transforms Intel     status code to the
message ID for the message catalog.

Syntax
Ipp32u ippStatusToMessageIdI18n(IppStatus stsCode      );

                                                                                            41
---------------------Page 42---------------------

 3    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Include Files
ippcore.h

Parameters

stsCode                         Code of Intel     status.

Description
The ippStatusToMessageIdI18n      function is deprecated. This function is obsolete and will be removed in a
future release. For more information about the deprecation process use the following link: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function returns the message ID in the i18n message catalog for the Intel     status specified by the
code stsCode . Use this function for the direct access to the associated message catalog.

See Also

    42
---------------------Page 43---------------------

Vector Initialization Functions                                                4

This chapter describes the Intel®     functions that initialize vectors with either constants, the contents of
other vectors, or the generated signals.

Vector Initialization Functions
This section describes functions that initialize the values of vector elements. All vector elements can be
initialized to a common zero or another specified value. They can also be initialized to respective values of a
second vector elements.

Copy
Copies the contents of one vector into another.

Syntax
IppStatus ippsCopy_8u(const Ipp8u* pSrc, Ipp8u* pDst, int len  );
IppStatus ippsCopy_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len  );
IppStatus ippsCopy_32s(const Ipp32s* pSrc, Ipp32s* pDst, int len  );
IppStatus ippsCopy_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len  );
IppStatus ippsCopy_64s(const Ipp64s* pSrc, Ipp64s* pDst, int len  );
IppStatus ippsCopy_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len  );
IppStatus ippsCopy_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len  );
IppStatus ippsCopy_32sc(const Ipp32sc* pSrc, Ipp32sc* pDst, int len  );
IppStatus ippsCopy_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len  );
IppStatus ippsCopy_64sc(const Ipp64sc* pSrc, Ipp64sc* pDst, int len  );
IppStatus ippsCopy_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len  );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsCopy_1u(const Ipp8u* pSrc, int srcBitOffset, Ipp8u* pDst, int
dstBitOffset, int len);

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.

                                                                                     43
---------------------Page 44---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

len                            Number of elements to copy.

srcBitOffset                   Offset, in bits, from the first byte of the source vector.

dstBitOffset                   Offset, in bits, from the first byte of the destination vector.

Description
The ippsCopy_1u   function is deprecated and will be removed in a future release. Use the ippsCopyLE_1u
function instead. For more information about the deprecation process, use the following link: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function copies the first len elements from a source vector pSrc into a destination vector pDst.
ippsCopy_1u  . This function flavor copies elements of a vector that has a 8u data type. It means that each
byte consists of eight consecutive elements of the vector (1 bit per element). You need to specify the start
position of the source and destination vectors in the srcBitOffset and dstBitOffset parameters,
respectively. The bit order of each byte is inverse to the element order. It means that the first element in a
vector represents the last (seventh) bit of the first byte in a vector, as shown in the figure below.

Bit Layout for the Function ippsCopy_1u.

      NOTE
      These functions perform only copying operations described above and are not intended to move data.
      Their behavior is unpredictable if source and destination buffers are overlapping. To move data, use
      ippsMove .

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when the   pSrc  or pDst pointer is NULL.

ippStsSizeErr                       Indicates an error when   len is less than or equal to zero.

Example
The example below shows how to use the ippsCopy   function.
IppStatus copy(void) {
       char src[] = “to be copied\0”;
       char dst[256];
       return ippsCopy_8u(src, dst, strlen(src)+1);
  } 

See Also
Move Moves the contents of one vector to another vector.

   44
---------------------Page 45---------------------

                                                                     Vector Initialization Functions  4 

CopyLE, CopyBE
Copies the contents of one bit vector into another.

Syntax
IppStatus ippsCopyLE_1u(const Ipp8u* pSrc, int srcBitOffset, Ipp8u* pDst, int
dstBitOffset, int len   );
IppStatus ippsCopyBE_1u(const Ipp8u* pSrc, int srcBitOffset, Ipp8u* pDst, int
dstBitOffset, int len   );

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.

len                           Number of elements to copy.

srcBitOffset                  Offset, in bits, from the first byte of the source vector.

dstBitOffset                  Offset, in bits, from the first byte of the destination vector.

Description
This function copies the first len elements from a source vector pSrc into a destination vector pDst.
These functions copy elements of a vector that has a 8u data type. It means that each byte consists of eight
consecutive elements of the vector (1 bit per element). You need to specify the start position of the source
and destination vectors in the srcBitOffset and dstBitOffset parameters, respectively.
For the ippsCopyLE_1u  function, the bit order of each byte is inverse to the element order. It means that
the first element in a vector represents the last (seventh) bit of the first byte in a vector, as shown in the
figure below.

Bit Layout for the ippsCopyLE_1u Function

                                                                                              45
---------------------Page 46---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

For the ippsCopyBE_1u function, the bit order of each byte is ordinary. It means that the first element in a
vector represents the last (zero) bit of the first byte in a vector, as shown in the figure below.

Bit Layout for the ippsCopyBE_1u Function

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the pSrc  or pDst pointer is NULL.

ippStsSizeErr                      Indicates an error when:
                                   • len  is less than, or equal to zero
                                   • srcBitOffset   or dstBitOffset  is less than zero

PackBits
DEPRECATED. Packs part of data bits from the vector
to the bitstream.

Syntax
IppStatus ippsPackBits_32u8u(const Ipp32u* pSrcBit, const int* pSrcBits, int srcLen,
Ipp8u* pDst, int dstBitOffset, int* pDstLenBit      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcBit                       Pointer to the source vector with data.

pSrcBits                      Pointer to the source vector that specifies the number of data bits.

srcLen                        Number of elements in each source vector.

pDst                          Pointer to the destination vector (bitstream).

dstBitOffset                  Offset (in bits) in the first byte of the destination vector.

pDstLenBit                    Pointer to the length in bits of the destination vector.

   46
---------------------Page 47---------------------

                                                                   Vector Initialization Functions  4 

Description
The function ippsPackBits is deprecated. This function is obsolete and will be removed in a future release.
Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function copies the certain number of bits from each element of the data source vector pSrcBit and
stores them contiguously in the destination vector pDst starting from the bit position dstBitOffset. Each
element of the source vector pSrcBits contains the number of bits that are copied from the corresponding
element of the vector pSrcBit. If this number is less than 0, or greater than 32, then its value is set to 0 or
32 respectively. If such cases occur, the function returns the warning message after completing the
operation. After completing the operation the function returns the length of the destination vector in bits
pDstLenBit .

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                     Indicates an error when srcLen  is less than or equal to 0, or
                                  dstBitOffset  is less than 0.
ippStsOverlongString              Indicates a warning when  pSrcBits[i]  is greater than 32 or
                                  less than 0.

Move
Moves the contents of one vector to another vector.

Syntax
IppStatus ippsMove_8u(const Ipp8u* pSrc, Ipp8u* pDst, int len       );
IppStatus ippsMove_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len       );
IppStatus ippsMove_32s(const Ipp32s* pSrc, Ipp32s* pDst, int len       );
IppStatus ippsMove_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len       );
IppStatus ippsMove_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len       );
IppStatus ippsMove_64s(const Ipp64s* pSrc, Ipp64s* pDst, int len       );
IppStatus ippsMove_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len       );
IppStatus ippsMove_32sc(const Ipp32sc* pSrc, Ipp32sc* pDst, int len       );
IppStatus ippsMove_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len       );
IppStatus ippsMove_64sc(const Ipp64sc* pSrc, Ipp64sc* pDst, int len       );
IppStatus ippsMove_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                           47
---------------------Page 48---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

pSrc                         Pointer to the source vector used to initialize pDst.

pDst                         Pointer to the destination vector to be initialized.

len                          Number of elements to move.

Description
This function moves the first len elements from a source vector pSrc into the destination vector pDst. If
some parts of the source and destination vectors are overlapping, then the function ensures that the original
source bytes in the overlapping parts are moved (it means that they are copied before being overwritten) to
the appropriate parts of the destination vector.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pSrc or pDst pointer is NULL.

ippStsSizeErr                     Indicates an error when len is less than or equal to zero.

Example
The example below shows how to use the function ippsMove.
Ipp8u pSrc[10] = { "123456789" }; 
Ipp8u pDst[6]; 
int len = 6; 
IppStatus status;

status = ippsMove_8u ( pSrc, pDst, len ); 
if(ippStsNoErr != status)
  printf("    Error: %s",ippGetStatusString(status));

Result:
pSrc = 123456789 
pDst = 123456

Set
Initializes vector elements to a specified common
value.

Syntax
IppStatus ippsSet_8u(Ipp8u val, Ipp8u* pDst, int len     );
IppStatus ippsSet_16s(Ipp16s val, Ipp16s* pDst, int len     );
IppStatus ippsSet_16sc(Ipp16sc val, Ipp16sc* pDst, int len      );
IppStatus ippsSet_32s(Ipp32s val, Ipp32s* pDst, int len     );
IppStatus ippsSet_32f(Ipp32f val, Ipp32f* pDst, int len     );
IppStatus ippsSet_32sc(Ipp32sc val, Ipp32sc* pDst, int len      );
IppStatus ippsSet_32fc(Ipp32fc val, Ipp32fc* pDst, int len      );
IppStatus ippsSet_64s(Ipp64s val, Ipp64s* pDst, int len     );
IppStatus ippsSet_64f(Ipp64f val, Ipp64f* pDst, int len     );
IppStatus ippsSet_64sc(Ipp64sc val, Ipp64sc* pDst, int len      );

   48
---------------------Page 49---------------------

                                                                 Vector Initialization Functions  4 

IppStatus ippsSet_64fc(Ipp64fc val, Ipp64fc* pDst, int len    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                        Pointer to the vector to be initialized.

len                         Number of elements to initialize.

val                         Value used to initialize the vector pDst.

Description
This function initializes the first len elements of the real or complex vector pDst to contain the same value
val.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pDst pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to zero.

Example
The code example below shows how to use the function ippsSet.
IppStatus set(void) {
      char src[] = “set”;
      return ippsSet_8u(‘0', src, strlen(src)); 
}

Zero
Initializes a vector to zero.

Syntax
IppStatus ippsZero_8u(Ipp8u* pDst, int len   );
IppStatus ippsZero_16s(Ipp16s* pDst, int len   );
IppStatus ippsZero_32s(Ipp32s* pDst, int len   );
IppStatus ippsZero_32f(Ipp32f* pDst, int len   );
IppStatus ippsZero_64s(Ipp64s* pDst, int len   );
IppStatus ippsZero_64f(Ipp64f* pDst, int len   );
IppStatus ippsZero_16sc(Ipp16sc* pDst, int len   );
IppStatus ippsZero_32sc(Ipp32sc* pDst, int len   );
IppStatus ippsZero_32fc(Ipp32fc* pDst, int len   );
IppStatus ippsZero_64sc(Ipp64sc* pDst, int len   );

                                                                                         49
---------------------Page 50---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsZero_64fc(Ipp64fc* pDst, int len       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                          Pointer to the vector to be initialized to zero.

len                           Number of elements to initialize.

Description
This function initializes the first len elements of the vector pDst to zero. If pDst is a complex vector, both
real and imaginary parts are zeroed.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when the  pDst  pointer is NULL.

ippStsSizeErr                       Indicates an error when  len  is less than or equal to zero.

Example
The code example below shows how to use the ippsZero  function.
IppStatus zero(void) {
   char src[] = “zero”;
   return ippsZero_8u(src, strlen(src)); 
}

Sample-Generating Functions

This section describes Intel     functions which generate tone samples, triangle samples, pseudo-random
samples with uniform distribution, and pseudo-random samples with Gaussian distribution, as well as special
test samples.
Some sample-generating functions operate with data in the fixed point format. These functions have Q15
suffix in their name. This means that integer data are used in calculations inside the function as real numbers
equal to the integer value multiplied by 2-15 (where “15” is called a scale factor).

Tone-Generating Functions
The functions described below generate a tone (or “sinusoid”) of a given frequency, phase, and magnitude.
Tones are fundamental building blocks for analog signals. Thus, sampled tones are extremely useful in signal
processing systems as test signals and as building blocks for more complex signals.
The use of tone functions is preferable against the analogous C math library's sin() function for many
applications, because Intel     functions can use information retained from the computation of the previous
sample to compute the next sample much faster than standard sin() or cos().

   50
---------------------Page 51---------------------

                                                                     Vector Initialization Functions  4 

ToneInitAllocQ15
DEPRECATED. Allocates memory and initializes the
tone generator specification structure for fixed point
data.

Syntax
IppStatus ippsToneInitAllocQ15_16s(IppToneState_16s** ppToneState, Ipp16s magn, Ipp16s
rFreqQ15, Ipp32s phaseQ15   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

ppToneState                   Double pointer to the tone generator specification structure.

magn                          Magnitude of the tone, that is, the maximum value attained by the
                              wave.
phaseQ15                      Phase of the tone relative to a cosine wave in Q16.15 format. It
                              must be in the range [0, 205886].
rFreqQ15                      Frequency of the tone relative to the sampling frequency in Q0.15
                              format. It must be in the range [0, 16383].

Description
The function ippsToneInitAllocQ15  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function allocates memory and initializes the tone generator structure pToneState with the specified
frequency rFreqQ15, phase phaseQ15 , and magnitude magn. Input data in the fixed point format Q15 are
converted to the corresponding float data type that lay in the range [0, 0.5) for relative frequency and [0,
2p) for phase. Q16.15 designates that 16 bits before and 15 bits after fixed point position are used to
present a 32-bit value in the fixed point format. Q0.15 designates that 0 bits before and 15 bits after fixed
point position are used to present a 16-bit value in the fixed point format.
Code example demonstrates how to use the function ippsToneInitAllocQ15 .

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pToneState  pointer is NULL.

ippStsToneMagnErr                  Indicates an error when  magn is less than or equal to zero.

ippStsToneFreqErr                  Indicates an error when  rFreqQ15  is negative, or greater than
                                   16383.
ippStsTonePhaseErr                 Indicates an error when the  phaseQ15  value is negative, or
                                   greater than 205886.

                                                                                              51
---------------------Page 52---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ToneFree
DEPRECATED. Frees memory allocated by the function
ippsToneInitAllocQ15  .

Syntax
IppStatus ippsToneFree(IppToneState_16s* pToneState       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pToneState                    Pointer to the tone generator specification structure.

Description
The function ippsToneFree is deprecated. This function is obsolete and will be removed in a future release.
Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function closes the tone generator state by freeing all memory associated with the structure created by 
ToneInitAllocQ15.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the pointer pToneState   is NULL.

ToneGetStateSizeQ15
DEPRECATED. Computes the length of the tone
generator structure.

Syntax
IppStatus ippsToneGetStateSizeQ15_16s(int* pToneStateSize        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pToneStateSize                Pointer to the computed value of size in bytes of the generator
                              specification structure.

   52
---------------------Page 53---------------------

                                                                      Vector Initialization Functions  4 

Description
The function ippsToneGetStateSizeQ15    is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function computes the length (in bytes) pToneStateSize of the tone generator structure that is used
by the function ToneInitQ15.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when the pointer  pToneStateSize   is NULL.

ToneInitQ15
DEPRECATED. Initializes the tone generator
specification structure for fixed point data.

Syntax
IppStatus ippsToneInitQ15_16s(IppToneState_16s* pToneState, Ipp16s magn, Ipp16s
rFreqQ15, Ipp32s phaseQ15    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pToneState                    Pointer to the tone generator specification structure.

magn                          Magnitude of the tone, that is, the maximum value attained by the
                              wave.
phaseQ15                      Phase of the tone relative to a cosine wave in Q16.15 format. It
                              must be in the range [0, 205886].
rFreqQ15                      Frequency of the tone relative to the sampling frequency in Q0.15
                              format. It must be in the range [0, 16383].

Description
The function ippsToneInitQ15  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function initializes the tone generator structure pToneState with the specified frequency rFreqQ15,
phase phaseQ15 , and magnitude magn . The structure is allocated in the external buffer, the size of which
must be computed by the function ToneGetStateSizeQ15 . Data in Q15 format are converted to the
corresponding float data type that lay in the range [0, 0.5) for relative frequency and [0, 2π) for phase.
Q16.15 designates that 16 bits before and 15 bits after fixed point position are used to present a 32-bit value
in the fixed point format. Q0.15 designates that 0 bits before and 15 bits after fixed point position are used
to present a 16-bit value in the fixed point format.

                                                                                                53
---------------------Page 54---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the pToneState   pointer is NULL.

ippStsToneMagnErr                  Indicates an error when magn  is less than or equal to zero.

ippStsToneFreqErr                  Indicates an error when rFreqQ15   is negative, or greater than
                                   16383.
ippStsTonePhaseErr                 Indicates an error when the phaseQ15  value is negative, or
                                   greater than 205886.

ToneQ15
DEPRECATED. Generates a tone with a frequency,
phase, and magnitude specified in the tone generator
structure.

Syntax
IppStatus ippsToneQ15_16s(Ipp16s* pDst, int len, IppToneState_16s* pToneState          );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                          Pointer to the array which stores the samples.

len                           Number of samples to be computed.

pToneState                    Pointer to the tone generator specification structure.

Description
The function ippsToneQ15 is deprecated. This function is obsolete and will be removed in a future release.
Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function generates the tone with the frequency, phase, and magnitude parameters that are specified in
the previously created structure pToneState. The function computes len samples of the tone, and stores
them in the array pDst. Generated values x[n] are computed using the same formulas as in the function 
Tone_Direct for computing real tones.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the pDst  or pToneState  pointer is NULL.

ippStsSizeErr                      Indicates an error when len  is less than or equal to zero.

   54
---------------------Page 55---------------------

                                                               Vector Initialization Functions  4 

Example
The code example below demonstrates how to use the function ippsToneQ15.
void func_toneq15() 
{
    IppToneState_16s *TS; 
    Ipp16s magn = 4095;
    Ipp16s rFreqQ15 = 512;
    Ipp16s phaseQ15 = 0;
    Ipp16s* pDst;
    IppStatus status;

    status = ippsToneInitAllocQ15_16s(&TS,magn,rFreqQ15,phaseQ15);
    if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status));
    status = ippsToneQ15_16s(pDst,rFreqQ15,TS);
    if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status)); 
}

Result:
 

 

Tone_Direct
DEPRECATED. Generates a tone with a given
frequency, phase, and magnitude.

Syntax
IppStatus ippsTone_Direct_16s(Ipp16s* pDst, int len, Ipp16s magn, float rFreq, float*
pPhase, IppHintAlgorithmhint );
IppStatus ippsTone_Direct_16sc(Ipp16sc* pDst, int len, Ipp16s magn, float rFreq, float*
pPhase, IppHintAlgorithmhint );
IppStatus ippsTone_Direct_32f(Ipp32f* pDst, int len, float magn, float rFreq, float*
pPhase, IppHintAlgorithmhint );
IppStatus ippsTone_Direct_32fc(Ipp32fc* pDst, int len, float magn, float rFreq, float*
pPhase, IppHintAlgorithmhint );
IppStatus ippsTone_Direct_64f(Ipp64f* pDst, int len, double magn, double rFreq, double*
pPhase, IppHintAlgorithmhint );
IppStatus ippsTone_Direct_64fc(Ipp64fc* pDst, int len, double magn, double rFreq,
double* pPhase, IppHintAlgorithmhint );

Include Files
ipps.h

                                                                                      55
---------------------Page 56---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

magn                          Magnitude of the tone, that is, the maximum value attained by the
                              wave.
pPhase                        Pointer to the phase of the tone relative to a cosine wave. It must
                              be in range [0.0, 2π). The returned value may be used to compute
                              the next continuous data block.
rFreq                         Frequency of the tone relative to the sampling frequency. It must be
                              in the interval [0.0, 0.5) for real tone and in [0.0, 1.0) for complex
                              tone.
pDst                          Pointer to the array which stores the samples.

len                           Number of samples to be computed.

hint                          Suggests using specific code. The possible values for the hint
                              argument are described in Special Arguments.

Description
The function ippsTone_Direct is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function generates the tone with the specified frequency rFreq, phase pPhase, and magnitude magn.
The function computes len samples of the tone, and stores them in the array pDst. For real tones, each
generated value x[n] is defined as:
x[n] = magn * cos(2πn*rFreq + phase)
For complex tones, x[n] is defined as:
x[n] = magn * (cos(2πn*rFreq + phase)+j* sin(2πn*rFreq + phase))
The parameter hint suggests using specific code, which provides for either fast but less accurate calculation,
or more accurate but slower execution.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pDst  or pPhase pointer is NULL.

ippStsSizeErr                     Indicates an error when  len  is less than or equal to zero.

ippStsToneMagnErr                 Indicates an error when  magn  is less than or equal to zero.

ippStsToneFreqErr                 Indicates an error when  rFreq  is negative, or greater than or
                                  equal to 0.5 for real tone and to 1.0 for complex tone.
ippStsTonePhaseErr                Indicates an error when the  pPhase  value is negative, or
                                  greater than or equal to IPP_2PI .

ToneQ15_Direct
DEPRECATED. Generates a tone with a given
frequency, phase, and magnitude.

   56
---------------------Page 57---------------------

                                                                     Vector Initialization Functions  4 

Syntax
IppStatus ippsToneQ15_Direct_16s(Ipp16s* pDst, int len, Ipp16s magn, Ipp16s rFreqQ15,
Ipp32s phaseQ15  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                          Pointer to the array which stores the samples.

magn                          Magnitude of the tone, that is, the maximum value attained by the
                              wave.
rFreqQ15                      Frequency of the tone relative to the sampling frequency in Q0.15
                              format. It must be in the range [0, 16383].
phaseQ15                      Phase of the tone relative to a cosine wave in Q16.15 format. It
                              must be in the range [0, 205886].

Description
The function ippsToneQ15_Direct  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function generates the tone with the specified frequency rFreqQ15, phase pPhaseQ15, and magnitude
magn. Data in Q15 format are converted to the corresponding float data type that lay in the range [0, 0.5)
for relative frequency and [0, 2π ) for phase.
Q16.15 designates that 16 bits before and 15 bits after fixed point position are used to present a 32-bit value
in the fixed point format. Q0.15 designates that 0 bits before and 15 bits after fixed point position are used
to present a 16-bit value in the fixed point format.
The function computes len samples of the tone, and stores them in the array pDst. Generated values x[n]
are computed using the same formulas as in the function Tone_Direct for computing real tones.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pDst pointer is NULL.

ippStsSizeErr                      Indicates an error when  len is less than or equal to zero.

ippStsToneMagnErr                  Indicates an error when  magn is less than or equal to zero.

ippStsToneFreqErr                  Indicates an error when  rFreqQ15  is negative, or greater than
                                   16383.
ippStsTonePhaseErr                 Indicates an error when the  phaseQ15  value is negative, or
                                   greater than 205886.

Triangle-Generating Functions
This section describes the functions that generate a periodic signal with a triangular wave form (referred to
as “triangle”) of a given frequency, phase, magnitude, and asymmetry.

                                                                                              57
---------------------Page 58---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

A real periodic signal with triangular wave form x[n] (referred to as a real triangle) of a given frequency
rFreq, phase value phase , magnitude magn, and asymmetry  h is defined as follows:
x[n] = magn * ct  h(2π* rFreq*n + phase)    , n = 0, 1, 2,...
A complexl periodic signal with triangular wave form x[n] (referred to as a complex triangle) of a given
frequency rFreq, phase value phase, magnitude magn , and asymmetry  h is defined as follows:
x[n] = magn * [ct   h(2π* rFreq*n + phase) + j * st     h(2π* rFreq*n + phase)]   , n = 0, 1, 2,...
The cth () function is determined as follows:
H = π + h
 

 
cth (α + k* 2π) = ct  h (α) , k = 0, ±1, ±2, ...
When H = π , asymmetry  h = 0, and function cth() is symmetric and a triangular analog of the cos()
function. Note the following equations:
cth (H/2 + k*π) = 0  , k = 0, ±1, ±2, ...
cth (k* 2π) = 1  , k = 0, ±1, ±2, ...
cth (H + k* 2π) = -1   , k = 0, ±1, ±2, ...
The sth () function is determined as follows:
 

 
sth (α + k* 2π) = st  h (α) , k = 0, ±1, ±2, ...
When H = π , asymmetry  h = 0, and function sth() is symmetric and a triangular analog of the sine function.
Note the following equations:
sth (α) = ct h (α + (3π + h)/2)    , k = 0, ±1, ±2, ...
sth (k* π) = 0  , k = 0, ±1, ±2, ...
sth ((π -h)/2 + k* 2π) = 1    , k = 0, ±1, ±2, ...
sth ((3π +h)/2 + k* 2π) = -1    , k = 0, ±1, ±2, ...

TriangleInitAllocQ15
DEPRECATED. Allocates memory and initializes the
triangle generator specification structure for fixed
point data.

   58
---------------------Page 59---------------------

                                                                    Vector Initialization Functions  4 

Syntax
IppStatus ippsTriangleInitAllocQ15_16s(IppTriangleState_16s** pTriangleState, Ipp16s
magn, Ipp16s rFreqQ15, Ipp32s phaseQ15, Ipp32s asymQ15      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTriangleState               Pointer to the pointer to the triangle generator specification
                             structure.
magn                         Magnitude of the tone, that is, the maximum value attained by the
                             wave.
rFreqQ15                     Frequency of the tone relative to the sampling frequency in Q0.15
                             format. It must be in the range [0, 16383].
phaseQ15                     Phase of the tone relative to a cosine wave in Q16.15 format. It
                             must be in the range [0, 205886].
asymQ15                      Asymmetry   h  of a triangle in Q16.15 format. It must be in the range
                             [-102943, 102943]. If  h=0, then the triangle is symmetric and a
                             direct analog of a tone.

Description
The function ippsTriangleInitAllocQ15  is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes the triangle generator structure pTriangleState with the
specified frequency rFreqQ15, phase phaseQ15, asymmetry asymQ15 and magnitude magn. Input data in
the fixed point format Q15 format are converted to the corresponding float data type that lay in the range [0,
0.5) for the relative frequency, [0, 2π) for the phase, and (-π, π) for the asymmetry.
Q16.15 designates that 16 bits before and 15 bits after fixed point position are used to present a 32-bit value
in the fixed point format. Q0.15 designates that 0 bits before and 15 bits after fixed point position are used
to present a 16-bit value in the fixed point format.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pTriandleState   pointer is NULL.

ippStsTriangleMagnErr             Indicates an error when  magn is less than or equal to zero.

ippStsTriangleFreqErr             Indicates an error when  rFreqQ15  is negative, or greater than
                                  16383.
ippStsTrianglePhaseErr            Indicates an error when the  phaseQ15  value is negative, or
                                  greater than 205886.
ippStsTriangleAsymErr             Indicates an error when the  asymQ15  value is less than -102943
                                  or greater than 102943.

                                                                                             59
---------------------Page 60---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

TriangleFree
DEPRECATED. Frees memory allocated by the function
ippsTriangleInitAlloc  .

Syntax
IppStatus ippsTriangleFree(IppTriangleState_16s* pTriangleState        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTriangleState                Pointer to the triangle generator specification structure.

Description
The function ippsTriangleFree  is deprecated. This function is obsolete and will be removed in a future
release. Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function closes the triangle generator state by freeing all memory associated with the structure created
by TriangleInitAllocQ15 .

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the pointer pTriangleState   is NULL.

TriangleGetStateSizeQ15
DEPRECATED. Computes the length of the triangle
generator structure.

Syntax
IppStatus ippsTriangleGetStateSizeQ15_16s(int* pTriangleStateSize         );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTriangleStateSize            Pointer tothe computed value of size in bytes of the generator
                              specification structure.

   60
---------------------Page 61---------------------

                                                                     Vector Initialization Functions  4 

Description
The function ippsTriangleGetStateSizeQ15    is deprecated. This function is obsolete and will be removed
in a future release. Use the following link for details: http://software.intel.com/sites/products/ipp-
deprecated-features-feedback/.
This function computes the length (in bytes) pTriangleStateSize of the tone generator structure that is
used by the function TriangleInitQ15.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the pointer  pTriangleStateSize   is
                                   NULL .

TriangleInitQ15
DEPRECATED. Initializes the triangle generator
specification structure for fixed point data.

Syntax
IppStatus ippsTriangleInitQ15_16s(IppTriangleState_16s* pTriangleState, Ipp16s magn,
Ipp16s rFreqQ15, Ipp32s phaseQ15, Ipp32s asymQ15       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTriangleState                Pointer to the triangle generator specification structure.

magn                          Magnitude of the tone, that is, the maximum value attained by the
                              wave.
rFreqQ15                      Frequency of the tone relative to the sampling frequency in Q0.15
                              format. It must be in the range [0, 16383].
phaseQ15                      Phase of the tone relative to a cosine wave in Q16.15 format. It
                              must be in the range [0, 205886].
asymQ15                       Asymmetry   h of a triangle in Q16.15 format. It must be in the range
                              [-102943,  102943]. If  h=0, then the triangle is symmetric and a
                              direct analog of a tone.

Description
The function ippsTriangleInitQ15  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function initializes the triangle generator structure pTriangleState with the specified magnitude magn,
frequency rFreqQ15, phase phaseQ15 , and asymmetry asymQ15 . The structure is allocated in the external
buffer, the size of which must be computed by the function ippsTriangleGetStateSizeQ15. Input data in the
fixed point format Q15 format are converted to the corresponding float data type that lay in the range [0,
0.5) for the relative frequency, [0, 2p) for the phase, and (-p, p) for the asymmetry.

                                                                                              61
---------------------Page 62---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Q16.15 designates that 16 bits before and 15 bits after fixed point position are used to present a 32-bit value
in the fixed point format. Q0.15 designates that 0 bits before and 15 bits after fixed point position are used
to present a 16-bit value in the fixed point format.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pTriandleState   pointer is NULL.

ippStsTriangleMagnErr              Indicates an error when  magn  is less than or equal to zero.

ippStsTriangleFreqErr              Indicates an error when  rFreqQ15  is negative, or greater than
                                   16383.
ippStsTrianglePhaseErr             Indicates an error when the  phaseQ15  value is negative, or
                                   greater than 205886.
ippStsTriangleAsymErr              Indicates an error when the  asymQ15  value is less than -102943
                                   or greater than 102943.

TriangleQ15
DEPRECATED. Generates a triangle with a frequency,
phase, and magnitude specified in the triangle
generator structure.

Syntax
IppStatus ippsTriangleQ15_16s(Ipp16s* pDst, int len, IppTriangleState_16s*
pTriangleState  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                          Pointer to the array which stores the generated samples.

len                           Number of samples to be computed.

pTriangleState                Pointer to the triangle generator specification structure.

Description
The function ippsTriangleQ15  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function generates the triangle with the frequency, phase, magnitude, and asymmetry parameters that
are specified in the previously created structure pTriangleState. The function computes len samples of
the triangle, and stores them in the array pDst. Generated values x[n] are computed using the same f
ormulas as in Triangle_Direct function for computing real triangles.

Return Values

ippStsNoErr                        Indicates no error.

   62
---------------------Page 63---------------------

                                                                 Vector Initialization Functions  4 

ippStsNullPtrErr                 Indicates an error when the pDst or pToneState pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to zero.

Triangle_Direct
DEPRECATED. Generates a triangle with a given
frequency, phase, and magnitude.

Syntax
IppStatus ippsTriangle_Direct_16s(Ipp16s* pDst, int len, Ipp16s magn, float rFreq,
float asym, float* pPhase );
IppStatus ippsTriangle_Direct_16sc(Ipp16sc* pDst, int len, Ipp16s magn, float rFreq,
float asym, float* pPhase );
IppStatus ippsTriangle_Direct_32f(Ipp32f* pDst, int len, float magn, float rFreq, float
asym, float* pPhase );
IppStatus ippsTriangle_Direct_32fc(Ipp32fc* pDst, int len, float magn, float rFreq,
float asym, float* pPhase );
IppStatus ippsTriangle_Direct_64f(Ipp64f* pDst, int len, double magn, double rFreq,
double asym, double* pPhase  );
IppStatus ippsTriangle_Direct_64fc(Ipp64fc* pDst, int len, double magn, double rFreq,
double asym, double* pPhase  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

rFreq                       Frequency of the triangle relative to the sampling frequency. It must
                            be in range [0.0, 0.5).
pPhase                      Pointer to the phase of the triangle relative to a cosine triangular
                            analog wave. It must be in range [0.0, 2π). The returned value may
                            be used to compute the next continuous data block.
magn                        Magnitude of the triangle, that is, the maximum value attained by
                            the wave.
asym                        Asymmetry   h of a triangle. It must be in range [-π , π ). If h=0, then
                            the triangle is symmetric and a direct analog of a tone.
pDst                        Pointer to the array which stores the samples.

len                         Number of samples to be computed.

Description
The function ippsTriangle_Direct is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.

                                                                                        63
---------------------Page 64---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

This function generates the triangle with the specified frequency rFreq, phase pointed by pPhase, and
magnitude magn. The function computes len samples of the triangle, and stores them in the array pDst. For
real triangle, x[n] is defined as:
x[n] = magn * ct  h(2π* rFreq*n + phase)  , n = 0, 1, 2,...
For complex triangles, x[n] is defined as:
x[n] = magn * [ct  h(2π* rFreq*n + phase) + j * st   h(2π* rFreq*n + phase)]   , n = 0, 1, 2,...
See Triangle-Generating Functions for the definition of functions cth and sth.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pDst  or pPhase pointer is NULL.

ippStsSizeErr                     Indicates an error when  len is less than or equal to zero.

ippStsTrnglMagnErr                Indicates an error when  magn  is less than or equal to zero.

ippStsTrnglFreqErr                Indicates an error when  rFreq  is negative, or greater than or
                                  equal to 0.5.
ippStsTrnglPhaseErr               Indicates an error when the  pPhase  value is negative, or
                                  greater than or equal to IPP_2PI .
ippStsTrnglAsymErr                Indicates an error when  asym  is less than -IPP_PI, or greater
                                  than or equal to IPP_PI .

Example
The code example below demonstrates how to use the function ippsTriangle.
void func_triangle_direct() 
{
    Ipp16s* pDst;
    int len = 512;
    Ipp16s magn = 4095;
    float rFreq = 0.02;
    float asym = 0.0;
    float Phase = 0.0;
    IppStatus status;

    status = ippsTriangle_Direct_16s(pDst, len, magn, rFreq, asym, &Phase);
    if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status)); 
}

Result:
 

 

   64
---------------------Page 65---------------------

                                                                     Vector Initialization Functions  4 

TriangleQ15_Direct
DEPRECATED. Generates a triangle with a given
frequency, phase, and magnitude for fixed point data.

Syntax
IppStatus ippsTriangleQ15_Direct_16s(Ipp16s* pDst, int len, Ipp16s magn, Ipp16s
rFreqQ15, Ipp32s phaseQ15, Ipp32s asymQ15      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                          Pointer to the array which stores the samples.

magn                          Magnitude of the tone, that is, the maximum value attained by the
                              wave.
rFreqQ15                      Frequency of the tone relative to the sampling frequency in Q0.15
                              format. It must be in the range [0, 16383].
phaseQ15                      Phase of the tone relative to a cosine wave in Q16.15 format. It
                              must be in the range [0, 205886].
asymQ15                       Asymmetry   h of a triangle in Q16.15 format. It must be in the range
                              [-102943, 102943]. If  h=0, then the triangle is symmetric and a
                              direct analog of a tone.

Description
The function ippsTriangleQ15_Direct   is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function generates the triangle with the specified magnitude magn, frequency rFreqQ15, phase
pPhaseQ15 , and asymmetry asymQ15 . Input data in the fixed point format Q15 format are converted to the
corresponding float data type that lay in the range [0, 0.5) for the relative frequency, [0, 2π) for the phase,
and [- π, π) for the asymmetry.
Q16.15 designates that 16 bits before and 15 bits after fixed point position are used to present a 32-bit value
in the fixed point format. Q0.15 designates that 0 bits before and 15 bits after fixed point position are used
to present a 16-bit value in the fixed point format.
The function computes len samples of the tone, and stores them in the array pDst. Generated values x[n]
are computed using the same formulas as in the function Triangle_Direct for computing real triangles.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pDst pointer is NULL.

ippStsSizeErr                      Indicates an error when  len is less than or equal to zero.

ippStsToneMagnErr                  Indicates an error when  magn is less than or equal to zero.

                                                                                              65
---------------------Page 66---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsToneFreqErr                 Indicates an error when rFreqQ15  is negative, or greater than
                                  16383.
ippStsTonePhaseErr                Indicates an error when the phaseQ15  value is negative, or
                                  greater than 205886.
ippStsTriangleAsymErr             Indicates an error when the asymQ15  value is less than -102943
                                  or greater than 102943.

Uniform Distribution Functions
This section describes the functions that generate pseudo-random samples with uniform distribution.

RandUniformInitAlloc
DEPRECATED. Allocates memory and initializes a noise
generator with uniform distribution.

Syntax
IppStatus ippsRandUniformInitAlloc_8u(IppsRandUniState_8u** pRandUniState, Ipp8u low,
Ipp8u high, unsigned int seed   );
IppStatus ippsRandUniformInitAlloc_16s(IppsRandUniState_16s** pRandUniState, Ipp16s
low, Ipp16s high, unsigned int seed    );
IppStatus ippsRandUniformInitAlloc_32f(IppsRandUniState_32f** pRandUniState, Ipp32f
low, Ipp32f high, unsigned int seed    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pRandUniState                Pointer to the structure containing parameters for the generator of
                             noise.
low                          Lower bound of the uniform distribution range.

high                         Upper bound of the uniform distribution range.

seed                         Seed value used by the pseudo-random number generation
                             algorithm.

Description
The function ippsRandUniformInitAlloc  is deprecated. This function is obsolete and will be removed in a
future release. Internal memory allocation will not be supported. Use the ippsRandUniformGetSize and
ippsRandUniformInit   functions instead. Use the following link for details: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function allocates memory and initializes the pseudo-random generator state pRandUniState. The
uniform distribution range is specified by the lower and upper bounds low and high, respectively.

   66
---------------------Page 67---------------------

                                                                   Vector Initialization Functions  4 

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pRandUniState  pointer is NULL.

ippStsMemAllocErr                 Indicates an error when there is not enough memory for the
                                  operation.

RandUniformFree
DEPRECATED. Closes the uniform distribution
generator state.

Syntax
IppStatus ippsRandUniformFree_8u(IppsRandUniState_8u* pRandUniState       );
IppStatus ippsRandUniformFree_16s(IppsRandUniState_16s* pRandUniState       );
IppStatus ippsRandUniformFree_32f(IppsRandUniState_32f* pRandUniState       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pRandUniState                Pointer to the structure containing parameters for the generator of
                             noise.

Description
The function ippsRandUniformFree is deprecated. This function is obsolete and will be removed in a future
release. Internal memory allocation will not be supported. Use the ippsRandUniformGetSize and
ippsRandUniformInit   functions instead. Use the following link for details: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function closes the noise generator state pRandUniState by freeing all memory allocated by the
function RandUniformInitAlloc.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pRandUniState  pointer is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

RandUniformInit
Initializes a noise generator with uniform distribution.

Syntax
IppStatus ippsRandUniformInit_16s(IppsRandUniState_16s* pRandUniState, Ipp16s low,
Ipp16s high, unsigned int seed   );

                                                                                           67
---------------------Page 68---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pRandUniState                Pointer to the structure containing parameters for the generator of
                             noise.
low                          Lower bound of the uniform distribution range.

high                         Upper bound of the uniform distribution range.

seed                         Seed value used by the pseudo-random number generation
                             algorithm.

Description
This function initializes the pseudo-random generator state structure pRandUniState in the external buffer.
The uniform distribution range is specified by the lower and upper bounds low and high, respectively. Before
using this function, you need to compute the size of the external buffer by using the
ippsRandUniformGetSize   function.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pRandUniState   pointer is NULL.

ippStsMemAllocErr                 Indicates an error when there is not enough memory for the
                                  operation.

See Also
RandUniformGetSize Computes the length of the uniform distribution generator structure.

RandUniformGetSize
Computes the length of the uniform distribution
generator structure.

Syntax
IppStatus ippsRandUniformGetSize_16s(int* pRandUniStateSize       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pRandUniStateSize            Pointer to the computed value of size in bytes of the generator
                             specification structure.

   68
---------------------Page 69---------------------

                                                                   Vector Initialization Functions  4 

Description
This function computes the length (in bytes) pRandUniStateSize of the uniform distribution generator
structure that is used by the ippsRandUniformInit function.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pointer pRandUniStateSize  is
                                  NULL .

See Also
RandUniformInit Initializes a noise generator with uniform distribution.

RandUniform
Generates the pseudo-random samples with a uniform
distribution.

Syntax
IppStatus ippsRandUniform_8u(Ipp8u* pDst, int len, IppsRandUniState_8u* pRandUniState         );
IppStatus ippsRandUniform_16s(Ipp16s* pDst, int len, IppsRandUniState_16s*
pRandUniState );
IppStatus ippsRandUniform_32f(Ipp32f* pDst, int len, IppsRandUniState_32f*
pRandUniState );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                         Pointer to the array which stores the samples.

len                          Number of samples to be computed.

pRandUniState                Pointer to the structure containing parameters for the generator of
                             noise.

Description
This function generates len pseudo-random samples with a uniform distribution and stores them in the array
pDst. Initial parameters of the generator are set in the generator state structure pRandUniState. Before
calling ippsRandUniform, you must initialize the generator state by calling the function 
RandUniformInitAlloc.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pDst or pRandUniState  pointer is
                                  NULL.
ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

                                                                                           69
---------------------Page 70---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Example
The code example below demonstrates how to use the function ippsRandUniform.
void func_randuniform()
{
    IppsRandUniState_16s* pRUS;
    Ipp16s low, high;
    low = -4096;
    high = 4095;
    unsigned int seed = 0;
    Ipp16s* pDst;
    int len = 512;
    IppStatus status;

    status = ippsRandUniformInitAlloc_16s(&pRUS,low,high,seed);
    if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status));

    status = ippsRandUniform_16s(pDst,len, pRUS);
    if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status));
}

result: 

 

 

RandUniform_Direct
DEPRECATED. Generates the pseudo-random samples
with a uniform distribution in direct mode.

Syntax
IppStatus ippsRandUniform_Direct_16s(Ipp16s* pDst, int len, Ipp16s low, Ipp16s high,
unsigned int* pSeed  );

   70
---------------------Page 71---------------------

                                                                   Vector Initialization Functions  4 

IppStatus ippsRandUniform_Direct_32f(Ipp32f* pDst, int len, Ipp32f low, Ipp32f high,
unsigned int* pSeed  );
IppStatus ippsRandUniform_Direct_64f(Ipp64f* pDst, int len, Ipp64f low, Ipp64f high,
unsigned int* pSeed  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSeed                        Pointer to the seed value used by the pseudo-random number
                             generation algorithm.
low                          Lower bound of the uniform distribution range.

high                         Upper bound of the uniform distribution range.

pDst                         Pointer to the array which stores the samples.

len                          Number of samples to be computed.

Description
The function iippsRandUniform_Direct  is deprecated. This function is obsolete and will be removed in a
future release. For information about the functions that you should use instead, see the table below.
 Deprecated Function                              Use Instead

 ippsRandUniform_Direct_16s                       ippsRandUniform_16s

 ippsRandUniform_Direct_32f                       ippsRandUniform_32f

 ippsRandUniform_Direct_64f                       ippsRandUniform_64f

For more information about the deprecation process use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function generates len pseudo-random samples with a uniform distribution and stores them in the array
pDst. This function does not require to initialize the generator state structure in advance. All parameters of
the pseudo-random number generator are set directly in the function.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pDst  or pSeed pointer is NULL.

ippStsSizeErr                     Indicates an error when  len is less than or equal to 0.

Gaussian Distribution Functions
This section describes the function that generates pseudo-random samples with Gaussian distribution.

                                                                                            71
---------------------Page 72---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

RandGaussInitAlloc
DEPRECATED. Allocates memory and initializes a noise
generator with Gaussian distribution.
IppStatus ippsRandGaussInitAlloc_8u(IppsRandGaussState_8u** pRandGaussState, Ipp8u
mean, Ipp8u stdDev, unsigned int seed    );
IppStatus ippsRandGaussInitAlloc_16s(IppsRandGaussState_16s** pRandGaussState, Ipp16s
mean, Ipp16s stdDev, unsigned int seed    );
IppStatus ippsRandGaussInitAlloc_32f(IppsRandGaussState_32f** pRandGaussState, Ipp32f
mean, Ipp32f stdDev, unsigned int seed    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pRandGaussState              Pointer to the structure containing parameters for the generator of noise.

mean                         Mean of the Gaussian distribution.

stdDev                       Standard deviation of the Gaussian distribution.

seed                         Seed value used by the pseudo-random number generator algorithm.

Description
The function ippsRandGaussInitAlloc  is deprecated. This function is obsolete and will be removed in a
future release. Internal memory allocation will not be supported. Use the ippsRandGaussGetSize and
ippsRandGaussInit   functions instead. Use the following link for details: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function allocates memory and initializes the pseudo-random generator state structure
pRandGaussState . This structure contains parameters of the required noise generator that are specified by
the mean, stdDev and seed values.

Return Values

ppStsNoErr                        Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pRandGaussState   pointer is NULL.

ippStsMemAllocErr                 Indicates an error when there is not enough memory for the
                                  operation.

RandGaussFree
DEPRECATED. Closes the Gaussian distribution
generator state.

Syntax
IppStatus ippsRandGaussFree_8u(IppsRandGaussState_8u* pRandGaussState        );
IppStatus ippsRandGaussFree_16s(IppsRandGaussState_16s* pRandGaussState        );

   72
---------------------Page 73---------------------

                                                                   Vector Initialization Functions  4 

IppStatus ippsRandGaussFree_32f(IppsRandGaussState_32f* pRandGaussState        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pRandGaussState              Pointer to the structure containing parameters for the generator of
                             noise.

Description
The function ippsRandGaussFree is deprecated. This function is obsolete and will be removed in a future
release. Internal memory allocation will not be supported. Use the ippsRandGaussGetSize and
ippsRandGaussInit   functions instead. Use the following link for details: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function closes the noise generator state pRandGaussState by freeing all memory allocated by the
function RandGaussInitAlloc.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pRandGaussState   pointer is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

RandGaussInit
Initializes a noise generator with Gaussian
distribution.

Syntax
IppStatus ippsRandGaussInit_16s(IppsRandGaussState_16s* pRandGaussState, Ipp16s mean,
Ipp16s stdDev, unsigned int seed   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pRandGaussState              Pointer to the structure containing parameters for the generator of
                             noise.
mean                         Mean of the Gaussian distribution.

stdDev                       Standard deviation of the Gaussian distribution.

                                                                                            73
---------------------Page 74---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

seed                         Seed value used by the pseudo-random number generator
                             algorithm.

Description
This function initializes the pseudo-random generator state structure pRandGaussState in the external
buffer. This structure contains parameters of the required noise generator that are specified by the mean,
stdDev, and seed values. Before using this function, you need to compute the size of the buffer by calling
the ippsRandGaussGetSize   function.

Return Values

ppStsNoErr                        Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pRandGaussState   pointer is NULL.

ippStsMemAllocErr                 Indicates an error when there is not enough memory for the
                                  operation.

See Also
RandGaussGetSize Computes the length of the Gaussian distribution generator structure.

RandGaussGetSize
Computes the length of the Gaussian distribution
generator structure.

Syntax
IppStatus ippsRandGaussGetSize_16s(int* pRandGaussStateSize       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pRandGaussStateSize          Pointer to the size, in bytes, of the generator specification structure.

Description
This function computes the length (in bytes) pRandGaussStateSize of the uniform distribution generator
structure that is used by the ippsRandGaussInit function.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pointer  pRandGaussStateSize   is
                                  NULL .

See Also
RandGaussInit Initializes a noise generator with Gaussian distribution.

   74
---------------------Page 75---------------------

                                                                 Vector Initialization Functions  4 

RandGauss
Generates the pseudo-random samples with a
Gaussian distribution.

Syntax
IppStatus ippsRandGauss_8u(Ipp8u* pDst, int len, IppsRandGaussState_8u*
pRandGaussState );
IppStatus ippsRandGauss_16s(Ipp16s* pDst, int len, IppsRandGaussState_16s*
pRandGaussState );
IppStatus ippsRandGauss_32f(Ipp32f* pDst, int len, IppsRandGaussState_32f*
pRandGaussState );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                        Pointer to the array which stores the samples.

len                         Number of samples to be computed.

pRandGaussState             Pointer to the structure containing parameters of the noise
                            generator.

Description
This function generates len pseudo-random samples with a Gaussian distribution and stores them in the
array pDst. The initial parameters of the generator are set in the generator state structure
pRandGaussState . Before calling ippsRandGauss, you must initialize the generator state by calling the 
RandGaussInitAlloc function.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pRandGaussState  pointer is NULL.

ippStsContextMatchErr            Indicates an error when the state identifier is incorrect.

RandGauss_Direct
DEPRECATED. Generates pseudo-random samples
with a Gaussian distribution in the direct mode.

Syntax
IppStatus ippsRandGauss_Direct_16s(Ipp16s* pDst, int len, Ipp16s mean, Ipp16s stdev,
unsigned int* pSeed );
IppStatus ippsRandGauss_Direct_32f(Ipp32f* pDst, int len, Ipp32f mean, Ipp32f stdev,
unsigned int* pSeed );
IppStatus ippsRandGauss_Direct_64f(Ipp64f* pDst, int len, Ipp64f mean, Ipp64f stdev,
unsigned int* pSeed );

                                                                                         75
---------------------Page 76---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                          Pointer to the array which stores the samples.

pSeed                         Pointer to the seed value used by the pseudo-random number
                              generation algorithm.
len                           Number of samples to be computed.

mean                          Mean of the Gaussian distribution.

stdev                         Standard deviation of the Gaussian distribution.

Description
The function ippsRandGauss_Direct  is deprecated. This function is obsolete and will be removed in a future
release. For information about the functions that you should use instead, see the table below.
 Deprecated Function                               Use Instead

 ippsRandGauss_Direct_16s                          ippsRandGauss_16s

 ippsRandGauss_Direct_32f                          ippsRandGauss_32f

 ippsRandGauss_Direct_64f                          ippsRandGauss_64f

For more information about the deprecation process use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function generates len pseudo-random samples with a Gaussian distribution, and stores them in the
array pDst.This function does not require to initialize the generator state structure in advance. All
parameters of the pseudo-random number generator are set directly in the function.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the pDst  or pSeed pointer is NULL.

ippStsSizeErr                      Indicates an error when len  is less than or equal to zero.

Example
The code example below demonstrates how to use the function ippsRandGauss_Direct.
void func_gauss_direct() 
{
    Ipp16s* pDst;
    int len = 512;
    Ipp16s mean = 0;
    Ipp16s stdev = 2047;
    unsigned int Seed = 0;
    IppStatus status;

    status = ippsRandGauss_Direct_16s(pDst, len, mean, stdev, &Seed);

   76
---------------------Page 77---------------------

                                                                Vector Initialization Functions  4 
    if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status)); 
}

Result:
 

 

Special Vector Functions
The functions described in this section create special vectors that can be used as a test signals to examine
the effect of applying different signal processing functions.

VectorJaehne
Creates a Jaehne vector.

Syntax
IppStatus ippsVectorJaehne_8u(Ipp8u* pDst, int len, Ipp8u magn    );
IppStatus ippsVectorJaehne_16u(Ipp16u* pDst, int len, Ipp16u magn    );
IppStatus ippsVectorJaehne_16s(Ipp16s* pDst, int len, Ipp16s magn    );
IppStatus ippsVectorJaehne_32s(Ipp32s* pDst, int len, Ipp32s magn    );
IppStatus ippsVectorJaehne_32f(Ipp32f* pDst, int len, Ipp32f magn    );
IppStatus ippsVectorJaehne_64f(Ipp64f* pDst, int len, Ipp64f magn    );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsVectorJaehne_8s(Ipp8s* pDst, int len, Ipp8s magn    );
IppStatus ippsVectorJaehne_32u(Ipp32u* pDst, int len, Ipp32u magn    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                        Pointer to the destination vector.

                                                                                        77
---------------------Page 78---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

len                         Number of elements in the vector.

magn                        Magnitude of the signal to be generated.

Description
Functions ippsVectorJaehne_8s and ippsVectorJaehne_32u  are deprecated. These functions are
obsolete and will be removed in a future release. Use the following link for details: http://software.intel.com/
sites/products/ipp-deprecated-features-feedback/.
This function creates a Jaehne vector and stores the result in pDst. The magnitude magn must be positive.
The function generates the sinusoid with a variable frequency. The computation is performed as follows:

pDst[n] = magn * sin ((0.5πn  2)/len), 0 ≤ n < len

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrcDst pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

ippStsJaehneErr                  Indicates an error when magn is negative.

Example
The code example below shows how to use the function ippsVectorJaehne.
IppStatus Jaehne (void)
{
    Ipp16s buf[100] ;
    return ippsVectorJaehne_16s ( buf, 100, 255 ); 
}

VectorSlope
Creates a slope vector.

Syntax
IppStatus ippsVectorSlope_8u(Ipp8u* pDst, int len, Ipp32f offset, Ipp32f slope       );
IppStatus ippsVectorSlope_16u(Ipp16u* pDst, int len, Ipp32f offset, Ipp32f slope       );
IppStatus ippsVectorSlope_16s(Ipp16s* pDst, int len, Ipp32f offset, Ipp32f slope       );
IppStatus ippsVectorSlope_32u(Ipp32u* pDst, int len, Ipp64f offset, Ipp64f slope       );
IppStatus ippsVectorSlope_32s(Ipp32s* pDst, int len, Ipp64f offset, Ipp64f slope       );
IppStatus ippsVectorSlope_32f(Ipp32f* pDst, int len, Ipp32f offset, Ipp32f slope       );
IppStatus ippsVectorSlope_64f(Ipp64f* pDst, int len, Ipp64f offset, Ipp64f slope       );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsVectorSlope_8s(Ipp8s* pDst, int len, Ipp32f offset, Ipp32f slope       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

   78
---------------------Page 79---------------------

                                                                 Vector Initialization Functions  4 

Parameters

pDst                        Pointer to the destination vector.

len                         Number of elements in the vector.

offset                      Offset value.

slope                       Slope coefficient.

Description
The function ippsVectorSlope_8s is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function creates a slope vector and stores the result in pDst. The destination vector elements are
computed according to the following formula:

pDst[n] = offset + slope*n  , 0 ≤ n < len.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pDst pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

VectorRamp
DEPRECATED. Creates a ramp vector.

Syntax
IppStatus ippsVectorRamp_8u(Ipp8u* pDst, int len, float offset, float slope      );
IppStatus ippsVectorRamp_8s(Ipp8s* pDst, int len, float offset, float slope      );
IppStatus ippsVectorRamp_16u(Ipp16u* pDst, int len, float offset, float slope      );
IppStatus ippsVectorRamp_16s(Ipp16s* pDst, int len, float offset, float slope      );
IppStatus ippsVectorRamp_32u(Ipp32u* pDst, int len, float offset, float slope      );
IppStatus ippsVectorRamp_32s(Ipp32s* pDst, int len, float offset, float slope      );
IppStatus ippsVectorRamp_32f(Ipp32f* pDst, int len, float offset, float slope      );
IppStatus ippsVectorRamp_64f(Ipp64f* pDst, int len, float offset, float slope      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pDst                        Pointer to the destination vector.

len                         Number of elements in the vector.

                                                                                         79
---------------------Page 80---------------------

 4    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

offset                         Offset value.

slope                          Slope coefficient.

Description
The function ippsVectorRamp   is deprecated. This function is obsolete and will be removed in a future
release. Use Slope function instead of this one. Use the following link for details: http://software.intel.com/
sites/products/ipp-deprecated-features-feedback/.
This function creates a ramp vector and stores the result in pDst. The destination vector elements are
computed according to the following formula:
pDst[n] = offset + slope*n     , 0 ≤ n < len  .
Note that this function is similar to the function VectorSlope, but the linear transform coefficients offset and
slope  have floating-point values for all flavors of the function ippsVectorRamp. In most cases the use of
the function ippsVectorSlope   is more preferrable.

Return Values

ippStsNoErr                          Indicates no error.

ippStsNullPtrErr                     Indicates an error when the   pDst  pointer is NULL.

ippStsSizeErr                        Indicates an error when   len  is less than or equal to 0.

   80
---------------------Page 81---------------------

Essential Functions                                                               5

This chapter describes the Intel®
                                functions that perform logical and shift, arithmetic, conversion,
windowing, and statistical operations.

Logical and Shift Functions
This section describes the Intel     signal processing functions that perform logical and shift operations on
vectors. Logical and shift functions are only defined for integer arguments.
For binary logical operations AND, OR and XOR, the following functions are provided:
AndC, OrC, XorC for vector-scalar operations;
And, Or, Xor for vector-vector operations.

AndC
Computes the bitwise AND of a scalar value and each
element of a vector.

Syntax
IppStatus ippsAndC_8u(const Ipp8u* pSrc, Ipp8u val, Ipp8u* pDst, int len     );
IppStatus ippsAndC_16u(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len      );
IppStatus ippsAndC_32u(const Ipp32u* pSrc, Ipp32u val, Ipp32u* pDst, int len      );
IppStatus ippsAndC_8u_I(Ipp8u val, Ipp8u* pSrcDst, int len    );
IppStatus ippsAndC_16u_I(Ipp16u val, Ipp16u* pSrcDst, int len     );
IppStatus ippsAndC_32u_I(Ipp32u val, Ipp32u* pSrcDst, int len     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

val                         Input scalar value.

pSrc                        Pointer to the source vector.

pDst                        Pointer to the destination vector.

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

                                                                                         81
---------------------Page 82---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Description
This function computes the bitwise AND of a scalar value val and each element of the vector pSrc, and
stores the result in pDst.
The in-place flavors of ippsAndC compute the bitwise AND of a scalar value val and each element of the
vector pSrcDst and store the result in pSrcDst.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pSrc , pDst, or pSrcDst pointer is
                                  NULL.
ippStsSizeErr                     Indicates an error when len  is less than or equal to 0.

And
Computes the bitwise AND of two vectors.

Syntax
IppStatus ippsAnd_8u(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, int len         );
IppStatus ippsAnd_16u(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst, int len          );
IppStatus ippsAnd_32u(const Ipp32u* pSrc1, const Ipp32u* pSrc2, Ipp32u* pDst, int len          );
IppStatus ippsAnd_8u_I(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len       );
IppStatus ippsAnd_16u_I(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len        );
IppStatus ippsAnd_32u_I(const Ipp32u* pSrc, Ipp32u* pSrcDst, int len        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2                 Pointers to the two source vectors.

pDst                         Pointer to the destination vector.

pSrc                         Pointer to the source vector for the in-place operation.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function computes the bitwise AND of the corresponding elements of the vectors pSrc1 and pSrc2, and
stores the result in the vector pDst.
The in-place flavors of ippsAnd compute the bitwise AND of the corresponding elements of the vectors pSrc
and pSrcDst and store the result in the vector pSrcDst.

   82
---------------------Page 83---------------------

                                                                          Essential Functions  5 

Return Values

ippStsNoErr                      Indicates no error.

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

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

OrC
Computes the bitwise OR of a scalar value and each
element of a vector.

Syntax
IppStatus ippsOrC_8u(const Ipp8u* pSrc, Ipp8u val, Ipp8u* pDst, int len      );
IppStatus ippsOrC_16u(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len       );
IppStatus ippsOrC_32u(const Ipp32u* pSrc, Ipp32u val, Ipp32u* pDst, int len       );
IppStatus ippsOrC_8u_I(Ipp8u val, Ipp8u* pSrcDst, int len     );
IppStatus ippsOrC_16u_I(Ipp16u val, Ipp16u* pSrcDst, int len     );
IppStatus ippsOrC_32u_I(Ipp16u val, Ipp32u* pSrcDst, int len     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

val                         Input scalar value.

pSrc                        Pointer to the source vector.

pDst                        Pointer to the destination vector.

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

Description
This function computes the bitwise OR of a scalar value val and each element of the vector pSrc, and stores
the result in pDst.
The in-place flavors of ippsOrC compute the bitwise OR of a scalar value val and each element of the vector
pSrcDst and store the result in pSrcDst.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc, pDst, or pSrcDst  pointer is
                                 NULL .

                                                                                          83
---------------------Page 84---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsSizeErr                     Indicates an error when len is less than or equal to 0.

Or
Computes the bitwise OR of two vectors.

Syntax
IppStatus ippsOr_8u(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, int len        );
IppStatus ippsOr_16u(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst, int len         );
IppStatus ippsOr_32u(const Ipp32u* pSrc1, const Ipp32u* pSrc2, Ipp32u* pDst, int len         );
IppStatus ippsOr_8u_I(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len      );
IppStatus ippsOr_16u_I(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len       );
IppStatus ippsOr_32u_I(const Ipp32u* pSrc, Ipp32u* pSrcDst, int len       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2                 Pointers to the two source vectors.

pDst                         Pointer to the destination vector.

pSrc                         Pointer to the source vector for the in-place operation.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function computes the bitwise OR of the corresponding elements of the vectors pSrc1 and pSrc2, and
stores the result in the vector pDst.
The in-place flavors of ippsOr compute the bitwise OR of the corresponding elements of the vectors pSrc
and pSrcDst and store the result in the vector pSrcDst.

Return Values

ippStsNoErr                       Indicates no error.

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

ippStsSizeErr                     Indicates an error when len is less than or equal to 0.

XorC
Computes the bitwise XOR of a scalar value and each
element of a vector.

   84
---------------------Page 85---------------------

                                                                        Essential Functions  5 

Syntax
IppStatus ippsXorC_8u(const Ipp8u* pSrc, Ipp8u val, Ipp8u* pDst, int len     );
IppStatus ippsXorC_16u(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len     );
IppStatus ippsXorC_32u(const Ipp32u* pSrc, Ipp32u val, Ipp32u* pDst, int len     );
IppStatus ippsXorC_8u_I(Ipp8u val, Ipp8u* pSrcDst, int len    );
IppStatus ippsXorC_16u_I(Ipp16u val, Ipp16u* pSrcDst, int len    );
IppStatus ippsXorC_32u_I(Ipp32u val, Ipp32u* pSrcDst, int len    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

val                         Input scalar value.

pSrc                        Pointer to the source vector.

pDst                        Pointer to the destination vector.

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

Description
This function computes the bitwise XOR of a scalar value val and each element of the vector pSrc, and
stores the result in pDst.
The in-place flavors of ippsXorC compute the bitwise XOR of a scalar value val and each element of the
vector pSrcDst and store the result in pSrcDst.

Return Values

ippStsNoErr                     Indicates no error.

ippStsNullPtrErr                Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                NULL .
ippStsSizeErr                   Indicates an error when len is less than or equal to 0.

Xor
Computes the bitwise XOR of two vectors.

Syntax
IppStatus ippsXor_8u(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, int len     );
IppStatus ippsXor_16u(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst, int len      );
IppStatus ippsXor_32u(const Ipp32u* pSrc1, const Ipp32u* pSrc2, Ipp32u* pDst, int len      );
IppStatus ippsXor_8u_I(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len    );

                                                                                        85
---------------------Page 86---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsXor_16u_I(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len      );
IppStatus ippsXor_32u_I(const Ipp32u* pSrc, Ipp32u* pSrcDst, int len      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2                 Pointers to the two source vectors.

pDst                         Pointer to the destination vector.

pSrc                         Pointer to the source vector for the in-place operation.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function computes the bitwise XOR of the corresponding elements of the vectors pSrc1 and pSrc2, and
stores the result in the vector pDst.
The in-place flavors of ippsXor compute the bitwise XOR of the corresponding elements of the vectors pSrc
and pSrcDst and store the result in the vector pSrcDst.

Return Values

ippStsNoErr                      Indicates no error.

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

ippStsSizeErr                    Indicates an error when len  is less than or equal to 0.

Not
Computes the bitwise NOT of the vector elements.

Syntax
IppStatus ippsNot_8u(const Ipp8u* pSrc, Ipp8u* pDst, int len      );
IppStatus ippsNot_16u(const Ipp16u* pSrc, Ipp16u* pDst, int len      );
IppStatus ippsNot_32u(const Ipp32u* pSrc, Ipp32u* pDst, int len      );
IppStatus ippsNot_8u_I(Ipp8u* pSrcDst, int len    );
IppStatus ippsNot_16u_I(Ipp16u* pSrcDst, int len    );
IppStatus ippsNot_32u_I(Ipp32u* pSrcDst, int len    );

Include Files
ipps.h

   86
---------------------Page 87---------------------

                                                                         Essential Functions  5 

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.

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

Description
This function computes the bitwise NOT of the corresponding elements of the vectors pSrc, and stores the
result in the vector pDst.
The in-place flavors of ippsNot compute the bitwise NOT of the corresponding elements of the vector
pSrcDst and store the result in the vector pSrcDst.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                 NULL.
ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

LShiftC
Shifts bits in vector elements to the left.

Syntax
IppStatus ippsLShiftC_8u(const Ipp8u* pSrc, int val, Ipp8u* pDst, int len      );
IppStatus ippsLShiftC_16s(const Ipp16s* pSrc, int val, Ipp16s* pDst, int len      );
IppStatus ippsLShiftC_16u(const Ipp16u* pSrc, int val, Ipp16u* pDst, int len      );
IppStatus ippsLShiftC_32s(const Ipp32s* pSrc, int val, Ipp32s* pDst, int len      );
IppStatus ippsLShiftC_8u_I(int val, Ipp8u* pSrcDst, int len     );
IppStatus ippsLShiftC_16u_I(int val, Ipp16u* pSrcDst, int len     );
IppStatus ippsLShiftC_16s_I(int val, Ipp16s* pSrcDst, int len     );
IppStatus ippsLShiftC_32s_I(int val, Ipp32s* pSrcDst, int len     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                         87
---------------------Page 88---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

val                         Number of bits by which the function shifts each element of the
                            vector pSrc  or pSrcDst.
pSrc                        Pointer to the source vector.

pDst                        Pointer to the destination vector.

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

Description
This function shifts each element of the vector pSrc by val bits to the left, and stores the result in pDst.
The in-place flavors of ippsLShiftC shift each element of the vector pSrcDst by val bits to the left and
store the result in pSrcDst.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc, pDst, or pSrcDst  pointer is
                                 NULL  .
ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

RShiftC
Shifts bits in vector elements to the right.

Syntax
IppStatus ippsRShiftC_8u(const Ipp8u* pSrc, int val, Ipp8u* pDst, int len       );
IppStatus ippsRShiftC_16s(const Ipp16s* pSrc, int val, Ipp16s* pDst, int len       );
IppStatus ippsRShiftC_16u(const Ipp16u* pSrc, int val, Ipp16u* pDst, int len       );
IppStatus ippsRShiftC_32s(const Ipp32s* pSrc, int val, Ipp32s* pDst, int len       );
IppStatus ippsRShiftC_8u_I(int val, Ipp8u* pSrcDst, int len     );
IppStatus ippsRShiftC_16u_I(int val, Ipp16u* pSrcDst, int len     );
IppStatus ippsRShiftC_16s_I(int val, Ipp16s* pSrcDst, int len     );
IppStatus ippsRShiftC_32s_I(int val, Ipp32s* pSrcDst, int len     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

val                         Number of bits by which the function shifts each element of the
                            vector pSrc  or pSrcDst.

   88
---------------------Page 89---------------------

                                                                              Essential Functions  5  

pSrc                          Pointer to the source vector.

pDst                          Pointer to the destination vector.

pSrcDst                       Pointer to the source and destination vector for the in-place
                              operation.
len                           Number of elements in the vector.

Description
This function shifts each element of the vector pSrc by val bits to the right, and stores the result in pDst.
The in-place flavors of ippsRShiftC shift each element of the vector pSrcDst by val bits to the right and
store the result in pSrcDst.
Note that the arithmetic shift is realized for signed data, and the logical shift for unsigned data.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the   pSrc, pDst, or pSrcDst   pointer is
                                   NULL .
ippStsSizeErr                      Indicates an error when   len is less than or equal to zero.

Example
The code example below shows how the logical and shift functions can be used in the saturate operation. The
data are converted to the unsigned char range [0...255].
void saturate(void) {
      Ipp16s x[8] = {1000, -257, 127, 4, 5, 0, 7, 8}, lo[8], hi[8];
      IppStatus status = ippsNot_16u((Ipp16u*)x, (Ipp16u*)lo, 8);
      ippsRShiftC_16s_I(15, lo, 8);
      ippsCopy_16s(x, hi, 8);
      ippsSubCRev_16s_ISfs(255, hi, 8, 0);
      ippsRShiftC_16s_I(15, hi, 8);
      ippsAnd_16u_I((Ipp16u*)lo, (Ipp16u*)x, 8);
      ippsOr_16u_I((Ipp16u*)hi, (Ipp16u*)x, 8);
      ippsAndC_16u_I(255, (Ipp16u*)x, 8);
      printf_16s(“saturate =”, x, 8, status); 
} 
Output:
    saturate =  255 0 127 4 5 0 7 8

Arithmetic Functions

This section describes the Intel     signal processing functions that perform vector arithmetic operations on
vectors. The arithmetic functions include basic element-wise arithmetic operations between vectors, as well
as more complex calculations such as computing absolute values, square and square root, natural logarithm
and exponential of vector elements.
Intel     software provides two versions of each function. One version performs the operation in-place, while
the other stores the results of the operation in a different destination vector, that is, executes an out-of-
place operation.

                                                                                               89
---------------------Page 90---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

AddC
Adds a constant value to each element of a vector.

Syntax
Case 1: Not-in-place operations on floating point data.
IppStatus ippsAddC_32f(const Ipp32f* pSrc, Ipp32f val, Ipp32f* pDst, int len  );
IppStatus ippsAddC_64f(const Ipp64f* pSrc, Ipp64f val, Ipp64f* pDst, int len  );
IppStatus ippsAddC_32fc(const Ipp32fc* pSrc, Ipp32fc val,Ipp32fc* pDst, int len  );
IppStatus ippsAddC_64fc(const Ipp64fc* pSrc, Ipp64fc val, Ipp64fc* pDst, int len  );
Case 2: Not-in-place operations on integer data.
IppStatus ippsAddC_8u_Sfs(const Ipp8u* pSrc, Ipp8u val, Ipp8u* pDst, int len, int
scaleFactor);
IppStatus ippsAddC_16s_Sfs(const Ipp16s* pSrc, Ipp16s val, Ipp16s* pDst, int len, int
scaleFactor);
IppStatus ippsAddC_16u_Sfs(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len, int
scaleFactor);
IppStatus ippsAddC_32s_Sfs(const Ipp32s* pSrc, Ipp32s val, Ipp32s* pDst, int len, int
scaleFactor);
IppStatus ippsAddC_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc val, Ipp16sc* pDst, int len,
int scaleFactor);
IppStatus ippsAddC_32sc_Sfs(const Ipp32sc* pSrc, Ipp32sc val, Ipp32sc* pDst, int len,
int scaleFactor);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsAddC_64u_Sfs(const Ipp64u* pSrc, Ipp64u val, Ipp64u* pDst, Ipp32u len,
int scaleFactor, IppRoundMode rndMode );
IppStatus ippsAddC_64s_Sfs(const Ipp64s* pSrc, Ipp64s val, Ipp64s* pDst, Ipp32u len,
int scaleFactor, IppRoundMode rndMode );
Case 3: In-place operations on floating point data.
IppStatus ippsAddC_16s_I(Ipp16s val, Ipp16s* pSrcDst, int len  );
IppStatus ippsAddC_32f_I(Ipp32f val, Ipp32f* pSrcDst, int len  );
IppStatus ippsAddC_64f_I(Ipp64f val, Ipp64f* pSrcDst, int len  );
IppStatus ippsAddC_32fc_I(Ipp32fc val, Ipp32fc* pSrcDst, int len  );
IppStatus ippsAddC_64fc_I(Ipp64fc val, Ipp64fc* pSrcDst, int len  );
Case 4: In-place operations on integer data.
IppStatus ippsAddC_8u_ISfs(Ipp8u val, Ipp8u* pSrcDst, int len, int scaleFactor  );
IppStatus ippsAddC_16u_ISfs(Ipp16u val, Ipp16u* pSrcDst, int len, int scaleFactor  );
IppStatus ippsAddC_16s_ISfs(Ipp16s val, Ipp16s* pSrcDst, int len, int scaleFactor  );
IppStatus ippsAddC_32s_ISfs(Ipp32s val, Ipp32s* pSrcDst, int len, int scaleFactor  );
IppStatus ippsAddC_16sc_ISfs(Ipp16sc val, Ipp16sc* pSrcDst, int len, int scaleFactor  );
IppStatus ippsAddC_32sc_ISfs(Ipp32sc val, Ipp32sc* pSrcDst, int len, int scaleFactor  );

   90
---------------------Page 91---------------------

                                                                                 Essential Functions  5  

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h  , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                           Pointer to the source vector.

val                            Scalar value used to increment each element of the source vector.

pDst                           Pointer to the destination vector.

pSrcDst                        Pointer to the source and destination vector for the in-place operation.

len                            Number of elements in the vector.

scaleFactor                    Scale factor, refer to Integer Scaling.

rndMode                        Rounding mode, the following values are possible:

                               ippRndZero   floating-point values are truncated to zero

                               ippRndNear   floating-point values are rounded to the nearest even integer
                               when the fractional part equals 0.5; otherwise they are rounded to the
                               nearest integer

                               ippRndFinancial    floating-point values are rounded down to the nearest
                               integer when the fractional part is less than 0.5, or rounded up to the
                               nearest integer if the fractional part is equal or greater than 0.5.

Description
Functions ippsAddC_64s_Sfs   and ippsAddC_64u_Sfs     are deprecated. These functions are obsolete and will
be removed in a future release.
For more information about the deprecation process, use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function adds a value val to each element of the source vector pSrc, and stores the result in the
destination vector pDst.
The in-place flavors of ippsAddC add a value val to each element of the vector pSrcDst, and store the
result in pSrcDst.
Functions with Sfs suffixe perform scaling of the result value in accordance with the scaleFactor value. If
the output value exceeds the data range, the result is saturated.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when the    pSrc, pDst , or pSrcDst  pointer is
                                    NULL .
ippStsSizeErr                       Indicates an error when    len is less than or equal to zero.

                                                                                                  91
---------------------Page 92---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

See Also
Integer Scaling

Add
Adds the elements of two vectors.

Syntax
Case 1. Not-in-place operations on floating point data, and integer data without scaling.
IppStatus ippsAdd_16s(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst, int len   );
IppStatus ippsAdd_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, Ipp32f* pDst, int len   );
IppStatus ippsAdd_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, Ipp64f* pDst, int len   );
IppStatus ippsAdd_32fc(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, Ipp32fc* pDst, int
len);
IppStatus ippsAdd_64fc(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, Ipp64fc* pDst, int
len);
IppStatus ippsAdd_8u16u(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp16u* pDst, int len   );
THE FOLLOWING FUNCTIONS ARE DEPRECATED
IppStatus ippsAdd_16u(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst, int len   );
IppStatus ippsAdd_32u(const Ipp32u* pSrc1, const Ipp32u* pSrc2, Ipp32u* pDst, int len   );
IppStatus ippsAdd_16s32f(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp32f* pDst, int
len);
Case 2. Not-in-place operations on integer data with scaling.
IppStatus ippsAdd_8u_Sfs(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, int len,
int scaleFactor);
IppStatus ippsAdd_16u_Sfs(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst, int
len, int scaleFactor);
IppStatus ippsAdd_16s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst, int
len, int scaleFactor);
IppStatus ippsAdd_32s_Sfs(const Ipp32s* pSrc1, const Ipp32s* pSrc2, Ipp32s* pDst, int
len, int scaleFactor);
IppStatus ippsAdd_16sc_Sfs(const Ipp16sc* pSrc1, const Ipp16sc* pSrc2, Ipp16sc* pDst,
int len, int scaleFactor);
IppStatus ippsAdd_32sc_Sfs(const Ipp32sc* pSrc1, const Ipp32sc* pSrc2, Ipp32sc* pDst,
int len, int scaleFactor);
THE FOLLOWING FUNCTION IS DEPRECATED
IppStatus ippsAdd_64s_Sfs(const Ipp64s* pSrc1, const Ipp64s* pSrc2, Ipp64s* pDst, int
len, int scaleFactor);
Case 3. In-place operations on floating point data, and integer data without scaling.
IppStatus ippsAdd_16s_I(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len  );
IppStatus ippsAdd_32f_I(const Ipp32f* pSrc, Ipp32f* pSrcDst, int len  );
IppStatus ippsAdd_64f_I(const Ipp64f* pSrc, Ipp64f* pSrcDst, int len  );
IppStatus ippsAdd_32fc_I(const Ipp32fc* pSrc, Ipp32fc* pSrcDst, int len  );
IppStatus ippsAdd_64fc_I(const Ipp64fc* pSrc, Ipp64fc* pSrcDst, int len  );

   92
---------------------Page 93---------------------

                                                                           Essential Functions  5 

IppStatus ippsAdd_16s32s_I(const Ipp16s* pSrc, Ipp32s* pSrcDst, int len        );
Case 4. In-place operations on integer data with scaling.
IppStatus ippsAdd_8u_ISfs(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len, int scaleFactor         );
IppStatus ippsAdd_16u_ISfs(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len, int
scaleFactor );
IppStatus ippsAdd_16s_ISfs(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len, int
scaleFactor );
IppStatus ippsAdd_32s_ISfs(const Ipp32s* pSrc, Ipp32s* pSrcDst, int len, int
scaleFactor );
IppStatus ippsAdd_16sc_ISfs(const Ipp16sc* pSrc, Ipp16sc* pSrcDst, int len, int
scaleFactor );
IppStatus ippsAdd_32sc_ISfs(const Ipp32sc* pSrc, Ipp32sc* pSrcDst, int len, int
scaleFactor );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2                 Pointers to the source vectors.

pDst                         Pointer to the destination vector.

pSrc                         Pointer to the source vector for in-place operations.

pSrcDst                      Pointer to the source and destination vector for in-place operation.

len                          Number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
Functions ippsAdd_16s32f, ippsAdd_16u , ippsAdd_32u, and ippsAdd_64s_Sfs  are deprecated. These
functions are obsolete and will be removed in a future release.
For more information about the deprecation process use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function adds the elements of the vector pSrc1 to the elements of the vector pSrc2, and stores the
result in pDst.
The in-place flavors of ippsAdd add the elements of the vector pSrc to the elements of the vector pSrcDst
and store the result in pSrcDst.
Functions with Sfs suffix perform scaling of the result value in accordance with the scaleFactor value. If
the output value exceeds the data range, the result is saturated.

Return Values

ippStsNoErr                       Indicates no error.

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

                                                                                           93
---------------------Page 94---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsSizeErr                     Indicates an error when  len is less than or equal to 0.

Example
The example below demonstrates how to use the ippsAdd_16s_ISfs function. The overflow does not occur
while adding big numbers due to the scaling.
IppStatus add(void) {
      Ipp16s x[4] = {-1, 32767, 2, 30000};
      IppStatus st = ippsAdd_16s_ISfs(x, x, 4, 1);
      printf_16s(“add =”, x, 4, st);
      return st;
}

Output:
add = -1 32767 2 30000

See Also
Integer Scaling

AddProductC
Adds product of a vector and a constant to the
accumulator vector.

Syntax
IppStatus ippsAddProductC_32f(const Ipp32f* pSrc, const Ipp32f val, Ipp32f* pSrcDst,
int len);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

val                          Pointer to the destination vector.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function multiplies each element of the source vector pSrc by a value val and adds the result to the
corresponding element of the accumulator vector pSrcDst as given by:

pSrcDst[n] = pSrcDst [n] + pSrc[n]*val, 0 ≤ n < len

Return Values

ippStsNoErr                       Indicates no error.

   94
---------------------Page 95---------------------

                                                                         Essential Functions  5 

ippStsNullPtrErr                 Indicates an error if any of the specified pointers is NULL.

ippStsSizeErr                    Indicates an error if len is less than or equal to 0.

AddProduct
Adds product of two vectors to the accumulator
vector.

Syntax
Case 1. Operations on floating point data.
IppStatus ippsAddProduct_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, Ipp32f* pSrcDst,
int len);
IppStatus ippsAddProduct_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, Ipp64f* pSrcDst,
int len);
IppStatus ippsAddProduct_32fc(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, Ipp32fc*
pSrcDst, int len );
IppStatus ippsAddProduct_64fc(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, Ipp64fc*
pSrcDst, int len );
Case 2. Operations on integer data with scaling.
IppStatus ippsAddProduct_16s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s*
pSrcDst, int len, int scaleFactor  );
IppStatus ippsAddProduct_32s_Sfs(const Ipp32s* pSrc1, const Ipp32s* pSrc2, Ipp32s*
pSrcDst, int len, int scaleFactor  );
IppStatus ippsAddProduct_16s32s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp32s*
pSrcDst, int len, int scaleFactor  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2                Pointers to the source vectors.

pSrcDst                     Pointer to the destination accumulator vector.

len                         The number of elements in the vectors.

scaleFactor                 Scale factor, refer to Integer Scaling.

Description
This function multiplies each element of the source vector pSrc1 by the corresponding element of the vector
pSrc2, and adds the result to the corresponding element of the accumulator vector pSrcDst as given by:

pSrcDst[n ] = pSrcDst[n ] + pSrc1[n ] * pSrc2[n ]    , 0 ≤ n < len.
Functions with Sfs suffixes perform scaling of the result value in accordance with the scaleFactor value. If
the output value exceeds the data range, the result becomes saturated.

                                                                                         95
---------------------Page 96---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                     Indicates no error.

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

ippStsSizeErr                   Indicates an error when len is less than or equal to 0.

MulC
Multiplies each element of a vector by a constant
value.

Syntax
Case 1. Not-in-place operations without scaling.
IppStatus ippsMulC_32f(const Ipp32f* pSrc, Ipp32f val, Ipp32f* pDst, int len   );
IppStatus ippsMulC_64f(const Ipp64f* pSrc, Ipp64f val, Ipp64f* pDst, int len   );
IppStatus ippsMulC_32fc(const Ipp32fc* pSrc, Ipp32fc val, Ipp32fc* pDst, int len   );
IppStatus ippsMulC_64fc(const Ipp64fc* pSrc, Ipp64fc val, Ipp64fc* pDst, int len   );

IppStatus ippsMulC_Low_32f16s(const Ipp32f* pSrc, Ipp32f val, Ipp16s* pDst, int len   );
Case 2. Not-in-place operations with scaling.
IppStatus ippsMulC_8u_Sfs(const Ipp8u* pSrc, Ipp8u val, Ipp8u* pDst, int len, int
scaleFactor);
IppStatus ippsMulC_16s_Sfs(const Ipp16s* pSrc, Ipp16s val, Ipp16s* pDst, int len, int
scaleFactor);
IppStatus ippsMulC_16u_Sfs(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len, int
scaleFactor);
IppStatus ippsMulC_32s_Sfs(const Ipp32s* pSrc, Ipp32s val, Ipp32s* pDst, int len, int
scaleFactor);
IppStatus ippsMulC_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc val, Ipp16sc* pDst, int len,
int scaleFactor);
IppStatus ippsMulC_32sc_Sfs(const Ipp32sc* pSrc, Ipp32sc val, Ipp32sc* pDst, int len,
int scaleFactor);
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsMulC_32f16s_Sfs(const Ipp32f* pSrc, Ipp32f val, Ipp16s* pDst, int len,
int scaleFactor);
Case 3. In-place operations without scaling.
IppStatus ippsMulC_16s_I(Ipp16s val, Ipp16s* pSrcDst, int len  );
IppStatus ippsMulC_32f_I(Ipp32f val, Ipp32f* pSrcDst, int len  );
IppStatus ippsMulC_64f_I(Ipp64f val, Ipp64f* pSrcDst, int len  );
IppStatus ippsMulC_32fc_I(Ipp32fc val, Ipp32fc* pSrcDst, int len  );
IppStatus ippsMulC_64fc_I(Ipp64fc val, Ipp64fc* pSrcDst, int len  );
Case 4. In-place operations with scaling. THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsMulC_8u_ISfs(Ipp8u val, Ipp8u* pSrcDst, int len, int scaleFactor   );
IppStatus ippsMulC_16u_ISfs(Ipp16u val, Ipp16u* pSrcDst, int len, int scaleFactor   );

   96
---------------------Page 97---------------------

                                                                            Essential Functions  5 

IppStatus ippsMulC_16s_ISfs(Ipp16s val, Ipp16s* pSrcDst, int len, int scaleFactor          );
IppStatus ippsMulC_32s_ISfs(Ipp32s val, Ipp32s* pSrcDst, int len, int scaleFactor          );
IppStatus ippsMulC_64f64s_ISfs(Ipp64f val, Ipp64s* pSrcDst, Ipp32f len, int
scaleFactor );
IppStatus ippsMulC_16sc_ISfs(Ipp16sc val, Ipp16sc* pSrcDst, int len, int scaleFactor          );
IppStatus ippsMulC_32sc_ISfs(Ipp32sc val, Ipp32sc* pSrcDst, int len, int scaleFactor          );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsMulC_64s_ISfs(Ipp64s val, Ipp64s* pSrcDst, Ipp32f len, int scaleFactor          );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

val                          The scalar value used to multiply each element of the source vector.

pDst                         Pointer to the destination vector.

pSrcDst                      Pointer to the source and destination vector for in-place operation.

len                          The number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
The function ippsMulC_64s_ISfs is deprecated. This function is obsolete and will be removed in a future
release.
The function ippsMulC_32f16s_Sfs  is deprecated. This function is obsolete and will be removed in a future
release. Use vector function with vector length = 1 instead.
For more information about the deprecation process use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function multiplies each element of the vector pSrc by a value val and stores the result in pDst.
The in-place flavors of ippsMulC multiply each element of the vector pSrcDst by a value val and store the
result in pSrcDst.
The function flavor with Low suffix in its name requires that each value of the product pSrc*val does not
exceed the Ipp32s data type range.
The function flavors with Sfs suffix perform scaling of the result value in accordance with the scaleFactor
value. If the output value exceeds the data range, the result is saturated.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pSrc, pDst, or pSrcDst pointer is
                                  NULL .

                                                                                            97
---------------------Page 98---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsSizeErr                  Indicates an error when len is less than, or equal to 0.

See Also
Integer Scaling

Mul
Multiplies the elements of two vectors.

Syntax
Case 1. Not-in-place operations on floating point and integer data without scaling.
IppStatus ippsMul_16s(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst, int len   );
IppStatus ippsMul_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, Ipp32f* pDst, int len   );
IppStatus ippsMul_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, Ipp64f* pDst, int len   );
IppStatus ippsMul_32fc(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, Ipp32fc* pDst, int
len);
IppStatus ippsMul_64fc(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, Ipp64fc* pDst, int
len);
IppStatus ippsMul_8u16u(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp16u* pDst, int len   );
IppStatus ippsMul_32f32fc(const Ipp32f* pSrc1, const Ipp32fc* pSrc2, Ipp32fc* pDst, int
len);
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsMul_16s32f(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp32f* pDst, int
len);
Case 2. Not-in-place operations on integer data with scaling.
IppStatus ippsMul_8u_Sfs(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, int len,
int scaleFactor);
IppStatus ippsMul_16u_Sfs(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst, int
len, int scaleFactor);
IppStatus ippsMul_16s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst, int
len, int scaleFactor);
IppStatus ippsMul_32s_Sfs(const Ipp32s* pSrc1, const Ipp32s* pSrc2, Ipp32s* pDst, int
len, int scaleFactor);
IppStatus ippsMul_16sc_Sfs(const Ipp16sc* pSrc1, const Ipp16sc* pSrc2, Ipp16sc* pDst,
int len, int scaleFactor);
IppStatus ippsMul_32sc_Sfs(const Ipp32sc* pSrc1, const Ipp32sc* pSrc2, Ipp32sc* pDst,
int len, int scaleFactor);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsMul_16u16s_Sfs(const Ipp16u* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst,
int len, int scaleFactor);
IppStatus ippsMul_16s32s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp32s* pDst,
int len, int scaleFactor);
IppStatus ippsMul_32s32sc_Sfs(const Ipp32s* pSrc1, const Ipp32sc* pSrc2, Ipp32sc* pDst,
int len, int scaleFactor);

   98
---------------------Page 99---------------------

                                                                      Essential Functions  5 

IppStatus ippsMul_Low_32s_Sfs(const Ipp32s* pSrc1, const Ipp32s* pSrc2, Ipp32s* pDst,
int len, int scaleFactor );
Case 3. In-place operations on floating point and integer data without scaling. THE FOLLOWING FUNCTIONS
ARE DEPRECATED:
IppStatus ippsMul_16s_I(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len  );
IppStatus ippsMul_32f_I(const Ipp32f* pSrc, Ipp32f* pSrcDst, int len  );
IppStatus ippsMul_64f_I(const Ipp64f* pSrc, Ipp64f* pSrcDst, int len  );
IppStatus ippsMul_32fc_I(const Ipp32fc* pSrc, Ipp32fc* pSrcDst, int len   );
IppStatus ippsMul_64fc_I(const Ipp64fc* pSrc, Ipp64fc* pSrcDst, int len   );
IppStatus ippsMul_32f32fc_I(const Ipp32f* pSrc, Ipp32fc* pSrcDst, int len   );
Case 4. In-place operations on integer data with scaling. THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsMul_8u_ISfs(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len, int scaleFactor   );
IppStatus ippsMul_16u_ISfs(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len, int
scaleFactor);
IppStatus ippsMul_16s_ISfs(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len, int
scaleFactor);
IppStatus ippsMul_32s_ISfs(const Ipp32s* pSrc, Ipp32s* pSrcDst, int len, int
scaleFactor);
IppStatus ippsMul_16sc_ISfs(const Ipp16sc* pSrc, Ipp16sc* pSrcDst, int len, int
scaleFactor);
IppStatus ippsMul_32sc_ISfs(const Ipp32sc* pSrc, Ipp32sc* pSrcDst, int len, int
scaleFactor);
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsMul_32s32sc_ISfs(const Ipp32s* pSrc, Ipp32sc* pSrcDst, int len, int
scaleFactor);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2               Pointers to the source vectors.

pDst                       Pointer to the destination vector.

pSrc                       Pointer to the source vector for in-place operation.

pSrcDst                    Pointer to the source and destination vector for in-place operation.

len                        Number of elements in the vector

scaleFactor                Scale factor, refer to Integer Scaling.

                                                                                      99
---------------------Page 100---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Description
Functions ippsMul_16s32f, ippsMul_16s32s_Sfs  , ippsMul_16u16s_Sfs  , ippsMul_32s32sc_ISfs  , and
ippsMul_Low_32s_Sfs   are deprecated. These functions are obsolete and will be removed in a future
release.
For more information about the deprecation process use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/
This function multiplies the elements of the vector pSrc1 by the elements of the vector pSrc2 and stores the
result in pDst.
The in-place flavors of ippsMul multiply the elements of the vector pSrc by the elements of the vector
pSrcDst and store the result in pSrcDst.
Function flavors with Sfs suffix perform scaling of the result value in accordance with the scaleFactor
value. If the output value exceeds the data range, the result is saturated.
Function flavor with Low suffix requires that each value of the product does not exceed the Ipp32s data type
range.

Return Values

ippStsNoErr                       Indicates no error

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

ippStsSizeErr                     Indicates an error when len  is less than, or equal to 0,

See Also
Integer Scaling

SubC
Subtracts a constant value from each element of a
vector.

Syntax
Case 1. Not-in-place operations on floating point data.
IppStatus ippsSubC_32f(const Ipp32f* pSrc, Ipp32f val, Ipp32f* pDst, int len        );
IppStatus ippsSubC_32fc(const Ipp32fc* pSrc, Ipp32fc val, Ipp32fc* pDst, int len         );
IppStatus ippsSubC_64f(const Ipp64f* pSrc, Ipp64f val, Ipp64f* pDst, int len        );
IppStatus ippsSubC_64fc(const Ipp64fc* pSrc, Ipp64fc val, Ipp64fc* pDst, int len         );
Case 2. Not-in-place operations on integer data.
IppStatus ippsSubC_8u_Sfs(const Ipp8u* pSrc, Ipp8u val, Ipp8u* pDst, int len, int
scaleFactor );
IppStatus ippsSubC_16u_Sfs(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len, int
scaleFactor );
IppStatus ippsSubC_16s_Sfs(const Ipp16s* pSrc, Ipp16s val, Ipp16s* pDst, int len, int
scaleFactor );
IppStatus ippsSubC_32s_Sfs(const Ipp32s* pSrc, Ipp32s val, Ipp32s* pDst, int len, int
scaleFactor );
IppStatus ippsSubC_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc val, Ipp16sc* pDst, int len,
int scaleFactor );

   100
---------------------Page 101---------------------

                                                                         Essential Functions  5 

IppStatus ippsSubC_32sc_Sfs(const Ipp32sc* pSrc, Ipp32sc val, Ipp32sc* pDst, int len,
int scaleFactor );
Case 3. In-place operations on floating point data.
IppStatus ippsSubC_16s_I(Ipp16s val, Ipp16s* pSrcDst, int len     );
IppStatus ippsSubC_32f_I(Ipp32f val, Ipp32f* pSrcDst, int len     );
IppStatus ippsSubC_64f_I(Ipp64f val, Ipp64f* pSrcDst, int len     );
IppStatus ippsSubC_32fc_I(Ipp32fc val, Ipp32fc* pSrcDst, int len     );
IppStatus ippsSubC_64fc_I(Ipp64fc val, Ipp64fc* pSrcDst, int len     );
Case 4. In-place operations on integer data.
IppStatus ippsSubC_8u_ISfs(Ipp8u val, Ipp8u* pSrcDst, int len, int scaleFactor      );
IppStatus ippsSubC_16u_ISfs(Ipp16u val, Ipp16u* pSrcDst, int len, int scaleFactor      );
IppStatus ippsSubC_16s_ISfs(Ipp16s val, Ipp16s* pSrcDst, int len, int scaleFactor      );
IppStatus ippsSubC_32s_ISfs(Ipp32s val, Ipp32s* pSrcDst, int len, int scaleFactor      );
IppStatus ippsSubC_16sc_ISfs(Ipp16sc val, Ipp16sc* pSrcDst, int len, int scaleFactor      );
IppStatus ippsSubC_32sc_ISfs(Ipp32sc val, Ipp32sc* pSrcDst, int len, int scaleFactor      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

val                         Scalar value used to decrement each element of the source vector.

pDst                        Pointer to the destination vector.

pSrcDst                     Pointer to the source and destination vector for in-place operation.

len                         Number of elements in the vector

scaleFactor                 Scale factor, refer to Integer Scaling.

Description
This function subtracts a value val from each element of the vector pSrc, and stores the result in pDst.
The in-place flavors of ippsSubC subtract a value val from each element of the vector pSrcDst and store
the result in pSrcDst.
Functions with Sfs suffixes perform scaling of the result value in accordance with the scaleFactor value. If
the output value exceeds the data range, the result becomes saturated.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                 NULL.

                                                                                        101
---------------------Page 102---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsSizeErr                   Indicates an error when len is less than or equal to 0.

SubCRev
Subtracts each element of a vector from a constant
value.

Syntax
Case 1. Not-in-place operations on floating point data.
IppStatus ippsSubCRev_32f(const Ipp32f* pSrc, Ipp32f val, Ipp32f* pDst, int len   );
IppStatus ippsSubCRev_64f(const Ipp64f* pSrc, Ipp64f val, Ipp64f* pDst, int len   );
IppStatus ippsSubCRev_32fc(const Ipp32fc* pSrc, Ipp32fc val, Ipp32fc* pDst, int len   );
IppStatus ippsSubCRev_64fc(const Ipp64fc* pSrc, Ipp64fc val, Ipp64fc* pDst, int len   );
Case 2. Not-in-place operations on integer data.
IppStatus ippsSubCRev_8u_Sfs(const Ipp8u* pSrc, Ipp8u val, Ipp8u* pDst, int len, int
scaleFactor);
IppStatus ippsSubCRev_16u_Sfs(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len,
int scaleFactor);
IppStatus ippsSubCRev_16s_Sfs(const Ipp16s* pSrc, Ipp16s val, Ipp16s* pDst, int len,
int scaleFactor);
IppStatus ippsSubCRev_32s_Sfs(const Ipp32s* pSrc, Ipp32s val, Ipp32s* pDst, int len,
int scaleFactor);
IppStatus ippsSubCRev_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc val, Ipp16sc* pDst, int
len, int scaleFactor);
IppStatus ippsSubCRev_32sc_Sfs(const Ipp32sc* pSrc, Ipp32sc val, Ipp32sc* pDst, int
len, int scaleFactor);
Case 3. In-place operations on floating point data.
IppStatus ippsSubCRev_32f_I(Ipp32f val, Ipp32f* pSrcDst, int len  );
IppStatus ippsSubCRev_64f_I(Ipp64f val, Ipp64f* pSrcDst, int len  );
IppStatus ippsSubCRev_32fc_I(Ipp32fc val, Ipp32fc* pSrcDst, int len  );
IppStatus ippsSubCRev_64fc_I(Ipp64fc val, Ipp64fc* pSrcDst, int len  );
Case 4. In-place operations on integer data.
IppStatus ippsSubCRev_8u_ISfs(Ipp8u val, Ipp8u* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSubCRev_16u_ISfs(Ipp16u val, Ipp16u* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSubCRev_16s_ISfs(Ipp16s val, Ipp16s* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSubCRev_32s_ISfs(Ipp32s val, Ipp32s* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSubCRev_16sc_ISfs(Ipp16sc val, Ipp16sc* pSrcDst, int len, int
scaleFactor);
IppStatus ippsSubCRev_32sc_ISfs(Ipp32sc val, Ipp32sc* pSrcDst, int len, int
scaleFactor);

Include Files
ipps.h

  102
---------------------Page 103---------------------

                                                                          Essential Functions  5 

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

val                          Scalar value from which vector elements are subtracted.

pSrc                         Pointer to the source vector.

pDst                         Pointer to the destination vector.

pSrcDst                      Pointer to the vector whose elements are to be subtracted from the
                             value val in case of the in-place operation. The destination vector
                             which stores the result of the subtraction val - pSrcDst[n].
len                          Number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
This function subtracts each element of the vector pSrc from a value val and stores the result in pDst.
The in-place flavors of ippsSubCRev subtract each element of the vector pSrcDst from a value val and
store the result in pSrcDst.
Functions with Sfs suffixes perform scaling of the result value in accordance with the scaleFactor value. If
the output value exceeds the data range, the result becomes saturated.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc , pDst, or pSrcDst pointer is
                                 NULL .
ippStsSizeErr                    Indicates an error when len  is less than or equal to 0.

Sub
Subtracts the elements of two vectors.

Syntax
Case 1. Not-in-place operations on floating point data, and integer data without scaling.
IppStatus ippsSub_16s(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst, int len        );
IppStatus ippsSub_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, Ipp32f* pDst, int len        );
IppStatus ippsSub_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, Ipp64f* pDst, int len        );
IppStatus ippsSub_32fc(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, Ipp32fc* pDst, int
len);
IppStatus ippsSub_64fc(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, Ipp64fc* pDst, int
len);
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsSub_16s32f(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp32f* pDst, int
len);

                                                                                          103
---------------------Page 104---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Case 2. Not-in-place operations on integer data with scaling.
IppStatus ippsSub_8u_Sfs(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, int len,
int scaleFactor);
IppStatus ippsSub_16u_Sfs(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst, int
len, int scaleFactor);
IppStatus ippsSub_16s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst, int
len, int scaleFactor);
IppStatus ippsSub_32s_Sfs(const Ipp32s* pSrc1, const Ipp32s* pSrc2, Ipp32s* pDst, int
len, int scaleFactor);
IppStatus ippsSub_16sc_Sfs(const Ipp16sc* pSrc1, const Ipp16sc* pSrc2, Ipp16sc* pDst,
int len, int scaleFactor );
IppStatus ippsSub_32sc_Sfs(const Ipp32sc* pSrc1, const Ipp32sc* pSrc2, Ipp32sc* pDst,
int len, int scaleFactor );
Case 3. In-place operations on floating point data and integer data without scaling.
IppStatus ippsSub_16s_I(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len   );
IppStatus ippsSub_32f_I(const Ipp32f* pSrc, Ipp32f* pSrcDst, int len   );
IppStatus ippsSub_64f_I(const Ipp64f* pSrc, Ipp64f* pSrcDst, int len   );
IppStatus ippsSub_32fc_I(const Ipp32fc* pSrc, Ipp32fc* pSrcDst, int len   );
IppStatus ippsSub_64fc_I(const Ipp64fc* pSrc, Ipp64fc* pSrcDst, int len   );
Case 4. In-place operations on integer data with scaling.
IppStatus ippsSub_8u_ISfs(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSub_16u_ISfs(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len, int
scaleFactor);
IppStatus ippsSub_16s_ISfs(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len, int
scaleFactor);
IppStatus ippsSub_32s_ISfs(const Ipp32s* pSrc, Ipp32s* pSrcDst, int len, int
scaleFactor);
IppStatus ippsSub_16sc_ISfs(const Ipp16sc* pSrc, Ipp16sc* pSrcDst, int len, int
scaleFactor);
IppStatus ippsSub_32sc_ISfs(const Ipp32sc* pSrc, Ipp32sc* pSrcDst, int len, int
scaleFactor);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1                      Pointer to the source vector-subtrahend, whose elements are to be
                           subtracted.
pSrc2                      Pointer to the source vector-minuend from whose elements the
                           elements of pSrc1are to be subtracted.

  104
---------------------Page 105---------------------

                                                                           Essential Functions  5 

pDst                         Pointer to the destination vector.

pSrc                         Pointer to the source vector-subtrahend for in-place operation.

pSrcDst                      Pointer to the source vector-minuend and destination vector for in-
                             place operation.
len                          Number of elements in the vector.

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
The function ippsSub_16s32f is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function subtracts the elements of the vector pSrc1 from the elements of the vector pSrc2, and stores
the result in pDst.
The in-place flavors of ippsSub subtract the elements of the vector pSrc from the elements of a vector
pSrcDst and store the result in pSrcDst.
Functions with Sfs suffixes perform scaling of the result value in accordance with the scaleFactor value. If
the output value exceeds the data range, the result becomes saturated.

Return Values

ippStsNoErr                       Indicates no error.

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

ippStsSizeErr                     Indicates an error when len  is less than or equal to 0.

DivC
Divides each element of a vector by a constant value.

Syntax
Case 1. Not-in-place operations on floating point data.
IppStatus ippsDivC_32f(const Ipp32f* pSrc, Ipp32f val, Ipp32f* pDst, int len        );
IppStatus ippsDivC_64f(const Ipp64f* pSrc, Ipp64f val, Ipp64f* pDst, int len        );
IppStatus ippsDivC_32fc(const Ipp32fc* pSrc, Ipp32fc val, Ipp32fc* pDst, int len         );
IppStatus ippsDivC_64fc(const Ipp64fc* pSrc, Ipp64fc val, Ipp64fc* pDst, int len         );
Case 2. Not-in-place operations on integer data with scaling.
IppStatus ippsDivC_8u_Sfs(const Ipp8u* pSrc, Ipp8u val, Ipp8u* pDst, int len, int
ScaleFactor );
IppStatus ippsDivC_16u_Sfs(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len, int
scaleFactor );
IppStatus ippsDivC_16s_Sfs(const Ipp16s* pSrc, Ipp16s val, Ipp16s* pDst, int len, int
ScaleFactor );
IppStatus ippsDivC_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc val, Ipp16sc* pDst, int len,
int ScaleFactor );
Case 3. In-place operations on floating point data.
IppStatus ippsDivC_32f_I(Ipp32f val, Ipp32f* pSrcDst, int len       );

                                                                                           105
---------------------Page 106---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsDivC_64f_I(Ipp64f val, Ipp64f* pSrcDst, int len      );
IppStatus ippsDivC_32fc_I(Ipp32fc val, Ipp32fc* pSrcDst, int len      );
IppStatus ippsDivC_64fc_I(Ipp64fc val, Ipp64fc* pSrcDst, int len      );
Case 4. In-place operations on integer data with scaling.
IppStatus ippsDivC_8u_ISfs(Ipp8u val, Ipp8u* pSrcDst, int len, int ScaleFactor        );
IppStatus ippsDivC_16u_ISfs(Ipp16u val, Ipp16u* pSrcDst, int len, int scaleFactor        );
IppStatus ippsDivC_16s_ISfs(Ipp16s val, Ipp16s* pSrcDst, int len, int ScaleFactor        );
IppStatus ippsDivC_64s_ISfs(Ipp64s val, Ipp64s* pSrcDst, Ipp32u len, int ScaleFactor        );
IppStatus ippsDivC_16sc_ISfs(Ipp16sc val, Ipp16sc* pSrcDst, int len, int ScaleFactor        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

val                          Scalar value used as a divisor.

pSrc                         Pointer to the source vector.

pDst                         Pointer to the destination vector.

pSrcDst                      Pointer to the source and destination vector for in-place operation.

len                          Number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
This function divides each element of the vector pSrc by a value val and stores the result in pDst.
The in-place flavors of ippsDivC divide each element of the vector pSrcDst by a value val and store the
result in pSrcDst.
Functions with Sfs suffixes perform scaling of the result value in accordance with the scaleFactor value. If
the output value exceeds the data range, the result becomes saturated.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                  NULL.
ippStsSizeErr                     Indicates an error when len is less than or equal to 0.

ippStsDivByZeroErr                Indicates an error when val is equal to 0.

DivCRev
Divides a constant value by each element of a vector.

   106
---------------------Page 107---------------------

                                                                         Essential Functions  5 

Syntax
IppStatus ippsDivCRev_16u(const Ipp16u* pSrc, Ipp16u val, Ipp16u* pDst, int len      );
IppStatus ippsDivCRev_32f(const Ipp32f* pSrc, Ipp32f val, Ipp32f* pDst, int len      );
IppStatus ippsDivCRev_16u_I(Ipp16u val, Ipp16u* pSrcDst, int len     );
IppStatus ippsDivCRev_32f_I(Ipp32f val, Ipp32f* pSrcDst, int len     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

val                         Constant value used as a dividend in the operation.

pSrc                        Pointer to the source vector whose elements are used as divisors.

pDst                        Pointer to the destination vector.

pSrcDst                     Pointer to the source and destination vector for in-place operation.

len                         Number of elements in the vector

Description
This function divides the constant value val by each element of the vector pSrc and stores the results in
pDst.
The in-place flavors of ippsDivC divide the constant value val by each element of the vector pSrcDst and
store the results in pSrcDst.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc, pDst, orpSrcDst pointer is
                                 NULL.
ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

ippStsDivByZeroErr               Indicates an error when any element of the vector pSource is
                                 equal to 0.

Div
Divides the elements of two vectors.

Syntax
Case 1. Not-in-place operations on integer data.
IppStatus ippsDiv_8u_Sfs(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, int len,
int scaleFactor );
IppStatus ippsDiv_16u_Sfs(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst, int
len, int scaleFactor );

                                                                                         107
---------------------Page 108---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsDiv_16s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst, int
len, int scaleFactor);
IppStatus ippsDiv_32s_Sfs(const Ipp32s* pSrc1, const Ipp32s* pSrc2, Ipp32s* pDst, int
len, int scaleFactor);
IppStatus ippsDiv_16sc_Sfs(const Ipp16sc* pSrc1, const Ipp16sc* pSrc2, Ipp16sc* pDst,
int len, int scaleFactor );
IppStatus ippsDiv_32s16s_Sfs(const Ipp16s* pSrc1, const Ipp32s* pSrc2, Ipp16s* pDst,
int len, int scaleFactor );
Case 2. Not-in-place operations on floating point data.
IppStatus ippsDiv_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, Ipp32f* pDst, int len   );
IppStatus ippsDiv_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, Ipp64f* pDst, int len   );
IppStatus ippsDiv_32fc(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, Ipp32fc* pDst, int
len);
IppStatus ippsDiv_64fc(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, Ipp64fc* pDst, int
len);
Case 3. In-place operations on integer data.
IppStatus ippsDiv_8u_ISfs(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len, int ScaleFactor   );
IppStatus ippsDiv_16u_ISfs(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len, int
scaleFactor);
IppStatus ippsDiv_16s_ISfs(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len, int
ScaleFactor);
IppStatus ippsDiv_16sc_ISfs(const Ipp16sc* pSrc, Ipp16sc* pSrcDst, int len, int
ScaleFactor);
IppStatus ippsDiv_32s_ISfs(const Ipp32s* pSrc, Ipp32s* pSrcDst, int len, int
ScaleFactor);
Case 4. In-place operations on floating point data.
IppStatus ippsDiv_32f_I(const Ipp32f* pSrc, Ipp32f* pSrcDst, int len   );
IppStatus ippsDiv_64f_I(const Ipp64f* pSrc, Ipp64f* pSrcDst, int len   );
IppStatus ippsDiv_32fc_I(const Ipp32fc* pSrc, Ipp32fc* pSrcDst, int len   );
IppStatus ippsDiv_64fc_I(const Ipp64fc* pSrc, Ipp64fc* pSrcDst, int len   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1                      Pointer to the divisor vector.

pSrc2                      Pointer to the dividend vector.

pDst                       Pointer to the destination vector.

pSrc                       Pointer to the divisor vector for in-place operations.

  108
---------------------Page 109---------------------

                                                                             Essential Functions  5 

pSrcDst                       Pointer to the source and destination vector for in-place operations.

len                           Number of elements in the vector.

scaleFactor                   Scale factor, refer to Integer Scaling.

Description
This function divides the elements of the pSrc2 vector by the elements of the pSrc1 vector , and stores the
result in pDst.
The in-place flavors of ippsDiv divide the elements of the vector pSrcDst by the elements of the vector
pSrc and store the result in pSrcDst.
Functions with Sfs suffixe perform scaling of the result in accordance with the scaleFactor value. If the
output value exceeds the data range, the result is saturated.
If any of the divisor vector elements is equal to zero, the function returns a warning and continues execution
with the corresponding result value. For more information see Appendix A Handling of Special Cases.

Return Values

ippStsNoErr                        Indicates no error.

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

ippStsSizeErr                      Indicates an error when  len is less than or equal to zero.

ippStsDivByZero                    Indicates a warning when any of the divisor vector elements is
                                   equal to zero.

Example
The example below shows that the use of the scaling factor in the integer functions increases operation
accuracy.
IppStatus div16s( void ) {
      Ipp16s x[4] = { -3, 2, 0, 300 };
      Ipp16s y[4] = { -2, 2, 0, 0 };
      IppStatus st = ippsDiv_16s_ISfs( y, x, 4, -1 );
      printf_16s(“div16s =”, x, 4, st );
      return st; 
}

Output:
    -- warning 6, Zero value(s) in the divisor of the function Div
    div16s =  3 2 0 32767

The example below considers division by zero exceptions (x / 0, 0 / 0).
IppStatus div32f( void ) {
      Ipp32f x[4] = { -3, 2, 0, 300 };
      Ipp32f y[4] = { -2, 2, 0, 0 };
      IppStatus st = ippsDiv_32f_I( y, x, 4 );
      printf_32f( "div32f =", x, 4, st );
      return st; 
} 

Output:
    -- warning 6, Zero value(s) in the divisor of the function Div
    div32f =  1.500000 1.000000 1.#IND00 1.#INF00

See Also
Integer Scaling

                                                                                              109
---------------------Page 110---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Handling of Special Cases

Div_Round
DEPRECATED. Divides the elements of two vectors
with rounding.

Syntax
Case 1. Not-in-place operations on integer data.
IppStatus ippsDiv_Round_8u_Sfs(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, int
len, IppRoundMode rndMode, int scaleFactor    );
IppStatus ippsDiv_Round_16u_Sfs(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst,
int len, IppRoundMode rndMode, int scaleFactor    );
IppStatus ippsDiv_Round_16s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, Ipp16s* pDst,
int len, IppRoundMode rndMode, int scaleFactor    );
Case 2. In-place operations on integer data.
IppStatus ippsDiv_Round_8u_ISfs(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len,
IppRoundMode rndMode, int scaleFactor   );
IppStatus ippsDiv_Round_16u_ISfs(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len,
IppRoundMode rndMode, int scaleFactor   );
IppStatus ippsDiv_Round_16s_ISfs(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len,
IppRoundMode rndMode, int scaleFactor   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1                        Pointer to the vector whose elements are used as divisors.

pSrc2                        Pointer to the vector whose elements are used as dividends.

pDst                         Pointer to the destination vector.

pSrc                         Pointer to the source vector whose elements are used as divisors for in-
                             place operations.

pSrcDst                      Pointer to the source and destination vector for in-place operations.

len                          Number of elements in the vector.

rndMode                      Rounding mode, the following values are possible:

                             ippRndZero  - specifies that floating-point values are truncated toward
                             zero,

   110
---------------------Page 111---------------------

                                                                              Essential Functions  5 

                              ippRndNear   - specifies that floating-point values are rounded to the
                              nearest even integer when the fractional part equals 0.5; otherwise they
                              are rounded to the nearest integer,

                              ippRndFinancial   - specifies that floating-point values are rounded down
                              to the nearest integer when the fractional part is less than 0.5, or rounded
                              up to the nearest integer if the fractional part is equal or greater than 0.5.

scaleFactor                   Scale factor, refer to Integer Scaling.

Description
The function ippsDiv_Round  is deprecated. This function is obsolete and will be removed in a future release.
Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function divides the elements of the vector pSrc2 by the elements of the vector pSrc1, the result is
rounded using the rounding method specified by the parameter roundMode and stored in the vector pDst.
The in-place flavors of ippsDiv_Round divide the elements of the vector pSrcDst by the elements of the
vector pSrc, the result is rounded using the rounding method specified by the parameter roundMode and
stored in the vector pSrcDst.
Functions perform scaling of the result value in accordance with the scaleFactor value. If the output value
exceeds the data range, the result becomes saturated.
If the function ippsDiv_Round encounters a zero-valued divisor vector element, it returns a warning status
and continues execution with the corresponding result value (see appendix A Appendix A Handling of Special
Cases for more information).

Return Values

ippStsNoErr                        Indicates no error.

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

ippStsSizeErr                      Indicates an error when  len  is less than or equal to 0.

ippStsDivByZero                    Indicates a warning for zero-valued divisor vector element. The
                                   function execution is continued.
ippStsRoundModeNotSupportedErr     Indicates an error condition if the roundMode  has an illegal
                                   value.

Abs
Computes absolute values of vector elements.

Syntax
IppStatus ippsAbs_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len         );
IppStatus ippsAbs_32s(const Ipp32s* pSrc, Ipp32s* pDst, int len         );
IppStatus ippsAbs_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len         );
IppStatus ippsAbs_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len         );
IppStatus ippsAbs_16s_I(Ipp16s* pSrcDst, int len       );
IppStatus ippsAbs_32s_I(Ipp32s* pSrcDst, int len       );
IppStatus ippsAbs_32f_I(Ipp32f* pSrcDst, int len       );

                                                                                              111
---------------------Page 112---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsAbs_64f_I(Ipp64f* pSrcDst, int len     );

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.

pSrcDst                      Pointer to the source and destination vector for in-place operations.

len                          Number of elements in the vector.

Description
This function computes the absolute values of each element of the vector pSrc and stores the result in pDst.
The in-place flavors of ippsAbs compute the absolute values of each element of the vector pSrcDst and
store the result in pSrcDst.
To compute the absolute values of complex data, use the function ippsMagnitudeAddC.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pSrc , pDst, or pSrcDst pointer is
                                  NULL.
ippStsSizeErr                     Indicates an error when len  is less than or equal to 0.

Example
The example below shows how to call the function ippsAbs_32f_I.
void abs32f(void) {
      Ipp32f x[4] = {-1, 1, 0, 0};
      x[3] *= (-1);
      ippsAbs_32f_I(x, 4);
      printf_32f(“abs =”, x, 4, ippStsNoErr); 
}

Output:
    abs =  1.000000 1.000000 0.000000 0.000000

Sqr
Computes a square of each element of a vector.

Syntax
IppStatus ippsSqr_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len       );
IppStatus ippsSqr_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len       );
IppStatus ippsSqr_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len       );

   112
---------------------Page 113---------------------

                                                                        Essential Functions  5 

IppStatus ippsSqr_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len    );
IppStatus ippsSqr_8u_Sfs(const Ipp8u* pSrc, Ipp8u* pDst, int len, int scaleFactor     );
IppStatus ippsSqr_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int len, int scaleFactor      );
IppStatus ippsSqr_16u_Sfs(const Ipp16u* pSrc, Ipp16u* pDst, int len, int scaleFactor      );
IppStatus ippsSqr_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, int
scaleFactor);
IppStatus ippsSqr_32f_I(Ipp32f* pSrcDst, int len   );
IppStatus ippsSqr_64f_I(Ipp64f* pSrcDst, int len   );
IppStatus ippsSqr_32fc_I(Ipp32fc* pSrcDst, int len   );
IppStatus ippsSqr_64fc_I(Ipp64fc* pSrcDst, int len   );
IppStatus ippsSqr_8u_ISfs(Ipp8u* pSrcDst, int len, int scaleFactor    );
IppStatus ippsSqr_16s_ISfs(Ipp16s* pSrcDst, int len, int scaleFactor    );
IppStatus ippsSqr_16u_ISfs(Ipp16u* pSrcDst, int len, int scaleFactor    );
IppStatus ippsSqr_16sc_ISfs(Ipp16sc* pSrcDst, int len, int scaleFactor     );

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.

pSrcDst                     Pointer to the source and destination vector for in-place operations.

len                         Number of elements in the vector

scaleFactor                 Scale factor, refer to Integer Scaling.

Description
This function computes the square of each element of the vector pSrc, and stores the result in pDst. The
computation is performed as follows:
pDst[n] = pSrc[ n] 2

The in-place flavors of ippsSqrcompute the square of each element of the vector pSrcDst and store the
result in pSrcDst. The computation is performed as follows:
pSrcDst[n] = pSrcDst[ n] 2

When computing the square of an integer number, the output result can exceed the data range and become
saturated. To get a precise result, use the scale factor.

Return Values

ippStsNoErr                      Indicates no error.

                                                                                       113
---------------------Page 114---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsNullPtrErr                Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                NULL.
ippStsSizeErr                   Indicates an error when len is less than or equal to zero.

Example
The example below shows how to get the value of 2002. Without scaling this result is clipped to 32767.
Scaling retains the output data range but results in the precision loss in low-order bits.
IppStatus sqr(void) {
      Ipp16s x[4] = {-3, 2, 30, 200};
      IppStatus st = ippsSqr_16s_ISfs(x, 4, 1);
      printf_16s(“sqr =”, x, 4, st);
      return st; 
} 

Output:
    sqr =  4 2 450 20000

Sqrt
Computes a square root of each element of a vector.

Syntax
IppStatus ippsSqrt_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len   );
IppStatus ippsSqrt_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len   );
IppStatus ippsSqrt_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len   );
IppStatus ippsSqrt_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len   );
IppStatus ippsSqrt_8u_Sfs(const Ipp8u* pSrc, Ipp8u* pDst, int len, int scaleFactor    );
IppStatus ippsSqrt_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int len, int scaleFactor    );
IppStatus ippsSqrt_16u_Sfs(const Ipp16u* pSrc, Ipp16u* pDst, int len, int scaleFactor    );
IppStatus ippsSqrt_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, int
scaleFactor);
IppStatus ippsSqrt_32s16s_Sfs(const Ipp32s* pSrc, Ipp16s* pDst, int len, int
scaleFactor);
IppStatus ippsSqrt_32f_I(Ipp32f* pSrcDst, int len  );
IppStatus ippsSqrt_64f_I(Ipp64f* pSrcDst, int len  );
IppStatus ippsSqrt_32fc_I(Ipp32fc* pSrcDst, int len  );
IppStatus ippsSqrt_64fc_I(Ipp64fc* pSrcDst, int len  );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsSqrt_8u_ISfs(Ipp8u* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSqrt_16s_ISfs(Ipp16s* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSqrt_16u_ISfs(Ipp16u* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSqrt_16sc_ISfs(Ipp16sc* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSqrt_64s_ISfs(Ipp64s* pSrcDst, int len, int scaleFactor   );
IppStatus ippsSqrt_64s16s_Sfs(const Ipp64s* pSrc, Ipp16s* pDst, int len, int
scaleFactor);

  114
---------------------Page 115---------------------

                                                                              Essential Functions  5 

IppStatus ippsSqrt_64s_Sfs(const Ipp64s* pSrc, Ipp64s* pDst, int len, int scaleFactor             );

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.

pSrcDst                       Pointer to the source and destination vector for in-place operations.

len                           Number of elements in the vector

scaleFactor                   Scale factor, refer to Integer Scaling.

Description
Functions ippsSqrt_64s_ISfs   , ippsSqrt_64s_Sfs  , and ippsSqrt_64s16s_Sfs   are deprecated. These
functions are obsolete and will be removed in a future release. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function computes the square root of each element of the vector pSrc, and stores the result in pDst.
The computation is performed as follows:
pDst[n] = (pSrc[n] )1/2

The in-place flavors of ippsSqrt compute the square root of each element of the vector pSrcDst and store
the result in pSrcDst. The computation is performed as follows:
pSrcDst [n] = (pSrcDst[n] )1/2.
The square root of complex vector elements is computed as follows:
 

 
If the function ippsSqrt encounters a negative value in the input, it returns a warning status and continues
execution with the corresponding result value (see appendix A Appendix A Handling of Special Cases for
more information).
To increase precision of an integer output, use the scale factor.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pSrc , pDst, or pSrcDst   pointer is
                                   NULL .
ippStsSizeErr                      Indicates an error when  len  is less than or equal to 0.

                                                                                               115
---------------------Page 116---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsSqrtNegArg                  Indicates a warning that a source element has a negative
                                  value.

Example
The example below shows how to call the function ippsSqrt_16s_ISfs.
IppStatus sqrt(void) {
      Ipp16s x[4] = {-3, 2, 30, 300};
      IppStatus st = ippsSqrt_16s_ISfs(x, 4, -1);
      printf_16s(“sqrt =”, x, 4, st);
      return st; 
} 

Output:
    -- warning 3, Negative value(s) in the argument of the function Sqrt
    sqrt = 0 3 11 35

Cubrt
Computes cube root of each element of a vector.

Syntax
IppStatus ippsCubrt_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len       );
IppStatus ippsCubrt_32s16s_Sfs(const Ipp32s* pSrc, Ipp16s* pDst, int len, int
scaleFactor );

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.

len                          Number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
This function computes cube root of each element of pSrc and stores the result in the corresponding element
of pDst.
The computation is performed as follows:

pDst[n] = (pSrc[n] )1/3 , 0 ≤ n < len.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pDst or pSrc pointer is NULL.

   116
---------------------Page 117---------------------

                                                                         Essential Functions  5 

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Exp
Computes e to the power of each element of a vector.

Syntax
IppStatus ippsExp_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len    );
IppStatus ippsExp_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len    );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsExp_32f64f(const Ipp32f* pSrc, Ipp64f* pDst, int len     );
IppStatus ippsExp_32f_I(Ipp32f* pSrcDst, int len   );
IppStatus ippsExp_64f_I(Ipp64f* pSrcDst, int len   );
IppStatus ippsExp_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int len, int scaleFactor      );
IppStatus ippsExp_32s_Sfs(const Ipp32s* pSrc, Ipp32s* pDst, int len, int scaleFactor      );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsExp_64s_Sfs(const Ipp64s* pSrc, Ipp64s* pDst, int len, int scaleFactor      );
IppStatus ippsExp_16s_ISfs(Ipp16s* pSrcDst, int len, int scaleFactor     );
IppStatus ippsExp_32s_ISfs(Ipp32s* pSrcDst, int len, int scaleFactor     );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsExp_64s_ISfs(Ipp64s* pSrcDst, int len, int scaleFactor     );

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.

pSrcDst                     Pointer to the source and destination vector pSrcDst for the in-place
                            operation.
len                         Number of elements in the vector

scaleFactor                 Scale factor, refer to Integer Scaling.

Description
Functions ippsExp_32f64f, ippsExp_64s_Sfs, and ippsExp_64s_ISfs are deprecated. These functions
are obsolete and will be removed in a future release. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function computes the exponential function of each element of the vector pSrc, and stores the result in
pDst.
The computation is performed as follows:

                                                                                        117
---------------------Page 118---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

pDst[n] = epSrc  [n]

The in-place flavors of ippsExp compute the exponential function of each element of the vector pSrcDst
and store the result in pSrcDst.
The computation is performed as follows:
pSrcDst[n] = epSrcDst   [n]

When an overflow occurs, the function continues operation with the corresponding result value (see appendix
A Appendix A Handling of Special Cases for more information).
When computing the exponent of an integer number, the output result can exceed the data range and
become saturated. The scaling retains the output data range but results in precision loss in low-order bits.
The function ippsExp_32f64f  computes the output result in a higher precision data range.

Application Notes
For the functions ippsExp and ippsLn the result is rounded to the nearest integer after scaling.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pSrc, pDst, or pSrcDst  pointer is
                                   NULL.
ippStsSizeErr                      Indicates an error when  len is less than or equal to zero.

Example
The code example below shows how to call ippsExp_16s_ISfs  function.
IppStatus exp16s(void) {
      Ipp16s x[4] = {-1, 2, 30, 0};
      IppStatus st = ippsExp_16s_ISfs(x, 4, -1);
      printf_16s(“exp16s =”, x, 4, st);
      return st; 
}

Output:
    exp16s =  1 15 32767 2

The code example below shows how to call ippsExp_64f_I function.
IppStatus exp64f(void) {
      Ipp64f x[4] = {-1, 2, 1, log(1.234567)};
      IppStatus st = ippsExp_64f_I(x, 4);
      printf_64f(“exp64f =”, x, 4, st);
      return st; 
} 

Output:
    exp64f =  0.367879 7.389056 2.718282 1.234567

Ln
Computes the natural logarithm of each element of a
vector.

Syntax
IppStatus ippsLn_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len         );
IppStatus ippsLn_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len         );

   118
---------------------Page 119---------------------

                                                                           Essential Functions  5 

IppStatus ippsLn_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int len, int scaleFactor         );
IppStatus ippsLn_32s_Sfs(const Ipp32s* pSrc, Ipp32s* pDst, int len, int scaleFactor         );
IppStatus ippsLn_32s16s_Sfs(const Ipp32s* pSrc, Ipp16s* pDst, int len, int
scaleFactor );
IppStatus ippsLn_16s_ISfs(Ipp16s* pSrcDst, int len, int scaleFactor       );
IppStatus ippsLn_32s_ISfs(Ipp32s* pSrcDst, int len, int scaleFactor       );
IppStatus ippsLn_32f_I(Ipp32f* pSrcDst, int len     );
IppStatus ippsLn_64f_I(Ipp64f* pSrcDst, int len     );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsLn_64f32f(const Ipp64f* pSrc, Ipp32f* pDst, int len       );

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.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
The function ippsLn_64f32f is deprecated. This function is obsolete and will be removed in a future release.
Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function computes the natural logarithm of each element of the vector pSrc and stores the result in
pDst as given by
pDst[n] = log e (pSrc[n])
The in-place flavors of ippsLn compute the natural logarithm of each element of the vector pSrcDst and
store the result in pSrcDst as given by
pSrcDst[n] = log e (pSrcDst[n])
If the function ippsLn encounters a zero or negative value in the input, it returns a warning status and
continues execution with the corresponding result value (see appendix A Appendix A Handling of Special
Cases for more information).

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                  NULL.

                                                                                          119
---------------------Page 120---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsSizeErr                     Indicates an error when  len  is less than or equal to zero.

ippStsLnZeroArg                   Indicates a warning for zero-valued input vector elements.

ippStsLnNegArg                    Indicates a warning for negative input vector elements.

Example
The example below shows how to call the function ippsLn_32f_I.
IppStatus ln32f(void) {
      Ipp32f x[4] = {-1, (float)IPP_E, 0, (float)(exp(1.234567))};
      IppStatus st = ippsLn_32f_I(x, 4);
      printf_32f(“Ln =”, x, 4, st);
      return st; 
} 

Output:
    -- warning 8, Negative value(s) of argument in the Ln function 
    Ln = -1.#IND00 1.000000 -1.#INF00 1.234567

10Log10
DEPRECATED. Computes the decimal logarithm of
each element of a vector and multiplies it by 10.

Syntax
IppStatus ipps10Log10_32s_Sfs(const Ipp32s* pSrc, Ipp32s* pDst, int len, int
scaleFactor );
IppStatus ipps10Log10_32s_ISfs(Ipp32s* pSrcDst, int len, int scaleFactor         );

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.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector

scaleFactor                  Refer to Integer Scaling in Chapter 2.

Description
The function ipps10Log10_32s_Sfs  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
The function ipps10Log10_32s_ISfs  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.

   120
---------------------Page 121---------------------

                                                                            Essential Functions  5 

This function computes the decimal logarithm of each element of the vector pSrc, multiplies it by 10, and
stores the result in pDstas given by
pDst[n] = 10*log  10(pSrc[n]).
The in-place flavor of ipps10Log10 computes the decimal logarithm of each element of the vector pSrcDst,
multiplies it by 10, and stores the result in pSrcDst as given by
pSrcDst[n] = 10*log  10(pSrcDst[n]) .
If the function ipps10Log10 encounters a zero or negative value in the input, it returns a warning status and
continues execution with the corresponding result value (see Appendix A Appendix A Handling of Special
Cases for more information).

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pSrc, pDst, or pSrcDst  pointer is
                                  NULL .
ippStsSizeErr                     Indicates an error when  len is less than or equal to 0.

ippStsLnZeroArg                   Indicates a warning for zero-valued input vector elements.

ippStsLnNegArg                    Indicates a warning for negative input vector elements.

SumLn
DEPRECATED. Sums natural logarithms of each
element of a vector.

Syntax
IppStatus ippsSumLn_32f(const Ipp32f* pSrc, int len, Ipp32f* pSum        );
IppStatus ippsSumLn_64f(const Ipp64f* pSrc, int len, Ipp64f* pSum        );
IppStatus ippsSumLn_32f64f(const Ipp32f* pSrc, int len, Ipp64f* pSum        );
IppStatus ippsSumLn_16s32f(const Ipp16s* pSrc, int len, Ipp32f* pSum        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

pSum                         Pointer to the output result.

len                          Number of elements in the vector.

Description
The function ippsSumLn is deprecated. This function is obsolete and will be removed in a future release. Use
the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.

                                                                                            121
---------------------Page 122---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

This function computes the sum of natural logarithms of each element of the vector pSrc and stores the
result value in pSum. The summation is given by:

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pSrc  or pSum pointer is NULL.

ippStsSizeErr                     Indicates an error when len  is less than or equal to 0.

ippStsLnZeroArg                   Indicates a warning for zero-valued input vector elements.
                                  Operation execution is not aborted. The value of the
                                  destination vector element for floating-point operations is set
                                  to -Inf.
ippStsLnNegArg                    Indicates a warning for negative input vector elements.
                                  Operation execution is not aborted. The value of the
                                  destination vector element for floating-point operations is set
                                  to NaN.

Arctan
Computes the inverse tangent of each element of a
vector.

Syntax
IppStatus ippsArctan_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len        );
IppStatus ippsArctan_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len        );
IppStatus ippsArctan_32f_I(Ipp32f* pSrcDst, int len      );
IppStatus ippsArctan_64f_I(Ipp64f* pSrcDst, int len      );

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.

pSrcDst                      Pointer to the source and destination vector pSrcDst for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function computes the inverse tangent of each element of pSrc and stores the result in the
corresponding element of pDst.
The computation is performed as follows:
pDst [n] = arctan(pSrc [n])   , 0 ≤ n < len .

   122
---------------------Page 123---------------------

                                                                        Essential Functions  5 

Return Values

ippStsNoErr                     Indicates no error.

ippStsNullPtrErr                Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                NULL .
ippStsSizeErr                   Indicates an error when len is less than or equal to 0.

Normalize
Normalizes elements of a real or complex vector using
offset and division operations.

Syntax
IppStatus ippsNormalize_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f vSub,
Ipp32f vDiv);
IppStatus ippsNormalize_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f vSub,
Ipp64f vDiv);
IppStatus ippsNormalize_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, Ipp32fc vSub,
Ipp32f vDiv);
IppStatus ippsNormalize_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, Ipp64fc vSub,
Ipp64f vDiv);
IppStatus ippsNormalize_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int len, Ipp16s vSub,
int vDiv, int scaleFactor );
IppStatus ippsNormalize_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, Ipp16sc
vSub, int vDiv, int scaleFactor  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

vSub                        Subtrahend value.

vDiv                        Denominator value.

pDst                        Pointer to the vector which stores the normalized elements.

len                         Number of elements in the vector

scaleFactor                 Scale factor, refer to Integer Scaling.

Description
This function subtracts vSub from elements of the input vector pSrc, divides the differences by vDiv, and
stores the result in pDst. The computation is performed as follows:
pDst[n] = (pSrc[n] - vSub)/vDiv  .

                                                                                       123
---------------------Page 124---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pSrc or pDst pointer is NULL.

ippStsSizeErr                      Indicates an error when  len is less than or equal to 0.

ippStsDivByZeroErr                 Indicates an error when  vDiv is equal to 0 or less than the
                                   minimum floating-point positive number.

Cauchy, CauchyD, CauchyDD2
DEPRECATED. Computes Cauchy robust error function
and its first and second derivatives

Syntax
IppStatus ippsCauchy_32f_I(Ipp32f* pSrcDst, int len, Ipp32f param         );
IppStatus ippsCauchyD_32f_I(Ipp32f* pSrcDst, int len, Ipp32f param         );
IppStatus ippsCauchyDD2_32f_I(Ipp32f* pSrcDst, Ipp32f* pD2FVal, int len, Ipp32f param            );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcDst                       Pointer to the source and destination vector.

len                           Number of elements in the vector

pD2FVal                       Pointer to the array of the values of the second derivatives.

param                         Parameter C of the Cuachy function.

Description
These functions are deprecated. These functions are obsolete and will be removed in a future release. Use
the following link for details:http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
For len elements of the source vector pSrcDst the function perform the following operations:
the function ippsCauchy calculates the Cauchy function and stores the results in the vector pSrcDst;
the function ippsCauchyD calculates first derivatives of the Cauchy function and stores the results in the
vector pSrcDst;
the function ippsCauchyDD2 calculates first and second derivatives of the Cauchy function and stores the
values of first derivatives in the vector pSrcDst, values of second derivatives - in the array pD2FVal.
The following pseudo-codes show how these operations are performed.
Calculating the Cauchy function (ippsCauchy):
for( int i = 0; i < len; i++ ) pSrcDst[i] = φ      C(pSrcDst[i]);
Calculating first derivatives of the Cauchy function (ippsCauchyD):

   124
---------------------Page 125---------------------

                                                                            Essential Functions  5 

for( int i = 0; i < len; i++ ) pSrcDst[i] =ψ     C(pSrcDst[i]);
Calculating first and second derivatives of the Cauchy function (ippsCauchyDD2):
for( int i = 0; i < len; i++ ){
pD2FVal[i] = ψ'C(pSrcDst[i]);
pSrcDst[i] = ψC(pSrcDst[i]);
}

Here

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                     Indicates an error when  len is less than 0.

Conversion Functions

The functions described in this section perform the following conversion operations for vectors:
• Sorting all elements of a vector
• Data type conversion (including floating-point to integer and integer to floating-point)
• Joining several vectors
• Extracting components from a complex vector and constructing a complex vector
• Computing the complex conjugates of vectors
• Cartesian to polar and polar to Cartesian coordinate conversion.
This section also describes the Intel     functions that extract real and imaginary components from a
complex vector or construct a complex vector using its real and imaginary components. The functions 
ippsReal  and ippsImag return the real and imaginary parts of a complex vector in a separate vector,
respectively. The function ippsRealToCplx constructs a complex vector from real and imaginary
components stored in two respective vectors. The function ippsCplxToReal returns the real and imaginary
parts of a complex vector in two respective vectors. The function ippsMagnitude computes the magnitude
of a complex vector elements.
Additionally this section describes functions that perform the Viterbi decoding for V34 receiver.

SortAscend, SortDescend
Sorts all elements of a vector.

Syntax
IppStatus ippsSortAscend_8u_I(Ipp8u* pSrcDst, int len      );
IppStatus ippsSortAscend_16u_I(Ipp16u* pSrcDst, int len       );
IppStatus ippsSortAscend_16s_I(Ipp16s* pSrcDst, int len       );
IppStatus ippsSortAscend_32s_I(Ipp32s* pSrcDst, int len       );
IppStatus ippsSortAscend_32f_I(Ipp32f* pSrcDst, int len       );
IppStatus ippsSortAscend_64f_I(Ipp64f* pSrcDst, int len       );

IppStatus ippsSortDescend_8u_I(Ipp8u* pSrcDst, int len       );
IppStatus ippsSortDescend_16u_I(Ipp16u* pSrcDst, int len       );

                                                                                            125
---------------------Page 126---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsSortDescend_16s_I(Ipp16s* pSrcDst, int len    );
IppStatus ippsSortDescend_32s_I(Ipp32s* pSrcDst, int len    );
IppStatus ippsSortDescend_32f_I(Ipp32f* pSrcDst, int len    );
IppStatus ippsSortDescend_64f_I(Ipp64f* pSrcDst, int len    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcDst                     Pointer to the source and destination vector.

len                         Number of elements in the vector

Description
These functions rearrange all elements of the source vector pSrcDst in the ascending or descending order,
respectively, and store the result in the destination vector pSrcDst.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrcDst is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to zero.

Example
The example below shows how to call the function ippsSortAscend_8u_I.
void func_sort() 
{
    Ipp8u vec[10] = {0,2,4,5,1,8,9,4,6,7};
    IppStatus status;        

    status = ippsSortAscend_8u_I(vec,10);
    if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status)); 
}

Result:
      0 1 2 4 4 5 6 7 8 9

SortIndexAscend, SortIndexDescend
Rearranges elements of the vector and their indexes.

Syntax
IppStatus ippsSortIndexAscend_8u_I(Ipp8u* pSrcDst, int* pDstIdx, int len      );
IppStatus ippsSortIndexAscend_16u_I(Ipp16u* pSrcDst, int* pDstIdx, int len      );
IppStatus ippsSortIndexAscend_16s_I(Ipp16s* pSrcDst, int* pDstIdx, int len      );

   126
---------------------Page 127---------------------

                                                                       Essential Functions  5 

IppStatus ippsSortIndexAscend_32s_I(Ipp32s* pSrcDst, int* pDstIdx, int len    );
IppStatus ippsSortIndexAscend_32f_I(Ipp32f* pSrcDst, int* pDstIdx, int len    );
IppStatus ippsSortIndexAscend_64f_I(Ipp64f* pSrcDst, int* pDstIdx, int len    );

IppStatus ippsSortIndexDescend_8u_I(Ipp8u* pSrcDst, int* pDstIdx, int len    );
IppStatus ippsSortIndexDescend_16u_I(Ipp16u* pSrcDst, int* pDstIdx, int len    );
IppStatus ippsSortIndexDescend_16s_I(Ipp16s* pSrcDst, int* pDstIdx, int len    );
IppStatus ippsSortIndexDescend_32s_I(Ipp32s* pSrcDst, int* pDstIdx, int len    );
IppStatus ippsSortIndexDescend_32f_I(Ipp32f* pSrcDst, int* pDstIdx, int len    );
IppStatus ippsSortIndexDescend_64f_I(Ipp64f* pSrcDst, int* pDstIdx, int len    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcDst                     Pointer to the source and destination vector.

pDstIdx                     Pointer to the destination vector containing indexes.

len                         Number of elements in the vector

Description
These functions rearrange all elements of the source vector pSrcDst in the ascending or descending order,
respectively, and store the elements in the destination vector pSrcDst, and their indexes in the desalination
vector pDstIdx. If some elements are identical, their indexes are not ordered.

Return Values

ippStsNoErr                     Indicates no error.

ippStsNullPtrErr                Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                   Indicates an error when len is less than or equal to 0.

SortRadixAscend, SortRadixDescend
Sorts all elements of a vector using radix sorting
algorithm.

Syntax
IppStatus ippsSortRadixAscend_8u_I(Ipp8u* pSrcDst, Ipp8u* pTmp, Ipp32s len    );
IppStatus ippsSortRadixAscend_16u_I(Ipp16u* pSrcDst, Ipp16u* pTmp, Ipp32s len    );
IppStatus ippsSortRadixAscend_16s_I(Ipp16s* pSrcDst, Ipp16s* pTmp, Ipp32s len    );
IppStatus ippsSortRadixAscend_32u_I(Ipp32u* pSrcDst, Ipp32u* pTmp, Ipp32s len    );
IppStatus ippsSortRadixAscend_32s_I(Ipp32s* pSrcDst, Ipp32s* pTmp, Ipp32s len    );

                                                                                      127
---------------------Page 128---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsSortRadixAscend_32f_I(Ipp32f* pSrcDst, Ipp32f* pTmp, Ipp32s len      );
IppStatus ippsSortRadixAscend_64f_I(Ipp64f* pSrcDst, Ipp64f* pTmp, Ipp32s len      );

IppStatus ippsSortRadixDescend_8u_I(Ipp8u* pSrcDst, Ipp8u* pTmp, Ipp32s len      );
IppStatus ippsSortRadixDescend_16u_I(Ipp16u* pSrcDst, Ipp16u* pTmp, Ipp32s len      );
IppStatus ippsSortRadixDescend_16s_I(Ipp16s* pSrcDst, Ipp16s* pTmp, Ipp32s len      );
IppStatus ippsSortRadixDescend_32u_I(Ipp32u* pSrcDst, Ipp32u* pTmp, Ipp32s len      );
IppStatus ippsSortRadixDescend_32s_I(Ipp32s* pSrcDst, Ipp32s* pTmp, Ipp32s len      );
IppStatus ippsSortRadixDescend_32f_I(Ipp32f* pSrcDst, Ipp32f* pTmp, Ipp32s len      );
IppStatus ippsSortRadixDescend_64f_I(Ipp64f* pSrcDst, Ipp64f* pTmp, Ipp32s len      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcDst                     Pointer to the source and destination vector.

pTmp                        Pointer to the temporary vector.

len                         Number of elements in the vector

Description
These functions rearrange all elements of the source vector pSrcDst in the ascending or descending order,
respectively, using “radix sort” algorithm, and store the result in the destination vector pSrcDst. Temporary
vector pTmp is required by the algorithm, its size must be equal to the the size of the source vector.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrcDst or pTmp is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Example
The example below shows how to call the function ippsSortRadixAscend_8u_I.
void func_sort() 
{
   Ipp8u i, vec[10] = {0,2,4,5,1,8,9,4,6,7}, tmp[10];
   IppStatus status;
   status = ippsSortRadixAscend_8u_I(vec,tmp,10);
   if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status));
   else {
       for(i=0; i<10; i++) printf("%d ",vec[i]); printf("\n");
   } 
} 

   128
---------------------Page 129---------------------

                                                                     Essential Functions  5 

Result:
   0 1 2 4 4 5 6 7 8 9

SortRadixIndexAscend, SortRadixIndexDescend
Indirectly sorts all elements of a vector using radix
sorting algorithm.

Syntax
IppStatus ippsSortRadixIndexAscend_8u(const Ipp32f* const pSrc, Ipp32s srcStrideBytes,
Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len);
IppStatus ippsSortRadixIndexAscend_16u(const Ipp16u* const pSrc, Ipp32s srcStrideBytes,
Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len);
IppStatus ippsSortRadixIndexAscend_16s(const Ipp16s* const pSrc, Ipp32s srcStrideBytes,
Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len);
IppStatus ippsSortRadixIndexAscend_32s(const Ipp32s* const pSrc, Ipp32s srcStrideBytes,
Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len);
IppStatus ippsSortRadixIndexAscend_32u(const Ipp32u* const pSrc, Ipp32s srcStrideBytes,
Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len);
IppStatus ippsSortRadixIndexAscend_32f(const Ipp32f* const pSrc, Ipp32s srcStrideBytes,
Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len);

IppStatus ippsSortRadixIndexDescend_8u(const Ipp32f* const pSrc, Ipp32s srcStrideBytes,
Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len);
IppStatus ippsSortRadixIndexDescend_16u(const Ipp16u* const pSrc, Ipp32s
srcStrideBytes, Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len );
IppStatus ippsSortRadixIndexDescend_16s(const Ipp16s* const pSrc, Ipp32s
srcStrideBytes, Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len );
IppStatus ippsSortRadixIndexDescend_32s(const Ipp32s* const pSrc, Ipp32s
srcStrideBytes, Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len );
IppStatus ippsSortRadixIndexDescend_32u(const Ipp32u* const pSrc, Ipp32s
srcStrideBytes, Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len );
IppStatus ippsSortRadixIndexDescend_32f(const Ipp32f* const pSrc, Ipp32s
srcStrideBytes, Ipp32s* pDstIndx, Ipp32s* pTmpIndx, Ipp32s len );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                      Pointer the source sparse keys vector.

srcStrideBytes            Distance in bytes between two consecutive elements of the source
                          vector.
pDstIndx                  Pointer to the destination vector of indexes.

                                                                                   129
---------------------Page 130---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

pTmpIndx                     Pointer to the temporary vector of indexes.

len                          Number of elements in the vectors.

Description
These functions indirectly sort all elements of the source sparse keys vector pSrc in the ascending or
descending order, respectively, using "radix sort" algorithm and store the indexes of resulting arrangement
order in the destination vector pDstIndx. Elements of the source vector are not rearranged.
Temporary vector pTmpIndx is required by the algorithm, its size must be equal to the size of the destination
vector and be sufficient to contain len number of indexes. Intervals between the elements of the source
sparse vector pSrc in memory must be equal to the value of srcStrideBytes, minimum value of which is
equal to the size of the datatype of the key value. The sorting algorithm does not change the relative order
of the elements with equal keys.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pSrc or pTmpIndx  is NULL.

ippStsSizeErr                     Indicates an error when  len is less than or equal to zero, or
                                  srcStrideBytes   is less than sizeof(key type) .

Example
The example below shows how to call the functions ippsSortRadixindexAscend_8u_I and
ippsSortRadixindexDescend_8u_I    .
void testsort(void) {
    struct C {
        Ipp8u key1;
        Ipp8u key2;
        float data;
    }
 c_array[4] = {{0,2,1.0f}, {1,3,2.0f}, {1,4,3.0f}, {8,2,10.0f}};

    int          idx1[4], idx2[4], tmp[4], i;

    ippsSortRadixIndexDescend_8u(&c_array[0].key1, sizeof(C), idx1, tmp, 4);
    ippsSortRadixIndexAscend_8u(&c_array[0].key2, sizeof(C), idx2, tmp, 4);
    printf("%f, %f, %f, %f\n",c_array[idx1[0]].data, c_array[idx1[1]].data, 
               c_array[idx1[2]].data, c_array[idx1[3]].data );
    printf("%f, %f, %f, %f\n",c_array[idx2[0]].data, c_array[idx2[1]].data,
               c_array[idx2[2]].data, c_array[idx2[3]].data ); 
}

Result:
   10.0  2.0  3.0  1.0
    1.0 10.0  2.0  3.0

SwapBytes
Reverses the byte order of a vector.

Syntax
IppStatus ippsSwapBytes_16u(const Ipp16u* pSrc, Ipp16u* pDst, int len         );
IppStatus ippsSwapBytes_24u(const Ipp8u* pSrc, Ipp8u* pDst, int len        );

   130
---------------------Page 131---------------------

                                                                           Essential Functions  5 

IppStatus ippsSwapBytes_32u(const Ipp32u* pSrc, Ipp32u* pDst, int len       );
IppStatus ippsSwapBytes_64u(const Ipp64u* pSrc, Ipp64u* pDst, int len       );
IppStatus ippsSwapBytes_16u_I(Ipp16u* pSrcDst, int len     );
IppStatus ippsSwapBytes_24u_I(Ipp8u* pSrcDst, int len     );
IppStatus ippsSwapBytes_32u_I(Ipp32u* pSrcDst, int len     );
IppStatus ippsSwapBytes_64u_I(Ipp64u* pSrcDst, int len     );

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.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function reverses the endian order (byte order) of the source vector pSrc (pSrcDst for the in-place
operation) and stores the result in pDst (pSrcDst). When the low-order byte is stored in memory at the
lowest address, and the high-order byte at the highest address, the little-endian order is implemented.When
the high-order byte is stored in memory at the lowest address, and the low-order byte at the highest
address, the big-endian order is implemented. The function ippsSwapBytes allows to switch from one order
to the other in either direction.

Return Values

ippStsNoErr                       Indicates no error.

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

ippStsSizeErr                     Indicates an error when len is less than or equal to zero.

Example
The example below shows how to call the function ippsSwapBytes_16u_I.
void func_swap() 
{
    Ipp16u vec[2] = {0x1234,0x5678};
    IppStatus status;

    status = ippsSwapBytes_16u_I(vec, 2);
    if(ippStsNoErr != status)
      printf("    Error: %s",ippGetStatusString(status)); 
}  

                                                                                           131
---------------------Page 132---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Result:
vec[0] = 0x3412 
vec[1] = 0x7856

Convert
Converts the data type of a vector and stores the
results in a second vector.

Syntax
IppStatus ippsConvert_8s16s(const Ipp8s* pSrc,Ipp16s* pDst, int len );
IppStatus ippsConvert_8s32f(const Ipp8s* pSrc, Ipp32f* pDst, int len );
IppStatus ippsConvert_8u32f(const Ipp8u* pSrc, Ipp32f* pDst, int len );
IppStatus ippsConvert_16s8s_Sfs(const Ipp16s* pSrc, Ipp8s* pDst, Ipp32u len,
IppRoundMode rndMode, int scaleFactor);
IppStatus ippsConvert_16s32s(const Ipp16s* pSrc, Ipp32s* pDst, int len );
IppStatus ippsConvert_16s32f(const Ipp16s* pSrc, Ipp32f* pDst, int len );
IppStatus ippsConvert_16u32f(const Ipp16u* pSrc, Ipp32f* pDst, int len );
IppStatus ippsConvert_32s16s(const Ipp32s* pSrc, Ipp16s* pDst, int len );
IppStatus ippsConvert_32s32f(const Ipp32s* pSrc, Ipp32f* pDst, int len );
IppStatus ippsConvert_32s64f(const Ipp32s* pSrc, Ipp64f* pDst, int len );
IppStatus ippsConvert_32f64f(const Ipp32f* pSrc, Ipp64f* pDst, int len );
IppStatus ippsConvert_64s64f(const Ipp64s* pSrc, Ipp64f* pDst, Ipp32u len );
IppStatus ippsConvert_64f32f(const Ipp64f* pSrc, Ipp32f* pDst, int len );
IppStatus ippsConvert_16s32f_Sfs(const Ipp16s* pSrc, Ipp32f* pDst, int len, int
scaleFactor);
IppStatus ippsConvert_16s64f_Sfs(const Ipp16s* pSrc, Ipp64f* pDst, int len, int
scaleFactor);
IppStatus ippsConvert_32s16s_Sfs(const Ipp32s* pSrc, Ipp16s* pDst, int len, int
scaleFactor);
IppStatus ippsConvert_32s32f_Sfs(const Ipp32s* pSrc, Ipp32f* pDst, int len, int
scaleFactor);
IppStatus ippsConvert_32s64f_Sfs(const Ipp32s* pSrc, Ipp64f* pDst, int len, int
scaleFactor);
IppStatus ippsConvert_32f8s_Sfs(const Ipp32f* pSrc, Ipp8s* pDst, int len, IppRoundMode
rndMode, int scaleFactor);
IppStatus ippsConvert_32f8u_Sfs(const Ipp32f* pSrc, Ipp8u* pDst, int len, IppRoundMode
rndMode, int scaleFactor);
IppStatus ippsConvert_32f16s_Sfs(const Ipp32f* pSrc, Ipp16s* pDst, int len,
IppRoundMode rndMode, int scaleFactor);
IppStatus ippsConvert_32f16u_Sfs(const Ipp32f* pSrc, Ipp16u* pDst, int len,
IppRoundMode rndMode, int scaleFactor);
IppStatus ippsConvert_32f32s_Sfs(const Ipp32f* pSrc, Ipp32s* pDst, int len,
IppRoundMode rndMode, int scaleFactor);

  132
---------------------Page 133---------------------

                                                                     Essential Functions  5 

IppStatus ippsConvert_64s32s_Sfs(const Ipp64s* pSrc, Ipp32s* pDst, int len,
IppRoundMode rndMode, int scaleFactor);
IppStatus ippsConvert_64f16s_Sfs(const Ipp64f* pSrc, Ipp16s* pDst, int len,
IppRoundMode rndMode, int scaleFactor);
IppStatus ippsConvert_64f32s_Sfs(const Ipp64f* pSrc, Ipp32s* pDst, int len,
IppRoundMode rndMode, int scaleFactor);
IppStatus ippsConvert_64f64s_Sfs(const Ipp64f* pSrc, Ipp64s* pDst, Ipp32u len,
IppRoundMode rndMode, int scaleFactor);

IppStatus ippsConvert_24u32u(const Ipp8u* pSrc, Ipp32u* pDst, int len );
IppStatus ippsConvert_24u32f(const Ipp8u* pSrc, Ipp32f* pDst, int len );
IppStatus ippsConvert_32u24u_Sfs(const Ipp32u* pSrc, Ipp8u* pDst, int len, int
scaleFactor);
IppStatus ippsConvert_32f24u_Sfs(const Ipp32f* pSrc, Ipp8u* pDst, int len, int
scaleFactor);

IppStatus ippsConvert_24s32s(const Ipp8u* pSrc, Ipp32s* pDst, int len );
IppStatus ippsConvert_24s32f(const Ipp8u* pSrc, Ipp32f* pDst, int len );
IppStatus ippsConvert_32s24s_Sfs(const Ipp32s* pSrc, Ipp8u* pDst, int len, int
scaleFactor);
IppStatus ippsConvert_32f24s_Sfs(const Ipp32f* pSrc, Ipp8u* pDst, int len, int
scaleFactor);

IppStatus ippsConvert_16s16f(const Ipp16s* pSrc, Ipp16f* pDst, int len, IppRoundMode
rndMode);
IppStatus ippsConvert_32f16f(const Ipp32f* pSrc, Ipp16f* pDst, int len, IppRoundMode
rndMode);
IppStatus ippsConvert_16f16s_Sfs(const Ipp16f* pSrc, Ipp16s* pDst, int len,
IppRoundMode rndMode, int scaleFactor);
IppStatus ippsConvert_16f32f(const Ipp16f* pSrc, Ipp32f* pDst, int len );

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.

rndMode                    Rounding mode, the following values are possible:

                           ippRndZero floating-point values are truncated to zero

                                                                                    133
---------------------Page 134---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

                              ippRndNear  floating-point values are rounded to the nearest even integer
                              when the fractional part equals 0.5; otherwise they are rounded to the
                              nearest integer

                              ippRndFinancial   floating-point values are rounded down to the nearest
                              integer when the fractional part is less than 0.5, or rounded up to the
                              nearest integer if the fractional part is equal or greater than 0.5.

len                           Number of elements in the vector.

scaleFactor                   Scale factor, refer to Integer Scaling.

Description
This function converts the type of data contained in the vector pSrc and stores the results in pDst.
Functions with Sfs suffixe perform scaling of the result value in accordance with the scaleFactor value.
The converted result is saturated if it exceeds the output data range.
Functions that operate with 16f data do not support the ippRndFinancial rounding mode.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pDst  or pSrc pointer is NULL.

ippStsSizeErr                      Indicates an error when  len is less than or equal to 0.

ippStsRoundModeNotSupportedErr     Indicates an error when the specified rounding mode is not
                                   supported.

Example
The example below shows how to use the ippsConvert  function .
Ipp32s src32s[2] = { 33000, -33000 }; 
Ipp32f src32f[2] = { 126.6, -125.4 }; 
Ipp32f src_32f[2] = { 113.12, -113.6 }; 
Ipp32f src1_32f[5] = { -2.5, -2.4, 1.4, 1.5, 1.6}; 
Ipp8s src_8s[2] = { 125, -125 }; 
Ipp8u src8[1] = { 255 }; 
Ipp32f dst32f[1]; 
Ipp16s dst16[2]; 
Ipp16s dst_16s[2]; 
Ipp8u dst8u[2]; 
Ipp8s dstN8[2]; 
Ipp8s dstZ8[2];

int scaleFactor = 0;  // no scaling 

ippsConvert_8s16s ( src_8s, dst_16s, 2 ); 
ippsConvert_8u32f ( src8, dst32f, 1 ); 
ippsConvert_32s16s ( src32s, dst16, 2 ); 
ippsConvert_32f8s_Sfs ( src32f, dstN8, 2, ippRndNear, scaleFactor ); 
ippsConvert_32f8s_Sfs ( src32f, dstZ8, 2, ippRndZero, scaleFactor ); 
ippsConvert_32f8u_Sfs ( src_32f, dst8u, 2, ippRndNear, scaleFactor ); 
ippsConvert_32f8s_Sfs ( src1_32f, dstF8, 5, ippRndFinancial, scaleFactor );

   134
---------------------Page 135---------------------

                                                                          Essential Functions  5 

Result:
8s16s >>        dst_16s = { 125, -125} 
8u32f >>         dst32f  = { 255.0 } 
32s16s >>         dst16  =  { 32767, -32768}    // max, min  16s values

// results for scaleFactor = 0 
32f8s_Sfs >>    dstN8  =  { 127, -125 }       // scaleFactor = 0 
32f8s_Sfs >>    dstZ8  =  { 126, -125 }       // scaleFactor = 0 
32f8s_Sfs >>    dstF8  =  { -3, -2, 1, 2, 2 } // scaleFactor = 0 
32f8u_Sfs >>    dst8u  =  { 113, 0 }          // scaleFactor = 0

// results for scaleFactor = 2 
32f8s_Sfs >>    dstN8  =  { 32, -31 }         // scaleFactor = 2 
32f8s_Sfs >>    dstZ8  =  { 31, -31 }         // scaleFactor = 2 
32f8u_Sfs >>    dst8u  =  { 28, 0 }           // scaleFactor = 2

The function ippsConvert_32f16f has the following specific when it processes the number that are not in
the range [MinVal16f..MaxVal16f]:
 If x > MaxVal16f then {
    If ( rndMode == IppRndNear ) then {
         y = Convert_32f16f (x) = +INF
    }
    If ( rndMode == IppRndZero ) then {
       If ( x == +INF ) then {
          y = Convert_32f16f (x) = +INF
       } else {
          y = Convert_32f16f(x) = MaxVal16f
       }
    }
 }

 If x < MinVal16f then {
    If ( rndMode == IppRndNear ) then {
          y = Convert_32f16f (x) = -INF
     }
    If ( rndMode == IppRndZero ) then {
        If ( x == -INF ) then {
            y = Convert_32f16f (x) = -INF
        } else {
           y = Convert_32f16f(x) = M in Val16f
        }
    }
 }
See Also
Integer Scaling

Join
DEPRECATED. Converts the floating-point data of
several vectors to integer data, and stores the results
in a single vector.

Syntax
IppStatus ippsJoin_32f16s_D2L(const Ipp32f** pSrc, int nChannels, int chanLen, Ipp16s*
pDst);

Include Files
ippac.h

                                                                                          135
---------------------Page 136---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Domain Dependencies
Headers: ippcore.h , ippvm.h , ipps.h
Libraries: ippcore.lib, ippvm.lib , ipps.lib

Parameters

pSrc                          Pointer to an array of pointers to the source vectors.

pDst                          Pointer to the destination vector.

nChannels                     Number of source vectors.

chanLen                       Number of elements in each sourcet vector.

Description
The function ippsJoin is deprecated. This function is obsolete and will be removed in a future release. Use
the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function converts floating-point data of nChannels input vectors stored in the array pSrc to integer
data type and writes the results to the destination vector pDst in the following order: first element of first
vector, first element of second vector, ..., first element of the last vector in the array; second element of first
vector, second element of second vector, and so on. The converted value is saturated if it exceeds the output
data range.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error condition if at least one of the specified
                                   pointers is NULL.
ippStsSizeErr                      Indicates an error condition if nChannels  or chanLen  is less than
                                   or equal to zero.

Example
The example below shows how to use the function ippsJoin.
Ipp32f** pSrc; 
Ipp16s pDst[8]; 
int nChannels = 2; 
int chanLen = 4; 
int bufSize; 
float k = 1.0;

pSrc = (Ipp32f**) ippiMalloc_32f_C1 ( 2, 1, &bufSize ); 
for(int I = 0; I < 2; i++) {
    pSrc[i] = ( Ipp32f*) ippiMalloc_32f_C1 ( 4, 1, &bufSize );
    for(int j = 0; j < 4; j++)
        pSrc[i][j] = k++; 
}

ippsJoin_32f16s_D2L ( (const Ipp32f**) pSrc, nChannels, chanLen, (Ipp16s*) pDst );

Result:
1.0 2.0 3.0 4.0 
5.0 6.0 7.0 8.0         pSrc
1 5 2 6 3 7 4 8        pDst

   136
---------------------Page 137---------------------

                                                                              Essential Functions  5 

JoinScaled
Converts with scaling the floating-point data of several
vectors to integer data and stores the results in a
single vector.

Syntax
IppStatus ippsJoinScaled_32f16s_D2L(const Ipp32f** pSrc, int nChannels, int chanLen,
Ipp16s* pDst );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsJoinScaled_32f24s_D2L(const Ipp32f** pSrc, int nChannels, int chanLen,
Ipp8u* pDst );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                          Pointer to an array of pointers to the source vectors.

pDst                          Pointer to the destination vector.

nChannels                     Number of source vectors.

chanLen                       Number of elements in each sourcet vector.

Description
The function ippsJoinScaled_32f24s_D2L    is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function converts floating-point data of nChannels input vectors stored in the array pSrc to integer
data type with scaling. Input data must be in the range [-1.0, 1.0] that is mapped onto output data type
range [dst_Min..dst_Max ] (see Data Ranges for more information on data types and ranges). If the input
data exceed the range [-1.0, 1.0], they are saturated. The function uses the following formula for scaling:
pDst[n] = dst_Min + k * [pSrc[n] - (-1)]
where k = (dst_Max - dst_Min) / (1 - (-1))
Mapped values are rounded to the nearest integer.
The function ippsJoinScaled  writes the results to the destination vector pDst in the following order: first
element of first vector, first element of second vector, ..., first element of the last vector in the array; second
element of first vector, second element of second vector, and so on.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates a then error condition if at least one of the specified
                                   pointers is NULL.

                                                                                               137
---------------------Page 138---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsSizeErr                      Indicates an error condition if nChannels  or chanLen is less than
                                   or equal to 0.

SplitScaled
DEPRECATED. Converts the integer data of a vector to
floating-point data with scaling, and stores the result
in several vectors.

Syntax
IppStatus ippsSplitScaled_16s32f_D2L(const Ipp16s* pSrc, Ipp32f** pDst, int nChannels,
int chanLen );
IppStatus ippsSplitScaled_24s32f_D2L(const Ipp8u* pSrc, Ipp32f** pDst, int nChannels,
int chanLen );

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 an array of pointers to the destination vectors.

nChannels                     Number of destination vectors.

chanLen                       Number of elements in each destination vector.

Description
The function ippsSplitScaled  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function converts integer data of the source vector pSrc to the floating-point data type with scaling. The
whole range of the input data [src_Min..src_Max] (see Data Ranges for more information on data types and
ranges) is mapped onto the output data range [-1.0, 1.0] The function uses the following formula for scaling:
pDst[n] = (-1) + k * (pSrc[n] - src_Min)      ,
where k = (1 - (-1)) / (src_Max - src_Min)      .
The function ippsSplitScaled  writes the results to the nChannels destination vectors pDstin the following
order: first element of the input vector becomes the first element of the first output vector, second element
of the input vector becomes the first element of the second output vector, and so on.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates a then error condition if at least one of the specified
                                   pointers is NULL.

   138
---------------------Page 139---------------------

                                                                          Essential Functions  5 

ippStsSizeErr                    Indicates an error condition if nChannels or chanLen is less than
                                 or equal to 0.

Conj
Stores the complex conjugate values of a vector in a
second vector or in-place.

Syntax
IppStatus ippsConj_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len      );
IppStatus ippsConj_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len      );
IppStatus ippsConj_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len      );
IppStatus ippsConj_16sc_I(Ipp16sc* pSrcDst, int len     );
IppStatus ippsConj_32fc_I(Ipp32fc* pSrcDst, int len     );
IppStatus ippsConj_64fc_I(Ipp64fc* pSrcDst, int len     );

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.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function stores in pDst the element-wise conjugation of the complex vector pSrc. The element-wise
conjugation of the vector is defined as follows:
pDst[n].re = pSrc[n].re
pDst[n].im = - pSrc[n].im
The in-place flavors of ippsConj store in pSrcDst the element-wise conjugation of the complex vector
pSrcDst.
The element-wise conjugation of the vector is defined as follows:
pSrcDst[n].re = pSrcDst[n].re
pSrcDst[n].im = - pSrcDst[n].im

Return Values

ippStsNoErr                      Indicates no error.

                                                                                          139
---------------------Page 140---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsNullPtrErr                   Indicates an error when the  pSrc, pDst, or pSrcDst   pointer is
                                   NULL.
ippStsSizeErr                      Indicates an error when  len is less than or equal to 0.

ConjFlip
Computes the complex conjugate of a vector and
stores the result in reverse order.

Syntax
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsConjFlip_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len          );
IppStatus ippsConjFlip_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len          );
IppStatus ippsConjFlip_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len          );

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.

len                           Number of elements in the vector.

Description
The function ippsConjFlip_16sc  is deprecated. Integer APIs for linear transforms are obsolete and will be
removed in a future release. All linear-transform functions are FP internally - use FP variant of this function.
Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function computes the conjugate of the vector pSrc and stores the result, in reverse order, in pDst. The
complex conjugate, stored in reverse order, is defined as follows:
pDst[n] = conj(pSrc[len - n - 1])    .
Note that if pSrc and pDst overlap in memory, the function returns unpredictable results.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pSrc or pDst pointer is NULL.

ippStsSizeErr                      Indicates an error when  len is less than or equal to 0.

   140
---------------------Page 141---------------------

                                                                         Essential Functions  5 

Magnitude
Computes the magnitudes of the elements of a
complex vector.

Syntax
IppStatus ippsMagnitude_32f(const Ipp32f* pSrcRe, const Ipp32f* pSrcIm, Ipp32f* pDst,
int len);
IppStatus ippsMagnitude_64f(const Ipp64f* pSrcRe, const Ipp64f* pSrcIm, Ipp64f* pDst,
int len);
IppStatus ippsMagnitude_32fc(const Ipp32fc* pSrc, Ipp32f* pDst, int len     );
IppStatus ippsMagnitude_64fc(const Ipp64fc* pSrc, Ipp64f* pDst, int len     );
IppStatus ippsMagnitude_16s32f(const Ipp16s* pSrcRe, const Ipp16s* pSrcIm, Ipp32f*
pDst, int len );
IppStatus ippsMagnitude_16sc32f(const Ipp16sc* pSrc, Ipp32f* pDst, int len     );
IppStatus ippsMagnitude_16s_Sfs(const Ipp16s* pSrcRe, const Ipp16s* pSrcIm, Ipp16s*
pDst, int len, int scaleFactor  );
IppStatus ippsMagnitude_16sc_Sfs(const Ipp16sc* pSrc, Ipp16s* pDst, int len, int
scaleFactor);
IppStatus ippsMagnitude_32sc_Sfs(const Ipp32sc* pSrc, Ipp32s* pDst, int len, int
scaleFactor);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

pSrcRe                      Pointer to the vector with the real parts of complex elements.

pSrcIm                      Pointer to the vector with the imaginary parts of complex elements.

pDst                        Pointer to the destination vector.

len                         Number of elements in the vector

scaleFactor                 Scale factor, refer to Integer Scaling.

Description
The complex flavor of this function computes the element-wise magnitude of the complex vector pSrc and
stores the result in pDst. The element-wise magnitude is defined by the formula:
magn[n] = (pSrc[n].re2 + pSrc[n].im2)1/2

The real flavor of the function ippsMagnitude computes the element-wise magnitude of the complex vector
whose real and imaginary components are specified in the vectors pSrcRe and pSrcIm, respectively, and
stores the result in pDst. The element-wise magnitude is defined by the formula:

                                                                                        141
---------------------Page 142---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

magn[n] = (pSrcRe[n]2 + pSrcIm[n]2)1/2

Return Values

ippStsNoErr                      Indicates no error.

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

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Example
The example below shows how the function ippsMagnitude is used to verify the identity sin2x + cos2x =
1.
void magn(void) {
      Ipp64f x[6], magn[4];
      int n;
      for (n = 0; n<6; ++n) x[n] = sin(IPP_2PI * n / 8);
      ippsMagnitude_64f(x, x+2, magn, 4);
      printf_64f(“magn =”, magn, 4, ippStsNoErr); 
} 

Output:
    magn =  1.000000 1.000000 1.000000 1.000000 
Matlab* Analog: 
    >> n = 0:9; x = sin(2*pi*n/8); z = [x(1:8)+j*x(3:10)]; abs(z(1:4))

MagSquared
DEPRECATED. Computes the squared magnitudes of
the elements of a complex vector.

Syntax
IppStatus ippsMagSquared_32sc32s_Sfs(const Ipp32sc* pSrc, Ipp32s* pDst, int len, int
scaleFactor );
IppStatus ippsMagSquared_32fc64f(const Ipp32fc* pSrc, Ipp64f* pDst, int len       );

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.

len                         Number of elements in the vector

scaleFactor                 Scale factor, refer to Integer Scaling.

   142
---------------------Page 143---------------------

                                                                         Essential Functions  5 

Description
The function ippsMagSquared is deprecated. This function is obsolete and will be removed in a future
release. Use PowerSpectr functionality instead of this one. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function computes the element-wise squared magnitude of the complex vector pSrc and stores the
result in pDst. The element-wise squared magnitude is defined by the formula:
magn[n] = pSrc[n].re2 + pSrc[n].im2

Return Values

ippStsNoErr                      Indicates no error.

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

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Phase
Computes the phase angles of elements of a complex
vector.

Syntax
IppStatus ippsPhase_64fc(const Ipp64fc* pSrc, Ipp64f* pDst, int len     );
IppStatus ippsPhase_32fc(const Ipp32fc* pSrc, Ipp32f* pDst, int len     );
IppStatus ippsPhase_16sc32f(const Ipp16sc* pSrc, Ipp32f* pDst, int len     );
IppStatus ippsPhase_64f(const Ipp64f* pSrcRe, const Ipp64f* pSrcIm, Ipp64f* pDst, int
len);
IppStatus ippsPhase_32f(const Ipp32f* pSrcRe, const Ipp32f* pSrcIm, Ipp32f* pDst, int
len);
IppStatus ippsPhase_16s32f(const Ipp16s* pSrcRe, const Ipp16s* pSrcIm, Ipp32f* pDst,
int len);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsPhase_16sc_Sfs(const Ipp16sc* pSrc, Ipp16s* pDst, int len, int
scaleFactor);
IppStatus ippsPhase_32sc_Sfs(const Ipp32sc* pSrc, Ipp32s* pDst, int len, int
scaleFactor);
IppStatus ippsPhase_16s_Sfs(const Ipp16s* pSrcRe, const Ipp16s* pSrcIm, Ipp16s* pDst,
int len, int scaleFactor );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

                                                                                        143
---------------------Page 144---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

pSrcRe                       Pointer to the source vector which stores the real components.

pSrcIm                       Pointer to the source vector which stores the imaginary
                             components.
pDst                         Pointer to the vector which stores the phase (angle) components of
                             the elements in radians. Phase values are in the range (-π, π].
len                          Number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling .

Description
Functions ippsPhase_16s_Sfs  , ippsPhase_16sc_Sfs , and ippsPhase_32sc_Sfs  are deprecated. These
functions are obsolete and will be removed in a future release. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function returns the phase angles of elements of the complex input vector pSrc, or the complex input
vector whose real and imaginary components are specified in the vectors pSrcRe and pSrcIm, respectively,
and stores the result in the vector pDst. Phase values are returned in radians and are in the range (-π, π] .

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when at least one of the specified pointers is
                                  NULL.
ippStsSizeErr                     Indicates an error when len  is less than or equal to zero.

Example
The example below shows how to call the function ippsPhase_32f.
void func_phase() 
{
    Ipp32f re[4]= {0.0, 1.0, 0.0, 1.0};
    Ipp32f im[4]= {0.0, 0.0, 1.0, 1.0};
    Ipp32f pDst[4];

    ippsPhase_32f(re,im,pDst, 4); 
} 

Result:
pDst -> {0.0, 0.0, 1.6 0.8)

PowerSpectr
Computes the power spectrum of a complex vector.

Syntax
IppStatus ippsPowerSpectr_64fc(const Ipp64fc* pSrc, Ipp64f* pDst, int len        );
IppStatus ippsPowerSpectr_32fc(const Ipp32fc* pSrc, Ipp32f* pDst, int len        );
IppStatus ippsPowerSpectr_16sc_Sfs(const Ipp16sc* pSrc, Ipp16s* pDst, int len, int
scaleFactor );
IppStatus ippsPowerSpectr_64f(const Ipp64f* pSrcRe, const Ipp64f* pSrcIm, Ipp64f* pDst,
int len);
IppStatus ippsPowerSpectr_32f(const Ipp32f* pSrcRe, const Ipp32f* pSrcIm, Ipp32f* pDst,
int len);

   144
---------------------Page 145---------------------

                                                                           Essential Functions  5 

IppStatus ippsPowerSpectr_16s_Sfs(const Ipp16s* pSrcRe, const Ipp16s* pSrcIm, Ipp16s*
pDst, int len, int scaleFactor   );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsPowerSpectr_16s32f(const Ipp16s* pSrcRe, const Ipp16s* pSrcIm, Ipp32f*
pDst, int len );
IppStatus ippsPowerSpectr_16sc32f(const Ipp16sc* pSrc, Ipp32f* pDst, int len        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

pSrcRe                       Pointer to the source vector which stores the real components.

pSrcIm                       Pointer to the source vector which stores the imaginary
                             components.
pDst                         Pointer to the vector which stores the spectrum components of the
                             elements.
len                          Number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
Functions ippsPowerSpectr_16s32f  and ippsPowerSpectr_16sc32f   are deprecated. These functions are
obsolete and will be removed in a future release. Use the following link for details: http://software.intel.com/
sites/products/ipp-deprecated-features-feedback/.
This function returns the power spectrum of the complex input vector pSrc, or the complex input vector
whose real and imaginary components are specified in the vectors pSrcRe and pSrcIm, respectively, and
stores the results in the vector pDst. The power spectrum elements are squares of the magnitudes of the
complex input vector elements:
pDst[n] = ( pSrc[n].re)  2 + (pSrc[n].im)  2 , or pDst[n] = ( pSrcRe[n])2 + (pSrcIm[n])  2 .
To compute magnitudes, use the function Magnitude.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when at least one of the specified pointers is
                                  NULL.
ippStsSizeErr                     Indicates an error when len is less than or equal to 0.

Real
Returns the real part of a complex vector in a second
vector.

                                                                                           145
---------------------Page 146---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Syntax
IppStatus ippsReal_16sc(const Ipp16sc* pSrc, Ipp16s* pDstRe, int len      );
IppStatus ippsReal_32fc(const Ipp32fc* pSrc, Ipp32f* pDstRe, int len      );
IppStatus ippsReal_64fc(const Ipp64fc* pSrc, Ipp64f* pDstRe, int len      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the complex source vector.

pDstRe                      Pointer to the destination vector with real parts.

len                         Number of elements in the vector.

Description
This function returns the real part of the complex vector pSrc in the vector pDstRe.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pDstRe or pSrc pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to zero.

Example
The example below shows how to call the function ippsReal_32fc.
void func_real() 
{
    Ipp32fc pSrc[5] = {{1.2, 3.2}, {0.0, 0.3}, {4.3, 6.7}, {4.2, 0.0},{1.2, 1.2}};
    Ipp32f pDstRe[5];

    ippsReal_32fc(pSrc,pDstRe,5); 
} 

Result:
pDestRe ->(1.2, 0.0, 4.3, 4.2, 1.2)

Imag
Returns the imaginary part of a complex vector in a
second vector.

Syntax
IppStatus ippsImag_16sc(const Ipp16sc* pSrc, Ipp16s* pDstIm, int len      );
IppStatus ippsImag_32fc(const Ipp32fc* pSrc, Ipp32f* pDstIm, int len      );
IppStatus ippsImag_64fc(const Ipp64fc* pSrc, Ipp64f* pDstIm, int len      );

   146
---------------------Page 147---------------------

                                                                         Essential Functions  5 

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the complex source vector.

pDstIm                      Pointer to the destination vector with imaginary parts.

len                         Number of elements in the vector.

Description
This function returns the imaginary part of a complex vector pSrc in the vector pDstIm.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pDstIm or pSrc pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to zero.

Example
The example below shows how to call the function ippsImag_32fc.
void func_imag() 
{
    Ipp32fc pSrc[5] = {{1.2, 3.2}, {0.0, 0.3}, {4.3, 6.7}, {4.2, 0.0}, {1.2, 1.2}};
    Ipp32f pDstIm[5];

    ippsImag_32fc(pSrc, pDstIm, 5); 
}
Result:
pDstIm ->(3.2, 0.3, 6.7, 0.0, 1.2)

RealToCplx
Returns a complex vector constructed from the real
and imaginary parts of two real vectors.

Syntax
IppStatus ippsRealToCplx_16s(const Ipp16s* pSrcRe, const Ipp16s* pSrcIm, Ipp16sc* pDst,
int len);
IppStatus ippsRealToCplx_32f(const Ipp32f* pSrcRe, const Ipp32f* pSrcIm, Ipp32fc* pDst,
int len);
IppStatus ippsRealToCplx_64f(const Ipp64f* pSrcRe, const Ipp64f* pSrcIm, Ipp64fc* pDst,
int len);

Include Files
ipps.h

                                                                                         147
---------------------Page 148---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcRe                       Pointer to the vector with real parts of complex elements.

pSrcIm                       Pointer to the vector with imaginary parts of complex elements.

pDst                         Pointer to the destination vector.

len                          Number of elements in the vector.

Description
This function returns a complex vector pDst constructed from the real and imaginary parts of the input
vectors pSrcRe and pSrcIm.
If pSrcRe is NULL, the real component of the vector is set to zero.
If pSrcIm is NULL, the imaginary component of the vector is set to zero.
Note that the pointers cannot be both NULL.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pDst  pointer is NULLNULL. The
                                  pointer pSrcRe  or pSrcIm can be NULL.
ippStsSizeErr                     Indicates an error when  len is less than or equal to zero.

Example
The example below shows how to call the function ippsRealToCplx_32f.
void func_realtocplx() 
{
    Ipp32f pSrcRe[6] = {12.2, -2.1, 4.3, 1.1, 2.2, 0.0};
    Ipp32f pSrcIm[6] = {-9.3, 2.3, -5.2, 0.0, -1.0, -1.2};
    Ipp32fc pDst[6];

    ippsRealToCplx_32f(pSrcRe, pSrcIm, pDst, 6); 
} 

Result:
pDst ->{(12.2, -9.3), (-2.1, 2.3), (4.3, -5.2), (1.1, 0.0), (2.2, -1.0), (0.0, 10.0}

CplxToReal
Returns the real and imaginary parts of a complex
vector in two respective vectors.

Syntax
IppStatus ippsCplxToReal_16sc(const Ipp16sc* pSrc, Ipp16s* pDstRe, Ipp16s* pDstIm, int
len);
IppStatus ippsCplxToReal_32fc(const Ipp32fc* pSrc, Ipp32f* pDstRe, Ipp32f* pDstIm, int
len);

   148
---------------------Page 149---------------------

                                                                         Essential Functions  5 

IppStatus ippsCplxToReal_64fc(const Ipp64fc* pSrc, Ipp64f* pDstRe, Ipp64f* pDstIm, int
len);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the complex vector pSrc.

pDstRe                      Pointer to the output vector with real parts.

pDstIm                      Pointer to the output vector with imaginary parts.

len                         Number of elements in the vector.

Description
This function returns the real and imaginary parts of a complex vector pSrc in two vectors pDstRe and
pDstIm.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the data vector pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

DemodulateFM
DEPRECATED. Converts frequency modulated signal
into the initial demodulated form.

Syntax
IppStatus ippsDemodulateFM_CToR_16s(const Ipp16s* pSrcRe, const Ipp16s* pSrcIm, Ipp16s*
pDst, int len, Ipp16sc* pDlyPoint  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcRe                      Pointer to the source vector with real parts of complex elements.

pSrcIm                      Pointer to the source vector with imaginary parts of complex
                            elements.
pDst                        Pointer to the destination vector.

                                                                                         149
---------------------Page 150---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

len                          Number of elements in the vector.

pDlyPoint                    Pointer to the value required for operation.

Description
The function ippsDemodulateFM_CToR is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details:http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function converts the frequency modulated signal to the initial demodulated form. The modulated signal
is presented as a complex vector, pSrcRe and pSrcIm. The demodulated signal is presented as the real
vector pDst.
On input the pointer pDlyPoint points to the value that corresponds to the demodulated value of the
element preceding the first element in the source vector. When operation is completed the pointer points to
the demodulated value of the last element.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the one of the specified pointer is
                                 NULL .
ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Threshold
Performs the threshold operation on the elements of a
vector by limiting the element values by specified
value.

Syntax
IppStatus ippsThreshold_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, Ipp16s level,
IppCmpOp relOp );
IppStatus ippsThreshold_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f level,
IppCmpOp relOp );
IppStatus ippsThreshold_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f level,
IppCmpOp relOp );
IppStatus ippsThreshold_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, Ipp32f level,
IppCmpOp relOp );
IppStatus ippsThreshold_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, Ipp64f level,
IppCmpOp relOp );
IppStatus ippsThreshold_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, Ipp16s level,
IppCmpOp relOp );
IppStatus ippsThreshold_16s_I(Ipp16s* pSrcDst, int len, Ipp16s level,IppCmpOp relOp        );
IppStatus ippsThreshold_32f_I(Ipp32f* pSrcDst, int len, Ipp32f level, IppCmpOp relOp        );
IppStatus ippsThreshold_64f_I(Ipp64f* pSrcDst, int len, Ipp64f level, IppCmpOp relOp        );
IppStatus ippsThreshold_32fc_I(Ipp32fc* pSrcDst, int len, Ipp32f level, IppCmpOp
relOp);
IppStatus ippsThreshold_64fc_I(Ipp64fc* pSrcDst, int len, Ipp64f level, IppCmpOp
relOp);

   150
---------------------Page 151---------------------

                                                                             Essential Functions  5 

IppStatus ippsThreshold_16sc_I(Ipp16sc* pSrcDst, int len, Ipp16s level, IppCmpOp
relOp);

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.

pSrcDst                       Pointer to the source and destination vector for the in-place
                              operation.
len                           Number of elements in the vector.

level                         Value used to limit each element of pSrc  or pSrcDst.This parameter
                              must always be real. For complex versions, it must be positive and
                              represent magnitude.
relOp                         Values of this argument specify which relational operator to use and
                              whether level  is an upper or lower bound for the input. The relOp
                              must have one of the following values:
                              ippCmpLess  Specifies the “less than” operator and level is a lower
                              bound.
                              ippCmpGreater  Specifies the “greater than” operator and level  is an
                              upper bound.

Description
This function performs the threshold operation on the vector pSrc by limiting each element by the threshold
value level. Function operation is similar to that of the functions ippsThreshold_LT, ippsThreshold_GT
but its interface contains the relOp parameter that specifies the type of the comparison operation to
perform.
The in-place flavors of ippsThreshold perform the threshold operation on the vector pSrcDst by limiting
each element by the threshold value level.
The relOp argument specifies which relational operator to use: when its value is ippCmpGreater - “greater
than”, when ippCmpLess  - “less than”, and determines whether level is an upper or lower bound for the
input, respectively.
The formula for ippsThreshold called with the relOp = ippCmpLess is:
 

 
The formula for ippsThreshold called with the relOp = ippCmpGreater is:
 

                                                                                             151
---------------------Page 152---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

 
For complex versions of the function ippsThreshold, the level argument is always real. The formula for
complex ippsThreshold   called with the relOp = ippCmpLess is:
 

 
The formula for complex ippsThreshold  called with the relOp = ippCmpGreater  is:
 

 

Application Notes
For all complex versions, level must be positive and represents a magnitude. The magnitude of the input is
limited, but the phase remains unchanged. Zero-valued input is assumed to have zero phase.
A special rule is applied to the integer complex versions of the function ippsThreshold. In general, the
resulting point coordinates at the complex plane are not integer. The function rounds them off to integer in
such a way that the threshold operation is not performed. Thus, for the “less than” operation (with the
ippCmpLess  flag) the coordinates are rounded to the infinity (+Inf for positive coordinates, and -Inf for
negative), and for the “greater than” operation (with the ippCmpGreater flag) the coordinates are rounded
to zero.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the   pSrc, pDst, or pSrcDst  pointer is
                                   NULL .
ippStsSizeErr                      Indicates an error when   len is less than or equal to 0.

ippStsBadArgErr                    Indicates an error when   relOp has an invalid value.

ippStsThreshNegLevelErr            Indicates an error when   level for the complex version is
                                   negative (see appendix A Appendix A Handling of Special Cases
                                   for more information).

Example
The code example below shows how to use the “complex” function ippsThreshold_16sc_I  .
IppStatus cmplx_threshold(void){
     Ipp16sc x[4] = {{2,3},{3,3}, {4,3}, {4,2}};
     /// level is near to the point {2,3} = 3.6
     /// the point {2,3} is to be replaced
     /// the computed coordinates are {2.2188,3.3282}
     /// the point used is {3,4};
     /// notice that it is the point with the phase,

   152
---------------------Page 153---------------------

                                                                      Essential Functions  5 

     /// nearest to the source
     IppStatus st = ippsThreshold_16sc_I(x, 4, 4, ippCmpLess);
     printf_16sc("complex threshold result =", x, 4, st);
     return st; 
}

Output:
    complex threshold result = {3, 4} {3, 3} {4, 3} {4, 2}

The code example below shows how to use the “real” function ippsTreshold_16s_I.
IppStatus threshold( void) {
     Ipp16s x[4] = { -1, 0, 2, 3 };
     IppStatus st = ippsThreshold_16s_I(x, 4, 2, ippCmpLess );
     printf_16s("threshold result =", x, 4, st );
     return st; 
}

Output:
    threshold result = 2 2 2 3

Threshold_LT, Threshold_GT
Performs the threshold operation on the elements of a
vector by limiting the element values by the specified
value.

Syntax
IppStatus ippsThreshold_LT_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, Ipp16s
level);
IppStatus ippsThreshold_LT_32s(const Ipp32s* pSrc, Ipp32s* pDst, int len, Ipp32s
level);
IppStatus ippsThreshold_LT_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f
level);
IppStatus ippsThreshold_LT_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f
level);
IppStatus ippsThreshold_LT_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, Ipp32f
level);
IppStatus ippsThreshold_LT_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, Ipp64f
level);
IppStatus ippsThreshold_LT_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, Ipp16s
level);
IppStatus ippsThreshold_GT_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, Ipp16s
level);
IppStatus ippsThreshold_GT_32s(const Ipp32s* pSrc, Ipp32s* pDst, int len, Ipp32s
level);
IppStatus ippsThreshold_GT_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f
level);
IppStatus ippsThreshold_GT_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f
level);
IppStatus ippsThreshold_GT_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, Ipp32f
level);

                                                                                     153
---------------------Page 154---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsThreshold_GT_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, Ipp64f
level);
IppStatus ippsThreshold_GT_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, Ipp16s
level);
IppStatus ippsThreshold_GT_16s_I(Ipp16s* pSrcDst, int len, Ipp16s level    );
IppStatus ippsThreshold_GT_32s_I(Ipp32s* pSrcDst, int len, Ipp32s level    );
IppStatus ippsThreshold_GT_32f_I(Ipp32f* pSrcDst, int len, Ipp32f level    );
IppStatus ippsThreshold_GT_64f_I(Ipp64f* pSrcDst, int len, Ipp64f level    );
IppStatus ippsThreshold_GT_32fc_I(Ipp32fc* pSrcDst, int len, Ipp32f level     );
IppStatus ippsThreshold_GT_64fc_I(Ipp64fc* pSrcDst, int len, Ipp64f level     );
IppStatus ippsThreshold_GT_16sc_I(Ipp16sc* pSrcDst, int len, Ipp16s level     );
IppStatus ippsThreshold_LT_16s_I(Ipp16s* pSrcDst, int len, Ipp16s level    );
IppStatus ippsThreshold_LT_32s_I(Ipp32s* pSrcDst, int len, Ipp32s level    );
IppStatus ippsThreshold_LT_32f_I(Ipp32f* pSrcDst, int len, Ipp32f level    );
IppStatus ippsThreshold_LT_64f_I(Ipp64f* pSrcDst, int len, Ipp64f level    );
IppStatus ippsThreshold_LT_32fc_I(Ipp32fc* pSrcDst, int len, Ipp32f level     );
IppStatus ippsThreshold_LT_64fc_I(Ipp64fc* pSrcDst, int len, Ipp64f level     );
IppStatus ippsThreshold_LT_16sc_I(Ipp16sc* pSrcDst, int len, Ipp16s level     );

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.

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

level                       Value used to limit each element of pSrc or pSrcDst.This argument
                            must always be real. For complex versions, it must be positive and
                            represent magnitude.

Description
They implement thresholding of the vector pSrc by limiting each element by the threshold value level.
These functions perform the similar operation to the ippsThreshold function but are designed for the fixed
type of the compare operation to use: ippsThreshold_LT is for the "less than" comparison, while
ippsThreshold_GT  is for the "greater than" comparison.
The in-place flavors perform the threshold operation on the vector pSrcDst by limiting each element by the
threshold value level.

   154
---------------------Page 155---------------------

                                                                                Essential Functions  5  

ippsThreshold_LT   . The ippsThreshold_LT   function performs the operation “less than”, and level is a
lower bound for the input. The formula for ippsThreshold_LT is the following:
 

 
For complex versions of the function ippsThreshold_LT , the parameter level is always real.
The formula for complex ippsThreshold_LT   is:
 

 

ippsThreshold_GT   . The function ippsThreshold_GT  performs the operation “greater than” and level is
an upper bound for the input.
The formula for ippsThreshold_GT   is the following:
 

 
For complex versions of the function ippsThreshold_GT , the parameter level is always real.
The formula for complex ippsThreshold_GT   is:

 

 

Application Notes
For all complex versions, level must be positive and represents a magnitude. The magnitude of the input is
limited, but the phase remains unchanged. Zero-valued input is assumed to have zero phase.
A special rule is applied to the integer complex versions of the threshold functions. In general, the resulting
point coordinates at the complex plane are not integer. The function rounds them off to integer in such a way
that the threshold operation is not performed. Thus, for the “less than” operation (the ippsThreshold_LT
function) the coordinates are rounded to the infinity (+Inf for positive coordinates, and -Inf for negative),
and for the “greater than” operation (the ippsThreshold_GT function) the coordinates are rounded to 0.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when the   pSrc , pDst, or pSrcDst  pointer is
                                    NULL .
ippStsSizeErr                       Indicates an error when   len  is less than or equal to 0

                                                                                                 155
---------------------Page 156---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsThreshNegLevelErr        Indicates an error when level for the complex version is
                               negative (see appendix A Appendix A Handling of Special Cases
                               for more information).

Threshold_LTAbs, Threshold_GTAbs
Performs the threshold operation on the absolute
values of elements of a vector.

Syntax
IppStatus ippsThreshold_LTAbs_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, Ipp16s
level);
IppStatus ippsThreshold_LTAbs_32s(const Ipp32s* pSrc, Ipp32s* pDst, int len, Ipp32s
level);
IppStatus ippsThreshold_LTAbs_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f
level);
IppStatus ippsThreshold_LTAbs_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f
level);

IppStatus ippsThreshold_GTAbs_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, Ipp16s
level);
IppStatus ippsThreshold_GTAbs_32s(const Ipp32s* pSrc, Ipp32s* pDst, int len, Ipp32s
level);
IppStatus ippsThreshold_GTAbs_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f
level);
IppStatus ippsThreshold_GTAbs_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f
level);
IppStatus ippsThreshold_GTAbs_16s_I(Ipp16s* pSrcDst, int len, Ipp16s level  );
IppStatus ippsThreshold_GTAbs_32s_I(Ipp32s* pSrcDst, int len, Ipp32s level  );
IppStatus ippsThreshold_GTAbs_32f_I(Ipp32f* pSrcDst, int len, Ipp32f level  );
IppStatus ippsThreshold_GTAbs_64f_I(Ipp64f* pSrcDst, int len, Ipp64f level  );
IppStatus ippsThreshold_LTAbs_16s_I(Ipp16s* pSrcDst, int len, Ipp16s level  );
IppStatus ippsThreshold_LTAbs_32s_I(Ipp32s* pSrcDst, int len, Ipp32s level  );
IppStatus ippsThreshold_LTAbs_32f_I(Ipp32f* pSrcDst, int len, Ipp32f level  );
IppStatus ippsThreshold_LTAbs_64f_I(Ipp64f* pSrcDst, int len, Ipp64f level  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                       Pointer to the source vector.

  156
---------------------Page 157---------------------

                                                                             Essential Functions  5 

pDst                          Pointer to the destination vector.

pSrcDst                       Pointer to the source and destination vector for the in-place
                              operation.
len                           Number of elements in the vector.

level                         Value used to limit each element of source vector. This argument
                              can not be negative.

Description
These functions implement thresholding of the vector pSrc by limiting absolute value of each element by the
threshold value level. These functions perform the compare operation of the fixed type:
ippsThreshold_LTAbs   is for the "less than" comparison, while ippsThreshold_GTAbs is for the "greater
than" comparison. Elements of the result vector pDst have the same sign that the source elements.
The in-place flavors perform the threshold operation on the vector pSrcDst.
ippsThreshold_LTAbs  . The ippsThreshold_LTAbs  function performs the operation “less than”, and level
is a lower bound for the input. The formula for ippsThreshold_LTAbs is the following:
 

 
ippsThreshold_GTAbs  . The function ippsThreshold_GTAbs  performs the operation “greater than” and
level is an upper bound for the input. The formula for ippsThreshold_GTAbs is the following:
 

 

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error if pSrc, pDst, or pSrcDst pointer is NULL.

ippStsSizeErr                      Indicates an error if len is less than or equal to zero.

ippStsThreshNegLevelErr            Indicates an error if level is negative.

Example
The example below shows how to use the function ippsThreshold_LTAbs_64f_I  .
IppStatus thresholdLTAbs( void ) {
    Ipp64f      vec[7] = { -4.01, -4.0, -3.9, 0.0, 2.5, 4.0, 4.5 };
    Ipp64f      level = 4.0;
    IppStatus   st = ippsThreshold_LTAbs_64f_I( vec, 7, level );
    printf("threshold abs   =   %f  %f  %f  %f\n",
        vec[0],vec[1],vec[2],vec[3]);
    printf("                     %f   %f   %f\n",
        vec[4],vec[5],vec[6]);
    return st; 
}

                                                                                             157
---------------------Page 158---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Output:
threshold abs = -4.010000 -4.000000 -4.000000 4.000000 
                          4.000000   4.000000   4.500000

Threshold_LTVal, Threshold_GTVal, Threshold_LTValGTVal
Performs the threshold operation on the elements of a
vector by limiting the element values by the specified
value.

Syntax
IppStatus ippsThreshold_LTVal_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, Ipp16s
level, Ipp16s value);
IppStatus ippsThreshold_LTVal_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f
level, Ipp32f value);
IppStatus ippsThreshold_LTVal_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f
level, Ipp64f value);
IppStatus ippsThreshold_LTVal_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, Ipp16s
level, Ipp16sc value);
IppStatus ippsThreshold_LTVal_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, Ipp32f
level, Ipp32fc value);
IppStatus ippsThreshold_LTVal_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, Ipp64f
level, Ipp64fc value);
IppStatus ippsThreshold_GTVal_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, Ipp16s
level, Ipp16s value);
IppStatus ippsThreshold_GTVal_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f
level, Ipp32f value);
IppStatus ippsThreshold_GTVal_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f
level, Ipp64f value);
IppStatus ippsThreshold_GTVal_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, Ipp16s
level, Ipp16sc value);
IppStatus ippsThreshold_GTVal_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, Ipp32f
level, Ipp32fc value);
IppStatus ippsThreshold_GTVal_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, Ipp64f
level, Ipp64fc value);
IppStatus ippsThreshold_LTValGTVal_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len,
Ipp16s levelLT, Ipp16s valueLT, Ipp16s levelGT, Ipp16s valueGT );
IppStatus ippsThreshold_LTValGTVal_32s(const Ipp32s* pSrc, Ipp32s* pDst, int len,
Ipp32s levelLT, Ipp32s valueLT, Ipp32s levelGT, Ipp32s valueGT );
IppStatus ippsThreshold_LTValGTVal_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len,
Ipp32f levelLT, Ipp32f valueLT, Ipp32f levelGT, Ipp32f valueGT );
IppStatus ippsThreshold_LTValGTVal_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len,
Ipp64f levelLT, Ipp64f valueLT, Ipp64f levelGT, Ipp64f valueGT );
IppStatus ippsThreshold_LTVal_16s_I(Ipp16s* pSrcDst, int len, Ipp16s level, Ipp16s
value);
IppStatus ippsThreshold_LTVal_32f_I(Ipp32f* pSrcDst, int len, Ipp32f level, Ipp32f
value);

  158
---------------------Page 159---------------------

                                                                     Essential Functions  5 

IppStatus ippsThreshold_LTVal_64f_I(Ipp64f* pSrcDst, int len, Ipp64f level, Ipp64f
value);
IppStatus ippsThreshold_LTVal_16sc_I(Ipp16sc* pSrcDst, int len, Ipp16s level, Ipp16sc
value);
IppStatus ippsThreshold_LTVal_32fc_I(Ipp32fc* pSrcDst, int len, Ipp32f level, Ipp32fc
value);
IppStatus ippsThreshold_LTVal_64fc_I(Ipp64fc* pSrcDst, int len, Ipp64f level, Ipp64fc
value);
IppStatus ippsThreshold_GTVal_16s_I(Ipp16s* pSrcDst, int len, Ipp16s level, Ipp16s
value);
IppStatus ippsThreshold_GTVal_32f_I(Ipp32f* pSrcDst, int len, Ipp32f level, Ipp32f
value);
IppStatus ippsThreshold_GTVal_64f_I(Ipp64f* pSrcDst, int len, Ipp64f level, Ipp64f
value);
IppStatus ippsThreshold_GTVal_16sc_I(Ipp16sc* pSrcDst, int len, Ipp16s level, Ipp16sc
value);
IppStatus ippsThreshold_GTVal_32fc_I(Ipp32fc* pSrcDst, int len, Ipp32f level, Ipp32fc
value);
IppStatus ippsThreshold_GTVal_64fc_I(Ipp64fc* pSrcDst, int len, Ipp64f level, Ipp64fc
value);
IppStatus ippsThreshold_LTValGTVal_16s_I(Ipp16s* pSrcDst, int len, Ipp16s levelLT,
Ipp16s valueLT, Ipp16s levelGT, Ipp16s valueGT );
IppStatus ippsThreshold_LTValGTVal_32s_I(Ipp32s* pSrcDst, int len, Ipp32s levelLT,
Ipp32s valueLT, Ipp32s levelGT, Ipp32s valueGT );
IppStatus ippsThreshold_LTValGTVal_32f_I(Ipp32f* pSrcDst, int len, Ipp32f levelLT,
Ipp32f valueLT, Ipp32f levelGT, Ipp32f valueGT );
IppStatus ippsThreshold_LTValGTVal_64f_I(Ipp64f* pSrcDst, int len, Ipp64f levelLT,
Ipp64f valueLT, Ipp64f levelGT, Ipp64f valueGT );

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.

pSrcDst                    Pointer to the source and destination vector for the in-place
                           operation.
len                        Number of elements in the vector.

level                      Value used to limit each element of pSrc or pSrcDst.This argument
                           must always be real. For complex versions, it must be positive and
                           represent magnitude.

                                                                                   159
---------------------Page 160---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

levelLT                       Low bound used to limit each element of   pSrc  or pSrcDst  for the
                              ippsThreshold_LTValGTVal     function.
levelGT                       Upper bound used to limit each element of   pSrc  or pSrcDst  for the
                              ippsThreshold_LTValGTVal     function.
value                         Value to be assigned to vector elements which are “less than” or
                              “greater than” level .
valueLT                       Value to be assigned to vector elements which are less than   levelLT
                              for the ippsThreshold_LTValGTVal    function.
valueGT                       Value to be assigned to vector elements which are greater than
                              levelGT  for the ippsThreshold_LTValGTVal    function.

Description
These functions perform the threshold operation on the vector pSrc by limiting each element by the
threshold value.
The in-place flavors of the function perform the threshold operation on the vector pSrcDst by limiting each
element by the threshold value.
ippsThreshold_LTVal  . The function ippsThreshold_LTVal n performs the operation “less than” and level
is a lower bound for the input. The vector elements less than level are set to value.
The formula for ippsThreshold_LTVal  is:
 

 
For complex versions of the function ippsThreshold_LTVal, the parameter level is always real.
The formula for complex ippsThreshold_LTVal   is:
 

 
ippsThreshold_GTVal  . The function ippsThreshold_GTVal   performs the operation “greater than” and
level is an upper bound for the input. The vector elements greater than level are set to value.
The formula for ippsThreshold_GtVal  is:
 

 
For complex versions of the function ippsThreshold_GTVal, the parameter level is always real.
The formula for complex ippsThreshold_GTVal   is:
 

 

   160
---------------------Page 161---------------------

                                                                         Essential Functions  5 

ippsThreshold_LTValGTVal . The function ippsThreshold_LTValGTVal checks both the “less than” and
“greater than” conditions. The parameter levelLT is a lower bound and the parameter levelGT is an upper
bound for the input. The source vector elements less than levelLT are set to valueLT, and the source
vector elements greater than levelGT are set to valueGT. The value of levelLT must be less than or equal
to levelGT.
The formula for ippsThreshold_LTValGTVal is:
 

 
For all complex versions, level must be positive and represent a magnitude.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                 NULL.
ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

ippStsThresholdErr               Indicates an error when levelLT is greater than levelGT.

ippStsThreshNegLevelErr          Indicates an error when level for the complex version is
                                 negative (see appendix A “Handling of Special Cases” for more
                                 information).

Threshold_LTInv
Computes the inverse of vector elements after limiting
their magnitudes by the given lower bound.

Syntax
IppStatus ippsThreshold_LTInv_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, Ipp32f
level);
IppStatus ippsThreshold_LTInv_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f
level);
IppStatus ippsThreshold_LTInv_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, Ipp32f
level);
IppStatus ippsThreshold_LTInv_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, Ipp64f
level);
IppStatus ippsThreshold_LTInv_32f_I(Ipp32f* pSrcDst, int len, Ipp32f level      );
IppStatus ippsThreshold_LTInv_64f_I(Ipp64f* pSrcDst, int len, Ipp64f level      );
IppStatus ippsThreshold_LTInv_32fc_I(Ipp32fc* pSrcDst, int len, Ipp32f level      );
IppStatus ippsThreshold_LTInv_64fc_I(Ipp64fc* pSrcDst, int len, Ipp64f level      );

Include Files
ipps.h

                                                                                        161
---------------------Page 162---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

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.

pSrcDst                        Pointer to the source and destination vector for the in-place
                               operation.
len                            Number of elements in the vector.

level                          Value used to limit each element of  pSrc  or pSrcDst.This argument
                               must always be real and positive.

Description
This function computes the inverse of elements of the vector pSrc and stores the result in pDst. The
computation occurs after first limiting the magnitude of each element by the threshold value level.
The in-place flavors of ippsThreshold_LTInv compute the inverse of elements of the vector pSrcDst and
store the result in pSrcDst. The computation occurs after first limiting the magnitude of each element by the
threshold value level.
The threshold operation is performed to avoid division by zero. Since level represents a magnitude, it is
always real and must be positive. The formula for ippsThreshold_LTInv is the following:
 

 
If the function encounters zero-valued vector elements and level is also 0 (see appendix A Appendix A
Handling of Special Cases), the output value is set to Inf (infinity), but operation execution is not aborted:
 

 

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when the  pSrc , pDst, or pSrcDst  pointer is
                                    NULL.
ippStsSizeErr                       Indicates an error when  len  is less than or equal to zero.

ippStsThreshNegLevelErr             Indicates an error when  level  is negative.

   162
---------------------Page 163---------------------

                                                                        Essential Functions  5 

ippStsInvZero                   Indicates a warning when level and a vector element are
                                equal to zero. Operation execution is not aborted. The value of
                                the destination vector element is Inf.

Example
The example below shows how to use the function ippsThreshold_LTInv_32f_I.
IppStatus invThreshold(void) {
     Ipp32f x[4] = {-1, 0, 2, 3};
     IppStatus st = ippsThreshold_LTInv_32f_I(x, 4, 0);
     printf_32f("inv threshold =", x, 4, st);
     return st; 
}

Output:
    -- warning 4, INF result. Zero value met by invThreshold with zero level
    inv threshold = -1.000000 1.#INF00 0.500000 0.333333

CartToPolar
Converts the elements of a complex vector to polar
coordinate form.

Syntax
IppStatus ippsCartToPolar_32f(const Ipp32f* pSrcRe, const Ipp32f* pSrcIm, Ipp32f*
pDstMagn, Ipp32f* pDstPhase, int len  );
IppStatus ippsCartToPolar_64f(const Ipp64f* pSrcRe, const Ipp64f* pSrcIm, Ipp64f*
pDstMagn, Ipp64f* pDstPhase, int len  );
IppStatus ippsCartToPolar_32fc(const Ipp32fc* pSrc, Ipp32f* pDstMagn, Ipp32f*
pDstPhase, int len );
IppStatus ippsCartToPolar_64fc(const Ipp64fc* pSrc, Ipp64f* pDstMagn, Ipp64f*
pDstPhase, int len );
IppStatus ippsCartToPolar_16sc_Sfs(const Ipp16sc* pSrc, Ipp16s* pDstMagn, Ipp16s*
pDstPhase, int len, int magnScaleFactor, int phaseScaleFactor   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

pSrcRe                      Pointer to the source vector which stores the real components of
                            Cartesian X,Y pairs.
pSrcIm                      Pointer to the source vector which stores the imaginary components
                            of Cartesian X,Y pairs.
pDstMagn                    Pointer to the vector which stores the magnitude (radius)
                            component of the elements of the vector pSrc.

                                                                                       163
---------------------Page 164---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

pDstPhase                    Pointer to the vector which stores the phase (angle) component of
                             the elements of the vector pSrc in radians. Phase values are in the
                             range (-π, π].
len                          Number of elements in the vector.

magnScaleFactor              Integer scale factor for the magnitude component, refer to Integer
                             Scaling.
phaseScaleFactor             Integer scale factor for the phase component, refer to Integer
                             Scaling.

Description
This function converts the elements of a complex input vector pSrcor the complex input vector whose real
and imaginary components are specified in the vectors pSrcRe and pSrcIm, respectively, to polar coordinate
form, and stores the magnitude (radius) component of each element in the vector pDstMagn and the phase
(angle) component of each element in the vector pDstPhase.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when at least one of the specified pointers is
                                  NULL.
ippStsSizeErr                     Indicates an error when len is less than or equal to zero.

Example
The example below verifies that points are lying in the unit radius circle.
IppStatus cart2polar( void ) {
     Ipp64f cart[6], magn[4], phase[4];
     int n;
     for (n=0; n<6; ++n) cart[n] = sin(IPP_2PI * n / 8);
     IppStatus st = ippsCartToPolar_64f( cart, cart+2, magn, phase, 4 );
     printf_64f( "magn =", magn, 4, st );
     return st; 
}

Output:
    magn =  1.000000 1.000000 1.000000 1.000000

PolarToCart
Converts the polar form magnitude/phase pairs stored
in input vectors to Cartesian coordinate form.

Syntax
IppStatus ippsPolarToCart_32f(const Ipp32f* pSrcMagn, const Ipp32f* pSrcPhase, Ipp32f*
pDstRe, Ipp32f* pDstIm, int len   );
IppStatus ippsPolarToCart_64f(const Ipp64f* pSrcMagn, const Ipp64f* pSrcPhase, Ipp64f*
pDstRe, Ipp64f* pDstIm, int len   );
IppStatus ippsPolarToCart_32fc(const Ipp32f* pSrcMagn, const Ipp32f* pSrcPhase,
Ipp32fc* pDst, int len  );
IppStatus ippsPolarToCart_64fc(const Ipp64f* pSrcMagn, const Ipp64f* pSrcPhase,
Ipp64fc* pDst, int len  );

   164
---------------------Page 165---------------------

                                                                          Essential Functions  5 

IppStatus ippsPolarToCart_16sc_Sfs(const Ipp16s* pSrcMagn, const Ipp16s* pSrcPhase,
Ipp16sc* pDst, int len, int magnScaleFactor, int phaseScaleFactor      );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsPolarToCart_16sc(const Ipp16s* pSrcMagn, const Ipp16s* pSrcPhase, int
phaseFixedPoint, Ipp16sc* pDst, int len    );
IppStatus ippsPolarToCart_32sc(const Ipp32s* pSrcMagn, const Ipp32s* pSrcPhase, int
phaseFixedPoint, Ipp32sc* pDst, int len    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcMagn                     Pointer to the source vector which stores the magnitude (radius)
                             components of the elements in polar coordinate form.
pSrcPhase                    Pointer to the vector which stores the phase (angle) components of
                             the elements in polar coordinate form in radians.
pDst                         Pointer to the resulting vector which stores the complex pairs in
                             Cartesian coordinates (X + iY).
pDstRe                       Pointer to the resulting vector which stores the real components of
                             Cartesian X,Y pairs.
pDstIm                       Pointer to the resulting vector which stores the imaginary
                             components of Cartesian X,Y pairs.
len                          Number of elements in the vectors.

phaseFixedPoint              Specified the position of the decimal fixed point for the phase.

magnScaleFactor              Integer scale factor for the magnitude component, refer to Integer
                             Scaling.
phaseScaleFactor             Integer scale factor for the phase component, refer to Integer
                             Scaling.

Description
Functions ippsPolarToCart_16sc  and ippsPolarToCart_32sc   are deprecated. These functions are
obsolete and will be removed in a future release. Use the following link for details: http://software.intel.com/
sites/products/ipp-deprecated-features-feedback/.
This function converts the polar form magnitude/phase pairs stored in the input vectors pSrcMagn and
pSrcPhase into a complex vector and stores the results in the vector pDst, or stores the real components of
the result in the vector pDstRe and the imaginary components in the vector pDstIm.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                     Indicates an error when len is less than or equal to 0.

                                                                                          165
---------------------Page 166---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

MaxOrder
Computes the maximum order of a vector.

Syntax
IppStatus ippsMaxOrder_16s(const Ipp16s* pSrc, int len, int* pOrder     );
IppStatus ippsMaxOrder_32s(const Ipp32s* pSrc, int len, int* pOrder     );
IppStatus ippsMaxOrder_32f(const Ipp32f* pSrc, int len, int* pOrder     );
IppStatus ippsMaxOrder_64f(const Ipp64f* pSrc, int len, int* pOrder     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

len                         Number of elements in the vector.

pOrder                      Pointer to the result value.

Description
This function finds the maximum binary number in elements of the exponent vector pSrc, and stores the
result in pOrder.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc or pOrder pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

ippStsNanArg                     Indicates a warning when NaN is encountered in the input data
                                 vector.

Preemphasize
DEPRECATED. Computes preemphasis of a single
precision real signal in-place.

Syntax
IppStatus ippsPreemphasize_16s(Ipp16s* pSrcDst, int len, Ipp32f val     );
IppStatus ippsPreemphasize_32f(Ipp32f* pSrcDst, int len, Ipp32f val     );

Include Files
ipps.h

   166
---------------------Page 167---------------------

                                                                          Essential Functions  5 

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

val                         Multiplier factor used in the difference signal preemphasis equation.

Description
The function ippsPreemphasize is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function computes preemphasis of a real signal pSrcDst. The computation is performed according to the
difference signal preemphasis equation:
y(n) = x(n) - val * x(n - 1)  ,
where y(n) is the preemphasized output, x(n) is the input, and val is the multiplier factor.
Note that usually val = 0.95 for speech signals.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrcDst pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Flip
Reverses the order of elements in a vector.

Syntax
IppStatus ippsFlip_8u(const Ipp8u* pSrc, Ipp8u* pDst, int len     );
IppStatus ippsFlip_16u(const Ipp16u* pSrc, Ipp16u* pDst, int len     );
IppStatus ippsFlip_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len     );
IppStatus ippsFlip_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len     );
IppStatus ippsFlip_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len      );
IppStatus ippsFlip_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len      );
IppStatus ippsFlip_16u_I(Ipp16u* pSrcDst, int len    );
IppStatus ippsFlip_8u_I(Ipp8u* pSrcDst, int len    );
IppStatus ippsFlip_32f_I(Ipp32f* pSrcDst, int len    );
IppStatus ippsFlip_64f_I(Ipp64f* pSrcDst, int len    );
IppStatus ippsFlip_32fc_I(Ipp32fc* pSrcDst, int len    );
IppStatus ippsFlip_64fc_I(Ipp64fc* pSrcDst, int len    );

                                                                                         167
---------------------Page 168---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

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.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function stores the elements of a source vector pSrc to a destination vector pDst in reverse order
according to the following formula:
pDst[n] = pSrc[len- n-1], n = 0 .. len-1

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when at least one of the specified pointers is
                                  NULL.
ippStsSizeErr                     Indicates an error when len  is less than or equal to 0.

FindNearestOne
Finds an element of the table which is closest to the
specified value.

Syntax
IppStatus ippsFindNearestOne_16u(Ipp16u inpVal, Ipp16u* pOutVal, int* pOutIndex, const
Ipp16u *pTable, int tblLen   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

inpVal                       Reference value.

pOutVal                      Pointer to the output value.

pOutIndx                     Pointer to the output index.

   168
---------------------Page 169---------------------

                                                                             Essential Functions  5 

pTable                        Pointer to the table for searching.

tblLen                        Number of elements in the table.

Description
This function searches through the table pTable for an element which is closest to the specified reference
value inpVal. The resulting element and its index are stored in pOutVal and pOutIndex, respectively. The
table elements must satisfy the condition pTable[n] ≤ pTable[n+1]. The function uses the following
distance criterion for determining the table closest element closest: min(|inpVal -pTable[n]|).

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when at least one of the specified pointers is
                                   NULL.
ippStsSizeErr                      Indicates an error when  tblLen  is less than or equal to 0.

FindNearest
Finds table elements that are closest to the elements
of the specified vector.

Syntax
IppStatus ippsFindNearest_16u(const Ipp16u* pVals, Ipp16u* pOutVals, int* pOutIndexes,
int len, const Ipp16u *pTable, int tblLen     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pVals                         Pointer to the vector containing reference values.

pOutVals                      Pointer to the output vector.

pOutIndexes                   Pointer to the array that stores output indexes.

len                           Number of elements in the input vector.

pTable                        Pointer to the table for searching.

tblLen                        Number of elements in the table.

Description
This function searches through the table pTable for elements which are closest to the reference elements of
the input vector pVals. The resulting elements and their indexes are stored in pOutVals and pOutIndexes,
respectively. The table elements must satisfy the condition pTable[n] ≤ pTable[n+1]. The function uses
the following distance criterion for determining the table element closest to pVals[k] : min(|pVals[k] -
pTable[n]|) .

                                                                                             169
---------------------Page 170---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when at least one of the specified pointers is
                                  NULL.
ippStsSizeErr                     Indicates an error when tblLen  or len is less than or equal to
                                  zero.

Example
The example below shows how to use the function ippsFindNearest.
Ipp16u pVals[] = { 12, 6, 78 }; 
Ipp16u pTable[] = { 1, 3, 5, 7, 18, 24, 35, 48 }; 
Ipp16u pOutVals[3]; 
int pOutIndexes[3];

ippsFindNearest_16u (pVals, pOutVals, pOutIndexes, 3, pTable, 8 );
Result:
pOutVals = { 7, 5, 48 } 
pOutIndexes = { 3, 2, 7 }

Viterbi Decoder Functions

This section describes the functions that perform operations of Viterbi decoding in the V34 receiver. The
encoding is performed in accordance with the algorithm that is described in the section 9.6.3 of the ITU-T
Recommendation V.34 (see [ITUV34]).

GetVarPointDV
DEPRECATED. Fills the array with the information
about points that are closest to the received point.

Syntax
IppStatus ippsGetVarPointDV_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, Ipp16sc*
pVariantPoint, const Ipp8u* pLabel, int state     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the reference point in format 9:7

pDst                         Pointer to the closest to the reference point left and bottom complex
                             point in format 9:7
pVariantPoint                Pointer to the array where the point information is stored

pLabel                       Pointer to the table that stores the labels.

   170
---------------------Page 171---------------------

                                                                              Essential Functions  5 

state                         Number of states of a convolution coder.

Description
The function ippsGetVarPointDV  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function fills the specified array pVariantPoint with the information about 2D complex points that are
closest to the reference point pSrc. This information includes the corresponding labels from the offset table
and calculated errors. The number of possible states may be 16, 32, and 64. The number of points in the
array depends on the number of states: if state = 16 , then 4 points will be referenced in the array, if
state =32 or 64, then 8 points will be referenced.

Return Values

ippStsNoErr                        Indicates no error.

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

CalcStatesDV
DEPRECATED. Calculates the states of the Viterbi
decoder.

Syntax
IppStatus ippsCalcStatesDV_16sc(const Ipp16u* pathError, const Ipp8u* pNextState,
Ipp16u* pBranchError, const Ipp16s* pCurrentSubsetPoint, Ipp16s* pPathTable, int state,
int presentIndex  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pPathError                    Pointer to the table of path error metrics.

pNextState                    Pointer to the next state table.

pBranchError                  Pointer to the branch error table.

pCurrentSubsetPoint           Pointer to the current 4D subset.

pPathTable                    Pointer to the Viterbi path table.

state                         Number of states of a convolutional encoder.

presentIndex                  Start index in Viterbi path table.

Description
The function ippsCalcStatesDV  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details:http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.

                                                                                              171
---------------------Page 172---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

This function computes the possible states of the Viterbi decoder and fills the table of the accumulated errors
pPathError  and the working Viterbi path table pPathTable.

Return Values

ippStsNoErr                       Indicates no error.

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

BuildSymblTableDV4D
DEPRECATED. Fills the array with the information
about possible 4D symbols.

Syntax
IppStatus ippsBuildSymblTableDV4D_16sc(const Ipp16sc* pVariantPoint, Ipp16sc*
pCurrentSubsetPoint, int state, int bitInversion     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pVariantPoint                Pointer to the array of possible 2D points.

pCurrentSubsetPoint          Pointer to the array with information about possible 4D symbols.

state                        Number of states of a convolutional encoder.

bitInversion                 Bit inversion.

Description
The function ippsBuildSymblTableDV4D  is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details:http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function fills the array pCurrentSubsetPoint with information about possible 4D symbols.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

UpdatePathMetricsDV
DEPRECATED. Searches for the state with the
minimum path metric.

Syntax
IppStatus ippsUpdatePathMetricsDV_16u(Ipp16u* pBranchError, Ipp16u* pMinPathError,
Ipp8u* pMinSost, Ipp16u* pPathError, int state     );

   172
---------------------Page 173---------------------

                                                                              Essential Functions  5  

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pBranchError                  Pointer to the branch error table.

pMinPathError                 Pointer to the current minimum path error metric.

pMinSost                      Pointer to the number of states with the minimum metric.

pPathError                    Pointer to the table of accumulated path errors.

state                         Number of states of a convolutional encoder.

Description
The function ippsBuildSymblTableDV4D   is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function searches for the state with the minimum path error metric and stores its number in the
pMinSost . For all states, the minimum metric is subtracted from the path metric. The branch errors for all
states are set to be infinitely large as is required for the next step of the Viterbi decoding.

Return Values

ippStsNoErr                        Indicates no error.

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

Windowing Functions
This chapter describes several of the windowing functions commonly used in signal processing. A window is a
mathematical function by which a signal is multiplied to improve the characteristics of some subsequent
analysis. Windows are commonly used in FFT-based spectral analysis.

Understanding Window Functions
The Intel     provides the following functions to generate window samples:
• Bartlett windowing function
• Blackman family of windowing functions
• Hamming windowing function
• WinHann windowing function
• WinKaiser windowing function
These functions generate the window samples and multiply them into an existing signal. To obtain the
window samples themselves, initialize the vector argument to the unity vector before calling the window
function.

                                                                                               173
---------------------Page 174---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

If you want to multiply different frames of a signal by the same window multiple times, it is better to first
calculate the window by calling one of the windowing functions (ippsWinHann, for example) on a vector with
all elements set to 1.0. Then use one of the vector multiplication functions (ippsMul, for example) to
multiply the window into the signal each time a new set of input samples is available. This avoids repeatedly
calculating the window samples. This is illustrated in the following code example.

Example
void multiFrameWin( void ) {
     Ipp32f win[LEN], x[LEN], X[LEN];
     IppsFFTSpec_R_32f* ctx;
     ippsSet_32f( 1, win, LEN );
     ippsWinHann_32f_I( win, LEN );
     /// ... initialize FFT context
     while(1 ){
        /// ... get x signal
        ///
        ippsMul_32f_I( win, x, LEN );
        ippsFFTFwd_RToPack_32f( x, X, ctx, 0 );
     } 
}

For more information on windowing, see: [Jack89], section 7.3, Windows in Spectrum Analysis; [Jack89],
section 9.1, Window-Function Technique; and [Mit93], section 16-2, Fourier Analysis of Finite-Time Signals.
For more information on these references, see also the Bibliography at the end of this manual.

WinBartlett
Multiplies a vector by a Bartlett windowing function.

Syntax
IppStatus ippsWinBartlett_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len       );
IppStatus ippsWinBartlett_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len       );
IppStatus ippsWinBartlett_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len       );
IppStatus ippsWinBartlett_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len        );
IppStatus ippsWinBartlett_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len        );
IppStatus ippsWinBartlett_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len        );
IppStatus ippsWinBartlett_16s_I(Ipp16s* pSrcDst, int len      );
IppStatus ippsWinBartlett_32f_I(Ipp32f* pSrcDst, int len      );
IppStatus ippsWinBartlett_64f_I(Ipp64f* pSrcDst, int len      );
IppStatus ippsWinBartlett_16sc_I(Ipp16sc* pSrcDst, int len      );
IppStatus ippsWinBartlett_32fc_I(Ipp32fc* pSrcDst, int len      );
IppStatus ippsWinBartlett_64fc_I(Ipp64fc* pSrcDst, int len      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

   174
---------------------Page 175---------------------

                                                                            Essential Functions  5 

Parameters

pSrc                         Pointer to the source vector.

pDst                         Pointer to the destination vector.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
len                          Number of elements in the vector.

Description
This function multiplies the vector pSrc by the Bartlett (triangle) window, and stores the result in pDst.
The in-place flavors of ippsWinBartlett multiply the pSrcDst by the Bartlett (triangle) window and store
the result in pSrcDst.
The complex types multiply both the real and imaginary parts of the vector by the same window.
The Bartlett window is defined as follows:
 

 

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pSrc, pDst, orpSrcDst pointer is
                                  NULL .
ippStsSizeErr                     Indicates an error when  len is less than 3.

Example
The example below shows how to use the function ippsWinBartlett_32f_I.
void bartlett(void) {
      Ipp32f x[8];
      ippsSet_32f(1, x, 8);
      ippsWinBartlett_32f_I(x, 8);
      printf_32f(“bartlett (half) =”, x, 4, ippStsNoErr); 
}
Output:
    bartlett (half) =  0.000000 0.285714 0.571429 0.857143 
Matlab* Analog: 
    >> b = bartlett(8); b(1:4)'

WinBlackman
Multiplies a vector by a Blackman windowing function.

Syntax
IppStatus ippsWinBlackman_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, float alpha          );

                                                                                            175
---------------------Page 176---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsWinBlackman_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, float
alpha);
IppStatus ippsWinBlackman_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, float alpha);
IppStatus ippsWinBlackman_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, float
alpha);
IppStatus ippsWinBlackman_64f(Ipp64f* pSrc, Ipp64f* pDst, int len, double alpha);
IppStatus ippsWinBlackman_64fc(Ipp64fc* pSrc, Ipp64fc* pDst, int len, double alpha);
IppStatus ippsWinBlackmanStd_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len);
IppStatus ippsWinBlackmanStd_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len);
IppStatus ippsWinBlackmanStd_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len);
IppStatus ippsWinBlackmanStd_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len);
IppStatus ippsWinBlackmanStd_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len);
IppStatus ippsWinBlackmanStd_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len);
IppStatus ippsWinBlackmanOpt_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len);
IppStatus ippsWinBlackmanOpt_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len);
IppStatus ippsWinBlackmanOpt_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len);
IppStatus ippsWinBlackmanOpt_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len);
IppStatus ippsWinBlackmanOpt_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len);
IppStatus ippsWinBlackmanOpt_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len);
IppStatus ippsWinBlackman_16s_I(Ipp16s* pSrcDst, int len, float alpha);
IppStatus ippsWinBlackman_16sc_I(Ipp16sc* pSrcDst, int len, float alpha);
IppStatus ippsWinBlackman_32f_I(Ipp32f* pSrcDst, int len, float alpha);
IppStatus ippsWinBlackman_32fc_I(Ipp32fc* pSrcDst, int len, float alpha);
IppStatus ippsWinBlackman_64f_I(Ipp64f* pSrcDst, int len, double alpha);
IppStatus ippsWinBlackman_64fc_I(Ipp64fc* pSrcDst, int len, double alpha);
IppStatus ippsWinBlackmanOpt_16s_I(Ipp16s* pSrcDst, int len);
IppStatus ippsWinBlackmanOpt_16sc_I(Ipp16sc* pSrcDst, int len);
IppStatus ippsWinBlackmanOpt_32f_I(Ipp32f* pSrcDst, int len);
IppStatus ippsWinBlackmanOpt_32fc_I(Ipp32fc* pSrcDst, int len);
IppStatus ippsWinBlackmanOpt_64f_I(Ipp64f* pSrcDst, int len);
IppStatus ippsWinBlackmanOpt_64fc_I(Ipp64fc* pSrcDst, int len);
IppStatus ippsWinBlackmanStd_16s_I(Ipp16s* pSrcDst, int len);
IppStatus ippsWinBlackmanStd_16sc_I(Ipp16sc* pSrcDst, int len);
IppStatus ippsWinBlackmanStd_32f_I(Ipp32f* pSrcDst, int len);
IppStatus ippsWinBlackmanStd_32fc_I(Ipp32fc* pSrcDst, int len);
IppStatus ippsWinBlackmanStd_64f_I(Ipp64f* pSrcDst, int len);
IppStatus ippsWinBlackmanStd_64fc_I(Ipp64fc* pSrcDst, int len);

  176
---------------------Page 177---------------------

                                                                           Essential Functions  5 

THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsWinBlackmanQ15_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, int
alphaQ15);
IppStatus ippsWinBlackmanQ15_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, int
alphaQ15);
IppStatus ippsWinBlackmanQ15_16s_I(Ipp16s* pSrcDst, int len, int alphaQ15       );
IppStatus ippsWinBlackmanQ15_16s_ISfs(Ipp16s* pSrcDst, int len, int alphaQ15, int
scaleFactor );
IppStatus ippsWinBlackmanQ15_16sc_I(Ipp16sc* pSrcDst, int len, int alphaQ15        );

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.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
alpha                        Adjustable parameter associated with the Blackman windowing
                             equation.
alphaQ15                     Scaled version of alpha. The scaleFactor  value is 15.

len                          Number of elements in the vector

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
Functions ippsWinBlackmanQ15_16s  and ippsWinBlackmanQ15_16sc   are deprecated. These functions are
obsolete and will be removed in a future release. Use the following link for details: http://software.intel.com/
sites/products/ipp-deprecated-features-feedback/.
These functions multiply the vector pSrc by the Blackman window, and store the result in pDst.
The in-place flavors of ippsWinBlackman multiply the vector pSrcDst by the Blackman window, and store
the result in pSrcDst.
The complex types multiply both the real and imaginary parts of the vector by the same window. The
functions for the Blackman family of windows are defined below.
ippsWinBlackman . The function ippsWinBlackman allows the application to specify alpha. The Blackman
window is defined as follows:
 

 

                                                                                          177
---------------------Page 178---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippsWinBlackmanQ15 . The function ippsWinBlackmanQ15multiplies a vector by a Blackman window with
alphaQ15 scaled according to the factor 15.
ippsWinBlackmanStd . The standard Blackman window is provided by the function ippsWinBlackmanStd,
which simply multiplies a vector by a Blackman window with the standard value of alpha shown below:
alpha = -0.16
ippsWinBlackmanOpt . The function ippsWinBlackmanOpt provides a modified window that has a 30 dB/
octave roll-off by multiplying a vector by a Blackman window with the optimal value of alpha shown below:
 

 

The minimum len  is equal to 4. For large len, the optimal alpha converges asymptotically to the asymptotic
alpha; the application can use the asymptotic value of alpha shown below:
alpha = -0.25

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                  NULL.
ippStsSizeErr                     Indicates an error when len is less than 4 for the function
                                  ippsWinBlackmanOpt   and less than 3 for all other functions of
                                  the family.

Example
The example below shows how to use the function ippsWinBlackmanStd_32f_I
void blackman(void) {
      Ipp32f x[8];
      ippsSet_32f(1, x, 8);
      ippsWinBlackmanStd_32f_I(x, 8);
      printf_32f(“blackman (half) =”, x, 4, ippStsNoErr); 
}

Output:
    blackman(half) = 0.000000 0.090453 0.459183 0.920364 
Matlab* Analog: 
    >> b = blackman(8)'; b(1:4)

WinHamming
Multiplies a vector by a Hamming windowing function.

Syntax
IppStatus ippsWinHamming_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len       );
IppStatus ippsWinHamming_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len       );
IppStatus ippsWinHamming_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len       );
IppStatus ippsWinHamming_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len       );
IppStatus ippsWinHamming_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len       );

   178
---------------------Page 179---------------------

                                                                         Essential Functions  5 

IppStatus ippsWinHamming_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len      );
IppStatus ippsWinHamming_16s_I(Ipp16s* pSrcDst, int len    );
IppStatus ippsWinHamming_32f_I(Ipp32f* pSrcDst, int len    );
IppStatus ippsWinHamming_64f_I(Ipp64f* pSrcDst, int len    );
IppStatus ippsWinHamming_16sc_I(Ipp16sc* pSrcDst, int len    );
IppStatus ippsWinHamming_32fc_I(Ipp32fc* pSrcDst, int len    );
IppStatus ippsWinHamming_64fc_I(Ipp64fc* pSrcDst, int len    );

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.

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

Description
This function multiplies the vector pSrc by the Hamming window and stores the result in pDst.
The in-place flavors of ippsWinHamming multiply the vector pSrcDst by the Hamming window and store the
result in pSrcDst.
The complex types multiply both the real and imaginary parts of the vector by the same window. The
Hamming window is defined as follows:
 

 

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                 NULL.
ippStsSizeErr                    Indicates an error when len is less than 3.

                                                                                         179
---------------------Page 180---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Example
The example below shows how to use the function ippsWinHamming_32f_I.

void hamming(void) {
      Ipp32f x[8];
      ippsSet_32f(1, x, 8);
      ippsWinHamming_32f_I(x, 8);
      printf_32f(“hamming(half) =”, x, 4, ippStsNoErr);
}   

Output:
 hamming(half) =  0.080000 0.253195 0.642360 0.954446
Matlab* Analog: 
    >> b = hamming(8); b(1:4)'

WinHann
Multiplies a vector by a Hann windowing function.

Syntax
IppStatus ippsWinHann_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len    );
IppStatus ippsWinHann_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len    );
IppStatus ippsWinHann_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len    );
IppStatus ippsWinHann_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len    );
IppStatus ippsWinHann_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len    );
IppStatus ippsWinHann_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len    );
IppStatus ippsWinHann_16s_I(Ipp16s* pSrcDst, int len   );
IppStatus ippsWinHann_16sc_I(Ipp16sc* pSrcDst, int len   );
IppStatus ippsWinHann_32f_I(Ipp32f* pSrcDst, int len   );
IppStatus ippsWinHann_32fc_I(Ipp32fc* pSrcDst, int len   );
IppStatus ippsWinHann_64f_I(Ipp64f* pSrcDst, int len   );
IppStatus ippsWinHann_64fc_I(Ipp64fc* pSrcDst, int len   );

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.

pSrcDst                     Pointer to the source and destination vector for the in-place
                            operation.
len                         Number of elements in the vector.

   180
---------------------Page 181---------------------

                                                                         Essential Functions  5 

Description
This function multiplies the vector pSrc by the Hann window and stores the result in pDst.
The in-place flavors of ippsWinHann multiply the vector pSrcDst by the Hann window and store the result in
pSrcDst.
The complex types multiply both the real and imaginary parts of the vector by the same window. The Hann
window is defined as follows:
 

 

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc, pDst, or pSrcDst pointer is
                                 NULL.
ippStsSizeErr                    Indicates an error when len is less than 3.

Example
The example below shows how to use the function ippsWinHann_32f_I

void hann(void) {
      Ipp32f x[8];
      ippsSet_32f(1, x, 8);
      ippsWinHann_32f_I(x, 8);
      printf_32f(“hann(half) =”, x, 4, ippStsNoErr);
}

Output:
 hann(half) =  0.000000 0.188255 0.611260 0.950484
Matlab* Analog: 
    >> N = 8; n = 0:N-1; 0.5*(1-cos(2*pi*n/(N-1)))

WinKaiser
Multiplies a vector by a Kaiser windowing function.

Syntax
IppStatus ippsWinKaiser_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, float alpha      );
IppStatus ippsWinKaiser_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, float alpha      );
IppStatus ippsWinKaiser_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, Ipp64f alpha      );
IppStatus ippsWinKaiser_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, float alpha      );
IppStatus ippsWinKaiser_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, float alpha      );
IppStatus ippsWinKaiser_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, Ipp64f
alpha);
IppStatus ippsWinKaiser_16s_I(Ipp16s* pSrcDst, int len, float alpha     );
IppStatus ippsWinKaiser_32f_I(Ipp32f* pSrcDst, int len, float alpha     );

                                                                                        181
---------------------Page 182---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsWinKaiser_64f_I(Ipp64f* pSrcDst, int len, Ipp64f alpha       );
IppStatus ippsWinKaiser_16sc_I(Ipp16sc* pSrcDst, int len, float alpha       );
IppStatus ippsWinKaiser_32fc_I(Ipp32fc* pSrcDst, int len, float alpha       );
IppStatus ippsWinKaiser_64fc_I(Ipp64fc* pSrcDst, int len, Ipp64f alpha       );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsWinKaiserQ15_16s(const Ipp16s* pSrc, Ipp16s* pDst, int len, int
alphaQ15);
IppStatus ippsWinKaiserQ15_16sc(const Ipp16sc* pSrc, Ipp16sc* pDst, int len, int
alphaQ15);
IppStatus ippsWinKaiserQ15_16s_I(Ipp16s* pSrcDst, int len, int alphaQ15       );
IppStatus ippsWinKaiserQ15_16sc_I(Ipp16sc* pSrcDst, int len, int alphaQ15       );

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.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
alpha                        Adjustable parameter associated with the Kaiser windowing
                             equation.
alphaQ15                     Scaled version of alpha. The scaleFactor value is 15.

len                          Number of elements in the vector.

Description
Functions ippsWinKaiserQ15_16s  and ippsWinKaiserQ15_16sc  are deprecated. These functions are
obsolete and will be removed in a future release. Use the following link for details: http://software.intel.com/
sites/products/ipp-deprecated-features-feedback/.
This function multiplies the vector pSrc by the Kaiser window, and stores the result in pDst.
The in-place flavors of ippsWinKaiser multiply the vector pSrcDst by the Kaiser window and store the
result in pSrcDst.
ippsWinKaiser . The function ippsWinKaiser allows the application to specify alpha. The function
multiplies both real and imaginary parts of the complex vector by the same window. The Kaiser family of
windows are defined as follows:
 

   182
---------------------Page 183---------------------

                                                                        Essential Functions  5 

 
Here I0() is the modified zero-order Bessel function of the first kind.
ippsWinKaiserQ15 . The function ippsWinKaiserQ15 multiplies a vector by a Kaiser window with alphaQ15
scaled according to the factor 15.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pDst, pSrc, or pSrcDst pointer is
                                 NULL.
ippStsSizeErr                    Indicates an error when len is less than 1.

ippStsHugeWinErr                 Indicates an error when the Kaiser window is too big.

Example
The example below shows how to use the function ippsWinKaiser_32f_I.

void kaiser(void) {
     Ipp32f x[8];
     IppStatus st;
     ippsSet_32f(1, x, 8);
     st = ippsWinKaiser_32f_I( x, 8, 1.0f );
     printf_32f("kaiser(half) =", x, 4, ippStsNoErr);
}

Output:
 kaiser(half) =  0.135534 0.429046 0.755146 0.970290
Matlab* Analog: 
    >> kaiser(8,7/2)'

Statistical Functions

This section describes the Intel     functions that compute the vector measure values: maximum, minimum,
mean, and standard deviation.

Sum
Computes the sum of the elements of a vector.

Syntax
IppStatus ippsSum_32f(const Ipp32f* pSrc, int len, Ipp32f* pSum, IppHintAlgorithm
hint);
IppStatus ippsSum_32fc(const Ipp32fc* pSrc, int len, Ipp32fc* pSum, IppHintAlgorithm
hint);
IppStatus ippsSum_64f(const Ipp64f* pSrc, int len, Ipp64f* pSum    );
IppStatus ippsSum_64fc(const Ipp64fc* pSrc, int len, Ipp64fc* pSum    );
IppStatus ippsSum_16s_Sfs(const Ipp16s* pSrc, int len, Ipp16s* pSum, int scaleFactor      );
IppStatus ippsSum_32s_Sfs(const Ipp32s* pSrc, int len, Ipp32s* pSum, int scaleFactor      );
IppStatus ippsSum_16s32s_Sfs(const Ipp16s* pSrc, int len, Ipp32s* pSum, int
scaleFactor);

                                                                                       183
---------------------Page 184---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsSum_16sc_Sfs(const Ipp16sc* pSrc, int len, Ipp16sc* pSum, int
scaleFactor );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsSum_16sc32sc_Sfs(const Ipp16sc* pSrc, int len, Ipp32sc* pSum, int
scaleFactor );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                          Pointer to the source vector.

pSum                          Pointer to the output result.

len                           Number of elements in the vector.

hint                          Suggests using specific code. The possible values for the hint
                              argument are described in Special Arguments.
scaleFactor                   Scale factor, refer to Integer Scaling.

Description
The function ippsSum_16sc32sc_Sfs   is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function computes the sum of the elements of the vector pSrc and stores the result in pSum.
The sum of the elements of pSrc is defined by the formula:
 

 
The hint argument suggests using specific code, either faster but less accurate calculation, or more accurate
but slower calculation.
When computing the sum of integer numbers, the output result can exceed the data range and become
saturated. To get a precise result, use the scale factor. The scaling is performed in accordance with the
scaleFactor  value.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pSum  or pSrc pointer is NULL.

ippStsSizeErr                      Indicates an error when  len is less than or equal to 0.

   184
---------------------Page 185---------------------

                                                                         Essential Functions  5 

Example
The example below shows how to use the function ippsSum.

void sum(void) {
      Ipp16s x[4] = {-32768, 32767, 32767, 32767}, sm;
      ippsSum_16s_Sfs(x, 4, &sm, 1);
      printf_16s(“sum =”, &sm, 1, ippStsNoErr);
}

Output:
  sum = 32766
Matlab* Analog: 
    >> x = [-32768, 32767, 32767, 32767]; sum(x)/2

Max
Returns the maximum value of a vector.

Syntax
IppStatus ippsMax_16s(const Ipp16s* pSrc, int len, Ipp16s* pMax     );
IppStatus ippsMax_32s(const Ipp32s* pSrc, int len, Ipp32s* pMax     );
IppStatus ippsMax_32f(const Ipp32f* pSrc, int len, Ipp32f* pMax     );
IppStatus ippsMax_64f(const Ipp64f* pSrc, int len, Ipp64f* pMax     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

pMax                        Pointer to the output result.

len                         Number of elements in the vector

Description
This function returns the maximum value of the input vector pSrc, and stores the result in pMax.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pMax or pSrc pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

                                                                                        185
---------------------Page 186---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

MaxIndx
Returns the maximum value of a vector and the index
of the maximum element.

Syntax
IppStatus ippsMaxIndx_16s(const Ipp16s* pSrc, int len, Ipp16s* pMax, int* pIndx        );
IppStatus ippsMaxIndx_32s(const Ipp32s* pSrc, int len, Ipp32s* pMax, int* pIndx        );
IppStatus ippsMaxIndx_32f(const Ipp32f* pSrc, int len, Ipp32f* pMax, int* pIndx        );
IppStatus ippsMaxIndx_64f(const Ipp64f* pSrc, int len, Ipp64f* pMax, int* pIndx        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

pMax                         Pointer to the output result.

len                          Number of elements in the vector.

pIndx                        Pointer to the index value of the maximum element.

Description
This function returns the maximum value of the input vector pSrc, and stores the result in pMax. If pIndx is
not a NULL pointer, the function returns the index of the maximum element and stores it in pIndx. If there
are several equal maximum elements, the first index from the beginning is returned.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                     Indicates an error when len is less than or equal to 0.

Example
The code example below demonstrates how to use the function ippsMaxIndx.
Ipp16s src[] = { 1, -2, 3, 8, -6 }; 
Ipp16s max; 
int len = 5; 
int  indx;

ippsMaxIndx_16s ( src, len, &max, &indx );

Result:
max = 8  indx = 3

   186
---------------------Page 187---------------------

                                                                         Essential Functions  5 

MaxAbs
Returns the maximum absolute value of a vector.

Syntax
IppStatus ippsMaxAbs_16s(const Ipp16s* pSrc, int len, Ipp16s* pMaxAbs     );
IppStatus ippsMaxAbs_32s(const Ipp32s* pSrc, int len, Ipp32s* pMaxAbs     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

pMaxAbs                     Pointer to the output result.

len                         Number of elements in the vector.

Description
This function returns the maximum absolute value of the input vector pSrc, and stores the result in
pMaxAbs.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pMaxAbs or pSrc pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Example
The example below shows how to use the function ippsMaxAbs_16s.
Ipp16s src[5] = { 2, -8, -3, -1, 7 }; 
Ipp16s maxAbs;
ippsMaxAbs_16s ( src, 5, &maxAbs );
Result:
maxAbs = 8

MaxAbsIndx
Returns the maximum absolute value of a vector and
the index of the corresponding element.

Syntax
IppStatus ippsMaxAbsIndx_16s(const Ipp16s* pSrc, int len, Ipp16s* pMaxAbs, int* pIndx       );
IppStatus ippsMaxAbsIndx_32s(const Ipp32s* pSrc, int len, Ipp32s* pMaxAbs, int* pIndx       );

                                                                                        187
---------------------Page 188---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

pMaxAbs                      Pointer to the output result.

len                          Number of elements in the vector.

pIndx                        Pointer to the index value of the maximum element.

Description
This function returns the maximum absolute value pMaxAbs of the input vector pSrc, and the index of the
corresponding element pIndx. If there are several elements with the equal maximum absolute value, the
first index from the beginning is returned.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                     Indicates an error when len is less than or equal to 0.

Min
Returns the minimum value of a vector.

Syntax
IppStatus ippsMin_16s(const Ipp16s* pSrc, int len, Ipp16s* pMin      );
IppStatus ippsMin_32s(const Ipp32s* pSrc, int len, Ipp32s* pMin      );
IppStatus ippsMin_32f(const Ipp32f* pSrc, int len, Ipp32f* pMin      );
IppStatus ippsMin_64f(const Ipp64f* pSrc, int len, Ipp64f* pMin      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

pMin                         Pointer to the output result.

   188
---------------------Page 189---------------------

                                                                         Essential Functions  5 

len                         Number of elements in the vector.

Description
This function returns the minimum value of the input vector pSrc, and stores the result in pMin.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pMin or pSrc pointer is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Example
The example below shows how to use the function ippsMin.
Ipp16s src = { 1, -2, 3, 8, -6}; 
Ipp16s min; 
int len = 5;
ippsMin_16s (src, len, &min );
Result:
 min = -6

MinIndx
Returns the minimum value of a vector and the index
of the minimum element.

Syntax
IppStatus ippsMinIndx_16s(const Ipp16s* pSrc, int len, Ipp16s* pMin, int* pIndx      );
IppStatus ippsMinIndx_32s(const Ipp32s* pSrc, int len, Ipp32s* pMin, int* pIndx      );
IppStatus ippsMinIndx_32f(const Ipp32f* pSrc, int len, Ipp32f* pMin, int* pIndx      );
IppStatus ippsMinIndx_64f(const Ipp64f* pSrc, int len, Ipp64f* pMin, int* pIndx      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

pMin                        Pointer to the output result.

len                         Number of elements in the vector.

pIndx                       Pointer to the index value of the minimum element.

                                                                                        189
---------------------Page 190---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Description
This function returns the minimum value of the input vector pSrc and stores the result in pMin. If pIndx is
not a NULL pointer, the function returns the index of the minimum element and stores it in pIndx. If there
are several equal minimum elements, the first index from the beginning is returned.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pMin or pSrc pointer is NULL.

ippStsSizeErr                     Indicates an error when  len is less than or equal to 0.

MinAbs
Returns the minimum absolute value of a vector.

Syntax
IppStatus ippsMinAbs_16s(const Ipp16s* pSrc, int len, Ipp16s* pMinAbs        );
IppStatus ippsMinAbs_32s(const Ipp32s* pSrc, int len, Ipp32s* pMinAbs        );

Include Files
ipps.h

Parameters

pSrc                         Pointer to the source vector.

pMinAbs                      Pointer to the output result.

len                          Number of elements in the vector.

Description
This function returns the minimum absolute value of the input vector pSrc, and stores the result in pMinAbs.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pMinAbs or pSrc pointer is NULL.

ippStsSizeErr                     Indicates an error when  len is less than or equal to 0.

MinAbsIndx
Returns the minimum absolute value of a vector and
the index of the corresponding element.

Syntax
IppStatus ippsMinAbsIndx_16s(const Ipp16s* pSrc, int len, Ipp16s* pMinAbs, int* pIndx          );
IppStatus ippsMinAbsIndx_32s(const Ipp32s* pSrc, int len, Ipp32s* pMinAbs, int* pIndx          );

Include Files
ipps.h

   190
---------------------Page 191---------------------

                                                                        Essential Functions  5 

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

pMinAbs                     Pointer to the output result.

len                         Number of elements in the vector.

pIndx                       Pointer to the index value of the corresponding element.

Description
This function returns the minimum absolute value pMinAbs of the input vector pSrc, and the index of the
corresponding element pIndx. If there are several elements with equal maximum absolute value, the first
index from the beginning is returned.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

MinMax
Returns the maximum and minimum values of a
vector.

Syntax
IppStatus ippsMinMax_8u(const Ipp8u* pSrc, int len, Ipp8u* pMin, Ipp8u* pMax     );
IppStatus ippsMinMax_16u(const Ipp16u* pSrc, int len, Ipp16u* pMin, Ipp16u* pMax     );
IppStatus ippsMinMax_16s(const Ipp16s* pSrc, int len, Ipp16s* pMin, Ipp16s* pMax     );
IppStatus ippsMinMax_32u(const Ipp32u* pSrc, int len, Ipp32u* pMin, Ipp32u* pMax     );
IppStatus ippsMinMax_32s(const Ipp32s* pSrc, int len, Ipp32s* pMin, Ipp32s* pMax     );
IppStatus ippsMinMax_32f(const Ipp32f* pSrc, int len, Ipp32f* pMin, Ipp32f* pMax     );
IppStatus ippsMinMax_64f(const Ipp64f* pSrc, int len, Ipp64f* pMin, Ipp64f* pMax     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

                                                                                        191
---------------------Page 192---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

pMin                        Pointer to the minimum value.

pMax                        Pointer to the maximum value.

len                         Number of elements in the vector.

Description
This function returns the minimum and maximum values of the input vector pSrc, and stores the results in
pMin and pMax, respectively.

Return Values

ippStsNoErr                     Indicates no error.

ippStsNullPtrErr                Indicates an error when the pMin or pSrc pointer is NULL.

ippStsSizeErr                   Indicates an error when len is less than or equal to 0.

MinMaxIndx
Returns the maximum and minimum values of a
vector and the indexes of the corresponding elements.

Syntax
IppStatus ippsMinMaxIndx_8u(const Ipp8u* pSrc, int len, Ipp8u* pMin, int* pMinIndx,
Ipp8u* pMax, int* pMaxIndx );
IppStatus ippsMinMaxIndx_16u(const Ipp16u* pSrc, int len, Ipp16u* pMin, int* pMinIndx,
Ipp16u* pMax, int* pMaxIndx );
IppStatus ippsMinMaxIndx_16s(const Ipp16s* pSrc, int len, Ipp16s* pMin, int* pMinIndx,
Ipp16s* pMax, int* pMaxIndx );
IppStatus ippsMinMaxIndx_32u(const Ipp32u* pSrc, int len, Ipp32u* pMin, int* pMinIndx,
Ipp32u* pMax, int* pMaxIndx );
IppStatus ippsMinMaxIndx_32s(const Ipp32s* pSrc, int len, Ipp32s* pMin, int* pMinIndx,
Ipp32s* pMax, int* pMaxIndx );
IppStatus ippsMinMaxIndx_32f(const Ipp32f* pSrc, int len, Ipp32f* pMin, int* pMinIndx,
Ipp32f* pMax, int* pMaxIndx );
IppStatus ippsMinMaxIndx_64f(const Ipp64f* pSrc, int len, Ipp64f* pMin, int* pMinIndx,
Ipp64f* pMax, int* pMaxIndx );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

pMin                        Pointer to the minimum value.

   192
---------------------Page 193---------------------

                                                                        Essential Functions  5 

pMax                        Pointer to the maximum value.

len                         Number of elements in the vector.

pMinIndx                    Pointer to the index value of the minimum element.

pMaxIndx                    Pointer to the index value of the maximum element.

Description
This function returns the minimum and maximum values of the input vector pSrc and stores the result in
pMin and pMax, respectively. The function also returns the indexes of the minimum and maximum elements
and stores them in pMinIndx and pMaxIndx, respectively. If there are several equal minimum or maximum
elements, the first index from the beginning is returned.

Return Values

ippStsNoErr                      Indicates no error.

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

ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Mean
Computes the mean value of a vector.

Syntax
IppStatus ippsMean_32f(const Ipp32f* pSrc, int len, Ipp32f* pMean, IppHintAlgorithm
hint);
IppStatus ippsMean_32fc(const Ipp32fc* pSrc, int len, Ipp32fc* pMean, IppHintAlgorithm
hint);
IppStatus ippsMean_64f(const Ipp64f* pSrc, int len, Ipp64f* pMean    );
IppStatus ippsMean_64fc(const Ipp64fc* pSrc, int len, Ipp64fc* pMean     );
IppStatus ippsMean_16s_Sfs(const Ipp16s* pSrc, int len, Ipp16s* pMean, int
scaleFactor);
IppStatus ippsMean_32s_Sfs(const Ipp32s* pSrc,int len,Ipp32s* pMean,int scaleFactor      );
IppStatus ippsMean_16sc_Sfs(const Ipp16sc* pSrc, int len, Ipp16sc* pMean, int
scaleFactor);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source vector.

pMean                       Pointer to the output result.

len                         Number of elements in the vector

                                                                                        193
---------------------Page 194---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

hint                         Suggests using specific code. The possible values for the hint
                             argument are described in Special Arguments.
scaleFactor                  Scale factor, refer to Integer Scaling.

Description
This function computes the mean (average) of the vector pSrc, and stores the result in pMean. The mean of
pSrc is defined by the formula:
 

 
The hint argument suggests using specific code, either faster but less accurate calculation, or more accurate
but slower calculation.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pMean or pSrc pointer is NULL.

ippStsSizeErr                     Indicates an error when len is less than or equal to 0.

Example
The example below shows how to use the function ippsMean_32f
void mean(void) {
      Ipp32f *x = ippsMalloc_32f(1000), mean;
      int i;
      for(i = 0; i<1000; ++i) x[i] = (float)rand() / RAND_MAX;
      ippsMean_32f(x, 1000, &mean, ippAlgHintFast);
      printf_32f(“mean =”, &mean, 1, ippStsNoErr);
      ippsFree(x);
}

Output:
 mean = 0.492591
Matlab* Analog: 
    >> x = rand(1,1000); mean(x)

StdDev
Computes the standard deviation value of a vector.

Syntax
IppStatus ippsStdDev_32f(const Ipp32f* pSrc, int len, Ipp32f* pStdDev, IppHintAlgorithm
hint);
IppStatus ippsStdDev_64f(const Ipp64f* pSrc, int len, Ipp64f* pStdDev       );
IppStatus ippsStdDev_16s_Sfs(const Ipp16s* pSrc, int len, Ipp16s* pStdDev, int
scaleFactor );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsStdDev_16s32s_Sfs(const Ipp16s* pSrc, int len, Ipp32s* pStdDev, int
scaleFactor );

   194
---------------------Page 195---------------------

                                                                              Essential Functions  5 

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                          Pointer to the source vector.

pStdDev                       Pointer to the output result.

len                           Number of elements in the vector.

hint                          Suggests using specific code. The possible values for the hint
                              argument are described in Special Arguments.
scaleFactor                   Scale factor, refer to Integer Scaling.

Description
The function ippsStdDev_16s32s_Sfs   is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function computes the standard deviation of the input vector pSrc, and stores the result in pStdDev.
The vector length can not be less than 2. The standard deviation of pSrc is defined by the unbiased estimate
formula:
 

 

The hint argument suggests using specific code, either faster but less accurate calculation, or more accurate
but slower calculation.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pStdDev  or pSrc pointer is NULL.

ippStsSizeErr                      Indicates an error when  len is less than or equal to 1.

Example
The example below shows how to use the function ippsStdDev_32f.

void stdev(void) {
      Ipp32f *x = ippsMalloc_32f(1000), stdev;
      int i;
      for (i = 0; i<1000; ++i) x[i] = (float)rand() / RAND_MAX;
      ippsStdDev_32f(x, 1000, &stdev, ippAlgHintFast);

                                                                                              195
---------------------Page 196---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing
      printf_32f(“stdev =”, &stdev, 1, ippStsNoErr);
      ippsFree(x);
}   

Output:
 stdev = 0.286813
Matlab* Analog: 
    >> x = rand(1,1000); std(x)

MeanStdDev
Computes the mean value and the standard deviation
value of a vector.

Syntax
IppStatus ippsMeanStdDev_32f(const Ipp32f* pSrc, int len, Ipp32f* pMean, Ipp32f*
pStdDev, IppHintAlgorithm hint   );
IppStatus ippsMeanStdDev_64f(const Ipp64f* pSrc, int len, Ipp64f* pMean, Ipp64f*
pStdDev);
IppStatus ippsMeanStdDev_16s_Sfs(const Ipp16s* pSrc, int len, Ipp16s* pMean, Ipp16s*
pStdDev, int scaleFactor  );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsMeanStdDev_16s32s_Sfs(const Ipp16s* pSrc, int len, Ipp32s* pMean, Ipp32s*
pStdDev, int scaleFactor  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

pMean                        Pointer to the output result - mean value.

pStdDev                      Pointer to the output result - standard deviation.

len                          Number of elements in the vector

hint                         Suggests using specific code. The possible values for the hint
                             argument are described in Special Arguments.
scaleFactor                  Scale factor, refer to Integer Scaling.

Description
The function ippsMeanStdDev is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function computes both the mean value and the standard deviation of the input vector pSrc, and stores
the results in pMean and pStdDev respectively. The vector length can not be less than 2. The mean of pSrc
is defined by the formula:

   196
---------------------Page 197---------------------

                                                                      Essential Functions  5 

 

 
The standard deviation of pSrc is defined by the unbiased estimate formula:
 

 

The hint argument suggests using specific code, either faster but less accurate calculation, or more accurate
but slower calculation.

Return Values

ippStsNoErr                     Indicates no error.

ippStsNullPtrErr                Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                   Indicates an error when len is less than or equal to 1.

Norm
Computes the C, L1, L2, or L2Sqr norm of a vector.

Syntax
IppStatus ippsNorm_Inf_32f(const Ipp32f* pSrc, int len, Ipp32f* pNorm   );
IppStatus ippsNorm_Inf_64f(const Ipp64f* pSrc, int len, Ipp64f* pNorm   );
IppStatus ippsNorm_Inf_16s32f(const Ipp16s* pSrc, int len, Ipp32f* pNorm   );
IppStatus ippsNorm_Inf_32fc32f(const Ipp32fc* pSrc, int len, Ipp32f* pNorm   );
IppStatus ippsNorm_Inf_64fc64f(const Ipp64fc* pSrc, int len, Ipp64f* pNorm   );

IppStatus ippsNorm_L1_32f(const Ipp32f* pSrc, int len, Ipp32f* pNorm   );
IppStatus ippsNorm_L1_64f(const Ipp64f* pSrc, int len, Ipp64f* pNorm   );
IppStatus ippsNorm_L1_16s32f(const Ipp16s* pSrc, int len, Ipp32f* pNorm   );
IppStatus ippsNorm_L1_32fc64f(const Ipp32fc* pSrc, int len, Ipp64f* pNorm   );
IppStatus ippsNorm_L1_64fc64f(const Ipp64fc* pSrc, int len, Ipp64f* pNorm   );
IppStatus ippsNorm_L2_32f(const Ipp32f* pSrc, int len, Ipp32f* pNorm   );
IppStatus ippsNorm_L2_64f(const Ipp64f* pSrc, int len, Ipp64f* pNorm   );
IppStatus ippsNorm_L2_16s32f(const Ipp16s* pSrc, int len, Ipp32f* pNorm   );
IppStatus ippsNorm_L2_32fc64f(const Ipp32fc* pSrc, int len, Ipp64f* pNorm   );
IppStatus ippsNorm_L2_64fc64f(const Ipp64fc* pSrc, int len, Ipp64f* pNorm   );

                                                                                     197
---------------------Page 198---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsNorm_Inf_16s32s_Sfs(const Ipp16s* pSrc, int len, Ipp32s* pNorm, int
scaleFactor );
IppStatus ippsNorm_L1_16s32s_Sfs(const Ipp16s* pSrc, int len, Ipp32s* pNorm, int
scaleFactor );
IppStatus ippsNorm_L1_16s64s_Sfs(const Ipp16s* pSrc, int len, Ipp64s* pNorm, int
scaleFactor );
IppStatus ippsNorm_L2_16s32s_Sfs(const Ipp16s* pSrc, int len, Ipp32s* pNorm, int
scaleFactor );
IppStatus ippsNorm_L2Sqr_16s64s_Sfs(const Ipp16s* pSrc, int len, Ipp64s* pNorm, int
scaleFactor );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the source vector.

pNorm                        Pointer to the output result.

len                          Number of elements in the vector.

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
Functions ippsNorm_Inf_16s32s_Sfs , ippsNorm_L1_16s32s_Sfs  , ippsNorm_L1_16s64s_Sfs  ,
ippsNorm_L2_16s32s_Sfs   , and ippsNorm_L2Sqr_16s64s_Sfs  are deprecated. These functions are
obsolete and will be removed in a future release. Use the following link for details: http://software.intel.com/
sites/products/ipp-deprecated-features-feedback/.
This function computes the C, L1, L2, or L2Sqr norm of the source vector pSrc and stores the result in
pNorm.
ippsNorm_Inf .The function ippsNorm_Inf computes the C norm defined by the formula:
 

 
ippsNorm_L1 . The function ippsNorm_L1 computes the L1 norm defined by the formula:
 

 
ippsNorm_L2 . The function ippsNorm_L2 computes the L2 norm defined by the formula:
 

   198
---------------------Page 199---------------------

                                                                      Essential Functions  5 

 

ippsNorm_L2Sqr. The function ippsNorm_L2Sqr computes the L2Sqr norm defined as square of the L2
norm.
Functions with Sfs suffixes perform scaling of the result value in accordance with the scaleFactor value.

Return Values

ippStsNoErr                    Indicates no error.

ippStsNullPtrErr               Indicates an error when the pSrc or pNorm pointer is NULL.

ippStsSizeErr                  Indicates an error when len is less than or equal to 0.

NormDiff
Computes the C, L1, L2, or L2Sqr norm of two vectors'
difference.

Syntax
IppStatus ippsNormDiff_Inf_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, int len,
Ipp32f* pNorm);
IppStatus ippsNormDiff_Inf_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, int len,
Ipp64f* pNorm);
IppStatus ippsNormDiff_Inf_16s32f(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len,
Ipp32f* pNorm);
IppStatus ippsNormDiff_Inf_32fc32f(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, int len,
Ipp32f* pNorm);
IppStatus ippsNormDiff_Inf_64fc64f(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, int len,
Ipp64f* pNorm);

IppStatus ippsNormDiff_L1_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, int len,
Ipp32f* pNorm);
IppStatus ippsNormDiff_L1_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, int len,
Ipp64f* pNorm);
IppStatus ippsNormDiff_L1_16s32f(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len,
Ipp32f* pNorm);
IppStatus ippsNormDiff_L1_32fc64f(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, int len,
Ipp64f* pNorm);
IppStatus ippsNormDiff_L1_64fc64f(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, int len,
Ipp64f* pNorm);
IppStatus ippsNormDiff_L2_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, int len,
Ipp32f* pNorm);
IppStatus ippsNormDiff_L2_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, int len,
Ipp64f* pNorm);

                                                                                     199
---------------------Page 200---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsNormDiff_L2_16s32f(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len,
Ipp32f* pNorm );
IppStatus ippsNormDiff_L2_32fc64f(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, int len,
Ipp64f* pNorm );
IppStatus ippsNormDiff_L2_64fc64f(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, int len,
Ipp64f* pNorm );
IppStatus ippsNormDiff_L2Sqr_16s64s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int
len, Ipp64s* pNorm, int scaleFactor  );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsNormDiff_Inf_16s32s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int
len, Ipp32s* pNorm, int scaleFactor  );
IppStatus ippsNormDiff_L1_16s32s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len,
Ipp32s* pNorm, int scaleFactor  );
IppStatus ippsNormDiff_L1_16s64s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len,
Ipp64s* pNorm, int scaleFactor  );
IppStatus ippsNormDiff_L2_16s32s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len,
Ipp32s* pNorm, int scaleFactor  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2                Pointers to the two source vectors; pSrc2 can be NULL.

pNorm                       Pointer to the output result.

len                         Number of elements in the vector.

scaleFactor                 Scale factor, refer to Integer Scaling.

Description
Functions ippsNormDiff_Inf_16s32s_Sfs, ippsNormDiff_L1_16s32s_Sfs   ,
ippsNormDiff_L1_16s64s_Sfs  , and ippsNormDiff_L2_16s32s_Sfs are deprecated. These functions are
obsolete and will be removed in a future release. Use the following link for details: http://software.intel.com/
sites/products/ipp-deprecated-features-feedback/.
This function computes the C, L1, L2, or L2Sqr norm of the source vectors' difference, and stores the result
in pNorm.
ippsNormDiff_Inf . The function ippsNormDiff_Inf computes the C norm defined by the formula:
 

 
ippsNormDiff_L1 . The function ippsNormDiff_L1 computes the L1 norm defined by the formula:

   200
---------------------Page 201---------------------

                                                                          Essential Functions  5 

 

 
ippsNormDiff_L2 . The function ippsNormDiff_L2 computes the L2 norm defined by the formula:
 

 
ippsNormDiff_L2Sqr . The function ippsNormDiff_L2Sqr computes the L2Sqr norm defined as square of
the L2 norm.
Functions with Sfs suffixes perform scaling of the result value in accordance with the scaleFactor value.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pSrc1 , pSrc2, or pNorm pointer is
                                 NULL .
ippStsSizeErr                    Indicates an error when len  is less than or equal to 0.

Example
The example below shows how to use the function ippsNormDiff.
int norm( void ) {
      Ipp16s x[LEN];
      Ipp32f Norm[3];
      IppStatus st;
      int i;
      for( i=0; i<LEN; ++i ) x[i] = (Ipp16s)rand();
      ippsNormDiff_Inf_16s32f( x, 0, LEN, Norm );
      ippsNormDiff_L1_16s32f( x, 0, LEN, Norm+1 );
      st = ippsNormDiff_L2_16s32f( x, 0, LEN, Norm+2 );
      printf_32f(“Norm (oo,L1,L2) =”, Norm, 3, st );
      return Norm[2] <= Norm[1] && Norm[1] <= LEN*Norm[0];
}

   

Output:
 Norm (oo,L1,L2) =  31993.000000 1526460.000000 180270.781250
Matlab* analog: 
    >> x = 32767*rand(1,100);norm(x,inf),norm(x,1),norm(x,2)

DotProd
Computes the dot product of two vectors.

Syntax
IppStatus ippsDotProd_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, int len, Ipp32f*
pDp);

                                                                                          201
---------------------Page 202---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsDotProd_32fc(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, int len,
Ipp32fc* pDp);
IppStatus ippsDotProd_32f32fc(const Ipp32f* pSrc1, const Ipp32fc* pSrc2, int len,
Ipp32fc* pDp);
IppStatus ippsDotProd_32f64f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, int len, Ipp64f*
pDp);
IppStatus ippsDotProd_32fc64fc(const Ipp32fc* pSrc1, const Ipp32fc* pSrc2, int len,
Ipp64fc* pDp);
IppStatus ippsDotProd_32f32fc64fc(const Ipp32f* pSrc1, const Ipp32fc* pSrc2, int len,
Ipp64fc* pDp);
IppStatus ippsDotProd_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, int len, Ipp64f*
pDp);
IppStatus ippsDotProd_64fc(const Ipp64fc* pSrc1, const Ipp64fc* pSrc2, int len,
Ipp64fc* pDp);
IppStatus ippsDotProd_64f64fc(const Ipp64f* pSrc1, const Ipp64fc* pSrc2, int len,
Ipp64fc* pDp);
IppStatus ippsDotProd_16s64s(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len, Ipp64s*
pDp);
IppStatus ippsDotProd_16sc64sc(const Ipp16sc* pSrc1, const Ipp16sc* pSrc2, int len,
Ipp64sc* pDp);
IppStatus ippsDotProd_16s16sc64sc(const Ipp16s* pSrc1, const Ipp16sc* pSrc2, int len,
Ipp64sc* pDp);
IppStatus ippsDotProd_16s32f(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len, Ipp32f*
pDp);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_16sc32fc(const Ipp16sc* pSrc1, const Ipp16sc* pSrc2, int len,
Ipp32fc* pDp);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_16s16sc32fc(const Ipp16s* pSrc1, const Ipp16sc* pSrc2, int len,
Ipp32fc* pDp);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_16s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len,
Ipp16s* pDp, int scaleFactor);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_16sc_Sfs(const Ipp16sc* pSrc1, const Ipp16sc* pSrc2, int len,
Ipp16sc* pDp, int scaleFactor);
IppStatus ippsDotProd_32s_Sfs(const Ipp32s* pSrc1, const Ipp32s* pSrc2, int len,
Ipp32s* pDp, int scaleFactor);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_32sc_Sfs(const Ipp32sc* pSrc1, const Ipp32sc* pSrc2, int len,
Ipp32sc* pDp, int scaleFactor);
IppStatus ippsDotProd_16s32s_Sfs(const Ipp16s* pSrc1, const Ipp16s* pSrc2, int len,
Ipp32s* pDp, int scaleFactor);

  202
---------------------Page 203---------------------

                                                                        Essential Functions  5 

THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_16s16sc32sc_Sfs(const Ipp16s* pSrc1, const Ipp16sc* pSrc2, int
len, Ipp32sc* pDp, int scaleFactor  );
IppStatus ippsDotProd_16s32s32s_Sfs(const Ipp16s* pSrc1, const Ipp32s* pSrc2, int len,
Ipp32s* pDp, int scaleFactor  );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_16s16sc_Sfs(const Ipp16s* pSrc1, const Ipp16sc* pSrc2, int len,
Ipp16sc* pDp, int scaleFactor  );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_16sc32sc_Sfs(const Ipp16sc* pSrc1, const Ipp16sc* pSrc2, int len,
Ipp32sc* pDp, int scaleFactor  );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsDotProd_32s32sc_Sfs(const Ipp32s* pSrc1, const Ipp32sc* pSrc2, int len,
Ipp32sc* pDp, int scaleFactor  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1                       Pointer to the first vector to compute the dot product value.

pSrc2                       Pointer to the second vector to compute the dot product value.

pDp                         Pointer to the output result.

len                         Number of elements in the vector.

scaleFactor                 Scale factor, refer to Integer Scaling.

Description
Functions ippsDotProd_16sc32fc, ippsDotProd_16s16sc32fc , ippsDotProd_16s_Sfs,
ippsDotProd_16sc_Sfs , ippsDotProd_32sc_Sfs , ippsDotProd_16s16sc32sc_Sfs ,
ippsDotProd_16s16sc_Sfs , ippsDotProd_16sc32sc_Sfs , andippsDotProd_32s32sc_Sfs  are
deprecated. These functions are obsolete and will be removed in a future release. Use the following link for
details: http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function computes the dot product (scalar value) of two vectors, pSrc1 and pSrc2, and stores the result
in pDp.
The computation is performed as follows:

 

 

                                                                                       203
---------------------Page 204---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

To compute the dot product of complex data, use the function ippsConj to conjugate one of the operands.
The vectors pSrc1 and pSrc2 must be of equal length.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pDp, pSrc1, or pSrc2 pointer is
                                 NULL.
ippStsSizeErr                    Indicates an error when len is less than or equal to 0.

Example
The example below shows how to use the function ippsDotProd_64f to verify orthogonality of the sine and
cosine functions. Two vectors are orthogonal to each other when the dot product of the two vectors is zero.

void dotprod(void) {
      Ipp64f x[10], dp;
      int n;
      for (n = 0; n<10; ++n) x[n] = sin(IPP_2PI * n / 8);
      ippsDotProd_64f(x, x+2, 8, &dp);
      printf_64f(“dp =”, &dp, 1, ippStsNoErr);
}

Output:
 dp = 0.000000
Matlab* Analog: 
    >> n = 0:9; x = sin(2*pi*n/8); a = x(1:8); b = x(3:10); a*b'

MaxEvery, MinEvery
Computes maximum or minimum value for each pair
of elements of two vectors.

Syntax
IppStatus ippsMaxEvery_8u(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, const
Ipp32u len);
IppStatus ippsMaxEvery_16u(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst,
const Ipp32u len );
IppStatus ippsMaxEvery_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, Ipp32f* pDst,
const Ipp32u len );
IppStatus ippsMaxEvery_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, Ipp64f* pDst,
const Ipp32u len );
IppStatus ippsMinEvery_8u(const Ipp8u* pSrc1, const Ipp8u* pSrc2, Ipp8u* pDst, const
Ipp32u len);
IppStatus ippsMinEvery_16u(const Ipp16u* pSrc1, const Ipp16u* pSrc2, Ipp16u* pDst,
const Ipp32u len );
IppStatus ippsMinEvery_32f(const Ipp32f* pSrc1, const Ipp32f* pSrc2, Ipp32f* pDst,
const Ipp32u len );
IppStatus ippsMinEvery_64f(const Ipp64f* pSrc1, const Ipp64f* pSrc2, Ipp64f* pDst,
const Ipp32u len );
IppStatus ippsMaxEvery_8u_I(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len     );

   204
---------------------Page 205---------------------

                                                                       Essential Functions  5 

IppStatus ippsMaxEvery_16u_I(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len   );
IppStatus ippsMaxEvery_16s_I(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len   );
IppStatus ippsMaxEvery_32s_I(const Ipp32s* pSrc, Ipp32s* pSrcDst, int len   );
IppStatus ippsMaxEvery_32f_I(const Ipp32f* pSrc, Ipp32f* pSrcDst, int len   );
IppStatus ippsMaxEvery_64f_I(const Ipp64f* pSrc, Ipp64f* pSrcDst, Ipp32u len   );
IppStatus ippsMinEvery_8u_I(const Ipp8u* pSrc, Ipp8u* pSrcDst, int len   );
IppStatus ippsMinEvery_16u_I(const Ipp16u* pSrc, Ipp16u* pSrcDst, int len   );
IppStatus ippsMinEvery_16s_I(const Ipp16s* pSrc, Ipp16s* pSrcDst, int len   );
IppStatus ippsMinEvery_32s_I(const Ipp32s* pSrc, Ipp32s* pSrcDst, int len   );
IppStatus ippsMinEvery_32f_I(const Ipp32f* pSrc, Ipp32f* pSrcDst, int len   );
IppStatus ippsMinEvery_64f_I(const Ipp64f* pSrc, Ipp64f* pSrcDst, Ipp32u len   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                       Pointer to the first input vector.

pSrcDst                    Pointer to the second input vector which stores the result.

len                        Number of elements in the vector.

Description
This function computes the maximum between each pair of corresponding elements of two input vectors and
stores the result in pSrcDst.
This function computes minimum values likewise.

Return Values

ippStsNoErr                     Indicates no error.

ippStsNullPtrErr                Indicates an error when the pSrc or pSrcDst pointer is NULL.

ippStsSizeErr                   Indicates an error when len is less than or equal to 0.

ZeroCrossing
Computes specific zero crossing measure.

Syntax
IppStatus ippsZeroCrossing_16s32f(const Ipp16s* pSrc, Ipp32u len, Ipp32f* pValZC,
IppsZCType zcType);
IppStatus ippsZeroCrossing_32f(const Ipp32f* pSrc, Ipp32u len, Ipp32f* pValZC,
IppsZCType zcType);

                                                                                      205
---------------------Page 206---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                          Pointer to the source vector.

len                           Number of elements in the vector.

pValZC                        Pointer to the output value of the zero crossing measure.

zcType                        Type of the zero crossing measure, possible values are    ippsZCR ,
                              ippsZCXor   or ippsZCC .

Description
This function computes specific zero crossing measure according to the parameter zcType. The result of zero
crossing measurement is stored in pValZC. The calculations are performed in accordance with the formulas
below.
If zcType = ippZCR , the function uses the following formula:
 

 
If zcType = ippZCXor , the function uses the following formula:

 

 

If zcType = ippZCC , the function uses the following formula:

 

 

Return Values

ippStsNoErr                        Indicates no error.

   206
---------------------Page 207---------------------

                                                                            Essential Functions  5 

ippStsNullPtrErr                  Indicates an error when the pSrc  or pValZC pointer is NULL.

ippStsRangeErr                    Indicates an error when zcType  has an invalid value.

CountInRange
Computes the number of elements of the vector
whose values are in the specified range.

Syntax
IppStatus ippsCountInRange_32s(const Ipp32s* pSrc, int len, int* pCounts, Ipp32s
lowerBound, Ipp32s upperBound   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                         Pointer to the first input vector.

pCounts                      Pointer to the second input vector which stores the result.

len                          Number of elements in the vector.

lowerBound                   Lower boundary of the range.

upperBound                   Upper boundary of the range.

Description
This function computes the number of elements of the vector pSrc whose values are in the range
lowerBound < pSrc[n] < upperBound    . The total number of such elements are stored in the pCounts.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pSrc  or pSCounts pointer is NULL.

ippStsSizeErr                     Indicates an error when len  is less than or equal to 0.

Sampling Functions
The functions described in this section manipulate signal samples. Sampling functions are used to change the
sampling rate of the input signal and thus to obtain the signal vector of a required length. The functions
perform the following operations:
• Insert zero-valued samples between neighboring samples of a signal (up-sample).
• Remove samples from between neighboring samples of a signal (down-sample).
The upsampling and downsampling functions are used by some filtering functions described in Chapter 6.

                                                                                            207
---------------------Page 208---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

SampleUp
Up-samples a signal, conceptually increasing its
sampling rate by an integer factor.

Syntax
IppStatus ippsSampleUp_16s (const Ipp16s* pSrc, int srcLen, Ipp16s* pDst, int* pDstLen,
int factor, int* pPhase  );
IppStatus ippsSampleUp_32f (const Ipp32f* pSrc, int srcLen, Ipp32f* pDst, int* pDstLen,
int factor, int* pPhase  );
IppStatus ippsSampleUp_64f (const Ipp64f* pSrc, int srcLen, Ipp64f* pDst, int* pDstLen,
int factor, int* pPhase  );
IppStatus ippsSampleUp_16sc (const Ipp16sc* pSrc, int srcLen, Ipp16sc* pDst, int*
pDstLen, int factor, int* pPhase  );
IppStatus ippsSampleUp_32fc (const Ipp32fc* pSrc, int srcLen, Ipp32fc* pDst, int*
pDstLen, int factor, int* pPhase  );
IppStatus ippsSampleUp_64fc (const Ipp64fc* pSrc, int srcLen, Ipp64fc* pDst, int*
pDstLen, int factor, int* pPhase  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                        Pointer to the source array (the signal to be up-sampled).

srcLen                      Number of samples in the source array  pSrc.

pDst                        Pointer to the destination array.

pDstLen                     Pointer to the length of the destination array pDst.

factor                      Factor by which the signal is up-sampled. That is, factor -1 zeros
                            are inserted after each sample of the source array pSrc.
pPhase                      Pointer to the input phase value which determines where each
                            sample from  pSrc lies within each output block of factor samples in
                            pDst . The value of pPhase is required to be in the range [0;
                            factor -1].

Description
This function up-samples the srcLen-length source array pSrc by factor factor with phase pPhase, and
stores the result in the array pDst, ignoring its length value by the pDstLen address.
Up-sampling inserts factor-1 zeros between each sample of pSrc. The pPhase argument determines where
each sample from the input array lies within each output block of factor samples. The value of pPhase is
required to be in the range [0; factor-1].

   208
---------------------Page 209---------------------

                                                                         Essential Functions  5 

For example, if the input phase is 0, then every factor samples of the destination array begin with the
corresponding source array sample, the other factor-1 samples are equal to 0. The length of the
destination array is stored by the pDstLen address.
The pPhase value is the phase of an source array sample. It is also a returned output phase which can be
used as an input phase for the first sample in the next block to process. Use pPhase for block mode
processing to get a continuous output signal.
The ippsSampleUp functionality can be described as follows:

pDst[factor* n + phase] = pSrc[n], 0    ≤ n < srcLen

pDst[factor* n + m] = 0, 0 ≤ n < srcLen, 0  ≤ m< factor, m ≠ phase
pDstLen = factor * srcLen   .

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error if the pDst, pSrc, pDstLen, or pPhase pointer
                                 is NULL.
ippStsSizeErr                    Indicates an error if srcLen is less than or equal to 0.

ippStsSampleFactorErr            Indicates an error if factor is less than or equal to 0.

ippStsSamplePhaseErr             Indicates an error when pPhase is negative, or bigger than or
                                 equal to factor.

SampleDown
Down-samples a signal, conceptually decreasing its
sampling rate by an integer factor.

Syntax
IppStatus ippsSampleDown_16s(const Ipp16s* pSrc, int srcLen, Ipp16s* pDst, int*
pDstLen, int factor, int* pPhase  );
IppStatus ippsSampleDown_32f(const Ipp32f* pSrc, int srcLen, Ipp32f* pDst, int*
pDstLen, int factor, int* pPhase  );
IppStatus ippsSampleDown_64f(const Ipp64f* pSrc, int srcLen, Ipp64f* pDst, int*
pDstLen, int factor, int* pPhase  );
IppStatus ippsSampleDown_16sc(const Ipp16sc* pSrc, int srcLen, Ipp16sc* pDst, int*
pDstLen, int factor, int* pPhase  );
IppStatus ippsSampleDown_32fc(const Ipp32fc* pSrc, int srcLen, Ipp32fc* pDst, int*
pDstLen, int factor, int* pPhase  );
IppStatus ippsSampleDown_64fc(const Ipp64fc* pSrc, int srcLen, Ipp64fc* Dst, int*
pDstLen, int factor, int* pPhase  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                         209
---------------------Page 210---------------------

 5    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

pSrc                          Pointer to the source array holding the samples to be down-
                              sampled.
srcLen                        Number of samples in the input array  pSrc .

pDst                          Pointer to the destination array.

pDstLen                       Pointer to the length of the destination array pDst.

factor                        Factor by which the signal is down-sampled. That is,  factor - 1
                              samples are discarded from every block of  factor  samples in pSrc .
pPhase                        Pointer to the input phase value that determines which of the
                              samples within each block of factor  samples from  pSrc  is not
                              discarded and copied to pDst . The value of pPhase is required to be
                              in the range [0; factor-1].

Description
This function down-samples the srcLen-length source array pSrc by factor factor with phase pPhase, and
stores the result in the array pDst, ignoring its length value by the pDstLen address.
Down-sampling discards factor - 1 samples from pSrc, copying one sample from each block of factor
samples from pSrc to pDst. The pPhase argument determines which of the samples in each block is not
discarded and where it lies within each input block of factor samples. The value of pPhase is required to be
in the range [0; factor-1]. The length of the destination array is stored by the pDstLen address.
The pPhase value is the phase of an source array sample. It is also a returned output phase which can be
used as an input phase for the first sample in the next block to process. Use pPhase for block mode
processing to get a continuous output signal.
You can use the FIR multi-rate filter to combine filtering and resampling, for example, for antialiasing
filtering before the sub-sampling procedure.
The ippsSampleDown  functionality can be described as follows:
pDstLen= (srcLen+ factor - 1 - phase)/factor

pDst[n]= pSrc[factor * n + phase]    , 0 ≤ n < pDstLen
phase = (factor+ phase - srcLen %factor)%factor      .

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pDst, pSrc, pDstLen , or pPhase
                                   pointer is NULL.
ippStsSizeErr                      Indicates an error when  srcLen is less than or equal to 0.

ippStsSampleFactorErr              Indicates an error when  factor is less than or equal to 0.

ippStsSamplePhaseErr               Indicates an error when  pPhase is negative, or bigger than or
                                   equal to factor.

Example
The example below shows how to use the function ippsSampleDown.
void sampling( void ) {
      Ipp16s x[8] = { 1,2,3,4,5,6,7,8 };
      Ipp16s y[8] = {9,10,11,12,13,14,15,16}, z[8];
      int dstLen1, dstLen2, phase = 2;

   210
---------------------Page 211---------------------

                                                                         Essential Functions  5 
      IppStatus st = ippsSampleDown_16s(x, 8, z, &dstLen1, 3, &phase);
      st = ippsSampleDown_16s(y, 8, z+dstLen1, &dstLen2, 3, &phase);
      printf_16s(“down-sampling =”, z, dstLen1+dstLen2, st); 
}
Output:
down-sampling = 3 6 9 12 15

                                                                                         211
---------------------Page 212---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Filtering Functions                                                                     6

This chapter describes the Intel®     functions that perform convolution and correlation operations, as well as
linear and non-linear filtering.

Convolution and Correlation Functions
Convolution is an operation used to define an output signal from any linear time-invariant (LTI) processor in
response to any input signal.
The correlation functions described in this section estimate either the auto-correlation of a source vector or
the cross-correlation of two vectors.

Special Arguments
Some Convolution and Correlation functions described in this section have two implementations of the
algorithm:
•     For small data size, function processes data as described by the formula
•     For big data size, function uses FFT-inherited algorithms
The optimal algorithm is selected automatically according to the input data size. You can manually choose
which algorithm to use by passing one of the following predefined values to the algType parameter of the
function:
ippAlgAuto                    Select the optimal algorithm automatically.
ippAlgDirect                  Use direct algorithm as described by the formula.
ippAlgFFT                     Use FFT-based algorithm implementation.
These values are declared in the IppAlgType enumerator.
Several functions support normalization of the output data. You can choose which normalization to apply by
passing one of the following values to the function:
ippsNormNone                  No normalization (default).
ippsNormA                     Biased normalization.
ippsNormB                     Unbiased normalization.
These values are declared in the IppsNormOp enumerator.

See Also
Enumerators

AutoCorrNormGetBufferSize
Computes the size of the work buffer for the
ippsAutoCorrNorm   function.

Syntax
IppStatus ippsAutoCorrNormGetBufferSize (int srcLen, int dstLen, IppDataType dataType,
IppEnum algType, int* pBufferSize     );

   212
---------------------Page 213---------------------

                                                                              Filtering Functions  6 

Include Files
ipps.h

Parameters

srcLen                        Number of elements in the source vector.

dstLen                        Number of elements in the destination vector (length of auto-correlation).

dataType                      Data type for auto-correlation. Possible values are Ipp32f, Ipp32fc,
                              Ipp64f , or Ipp64fc.

algType                       Bit-field mask for the algorithm type definition. Possible values are the
                              results of composition of the IppAlgType and IppsNormOp values.

pBufferSize                   Pointer to the size of the work buffer.

Description
The ippsAutoCorrNormGetBufferSize     function computes the size in bytes of the external work buffer
needed for the function that performs auto-correlation. The result is stored in the pBufferSize parameter.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when  pBufferSize  is NULL.

ippStsSizeErr                      Indicates an error when  srcLen or dstLen  is less than, or equal
                                   to zero.
ippStsAlgTypeErr                   Indicates an error when:
                                   •     the result of the bitwise AND operation between the algType and
                                      ippAlgMask  differs from the ippAlgAuto, ippAlgDirect, or
                                      ippAlgFFT  values;
                                   •     the result of the bitwise AND operation between the algType and
                                      ippsNormMask  differs from the ippsNormNone, ippsNormA, or
                                      ippsNormB  values.

ippStsDataTypeErr                  Indicates an error when the dataType value differs from the Ipp32f,
                                   Ipp32fc , Ipp64f, or Ipp64fc.

See Also
Enumerators
Special Arguments
AutoCorrNorm Calculates normal, biased, and unbiased auto-correlation of a vector.

AutoCorrNorm
Calculates normal, biased, and unbiased auto-
correlation of a vector.

Syntax
IppStatus ippsAutoCorrNorm_32f (const Ipp32f* pSrc, int srcLen, Ipp32f* pDst, int
dstLen, IppEnum algType, Ipp8u* pBuffer     );

                                                                                             213
---------------------Page 214---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsAutoCorrNorm_64f (const Ipp64f* pSrc, int srcLen, Ipp64f* pDst, int
dstLen, IppEnum algType, Ipp8u* pBuffer      );
IppStatus ippsAutoCorrNorm_32fc (const Ipp32fc* pSrc, int srcLen, Ipp32fc* pDst, int
dstLen, IppEnum algType, Ipp8u* pBuffer      );
IppStatus ippsAutoCorrNorm_64fc (const Ipp64fc* pSrc, int srcLen, Ipp64fc* pDst, int
dstLen, IppEnum algType, Ipp8u* pBuffer      );

Include Files
ipps.h

Parameters

pSrc                          Pointer to the source vector.

srcLen                        Number of elements in the source vector.

pDst                          Pointer to the destination vector. This vector stores the calculated auto-
                              correlation of the source vector.

dstLen                        Number of elements in the destination vector (length of auto-correlation).

algType                       Bit-field mask for the algorithm type definition. Possible values are the
                              results of composition of the IppAlgType and IppsNormOp values.

pBuffer                       Pointer to the buffer for internal calculations.

Description
Before using these functions, you need to compute the size of the work buffer using the
ippsAutoCorrNormGetBufferSize     function.
These functions calculate the normalized auto-correlation of the pSrc vector of srcLen length and store the
results in the pDst vector of dstLen length. The result vector pDst is calculated by the following equations:
 

 
where
 

   214
---------------------Page 215---------------------

                                                                            Filtering Functions  6 

 

     NOTE
     The auto-correlation is computed for positive lags only. Auto-correlation for a negative lag is a
     complex conjugate of the auto-correlation for the equivalent positive lag.

Return Values

ippStsNoErr                       Indicates no error.

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

ippStsSizeErr                     Indicates an error when  srcLen or dstLen  is less than, or equal
                                  to zero.
ippStsAlgTypeErr                  Indicates an error when:
                                  •     the result of the bitwise AND operation between the algType and
                                     ippAlgMask  differs from the ippAlgAuto, ippAlgDirect, or
                                     ippAlgFFT  values;
                                  •     the result of the bitwise AND operation between the algType and
                                     ippsNormMask   differs from the ippsNormNone, ippsNormA, or
                                     ippsNormB  values.

Example
The code example below demonstrates how to use the ippsAutoCorrNormGetBufferSize   and
ippsAutoCorrNorm   functions.
IppStatus AutoCorrNormExample (void) {
   IppStatus status;
   const int srcLen = 5, dstLen = 10;
   Ipp32f pSrc[srcLen] = {0.2f, 3.1f, 2.0f, 1.2f, -1.1f}, pDst[dstLen];
   IppEnum funCfg = (IppEnum)(ippAlgAuto|ippsNormB);
   int bufSize = 0;
   Ipp8u *pBuffer;

   status = ippsAutoCorrNormGetBufferSize(srcLen, dstLen, ipp32f, funCfg, &bufSize);

   if ( status != ippStsNoErr )
      return status;

   pBuffer = ippsMalloc_8u( bufSize );

   status = ippsAutoCorrNorm_32f(pSrc, srcLen, pDst, dstLen, funCfg, pBuffer);

   printf_32f("pDst", pDst, dstLen);

   ippsFree( pBuffer );
   return status;
}

                                                                                            215
---------------------Page 216---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

The result is as follows:
pDst -> 3.3 2.0 0.6 -1.6 -0.2 0.0 0.0 0.0 0.0 0.0

See Also
Enumerators
Special Arguments
AutoCorrNormGetBufferSize Computes the size of the work buffer for the     ippsAutoCorrNorm
function.

CrossCorrNormGetBufferSize
Computes the size of the work buffer for the
ippsCrossCorrNorm   function.

Syntax
IppStatus ippsCrossCorrNormGetBufferSize (int src1Len, int src2Len, int dstLen, int
lowLag, IppDataType dataType, IppEnum algType, int* pBufferSize         );

Include Files
ipps.h

Parameters

src1Len                       Number of elements in the first source vector.

src2Len                       Number of elements in the second source vector.

dstLen                        Number of elements in the destination vector (length of cross-correlation).

lowLag                        Lower value of the range of lags at which the correlation is computed.

dataType                      Data type for cross-correlation. Possible values are Ipp32f, Ipp32fc,
                              Ipp64f , or Ipp64fc.

algType                       Bit-field mask for the algorithm type definition. Possible values are the
                              results of composition of the IppAlgType and IppsNormOp values.

pBufferSize                   Pointer to the size of the work buffer.

Description
The ippsCrossCorrNormGetBufferSize     function computes the size in bytes of the external work buffer
needed for the function that performs cross-correlation. The result is stored in the pBufferSize parameter.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when  pBufferSize  is NULL.

ippStsSizeErr                      Indicates an error when the length of the vector is negative, or
                                   equal to zero.
ippStsAlgTypeErr                   Indicates an error when:
                                   •     the result of the bitwise AND operation between the algType and
                                      ippAlgMask  values differs from the ippAlgAuto, ippAlgDirect,
                                      or ippAlgFFT  values.

   216
---------------------Page 217---------------------

                                                                           Filtering Functions  6 

                                  •     the result of the bitwise AND operation between the algType and
                                    ippsNormMask   values differs from the ippsNormNone, ippsNormA,
                                    or ippsNormB  values.

ippStsDataTypeErr                 Indicates an error when the dataType value differs from the Ipp32f,
                                  Ipp32fc , Ipp64f, or Ipp64fc.

See Also
Enumerators
CrossCorrNorm Calculates the cross-correlation of two vectors.
Special Arguments

CrossCorrNorm
Calculates the cross-correlation of two vectors.

Syntax
IppStatus ippsCrossCorrNorm_32f (const Ipp32f* pSrc1, int src1Len, const Ipp32f* pSrc2,
int src2Len, Ipp32f* pDst, int dstLen, int lowLag, IppEnum algType, Ipp8u* pBuffer         );
IppStatus ippsCrossCorrNorm_64f (const Ipp64f* pSrc1, int src1Len, const Ipp64f* pSrc2,
int src2Len, Ipp64f* pDst, int dstLen, int lowLag, IppEnum algType, Ipp8u* pBuffer         );
IppStatus ippsCrossCorrNorm_32fc (const Ipp32fc* pSrc1, int src1Len, const Ipp32fc*
pSrc2, int src2Len, Ipp32fc* pDst, int dstLen, int lowLag, IppEnum algType, Ipp8u*
pBuffer);
IppStatus ippsCrossCorrNorm_64fc (const Ipp64fc* pSrc1, int src1Len, const Ipp64fc*
pSrc2, int src2Len, Ipp64fc* pDst, int dstLen, int lowLag, IppEnum algType, Ipp8u*
pBuffer);

Include Files
ipps.h

Parameters

pSrc1                        Pointer to the first source vector.

src1Len                      Number of elements in the first source vector.

pSrc2                        Pointer to the second source vector.

src2Len                      Number of elements in the second source vector.

pDst                         Pointer to the destination vector. This vector stores the calculated cross-
                             correlation of the pSrc1 and pSrc2 vectors.

dstLen                       Number of elements in the destination vector. This value determines the
                             range of lags at which the cross-correlation is calculated.

algType                      Bit-field mask for the algorithm type definition. Possible values are the
                             results of composition of the IppAlgType and IppsNormOp values.

pBuffer                      Pointer to the buffer for internal calculations.

                                                                                           217
---------------------Page 218---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Description
These functions calculate the cross-correlation of the pSrc1 vector and the pSrc2 vector, and store the
results in the pDst vector. The result vector pDst is calculated by the following equations:
 

 
where
 

 
 

 
Before using this function, you need to compute the size of the work buffer using the
ippsCrossCorrNormGetBufferSize      function.

Return Values

ippStsNoErr                         Indicates no error.

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

ippStsSizeErr                       Indicates an error when the length of a vector is less than, or
                                    equal to zero.
ippStsAlgTypeErr                    Indicates an error when:
                                    •     the result of the bitwise AND operation between the algType and
                                       ippAlgMask   differs from the ippAlgAuto, ippAlgDirect , or
                                       ippAlgFFT   values.
                                    •     the result of the bitwise AND operation between the algType and
                                       ippsNormMask   differs from the ippsNormNone, ippsNormA , or
                                       ippsNormB   values.

   218
---------------------Page 219---------------------

                                                                          Filtering Functions  6 

Example
The code example below demonstrates how to use the ippsCrossCorrNormGetBufferSize and
ippsCrossCorrNorm  functions.
IppStatus CrossCorrNormExample (void) {
   IppStatus status;
   const int src1Len=5, src2Len=7, dstLen=16;
   int lowLag = -5;
   Ipp32f pSrc1[src1Len] = {1.f,1.f,1.f,1.f,1.f}, pSrc2[src2Len] = {1.f,1.f,1.f,1.f,1.f,1.f,1.f}, 
pDst[dstLen];
   IppEnum funCfgNormNo = (IppEnum)(ippAlgAuto|ippsNormNone);
   IppEnum funCfgNormA = (IppEnum)(ippAlgAuto|ippsNormA);
   IppEnum funCfgNormB = (IppEnum)(ippAlgAuto|ippsNormB);
   int bufSizeNo=0, bufSizeA=0, bufSizeB=0, bufSizeMax=0;
   Ipp8u *pBuffer;

   status = ippsCrossCorrNormGetBufferSize(src1Len, src2Len, dstLen, -5, ipp32f, funCfgNormNo, 
&bufSizeNo);
   if ( status != ippStsNoErr ) return status;
   status = ippsCrossCorrNormGetBufferSize(src1Len, src2Len, dstLen, -5, ipp32f, funCfgNormA, 
&bufSizeA);
   if ( status != ippStsNoErr ) return status;
   status = ippsCrossCorrNormGetBufferSize(src1Len, src2Len, dstLen, -5, ipp32f, funCfgNormB, 
&bufSizeB);
   if ( status != ippStsNoErr ) return status;

   bufSizeMax = IPP_MAX(bufSizeNo, IPP_MAX(bufSizeA, bufSizeB));// get max buffer size

   pBuffer = ippsMalloc_8u( bufSizeMax );

   status = ippsCrossCorrNorm_32f(pSrc1, src1Len, pSrc2, src2Len, pDst, dstLen, lowLag, funCfgNormNo, 
pBuffer);
   printf_32f("pDst_NormNone", pDst, dstLen);

   status = ippsCrossCorrNorm_32f(pSrc1, src1Len, pSrc2, src2Len, pDst, dstLen, lowLag, funCfgNormA, 
pBuffer);
   printf_32f("pDst_NormA", pDst, dstLen);

   status = ippsCrossCorrNorm_32f(pSrc1, src1Len, pSrc2, src2Len, pDst, dstLen, lowLag, funCfgNormB, 
pBuffer);
   printf_32f("pDst_NormB", pDst, dstLen);

   ippsFree( pBuffer );
   return status;
}

The result is as follows:
pDst_NormNone -> 0.0 1.0 2.0 3.0 4.0 5.0 5.0 5.0 4.0 3.0 2.0 1.0 0.0 0.0 0.0 0.0
pDst_NormA    -> 0.0 0.2 0.4 0.6 0.8 1.0 1.0 1.0 0.8 0.6 0.4 0.2 0.0 0.0 0.0 0.0
pDst_NormB    -> 0.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 0.0 0.0 0.0 0.0

See Also
Enumerators
Special Arguments
CrossCorrNormGetBufferSize Computes the size of the work buffer for the ippsCrossCorrNorm
function.

                                                                                         219
---------------------Page 220---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ConvolveGetBufferSize
Computes the size of the work buffer for the
ippsConvolve  function.

Syntax
IppStatus ippsConvolveGetBufferSize (int src1Len, int src2Len, IppDataType dataType,
IppEnum algType, int* pBufferSize    );

Include Files
ipps.h

Parameters

src1Len                       Number of elements in the first source vector.

src2Len                       Number of elements in the second source vector.

dataType                      Data type for convolution. Possible values are Ipp32f and Ipp64f.

algType                       Bit-field mask for the algorithm type definition. Possible values are listed in
                              the IppAlgType  enumerator.

pBufferSize                   Pointer to the size of the work buffer.

Description
The ippsConvolveGetBufferSize    function computes the size, in bytes, of the external work buffer needed
for the functions that perform convolution operations. The result is stored in the pBufferSize parameter.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when  pBufferSize  is NULL.

ippStsSizeErr                      Indicates an error when the length of the vector is negative, or
                                   equal to zero.
ippStsAlgTypeErr                   Indicates an error when the result of the bitwise AND operation
                                   between the  algType  and ippAlgMask  differs from the
                                   ippAlgAuto , ippAlgDirect , or ippAlgFFT  values.
ippStsDataTypeErr                  Indicates an error when the dataType value differs from the Ipp32f
                                   or Ipp64f.

See Also
Enumerators
Special Arguments
Convolve Performs a finite linear convolution of two vectors.

Convolve
Performs a finite linear convolution of two vectors.

   220
---------------------Page 221---------------------

                                                                              Filtering Functions  6 

Syntax
IppStatus ippsConvolve_32f (const Ipp32f* pSrc1, int src1Len, const Ipp32f* pSrc2, int
src2Len, Ipp32f* pDst, IppEnum algType, Ipp8u* pBuffer        );
IppStatus ippsConvolve_64f (const Ipp64f* pSrc1, int src1Len, const Ipp64f* pSrc2, int
src2Len, Ipp64f* pDst, IppEnum algType, Ipp8u* pBuffer        );

Include Files
ipps.h

Parameters

pSrc1                         Pointer to the first source vector.

src1Len                       Number of elements in the first source vector.

pSrc2                         Pointer to the second source vector.

src2Len                       Number of elements in the second source vector.

pDst                          Pointer to the destination vector. This vector stores the result of the
                              convolution of the pSrc1 and pSrc2 vectors.

algType                       Bit-field mask for the algorithm type definition. Possible values are listed in
                              the IppAlgType  enumerator.

pBuffer                       Pointer to the buffer for internal calculations.

Description
These functions perform the finite linear convolution of the pSrc1 and pSrc2 vectors. The src1Len elements
of the pSrc1 vector are convolved with the src2Len elements of the pSrc2 vector. The result of the
convolution is stored in the pDst vector with the length equal to src1Len+src2Len-1. The result vector
pDst is calculated by the following equations:
 

 
where
• pSrc1[i]=0  , if i ≥ src1Len
• pSrc2[j]=0  , if j ≥ src2Len

Before using this function, you need to compute the size of the work buffer using the
ippsConvolveGetBufferSize    function.

Return Values

ippStsNoErr                        Indicates no error.

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

                                                                                              221
---------------------Page 222---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsSizeErr                    Indicates an error when the length of a vector is less than, or
                                 equal to zero.
ippStsAlgTypeErr                 Indicates an error when the result of the bitwise AND operation
                                 between  algType and ippAlgMask  differs from the ippAlgAuto,
                                 ippAlgDirect , or ippAlgFFT values.

Example
The code example below demonstrates how to use the ippsConvolveGetBufferSize and
ippsConvolve_32f  functions.
IppStatus ConvolveExample (void) {
   IppStatus status;
   const int src1Len = 5, src2Len = 2, dstLen = src1Len+src2Len-1;
   Ipp32f pSrc1[src1Len] = {-2.f,0.f,1.f,-1.f,3.f}, pSrc2[src2Len]={0.f,1.f}, pDst[dstLen];
   IppEnum funCfg = (IppEnum)(ippAlgAuto);
   int bufSize = 0;
   Ipp8u *pBuffer;

   status = ippsConvolveGetBufferSize(src1Len, src2Len, ipp32f, funCfg, &bufSize);

   if ( status != ippStsNoErr )
      return status;

   pBuffer = ippsMalloc_8u( bufSize );

   status = ippsConvolve_32f(pSrc1, src1Len, pSrc2, src2Len, pDst, funCfg, pBuffer);

   printf_32f("pDst", pDst, dstLen);

   ippsFree( pBuffer );
   return status;
}

The result is as follows:
pDst -> 0.0 -2.0 0.0 1.0 -1.0 3.0

See Also
Enumerators
Special Arguments
ConvolveGetBufferSize Computes the size of the work buffer for the ippsConvolve function.

Conv
DEPRECATED. Performs finite, linear convolution of
two vectors.

Syntax
IppStatus ippsConv_32f(const Ipp32f* pSrc1, int src1Len, const Ipp32f* pSrc2, int
src2Len, Ipp32f* pDst );
IppStatus ippsConv_64f(const Ipp64f* pSrc1, int src1Len, const Ipp64f* pSrc2, int
src2Len, Ipp64f* pDst );
IppStatus ippsConv_16s_Sfs(const Ipp16s* pSrc1, int src1Len, const Ipp16s* pSrc2, int
src2Len, Ipp16s* pDst, int scaleFactor   );

Include Files
ipps.h

   222
---------------------Page 223---------------------

                                                                             Filtering Functions  6 

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2                 Pointers to the source vectors.

src1Len                      Number of elements in the vector   pSrc1 .

src2Len                      Number of elements in the vector   pSrc2 .

pDst                         Pointer to the destination vector.

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
The ippsAutoCorr  function is deprecated. For information about the functions that you should use instead,
see the table below.

 Deprecated Function                               Use Instead
 ippsConv_32f                                     ippsConvolve_32f
 ippsConv_64f                                     ippsConvolve_64f
 ippsConv_16s_Sfs                                 ippsConvert_16s32f    and
                                                  ippsConvolve_32f

For more information about the deprecation process use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function performs finite linear convolution of two sequences. The src1Len elements of the vector pSrc1
is convolved with the src2Len elements of the vector pSrc2 to produce an (src1Len + src2Len - 1)-length
vector pDst. The result of the convolution is defined as follows:
 

 
Here pSrc1[i] = 0 , if i ≥ src1Len, and pSrc2[j]= 0, if j ≥ src2Len.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pDst  or pSrc pointer is NULL.

ippStsSizeErr                     Indicates an error when  src1Len  or src2Len is less than, or
                                  equal to 0.
ippStsMemAllocErr                 Indicates an error when there is not enough memory for
                                  internal buffers.

                                                                                            223
---------------------Page 224---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Example
The example below shows the code for the convolution of two vectors using ippsConv_16s_Sfs function.
IppStatus convolution(void) {
      Ipp16s x[5] = {-2,0,1,-1,3}, h[2] = {0,1}, y[6];
      IppStatus st = ippsConv_16s_Sfs(x, 5, h, 2, y, 0);
      printf_16s(“conv =”, y, 6, st);
      return st; 
}

Output:
conv = 0 -2 0 1 -1 3
Matlab* Analog: 
                 >> x = [-2,0,1,-1,3]; h = [0,1]; y = conv(x,h)

ConvBiased
Computes the specified number of elements of the full
finite linear convolution of two vectors.

Syntax
IppStatus ippsConvBiased_32f(const Ipp32f* pSrc1, int src1Len, const Ipp32f* pSrc2, int
src2Len, Ipp32f* pDst, int dstLen, int bias     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1, pSrc2                 Pointers to the two vectors to be convolved.

src1Len                      Number of elements in the vector   pSrc1.

src2Len                      Number of elements in the vector   pSrc2.

pDst                         Pointer to the vector pDst. This vector stores the result of the
                             convolution.
dstLen                       Number of elements in the vector   pDst.

bias                         Parameter that specifes the starting element of the convolution.

Description
This function computes dstLen elements of finite linear convolution of two specified vectors pSrc1 and
pSrc2 starting with an element that is specified by the bias. The result is stored in the vector pDst.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pDst or pSrc pointer is NULL.

   224
---------------------Page 225---------------------

                                                                            Filtering Functions  6 

ippStsSizeErr                     Indicates an error when src1Len  or src2Len is less than or
                                  equal to 0.

Example
The example below shows how to call the function ippsConvBiased.
void func_convbiased() 
{    
    Ipp32f pSrc1[5] = {1.1, -2.0, 3.5, 2.2, 0.0};
    Ipp32f pSrc2[4] = {0.0, 0.2, 2.5, -1.0};
    const int len = 10;
    Ipp32f pDst[len];
    int bias = 1;

    ippsZero_32f(pDst, len);
    ippsConvBiased_32f(pSrc1, 5, &pSrc2[1], 3, pDst, len, bias); 
}

Result:
        pDst -> 0.2  2.3  -4.3  9.2  5.5  0.0  0.0  0.0  0.0  0.0

ConvCyclic
DEPRECATED. Performs cyclic convolution of two
sequences of the fixed size.

Syntax
IppStatus ippsConvCyclic8x8_32f(const Ipp32f* x, const Ipp32f* h, Ipp32f* y        );
IppStatus ippsConvCyclic4x4_32f32fc(const Ipp32f* x, const Ipp32fc* h, Ipp32fc* y         );
IppStatus ippsConvCyclic8x8_16s_Sfs(const Ipp16s* x, const Ipp16s* h, Ipp16s* y, int
scaleFactor );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

x, h                         Pointers to the source vectors.

y                            Pointer to the destination vector that stores the result of
                             convolution.
scaleFactor                  Scale factor, refer to Integer Scaling.

Description
The function ippsConvCyclic is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details:http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function performs cyclic convolution of two sequences of the fixed size.

                                                                                           225
---------------------Page 226---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                    Indicates no error.

AutoCorr
DEPRECATED. Estimates normal, biased, and unbiased
auto-correlation of a vector and stores the result in a
second vector.

Syntax
IppStatus ippsAutoCorr_32f(const Ipp32f* pSrc, int srcLen, Ipp32f* pDst, int dstLen  );
IppStatus ippsAutoCorr_NormA_32f(const Ipp32f* pSrc, int srcLen, Ipp32f* pDst, int
dstLen);
IppStatus ippsAutoCorr_NormB_32f(const Ipp32f* pSrc, int srcLen, Ipp32f* pDst, int
dstLen);
IppStatus ippsAutoCorr_64f(const Ipp64f* pSrc, int srcLen, Ipp64f* pDst, int dstLen  );
IppStatus ippsAutoCorr_NormA_64f(const Ipp64f* pSrc, int srcLen, Ipp64f* pDst, int
dstLen);
IppStatus ippsAutoCorr_NormB_64f(const Ipp64f* pSrc, int srcLen, Ipp64f* pDst, int
dstLen);
IppStatus ippsAutoCorr_32fc(const Ipp32fc* pSrc, int srcLen, Ipp32fc* pDst, int
dstLen);
IppStatus ippsAutoCorr_NormA_32fc(const Ipp32fc* pSrc, int srcLen, Ipp32fc* pDst, int
dstLen);
IppStatus ippsAutoCorr_NormB_32fc(const Ipp32fc* pSrc, int srcLen, Ipp32fc* pDst, int
dstLen);
IppStatus ippsAutoCorr_64fc(const Ipp64fc* pSrc, int srcLen, Ipp64fc* pDst, int
dstLen);
IppStatus ippsAutoCorr_NormA_64fc(const Ipp64fc* pSrc, int srcLen, Ipp64fc* pDst, int
dstLen);
IppStatus ippsAutoCorr_NormB_64fc(const Ipp64fc* pSrc, int srcLen, Ipp64fc* pDst, int
dstLen);
IppStatus ippsAutoCorr_16s_Sfs(const Ipp16s* pSrc, int srcLen, Ipp16s* pDst, int
dstLen, int scaleFactor);
IppStatus ippsAutoCorr_NormA_16s_Sfs( const Ipp16s* pSrc, int srcLen, Ipp16s* pDst, int
dstLen, int scaleFactor);
IppStatus ippsAutoCorr_NormB_16s_Sfs(const Ipp16s* pSrc, int srcLen, Ipp16s* pDst, int
dstLen, int scaleFactor);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

  226
---------------------Page 227---------------------

                                                                          Filtering Functions  6 

Parameters

pSrc                        Pointer to the source vector.

srcLen                      The number of elements in the source vector.

pDst                        Pointer to the destination vector, which stores the estimated auto-
                            correlation results of the source vector.
dstLen                      The number of elements in the destination vector (length of auto-
                            correlation).
scaleFactor                 Scale factor, refer to Integer Scaling.

Description
The ippsAutoCorr function is deprecated. For information about the functions that you should use instead,
see the table below.

 Deprecated Function                 Use Instead

 ippsAutoCorr_32f                   ippsAutoCorrNorm_32f   with algType=ippsNormNone

 ippsAutoCorr_NormA_32f             ippsAutoCorrNorm_32f   with algType=ippsNormA

 ippsAutoCorr_NormB_32f             ippsAutoCorrNorm_32f   with algType=ippsNormB

 ippsAutoCorr_64f                   ippsAutoCorrNorm_64f   with algType=ippsNormNone

 ippsAutoCorr_NormA_64f             ippsAutoCorrNorm_64f   with algType=ippsNormA

 ippsAutoCorr_NormB_64f             ippsAutoCorrNorm_64f   with algType=ippsNormB

 ippsAutoCorr_32fc                  ippsAutoCorrNorm_32fc   with algType=ippsNormNone

 ippsAutoCorr_NormA_32fc            ippsAutoCorrNorm_32cf   with algType=ippsNormA

 ippsAutoCorr_NormB_32fc            ippsAutoCorrNorm_32fc   with algType=ippsNormB

 ippsAutoCorr_64fc                  ippsAutoCorrNorm_64fc   with algType=ippsNormNone

 ippsAutoCorr_NormA_64fc            ippsAutoCorrNorm_64fc   with algType=ippsNormA

 ippsAutoCorr_NormB_64fc            ippsAutoCorrNorm_64fc   with algType=ippsNormB

 ippsAutoCorr_16s_Sfs               ippsConvert_16s32f   and
                                    ippsAutoCorrNorm_32f   with algType=ippsNormNone

 ippsAutoCorr_NormA_16s_Sfs         ippsConvert_16s32f   and
                                    ippsAutoCorrNorm_32f   with algType=ippsNormA

 ippsAutoCorr_NormB_16s_Sfs         ippsConvert_16s32f   and
                                    ippsAutoCorrNorm_32f   with algType=ippsNormB

For more information about the deprecation process use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function estimates normal auto-correlation of the srcLen-length source vector pSrc and stores the
results in the dstLen-length vector pDst. Function flavors ippsAutoCorr_NormA and
ippsAutoCorr_NormB  compute biased and unbiased auto-correlation of the source vector, respectively. The
resulting vector pDst is defined by the following equations:

                                                                                         227
---------------------Page 228---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

 

 
where
 

 

      NOTE
      The auto-correlation estimates are computed only for positive lags, since the auto-correlation for a
      negative lag value is the complex conjugate of the auto-correlation for the equivalent positive lag.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the  pSrc or pDst  pointer is NULL.

ippStsSizeErr                      Indicates an error when  srcLen  or dstLen is less than or equal
                                   to 0.

Example
The example below shows how to call the function ippsAutoCorr_NormB_32f.
void func_autocorr() 
{
    Ipp32f pSrc[5] = {0.2, 3.1, 2.0, 1.2, -1.1};
    const int dstLen = 10;
    Ipp32f pDst[dstLen];
         
    ippsAutoCorr_NormB_32f(pSrc, 5, pDst, dstLen); 
}
Result:
pDst -> 3.3 2.0 0.6 -1.6 -0.2 0.0 0.0 0.0 0.0 0.0

See Also
CrossCorr Estimates the cross-correlation of two vectors.
AutoCorrNorm Calculates normal, biased, and unbiased auto-correlation of a vector.

   228
---------------------Page 229---------------------

                                                                          Filtering Functions  6 

CrossCorr
Estimates the cross-correlation of two vectors.

Syntax
IppStatus ippsCrossCorr_16s_Sfs(const Ipp16s* pSrc1, int src1Len, const Ipp16s* pSrc2,
int src2Len, Ipp16s* pDst, int dstLen, int lowLag, int scaleFactor     );
IppStatus ippsCrossCorr_16s64s(const Ipp16s* pSrc1, int src1Len, const Ipp16s* pSrc2,
int src2Len, Ipp64s* pDst, int dstLen, int lowLag    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc1                       Pointer to the first source vector.

src1Len                     Number of elements in the vector pSrc1.

pSrc2                       Pointer to the second source vector.

src2Len                     Number of elements in the vector pSrc2.

pDst                        Pointer to the vector which stores the results of the estimated cross-
                            correlation of the vectors pSrc1 and pSrc2.
dstLen                      Number of elements in the vector pDst, which determines the range
                            of lags at which the correlation estimates are computed.
lowLag                      Lower value of the range of lags at which the correlation estimates
                            are computed.
scaleFactor                 Scale factor, refer to Integer Scaling.

Description
The following flavors of the ippsCrossCorr function are deprecated. For information about the functions
that you should use instead, see the table below.

 Deprecated Function                            Use Instead
 ippsCrossCorr_32f                              ippsCrossCorrNorm_32f   with
                                                algType =ippsNormNone
 ippsCrossCorr_64f                              ippsCrossCorrNorm_64f   with
                                                algType =ippsNormNone
 ippsCrossCorr_32fc                             ippsCrossCorrNorm_32fc   with
                                                algType =ippsNormNone
 ippsCrossCorr_64fc                             ippsCrossCorrNorm_64fc   with
                                                algType =ippsNormNone
 ippsCrossCorr_16s64s                           This function is obsolete.

                                                                                        229
---------------------Page 230---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

For more information about the deprecation process use the following link: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function estimates cross-correlation of the src1Len elements of the vector pSrc1 and the src2Len
elements of the vector pSrc2, and stores the results in the vector pDst. The resulting vector pDst is defined
by the equation:
 

 
,
where 0 ≤ n < dstLen, and
 

 

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pSrc1  or pSrc2 pointer is NULL.

ippStsSizeErr                     Indicates an error when  src1Len  or src2Len is less than, or
                                  equal to 0.

Example
The example below shows how to use the function ippsCrossCorr.
void crossCorr(void) {
      #undef LEN
      #define LEN 11
      Ipp32f win[LEN], y[LEN];
      IppStatus st;
      ippsSet_32f (1, win, LEN);
      ippsWinHamming_32f_I (win, LEN);
      st = ippsCrossCorr_32f (win, LEN, win, LEN, y, LEN, -(LEN-1));
      printf_32f(“cross corr =”, y,7,st); 
}

Output:
    cross corr = 0.006400 0.026856 0.091831 0.242704 0.533230
    1.009000 1.672774 
Matlab* analog:
    >> x = hamming(11)'; y = xcorr(x,x); y(1:7)
CrossCorrNorm Calculates the cross-correlation of two vectors.

UpdateLinear
DEPRECATED. Integrates an input vector with
specified integration weight.

Syntax
IppStatus ippsUpdateLinear_16s32s_I(const Ipp16s* pSrc, int len, Ipp32s* pSrcDst, int
srcShiftRight, Ipp16s alpha, IppHintAlgorithm hint      );

   230
---------------------Page 231---------------------

                                                                             Filtering Functions  6 

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                          Pointer to the source vector.

len                           Number of elements of the vector.

pSrcDst                       Pointer to the input value and output result.

srcShiftRight                 Shift value; must be non-negative.

alpha                         Integration weight.

hint                          Suggests using specific code. The possible values for the hint
                              argument are described in Special Arguments.

Description
The function ippsUpdateLinear  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function performs len iterations in which the sum
alpha * pSrcDst + (1 - alpha) * pSrc[i]shift       is calculated and stored in pSrcDst. Here i is the
number of previous iterations, pSrcDst is the result of previous iteration, and pSrc[i]shift is the element
of the source vector right-shifted by the non-negative value srcShiftRight.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when at least one of the specified pointers is
                                   NULL.
ippStsSizeErr                      Indicates an error when len  is less than or equal to 0.

Example
The example below shows how to use the function ippsUpdateLinear.
void func_updatelinear() 
{
    Ipp16s pSrc[2] = {16, 32};
    Ipp32s pSrcDst =1;
    Ipp16s alpha = 2;
    int shift = 2;
    int srcLen = 2;

    ippsUpdateLinear_16s32s_I(pSrc, 2, &pSrcDst, shift, alpha, ippAlgHintFast);
         
}

Result:
 -12

                                                                                             231
---------------------Page 232---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

UpdatePower
DEPRECATED. Integrates the square of an input vector
with specified integration weight.

Syntax
IppStatus ippsUpdatePower_16s32s_I(const Ipp16s* pSrc, int len, Ipp32s* pSrcDst, int
srcShiftRight,Ipp16s alpha, IppHintAlgorithm hint      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pSrc                          Pointer to the source vector.

len                           Number of elements of the vector.

pSrcDst                       Pointer to input and output

srcShiftRight                 Shift value.

alpha                         Integration weight.

hint                          Suggests using specific code. The possible values for the hint
                              argument are described in Special Arguments.

Description
The function ippsUpdatePower is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function performs len iterations in which the sum alpha * pSrcDst + (1 - alpha) * (pSrc[i]
*pSrc[i]) shift   is calculated and stored in pSrcDst. Here i is the number of previous iterations, pSrcDst
is the result of previous iteration, and (pSrc[i] * pSrc[i]) shift is the squared i-th element right-
shifted by the non-negative value srcShiftRight.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when at least one of the specified pointers is
                                  NULL .
ippStsSizeErr                     Indicates an error when  len  is less than or equal to 0.

Example
The example below shows how to use the function ippsUpdatePower.
void func_updatepower() 
{    
    Ipp16s pSrc[2] = {16, 32};
    Ipp32s pSrcDst = 1;
    Ipp16s alpha = 3;

   232
---------------------Page 233---------------------

                                                                              Filtering Functions  6 
    int shift = 1;
    int srcLen = 2;

    ippsUpdatePower_16s32s_I(pSrc, 2, &pSrcDst, shift, alpha, ippAlgHintFast); 
}
Result:
-1783

Filtering Functions

The Intel     functions described in this section implement the following types of filters:
• Finite impulse response (FIR) filter
• Adaptive finite impulse response using least mean squares (LMS) filter
• Infinite impulse response (IIR) filter
• Median filter
A special set of functions is designed to generate filter coefficients for different types of FIR filters.

SumWindow
DEPRECATED. Sums elements in the mask applied to
each element of a vector.

Syntax
IppStatus ippsSumWindow_8u32f(const Ipp8u* pSrc, Ipp32f* pDst, int len, int maskSize            );
IppStatus ippsSumWindow_16s32f(const Ipp16s* pSrc, Ipp32f* pDst, int len, int
maskSize );

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.

len                           Number of elements of the vector.

maskSize                      Size of the mask.

Description
The function ippsSumWindow is deprecated. This function is obsolete and will be removed in a future release.
Use vector function with vector length = 1 instead. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function sets each element in the destination vector pDst as the sum of maskSize elements of the
source vector pSrc. The computation is performed as follows:
 

                                                                                              233
---------------------Page 234---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

 

Return Values

ippStsNoErr                          Indicates no error.

ippStsNullPtrErr                     Indicates an error when one of the specified pointers is     NULL .

ippStsMaskSizeErr                    Indicates an error when    maskSize   is less than or equal to 0.

FIR Filter Functions
The functions described in this section perform a finite impulse response (FIR) filtering of input data. The
functions initialize different FIR filter structures, get and set the delay lines and filter coefficients (taps), and
perform filtering. Intel     contains the functions that implement the FIR filters without the delay line -
stream FIR filters.
To use the FIR filter functions, follow this general scheme:
1.   Call either ippsFIRInitAlloc   or ippsFIRMRInitAlloc    to allocate memory and initialize the taps and
     the delay line in the filter state structure of a single-rate or multi-rate filter, respectively. Or call either 
     ippsFIRInit   or ippsFIRMRInit    to initialize the taps and the delay line in the corresponding filter
     state structure in the previously created external buffer. The size of this buffer must be computed
     beforehand by calling the functions ippsFIRGetStateSize    or ippsFIRMRGetStateSize    , respectively.
2.   Call ippsFIROne  to filter a single sample through a single-rate filter, ippsFIR to filter a block of
     consecutive samples through a single-rate or multi-rate filter.
3.   To set new taps and delay line values in the previously initialized filter state, call the functions 
     ippsFIRSetTaps    and ippsFIRSetDlyLine    . To get taps and delay line values of the initialized filter
     state, call the functions ippsFIRGetTaps and ippsFIRGetDlyLine    .
4.   Call ippsFIRFree   to free dynamic memory associated with the FIR filter state structure created by 
     ippsFIRInitAlloc    or ippsFIRMRInitAlloc    .
Alternatively, you may use the direct version of the functions ippsFIROne_Direct , ippsFIR_Direct  , 
ippsFIRMR_Direct   . These functions perform filtering without initializing the filter state structure. All
required parameters are directly set in the function.
Special set of functions allows to compute the filter coefficients for different filters.
To perform single-rate FIR filtering with the ippsFIRSR function, follow this scheme:
1.  Call ippsFIRSRGetSize     function to get the size of the filter specification structure and the work buffer.
2.   Call ippsFIRSRInit   function to initialize the filter specification structure.
3.   Call ippsFIRSR  function to apply the single-rate FIR filter to a source vector.

FIRSRGetSize
Computes the size of the constant structure and work
buffer for single-rate FIR filtering.

Syntax
IppStatus ippsFIRSRGetSize(int tapsLen, IppDataType tapsType, int* pSpecSize, int*
pBufSize );

Include Files
ipps.h

   234
---------------------Page 235---------------------

                                                                              Filtering Functions  6 

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

tapsLen                       Length of the FIR filter.

tapsType                      Bit-field mask for the algorithm type definition. Possible values are:
                              ippAlgAuto , ippAlgDirect , or ippAlgFFT .

pSpecSize                     Pointer to the size of the internal constant specification structure.

pBufSize                      Pointer to the size of the work buffer required for FIR filtering.

Description
This function computes the following:
•     Size of the internal constant specification structure for single-rate FIR filtering. The structure can be
  shared between all threads of the application.
•     Size of the work buffer for each thread.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                      Indicates an error when the  tapsLen  value is less than, or
                                   equal to zero.
ippStsAlgTypeErr                   Indicates an error when the specified algorithm type is not
                                   supported.

See Also
Examples of Using FIR Functions

FIRSRInit
Initializes the constant structure for single-rate FIR
filtering.

Syntax
IppStatus ippsFIRSRInit_32f(const Ipp32f* pTaps, int tapsLen, IppAlgType algType,
IppsFIRSpec_32f* pSpec   );
IppStatus ippsFIRSRInit_64f(const Ipp64f* pTaps, int tapsLen, IppAlgType algType,
IppsFIRSpec_64f* pSpec   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                              235
---------------------Page 236---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

pTaps                         Pointer to the filter coefficients.

tapsLen                       Length of the FIR filter.

algType                       Bit-field mask for the algorithm type definition. Possible values are:
                              ippAlgAuto , ippAlgDirect , or ippAlgFFT.

pSpec                         Pointer to the internal constant specification structure.

Description
Before using this function, you need to compute the size of the specification structure using the
ippsFIRSRGetSize   function. This function initializes the constant specification structure for single-rate FIR
filtering.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                     Indicates an error when the  tapsLen  value is less than, or
                                  equal to zero.
ippStsAlgTypeErr                  Indicates an error when the specified algorithm type is not
                                  supported.
ippStsMismatch                    Indicates an error when the selected algorithm type for the
                                  pair of tapsLen  and numIters  values is not effective.

See Also
FIRSRGetSize Computes the size of the constant structure and work buffer for single-rate FIR
filtering.
Examples of Using FIR Functions

FIRSR
Performs single-rate FIR filtering of a source vector.

Syntax
IppStatus ippsFIRSR_32f(const Ipp32f* pSrc, Ipp32f* pDst, int numIters,
IppsFIRSpec_32f* pSpec, const Ipp32f* pDlySrc, Ipp32f* pDlyDst, Ipp8u* pBuf          );
IppStatus ippsFIRSR_64f(const Ipp64f* pSrc, Ipp64f* pDst, int numIters,
IppsFIRSpec_64f* pSpec, const Ipp64f* pDlySrc, Ipp64f* 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.

   236
---------------------Page 237---------------------

                                                                                Filtering Functions  6 

pDst                           Pointer to the destination vector.

numIters                       Number of elements in the destination vector.

pSpec                          Pointer to the internal constant specification structure.

pDlySrc                        Pointer to the array containing values for the source delay lines.

pDlyDst                        Pointer to the array containing values for the destination delay line.

pBuf                           Pointer to the work buffer.

Description
Before using this function, you need to initialize the internal constant specification structure using the
ippsFIRSRInit   function.
This function filters the source vector using the single-rate FIR filter. 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

To compute the y(0)...y(tapsLen-1)    destination vector, the function uses the pDlySrc array of the delay
line. The length of the pDlySrc array is tapsLen-1 elements.
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  pTaps  or pSpec  is NULL.

ippStsSizeErr                       Indicates an error when the  tapsLen   value is less than, or
                                    equal to zero.

                                                                                                237
---------------------Page 238---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsAlgTypeErr               Indicates an error when the specified algorithm type is not
                               supported.
ippStsMismatch                 Indicates an error when the selected algorithm type for the
                               pair of tapsLen and numIters values is not effective.

See Also
FIRSRInit Initializes the constant structure for single-rate FIR filtering.
Examples of Using FIR Functions

FIRInitAlloc
DEPRECATED. Allocates memory and initializes a
single-rate FIR filter state.

Syntax
Case 1: Operation on integer samples
IppStatus ippsFIRInitAlloc_16s(IppsFIRState_16s** pState, const Ipp16s* pTaps, int
tapsLen, int tapsFactor, const Ipp16s* pDlyLine );
IppStatus ippsFIRInitAlloc32s_16s(IppsFIRState32s_16s** pState, const Ipp32s* pTaps,
int tapsLen, int tapsFactor, const Ipp16s* pDlyLine );
IppStatus ippsFIRInitAlloc32s_16s32f(IppsFIRState32s_16s** pState, const Ipp32f* pTaps,
int tapsLen, const Ipp16s* pDlyLine );
IppStatus ippsFIRInitAlloc32f_16s(IppsFIRState32f_16s** pState, const Ipp32f* pTaps,
int tapsLen, const Ipp16s* pDlyLine );
IppStatus ippsFIRInitAlloc64f_16s(IppsFIRState64f_16s** pState, const Ipp64f* pTaps,
int tapsLen, const Ipp16s* pDlyLine );
IppStatus ippsFIRInitAlloc_32s(IppsFIRState_32s** pState, const Ipp32s* pTaps, int
tapsLen, const Ipp32s* pDlyLine );
IppStatus ippsFIRInitAlloc64f_32s(IppsFIRState64f_32s** pState, const Ipp64f* pTaps,
int tapsLen, const Ipp32s* pDlyLine );

IppStatus ippsFIRInitAlloc32sc_16sc(IppsFIRState32sc_16sc** pState, const Ipp32sc*
pTaps, int tapsLen, int tapsFactor, const Ipp16sc* pDlyLine  );
IppStatus ippsFIRInitAlloc32sc_16sc32fc(IppsFIRState32sc_16sc** pState, const Ipp32fc*
pTaps, int tapsLen, const Ipp16sc* pDlyLine );
IppStatus ippsFIRInitAlloc32fc_16sc(IppsFIRState32fc_16sc** pState, const Ipp32fc*
pTaps, int tapsLen, const Ipp16sc* pDlyLine );
IppStatus ippsFIRInitAlloc64fc_16sc(IppsFIRState64fc_16sc** pState, const Ipp64fc*
pTaps, int tapsLen, const Ipp16sc* pDlyLine );
IppStatus ippsFIRInitAlloc64fc_32sc(IppsFIRState64fc_32sc** pState, const Ipp64fc*
pTaps, int tapsLen, const Ipp32sc* pDlyLine );
Case 2: Operation on floating point samples
IppStatus ippsFIRInitAlloc_32f(IppsFIRState_32f** pState, const Ipp32f* pTaps, int
tapsLen, const Ipp32f* pDlyLine );
IppStatus ippsFIRInitAlloc64f_32f(IppsFIRState64f_32f** pState, const Ipp64f* pTaps,
int tapsLen, const Ipp32f* pDlyLine );
IppStatus ippsFIRInitAlloc_64f(IppsFIRState_64f** pState,const Ipp64f* pTaps, int
tapsLen, const Ipp64f* pDlyLine );

  238
---------------------Page 239---------------------

                                                                              Filtering Functions  6 

IppStatus ippsFIRInitAlloc_32fc(IppsFIRState_32fc** pState, const Ipp32fc* pTaps, int
tapsLen, const Ipp32fc* pDlyLine    );
IppStatus ippsFIRInitAlloc64fc_32fc(IppsFIRState64fc_32fc** pState, const Ipp64fc*
pTaps, int tapsLen, const Ipp32fc* pDlyLine      );
IppStatus ippsFIRInitAlloc_64fc(IppsFIRState_64fc** pState, const Ipp64fc* pTaps, int
tapsLen, const Ipp64fc* pDlyLine    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

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

tapsFactor                    Scale factor for the taps.

pDlyLine                      Pointer to the array containing the delay line values. The number of
                              elements in the array is tapsLen .
pState                        Pointer to the FIR state structure.

Description
The function ippsFIRInitAlloc  is deprecated. This function is obsolete and will be removed in a future
release. Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes a single-rate FIR filter state. The initialization function copies
the tap values from the tapsLen-length array pTaps into the state structure pState. To scale integer taps
use the tapsFactor value. The array pDlyLine specifies the delay line values. If the pointer to the
tapsLen -length array pDlyLine is not NULL, the array content is copied into the state structure pState,
otherwise the delay line values in the state structure are initialized to 0.
Note that the delay line length is different than that for direct FIR filters (where this length is doubled).
If the state is not created, the initialization function returns an error status.

Return Values

ippStsNoErr                        Indicates no error.

ippStsMemAllocErr                  Indicates an error when no memory is allocated.

ippStsNullPtrErr                   Indicates an error when  pTaps  or pState is NULL.

ippStsFIRLenErr                    Indicates an error when  tapsLen  is less than or equal to 0.

FIRStreamInitAlloc
DEPRECATED. Allocates memory and initializes a state
structure for the single-rate stream FIR filter.

                                                                                              239
---------------------Page 240---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Syntax
IppStatus ippsFIRStreamInitAlloc_16s(IppsFIRState_16s** ppState, const Ipp16s* pTaps,
int tapsLen, int tapsFactor, IppRoundMode rndMode        );
IppStatus ippsFIRStreamInitAlloc_32f(IppsFIRState_32f** ppState, const Ipp32f* pTaps,
int tapsLen  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                          Pointer to the array containing the tap values.

tapsLen                        Number of elements in the array pTaps.

tapsFactor                     Scale factor for the integer taps.

rndMode                        Rounding mode, the following values are possible:

                               ippRndZero   - specifies that floating-point values are truncated toward
                               zero,

                               ippRndNear   - specifies that floating-point values are rounded to the
                               nearest even integer when the fractional part equals 0.5; otherwise they
                               are rounded to the nearest integer,

                               ippRndFinancial    - specifies that floating-point values are rounded down
                               to the nearest integer when the fractional part is less than 0.5, or rounded
                               up to the nearest integer if the fractional part is equal or greater than 0.5.

ppState                        Double pointer to the FIR state structure to be created.

Description
The function ippsFIRStreamInitAlloc    is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes a state structure for a single-rate stream FIR filter. The
initialization function copies the tap values from the tapsLen-length array pTaps into the state structure
ppState . To scale integer taps use the tapsFactor value.
The parameter rndMode  sets the rounding mode that is used by the functions FIR and FIRFree.
If the state is not created, the initialization function returns an error status.

Return Values

ippStsNoErr                         Indicates no error.

ippStsMemAllocErr                   Indicates an error when no memory is allocated.

ippStsNullPtrErr                    Indicates an error when   pTaps  or ppState is NULL.

   240
---------------------Page 241---------------------

                                                                     Filtering Functions  6 

ippStsFIRLenErr                Indicates an error when tapsLen is less than or equal to 0.

ippStsRoundModeNotSupportedErr Indicates an error when the rndMode has an illegal value.

FIRMRInitAlloc
DEPRECATED. Allocates memory and initializes a
multi-rate FIR filter state.

Syntax
Case 1: Operation on integer samples
IppStatus ippsFIRMRInitAlloc_16s(IppsFIRState_16s** pState, const Ipp16s* pTaps, int
tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int downPhase,
const Ipp16s* pDlyLine);
IppStatus ippsFIRMRInitAlloc32s_16s(IppsFIRState32s_16s** pState, const Ipp32s* pTaps,
int tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int downPhase,
const Ipp16s* pDlyLine);
IppStatus ippsFIRMRInitAlloc32s_16s32f(IppsFIRState32s_16s** pState, const Ipp32f
*pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const
Ipp16s* pDlyLine);
IppStatus ippsFIRMRInitAlloc32f_16s(IppsFIRState32f_16s** pState, const Ipp32f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp16s*
pDlyLine);
IppStatus ippsFIRMRInitAlloc64f_16s(IppsFIRState64f_16s** pState, const Ipp64f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp16s*
pDlyLine);
IppStatus ippsFIRMRInitAlloc64f_32s(IppsFIRState64f_32s** pState, const Ipp64f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32s*
pDlyLine);
IppStatus ippsFIRMRInitAlloc32sc_16sc(IppsFIRState32sc_16sc** pState, const Ipp32sc*
pTaps, int tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int
downPhase, const Ipp16sc* pDlyLine);
IppStatus ippsFIRMRInitAlloc32sc_16sc32fc(IppsFIRState32sc_16sc** pState, const
Ipp32fc* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase,
const Ipp16sc* pDlyLine);
IppStatus ippsFIRMRInitAlloc32fc_16sc(IppsFIRState32fc_16sc** pState, const Ipp32fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const
Ipp16sc* pDlyLine);
IppStatus ippsFIRMRInitAlloc64fc_16sc(IppsFIRState64fc_16sc** pState,const Ipp64fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const
Ipp16sc* pDlyLine);
IppStatus ippsFIRMRInitAlloc64fc_32sc(IppsFIRState64fc_32sc** pState, const Ipp64fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const
Ipp32sc* pDlyLine);
Case 2: Operation on floating point samples
IppStatus ippsFIRMRInitAlloc_32f(IppsFIRState_32f** pState, const Ipp32f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32f*
pDlyLine);

                                                                                   241
---------------------Page 242---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsFIRMRInitAlloc64f_32f(IppsFIRState64f_32f** pState, const Ipp64f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32f*
pDlyLine);
IppStatus ippsFIRMRInitAlloc_64f(IppsFIRState_64f** pState, const Ipp64f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp64f*
pDlyLine);

IppStatus ippsFIRMRInitAlloc_32fc(IppsFIRState_32fc** pState, const Ipp32fc* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32fc*
pDlyLine);
IppStatus ippsFIRMRInitAlloc64fc_32fc(IppsFIRState64fc_32fc** pState, const Ipp64fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const
Ipp32fc* pDlyLine );
IppStatus ippsFIRMRInitAlloc_64fc(IppsFIRState_64fc** pState, const Ipp64fc* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp64fc*
pDlyLine);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

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

tapsFactor                   Scale factor for the integer taps.

downFactor                   Downsampling factor.

downPhase                    Phase for downsampled signal.

upFactor                     Upsampling factor.

upPhase                      Phase for upsampled signal.

pDlyLine                     Pointer to the array containing the delay line values. The number of
                             elements in the array (tapsLen + upFactor - 1) / upFactor   .
pState                       Pointer to the FIR state structure.

Description
The function ippsFIRMRInitAlloc is deprecated. This function is obsolete and will be removed in a future
release. Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes a multi-rate FIR filter state. The initialization functions copy the
taps from the tapsLen-length array pTaps into the state structure pState. To scale integer taps use the
tapsFactor  value. The array pDlyLine specifies the delay line values. If the pointer to the array pDlyLine
is not NULL, the array content is copied into the state structure pState, otherwise the delay line values in
the state structure are initialized to 0.

   242
---------------------Page 243---------------------

                                                                              Filtering Functions  6 

If the state is not created, the initialization function returns an error status.
The function initializes the state structure pState of a multi-rate filter; that is, a filter that internally
upsamples and/or downsamples using a polyphase filter structure. It initializes the state structure in the
same way as described for single-rate filters, but includes additional information about the required
upsampling and downsampling parameters.
The parameter upFactor  is the factor by which the filtered signal is internally upsampled (see description of
the function SampleUp for more details). That is, upFactor-1 zeros are inserted between each sample of the
input signal.
The parameter upPhase  is the parameter which 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 obtained by filtering an upsampled input
signal, is internally downsampled (see description of the function SampleDown 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.
If the delay line array pDlyLine is non-NULL, its length is defined as (tapsLen + upFactor - 1) /
upFactor .
Code FIR shows how to use the function ippsFIRMRInitAlloc_32f .

Return Values

ippStsNoErr                        Indicates no error.

ippStsMemAllocErr                  Indicates an error when no memory is allocated.

ippStsNullPtrErr                   Indicates an error when  pTaps or pState  is NULL.

ippStsFIRLenErr                    Indicates an error when  tapsLen  is less than or equal to 0.

ippStsFIRMRFactorErr               Indicates an error when  upFactor  (downFactor ) is less than or
                                   equal to 0.
ippStsFIRMRPhaseErr                Indicates an error when  upPhase  (downPhase ) is negative, or
                                   greater than or equal to upFactor  (downFactor ).

FIRMRStreamInitAlloc
DEPRECATED. Allocates memory and initializes a state
structure for a multi-rate stream FIR filter.

Syntax
IppStatus ippsFIRMRStreamInitAlloc_16s(IppsFIRState_16s** ppState, const Ipp16s* pTaps,
int tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int downPhase,
IppRoundMode rndMode  );
IppStatus ippsFIRMRStreamInitAlloc_32f(IppsFIRState_32f** ppState, const Ipp32f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase          );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                              243
---------------------Page 244---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

pTaps                           Pointer to the array containing the tap values.

tapsLen                         Number of elements in the array  pTaps .

tapsFactor                      Scale factor for the integer taps.

downFactor                      Downsampling factor.

downPhase                       Phase for downsampled signal.

upFactor                        Upsampling factor.

upPhase                         Phase for upsampled signal.

rndMode                         Rounding mode, the following values are possible:

                                ippRndZero   - specifies that floating-point values are truncated toward
                                zero,

                                ippRndNear   - specifies that floating-point values are rounded to the
                                nearest even integer when the fractional part equals 0.5; otherwise they
                                are rounded to the nearest integer,

                                ippRndFinancial    - specifies that floating-point values are rounded down
                                to the nearest integer when the fractional part is less than 0.5, or rounded
                                up to the nearest integer if the fractional part is equal or greater than 0.5.

ppState                         Double pointer to the stream FIR filter state structure.

Description
The function ippsFIRMRStreamInitAlloc      is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes a state structure for a multi-rate stream FIR filter. The
initialization function copies the tap values from the tapsLen-length array pTaps into the state structure
ppState . To scale integer taps use the tapsFactor  value.
If the state is not created, the initialization function returns an error status.
The function initializes the state structure ppState of a multi-rate filter; that is, a filter that internally
upsamples and/or downsamples using a polyphase filter structure. It initializes the state structure in the
same way as described for single-rate filters, but includes additional information about the required
upsampling and downsampling parameters.
The parameter  upFactor  is the factor by which the filtered signal is internally upsampled (see description of
the ip psSampleUp function for more details). That is, upFactor-1 zeros are inserted between each sample
of input signal.
The parameter  upPhase  is the parameter which 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 obtained by filtering an upsampled input
signal is internally downsampled (see description of the ipp sSampleDown function for more details). That is,
downFactor  -1 output samples are discarded from each  downFactor  -length output block of upsampled filter
response.

   244
---------------------Page 245---------------------

                                                                       Filtering Functions  6 

The parameter downPhase is the parameter which determines where non-discarded sample lies within a
block of upsampled filter response.
The parameter rndMode sets the rounding mode that is used by the functions FIR and FIRFree.

Return Values

ippStsNoErr                     Indicates no error.

ippStsMemAllocErr               Indicates an error when no memory is allocated.

ippStsNullPtrErr                Indicates an error when pTaps or ppState is NULL.

ippStsFIRLenErr                 Indicates an error when tapsLen is less than or equal to 0.

ippStsFIRMRFactorErr            Indicates an error when upFactor (downFactor) is less than or
                                equal to 0.
ippStsFIRMRPhaseErr             Indicates an error when upPhase (downPhase) is negative, or
                                greater than or equal to upFactor (downFactor).
ippStsRoundModeNotSupportedErr  Indicates an error when the rndMode has an illegal value.

FIRFree
DEPRECATED. Closes a FIR filter state.

Syntax
IppStatus ippsFIRFree_16s(IppsFIRState_16s* pState  );
IppStatus ippsFIRFree32s_16s(IppsFIRState32s_16s* pState  );
IppStatus ippsFIRFree32f_16s(IppsFIRState32f_16s* pState  );
IppStatus ippsFIRFree64f_16s(IppsFIRState64f_16s* pState  );
IppStatus ippsFIRFree_32s(IppsFIRState_32s* pState  );
IppStatus ippsFIRFree64f_32s(IppsFIRState64f_32s* pState  );
IppStatus ippsFIRFree32sc_16sc(IppsFIRState32sc_16sc* pState   );
IppStatus ippsFIRFree32fc_16sc(IppsFIRState32fc_16sc* pState   );
IppStatus ippsFIRFree64fc_16sc(IppsFIRState64fc_16sc* pState   );
IppStatus ippsFIRFree64fc_32sc(IppsFIRState64fc_32sc* pState   );

IppStatus ippsFIRFree_32f(IppsFIRState_32f* pState  );
IppStatus ippsFIRFree64f_32f(IppsFIRState64f_32f* pState  );
IppStatus ippsFIRFree_64f(IppsFIRState_64f* pState  );
IppStatus ippsFIRFree_32fc(IppsFIRState_32fc* pState  );
IppStatus ippsFIRFree64fc_32fc(IppsFIRState64fc_32fc* pState   );
IppStatus ippsFIRFree_64fc(IppsFIRState_64fc* pState  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                      245
---------------------Page 246---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

pState                      Pointer to the FIR filter state structure to be closed.

Description
The function ippsFIRFree is deprecated. This function is obsolete and will be removed in a future release.
Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function closes the FIR filter state by freeing all memory associated with the filter state structure created
by FIRInitAlloc or FIRMRInitAlloc. Call ippsFIRFree after filtering is completed.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr            Indicates an error when the state identifier is incorrect.

FIRInit
Initializes a single-rate FIR filter state.

Syntax
Case 1: Operation on integer samples
IppStatus ippsFIRInit32s_16s(IppsFIRState32s_16s** ppState, const Ipp32s* pTaps, int
tapsLen, int tapsFactor, const Ipp16s* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsFIRInit32f_16s(IppsFIRState32f_16s** ppState, const Ipp32f* pTaps, int
tapsLen, const Ipp16s* pDlyLine, Ipp8u* pBuffer   );
IppStatus ippsFIRInit64f_16s(IppsFIRState64f_16s** ppState, const Ipp64f* pTaps, int
tapsLen, const Ipp16s* pDlyLine, Ipp8u* pBuffer   );
IppStatus ippsFIRInit64f_32s(IppsFIRState64f_32s** ppState, const Ipp64f* pTaps, int
tapsLen, const Ipp32s* pDlyLine, Ipp8u* pBuffer   );

IppStatus ippsFIRInit32sc_16sc(IppsFIRState32sc_16sc** ppState, const Ipp32sc* pTaps,
int tapsLen, int tapsFactor, const Ipp16sc* pDlyLine, Ipp8u* pBuffer     );
IppStatus ippsFIRInit32fc_16sc(IppsFIRState32fc_16sc** ppState, const Ipp32fc* pTaps,
int tapsLen, const Ipp16sc* pDlyLine, Ipp8u* pBuffer   );
IppStatus ippsFIRInit64fc_16sc(IppsFIRState64fc_16sc** ppState, const Ipp64fc* pTaps,
int tapsLen, const Ipp16sc* pDlyLine, Ipp8u* pBuffer   );
IppStatus ippsFIRInit64fc_32sc(IppsFIRState64fc_32sc** ppState, const Ipp64fc* pTaps,
int tapsLen, const Ipp32sc* pDlyLine, Ipp8u* pBuffer   );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsFIRInit_16s(IppsFIRState_16s** ppState, const Ipp16s* pTaps, int tapsLen,
int tapsFactor, const Ipp16s* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsFIRInit_32s(IppsFIRState_32s** ppState, const Ipp32s* pTaps, int tapsLen,
const Ipp32s* pDlyLine, Ipp8u* pBuffer  );
IppStatus ippsFIRInit32s_16s32f(IppsFIRState32s_16s** ppState, const Ipp32f* pTaps, int
tapsLen, const Ipp16s* pDlyLine, Ipp8u* pBuffer   );

   246
---------------------Page 247---------------------

                                                                            Filtering Functions  6 

IppStatus ippsFIRInit32sc_16sc32fc(IppsFIRState32sc_16sc** ppState, const Ipp32fc*
pTaps, int tapsLen, const Ipp16sc* pDlyLine, Ipp8u* pBuffer      );
Case 2: Operation on floating point samples
IppStatus ippsFIRInit_32f(IppsFIRState_32f** ppState, const Ipp32f* pTaps, int tapsLen,
const Ipp32f* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsFIRInit64f_32f(IppsFIRState64f_32f** ppState, const Ipp64f* pTaps, int
tapsLen, const Ipp32f* pDlyLine, Ipp8u* pBuffer     );
IppStatus ippsFIRInit_64f(IppsFIRState_64f** ppState, const Ipp64f* pTaps, int tapsLen,
const Ipp64f* pDlyLine, Ipp8u* pBuffer    );

IppStatus ippsFIRInit_32fc(IppsFIRState_32fc** ppState, const Ipp32fc* pTaps, int
tapsLen, const Ipp32fc* pDlyLine, Ipp8u* pBuffer     );
IppStatus ippsFIRInit64fc_32fc(IppsFIRState64fc_32fc** ppState, const Ipp64fc* pTaps,
int tapsLen, const Ipp32fc* pDlyLine, Ipp8u* pBuffer     );
IppStatus ippsFIRInit_64fc(IppsFIRState_64fc** ppState, const Ipp64fc* pTaps, int
tapsLen, const Ipp64fc* pDlyLine, Ipp8u* pBuffer     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

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

tapsFactor                   Scale factor for the taps.

pDlyLine                     Pointer to the array containing the delay line values. The number of
                             elements in the array is tapsLen.
ppState                      Pointer to the pointer to the FIR state structure to be created.

pBuffer                      Pointer to the external buffer for FIR state structure.

Description
Functions ippsFIRInit_16s , ippsFIRInit_32s  , ippsFIRInit32s_16s32f  , and
ippsFIRInit32sc_16sc32fc   are deprecated. These functions are obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function initializes a single-rate FIR filter state structure in the external buffer. The size of this buffer
must be computed previously by calling the functions FIRGetStateSize FIRMRGetStateSize. The initialization
function copies the taps from the tapsLen-length array pTaps into the state structure ppState of a single-
rate filter. To scale integer taps, use the tapsFactor value. The tapsLen-length array pDlyLine specifies
the delay line values. If the pointer to the array pDlyLine is not NULL, the array contents is copied into the
state structure ppState, otherwise the delay line values in the state structure are initialized to 0.
Note that the delay line length is different than that for direct FIR filters (where this length is doubled).

                                                                                           247
---------------------Page 248---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when one of the specified pointers is NULL .

ippStsFIRLenErr                     Indicates an error when  tapsLen  is less than or equal to 0.

FIRStreamInit
DEPRECATED. Initializes a single-rate stream FIR filter
state.

Syntax
IppStatus ippsFIRStreamInit_16s(IppsFIRState_16s** ppState, const Ipp16s* pTaps, int
tapsLen, int tapsFactor, IppRoundMode rndMode, Ipp8u* pBuffer          );
IppStatus ippsFIRStreamInit_32f(IppsFIRState_32f** ppState, const Ipp32f* pTaps, int
tapsLen, Ipp8u* pBuffer   );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                         Pointer to the array containing the tap values.

tapsLen                       Number of elements in the array pTaps.

tapsFactor                    Scale factor for the integer taps.

rndMode                       Rounding mode, the following values are possible:

                              ippRndZero   - specifies that floating-point values are truncated toward
                              zero,

                              ippRndNear   - specifies that floating-point values are rounded to the
                              nearest even integer when the fractional part equals 0.5; otherwise they
                              are rounded to the nearest integer,

                              ippRndFinancial    - specifies that floating-point values are rounded down
                              to the nearest integer when the fractional part is less than 0.5, or rounded
                              up to the nearest integer if the fractional part is equal or greater than 0.5.

ppState                       Double pointer to the FIR state structure to be created.

pBuffer                       Pointer to the external buffer for FIR state structure.

Description
The function ippsFIRStreamInit   is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.

   248
---------------------Page 249---------------------

                                                                        Filtering Functions  6 

This function initializes a single-rate FIR filter state structure in the external buffer . The size of this buffer
must be computed by calling the function FIRStreamGetStateSize FIRMRStreamGetStateSize beforehand.
The initialization function copies the taps from the tapsLen-length array pTaps into the state structure
ppState of a single-rate filter. To scale integer taps, use the tapsFactor value.
The parameter rndMode sets the rounding mode that is used by the functions FIR and FIROne .

Return Values

ippStsNoErr                     Indicates no error.

ippStsNullPtrErr                Indicates an error when one of the specified pointers is NULL.

ippStsFIRLenErr                 Indicates an error when tapsLen is less than or equal to 0.

ippStsRoundModeNotSupportedErr  Indicates an error when the rndMode has an illegal value.

FIRMRInit
Initializes a multi-rate FIR filter state.

Syntax
Case 1: Operation on integer samples
IppStatus ippsFIRMRInit32s_16s(IppsFIRState32s_16s** ppState, const Ipp32s* pTaps, int
tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int downPhase,
const Ipp16s* pDlyLine, Ipp8u* pBuffer  );
IppStatus ippsFIRMRInit32f_16s(IppsFIRState32f_16s** ppState, const Ipp32f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp16s*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit64f_16s(IppsFIRState64f_16s** ppState, const Ipp64f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp16s*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit64f_32s(IppsFIRState64f_32s** ppState, const Ipp64f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32s*
pDlyLine, Ipp8u* pBuffer );

IppStatus ippsFIRMRInit32sc_16sc(IppsFIRState32sc_16sc** ppState, const Ipp32sc* pTaps,
int tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int downPhase,
const Ipp16sc* pDlyLine, Ipp8u* pBuffer  );
IppStatus ippsFIRMRInit32fc_16sc(IppsFIRState32fc_16sc** ppState, const Ipp32fc* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp16sc*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit64fc_16sc(IppsFIRState64fc_16sc** ppState, const Ipp64fc* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp16sc*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit64fc_32sc(IppsFIRState64fc_32sc** ppState, const Ipp64fc* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32sc*
pDlyLine, Ipp8u* pBuffer );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsFIRMRInit_16s(IppsFIRState_16s** ppState, const Ipp16s* pTaps, int
tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int downPhase,
const Ipp16s* pDlyLine, Ipp8u* pBuffer  );

                                                                                      249
---------------------Page 250---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsFIRMRInit32s_16s32f(IppsFIRState32s_16s** ppState, const Ipp32f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp16s*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit32sc_16sc32fc(IppsFIRState32sc_16sc** ppState, const Ipp32fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const
Ipp16sc* pDlyLine, Ipp8u* pBuffer );
Case 2: Operation on floating point samples
IppStatus ippsFIRMRInit_32f(IppsFIRState_32f** ppState, const Ipp32f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32f*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit64f_32f(IppsFIRState64f_32f** ppState, const Ipp64f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32f*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit_64f(IppsFIRState_64f** ppState, const Ipp64f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp64f*
pDlyLine, Ipp8u* pBuffer );

IppStatus ippsFIRMRInit_32fc(IppsFIRState_32fc** ppState, const Ipp32fc* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32fc*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit64fc_32fc(IppsFIRState64fc_32fc** ppState, const Ipp64fc* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp32fc*
pDlyLine, Ipp8u* pBuffer );
IppStatus ippsFIRMRInit_64fc(IppsFIRState_64fc** ppState, const Ipp64fc* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, const Ipp64fc*
pDlyLine, Ipp8u* pBuffer );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

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

tapsLen                    Number of elements in the array containing the tap values.

tapsFactor                 Scale factor for the integer taps.

downFactor                 Downsampling factor.

downPhase                  Phase for downsampled signal.

upFactor                   Upsampling factor.

upPhase                    Phase for upsampled signal.

  250
---------------------Page 251---------------------

                                                                                 Filtering Functions  6  

pDlyLine                       Pointer to the array containing the delay line values. The number of
                               elements in the array is (tapsLen + upFactor - 1) / upFactor     .

ppState                        Pointer to the pointer to the FIR state structure.

pBuffer                        Pointer to the external buffer for FIR state structure.

Description
Functions ippsFIRMRInit_16s   , ippsFIRMRInit32s_16s32f     , and ippsFIRMRInit32sc_16sc32fc     are
deprecated. These functions are obsolete and will be removed in a future release. Use the following link for
details: http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function initializes a multi-rate FIR filter state structure in the external buffer. The size of this buffer
must be computed previously by calling the functions FIRGetStateSize FIRMRGetStateSize. The initialization
functions copy the taps from the tapsLen-length array pTaps into the state structure ppState. To scale
integer taps, use the tapsFactor value. The array pDlyLine specifies the delay line values. If the pointer to
the array pDlyLine is not NULL, the array contents is copied into the state structure ppState, otherwise the
delay line values in the state structure are initialized to 0.
The function initializes the state structure ppState of a multi-rate filter, that is, a filter that internally
upsamples and/or downsamples signals using a polyphase filter structure. It initializes the state structure in
the same way as described for single-rate filters, but includes additional information about the required
upsampling and downsampling parameters.
The parameter upFactor   is the factor by which the filtered signal is internally upsampled (see description of
the function SampleUp for more details). That is, upFactor-1 zeros are inserted between each sample of the
input signal.
The parameter upPhase   is the parameter, which determines where a non-zero sample lies within the
upFactor -length block of the upsampled input signal.
The parameter downFactor   is the factor by which the FIR response obtained by filtering an upsampled input
signal, is internally downsampled (see description of the function SampleDown 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.
If the delay line array pDlyLine is not NULL, its length is defined as (tapsLen + upFactor - 1) /
upFactor .

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when   pTaps , ppState  or pBuffer  is NULL.

ippStsFIRLenErr                     Indicates an error when   tapsLen   is less than or equal to 0.

ippStsFIRMRFactorErr                Indicates an error when   upFactor   (downFactor  ) is less than or
                                    equal to 0.
ippStsFIRMRPhaseErr                 Indicates an error when   upPhase   (downPhase ) is negative, or
                                    greater than or equal to   upFactor  (downFactor  ).

FIRMRStreamInit
DEPRECATED. Initializes a multi-rate stream FIR filter
state.

                                                                                                  251
---------------------Page 252---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Syntax
IppStatus ippsFIRMRStreamInit_16s(IppsFIRState_16s** ppState, const Ipp16s* pTaps, int
tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int downPhase,
IppRoundMode rndMode, Ipp8u* pBuffer     );
IppStatus ippsFIRMRStreamInit_32f(IppsFIRState_32f** ppState, const Ipp32f* pTaps, int
tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp8u* pBuffer             );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                         Pointer to the array containing the tap values.

tapsLen                       Number of elements in the array pTaps.

tapsFactor                    Scale factor for the integer taps.

downFactor                    Downsampling factor.

downPhase                     Phase for downsampled signal.

upFactor                      Upsampling factor.

upPhase                       Phase for upsampled signal.

rndMode                       Rounding mode, the following values are possible:

                              ippRndZero   - specifies that floating-point values are truncated toward
                              zero,

                              ippRndNear   - specifies that floating-point values are rounded to the
                              nearest even integer when the fractional part equals 0.5; otherwise they
                              are rounded to the nearest integer,

                              ippRndFinancial    - specifies that floating-point values are rounded down
                              to the nearest integer when the fractional part is less than 0.5, or rounded
                              up to the nearest integer if the fractional part is equal or greater than 0.5.

ppState                       Double pointer to the stream FIR filter state structure.

pBuffer                       Pointer to the external buffer for the stream FIR filter state structure.

Description
The function ippsFIRMRStreamInit   is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.

   252
---------------------Page 253---------------------

                                                                              Filtering Functions  6 

This function initializes a state structure for a multi-rate stream FIR filter in the external buffer. The size of
this buffer must be computed by calling the function FIRStreamGetStateSize FIRMRStreamGetStateSize
beforehand. The initialization function copies the tap values from the tapsLen-length array pTaps into the
state structure ppState. To scale integer taps use the tapsFactor value.
The function initializes the state structure ppState of a multi-rate filter; that is, a filter that internally
upsamples and/or downsamples using a polyphase filter structure. It initializes the state structure in the
same way as described for single-rate filters, but includes additional information about the required
upsampling and downsampling parameters.
The parameter upFactor  is the factor by which the filtered signal is internally upsampled (see description of
the ip psSampleUp function for more details). That is, upFactor-1 zeros are inserted between each sample
of input signal.
The parameter upPhase  is the parameter which 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 obtained by filtering an upsampled input
signal is internally downsampled (see description of the function SampleDown for more details). That is,
downFactor -1 output samples are discarded from each downFactor-length output block of upsampled filter
response.
The parameter downPhase  is the parameter which determines where non-discarded sample lies within a
block of upsampled filter response.
The parameter rndMode  sets the rounding mode that is used by the functions FIR and FIRFree.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when  pTaps  or ppState is NULL.

ippStsFIRLenErr                    Indicates an error when  tapsLen  is less than or equal to 0.

ippStsFIRMRFactorErr               Indicates an error when  upFactor  (downFactor ) is less than or
                                   equal to 0.
ippStsFIRMRPhaseErr                Indicates an error when  upPhase  (downPhase ) is negative, or
                                   greater than or equal to upFactor  (downFactor ).
ippStsRoundModeNotSupportedErr     Indicates an error when the  rndMode  has an illegal value.

FIRGetStateSize, FIRMRGetStateSize
Returns the length of the FIR filter state structure.

Syntax
Case 1: Single-rate filter
IppStatus ippsFIRGetStateSize_16s(int tapsLen, int* pBufferSize         );
IppStatus ippsFIRGetStateSize_32f(int tapsLen, int* pBufferSize         );
IppStatus ippsFIRGetStateSize_32fc(int tapsLen, int* pBufferSize         );
IppStatus ippsFIRGetStateSize_64f(int tapsLen, int* pBufferSize         );
IppStatus ippsFIRGetStateSize_64fc(int tapsLen, int* pBufferSize         );
IppStatus ippsFIRGetStateSize32s_16s(int tapsLen, int* pBufferSize         );
IppStatus ippsFIRGetStateSize32sc_16sc(int tapsLen, int* pBufferSize          );
IppStatus ippsFIRGetStateSize32f_16s(int tapsLen, int* pBufferSize         );

                                                                                              253
---------------------Page 254---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsFIRGetStateSize32fc_16sc(int tapsLen, int* pBufferSize);
IppStatus ippsFIRGetStateSize64f_16s(int tapsLen, int* pBufferSize);
IppStatus ippsFIRGetStateSize64f_32f(int tapsLen, int* pBufferSize);
IppStatus ippsFIRGetStateSize64f_32s(int tapsLen, int* pBufferSize);
IppStatus ippsFIRGetStateSize64fc_16sc(int tapsLen, int* pBufferSize);
IppStatus ippsFIRGetStateSize64fc_32sc(int tapsLen, int* pBufferSize);
IppStatus ippsFIRGetStateSize64fc_32fc(int tapsLen, int* pBufferSize);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsFIRGetStateSize_32s(int tapsLen, int* pBufferSize);
IppStatus ippsFIRGetStateSize32s_16s32f(int tapsLen, int* pBufferSize);
IppStatus ippsFIRGetStateSize32sc_16sc32fc(int tapsLen, int* pBufferSize );
Case 2: Multi-rate filter
IppStatus ippsFIRMRGetStateSize_32f(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize_32fc(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize_64f(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize_64fc(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize32s_16s(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize32sc_16sc(int tapsLen, int upFactor, int downFactor,
int* pBufferSize);
IppStatus ippsFIRMRGetStateSize32f_16s(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize32fc_16sc(int tapsLen, int upFactor, int downFactor,
int* pBufferSize);
IppStatus ippsFIRMRGetStateSize64f_16s(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize64f_32s(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize64f_32f(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);
IppStatus ippsFIRMRGetStateSize64fc_16sc(int tapsLen, int upFactor, int downFactor,
int* pBufferSize);
IppStatus ippsFIRMRGetStateSize64fc_32sc(int tapsLen, int upFactor, int downFactor,
int* pBufferSize);
IppStatus ippsFIRMRGetStateSize64fc_32fc(int tapsLen, int upFactor, int downFactor,
int* pBufferSize);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsFIRMRGetStateSize_16s(int tapsLen, int upFactor, int downFactor, int*
pBufferSize);

  254
---------------------Page 255---------------------

                                                                              Filtering Functions  6 

IppStatus ippsFIRMRGetStateSize32s_16s32f(int tapsLen, int upFactor, int downFactor,
int* pBufferSize  );
IppStatus ippsFIRMRGetStateSize32sc_16sc32fc(int tapsLen, int upFactor, int downFactor,
int* pBufferSize  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

tapsLen                       Number of elements in the array containing the tap values.

upFactor                      Upsampling factor for the multi-rate filter.

downFactor                    Downsampling factor for the multi-rate filter.

pBufferSize                   Pointer to the computed buffer size value.

Description
Functions ippsFIRGetStateSize_32s  , ippsFIRGetStateSize32s_16s32f    ,
ippsFIRGetStateSize32sc_16sc32fc    , ippsFIRMRGetStateSize_16s   ,
ippsFIRMRGetStateSize32s_16s32f    , and ippsFIRMRGetStateSize32sc_16sc32fc     are deprecated.
These functions are obsolete and will be removed in a future release. Use the following link for details:
http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
These functions compute the size of the external buffer for a single-rate or multi-rate FIR filter state,
respectively, and store the result in pBufferSize.
To compute the size of a buffer for the single-rate FIR filter state, the number of taps tapsLen only need be
specified. To compute the size of a buffer for the multi-rate FIR filter state, the number of taps tapsLen and
upsampling/downsampling parameters  upFactor  and downFactor  must be specified. The parameter
upFactor  is the factor by which the filtered signal is internally upsampled (see description of the function 
SampleUp for more details). That is, upFactor-1 zeros are inserted between each sample of the input signal.
The parameter downFactor  is the factor by which the FIR response obtained by filtering an upsampled input
signal, is internally downsampled (see description of the function SampleDown for more details). That is,
downFactor -1 output samples are discarded from each downFactor-length output block of the upsampled
filter response.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error if the pBufferSize pointer is NULL.

ippStsFIRLenErr                    Indicates an error if tapsLen is less than or equal to 0.

ippStsFIRMRFactorErr               Indicates an error if upFactor (downFactor ) is less than or
                                   equal to 0.

FIRStreamGetStateSize, FIRMRStreamGetStateSize
DEPRECATED. Calculates the size of the stream FIR
filter state structure.

                                                                                              255
---------------------Page 256---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Case 1: Single-rate filter
IppStatus ippsFIRStreamGetStateSize_16s(int tapsLen, int* pBufferSize);
IppStatus ippsFIRStreamGetStateSize_32f(int tapsLen, int* pBufferSize);

Case 2: Multi-rate filter
IppStatus ippsFIRMRStreamGetStateSize_16s(int tapsLen, int upFactor, int downFactor,
int* pBufferSize);
IppStatus ippsFIRMRStreamGetStateSize_32f(int tapsLen, int upFactor, int downFactor,
int* pBufferSize);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

upFactor                      Upsampling factor for the multi-rate filter.

downFactor                    Downsampling factor for the multi-rate filter.

pBufferSize                   Pointer to the computed value of the buffer size.

Description
Functions ippsFIRStreamGetStateSize    and ippsFIRMRStreamGetStateSize     are deprecated. These
functions are obsolete and will be removed in a future release. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
These functions compute the size of the external buffer for a single-rate or multi-rate stream FIR filter state,
tapsLen  respectively, and store the result in pBufferSize.
To calculate the size of a buffer for the single-rate filter state, the filter state number of taps only need be
specified. To calculate the size of a buffer for the multi-rate FIR filter state, the number of taps tapsLen and
upsampling/downsampling parameters  upFactor   and downFactor  must be specified.
The parameter upFactor  is the factor by which the filtered signal is internally upsampled (see description of
the function SampleUp for more details). That is, upFactor-1 zeros are inserted between each sample of the
input signal.
The parameter downFactor   is the factor by which the FIR response obtained by filtering an upsampled input
signal, is internally downsampled (see description of the function SampleDown for more details). That is,
downFactor -1 output samples are discarded from each downFactor -length output block of the upsampled
filter response.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error if the pBufferSize  pointer is NULL.

ippStsFIRLenErr                    IIndicates an error if tapsLen  is less than or equal to 0.

ippStsFIRMRFactorErr               Indicates an error if upFactor  (downFactor ) is less than or
                                   equal to 0.

   256
---------------------Page 257---------------------

                                                                      Filtering Functions  6 

FIRGetTaps
DEPRECATED. Retrieves the tap values from the FIR
filter state structure.

Syntax
IppStatus ippsFIRGetTaps_16s(const IppsFIRState_16s* pState, Ipp16s* pTaps, int
tapsFactor);
IppStatus ippsFIRGetTaps_32s(const IppsFIRState_32s* pState, Ipp32f* pTaps );
IppStatus ippsFIRGetTaps_32f(const IppsFIRState_32f* pState, Ipp32f* pTaps );
IppStatus ippsFIRGetTaps_64f(const IppsFIRState_64f* pState, Ipp64f* pTaps );
IppStatus ippsFIRGetTaps32f_16s(const IppsFIRState32f_16s* pState, Ipp32f* pTaps  );
IppStatus ippsFIRGetTaps64f_16s(const IppsFIRState64f_16s* pState, Ipp64f* pTaps  );
IppStatus ippsFIRGetTaps64f_32s(const IppsFIRState64f_32s* pState, Ipp64f* pTaps  );
IppStatus ippsFIRGetTaps64f_32f(const IppsFIRState64f_32f* pState, Ipp64f* pTaps  );
IppStatus ippsFIRGetTaps_32fc(const IppsFIRState_32fc* pState, Ipp32fc* pTaps  );
IppStatus ippsFIRGetTaps_64fc(const IppsFIRState_64fc* pState, Ipp64fc* pTaps  );
IppStatus ippsFIRGetTaps32fc_16sc(const IppsFIRState32fc_16sc* pState, Ipp32fc* pTaps  );
IppStatus ippsFIRGetTaps64fc_16sc(const IppsFIRState64fc_16sc* pState, Ipp64fc* pTaps  );
IppStatus ippsFIRGetTaps64fc_32sc(const IppsFIRState64fc_32sc* pState, Ipp64fc* pTaps  );
IppStatus ippsFIRGetTaps64fc_32fc(const IppsFIRState64fc_32fc* pState, Ipp64fc* pTaps  );
IppStatus ippsFIRGetTaps32s_16s32f(const IppsFIRState32s_16s* pState, Ipp32f* pTaps  );
IppStatus ippsFIRGetTaps32sc_16sc32fc(const IppsFIRState32sc_16sc* pState, Ipp32fc*
pTaps);
IppStatus ippsFIRGetTaps32s_16s(const IppsFIRState32s_16s* pState, Ipp32s* pTaps, int*
pTapsFactor);
IppStatus ippsFIRGetTaps32sc_16sc(const IppsFIRState32sc_16sc* pState, Ipp32sc* pTaps,
int* pTapsFactor);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                     Pointer to the FIR filter state structure.

pTaps                      Pointer to the array containing the tap values.

pTapsFactor                Pointer to the scale factor for the taps.

                                                                                    257
---------------------Page 258---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Description
The function ippsFIRGetTaps is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function copies the tap values from the initialized FIR state structure pState to the tapsLen-length
array pTaps. To scale integer taps, use the pTapsFactor value.
Before calling ippsFIRGetTaps function, the corresponding filter state structure must be initialized, for
example by calling the functions FIRInitAlloc or FIRMRInitAlloc.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr            Indicates an error when the state identifier is incorrect.

FIRSetTaps
DEPRECATED. Sets the tap values in the FIR filter
state structure.

Syntax
IppStatus ippsFIRSetTaps_16s(const Ipp16s* pTaps, IppsFIRState_16s* pState, int
tapsFactor);
IppStatus ippsFIRSetTaps_32s(const Ipp32s* pTaps, IppsFIRState_32s* pState     );
IppStatus ippsFIRSetTaps_32f(const Ipp32f* pTaps, IppsFIRState_32f* pState     );
IppStatus ippsFIRSetTaps_64f(const Ipp64f* pTaps, IppsFIRState_64f* pState     );
IppStatus ippsFIRSetTaps32f_16s(const Ipp32f* pTaps, IppsFIRState32f_16s* pState     );
IppStatus ippsFIRSetTaps64f_16s(const Ipp64f* pTaps, IppsFIRState64f_16s* pState     );
IppStatus ippsFIRSetTaps64f_32s(const Ipp64f* pTaps, IppsFIRState64f_32s* pState     );
IppStatus ippsFIRSetTaps64f_32f(const Ipp64f* pTaps, IppsFIRState64f_32f* pState     );
IppStatus ippsFIRSetTaps_32fc(const Ipp32fc* pTaps, IppsFIRState_32fc* pState     );
IppStatus ippsFIRSetTaps_64fc(const Ipp64fc* pTaps, IppsFIRState_64fc* pState     );
IppStatus ippsFIRSetTaps32fc_16sc(const Ipp32fc* pTaps, IppsFIRState32fc_16sc* pState      );
IppStatus ippsFIRSetTaps64fc_16sc(const Ipp64fc* pTaps, IppsFIRState64fc_16sc* pState      );
IppStatus ippsFIRSetTaps64fc_32sc(const Ipp64fc* pTaps, IppsFIRState64fc_32sc* pState      );
IppStatus ippsFIRSetTaps64fc_32fc(const Ipp64fc* pTaps, IppsFIRState64fc_32fc* pState      );
IppStatus ippsFIRSetTaps32s_16s32f(const Ipp32f* pTaps, IppsFIRState32s_16s* pState      );
IppStatus ippsFIRSetTaps32sc_16sc32fc(const Ipp32fc* pTaps, IppsFIRState32sc_16sc*
pState);
IppStatus ippsFIRSetTaps32s_16s(const Ipp32s* pTaps, IppsFIRState32s_16s* pState, int
tapsFactor);
IppStatus ippsFIRSetTaps32sc_16sc(const Ipp32sc* pTaps, IppsFIRState32sc_16sc* pState,
int tapsFactor );

   258
---------------------Page 259---------------------

                                                                             Filtering Functions  6 

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                       Pointer to the FIR filter state structure.

pTaps                        Pointer to the array containing the tap values.

tapsFactor                   Scale factor for the taps.

Description
The function ippsFIRSetTaps is deprecated. This function is obsolete and will be removed in a future
release. Use Init function instead of SetTaps for changing filter coefficients. Use the following link for
details: http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function sets new tap values in the previously initialized FIR filter state structure pState. New tap
values must be specified in the array pTaps. The length of the array pTaps must be equal to the tapsLen
parameter value of the initialized filter state.
To scale integer taps, use the tapsFactor value.
Before calling ippsFIRSetTaps function, the corresponding filter state structure must be initialized by calling
the function FIRInitAlloc or FIRMRInitAlloc.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

FIRGetDlyLine
Retrieves the delay line contents from the FIR filter
state structure.

Syntax
IppStatus ippsFIRGetDlyLine_16s(const IppsFIRState_16s* pState, Ipp16s* pDlyLine          );
IppStatus ippsFIRGetDlyLine_32f(const IppsFIRState_32f* pState, Ipp32f* pDlyLine          );
IppStatus ippsFIRGetDlyLine_64f(const IppsFIRState_64f* pState, Ipp64f* pDlyLine          );
IppStatus ippsFIRGetDlyLine32s_16s(const IppsFIRState32s_16s* pState, Ipp16s*
pDlyLine );
IppStatus ippsFIRGetDlyLine32f_16s(const IppsFIRState32f_16s* pState, Ipp16s*
pDlyLine );
IppStatus ippsFIRGetDlyLine64f_16s(const IppsFIRState64f_16s* pState, Ipp16s*
pDlyLine );
IppStatus ippsFIRGetDlyLine64f_32s(const IppsFIRState64f_32s* pState, Ipp32s*
pDlyLine );

                                                                                             259
---------------------Page 260---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsFIRGetDlyLine64f_32f(const IppsFIRState64f_32f* pState, Ipp32f*
pDlyLine);

IppStatus ippsFIRGetDlyLine_32fc(const IppsFIRState_32fc* pState, Ipp32fc* pDlyLine       );
IppStatus ippsFIRGetDlyLine_64fc(const IppsFIRState_64fc* pState, Ipp64fc* pDlyLine       );
IppStatus ippsFIRGetDlyLine32sc_16sc(const IppsFIRState32sc_16sc* pState, Ipp16sc*
pDlyLine);
IppStatus ippsFIRGetDlyLine32fc_16sc(const IppsFIRState32fc_16sc* pState, Ipp16sc*
pDlyLine);
IppStatus ippsFIRGetDlyLine64fc_16sc(const IppsFIRState64fc_16sc* pState, Ipp16sc*
pDlyLine);
IppStatus ippsFIRGetDlyLine64fc_32sc(const IppsFIRState64fc_32sc* pState, Ipp32sc*
pDlyLine);
IppStatus ippsFIRGetDlyLine64fc_32fc(const IppsFIRState64fc_32fc* pState, Ipp32fc*
pDlyLine);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                      Pointer to the FIR filter state structure.

pDlyLine                    Pointer to the array holding the delay line values.

Description
This function copies the delay line values from the state structure pState and stores them into pDlyLine.
The destination array pDlyLinecontains samples in the reverse order as compared to the order of samples in
the source vector.
Before calling ippsFIRGetDlyLine, the corresponding filter state structure must be initialized, for example
by calling the functions FIRInitAlloc or FIRMRInitAlloc.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pState pointer is NULL.

ippStsContextMatchErr            Indicates an error when the state identifier is incorrect.

FIRSetDlyLine
Sets the delay line contents in the FIR filter state
structure.

Syntax
IppStatus ippsFIRSetDlyLine_32f(IppsFIRState_32f* pState, const Ipp32f* pDlyLine       );
IppStatus ippsFIRSetDlyLine_64f(IppsFIRState_64f* pState, const Ipp64f* pDlyLine       );

   260
---------------------Page 261---------------------

                                                                         Filtering Functions  6 

IppStatus ippsFIRSetDlyLine32s_16s(IppsFIRState32s_16s* pState, const Ipp16s*
pDlyLine);
IppStatus ippsFIRSetDlyLine32f_16s(IppsFIRState32f_16s* pState, const Ipp16s*
pDlyLine);
IppStatus ippsFIRSetDlyLine64f_16s(IppsFIRState64f_16s* pState, const Ipp16s*
pDlyLine);
IppStatus ippsFIRSetDlyLine64f_32s(IppsFIRState64f_32s* pState, const Ipp32s*
pDlyLine);
IppStatus ippsFIRSetDlyLine64f_32f(IppsFIRState64f_32f* pState, const Ipp32f*
pDlyLine);

IppStatus ippsFIRSetDlyLine_32fc(IppsFIRState_32fc* pState, const Ipp32fc* pDlyLine      );
IppStatus ippsFIRSetDlyLine_64fc(IppsFIRState_64fc* pState, const Ipp64fc* pDlyLine      );
IppStatus ippsFIRSetDlyLine32sc_16sc(IppsFIRState32sc_16sc* pState, const Ipp16sc*
pDlyLine);
IppStatus ippsFIRSetDlyLine32fc_16sc(IppsFIRState32fc_16sc* pState, const Ipp16sc*
pDlyLine);
IppStatus ippsFIRSetDlyLine64fc_16sc(IppsFIRState64fc_16sc* pState, const Ipp16sc*
pDlyLine);
IppStatus ippsFIRSetDlyLine64fc_32sc(IppsFIRState64fc_32sc* pState, const Ipp32sc*
pDlyLine);
IppStatus ippsFIRSetDlyLine64fc_32fc(IppsFIRState64fc_32fc* pState, const Ipp32fc*
pDlyLine);
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsFIRSetDlyLine_16s(IppsFIRState_16s* pState, const Ipp16s* pDlyLine     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                      Pointer to the FIR filter state structure.

pDlyLine                    Pointer to the array holding the delay line values.

Description
The function ippsFIRSetDlyLine_16s is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function copies the delay line values from pDlyLine and stores them into the state structure pState.
The source array pDlyLine must contain samples in the reverse order as compared to the order of samples
in the source vector.
Before calling ippsFIRGetDlyLine the corresponding filter state structure must be initialized by calling the 
FIRInitAlloc or FIRMRInitAlloc.

                                                                                        261
---------------------Page 262---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                    Indicates no error.

ippStsNullPtrErr               Indicates an error when the pState pointer is NULL.

ippStsContextMatchErr          Indicates an error when the state identifier is incorrect.

FIROne
DEPRECATED. Filters a single sample through a FIR
filter.

Syntax
Case 1: Integer sample
IppStatus ippsFIROne_32s_Sfs(Ipp32s src, Ipp32s* pDstVal, IppsFIRState_32s* pState, int
scaleFactor);
IppStatus ippsFIROne32s_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, IppsFIRState32s_16s*
pState, int scaleFactor);
IppStatus ippsFIROne32f_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, IppsFIRState32f_16s*
pState, int scaleFactor);
IppStatus ippsFIROne64f_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, IppsFIRState64f_16s*
pState, int scaleFactor);
IppStatus ippsFIROne32sc_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, IppsFIRState32sc_16sc*
pState, int scaleFactor);
IppStatus ippsFIROne32fc_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, IppsFIRState32fc_16sc*
pState, int scaleFactor);
IppStatus ippsFIROne64fc_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, IppsFIRState64fc_16sc*
pState, int scaleFactor);
IppStatus ippsFIROne64fc_32sc_Sfs(Ipp32sc src, Ipp32sc* pDstVal, IppsFIRState64fc_32sc*
pState, int scaleFactor);
IppStatus ippsFIROne_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, IppsFIRState_16s* pState, int
scaleFactor);
IppStatus ippsFIROne64f_32s_Sfs(Ipp32s src, Ipp32s* pDstVal, IppsFIRState64f_32s*
pState, int scaleFactor);
Case 2: Floating point sample
IppStatus ippsFIROne64f_32f(Ipp32f src, Ipp32f* pDstVal, IppsFIRState64f_32f* pState  );
IppStatus ippsFIROne64fc_32fc(Ipp32fc src, Ipp32fc* pDstVal, IppsFIRState64fc_32fc*
pState);
IppStatus ippsFIROne_32f(Ipp32f src, Ipp32f* pDstVal, IppsFIRState_32f* pState  );
IppStatus ippsFIROne_32fc(Ipp32fc src, Ipp32fc* pDstVal, IppsFIRState_32fc* pState  );
IppStatus ippsFIROne_64f(Ipp64f src, Ipp64f* pDstVal, IppsFIRState_64f* pState  );
IppStatus ippsFIROne_64fc(Ipp64fc src, Ipp64fc* pDstVal, IppsFIRState_64fc* pState  );

Include Files
ipps.h

  262
---------------------Page 263---------------------

                                                                               Filtering Functions  6 

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the FIR filter state structure.

src                           Input sample.

pDstVal                       Pointer to the output sample.

scaleFactor                   Scale factor, refer to Integer Scaling.

Description
The function ippsFIROne is deprecated. This function is obsolete and will be removed in a future release.
Use vector function with vector length = 1 instead. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function filters a single sample src through a single-rate filter and stores the result in pDstVal. The
filter parameters are specified in pState. The output of the integer sample is scaled according to
scaleFactor  and can be saturated. In the following definition of the FIR filter, the sample to be filtered is
denoted x(n) and the taps are denoted h(i).
The return value y(n) is defined by the formula for a single-rate filter:
 

 
Before calling ippsFIROne, initialize the corresponding filter state by calling FIRInitAlloc. Specify the number
of taps tapsLen, the tap values in pTaps, and the delay line values in pDlyLine beforehand.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when one of the specified pointers is  NULL.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

FIR
Filters a source vector through a single-rate or multi-
rate FIR filter.

Syntax
Case 1: Not-in-place operation on integer samples
IppStatus ippsFIR_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
IppsFIRState_16s* pState, int scaleFactor      );
IppStatus ippsFIR32s_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
IppsFIRState32s_16s* pState, int scaleFactor       );
IppStatus ippsFIR64f_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
IppsFIRState64f_16s* pState, int scaleFactor       );

                                                                                               263
---------------------Page 264---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsFIR64f_32s_Sfs(const Ipp32s* pSrc, Ipp32s* pDst, int numIters,
IppsFIRState64f_32s* pState, int scaleFactor);
IppStatus ippsFIR32sc_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int numIters,
IppsFIRState32sc_16sc* pState, int scaleFactor);
IppStatus ippsFIR32fc_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int numIters,
IppsFIRState32fc_16sc* pState, int scaleFactor);
IppStatus ippsFIR64fc_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int numIters,
IppsFIRState64fc_16sc* pState, int scaleFactor);
IppStatus ippsFIR64fc_32sc_Sfs(const Ipp32sc* pSrc, Ipp32sc* pDst, int numIters,
IppsFIRState64fc_32sc* pState, int scaleFactor);
IppStatus ippsFIR32f_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
IppsFIRState32f_16s* pState, int scaleFactor);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsFIR_32s_Sfs(const Ipp32s* pSrc, Ipp32s* pDst, int numIters,
IppsFIRState_32s* pState, int scaleFactor);
Case 2 Not-in-place operation on floating point samples
IppStatus ippsFIR_32f(const Ipp32f* pSrc, Ipp32f* pDst, int numIters, IppsFIRState_32f*
pState);
IppStatus ippsFIR_64f(const Ipp64f* pSrc, Ipp64f* pDst, int numIters, IppsFIRState_64f*
pState);
IppStatus ippsFIR_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int numIters,
IppsFIRState_32fc* pState);
IppStatus ippsFIR_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int numIters,
IppsFIRState_64fc* pState);
IppStatus ippsFIR64f_32f(const Ipp32f* pSrc, Ipp32f* pDst, int numIters,
IppsFIRState64f_32f* pState);
IppStatus ippsFIR64fc_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int numIters,
IppsFIRState64fc_32fc* pState);
Case 3 In-place operation on integer samples
IppStatus ippsFIR64fc_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, IppsFIRState64fc_16sc*
pState, int scaleFactor);
IppStatus ippsFIR64fc_32sc_ISfs(Ipp32sc* pSrcDst, int numIters, IppsFIRState64fc_32sc*
pState, int scaleFactor);
IppStatus ippsFIR32f_16s_ISfs(Ipp16s* pSrcDst, int numIters, IppsFIRState32f_16s*
pState, int scaleFactor);
IppStatus ippsFIR32fc_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, IppsFIRState32fc_16sc*
pState, int scaleFactor);
IppStatus ippsFIR64f_16s_ISfs(Ipp16s* pSrcDst, int numIters, IppsFIRState64f_16s*
pState, int scaleFactor);
IppStatus ippsFIR64f_32s_ISfs(Ipp32s* pSrcDst, int numIters, IppsFIRState64f_32s*
pState, int scaleFactor);
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsFIR_16s_ISfs(Ipp16s* pSrcDst, int numIters, IppsFIRState_16s* pState, int
scaleFactor);

  264
---------------------Page 265---------------------

                                                                             Filtering Functions  6 

IppStatus ippsFIR_32s_ISfs(Ipp32s* pSrcDst, int numIters, IppsFIRState_32s* pState, int
scaleFactor );
IppStatus ippsFIR32s_16s_ISfs(Ipp16s* pSrcDst, int numIters, IppsFIRState32s_16s*
pState, int scaleFactor  );
IppStatus ippsFIR32sc_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, IppsFIRState32sc_16sc*
pState, int scaleFactor  );
Case 4 In-place operation on floating point samples
IppStatus ippsFIR64f_32f_I(Ipp32f* pSrcDst, int numIters, IppsFIRState64f_32f* pState          );
IppStatus ippsFIR64fc_32fc_I(Ipp32fc* pSrcDst, int numIters, IppsFIRState64fc_32fc*
pState);
IppStatus ippsFIR_32f_I(Ipp32f* pSrcDst, int numIters, IppsFIRState_32f* pState          );
IppStatus ippsFIR_64f_I(Ipp64f* pSrcDst, int numIters, IppsFIRState_64f* pState          );
IppStatus ippsFIR_32fc_I(Ipp32fc* pSrcDst, int numIters, IppsFIRState_32fc* pState          );
IppStatus ippsFIR_64fc_I(Ipp64fc* pSrcDst, int numIters, IppsFIRState_64fc* pState          );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                       Pointer to the FIR filter state structure.

pSrc                         Pointer to the source vector.

pDst                         Pointer to the destination vector.

pSrcDst                      Pointer to the source and destination vector for the in-place
                             operation.
numIters                     Number of iterations.

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
Functions ippsFIR_16s_ISfs , ippsFIR_16s_Sfs , ippsFIR_32s_ISfs , and ippsFIR_32s_Sfs  are
deprecated. These functions are obsolete and will be removed in a future release. Use the following link for
details: http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function filters a source vector pSrc or pSrcDst through a FIR or stream FIR filters, and stores the
results in pDst or pSrcDst, respectively. Both filters can be single-rate or multi-rate. The filter state
structure pState defines the type of the filter and specifies its parameters. It must be initialized before
calling the function ippsFIR using one of the initializing functions (FIRInitAlloc, FIRMRStreamInitAlloc, 
FIRInit, FIRStreamInit for single-rate filters, or FIRMRStreamInitAlloc, FIRMRStreamInitAlloc, FIRMRInit, 
FIRMRStreamInit for multi-rate filters).
The parameter numIters specifies the number of iterations associated with the number of samples to be
filtered by the function. The length of the source and destination vectors depends on this parameter.
For single-rate FIR filters, the length of the pSrc (pSrcDst) and pDst (pSrcDst) is equal to numIters.

                                                                                            265
---------------------Page 266---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

For single-rate stream FIR filters, the length of the pSrc (pSrcDst) is equal to numIters+tapLen -1, and
length of the pDst (pSrcDst) is equal to numIters.
For multi-rate FIR filters, the length of the pSrc is equal to numIters*downFactor, the length of the pDst is
equal tonumIters *upFactor .
For multi-rate stream FIR filters, the length of the pSrc is equal to numIters*downFactor + (tapLen-1)/
upFactor+ 1 , the length of the pDst is equal to numIters *upFactor.
In the following definition of the FIR filter, the sample to be filtered is denoted x(n), the taps are denoted
h(i), and the return value is y(n).
The return value y(n) is defined by the formula for a single-rate filter:
For a single-rate filter the return value y(n) is defined by the following formula:
 

 
The results are identical to numIters consecutive calls to the function FIROne.
When the function completes calculation, it updates the delay line values stored in the state structure (for
structures with delay line only).
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 above-
mentioned three steps. Thus, the function does not create an internal (upFactor*numIters*downFactor)-
size buffer to store the upsampling result.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when one of the specified pointers is  NULL .

ippStsSizeErr                       Indicates an error when  numIters   is less or equal to 0.

ippStsContextMatchErr               Indicates an error when the state identifier is incorrect.

Example
The code example below illustrates single-rate filtering with the function ippsFIR_32f.
#undef NUMITERS 
#define NUMITERS 150
     int n;
     IppStatus status;
     IppsIIRState_32f *ictx;
     IppsFIRState_32f *fctx;
     IppsFIRState_32f *fsctx;
     Ipp32f *x = ippsMalloc_32f(NUMITERS+10),
            *y = ippsMalloc_32f(NUMITERS),
            *z = ippsMalloc_32f(NUMITERS);
     const float taps[] = {
         0.0051f, 0.0180f, 0.0591f, 0.1245f, 0.1869f, 0.2127f, 0.1869f,
         0.1245f, 0.0591f, 0.0180f, 0.0051f, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
     };
     for (n =0;n<NUMITERS;++n)x[n]=(float)sin(IPP_2PI *n *0.2);
     ippsIIRInitAlloc_32f( &ictx, taps, 10, NULL );
     ippsFIRInitAlloc_32f( &fctx, taps, 11, NULL );

   266
---------------------Page 267---------------------

                                                                           Filtering Functions  6 

     ippsFIRStreamInitAlloc_32f( &fsctx, taps, 11 );
     status = ippsIIR_32f( x, y, NUMITERS, ictx);
     printf_32f("IIR 32f output + 120 =", y + 120, 5, status);
     ippsIIRFree_32f(ictx);
     status = ippsFIR_32f( x, z, NUMITERS, fctx );
     printf_32f("FIR 32f output + 120 =", z + 120, 5, status);
     ippsFIRFree_32f(fctx);
     status = ippsFIR_32f( x, z, NUMITERS, fsctx );
     printf_32f("FIR 32f output + 110 =", z + 110, 5, status);
     ippsFIRFree_32f(fsctx);
     ippsFree(z);
     ippsFree(y);
     ippsFree(x);
     return status; 
}

Output:
    IIR 32f output + 120 = 0.000000 0.049896 0.030838 -0.030838 -0.049896
    FIR 32f output + 120 = 0.000000 0.049896 0.030838 -0.030838 -0.049896 
Matlab* Analog: 
    >> F = 0.2; N = 150; n = 0:N-1; x = sin(2*pi*n*F); 
    y = filter(fir1(10,0.15),1,x); y(121:125)

The code example below shows how to use multi-rate filter functions for vector interpolation (resizing).
IppsFIRState_32f *pState;
    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;
    Ipp32f pSrc[downFactor*numIters];
    Ipp32f pDst[upFactor  *numIters];
    IppStatus status;
    status = ippsFIRMRInitAlloc_32f ( &pState, pTaps, tapsLen, upFactor, upPhase, downFactor, 
downPhase, NULL);
    printf("ippsFIRMRInitAlloc_32f / status = %s\n", ippGetStatusString(status));
    if( ippStsNoErr != status) return -1;
    for(i=0;i<downFactor*numIters;i++){ pSrc[i] = 1;}
    status = ippsFIR_32f( pSrc, pDst, numIters, pState);
    printf("ippsFIR_32f / status = %s\n", ippGetStatusString(status));
    if( ippStsNoErr != status) return -1;
    status = ippsFIRFree_32f(pState );
    printf("ippsFIRFree_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;

FIROne_Direct
DEPRECATED. Directly filters a single sample through
a FIR filter.

                                                                                          267
---------------------Page 268---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Syntax
Case 1: Not-in-place operation on integer sample
IppStatus ippsFIROne_Direct_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, const Ipp16s*
pTapsQ15, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne32f_Direct_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, const Ipp32f*
pTaps, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne64f_Direct_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, const Ipp64f*
pTaps, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne64f_Direct_32s_Sfs(Ipp32s src, Ipp32s* pDstVal, const Ipp64f*
pTaps, int tapsLen, Ipp32s* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne32fc_Direct_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, const Ipp32fc*
pTaps, int tapsLen, Ipp16sc* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne64fc_Direct_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, const Ipp64fc*
pTaps, int tapsLen, Ipp16sc* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne64fc_Direct_32sc_Sfs(Ipp32sc src, Ipp32sc* pDstVal, const Ipp64fc*
pTaps, int tapsLen, Ipp32sc* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne32s_Direct_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, const Ipp32s*
pTaps, int tapsLen, int tapsFactor, Ipp16s* pDlyLine, int* pDlyLineIndex, int
scaleFactor);
IppStatus ippsFIROne32sc_Direct_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, const Ipp32sc*
pTaps, int tapsLen, int tapsFactor, Ipp16sc* pDlyLine, int* pDlyLineIndex, int
scaleFactor);
Case 2: Not-in-place operation on floating point sample
IppStatus ippsFIROne_Direct_32f(Ipp32f src, Ipp32f* pDstVal, const Ipp32f* pTaps, int
tapsLen, Ipp32f* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIROne_Direct_64f(Ipp64f src, Ipp64f* pDstVal, const Ipp64f* pTaps, int
tapsLen, Ipp64f* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIROne_Direct_32fc(Ipp32fc src, Ipp32fc* pDstVal, const Ipp32fc* pTaps,
int tapsLen, Ipp32fc* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIROne_Direct_64fc(Ipp64fc src, Ipp64fc* pDstVal, const Ipp64fc* pTaps,
int tapsLen, Ipp64fc* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIROne64f_Direct_32f(Ipp32f src, Ipp32f* pDstVal, const Ipp64f* pTaps,
int tapsLen, Ipp32f* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIROne64fc_Direct_32fc(Ipp32fc src, Ipp32fc* pDstVal, const Ipp64fc*
pTaps, int tapsLen, Ipp32fc* pDlyLine, int* pDlyLineIndex );
Case 3: In-place operation on integer sample
IppStatus ippsFIROne_Direct_16s_ISfs(Ipp16s* pSrcDstVal, const Ipp16s* pTaps, int
tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne32f_Direct_16s_ISfs(Ipp16s* pSrcDstVal, const Ipp32f* pTaps, int
tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne64f_Direct_16s_ISfs(Ipp16s* pSrcDstVal, const Ipp64f* pTaps, int
tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor );
IppStatus ippsFIROne64f_Direct_32s_ISfs(Ipp32s* pSrcDstVal, const Ipp64f* pTaps, int
tapsLen, Ipp32s* pDlyLine, int* pDlyLineIndex, int scaleFactor );

  268
---------------------Page 269---------------------

                                                                      Filtering Functions  6 

IppStatus ippsFIROne32fc_Direct_16sc_ISfs(Ipp16sc* pSrcDstVal, const Ipp32fc* pTaps,
int tapsLen, Ipp16sc* pDlyLine, int* pDlyLineIndex, int scaleFactor  );
IppStatus ippsFIROne64fc_Direct_16sc_ISfs(Ipp16sc* pSrcDstVal, const Ipp64fc* pTaps,
int tapsLen, Ipp16sc* pDlyLine, int* pDlyLineIndex, int scaleFactor  );
IppStatus ippsFIROne64fc_Direct_32sc_ISfs(Ipp32sc* pSrcDstVal, const Ipp64fc* pTaps,
int tapsLen, Ipp32sc* pDlyLine, int* pDlyLineIndex, int scaleFactor  );
IppStatus ippsFIROne32s_Direct_16s_ISfs(Ipp16s* pSrcDstVal, const Ipp32s* pTaps, int
tapsLen, int tapsFactor, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor  );
IppStatus ippsFIROne32sc_Direct_16sc_ISfs(Ipp16sc* pSrcDstVal, const Ipp32sc* pTaps,
int tapsLen, int tapsFactor, Ipp16sc* pDlyLine, int* pDlyLineIndex, int scaleFactor   );
Case 4: In-place operation on floating point sample
IppStatus ippsFIROne_Direct_32f_I(Ipp32f* pSrcDstVal, const Ipp32f* pTaps, int tapsLen,
Ipp32f* pDlyLine, int* pDlyLineIndex );
IppStatus ippsFIROne_Direct_64f_I(Ipp64f* pSrcDstVal, const Ipp64f* pTaps, int tapsLen,
Ipp64f* pDlyLine, int* pDlyLineIndex );
IppStatus ippsFIROne_Direct_32fc_I(Ipp32fc* pSrcDstVal, const Ipp32fc* pTaps, int
tapsLen, Ipp32fc* pDlyLine, int* pDlyLineIndex );
IppStatus ippsFIROne_Direct_64fc_I(Ipp64fc* pSrcDstVal, const Ipp64fc* pTaps, int
tapsLen, Ipp64fc* pDlyLine, int* pDlyLineIndex );
IppStatus ippsFIROne64f_Direct_32f_I(Ipp32f* pSrcDstVal, const Ipp64f* pTaps, int
tapsLen, Ipp32f* pDlyLine, int* pDlyLineIndex );
IppStatus ippsFIROne64fc_Direct_32fc_I(Ipp32fc* pSrcDstVal, const Ipp64fc* pTaps, int
tapsLen, Ipp32fc* pDlyLine, int* pDlyLineIndex );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

src                        Input sample.

pDstVal                    Pointer to the output sample.

pSrcDstVal                 Pointer to the input and output sample for in-place operation.

pTaps                      Pointer to the array containing the tap values. The number of
                           elements in the array is tapsLen.
pTapsQ15                   Pointer to the array containing the tap values, represented in Q0.15
                           format. The number of elements in the array is tapsLen.
tapsLen                    Number of elements in the array containing the tap values.

tapsFactor                 Scale factor for the integer taps.

pDlyLine                   Pointer to the array containing the delay line values. The number of
                           elements in the array is 2*tapsLen. Note that the delay line length
                           is different than that for FIR filters using state structure.

                                                                                     269
---------------------Page 270---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

pDlyLineIndex                 Pointer to the current delay line index.

scaleFactor                   Scale factor, refer to Integer Scaling.

Description
The function ippsFIROne_Direct  is deprecated. This function is obsolete and will be removed in a future
release. Use the FIR function with the State structure instead of this one. Use the following link for details:
http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function directly filters a single sample src or pSrcDstVal through a single-rate filter and stores the
result in pDstVal or pSrcDstVal. The values of filter coefficients (taps) are specified in the tapsLen-length
array pTaps. To scale integer taps, the tapsFactor value is used. The set of tapsLen input samples is
copied twice to the 2*tapsLen-length array pDlyLine. Double length of the delay line in direct FIR filters is
used to improve filter performance by decreasing the number of sample copyings. The current delay line
index is specified in the pDlyLineIndex. The output of the integer sample is scaled according to
scaleFactor  and can be saturated. In the following definition of the FIR filter, the sample to be filtered is
denoted x(n) and the taps are denoted h(i).
The return value y(n) is defined by the formula for a single-rate filter:
 

 

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when one of the specified pointers is NULL.

ippStsFIRLenErr                    Indicates an error when  tapsLen  is less than or equal to 0.

FIR_Direct
DEPRECATED. Directly filters a source vector through
a single-rate FIR filter.

Syntax
Case 1: Not-in-place operation on integer samples
IppStatus ippsFIR_Direct_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters, const
Ipp16s* pTapsQ15, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor            );
IppStatus ippsFIR32f_Direct_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
const Ipp32f* pTaps, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int
scaleFactor );
IppStatus ippsFIR64f_Direct_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
const Ipp64f* pTaps, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int
scaleFactor );
IppStatus ippsFIR64f_Direct_32s_Sfs(const Ipp32s* pSrc, Ipp32s* pDst, int numIters,
const Ipp64f* pTaps, int tapsLen, Ipp32s* pDlyLine, int* pDlyLineIndex, int
scaleFactor );

   270
---------------------Page 271---------------------

                                                                    Filtering Functions  6 

IppStatus ippsFIR32fc_Direct_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int numIters,
const Ipp32fc* pTaps, int tapsLen, Ipp16sc* pDlyLine, int* pDlyLineIndex, int
scaleFactor);
IppStatus ippsFIR64fc_Direct_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int numIters,
const Ipp64fc* pTaps, int tapsLen, Ipp16sc* pDlyLine, int* pDlyLineIndex, int
scaleFactor);
IppStatus ippsFIR64fc_Direct_32sc_Sfs(const Ipp32sc* pSrc, Ipp32sc* pDst, int numIters,
const Ipp64fc* pTaps, int tapsLen, Ipp32sc* pDlyLine, int* pDlyLineIndex, int
scaleFactor);

IppStatus ippsFIR32s_Direct_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
const Ipp32s* pTaps, int tapsLen, int tapsFactor, Ipp16s* pDlyLine, int* pDlyLineIndex,
int scaleFactor);
IppStatus ippsFIR32sc_Direct_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int numIters,
const Ipp32sc* pTaps, int tapsLen, int tapsFactor, Ipp16sc* pDlyLine, int*
pDlyLineIndex, int scaleFactor);
Case 2: Not-in-place operation on floating point samples
IppStatus ippsFIR_Direct_32f(const Ipp32f* pSrc, Ipp32f* pDst, int numIters, const
Ipp32f* pTaps, int tapsLen, Ipp32f* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIR_Direct_64f(const Ipp64f* pSrc, Ipp64f* pDst, int numIters, const
Ipp64f* pTaps, int tapsLen, Ipp64f* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIR_Direct_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int numIters, const
Ipp32fc* pTaps, int tapsLen, Ipp32fc* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIR_Direct_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int numIters, const
Ipp64fc* pTaps, int tapsLen, Ipp64fc* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIR64f_Direct_32f(const Ipp32f* pSrc, Ipp32f* pDst, int numIters, const
Ipp64f* pTaps, int tapsLen, Ipp32f* pDlyLine, int* pDlyLineIndex);
IppStatus ippsFIR64fc_Direct_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int numIters,
const Ipp64fc* pTaps, int tapsLen, Ipp32fc* pDlyLine, int* pDlyLineIndex);
Case 3: In-place operation on integer samples
IppStatus ippsFIR_Direct_16s_ISfs(Ipp16s* pSrcDst, int numIters, const Ipp16s*
pTapsQ15, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor);
IppStatus ippsFIR32f_Direct_16s_ISfs(Ipp16s* pSrcDst, int numIters, const Ipp32f*
pTaps, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor);
IppStatus ippsFIR64f_Direct_16s_ISfs(Ipp16s* pSrcDst, int numIters, const Ipp64f*
pTaps, int tapsLen, Ipp16s* pDlyLine, int* pDlyLineIndex, int scaleFactor);
IppStatus ippsFIR64f_Direct_32s_ISfs(Ipp32s* pSrcDst, int numIters, const Ipp64f*
pTaps, int tapsLen, Ipp32s* pDlyLine, int* pDlyLineIndex, int scaleFactor);
IppStatus ippsFIR32fc_Direct_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, const Ipp32fc*
pTaps, int tapsLen, Ipp16sc* pDlyLine, int* pDlyLineIndex, int scaleFactor);
IppStatus ippsFIR64fc_Direct_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, const Ipp64fc*
pTaps, int tapsLen, Ipp16sc* pDlyLine, int* pDlyLineIndex, int scaleFactor);
IppStatus ippsFIR64fc_Direct_32sc_ISfs(Ipp32sc* pSrcDst, int numIters, const Ipp64fc*
pTaps, int tapsLen, Ipp32sc* pDlyLine, int* pDlyLineIndex, int scaleFactor);

                                                                                  271
---------------------Page 272---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsFIR32s_Direct_16s_ISfs(Ipp16s* pSrcDst, int numIters, const Ipp32s*
pTaps, int tapsLen, int tapsFactor, Ipp16s* pDlyLine, int* pDlyLineIndex, int
scaleFactor);
IppStatus ippsFIR32sc_Direct_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, const Ipp32sc*
pTaps, int tapsLen, int tapsFactor, Ipp16sc* pDlyLine, int* pDlyLineIndex, int
scaleFactor);
Case 4: In-place operation on floating point samples
IppStatus ippsFIR_Direct_32f_I(Ipp32f* pSrcDst, int numIters, const Ipp32f* pTaps, int
tapsLen, Ipp32f* pDlyLine, int* pDlyLineIndex  );
IppStatus ippsFIR_Direct_64f_I(Ipp64f* pSrcDst, int numIters, const Ipp64f* pTaps, int
tapsLen, Ipp64f* pDlyLine, int* pDlyLineIndex  );
IppStatus ippsFIR_Direct_32fc_I(Ipp32fc* pSrcDst, int numIters, const Ipp32fc* pTaps,
int tapsLen, Ipp32fc* pDlyLine, int* pDlyLineIndex  );
IppStatus ippsFIR_Direct_64fc_I(Ipp64fc* pSrcDst, int numIters, const Ipp64fc* pTaps,
int tapsLen, Ipp64fc* pDlyLine, int* pDlyLineIndex  );
IppStatus ippsFIR64f_Direct_32f_I(Ipp32f* pSrcDst, int numIters, const Ipp64f* pTaps,
int tapsLen, Ipp32f* pDlyLine, int* pDlyLineIndex  );
IppStatus ippsFIR64fc_Direct_32fc_I(Ipp32fc* pSrcDst, int numIters, const Ipp64fc*
pTaps, int tapsLen, Ipp32fc* pDlyLine, int* pDlyLineIndex   );

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 output array.

pSrcDst                    Pointer to the source and destination vector for the in-place
                           operation.
numIters                   Number of iterations.

pTaps                      Pointer to the array containing the tap values. The number of
                           elements in the array is tapsLen.
pTapsQ15                   Pointer to the array containing the tap values, represented in Q0.15
                           format. The number of elements in the array is tapsLen.
tapsLen                    Number of elements in the array containing the tap values.

tapsFactor                 Scale factor for the integer taps.

pDlyLine                   Pointer to the array containing the delay line values. The number of
                           elements in the array is 2*tapsLen. Note that the delay line length
                           is different than that for FIR filters using state structure.
pDlyLineIndex              Pointer to the current delay line index.

scaleFactor                Scale factor, refer to Integer Scaling.

   272
---------------------Page 273---------------------

                                                                             Filtering Functions  6 

Description
The function ippsFIR_Direct is deprecated. This function is obsolete and will be removed in a future
release. Use the FIR function with the State structure instead of this one. Use the following link for details:
http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function filters an source vector pSrc or pSrcDst containing numIters samples through a single-rate
filter, and stores the resulting numIters samples in pDst or pSrcDst, respectively. The results are identical
to numIters consecutive calls to ippsFIROne_Direct. The values of filter coefficients (taps) are specified in
the tapsLen-length array pTaps. To scale integer taps the tapsFactor value is used. The set of tapsLen
input samples is copied to the 2*tapsLen-length array pDlyLine. Double length of the delay line in direct
FIR filters is used to improve filter performance by decreasing the number of sample copyings. The current
delay line index is specified in the pDlyLineIndex. The output of the integer sample is scaled according to
scaleFactor  and can be saturated.
In the following definition of the FIR filter, the sample to be filtered is denoted x(n), the taps are denoted
h(i), and the return value is y(n).
The return value y(n) is defined by the formula for a single-rate filter:
 

 

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsFIRLenErr                   Indicates an error when  tapsLen  is less than or equal to 0.

ippStsSizeErr                     Indicates an error when  numIters  is less than or equal to 0.

FIRMR_Direct
DEPRECATED. Directly filters a source vector through
a multi-rate FIR filter.

Syntax
Case 1: Not-in-place operation on integer samples
IppStatus ippsFIRMR32f_Direct_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
const Ipp32f* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int
downPhase, Ipp16s* pDlyLine, int scaleFactor     );
IppStatus ippsFIRMR64f_Direct_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
const Ipp64f* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int
downPhase, Ipp16s* pDlyLine, int scaleFactor     );
IppStatus ippsFIRMR64f_Direct_32s_Sfs(const Ipp32s* pSrc, Ipp32s* pDst, int numIters,
const Ipp64f* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int
downPhase, Ipp32s* pDlyLine, int scaleFactor     );
IppStatus ippsFIRMR32fc_Direct_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int
numIters, const Ipp32fc* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor,
int downPhase, Ipp16sc* pDlyLine, int scaleFactor      );

                                                                                            273
---------------------Page 274---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsFIRMR64fc_Direct_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int
numIters, const Ipp64fc* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor,
int downPhase, Ipp16sc* pDlyLine, int scaleFactor);
IppStatus ippsFIRMR64fc_Direct_32sc_Sfs(const Ipp32sc* pSrc, Ipp32sc* pDst, int
numIters, const Ipp64fc* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor,
int downPhase, Ipp32sc* pDlyLine, int scaleFactor);

IppStatus ippsFIRMR32s_Direct_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int numIters,
const Ipp32s* pTaps, int tapsLen, int tapsFactor, int upFactor, int upPhase, int
downFactor, int downPhase, Ipp16s* pDlyLine, int scaleFactor);
IppStatus ippsFIRMR32sc_Direct_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int
numIters, const Ipp32sc* pTaps, int tapsLen, int tapsFactor, int upFactor, int upPhase,
int downFactor, int downPhase, Ipp16sc* pDlyLine, int scaleFactor);
Case 2: Not-in-place operation on floating point samples
IppStatus ippsFIRMR_Direct_32f(const Ipp32f* pSrc, Ipp32f* pDst, int numIters, const
Ipp32f* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase,
Ipp32f* pDlyLine);
IppStatus ippsFIRMR64f_Direct_32f(const Ipp32f* pSrc, Ipp32f* pDst, int numIters, const
Ipp64f* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase,
Ipp32f* pDlyLine);
IppStatus ippsFIRMR_Direct_64f(const Ipp64f* pSrc, Ipp64f* pDst, int numIters, const
Ipp64f* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase,
Ipp64f* pDlyLine);
IppStatus ippsFIRMR_Direct_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int numIters, const
Ipp32fc* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase,
Ipp32fc* pDlyLine);
IppStatus ippsFIRMR64fc_Direct_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int numIters,
const Ipp64fc* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int
downPhase, Ipp32fc* pDlyLine);
IppStatus ippsFIRMR_Direct_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int numIters, const
Ipp64fc* pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase,
Ipp64fc* pDlyLine);
Case 3: In-place operation on integer samples
IppStatus ippsFIRMR32f_Direct_16s_ISfs(Ipp16s* pSrcDst, int numIters, const Ipp32f*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp16s*
pDlyLine, int scaleFactor);
IppStatus ippsFIRMR64f_Direct_16s_ISfs(Ipp16s* pSrcDst, int numIters, const Ipp64f*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp16s*
pDlyLine, int scaleFactor);
IppStatus ippsFIRMR64f_Direct_32s_ISfs(Ipp32s* pSrcDst, int numIters, const Ipp64f*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp32s*
pDlyLine, int scaleFactor);
IppStatus ippsFIRMR32fc_Direct_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, const Ipp32fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp16sc*
pDlyLine, int scaleFactor);
IppStatus ippsFIRMR64fc_Direct_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, const Ipp64fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp16sc*
pDlyLine, int scaleFactor);

  274
---------------------Page 275---------------------

                                                                      Filtering Functions  6 

IppStatus ippsFIRMR64fc_Direct_32sc_ISfs(Ipp32sc* pSrcDst, int numIters, const Ipp64fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp32sc*
pDlyLine, int scaleFactor);

IppStatus ippsFIRMR32s_Direct_16s_ISfs(Ipp16s* pSrcDst, int numIters, const Ipp32s*
pTaps, int tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int
downPhase, Ipp16s* pDlyLine, int scaleFactor );
IppStatus ippsFIRMR32sc_Direct_16sc_ISfs(Ipp16sc* pSrcDst, int numIters, const Ipp32sc*
pTaps, int tapsLen, int tapsFactor, int upFactor, int upPhase, int downFactor, int
downPhase, Ipp16sc* pDlyLine, int scaleFactor );
Case 4: In-place operation on floating point samples
IppStatus ippsFIRMR_Direct_32f_I(Ipp32f* pSrcDst, int numIters, const Ipp32f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp32f*
pDlyLine);
IppStatus ippsFIRMR64f_Direct_32f_I(Ipp32f* pSrcDst, int numIters, const Ipp64f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp32f*
pDlyLine);
IppStatus ippsFIRMR_Direct_64f_I(Ipp64f* pSrcDst, int numIters, const Ipp64f* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp64f*
pDlyLine);
IppStatus ippsFIRMR_Direct_32fc_I(Ipp32fc* pSrcDst, int numIters, const Ipp32fc* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp32fc*
pDlyLine);
IppStatus ippsFIRMR64fc_Direct_32fc_I(Ipp32fc* pSrcDst, int numIters, const Ipp64fc*
pTaps, int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp32fc*
pDlyLine);
IppStatus ippsFIRMR_Direct_64fc_I(Ipp64fc* pSrcDst, int numIters, const Ipp64fc* pTaps,
int tapsLen, int upFactor, int upPhase, int downFactor, int downPhase, Ipp64fc*
pDlyLine);

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.

pSrcDst                    Pointer to the source and destination vector for the in-place
                           operation.
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 output array.
pTaps                      Pointer to the array containing the tap values. The number of
                           elements in the array is tapsLen.

                                                                                    275
---------------------Page 276---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

tapsLen                        Number of elements in the array containing the tap values.

tapsFactor                     Scale factor for the integer taps.

pDlyLine                       Pointer to the array containing the delay line values. The number of
                               elements in the array is (tapsLen + upFactor - 1) / upFactor      .
upFactor                       Factor for upsampling the multi-rate signals.

downFactor                     Factor for downsampling the multi-rate signals.

upPhase                        Phase for upsampling the multi-rate signals.

downPhase                      Phase for downsampling the multi-rate signals.

scaleFactor                    Scale factor, refer to Integer Scaling.

Description
The function ippsFIRMR_Direct   is deprecated. This function is obsolete and will be removed in a future
release. Use the FIR function with the State structure instead of this one. Use the following link for details:
http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function filters an source vector pSrc or pSrcDst through a multi-rate filter, and stores the resulting
samples in pDst or pSrcDst, respectively. The values of filter coefficients (taps) are specified in the
tapsLen -length array pTaps. To scale integer taps the tapsFactor value is used. The array pDlyLine
specifies 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 above-mentioned three steps.
The parameter upFactor  is the factor by which the filtered signal is internally upsampled (see description of
the function SampleUp for more details). That is, upFactor-1 zeros are inserted between each sample of the
input signal.
The parameter upPhase  is the parameter which 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 obtained by filtering an upsampled input
signal, is internally downsampled (see description of the function SampleDown 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. The length of the delay line array pDlyLine is defined as (tapsLen +
upFactor - 1) / upFactor    . The output of the integer sample is scaled according to scaleFactor and can
be saturated.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when one of the specified pointers is  NULL.

ippStsFIRLenErr                     Indicates an error when  tapsLen  is less than or equal to 0.

ippStsSizeErr                       Indicates an error when  numIters   is less than or equal to 0.

ippStsFIRMRFactorErr                Indicates an error when  upFactor   (downFactor ) is less than or
                                    equal to 0.
ippStsFIRMRPhaseErr                 Indicates an error when  upPhase  (downPhase  ) is negative, or
                                    greater than or equal to upFactor   (downFactor ).

   276
---------------------Page 277---------------------

                                                                              Filtering Functions  6 

FIRSparseInit
Initializes a sparse FIR filter structure.

Syntax
IppStatus ippsFIRSparseInit_32f(IppsFIRSparseState_32f** ppState, const Ipp32f*
pNZTaps, const Ipp32s* pNZTapPos, int nzTapsLen, const Ipp32f* pDlyLine, Ipp8u*
pBuffer );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pNZTaps                       Pointer to the array containing the non-zero tap values. The number
                              of elements in the array is nzTapsLen.
pNZTapPos                     Pointer to the array containing positions of the non-zero tap values.
                              The number of elements in the array is  nzTapsLen .
nzTapsLen                     Number of elements in the array with non-zero tap values.

pDlyLine                      Pointer to the array containing the delay line values.

ppState                       Double pointer to the sparse FIR state structure.

pBuffer                       Pointer to the external buffer for the sparse FIR state structure.

Description
This function initializes a sparse FIR filter state structure ppState in the external buffer pBuffer. The size of
this buffer must be computed previously by calling the function FIRSparseGetStateSize. The initialization
function copies the values of filter coefficients from the array pNZTaps containing nzTapsLen non-zero taps
and their positions from the array pNZTapPos into the state structure ppState. The array pDlyLine
specifies the delay line values. The number of elements in this array is pNZTapPos[nzTapsLen -1]. If the
pointer to the array pDlyLine is not NULL, the array contents are copied into the state structure ppState,
otherwise the delay line values in the state structure are initialized to 0.

      NOTE
      The values of nzTapsLen and pNZTapPos[nzTapsLen -1]    must be equal to those specified in the
      function FIRSparseGetStateSize.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error if one of the pointers ppState, pNZTaps,
                                   pNZTapPos , or pBuffer is NULL.
ippStsFIRLenErr                    Indicates an error if nxTapsLen is less than or equal to 0.

ippStsSparseErr                    Indicates an error if positions of the non-zero taps are not in
                                   ascending order, or are negative or repetitive.

                                                                                             277
---------------------Page 278---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

FIRSparseGetStateSize
Computes the size of the external buffer for the
sparse FIR filter structure.

Syntax
IppStatus ippsFIRSparseGetStateSize_32f(int nzTapsLen, int order, int* pStateSize           );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

nzTapsLen                     Number of elements in the array containing the non-zero tap
                              values.
order                         Order of the sparse FIR filter.

pStateSize                    Pointer to the computed value of the external buffer.

Description
This function computes the size of the external buffer for a sparse FIR filter structure that is required for the
function ippsFIRSparseInit . Computation is based on the specified number of non-zero filter coefficients
nzTapsLen  and filter order order that is equal to the number of elements in the delay line pNZTapPos
[nzTapsLen -1]   (see description of the function FIRSparseInit). The result value is stored in the
pStateSize .

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error if pStateSize pointer is NULL.

ippStsFIRLenErr                    Indicates an error if nzTapsLen or order is less than or equal to
                                   0; or nzTapsLen  is more than order .

FIRSparse
Filters a source vector through a sparse FIR filter.

Syntax
IppStatus ippsFIRSparse_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len,
IppsFIRSparseState_32f* pState    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

   278
---------------------Page 279---------------------

                                                                               Filtering Functions  6 

Parameters

pState                        Pointer to the sparse FIR filter state structure.

pSrc                          Pointer to the source vector.

pDst                          Pointer to the destination vector.

len                           Number of elements that are filtered.

Description
This function applies the sparse FIR filter to the len elements of the source vector pSrc, and stores the
results in pDst. The filter parameters - the number of non-zero taps nzTapsLen, their values pNZTaps and
their positions pNZTapPos, and the delay line values pDlyLine - are specified in the sparse FIR filter
structure pState that should be previously initialized by calling the function FIRSparseInit.
In the following definition of the sparse FIR filter, the sample to be filtered is denoted x(n), the non-zero
taps are denoted pNZTaps(i), their positions are denoted pNZTapPos(i) and the return value is y(n).
The return value y(n) is defined by the formula for a sparse FIR filter:
 

 
After the function has performed calculations, it updates the delay line values stored in the state.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error if one of the specified pointers is NULL.

ippStsSizeErr                      Indicates an error if len is less or equal to 0.

Example
The example below shows how to use the sparse FIR filter functions.
int buflen; 
Ipp8u *buf; 
int nzTapsLen = 5; //number of non-zero taps 
Ipp32f nzTaps [] = {0.5, 0.4, 0.3, 0.2, 0.1};  //non-zero taps values 
Ipp32s nzTapsPos[] = {0, 10, 20, 30, 40};  //non-zero tap positions 
IppsFIRSparseState_32f* firState; 
Ipp32f *src, *dst;

/* ........................... */
ippsFIRSparseGetStateSize_32f(nzTapsLen, nzTapsPos [nzTapsLen - 1], &buflen); 
buf = ippsMalloc_8u(buflen); 
ippsFIRSparseInit_32f(&firState, nzTaps, nzTapsPos, nzTapsLen, NULL, buf);

/* .... initializing src somehow .... */
ippsFIRSparse_32f(src, dst, len, firState);

/*dst[i]=src[i]*0.5 + src[i-10]*0.4 + src[i-20]*0.3 + src[i-30]*0.2 + src[i-40]*0.1 */

/* ...........................*/
ippsFree(buf);

                                                                                               279
---------------------Page 280---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Examples of Using FIR Functions
The code examples below demonstrate how to use the ippsFIRSR function:
• Standard FIR Filtering with an Not-in-place Destination
• Standard FIR Filtering with an In-place Destination
• Stream FIR Filtering with an Not-in-place Destination
• Stream FIR Filtering with an In-place Destination
• Standard FIR Filtering with an Not-in-place Destination and Threading
• Standard FIR Filtering with an In-place Destination and Threading

Standard FIR Filtering with an Not-in-place Destination

 Type of FIR Filter       Destination              Source Delay Line       Threading

 standard                not-in-place             zero                     none

#define LEN 1024
#define TAPS_LEN 8

IppsFIRSpec_32f *pSpec;
float           *src, *dst, *dly, *taps;
Ipp8u           *buf;
int             specSize, bufSize, initSize;

//get sizes of the spec structure and the work buffer
ippsFIRSRGetSize_32f(TAPS_LEN, ippAlgDirect, &specSize, &bufSize );

src   = malloc_32f(LEN);
dst   = malloc_32f(LEN);
dly   = malloc_32f(TAPS_LEN-1);
taps  = malloc_32f(TAPS_LEN);
pSpec = (IppsFIRSpec_32f*)malloc_8u(specSize);
buf   = malloc_8u(bufSize);

//initialize the spec structure
ippsFIRSRInit_32f( taps, TAPS_LEN, ippAlgDirect, pSpec );
//apply the FIR filter
ippsFIRSR_32f(src, dst, LEN,  pSpec,  NULL, dly,  buf);

Standard FIR Filtering with an In-place Destination

 Type of FIR Filter       Destination              Source Delay Line       Threading

 standard                in-place                 zero                     none

#define LEN 1024
#define TAPS_LEN 8

IppsFIRSpec_32f *pSpec;
float           *src, *dst, *dly, *taps;
Ipp8u           *buf;
int             specSize, bufSize, initSize;

//get sizes of the spec structure and the work buffer
ippsFIRSRGetSize_32f(TAPS_LEN, ippAlgDirect, &specSize, &bufSize );

src   = malloc_32f(LEN);
dst   = src;
dly   = malloc_32f(TAPS_LEN-1);

   280
---------------------Page 281---------------------

                                                                          Filtering Functions  6 

taps  = malloc_32f(TAPS_LEN);
pSpec = (IppsFIRSpec_32f*)malloc_8u(specSize);
buf   = malloc_8u(bufSize);

//initialize the spec structure
ippsFIRSRInit_32f( taps, TAPS_LEN, ippAlgDirect, pSpec );
//apply the FIR filter
ippsFIRSR_32f(src, dst, LEN,  pSpec,  NULL, dly,  buf);

Stream FIR Filtering with an Not-in-place Destination

 Type of FIR Filter      Destination             Source Delay Line       Threading

 stream                  not-in-place           src                     none

#define LEN 1024
#define TAPS_LEN 8

IppsFIRSpec_32f *pSpec;
float           *src, *dst, *dly, *taps;
Ipp8u           *buf;
int             specSize, bufSize, initSize;

//get sizes of the spec structure and the work buffer
ippsFIRSRGetSize_32f(TAPS_LEN, ippAlgDirect, &specSize, &bufSize );

src   = malloc_32f(LEN+TAPS_LEN-1);
dst   = malloc_32f(LEN);
taps  = malloc_32f(TAPS_LEN);
pSpec = (IppsFIRSpec_32f*)malloc_8u(specSize);
buf   = malloc_8u(bufSize);

//initialize the spec structure
ippsFIRSRInit_32f( taps, TAPS_LEN, ippAlgDirect, pSpec );
//apply the FIR filter
ippsFIRSR_32f(src+TAPS_LEN-1, dst, LEN,  pSpec,  src, NULL,  buf);

Stream FIR Filtering with an In-place Destination

 Type of FIR Filter      Destination             Source Delay Line       Threading

 stream                  in-place               src                     none

#define LEN 1024
#define TAPS_LEN 8

IppsFIRSpec_32f *pSpec;
float           *src, *dst, *dly, *taps;
Ipp8u           *buf;
int             specSize, bufSize, initSize;

//get sizes of the spec structure and the work buffer
ippsFIRSRGetSize_32f(TAPS_LEN, ippAlgDirect, &specSize, &bufSize );

src   = malloc_32f(LEN+TAPS_LEN-1);
dst   = src;
taps  = malloc_32f(TAPS_LEN);
pSpec = (IppsFIRSpec_32f*)malloc_8u(specSize);
buf   = malloc_8u(bufSize);

//initialize the spec structure

                                                                                         281
---------------------Page 282---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippsFIRSRInit_32f( taps, TAPS_LEN, ippAlgDirect, pSpec );
//apply the FIR filter
ippsFIRSR_32f(src+TAPS_LEN-1, dst, LEN,  pSpec,  src, NULL,  buf);

Standard FIR Filtering with an Not-in-place Destination and Threading

 Type of FIR Filter      Destination             Source Delay Line       Threading

 standard                not-in-place            zero                    NTHREADS

#define LEN 1024
#define TAPS_LEN 8
#define DLY_LEN TAPS_LEN-1
#define NTHREADS 32

float *s, *d, *dlyIn, *dlyOut, *taps;
unsigned char *initBuf, *buf;
IppsFIRSpec_32f* pSpec;
int specSize, bufSize, initSize;
int i, num_threads, tlen, ttail;

//get sizes of the spec structure and the work buffer
ippsFIRSRGetSize_32f(TAPS_LEN, ippAlgDirect, &specSize, &bufSize );

src    = malloc_32f(LEN);
dst    = malloc_32f(LEN);
dlyOut = malloc_32f(TAPS_LEN-1);
taps   = malloc_32f(TAPS_LEN);
pSpec  = malloc_8u(specSize);
buf    = malloc_8u(bufSize);

//initialize the spec structure
ippsFIRSRInit_32f( taps, TAPS_LEN, ippAlgDirect, pSpec );
tlen  = LEN / NTHREADS;
ttail = LEN % NTHREADS;
for(i=0;i< NTHREADS;i++) {//this cycle means parallel region
 Ipp32f* s   = src+i*tlen;
 Ipp32f* d   = dst+i*tlen;
 int     len = tlen+((i==NTHREADS–1)?ttail:0);
 Ipp8u*  b   = buf+i*bufSize;
 if( i == 0) 
     ippsFIR_32f(s, d, len, pSpec, NULL,           NULL  , b);
 else if (i == NTHREADS - 1)
     ippsFIR_32f(s, d, len, pSpec, s-(TAPS_LEN-1), dlyOut, b);
 else
     ippsFIR_32f(s, d, len, pSpec, s-(TAPS_LEN-1), NULL  , b);
}

Standard FIR Filtering with an In-place Destination and Threading

 Type of FIR Filter      Destination             Source Delay Line       Threading

 standard                in-place                zero                    NTHREADS

#define LEN 1024
#define TAPS_LEN 8
#define DLY_LEN TAPS_LEN-1
#define NTHREADS 32

float *src, *dst,  *dlyOut, *taps;
float* tdly[NTHREADS];

   282
---------------------Page 283---------------------

                                                                           Filtering Functions  6 

unsigned char *buf;
IppsFIRSpec_32f* pSpec;
int specSize, bufSize, ;
int i,tlen, ttail;

//get sizes of the spec structure and the work buffer
ippsFIRSRGetSize_32f(TAPS_LEN, ippAlgDirect, &specSize, &bufSize );

src    = malloc_32f(LEN);
dst    = malloc_32f(LEN);
dlyOut = malloc_32f(TAPS_LEN-1);
taps   = malloc_32f(TAPS_LEN);
pSpec  = malloc_8u(specSize);
buf    = malloc_8u(bufSize);

//initialize the spec structure
ippsFIRSRInit_32f( taps, TAPS_LEN, ippAlgDirect, pSpec );
tlen  = LEN / NTHREADS;
ttail = LEN % NTHREADS;
tdly    = malloc_32f((TAPS_LEN-1)*(num_threads-1));

for(i=1;i<num_threads;i++){//cycle in main thread
  tdly[i]  = malloc_32f(TAPS_LEN-1);
  memcpy_32f(src+i*tlen-(TAPS_LEN-1), tdly[i], TAPS_LEN-1);
}
for(i=0;i< NTHREADS;i++) {//this cycle means parallel region
 Ipp32f* s   = src+i*tlen;
 Ipp32f* d   = dst+i*tlen;
 int     len = tlen+((i==NTHREADS–1)?ttail:0);
 Ipp8u*  b   = buf+i*bufSize;
 if( i == 0) 
     ippsFIR_32f(s, d, len, pSpec, NULL,    NULL  , b);
 else if (i == NTHREADS - 1)
     ippsFIR_32f(s, d, len, pSpec, tdly[i], dlyOut, b);
 else
     ippsFIR_32f(s, d, len, pSpec, tdly[i], NULL  , b);
}

FIR Filter Coefficient Generating Functions
The functions described in this section compute coefficients (tap values) for different FIR filters by windowing
the ideal infinite filter coefficients.

FIRGenLowpass
Computes lowpass FIR filter coefficients.

Syntax
IppStatus ippsFIRGenLowpass_64f(Ipp64f rFreq, Ipp64f* taps, int tapsLen, IppWinType
winType, IppBool doNormal  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                         283
---------------------Page 284---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

rFreq                        Normalized cutoff frequency, must be in the range (0, 0.5).

pTaps                        Pointer to the array where computed tap values are stored. The
                             number of elements in the array is  tapsLen .
tapsLen                      Number of elements in the array containing the tap values; must be
                             equal or greater than 5.
winType                      Specifies what type of window is used in computations. The   winType
                             must have one of the following values:
                             •  ippWinBartlett   - Bartlett window
                             •  ippWinBlackman   - Blackman window
                             •  ippWinHamming   - Hamming window
                             •  ippWinHann   - Hann window

doNormal                     Specifies normalized or non-normalized sequence of the filter
                             coefficients is computed. The doNormal  must have one of the
                             following values:
                             •  ippTrue  for normalized sequence of coefficients
                             •  ippFalse  for non-normalized sequence of coefficients

Description
This function computes tapsLen coefficients for lowpass FIR filter with the cutoff frequency rFreq by
windowing the ideal infinite filter coefficients. The quality of filtering is defined by the number of coefficients.
The parameter winType specifies the type of the window. For more information on window types used by the
function, see Understanding Window Functions. The computed coefficients are stored in the array pTaps.
For more information about the used algorithm, see [MIT 93].

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pTaps  pointer is NULL.

ippStsSizeErr                     Indicates an error when the  tapsLen  is less than 5, or rFreq is
                                  out of range.

Example
The example below shows how to use the function ippsFIRGenLowpass.
void func_firgenlowpass() 
{    
    int len = 512;
    Ipp64f pDst[512];
    Ipp64f magn = 4095;
    Ipp64f rFreq = 0.2;
    int tapslen = 27;
    int numIters = 512;        
    IppsFIRState_64f* pState;
    IppStatus st;

    Ipp64f* FIRDst = ippsMalloc_64f(512*sizeof(Ipp64f));
    Ipp64f* taps = ippsMalloc_64f(tapslen*sizeof(Ipp64f));
    Ipp64f* pDL = ippsMalloc_64f(tapslen*sizeof(Ipp64f));

   284
---------------------Page 285---------------------

                                                                         Filtering Functions  6 
    ippsZero_64f(pDL,tapslen);
    //generate source vector
    ippsVectorJaehne_64f(pDst, len, magn);// create a Jaehne vector
    //computes tapsLen coefficients for lowpass FIR filter
    ippsFIRGenLowpass_64f(rFreq, taps, tapslen, ippWinBartlett, ippTrue);
                printf("Generated taps:\n");
                for( i = 0; i < tapslen; i++) printf("%f,", taps[i] );
                printf("\n");
    ippsFIRInitAlloc_64f(&pState, taps,tapslen, pDL);
    //filter an input vector
    ippsFIR_64f(pDst, FIRDst, numIters, pState); 
} 

Result:
 

 

FIRGenHighpass
Computes highpass FIR filter coefficients.

Syntax
IppStatus ippsFIRGenHighpass_64f(Ipp64f rFreq, Ipp64f* taps, int tapsLen, IppWinType
winType, IppBool doNormal  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h

                                                                                        285
---------------------Page 286---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Libraries: ippcore.lib, ippvm.lib

Parameters

rFreq                        Normalized cutoff frequency, must be in the range (0, 0.5).

pTaps                        Pointer to the array where computed tap values are stored. The
                             number of elements in the array is tapsLen.
tapsLen                      Number of elements in the array containing the tap values; must be
                             equal or greater than 5.
winType                      Specifies what type of window is used in computations. The winType
                             must have one of the following values:
                             ippWinBartlett  Bartlett window;
                             ippWinBlackman  Blackman window;
                             ippWinHamming  Hamming window;
                             ippWinHann  Hann window.
doNormal                     Specifies normalized or non-normalized sequence of the filter
                             coefficients is computed. The doNormal must have one of the
                             following values:
                             ippTrue  The function computes normalized sequence of coefficients.
                             ippFalse  The function computes non-normalized sequence of
                             coefficients.

Description
This function computes tapsLen coefficients for highpass FIR filter the cutoff frequency rFreq by windowing
the ideal infinite filter coefficients. The parameter winType specifies the type of the window. For more
information on window types used by the function, see Understanding Window Functions.he computed
coefficients are stored in the array pTaps.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pTaps pointer is NULL.

ippStsSizeErr                     Indicates an error when the tapsLen is less than 5, or rFreq is
                                  out of the range.

FIRGenBandpass
Computes bandpass FIR filter coefficients.

Syntax
IppStatus ippsFIRGenBandpass_64f(Ipp64f rLowFreq, Ipp64f rHighFreq, Ipp64f* pTaps, int
tapsLen, IppWinType winType, IppBool doNormal    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

   286
---------------------Page 287---------------------

                                                                           Filtering Functions  6 

Parameters

rLowFreq                     Normalized low cutoff frequency, must be in the range (0, 0.5) and
                             less than rHighFreq.
rHighFreq                    Normalized high cutoff frequency, must be in the range (0, 0.5) and
                             greater than rLowFreq.
pTaps                        Pointer to the array where computed tap values are stored. The
                             number of elements in the array is tapsLen.
tapsLen                      Number of elements in the array containing the tap values; should
                             be equal or greater than 5.
winType                      Specifies what type of window is used in computations. The winType
                             must have one of the following values:
                             ippWinBartlett  Bartlett window;
                             ippWinBlackman  Blackman window;
                             ippWinHamming  Hamming window;
                             ippWinHann  Hann window.
doNormal                     Specifies normalized or non-normalized sequence of the filter
                             coefficients is computed. The doNormal must have one of the
                             following values:
                             ippTrue The function computes normalized sequence of coefficients.
                             ippFalse The function computes non-normalized sequence of
                             coefficients.

Description
This function computes tapsLen coefficients for bandpass FIR filter with the cutoff frequencies rLowFreq and
rHighFreq by windowing the ideal infinite filter coefficients. The parameter winType specifies the type of
the window. For more information on window types used by the function, see Understanding Window
Functions. The computed coefficients are stored in the array pTaps.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pTaps  pointer is NULL.

ippStsSizeErr                    Indicates an error when the tapsLen  is less than 5, or rLowFreq
                                 is greater than or equal to rHighFreq, or one of the frequency
                                 parameters  rLowFreq  and rHighFreq  is out of the range.

Example
The example below shows how to use the function ippsFIRGenBandpass.
void func_BandPass() 
{
    int len = 512;
    Ipp64f pDst[512];
    Ipp64f magn = 4095;
    Ipp64f rLowFreq = 0.2;
    Ipp64f rHighFreq = 0.3;

    int tapslen = 27;
    int numIters = 512;
     
    IppsFIRState_64f* pState;

                                                                                          287
---------------------Page 288---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

    IppStatus st;

Ipp64f* FIRDst = ippsMalloc_64f(512*sizeof(Ipp64f));
    Ipp64f* taps = ippsMalloc_64f(tapslen*sizeof(Ipp64f));
    Ipp64f* pDL = ippsMalloc_64f(tapslen*sizeof(Ipp64f));
    ippsZero_64f(pDL,tapslen);
    ippsVectorJaehne_64f(pDst, len, magn);// //generate source vector
    //computes tapsLen coefficients for bandstop  FIR filter
    ippsFIRGenBandpass_64f(rLowFreq, rHighFreq, taps, tapslen, ippWinHamming, ippTrue);
    ////filter an input vector
    ippsFIRInitAlloc_64f(&pState, taps,tapslen, pDL);
    ippsFIR_64f(pDst, FIRDst, numIters, pState); 
}

Result:
 

 

FIRGenBandstop
Computes bandstop FIR filter coefficients.

Syntax
IppStatus ippsFIRGenBandstop_64f(Ipp64f rLowFreq, Ipp64f rHighFreq, Ipp64f* pTaps, int
tapsLen, IppWinType winType, IppBool doNormal    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h

   288
---------------------Page 289---------------------

                                                                             Filtering Functions  6 

Libraries: ippcore.lib, ippvm.lib

Parameters

rLowFreq                     Normalized low cutoff frequency, must be in the range (0, 0.5) and
                             less than rHighFreq .
rHighFreq                    Normalized high cutoff frequency, must be in the range (0, 0.5) and
                             greater than rLowFreq  .
pTaps                        Pointer to the array where computed tap values are stored. The
                             number of elements in the array is  tapsLen .
tapsLen                      Number of elements in the array containing the tap values, must be
                             equal or greater than 5.
winType                      Specifies what type of window is used in computations. The   winType
                             must have one of the following values:
                             ippWinBartlett   Bartlett window;
                             ippWinBlackman   Blackman window;
                             ippWinHamming   Hamming window;
                             ippWinHann   Hann window.
doNormal                     Specifies normalized or non-normalized sequence of the filter
                             coefficients is computed. The doNormal  must have one of the
                             following values:
                             ippTrue  The function computes normalized sequence of coefficients.
                             ippFalse  The function computes non-normalized sequence of
                             coefficients.

Description
This function computes tapsLen coefficients for bandstop FIR filter with the cutoff frequencies rLowFreq and
rHighFreq  by windowing the ideal infinite filter coefficients. The parameter winType specifies the type of
the window. For more information on window types used by the function, see Understanding Window
Functions. The computed coefficients are stored in the array pTaps.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the  pTaps pointer is NULL.

ippStsSizeErr                     Indicates an error when the  tapsLen  is less than 5, or rLowFreq
                                  is greater than or equal to rHighFreq, or one of the frequency
                                  parameters  rLowFreq  and  rHighFreq  is out of the range.

Single-Rate FIR LMS Filter Functions
The functions described in this section perform the following tasks:
• initialize a single-rate FIR LMS filter
• get and set the delay line values
• get the filter coefficients (taps) values
• perform filtering
• free dynamic memory allocated for the functions state
To use the single-rate FIR LMS adaptive filter functions, follow this general scheme:
1.  Call ippsFIRLMSInitAlloc   to allocate memory and initialize a single-rate FIR LMS filter.

                                                                                            289
---------------------Page 290---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

2.   Call ippsFIRLMSOne_Direct   to make one iteration of FIR filter taps fitting with one input sample
     and/or call ippsFIRLMS to fit taps with a block of consecutive input samples.
3.   Call ippsFIRLMSMRGetTaps   to get the filter coefficients (taps). Call ippsFIRLMSMRGetDlyLine and 
     ippsFIRLMSMRSetDlyLine    to get and set the values in the delay line.
4.   Call ippsFIRLMSMRFree  to release dynamic memory associated with the FIR LMS filter.

FIRLMSInitAlloc
DEPRECATED. Allocates memory and initializes an
adaptive FIR filter that uses the least mean squares
(LMS) algorithm.
IppStatus ippsFIRLMSInitAlloc_32f(IppsFIRLMSState_32f** ppState, const Ipp32f* pTaps,
int tapsLen, const Ipp32f* pDlyLine, int dlyLineIndex);
IppStatus ippsFIRLMSInitAlloc32f_16s(IppsFIRLMSState32f_16s** ppState, const Ipp32f*
pTaps, int tapsLen, const Ipp16s* pDlyLine, int dlyLineIndex);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                         Pointer to the multi-rate FIR LMS filter state structure to be closed.

tapsLen                       Number of elements in the array containing the tap values.

pDlyLine                      Pointer to the array holding the delay line values. The number of
                              elements in the array is 2* tapsLen .
dlyLineIndex                  Current index of the delay line.

ppState                       Pointer to the pointer to the state structure.

Description
The function ippsFIRLMSInitAlloc   is deprecated. This function is obsolete and will be removed in a future
release. Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes a single-rate FIR LMS filter state. The function
ippsFIRLMSInitAlloc   copies the taps from the tapsLen-length array pTaps into the state structure
ppState . The (2*tapsLen-length array pDlyLine specifies the delay line values. The current index of the
delay line pDlyLine is defined by dlyLineIndex. If the pointer to the array pDlyLine or pTaps is NULL,
then the corresponding values of the state structure are initialized to 0.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when one of the specified pointers is NULL .

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

   290
---------------------Page 291---------------------

                                                                             Filtering Functions  6 

FIRLMSFree
DEPRECATED. Closes an adaptive FIR filter that uses
the least mean squares (LMS) algorithm.

Syntax
IppStatus ippsFIRLMSFree_32f(IppsFIRLMSState_32f* pState       );
IppStatus ippsFIRLMSFree32f_16s(IppsFIRLMSState32f_16s* pState       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                       Pointer to the FIR LMS filter state structure to be closed.

Description
The function ippsFIRLMSFree is deprecated. This function is obsolete and will be removed in a future
release. Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function closes the FIR LMS filter state by freeing all memory associated with a filter state created by
the function FIRLMSInitAlloc. Call ippsFIRLMSFree after filtering is completed.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

FIRLMSGetTaps
Retrieves the tap values from the FIR LMS filter.

Syntax
IppStatus ippsFIRLMSGetTaps_32f(const IppsFIRLMSState_32f* pState, Ipp32f* pOutTaps          );
IppStatus ippsFIRLMSGetTaps32f_16s(const IppsFIRLMSState32f_16s* pState, Ipp32f*
pOutTaps );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                            291
---------------------Page 292---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

pState                        Pointer to the FIR LMS filter state structure.

pOutTaps                      Pointer to the array holding copies of the taps.

Description
This function copies the taps from the state structure pState to the tapsLen-length array pOutTaps. To set
new taps in the state structure, create a new state using the function FIRLMSInitAlloc.
Before calling the function ippsFIRLMSGetTaps the filter state structure must be initialized by the function 
FIRLMSInitAlloc.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

FIRLMSGetDlyLine
Retrieves the delay line contents from the FIR LMS
filter.

Syntax
IppStatus ippsFIRLMSGetDlyLine_32f(const IppsFIRLMSState_32f* pState, Ipp32f* pDlyLine,
int* pDlyLineIndex  );
IppStatus ippsFIRLMSGetDlyLine32f_16s(const IppsFIRLMSState32f_16s* pState, Ipp16s*
pDlyLine, int* pDlyLineIndex    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the FIR LMS filter state structure.

pDlyLine                      Pointer to the tapsLen -length array holding the delay line values.

pDlyLineIndex                 Pointer to the array to store the current delay line index copied from
                              the filter state structure.

Description
This function copies the delay line values and the current delay line index from the state structure pState,
and stores them into pDlyLine and pDlyLineIndex , respectively.
Before calling the function ippsFIRLMSGetDlyLine the filter state structure must be initialized by the
function FIRLMSInitAlloc.

   292
---------------------Page 293---------------------

                                                                           Filtering Functions  6 

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

FIRLMSSetDlyLine
Sets the delay line contents in the FIR LMS filter.

Syntax
IppStatus ippsFIRLMSGetDlyLine_32f(const IppsFIRLMSState_32f* pState, Ipp32f* pDlyLine,
int* pDlyLineIndex );
IppStatus ippsFIRLMSGetDlyLine32f_16s(const IppsFIRLMSState32f_16s* pState, Ipp16s*
pDlyLine, int* pDlyLineIndex  );
IppStatus ippsFIRLMSSetDlyLine_32f(IppsFIRLMSState_32f* pState, const Ipp32f* pDlyLine,
int dlyLineIndex );
IppStatus ippsFIRLMSSetDlyLine32f_16s(IppsFIRLMSState32f_16s* pState, const Ipp16s*
pDlyLine, int dlyLineIndex  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                       Pointer to the FIR LMS filter state structure.

pDlyLine                     Pointer to the tapsLen-length array holding the delay line values.

dlyLineIndex                 Initial index of the delay line to be stored in the filter state structure
                             pState.

Description
This function copies the delay line values from pDlyLine, and the current delay line index from
dlyLineIndex , and stores them into the state structure pState.
Before calling the function ippsFIRLMSSetDlyLine the filter state structure must be initialized by the
function FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

FIRLMS
Filters a vector through the FIR LMS filter.

                                                                                          293
---------------------Page 294---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Syntax
IppStatus ippsFIRLMS_32f(const Ipp32f* pSrc, const Ipp32f* pRef, Ipp32f* pDst, int len,
float mu, IppsFIRLMSState_32f* pState      );
IppStatus ippsFIRLMS32f_16s(const Ipp16s* pSrc, const Ipp16s* pRef, Ipp16s* pDst, int
len, float mu, IppsFIRLMSState32f_16s* pState       );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                         Pointer to the FIR LMS filter state structure.

pSrc                           Pointer to the source vector .

pRef                           Pointer to the reference signal

pDst                           Pointer to the output signal

len                            Number of elements in the vector.

mu                             Adaptation step.

Description
This function filters a source vector pSrc using an adaptive FIR LMS filter.
Each of len iterations performed by the function consists of two main procedures. First, ippsLMS filters the
current element of the source vector pSrc and stores the result in pDst. Next, the function updates the
current taps using the reference signal pRef, the computed result signal pDst, and the adaptation step mu.
The filtering procedure can be described as a FIR filter operation:
 

 
Here the input sample to be filtered is denoted by x(n), the taps are denoted by h(i), and y(n) is the
return value.
The function updates the filter coefficients that are stored in the filter state structure pState. Updated filter
coefficients are defined as hn+1(i) = hn(i) + 2* mu* errVal * x(n-i)  ,
where hn+1(i) denotes new taps, hn(i) denotes initial taps, mu and errVal are the adaptation step and
adaptation error value, respectively. An adaptation error value errVal is computed inside the function as the
difference between the output and reference signals.
Before using ippsFIRLMS , initialize the pState structure by calling the function FIRLMSInitAlloc.

Return Values

ippStsNoErr                         Indicates no error.

   294
---------------------Page 295---------------------

                                                                         Filtering Functions  6 

ippStsNullPtrErr                 Indicates an error when one of the specified pointers is NULL.

ippStsSizeErr                    Indicates an error when len is less or equal to 0.

ippStsContextMatchErr            Indicates an error when the state identifier is incorrect.

Example
The code example below demonstrates how to use ippsFIRLMS_32f functions to filter a signal sample.
IppStatus firlms(void) {
     IppStatus st;
     Ipp32f taps = 0, x[LEN], y[LEN], mu = 0.03f;
     IppsFIRLMSState_32f* ctx;
     int i;
     /// no taps and no delay line from outside
     ippsFIRLMSInitAlloc_32f( &ctx, 0, 1, 0, 0 );
     /// make a const signal of amplitude 1 and noise it
     for(i=0; i<LEN; ++i) x[i] = 0.4f * rand()/RAND_MAX + 0.8f;
     st = ippsFIRLMS_32f( x, x+1, y, LEN-1, mu, ctx);
     /// get FIR LMS tap, it must be near to 1
     ippsFIRLMSGetTaps_32f(ctx, &taps);
     ippsFIRLMSFree_32f(ctx);
     printf_32f("FIR LMS tap fitted =", &taps, 1, st);
     return st; 
}

Output:
    FIR LMS tap adapted = 0.986842

FIRLMSOne_Direct
DEPRECATED. Filters a single sample through a FIR
LMS filter.

Syntax
IppStatus ippsFIRLMSOne_Direct_32f(Ipp32f src, Ipp32f refVal, Ipp32f* pDstVal, Ipp32f*
pTapsInv, int tapsLen, float mu, Ipp32f* pDlyLine, int* pDlyLineIndex     );
IppStatus ippsFIRLMSOne_Direct32f_16s(Ipp16s src, Ipp16s refVal, Ipp16s* pDstVal,
Ipp32f* pTapsInv, int tapsLen, float mu, Ipp16s* pDlyLine, int* pDlyLineIndex     );
IppStatus ippsFIRLMSOne_DirectQ15_16s(Ipp16s src, Ipp16s refVal, Ipp16s* pDstVal,
Ipp32s* pTapsInv, int tapsLen, int muQ15, Ipp16s* pDlyLine, int* pDlyLineIndex     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

src                         Input sample to be filtered.

pDstVal                     Pointer to the output sample.

refVal                      Reference signal sample.

                                                                                       295
---------------------Page 296---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

pTapsInv                       Pointer to the array containing the FIR filter taps to be adapted. The
                               tap values are stored in the array in the inverse order.
tapsLen                        Number of elements in the array containing the tap values.

pDlyLine                       Pointer to the array holding the delay line values.

pDlyLineIndex                  Pointer to the current index of the delay line.

mu                             Adaptation step.

muQ15                          Integer version adaptation step.

Description
The function ippsFIRLMSOne_Direct   is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function performs directly a single iteration of FIR filter taps adaptation. The tapsLen-length array
pTapsInv  contains the FIR filter taps in the inverse order. The (2*tapsLen)-length array pDlyLine specifies
the delay line values. The pDlyLineIndex array specifies the current index of the delay line. The output
signal is stored in pDstVal.

      NOTE
      The adaptation error value can be computed as follows: err[n] = refVal[n] - *pDstVal   .

The function ippsFIRLMSOne_Direct   performs a single iteration of FIR filter taps adaptation with the mu
step value. The taps are floating-point numbers.
Set the taps to zero or to values close to calculated to speed up the process.
The function ippsLMSOne_Direct   is to be called within cycle with the number of iterations equal to the
number of input samples. You can decide what data is to be saved as a result of adaptation: either the
filtered output signal or the adaptation error.
The function ippsFIRLMSOne_DirectQ15    performs a single iteration of FIR filter taps adaptation with the
muQ15 step value. The taps are integer numbers. The adaptation step muQ15 can be computed as follows:
muQ15 = (int)(mu *(1<<15)+0.5f)

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when the pointers to data arrays are   NULL .

ippStsSizeErr                       Indicates an error when  tapsLen   is less or equal to 0.

Example
The example below illustrates the use of the function ippsFIRLMSOne_Direct to adapt the FIR filter taps.
After adaptation the taps are close to 1.0.
IppStatus firlmsone(void) { 
#define LEN 200
      IppStatus st = ippStsNoErr;
      Ipp32f taps = 0, dly[2] = {0};
      Ipp32f x[LEN], y[LEN], mu = 0.05f;
      int i, indx = 0;
      /// make a const signal of amplitude 1 and noise it
      for( i=0; i<LEN; ++i ) x[i] = 0.4f * rand()/RAND_MAX + 0.8f;

   296
---------------------Page 297---------------------

                                                                              Filtering Functions  6 
      for( i=0; i<LEN-1 && ippStsNoErr==st; ++i )
      st=ippsFIRLMSOne_Direct_32f( x[i], x[i+1], y+1+i, &taps, 1, mu,
          dly, &indx );
      printf_32f(“FIRLMSOne tap adapted =”, &taps, 1, st );
      return st; 
}

Output:
    FIRLMSOne tap adapted = 0.993872

Multi-Rate FIR LMS Filter Functions
The functions described in this section perform the following tasks:
• initialize a multi-rate FIR LMS filter
• get and set the delay line values
• get and set the filter coefficients (taps) values
• set the adaptation step value
• perform filtering
• update the filter coefficients using the result of the filter operation
• free dynamic memory allocated for the functions state
To use the multi-rate FIR LMS adaptive filter functions, follow this general scheme:
1.   Call ippsFIRLMSMRInitAlloc  to initialize a multi-rate FIR LMS filter.
2.   Call ippsFIRLMSMRPutVal  a required number of times to place the input values in the delay line.
3.   Call ippsFIRLMSMROne  to filter the samples in the delay line.
4.   Call ippsFIRLMSMRUpdateTaps   to update the taps using the value of adaptation error that is based on
     comparison between filtered and reference signals.
5.   Call ippsFIRLMSMRGetTaps  and ippsFIRLMSMRSetTaps   to get and set the filter coefficients (taps).
     Call ippsFIRLMSMRGetDlyLine   and ippsFIRLMSMRSetDlyLine   to get and set the values in the delay
     line.
6.   Call ippsFIRLMSMRFree  to release dynamic memory associated with the FIR LMS filter.

FIRLMSMRInitAlloc
DEPRECATED. Allocates memory and initializes an
adaptive multi-rate FIR filter that uses the least mean
squares (LMS) algorithm.

Syntax
IppStatus ippsFIRLMSMRInitAlloc32s_16s(IppsFIRLMSMRState32s_16s** ppState, const
Ipp32s* pTaps, int tapsLen, const Ipp16s* pDlyLine, int dlyLineIndex, int dlyStep, int
updateDly, int mu  );
IppStatus ippsFIRLMSMRInitAlloc32sc_16sc(IppsFIRLMSMRState32sc_16sc** ppState, const
Ipp32sc* pTaps, int tapsLen, const Ipp16sc* pDlyLine, int dlyLineIndex, int dlyStep,
int updateDly, int mu  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

                                                                                             297
---------------------Page 298---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Parameters

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

pDlyLine                       Pointer to the array holding the delay line values. The number of
                               elements in the array is tapsLen*dlyStep + updateDly     .
dlyLineIndex                   Current index of the delay line.

dlyStep                        Multi-rate down factor applied to delay line values.

updateDly                      Value of adaptation delay in samples.

mu                             Adaptation step.

ppState                        Pointer to the pointer to the filter state structure.

Description
The function ippsFIRLMSMRInitAlloc   is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes a multi-rate FIR LMS filter state. The function copies the filter
coefficients from tapsLen-length array pTaps into the state structure ppState. The array pDlyLine
specifies the delay line values. The structure is initialized by the downsampling factor over the delay line
dlyStep , by the adaptation delay value updateDly, and by the adaptation step value mu. The function
returns the pointer in the output parameter ppState and also the operation status value.
The function uses copies of the tap values during the filtering procedure. The initial values passed to the
function may be obtained from the previous filtering procedure. If the pointer pTaps is NULL, then the filter
coefficient values are set to zero.
Copies of the input samples are used in the filtering procedure. Values in the delay line represent data in the
same format as the input data to be filtered. If the pointer pDlyLine is NULL, then the filter delay line values
are set to zero.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when the  ppState   pointer is NULL.

ippStsContextMatchErr               Indicates an error when the state identifier is incorrect.

FIRLMSMRFree
DEPRECATED. Closes an adaptive multi-rate FIR filter
that uses the least mean squares algorithm.

Syntax
IppStatus ippsFIRLMSMRFree32s_16s(IppsFIRLMSMRState32s_16s* pState           );
IppStatus ippsFIRLMSMRFree32sc_16sc(IppsFIRLMSMRState32sc_16sc* pState            );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h

   298
---------------------Page 299---------------------

                                                                               Filtering Functions  6 

Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the multi-rate FIR LMS filter state structure to be closed.

Description
The function ippsFIRLMSMRFree  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function closes the multi-rate FIR LMS filter state by freeing all memory associated with a filter state
created by the function FIRLMSMRInitAlloc. Call ippsFIRLMSMRFree after filtering is completed.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the   pState  pointer is NULL.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

FIRLMSMRSetMu
DEPRECATED. Sets the adaptation step.

Syntax
IppStatus ippsFIRLMSMRSetMu32s_16s(IppsFIRLMSMRState32s_16s* pState, const int mu             );
IppStatus ippsFIRLMSMRSetMu32sc_16sc( IppsFIRLMSMRState32sc_16sc* pState, const int
mu);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

mu                            New adaptation step

pState                        Pointer to the filter state structure.

Description
The function ippsFIRLMSMRSetMu  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function updates the adaptation step stored in pState with the new value mu.
Before calling the function ippsFIRLMSMRSetMu the filter state structure must be initialized by the function 
FIRLMSMRInitAlloc.

                                                                                               299
---------------------Page 300---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the   pState  pointer is NULL.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

FIRLMSMRUpdateTaps
DEPRECATED. Updates the filter coefficients using the
adaptation error value.

Syntax
IppStatus ippsFIRLMSMRUpdateTaps32s_16s(Ipp32s errVal, IppsFIRLMSMRState32s_16s*
pState);
IppStatus ippsFIRLMSMRUpdateTaps32sc_16sc(Ipp32scerrVal, IppsFIRLMSMRState32sc_16sc*
pState);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the filter state structure.

errVal                        Adaptation error value.

Description
The function ippsFIRLMSMRUpdateTaps   is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function updates the filter coefficients that are stored in the filter state structure pState. It is assumed
that the filter operation was performed and the adaptation error value errVal was computed before calling
this function. The adaptation error value is computed outside the function as the difference between output
and reference signals. Updated filter coefficients are defined as hn+1(i) = hn(i) + mu * errVal * x(n-
(i * dlyStep) - updateDly)    ,
where hn+1(i) denotes new taps, hn(i) denotes initial taps, and mu, errVal and updateDly are the
adaptation step, adaptation error value and adaptation delay, respectively. Before calling the function
ippsFIRLMSMRUpdateTaps    the filter state structure must be initialized by the function FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the   pState  pointer is NULL.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

   300
---------------------Page 301---------------------

                                                                            Filtering Functions  6 

FIRLMSMRGetTaps
DEPRECATED. Retrieves tap values from the multi-
rate FIR LMS filter.

Syntax
IppStatus ippsFIRLMSMRGetTaps32s_16s(IppsFIRLMSMRState32s_16s* pState, Ipp32s*
pOutTaps);
IppStatus ippsFIRLMSMRGetTaps32sc_16sc(IppsFIRLMSMRState32sc_16sc* pState, Ipp32sc*
pOutTaps);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                       Pointer to the filter state structure.

pOutTaps                     Pointer to the array holding copies of the taps.

Description
The function ippsFIRLMSMRGetTaps  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function copies the values of the filter coefficients stored in the filter state structure pState to the array
pointed by the pOutTaps pointer.
Before calling the function ippsFIRLMSMRGetTaps the filter state structure must be initialized by the
function FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

FIRLMSMRSetTaps
DEPRECATED. Sets tap values in the multi-rate FIR
LMS filter.

Syntax
IppStatus ippsFIRLMSMRSetTaps32s_16s(IppsFIRLMSMRState32s_16s* pState, const Ipp32s*
pInTaps);
IppStatus ippsFIRLMSMRSetTaps32sc_16sc(IppsFIRLMSMRState32sc_16sc* pState, const
Ipp32sc* pInTaps );

Include Files
ipps.h

                                                                                            301
---------------------Page 302---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the filter state structure.

pInTaps                       Pointer to the array holding new tap values.

Description
The function ippsFIRLMSMRSetTaps   is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function sets the filter coefficients stored in the filter state structure pState to the new values stored in
an array pointed by the pInTaps pointer. If the pointer is NULL, then the filter coefficients values are set to
zero.
Before calling the function ippsFIRLMSMRSetTaps the filter state structure must be initialized by the
function FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when one of the specified pointers is NULL .

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

FIRLMSMRGetTapsPointer
DEPRECATED. Returns the pointer to the filter
coefficients.

Syntax
IppStatus ippsFIRLMSMRGetTapsPointer32s_16s(IppsFIRLMSMRState32s_16s* pState, Ipp32s**
ppTaps);
IppStatus ippsFIRLMSMRGetTapsPointer32sc_16sc(IppsFIRLMSMRState32sc_16sc* pState,
Ipp32sc** ppTaps  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the filter state structure.

ppTaps                        Pointer to the variable that contains the pointer to the tap values.

   302
---------------------Page 303---------------------

                                                                              Filtering Functions  6 

Description
The function ippsFIRLMSMRGetTapsPointer   is deprecated. This function is obsolete and will be removed in
a future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function writes the pointer to the filter coefficients stored in the filter state structure pState to the
variable pointed by pTaps.

      NOTE
      To get the pointer to tap values directly is faster than to copy them using the the function 
      FIRLMSMRGetTaps function, but this operation may be error-prone.

Before calling the function ippsFIRLMSMRGetTapsPointer the filter state structure must be initialized by
the the function FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

FIRLMSMRGetDlyLine
DEPRECATED. Retrieves the delay line contents from
the multi-rate FIR LMS filter state.

Syntax
IppStatus ippsFIRLMSMRGetDlyLine32s_16s(IppsFIRLMSMRState32s_16s* pState, Ipp16s*
pOutDlyLine, int* pOutDlyLineIndex     );
IppStatus ippsFIRLMSMRGetDlyLine32sc_16sc(IppsFIRLMSMRState32sc_16sc* pState, Ipp16sc*
pOutDlyLine, int* pOutDlyLineIndex     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the filter state structure.

pOutDlyLine                   Pointer to the array containing the copies of delay line values. The
                              number of elements in the array is  tapsLen*dlyStep+updateDly    .
pOutDlyLineIndex              Pointer to the array to store the current delay line index copied from
                              pState .

Description
The function ippsFIRLMSMRGetDlyLine   is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.

                                                                                              303
---------------------Page 304---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

This function copies the delay line values and the current delay line index from the state structure pState,
and stores them into pOutDlyLine and pOutDlyLineIndex  , respectively.
Before calling the function ippsFIRLMSMRGetDlyLine the filter state structure must be initialized by the
function FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

FIRLMSMRSetDlyLine
DEPRECATED. Gets and sets the delay line contents of
a multi-rate FIR LMS filter state.

Syntax
IppStatus ippsFIRLMSMRSetDlyLine32s_16s(IppsFIRLMSMRState32s_16s* pState, const Ipp16s*
pInDlyLine, int dlyLineIndex    );
IppStatus ippsFIRLMSMRSetDlyLine32sc_16sc(IppsFIRLMSMRState32sc_16sc* pState, const
Ipp16sc* pInDlyLine, int dlyLineIndex     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the filter state structure.

pInDlyLine                    Pointer to the array containing the new delay line values.The
                              number of elements in the array is  tapsLen*dlyStep+updateDly    .
dlyLineIndex                  Initial index of the delay line to be stored in pState.

Description
The function ippsFIRLMSMSetDlyLine   is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function copies the new values stored in the pInDlyLine and corresponding delay line index from
dlyLineIndex  and stores them into the state structure pState. If the pointer pInDlyLine is NULL, the
delay line values are set to zero.
Before calling the function ippsFIRLMSMRSetDlyLine the filter state structure must be initialized by the
function FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                        Indicates no error.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

   304
---------------------Page 305---------------------

                                                                             Filtering Functions  6 

FIRLMSMRGetDlyVal
DEPRECATED. Gets one delay line values from the
specified position.

Syntax
IppStatus ippsFIRLMSMRGetDlyVal32s_16s(IppsFIRLMSMRState32s_16s* pState, Ipp16s*
pOutVal, int index  );
IppStatus ippsFIRLMSMRGetDlyVal32sc_16sc(IppsFIRLMSMRState32sc_16sc* pState, Ipp16sc*
pOutVal, int index  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                       Pointer to the filter state structure.

pOutVal                      Pointer to the copied delay line value.

index                        Index of the required delay line value.

Description
The function ippsFIRLMSMRGetDlyVal  is deprecated. This function is obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function copies from the filter state structure pState one value to the pOutVal. The position of this
sample in the delay line is specified by index - it means that index iterations ago the sample was placed
into the delay line.
Before calling the function ippsFIRLMSMRGetDlyVal the filter state structure must be initialized by the
function FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

FIRLMSMRPutVal
DEPRECATED. Places the input value in the delay line.

Syntax
IppStatus ippsFIRLMSMRPutVal32s_16s(Ipp16s val, IppsFIRLMSMRState32s_16s* pState          );
IppStatus ippsFIRLMSMRPutVal32sc_16sc(Ipp16sc val, IppsFIRLMSMRState32sc_16sc* pState          );

Include Files
ipps.h

                                                                                            305
---------------------Page 306---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the filter state structure.

val                           Value of the input sample.

Description
The function ippsFIRLMSMRPutVal   is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function places the value of the input sample val into the delay line, thus preparing the filter with the
state structure pState for the filtering procedure.
Before calling the function ippsFIRLMSMRPutVal the filter state structure must be initialized by the function 
FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                        Indicates no error.

ippStsNullPtrErr                   Indicates an error when the   pState  pointer is NULL.

ippStsContextMatchErr              Indicates an error when the state identifier is incorrect.

FIRLMSMROne
DEPRECATED. Filters data placed in the delay line.

Syntax
IppStatus ippsFIRLMSMROne32s_16s(Ipp32s* pDstVal, IppsFIRLMSMRState32s_16s* pState             );
IppStatus ippsFIRLMSMROne32sc_16sc(Ipp32sc* pDstVal, IppsFIRLMSMRState32sc_16sc*
pState);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                        Pointer to the filter state structure.

pDstVal                       Pointer to the output signal value.

Description
The function ippsFIRLSMMROne  is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.

   306
---------------------Page 307---------------------

                                                                                 Filtering Functions  6 

This function filters the samples placed in the delay line using the filter coefficients stored in the filter state
structure pState. The resulting value is placed in the pDstVal. The downsampling factor dlyStep defines
the number of samples that are filtered. The filter coefficients are not updated.
The filtering procedure can be described as a FIR filter operation (here the input sample to be filtered is
denoted x(n) , the taps are denoted h(i), and the return value is y(n)):
 

 
Note that the function operates with values stored in the delay line that are copies of the input samples.
Before calling the function ippsFIRLMSMROne, initialize the filter state by calling the function 
FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when one of the specified pointers is   NULL.

ippStsContextMatchErr               Indicates an error when the state identifier is incorrect.

FIRLMSMROneVal
DEPRECATED. Filters one input value.

Syntax
IppStatus ippsFIRLMSMROneVal32s_16s(Ipp16s val, Ipp32s* pDstVal,
IppsFIRLMSMRState32s_16s* pState     );
IppStatus ippsFIRLMSMROneVal32sc_16sc(Ipp16sc val, Ipp32sc* pDstVal,
IppsFIRLMSMRState32sc_16sc* pState      );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h , ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                         Pointer to the filter state structure.

pDstVal                        Pointer to the output signal value.

val                            Value of the input signal sample.

Description
The function ippsFIRLMSMROneVal   is deprecated. This function is obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function places one input sample val into the delay line and filters it using the filter coefficients
specified in the filter state structure pState. The result value is stored in the pDstVal.

                                                                                                 307
---------------------Page 308---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Before calling the function ippsFIRLMSMROneVal   , initialize the filter state by calling the function 
FIRLMSMRInitAlloc.

Return Values

ippStsNoErr                           Indicates no error.

ippStsNullPtrErr                      Indicates an error when one of the specified pointers is      NULL .

ippStsContextMatchErr                 Indicates an error when the state identifier is incorrect.

IIR Filter Functions
The functions described in this section initialize an infinite impulse response (IIR) filter and perform filtering.
Intel     supports two types of filters: arbitrary order filter and biquad filter.
shows the structure of an arbitrary order IIR filter.

Structure of an Arbitrary Order Filter

Here x[n]  is a sample of the input signal, y[n] is a sample of the output signal, order is the filter order,
and b0, b1, . . ., b order, a1, . . ., a order are the reduced filter coefficients.
The output signal is computed by the following formula:
 

 
.
Reduced coefficients are calculated as ak = Ak/A0 and bk = Bk/A0
where A 0, A 1,...Aorder, B0, B1,...Border are initial filter coefficients (taps).

   308
---------------------Page 309---------------------

                                                                              Filtering Functions  6 

A biquad IIR filter is a cascade of second-order filters. Figure 6-2below illustrates the structure of the biquad
filter with k cascades of second-order filters.

Structure of a BiQuad IIR Filter

To initialize and use an IIR filter, follow this general scheme:
1.   Call ippsIIRInitAlloc  to allocate memory and initialize the filter as an arbitrary order IIR filter, or
     call ippsIIRInitAlloc_BiQuad   to allocate memory and initialize the filter as a cascade of biquads. Or
     alternatively call ippsIIRInit to initialize the filter as an arbitrary order IIR filter in the external
     buffer, or ippsIIRInit_BiQuad to initialize the filter as a cascade of biquads in the external buffer.
     Size of the buffer can be computed by calling the functions ippsIIRGetStateSize or 
     ippsIIRGetStateSize_BiQuad   , respectively.
2.   Call ippsIIROnerepeatedly to filter a single sample through an IIR filter or call ippsIIR to filter
     consecutive samples at once.
3.   Call ippsIIRGetDlyLine  and ippsIIRSetDlyLine   to get and set the delay line values in the IIR state
     structure.
4.   Call ippsIIRSetTaps  to set new tap values in the previously initialized filter state structure.
5.   After all filtering is complete, call ippsIIRFree to release dynamic memory associated with the filter
     state structure created by ippsIIRInitAlloc or ippsIIRInitAlloc_BiQuad  .
Alternatively, you may use the direct version of the functions. These functions perform filtering without
initializing the filter state structure. All required parameters are directly set in the function.

IIRInitAlloc
DEPRECATED. Allocates memory and initializes the
state structure for an arbitrary IIR filter.

Syntax
Case 1: Operation on integer samples
IppStatus ippsIIRInitAlloc32s_16s(IppsIIRState32s_16s** ppState, const Ipp32s* pTaps,
int order, int tapsFactor, const Ipp32s* pDlyLine       );
IppStatus ippsIIRInitAlloc32s_16s32f(IppsIIRState32s_16s** ppState, const Ipp32f*
pTaps, int order, const Ipp32s* pDlyLine     );
IppStatus ippsIIRInitAlloc32f_16s(IppsIIRState32f_16s** ppState, const Ipp32f* pTaps,
int order, const Ipp32f* pDlyLine    );
IppStatus ippsIIRInitAlloc64f_16s(IppsIIRState64f_16s** ppState, const Ipp64f* pTaps,
int order, const Ipp64f* pDlyLine    );
IppStatus ippsIIRInitAlloc64f_32s(IppsIIRState64f_32s** ppState, const Ipp64f* pTaps,
int order, const Ipp64f* pDlyLine    );

IppStatus ippsIIRInitAlloc32sc_16sc(IppsIIRState32sc_16sc** ppState, const Ipp32sc*
pTaps, int order, int tapsFactor, const Ipp32sc* pDlyLine        );
IppStatus ippsIIRInitAlloc32sc_16sc32fc(IppsIIRState32sc_16sc** ppState, const Ipp32fc*
pTaps, int order, const Ipp32sc* pDlyLine     );

                                                                                             309
---------------------Page 310---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsIIRInitAlloc32fc_16sc(IppsIIRState32fc_16sc** ppState, const Ipp32fc*
pTaps, int order, const Ipp32fc* pDlyLine   );
IppStatus ippsIIRInitAlloc64fc_16sc(IppsIIRState64fc_16sc** ppState, const Ipp64fc*
pTaps, int order, const Ipp64fc* pDlyLine   );
IppStatus ippsIIRInitAlloc64fc_32sc(IppsIIRState64fc_32sc** ppState, const Ipp64fc*
pTaps, int order, const Ipp64fc* pDlyLine   );
Case 2: Operation on floating point samples
IppStatus ippsIIRInitAlloc_32f(IppsIIRState_32f** ppState, const Ipp32f* pTaps, int
order, const Ipp32f* pDlyLine  );
IppStatus ippsIIRInitAlloc64f_32f(IppsIIRState64f_32f** ppState, const Ipp64f* pTaps,
int order, const Ipp64f* pDlyLine   );
IppStatus ippsIIRInitAlloc_64f(IppsIIRState_64f** ppState, const Ipp64f* pTaps, int
order, const Ipp64f* pDlyLine  );
IppStatus ippsIIRInitAlloc_32fc(IppsIIRState_32fc** ppState, const Ipp32fc* pTaps, int
order, const Ipp32fc* pDlyLine  );
IppStatus ippsIIRInitAlloc64fc_32fc(IppsIIRState64fc_32fc** ppState, const Ipp64fc*
pTaps, int order, const Ipp64fc* pDlyLine   );
IppStatus ippsIIRInitAlloc_64fc(IppsIIRState_64fc** ppState, const Ipp64fc* pTaps, int
order, const Ipp64fc* pDlyLine  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                       Pointer to the array containing the taps. The number of elements in
                            the array is 2*( order+1).
tapsFactor                  Scale factor for the taps of integer data type.

order                       Order of the IIR filter.

pDlyLine                    Pointer to the array containing the delay line values. The number of
                            elements in the array is order.
ppState                     Pointer to the pointer to the IIR state structure.

Description
The function ippsIIRInitAlloc is deprecated. This function is obsolete and will be removed in a future
release. Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes an arbitrary IIR filter state. The initialization functions copy the
taps from the array pTaps into the state structure ppState. The tapsFactor is used to scale integer tap
values. The array pDlyLine specifies the delay line values. If the pointer to the array pDlyLine is not NULL,

   310
---------------------Page 311---------------------

                                                                          Filtering Functions  6 

the array content is copied into the context structure, otherwise the delay values of the state structure are
set to 0. The filter order is defined by the order value which is equal to 0 for zero-order filters. The
2*(order + 1)-length array pTaps specifies the taps arranged in the array as follows:
B0, B1, . . ., Border, A0, A1, . . ., Aorder
A0 ≠ 0
If the state is not created, the initialization function returns an error status.
The initialization functions with the 32s_32f suffixes called with floating-point taps automatically convert the
taps into integer data type.
In all cases the data is converted into integer type with scaling for better precision. Example shows how to
convert floating-point taps into integer data type.

Return Values

ippStsNoErr                      Indicates no error.

ippStsMemAllocErr                Indicates an error when no memory allocated.

ippStsNullPtrErr                 Indicates an error when pTaps or ppState is NULL.

ippStsIIROrderErr                Indicates an error when order is less than or equal to 0.

ippStsDivByZeroErr               Indicates an error when A0 is equal to 0.

IIRInitAlloc_BiQuad
DEPRECATED. Allocates memory and initializes the
state structure for the biquad IIR filter.

Syntax
Case 1: Operation on integer samples
IppStatus ippsIIRInitAlloc32s_BiQuad_16s(IppsIIRState32s_16s** ppState, const Ipp32s*
pTaps, int numBq, int tapsFactor, const Ipp32s* pDlyLine    );
IppStatus ippsIIRInitAlloc32s_BiQuad_16s32f(IppsIIRState32s_16s** ppState, const
Ipp32f* pTaps, int numBq, const Ipp32s* pDlyLine    );
IppStatus ippsIIRInitAlloc32f_BiQuad_16s(IppsIIRState32f_16s** ppState, const Ipp32f*
pTaps, int numBq, const Ipp32f* pDlyLine   );
IppStatus ippsIIRInitAlloc64f_BiQuad_16s(IppsIIRState64f_16s** ppState, const Ipp64f*
pTaps, int numBq, const Ipp64f* pDlyLine   );
IppStatus ippsIIRInitAlloc64f_BiQuad_32s(IppsIIRState64f_32s** ppState, const Ipp64f*
pTaps, int numBq, const Ipp64f* pDlyLine   );
IppStatus ippsIIRInitAlloc64f_BiQuad_DF1_32s(IppsIIRState64f_32s** ppState, const
Ipp64f* pTaps, int numBq, const Ipp32s* pDlyLine    );

IppStatus ippsIIRInitAlloc32sc_BiQuad_16sc(IppsIIRState32sc_16sc** ppState, const
Ipp32sc* pTaps, int numBq, int tapsFactor, const Ipp32sc* pDlyLine     );
IppStatus ippsIIRInitAlloc32sc_BiQuad_16sc32fc(IppsIIRState32sc_16sc** ppState, const
Ipp32fc* pTaps, int numBq, const Ipp32sc* pDlyLine    );
IppStatus ippsIIRInitAlloc32fc_BiQuad_16sc(IppsIIRState32fc_16sc** ppState, const
Ipp32fc* pTaps, int numBq, const Ipp32fc* pDlyLine    );
IppStatus ippsIIRInitAlloc64fc_BiQuad_16sc(IppsIIRState64fc_16sc** ppState, const
Ipp64fc* pTaps, int numBq, const Ipp64fc* pDlyLine    );

                                                                                         311
---------------------Page 312---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsIIRInitAlloc64fc_BiQuad_32sc(IppsIIRState64fc_32sc** ppState, const
Ipp64fc* pTaps, int numBq, const Ipp64fc* pDlyLine     );
Case 2: Operation on floating point samples

IppStatus ippsIIRInitAlloc_BiQuad_32f(IppsIIRState_32f** ppState, const Ipp32f* pTaps,
int numBq, const Ipp32f* pDlyLine   );
IppStatus ippsIIRInitAlloc_BiQuad_DF1_32f(IppsIIRState_32f** ppState, const Ipp32f*
pTaps, int numBq, const Ipp32f* pDlyLine    );
IppStatus ippsIIRInitAlloc64f_BiQuad_32f(IppsIIRState64f_32f** ppState, const Ipp64f*
pTaps, int numBq, const Ipp64f* pDlyLine    );
IppStatus ippsIIRInitAlloc_BiQuad_64f(IppsIIRState_64f** ppState, const Ipp64f* pTaps,
int numBq, const Ipp64f* pDlyLine   );

IppStatus ippsIIRInitAlloc_BiQuad_32fc(IppsIIRState_32fc** ppState, const Ipp32fc*
pTaps, int numBq, const Ipp32fc* pDlyLine    );
IppStatus ippsIIRInitAlloc64fc_BiQuad_32fc(IppsIIRState64fc_32fc** ppState, const
Ipp64fc* pTaps, int numBq, const Ipp64fc* pDlyLine     );
IppStatus ippsIIRInitAlloc_BiQuad_64fc(IppsIIRState_64fc** ppState, const Ipp64fc*
pTaps, int numBq, const Ipp64fc* pDlyLine    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                        Pointer to the array containing the taps. The number of elements in
                             the array is 6*numBq.
tapsFactor                   Scale factor for the taps of integer data type.

numBq                        Number of cascades of biquads.

pDlyLine                     Pointer to the array containing the delay line values.

ppState                      Pointer to the pointer to the biquad IIR state structure.

Description
The function ippsIIRInitAlloc_BiQuad is deprecated. This function is obsolete and will be removed in a
future release. Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for
this functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function allocates memory and initializes a biquad (BQ) IIR filter state. The initialization functions copy
the taps from the array pTaps into the state structure ppState. The tapsFactor is used to scale integer tap
values. The array pDlyLine specifies the delay line values. The number of elements in the array pDlyLine is
4*numBq for the function flavor ippsIIRInitAlloc_BiQuad_DF1, and 2* numBq for all other flavors. If the
pointer to the array pDlyLine is not NULL, the array content is copied into the context structure, otherwise
the delay values of the state structure are set to 0.

   312
---------------------Page 313---------------------

                                                                            Filtering Functions  6 

The function flavor ippsIIRInitAlloc_BiQuad_DF1 initializes the filter with the biquad section in the direct
form I (DF1) [Opp75]. In this case the delay line values are arranged in the array as follows:
x0,-2, x0,-1, B0,2, y0,-2, y0,-1, x1,-2, x1,-1, y1,-2, y1,-1, ... xnumBq-1,-2, xnumBq-1,-1, y numBq-1,-2, y numBq-1,-1.
A biquad IIR filter is defined by a cascade of biquads. The number of cascades of biquads is specified by the
numBq value. The 6*numBq -length array pTaps specifies the taps arranged in the array as follows:
B0,0, B0,1, B0,2, A0,0, A0,1, A0,2; B1,0, B1,1, B1,2, A1,0, A1,1, A1,2; . . . AnumBq-1,2
An,0 ≠ 0, Bn,0 ≠ 0
If the state is not created, the initialization function returns an error status.
The initialization functions with the 32s_32f suffixes called with floating-point taps automatically convert the
taps into integer data type.
In all cases the data is converted into integer type with scaling for better precision. Example 6-15 shows how
to convert floating-point taps into integer data type.

Return Values

ippStsNoErr                       Indicates no error.

ippStsMemAllocErr                 Indicates an error when no memory allocated.

ippStsNullPtrErr                  Indicates an error when  pTaps or ppState  is NULL.

ippStsIIROrderErr                 Indicates an error when  numBq is less than or equal to 0.

ippStsDivByZeroErr                Indicates an error when A 0, An,0 or Bn,0 is equal to 0.

IIRFree
DEPRECATED. Closes an IIR filter state.

Syntax
IppStatus ippsIIRFree_32f(IppsIIRState_32f* pState      );
IppStatus ippsIIRFree_64f(IppsIIRState_64f* pState      );
IppStatus ippsIIRFree_32fc(IppsIIRState_32fc* pState      );
IppStatus ippsIIRFree_64fc(IppsIIRState_64fc* pState      );
IppStatus ippsIIRFree32s_16s(IppsIIRState32s_16s* pState       );
IppStatus ippsIIRFree32sc_16sc(IppsIIRState32sc_16sc* pState       );
IppStatus ippsIIRFree32f_16s(IppsIIRState32f_16s* pState       );
IppStatus ippsIIRFree32fc_16sc(IppsIIRState32fc_16sc* pState       );
IppStatus ippsIIRFree64f_16s(IppsIIRState64f_16s* pState       );
IppStatus ippsIIRFree64f_32s(IppsIIRState64f_32s* pState       );
IppStatus ippsIIRFree64f_32f(IppsIIRState64f_32f* pState       );
IppStatus ippsIIRFree64fc_16sc(IppsIIRState64fc_16sc* pState       );
IppStatus ippsIIRFree64fc_32sc(IppsIIRState64fc_32sc* pState       );
IppStatus ippsIIRFree64fc_32fc(IppsIIRState64fc_32fc* pState       );

Include Files
ipps.h

                                                                                            313
---------------------Page 314---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                      Pointer to an IIR filter state structure to be closed.

Description
The function ippsIIRFree is deprecated. This function is obsolete and will be removed in a future release.
Internal memory allocation will not be supported - use Get<Buffer>Size and Init pair for this
functionality. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function closes the IIR filter state by freeing all memory associated with a filter state created by 
IIRInitAlloc or IIRInitAlloc_BiQuad. Call ippsIIRFree after filtering is completed.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pState pointer is NULL.

ippStsContextMatchErr            Indicates an error when the state identifier is incorrect.

IIRInit
Initializes an arbitrary IIR filter state.

Syntax
Case 1: Operation on integer samples
IppStatus ippsIIRInit32f_16s(IppsIIRState32f_16s** ppState, const Ipp32f* pTaps, int
order, const Ipp32f* pDlyLine, Ipp8u* pBuf   );
IppStatus ippsIIRInit64f_16s(IppsIIRState64f_16s** ppState, const Ipp64f* pTaps, int
order, const Ipp64f* pDlyLine, Ipp8u* pBuf   );
IppStatus ippsIIRInit64f_32s(IppsIIRState64f_32s** ppState, const Ipp64f* pTaps, int
order, const Ipp64f* pDlyLine, Ipp8u* pBuf   );

IppStatus ippsIIRInit32fc_16sc(IppsIIRState32fc_16sc** ppState, const Ipp32fc* pTaps,
int order, const Ipp32fc* pDlyLine, Ipp8u* pBuf    );
IppStatus ippsIIRInit64fc_16sc(IppsIIRState64fc_16sc** ppState, const Ipp64fc* pTaps,
int order, const Ipp64fc* pDlyLine, Ipp8u* pBuf    );
IppStatus ippsIIRInit64fc_32sc(IppsIIRState64fc_32sc** ppState, const Ipp64fc* pTaps,
int order, const Ipp64fc* pDlyLine, Ipp8u* pBuf    );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIRInit32s_16s(IppsIIRState32s_16s** ppState, const Ipp32s* pTaps, int
order, int tapsFactor, const Ipp32s* pDlyLine, Ipp8u* pBuf     );
IppStatus ippsIIRInit32s_16s32f(IppsIIRState32s_16s** ppState, const Ipp32f* pTaps, int
order, const Ipp32s* pDlyLine, Ipp8u* pBuf   );
IppStatus ippsIIRInit32sc_16sc(IppsIIRState32sc_16sc** ppState, const Ipp32sc* pTaps,
int order, int tapsFactor, const Ipp32sc* pDlyLine, Ipp8u* pBuf     );

   314
---------------------Page 315---------------------

                                                                           Filtering Functions  6 

IppStatus ippsIIRInit32sc_16sc32fc(IppsIIRState32sc_16sc** ppState, const Ipp32fc*
pTaps, int order, const Ipp32sc* pDlyLine, Ipp8u* pBuf     );
Case 2: Operation on floating point samples
IppStatus ippsIIRInit_32f(IppsIIRState_32f** ppState, const Ipp32f* pTaps, int order,
const Ipp32f* pDlyLine, Ipp8u* pBuf   );
IppStatus ippsIIRInit64f_32f(IppsIIRState64f_32f** ppState, const Ipp64f* pTaps, int
order, const Ipp64f* pDlyLine, Ipp8u* pBuf    );
IppStatus ippsIIRInit_64f(IppsIIRState_64f** ppState, const Ipp64f* pTaps, int order,
const Ipp64f* pDlyLine, Ipp8u* pBuf   );

IppStatus ippsIIRInit_32fc(IppsIIRState_32fc** ppState, const Ipp32fc* pTaps, int
order, const Ipp32fc* pDlyLine, Ipp8u* pBuf    );
IppStatus ippsIIRInit64fc_32fc(IppsIIRState64fc_32fc** ppState, const Ipp64fc* pTaps,
int order, const Ipp64fc* pDlyLine, Ipp8u* pBuf    );
IppStatus ippsIIRInit_64fc(IppsIIRState_64fc** ppState, const Ipp64fc* pTaps, int
order, const Ipp64fc* pDlyLine, Ipp8u* pBuf    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                        Pointer to the array containing the taps. The number of elements in
                             the array is 2*(order+1).
tapsFactor                   Scale factor for the taps of integer data type.

order                        Order of the IIR filter.

pDlyLine                     Pointer to the array containing the delay line values. The number of
                             elements in the array is order.
ppState                      Pointer to the pointer to the arbitrary IIR state structure to be
                             created.
pBuf                         Pointer to the external buffer.

Description
Functions ippsIIRInit32s_16s, ippsIIRInit32s_16s32f  , ippsIIRInit32sc_16sc , and
ippsIIRInit32sc_16sc32fc   are deprecated. These functions are obsolete and will be removed in a future
release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-features-
feedback/.
This function initializes an arbitrary IIR filter state in the external buffer. The size of this buffer must be
computed previously by calling the function IIRGetStateSize. The initialization functions copy the taps from
the array pTaps into the state structure pState. The tapsFactor is used to scale integer tap values. The
order-length array pDlyLine specifies the delay line values. If the pointer to the array pDlyLine is not
NULL, the array content is copied into the context structure, otherwise the delay values of the state structure
are set to 0.

                                                                                          315
---------------------Page 316---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

The filter order is defined by the order value which is equal to 0 for zero-order filters. The 2*( order +
1)-length array pTaps specifies the taps arranged in the array as follows:
B0, B1, . . ., Border, A0, A1, . . ., Aorder
A0 ≠ 0
If the state is not created, the initialization function returns an error status.
The initialization functions with the 32s_32f suffixes called with floating-point taps automatically convert the
taps into integer data type.
In all cases the data is converted into integer type with scaling for better precision. Example shows how to
convert floating-point taps into integer data type.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when one of the specified pointers is NULL.

ippStsDivByZeroErr               Indicates an error when A0 is equal to 0.

ippStsIIROrderErr                Indicates an error when order is less than or equal to 0.

IIRInit_BiQuad
Initializes an IIR filter state.

Syntax
Case 1: Operation on integer samples
IppStatus ippsIIRInit32f_BiQuad_16s(IppsIIRState32f_16s** ppState, const Ipp32f* pTaps,
int numBq, const Ipp32f* pDlyLine, Ipp8u* pBuffer   );
IppStatus ippsIIRInit64f_BiQuad_16s(IppsIIRState64f_16s** ppState, const Ipp64f* pTaps,
int numBq, const Ipp64f* pDlyLine, Ipp8u* pBuffer   );
IppStatus ippsIIRInit64f_BiQuad_32s(IppsIIRState64f_32s** ppState, const Ipp64f* pTaps,
int numBq, const Ipp64f* pDlyLine, Ipp8u* pBuffer   );

IppStatus ippsIIRInit32fc_BiQuad_16sc(IppsIIRState32fc_16sc** ppState, const Ipp32fc*
pTaps, int numBq, const Ipp32fc* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsIIRInit64fc_BiQuad_16sc(IppsIIRState64fc_16sc** ppState, const Ipp64fc*
pTaps, int numBq, const Ipp64fc* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsIIRInit64fc_BiQuad_32sc(IppsIIRState64fc_32sc** ppState, const Ipp64fc*
pTaps, int numBq, const Ipp64fc* pDlyLine, Ipp8u* pBuffer    );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIRInit32s_BiQuad_16s(IppsIIRState32s_16s** ppState, const Ipp32s* pTaps,
int numBq, int tapsFactor, const Ipp32s* pDlyLine, Ipp8u* pBuffer     );
IppStatus ippsIIRInit32s_BiQuad_16s32f(IppsIIRState32s_16s** ppState, const Ipp32f*
pTaps, int numBq, const Ipp32s* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsIIRInit32sc_BiQuad_16sc(IppsIIRState32sc_16sc** ppState, const Ipp32sc*
pTaps, int numBq, int tapsFactor, const Ipp32sc* pDlyLine, Ipp8u* pBuffer     );
IppStatus ippsIIRInit32sc_BiQuad_16sc32fc(IppsIIRState32sc_16sc** ppState, const
Ipp32fc* pTaps, int numBq, const Ipp32sc* pDlyLine, Ipp8u* pBuffer     );
IppStatus ippsIIRInit64f_BiQuad_DF1_32s(IppsIIRState64f_32s** ppState, const Ipp64f*
pTaps, int numBq, const Ipp32s* pDlyLine, Ipp8u* pBuffer    );

   316
---------------------Page 317---------------------

                                                                          Filtering Functions  6 

Case 2: Operation on floating point samples
IppStatus ippsIIRInit_BiQuad_32f(IppsIIRState_32f** ppState, const Ipp32f* pTaps, int
numBq, const Ipp32f* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsIIRInit64f_BiQuad_32f(IppsIIRState64f_32f** ppState, const Ipp64f* pTaps,
int numBq, const Ipp64f* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsIIRInit_BiQuad_64f(IppsIIRState_64f** ppState, const Ipp64f* pTaps, int
numBq, const Ipp64f* pDlyLine, Ipp8u* pBuffer    );

IppStatus ippsIIRInit_BiQuad_32fc(IppsIIRState_32fc** ppState, const Ipp32fc* pTaps,
int numBq, const Ipp32fc* pDlyLine, Ipp8u* pBuffer    );
IppStatus ippsIIRInit64fc_BiQuad_32fc(IppsIIRState64fc_32fc** ppState, const Ipp64fc*
pTaps, int numBq, const Ipp64fc* pDlyLine, Ipp8u* pBuffer     );
IppStatus ippsIIRInit_BiQuad_64fc(IppsIIRState_64fc** ppState, const Ipp64fc* pTaps,
int numBq, const Ipp64fc* pDlyLine, Ipp8u* pBuffer    );
THE FOLLOWING FUNCTION IS DEPRECATED:
IppStatus ippsIIRInit_BiQuad_DF1_32f(IppsIIRState_32f** pState, const Ipp32f* pTaps,
int numBq, const Ipp32f* pDlyLine, Ipp8u* pBuffer    );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                       Pointer to the array containing the taps. The number of elements in
                            the array is 6*numBq.
tapsFactor                  Scale factor for the taps of integer data type.

numBq                       Number of cascades of biquads.

pDlyLine                    Pointer to the array containing the delay line values. The number of
                            elements in the array is 2*numBq.
ppState                     Pointer to the pointer to the biquad IIR state structure.

pBuffer                     Pointer to the external buffer.

Description
Functions ippsIIRInit_BiQuad_DF1_32f , ippsIIRInit32s_BiQuad_16s ,
ippsIIRInit32s_BiQuad_16s32f  , ippsIIRInit32sc_BiQuad_16sc  ,
ippsIIRInit32sc_BiQuad_16sc32fc  , and ippsIIRInit64f_BiQuad_DF1_32s   are deprecated. These
functions are obsolete and will be removed in a future release. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function initializes a biquad (BQ) IIR filter state in the external buffer. The size of this buffer must be
computed previously by calling the corresponding function IIRGetStateSize_BiQuad. The initialization function
copies the taps from the array pTaps into the state structure ppState. The tapsFactor is used to scale
integer tap values. The array pDlyLine specifies the delay line values. The number of elements in the array
pDlyLine is 4*numBq for the function flavor ippsIIRInit_BiQuad_DF1, and 2* numBq for all other flavors.

                                                                                         317
---------------------Page 318---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

If the pointer to the array pDlyLine is not NULL, the array content is copied into the context structure,
otherwise the delay values of the state structure are set to 0.
The function flavor ippsIIRInit_BiQuad_DF1 operates with the delay line values that are arranged in the
array as follows:
x0,-2, x0,-1, B0,2, y0,-2, y0,-1, x1,-2, x1,-1, y1,-2, y1,-1, ... xnumBq-1,-2, xnumBq-1,-1, y numBq-1,-2, y numBq-1,-1.

A biquad IIR filter is defined by a cascade of biquads. The number of cascades of biquads is specified by the
numBq value. The 6*numBq -length array pTaps specifies the taps arranged in the array as follows:
B0,0, B0,1, B0,2, A0,0, A0,1, A0,2; B1,0, B1,1, B1,2, A1,0, A1,1, A1,2; . . . AnumBq-1,2
An,0 ≠ 0, Bn,0 ≠ 0
If the state is not created, the initialization function returns an error status.
The initialization functions with the 32s_32f suffixes called with floating-point taps automatically convert the
taps into integer data type.
In all cases the data is converted into integer type with scaling for better precision. Example shows how to
convert floating-point taps into integer data type.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when one of the specified pointers is NULL.

ippStsDivByZeroErr                Indicates an error when A 0, An,0 or Bn,0 is equal to 0.

ippStsIIROrderErr                 Indicates an error when  numBq  is less than or equal to 0.

IIRGetStateSize
Computes the length of the external buffer for the
arbitrary IIR filter state structure.

Syntax
IppStatus ippsIIRGetStateSize32f_16s(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize64f_16s(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize64f_32s(int order, int* pBufferSize        );

IppStatus ippsIIRGetStateSize32fc_16sc(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize64fc_16sc(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize64fc_32sc(int order, int* pBufferSize        );

IppStatus ippsIIRGetStateSize_32f(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize64f_32f(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize_64f(int order, int* pBufferSize        );

IppStatus ippsIIRGetStateSize_32fc(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize64fc_32fc(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize_64fc(int order, int* pBufferSize        );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIRGetStateSize32s_16s(int order, int* pBufferSize        );
IppStatus ippsIIRGetStateSize32s_16s32f(int order, int* pBufferSize         );

   318
---------------------Page 319---------------------

                                                                         Filtering Functions  6 

IppStatus ippsIIRGetStateSize32sc_16sc(int order, int* pBufferSize     );
IppStatus ippsIIRGetStateSize32sc_16sc32fc(int order, int* pBufferSize     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

order                       Order of the IIR filter.

pBufferSize                 Pointer to the computed buffer size value.

Description
Functions ippsIIRGetStateSize32s_16s, ippsIIRGetStateSize32s_16s32f  ,
ippsIIRGetStateSize32sc_16sc  , and ippsIIRGetStateSize32sc_16sc32fc  are deprecated. These
functions are obsolete and will be removed in a future release. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function computes the size of the external buffer for an arbitrary IIR filter state, and stores the result in
pBufferSize.
To compute a size of the buffer, the filter order parameter order must be specified.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when pBufferSize pointer is NULL.

ippStsIIROrderErr                Indicates an error when order is less than or equal to 0.

IIRGetStateSize_BiQuad
Computes the length of the external buffer for the
biquad IIR filter state structure.

Syntax
IppStatus ippsIIRGetStateSize32f_BiQuad_16s(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize64f_BiQuad_16s(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize64f_BiQuad_32s(int numBq, int* pBufferSize     );

IppStatus ippsIIRGetStateSize32fc_BiQuad_16sc(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize64fc_BiQuad_16sc(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize64fc_BiQuad_32sc(int numBq, int* pBufferSize     );

IppStatus ippsIIRGetStateSize_BiQuad_32f(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize64f_BiQuad_32f(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize_BiQuad_64f(int numBq, int* pBufferSize     );

IppStatus ippsIIRGetStateSize_BiQuad_32fc(int numBq, int* pBufferSize     );

                                                                                        319
---------------------Page 320---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

IppStatus ippsIIRGetStateSize64fc_BiQuad_32fc(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize_BiQuad_64fc(int order, int* pBufferSize     );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIRGetStateSize_BiQuad_DF1_32f(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize32s_BiQuad_16s(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize32s_BiQuad_16s32f(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize32sc_BiQuad_16sc(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize32sc_BiQuad_16sc32fc(int numBq, int* pBufferSize     );
IppStatus ippsIIRGetStateSize64f_BiQuad_DF1_32s(int numBq, int* pBufferSize     );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

numBq                       Number of cascades of biquads.

pBufferSize                 Pointer to the computed buffer size value.

Description
Functions ippsIIRGetStateSize_BiQuad_DF1_32f , ippsIIRGetStateSize32s_BiQuad_16s  ,
ippsIIRGetStateSize32s_BiQuad_16s32f  , ippsIIRGetStateSize32sc_BiQuad_16sc  ,
ippsIIRGetStateSize32sc_BiQuad_16sc32fc  , and ippsIIRGetStateSize64f_BiQuad_DF1_32s   are
deprecated. These functions are obsolete and will be removed in a future release. Use the following link for
details: http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function computes the size of the external buffer for a corresponding biquad IIR filter state, and stores
the result in pBufferSize.
To compute a size of the buffer, the number of cascades of biquads numBq must be specified.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when pBufferSize pointer is NULL.

ippStsIIROrderErr                Indicates an error when numBq is less than or equal to 0.

IIRSetTaps
DEPRECATED. Sets the taps in an IIR filter state.

Syntax
IppStatus ippsIIRSetTaps_32f(const Ipp32f* pTaps, IppsIIRState_32f* pState     );
IppStatus ippsIIRSetTaps_32fc(const Ipp32fc* pTaps, IppsIIRState_32fc* pState     );
IppStatus ippsIIRSetTaps_64f(const Ipp64f* pTaps, IppsIIRState_64f* pState     );
IppStatus ippsIIRSetTaps_64fc(const Ipp64fc* pTaps, IppsIIRState_64fc* pState     );

   320
---------------------Page 321---------------------

                                                                          Filtering Functions  6 

IppStatus ippsIIRSetTaps32s_16s(const Ipp32s* pTaps, IppsIIRState32s_16s* pState, int
tapsFactor);
IppStatus ippsIIRSetTaps32s_16s32f(const Ipp32f* pTaps, IppsIIRState32s_16s* pState       );
IppStatus ippsIIRSetTaps32sc_16sc(const Ipp32sc* pTaps, IppsIIRState32sc_16sc* pState,
int tapsFactor );
IppStatus ippsIIRSetTaps32sc_16sc32fc(const Ipp32fc* pTaps, IppsIIRState32sc_16sc*
pState);
IppStatus ippsIIRSetTaps32f_16s(const Ipp32f* pTaps, IppsIIRState32f_16s* pState       );
IppStatus ippsIIRSetTaps32fc_16sc(const Ipp32fc* pTaps, IppsIIRState32fc_16sc* pState        );
IppStatus ippsIIRSetTaps64f_16s(const Ipp64f* pTaps, IppsIIRState64f_16s* pState       );
IppStatus ippsIIRSetTaps64f_32s(const Ipp64f* pTaps, IppsIIRState64f_32s* pState       );
IppStatus ippsIIRSetTaps64f_32f(const Ipp64f* pTaps, IppsIIRState64f_32f* pState       );
IppStatus ippsIIRSetTaps64fc_16sc(const Ipp64fc* pTaps, IppsIIRState64fc_16sc* pState        );
IppStatus ippsIIRSetTaps64fc_32sc(const Ipp64fc* pTaps, IppsIIRState64fc_32sc* pState        );
IppStatus ippsIIRSetTaps64fc_32fc(const Ipp64fc* pTaps, IppsIIRState64fc_32fc* pState        );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pTaps                       Pointer to the array containing the tap values.

pState                      Pointer to the IIR filter state structure.

tapsFactor                  Scale factor for the taps of Ipp32s data type (for integer versions
                            only).

Description
The function ippsIIRSetTaps is deprecated. This function is obsolete and will be removed in a future
release. Use Init function instead of SetTaps for changing filter coefficients. Use the following link for
details: http://software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function sets new tap values in the previously initialized IIR filter state structure pState. New tap
values must be specified in the array pTaps. To scale integer taps use the tapsFactor value.
The filter state must be initialized before calling the function ippsIIRSetTaps. The length of the array
pTaps must be equal to the tapsLen parameter of the initialized filter state.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when one of the specified pointers is NULL.

ippStsDivByZeroErr               Indicates an error when A0 is equal to 0 for an arbitrary IIR
                                 filter state, or A0, An,0 or Bn,0 is equal to 0 for a biquad IIR filter
                                 state.

                                                                                         321
---------------------Page 322---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ippStsContextMatchErr          Indicates an error when the state identifier is incorrect.

IIRGetDlyLine
Retrieves the delay line contents from the IIR filter
state.

Syntax
IppStatus ippsIIRGetDlyLine32f_16s(const IppsIIRState32f_16s* pState, Ipp32f*
pDlyLine);
IppStatus ippsIIRGetDlyLine64f_16s(const IppsIIRState64f_16s* pState, Ipp64f*
pDlyLine);
IppStatus ippsIIRGetDlyLine64f_32s(const IppsIIRState64f_32s* pState, Ipp64f*
pDlyLine);
IppStatus ippsIIRGetDlyLine32fc_16sc(const IppsIIRState32fc_16sc* pState, Ipp32fc*
pDlyLine);
IppStatus ippsIIRGetDlyLine64fc_16sc(const IppsIIRState64fc_16sc* pState, Ipp64fc*
pDlyLine);
IppStatus ippsIIRGetDlyLine64fc_32sc(const IppsIIRState64fc_32sc* pState, Ipp64fc*
pDlyLine);
IppStatus ippsIIRGetDlyLine_32f(const IppsIIRState_32f* pState, Ipp32f* pDlyLine  );
IppStatus ippsIIRGetDlyLine64f_32f(const IppsIIRState64f_32f* pState, Ipp64f*
pDlyLine);
IppStatus ippsIIRGetDlyLine_64f(const IppsIIRState_64f* pState, Ipp64f* pDlyLine  );
IppStatus ippsIIRGetDlyLine_32fc(const IppsIIRState_32fc* pState, Ipp32fc* pDlyLine   );
IppStatus ippsIIRGetDlyLine64fc_32fc(const IppsIIRState64fc_32fc* pState, Ipp64fc*
pDlyLine);
IppStatus ippsIIRGetDlyLine_64fc(const IppsIIRState_64fc* pState, Ipp64fc* pDlyLine   );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIRGetDlyLine32s_16s(const IppsIIRState32s_16s* pState, Ipp32s*
pDlyLine);
IppStatus ippsIIRGetDlyLine32sc_16sc(const IppsIIRState32sc_16sc* pState, Ipp32sc*
pDlyLine);
IppStatus ippsIIRGetDlyLine64f_DF1_32s(const IppsIIRState64f_32s* pState, Ipp32s*
pDlyLine);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                     Pointer to the IIR filter state structure.

  322
---------------------Page 323---------------------

                                                                          Filtering Functions  6 

pDlyLine                    Pointer to the array containing the delay line values. The number of
                            elements in the array is order for arbitrary filters and 2*numBq for
                            BQ filters.

Description
Functions ippsIIRGetDlyLine32s_16s, ippsIIRGetDlyLine32sc_16sc  , and
ippsIIRGetDlyLine64f_DF1_32s   are deprecated. These functions are obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function copies the delay line values from the corresponding state structure pState and stores them
into the arrays pDlyLine. If the pointer is NULL, then the delay line values in the state structure are
initialized to zero.
The corresponding filter state must be previously initialized by the one of the initialization functions.

Return Values

ippStsNoErr                      Indicates no error.

ippStsNullPtrErr                 Indicates an error when the pState pointers is NULL.

ippStsContextMatchErr            Indicates an error when the state identifier is incorrect.

IIRSetDlyLine
Sets the delay line contents in an IIR filter state.

Syntax
IppStatus ippsIIRSetDlyLine32f_16s(IppsIIRState32f_16s* pState, const Ipp32f*
pDlyLine);
IppStatus ippsIIRSetDlyLine64f_16s(IppsIIRState64f_16s* pState, const Ipp64f*
pDlyLine);
IppStatus ippsIIRSetDlyLine64f_32s(IppsIIRState64f_32s* pState, const Ipp64f*
pDlyLine);

IppStatus ippsIIRSetDlyLine32fc_16sc(IppsIIRState32fc_16sc* pState, const Ipp32fc*
pDlyLine);
IppStatus ippsIIRSetDlyLine64fc_16sc(IppsIIRState64fc_16sc* pState, const Ipp64fc*
pDlyLine);
IppStatus ippsIIRSetDlyLine64fc_32sc(IppsIIRState64fc_32sc* pState, const Ipp64fc*
pDlyLine);

IppStatus ippsIIRSetDlyLine_32f(IppsIIRState_32f* pState, const Ipp32f* pDlyLine      );
IppStatus ippsIIRSetDlyLine64f_32f(IppsIIRState64f_32f* pState, const Ipp64f*
pDlyLine);
IppStatus ippsIIRSetDlyLine_64f(IppsIIRState_64f* pState, const Ipp64f* pDlyLine      );
IppStatus ippsIIRSetDlyLine_32fc(IppsIIRState_32fc* pState, const Ipp32fc* pDlyLine       );
IppStatus ippsIIRSetDlyLine64fc_32fc(IppsIIRState64fc_32fc* pState, const Ipp64fc*
pDlyLine);
IppStatus ippsIIRSetDlyLine_64fc(IppsIIRState_64fc* pState, const Ipp64fc* pDlyLine       );

                                                                                         323
---------------------Page 324---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIRSetDlyLine32s_16s(IppsIIRState32s_16s* pState, const Ipp32s*
pDlyLine);
IppStatus ippsIIRSetDlyLine32sc_16sc(IppsIIRState32sc_16sc* pState, const Ipp32sc*
pDlyLine);
IppStatus ippsIIRSetDlyLine64f_DF1_32s(IppsIIRState64f_32s* pState, const Ipp32s*
pDlyLine);

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                       Pointer to the IIR filter state structure.

pDlyLine                     Pointer to the array holding the delay line values. The number of
                             elements in the array is order for arbitrary filters and 2*numBq for
                             BQ filters. If the pointer is NULL, then the delay line values in the
                             state structure are initialized to zero.

Description
Functions ippsIIRSetDlyLine32s_16s , ippsIIRSetDlyLine32sc_16sc  , and
ippsIIRSetDlyLine64f_DF1_32s    are deprecated. These functions are obsolete and will be removed in a
future release. Use the following link for details: http://software.intel.com/sites/products/ipp-deprecated-
features-feedback/.
This function copies the delay line values from pDlyLine and stores them into the state structure pState. If
the pointer is NULL, then the delay line values in the state structure are initialized to zero.
The filter state must be previously initialized by the one of the initialization functions.

Return Values

ippStsNoErr                       Indicates no error.

ippStsNullPtrErr                  Indicates an error when the pState pointers is NULL.

ippStsContextMatchErr             Indicates an error when the state identifier is incorrect.

IIROne
DEPRECATED. Filters a single sample through an IIR
filter.

Syntax
IppStatus ippsIIROne_32f(Ipp32f src, Ipp32f* pDstVal, IppsIIRState_32f* pState        );
IppStatus ippsIIROne_64f(Ipp64f src, Ipp64f* pDstVal, IppsIIRState_64f* pState        );
IppStatus ippsIIROne64f_32f(Ipp32f src, Ipp32f* pDstVal, IppsIIRState64f_32f* pState         );
IppStatus ippsIIROne_32fc(Ipp32fc src, Ipp32fc* pDstVal, IppsIIRState_32fc* pState         );
IppStatus ippsIIROne_64fc(Ipp64fc src, Ipp64fc* pDstVal, IppsIIRState_64fc* pState         );

   324
---------------------Page 325---------------------

                                                                           Filtering Functions  6 

IppStatus ippsIIROne64fc_32fc(Ipp32fc src, Ipp32fc* pDstVal, IppsIIRState64fc_32fc*
pState);

IppStatus ippsIIROne32s_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, IppsIIRState32s_16s*
pState, int scaleFactor  );
IppStatus ippsIIROne32f_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, IppsIIRState32f_16s*
pState, int scaleFactor  );
IppStatus ippsIIROne64f_16s_Sfs(Ipp16s src, Ipp16s* pDstVal, IppsIIRState64f_16s*
pState, int scaleFactor  );
IppStatus ippsIIROne64f_32s_Sfs(Ipp32s src, Ipp32s* pDstVal, IppsIIRState64f_32s*
pState, int scaleFactor  );

IppStatus ippsIIROne32sc_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, IppsIIRState32sc_16sc*
pState, int scaleFactor  );
IppStatus ippsIIROne32fc_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, IppsIIRState32fc_16sc*
pState, int scaleFactor  );
IppStatus ippsIIROne64fc_16sc_Sfs(Ipp16sc src, Ipp16sc* pDstVal, IppsIIRState64fc_16sc*
pState, int scaleFactor  );
IppStatus ippsIIROne64fc_32sc_Sfs(Ipp32sc src, Ipp32sc* pDstVal, IppsIIRState64fc_32sc*
pState, int scaleFactor  );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                       Pointer to the IIR filter state structure.

src                          Input sample.

pDstVal                      Pointer to the output filtered sample.

scaleFactor                  Scale factor, refer to Integer Scaling.

Description
The function ippsIIROne is deprecated. This function is obsolete and will be removed in a future release.
Use vector function with vector length = 1 instead. Use the following link for details: http://
software.intel.com/sites/products/ipp-deprecated-features-feedback/.
This function filters a single sample src through an IIR filter with real taps, and stores the result in pDstVal.
The filter parameters are specified in pState. The output of the integer sample is scaled according to
scaleFactor  and can be saturated.
Do not modify the scaleFactor value unless the state structure is changed.
The filter state must be initialized before calling the function ippsFIROne function. Specify the number of
taps tapsLen, the tap values in pTaps, the delay line values in pDlyLine, and the order or numBq value
beforehand.

                                                                                          325
---------------------Page 326---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

Return Values

ippStsNoErr                     Indicates no error.

ippStsNullPtrErr                Indicates an error when one of the specified pointers is NULL.

ippStsContextMatchErr           Indicates an error when the state identifier is incorrect.

IIR
Filters a source vector through an IIR filter.

Syntax
Case 1: Not-in-place operation on integer samples
IppStatus ippsIIR32f_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int len,
IppsIIRState32f_16s* pState, int scaleFactor );
IppStatus ippsIIR64f_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int len,
IppsIIRState64f_16s* pState, int scaleFactor );
IppStatus ippsIIR64f_32s_Sfs(const Ipp32s* pSrc, Ipp32s* pDst, int len,
IppsIIRState64f_32s* pState, int scaleFactor );

IppStatus ippsIIR32fc_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int len,
IppsIIRState32fc_16sc* pState, int scaleFactor );
IppStatus ippsIIR64fc_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int len,
IppsIIRState64fc_16sc* pState, int scaleFactor );
IppStatus ippsIIR64fc_32sc_Sfs(const Ipp32sc* pSrc, Ipp32sc* pDst, int len,
IppsIIRState64fc_32sc* pState, int scaleFactor );
THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIR32s_16s_Sfs(const Ipp16s* pSrc, Ipp16s* pDst, int len,
IppsIIRState32s_16s* pState, int scaleFactor );
IppStatus ippsIIR32sc_16sc_Sfs(const Ipp16sc* pSrc, Ipp16sc* pDst, int len,
IppsIIRState32sc_16sc* pState, int scaleFactor );
Case 2: Not-in-place operation on floating point samples
IppStatus ippsIIR_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len, IppsIIRState_32f*
pState);
IppStatus ippsIIR_64f(const Ipp64f* pSrc, Ipp64f* pDst, int len, IppsIIRState_64f*
pState);
IppStatus ippsIIR64f_32f(const Ipp32f* pSrc, Ipp32f* pDst, int len,
IppsIIRState64f_32f* pState );
IppStatus ippsIIR_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len, IppsIIRState_32fc*
pState);
IppStatus ippsIIR_64fc(const Ipp64fc* pSrc, Ipp64fc* pDst, int len, IppsIIRState_64fc*
pState);
IppStatus ippsIIR64fc_32fc(const Ipp32fc* pSrc, Ipp32fc* pDst, int len,
IppsIIRState64fc_32fc* pState );
Case 3: In-place operation on integer samples
IppStatus ippsIIR32f_16s_ISfs(Ipp16s* pSrcDst, int len, IppsIIRState32f_16s* pState,
int scaleFactor);

  326
---------------------Page 327---------------------

                                                                      Filtering Functions  6 

IppStatus ippsIIR32fc_16sc_ISfs(Ipp16sc* pSrcDst, int len, IppsIIRState32fc_16sc*
pState, int scaleFactor);
THE FOLLOWING FUNCTIONS ARE DEPRECATED
IppStatus ippsIIR32s_16s_ISfs(Ipp16s* pSrcDst, int len, IppsIIRState32s_16s* pState,
int scaleFactor);
IppStatus ippsIIR64f_16s_ISfs(Ipp16s* pSrcDst, int len, IppsIIRState64f_16s* pState,
int scaleFactor);
IppStatus ippsIIR64f_32s_ISfs(Ipp32s* pSrcDst, int len, IppsIIRState64f_32s* pState,
int scaleFactor);
IppStatus ippsIIR32sc_16sc_ISfs(Ipp16sc* pSrcDst, int len, IppsIIRState32sc_16sc*
pState, int scaleFactor);
IppStatus ippsIIR64fc_16sc_ISfs(Ipp16sc* pSrcDst, int len, IppsIIRState64fc_16sc*
pState, int scaleFactor);
IppStatus ippsIIR64fc_32sc_ISfs(Ipp32sc* pSrcDst, int len, IppsIIRState64fc_32sc*
pState, int scaleFactor);
Case 4: In-place operation on floating point samples. THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIR_32f_I(Ipp32f* pSrcDst, int len, IppsIIRState_32f* pState  );
IppStatus ippsIIR_64f_I(Ipp64f* pSrcDst, int len, IppsIIRState_64f* pState  );
IppStatus ippsIIR64f_32f_I(Ipp32f* pSrcDst, int len, IppsIIRState64f_32f* pState  );
IppStatus ippsIIR_32fc_I(Ipp32fc* pSrcDst, int len, IppsIIRState_32fc* pState  );
IppStatus ippsIIR_64fc_I(Ipp64fc* pSrcDst, int len, IppsIIRState_64fc* pState  );
IppStatus ippsIIR64fc_32fc_I(Ipp32fc* pSrcDst, int len, IppsIIRState64fc_32fc* pState  );
Case 4: Operation with specified number of vector. THE FOLLOWING FUNCTIONS ARE DEPRECATED:
IppStatus ippsIIR_32f_P(const Ipp32f** ppSrc, Ipp32f** ppDst, int len, int nChannels,
IppsIIRState_32f** ppState);
IppStatus ippsIIR64f_32s_PSfs(const Ipp32s** ppSrc, Ipp32s** ppDst, int len, int
nChannels, IppsIIRState_32s** ppState, int* pScaleFactornChannels );
IppStatus ippsIIR_32f_IP(Ipp32f** ppSrcDst, int len, int nChannels, IppsIIRState_32f**
ppState);
IppStatus ippsIIR64f_32s_IPSfs(Ipp32s** ppSrcDst, int len, int nChannels,
IppsIIRState_32s** ppState, int* pScaleFactor );

Include Files
ipps.h

Domain Dependencies
Headers: ippcore.h, ippvm.h
Libraries: ippcore.lib, ippvm.lib

Parameters

pState                     Pointer to the IIR filter state structure.

ppState                    Pointer to the array of the pointers to the IIR filter state structures.

pSrc                       Pointer to the source vector.

                                                                                    327
---------------------Page 328---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

ppSrc                         Pointer to the array of pointers to the source vectors.

pDst                          Pointer to the destination vector.

pSrcDst                       Pointer to the source and destination vector for the in-place
                              operations.
ppSrcDst                      Pointer to the array of pointers to the source and destination vectors
                              for the in-place operations.
len                           Number of elements of the vector to be filtered.

nChannels                     Number of vectors to be filtered.

scaleFactor                   Scale factor, refer to Integer Scaling.

Description
Functions ippsIIR_32f_IP , ippsIIR_32f_P  , ippsIIR32s_16s_ISfs  , ippsIIR32s_16s_Sfs   ,
ippsIIR32sc_16sc_ISfs    , and ippsIIR32sc_16sc_Sfs    are deprecated. These functions are obsolete and
will be removed in a future release. Use the following link for details: http://software.intel.com/sites/
products/ipp-deprecated-features-feedback/.
This function filters len elements of the source vector pSrc or pSrcDst through an IIR filter, and stores the
results in pDst or pSrcDst, respectively. The filter parameters are specified in pState.The output of the
integer sample is scaled according to scaleFactor and can be saturated.
Do not modify the scaleFactor  value unless the state structure is changed.
The filter state must be initialized before calling the function ippsIIR. Specify the number of taps tapsLen,
the tap values in pTaps, the delay line values in pDlyLine, and the order or numBq value beforehand.
Function flavors described in the Case 4 filter simultaneously the nChannels source vectors. Each vector
must have the len elements and is filtered with its own state structure. These state structures must be
initialized beforehand.
Example demonstrates how to use the function ippsIIR to filter a sample. The function
ippsConvert_64f32s_Sfs    converts floating-point taps into integer data type before calling
ippsIIRInitAlloc_32s   .

Return Values

ippStsNoErr                         Indicates no error.

ippStsNullPtrErr                    Indicates an error when one of the specified pointers is NULL .

ippStsSizeErr                       Indicates an error when  len is less or equal to 0.

ippStsChannelErr                    Indicates an error when  nChannels  is less or equal to 0.

ippStsContextMatchErr               Indicates an error when the state identifier is incorrect.

Example
The example below illustrates using ippsIIR_32f function.
IppStatus iir( void )
{ 
#undef NUMITERS 
#define NUMITERS 150
     int n;
     IppStatus status;
     IppsIIRState_32f *ctx;
     Ipp32f *x = ippsMalloc_32f( NUMITERS ), *y = ippsMalloc_32f( NUMITERS );
     /// A second-order notch filter having notch freq at 60 Hz

   328
---------------------Page 329---------------------

                                                                          Filtering Functions  6 

     const float taps[] = {
        0.940809f,-1.105987f,0.940809f,1,-1.105987f,0.881618f
     };
     /// generate a signal having 60 Hz freq sampled with 400 Hz freq
     for(n=0;n<NUMITERS;++n)x[n]=(float)sin(IPP_2PI *n *60 /400);
     ippsIIRInitAlloc_32f( &ctx, taps, 2, NULL );
     status = ippsIIR_32f( x, y, NUMITERS, ctx );
     printf_32f( " IIR 32f output+120 =", y+120, 5, status );
     ippsIIRFree_32f( ctx );
     ippsFree( y );
     ippsFree( x );
     return status; 
} 

Output:
    IIR 32f output + 120 =  -0.000094 0.000339 0.000458 0.000208 -0.000173 
Matlab* Analog:
    >> B = [0.940809,-1.105987,0.940809]; A = [1,-1.105987,0.881618];
    n = 0:150; x = sin(2*pi*n*60/400); y = filter(B,A,x); y(121:125)

The example below shows how to use ippsIIR function to filter a sample.
IppStatus iir16s( void ) { 
#undef NUMITERS 
#define NUMITERS 150
     int n, tapsfactor = 30;
     IppStatus status;
     IppsIIRState32s_16s *ctx;
     Ipp16s *x = ippsMalloc_16s( NUMITERS ), *y = ippsMalloc_16s( NUMITERS );
     /// A second-order notch filter having notch freq at 60 Hz
     Ipp64f taps[6] = {
        0.940809f,-1.105987f,0.940809f,1,-1.105987f,0.881618f
     };
     Ipp32s taps32s[6];
     Ipp64f tmax, tmp[6];
     ippsAbs_64f( taps, tmp, 6 );
     ippsMax_64f( tmp, 6, &tmax );
     tapsfactor = 0;
     if( tmax > IPP_MAX_32S )
        while( (tmax/=2) > IPP_MAX_32S ) ++tapsfactor;
     else
        while( (tmax*=2) < IPP_MAX_32S ) --tapsfactor;
     if(tapsfactor >0 )
        ippsDivC_64f_I( (float)(1<<(++tapsfactor)), taps, 6 );
     else if( tapsfactor < 0 )
        ippsMulC_64f_I( (float)(1<<(-(tapsfactor))), taps, 6 );
     ippsConvert_64f32s_Sfs( taps, taps32s, 6, ippRndNear, 0 );
     /// generate a signal of 60 Hz freq that is sampled with 400 Hz freq
     for(n=0; n<NUMITERS; ++n) x[n] = (Ipp16s)(1000*sin(IPP_2PI*n*60/400));
     ippsIIRInitAlloc32s_16s( &ctx, taps32s, 2, tapsfactor, NULL );
     status = ippsIIR32s_16s_Sfs( x, y, NUMITERS, ctx, 0 );
     printf_16s( " IIR 32s output+120 =", y+120, 5, status );
     ippsIIRFree32s_16s( ctx );
     ippsFree( y );
     ippsFree( x );
     return status; 
}

Output:
    IIR 32s output + 120 =  0 0 0 0 0

                                                                                         329
---------------------Page 330---------------------

 6    Intel® Integrated Performance Primitives Reference Manual, Volume 1: Signal Processing

The example below shows hot to use ippsIIR function for low pass filtering.
#include <ipp.h> 
/* 
y[n] = ( 1 * x[n- 2]) 
+ ( 2 * x[n- 1]) 
+ ( 1 * x[n- 0]) 
+ ( -0.1958157127 * y[n- 2]) 
+ ( -0.3695273774 * y[n- 1]) 
*/ 
#define NZEROS 2 
#define NPOLES 2 
#define GAIN 2.555350342e+00f 
static float xv[NZEROS+1], yv[NPOLES+1]; 
static void filterloop( const float* x, float* y, int len ) 
{ for (int i=0; i<len; i++ )
{ xv[0] = xv[1]; xv[1] = xv[2]; 
xv[2] = x[i] / GAIN; 
yv[0] = yv[1]; yv[1] = yv[2]; 
yv[2] = (xv[0] + xv[2]) + 2 * xv[1] 
+ ( -0.1958157127f * yv[0]) + ( -0.3695273774f * yv[1]); 
y[i] = yv[2]; 
} 
} 
const int LEN = 100; 
int main() { 
float x[LEN], yu[LEN], yi[LEN]; 
for(int i=0; i<LEN; i++) x[i] = i-3; 
/// customer will compute 
/// -1.1740073 -2.6968584 -1.9042342 -0.33358926 
filterloop(x,yu,LEN); 
/// matlab gives 
///>> b=[1 2 1];a=[1 0.3695273774 0.1958157127 ];x=[-3:1:15]/2.555350342;filter(b,a,x) 
/// -1.1740 -2.6969 -1.9042 -0.3336 
///     will compute 
/// -1.1740074 -2.6968584 -1.9042342 -0.33358920 
const int order = 2; 
float taps[6] = {1.0f, 2.0f, 1.0f, 1.0f, 0.3695273774f, 0.1958157127f}; 
IppsIIRState_32f *ctx; 
ippsIIRInitAlloc_32f( &ctx, taps, order, (Ipp32f*)0 ); 
ippsDivC_32f_I( GAIN, x, LEN); 
ippsIIR_32f( x, y