Intel Integrated Performance Primitives for Intel Architecture. Using Intel Integrated Performance Primitives in C++ Applications

Transcription

1 Intel Integrated Performance Primitives for Intel Architecture Using Intel Integrated Performance Primitives in C++ Applications Version 2.0 June, 2004

2 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. Intel products are not intended for use in medical, life saving, or life sustaining applications. This document as well as the software described in it is furnished under license and may only be used or copied in accordance with the terms of the license. The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. 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 software described in this document may contain software defects which may cause the product to deviate from published specifications. Current characterized errata are available on request. Intel SpeedStep, Celeron, Dialogic, i386, i486, icomp, Intel, Intel Centrino, Intel logo, Intel386, Intel486, Intel740, IntelDX2, IntelDX4, IntelSX2, Intel Inside, Intel Inside logo, Intel NetBurst, Intel NetStructure, Intel Xeon, Intel XScale, Itanium, MMX, MMX logo, Pentium, Pentium II Xeon, Pentium III Xeon, and VTune are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. * Other names and brands may be claimed as the property of others. Copyright Intel Corporation.

3 Table of Contents Introduction...4 Interface Discussion...4 CIir Template Class Library Reference...5 CArgTypes Template Class...5 Definition...5 Specializations Base CIir Class Members...6 CIir::CIir...6 CIir::SetDly...6 CIir::GetDly...7 CIir::Filter...7 CIir:: GetLastStatus...7 CIir::Free...7 CIirAR Class Members...8 CIirAR::CIirAR...8 CIirBQ Class Members...8 CIirBQ::CIirBQ...8 Exception Handling...9 Demo Application...9 Test 1: 32f-data 64f-taps IIR filter Accuracy Evaluation...10 Test 2: 32f-data 32f-taps IIR Filter Accuracy Evaluation...10 Test 3: Point-wise IIR Filter Accuracy Evaluation...12 Test 4: Delay Line Compatibility for Switching from Point-wise to Vector Filtering...12 Test 5: In-Place IIR Filter Accuracy Evaluation...13 Test 6: Biquad IIR Filter Accuracy Evaluation...13 Application Output...13 Summary...14 References...14 iii

4 Introduction The Intel Integrated Performance Primitives (Intel IPP) provide an interface to develop applications in the C language. However, Intel IPP may also be used for developing applications in many different languages. The Intel IPP sample demonstrates the use of Intel IPP libraries in C++ applications. In particular, the sample described in more detail later in this document shows how Intel IPP C-library functions can be overloaded in the C++ interface to subsequently serve as the basis for creating special classes for easy access to the large variety of signal and image processing as well as string manipulation functions. The sample package contains header files for all Intel IPP function overloads for signal and image processing libraries, as well as a specially developed code of the demonstration application and newly created classes for it. This demo application shows how to create a C++ application that performs simple testing of the functionality of the infinite impulse response (IIR) filters created with the Intel IPP functions for signal processing. The main goal of this sample is to stimulate C++ developers to use Intel IPP in their C++ applications. Interface Discussion Intel IPP library contains a large number of functions for signal and image processing. Almost every function has several data specific implementations. Using function overloads, which is typical for C++, simplifies development of applications that operate on data of different types. Hence, the first step to migrate to C++ is creating a C++ header file with function overloads based on the ipp<application-domain> C header file. To perform this operation, a special Perl script was developed. For example, consider the function ippscopy for signal processing. This function has several implementations for different data types. A corresponding C header file contains the following: ipps.h IPPAPI(IppStatus, ippscopy_8u,(const Ipp8u* psrc, Ipp8u* pdst, int len)) IPPAPI(IppStatus, ippscopy_16s,(const Ipp16s* psrc, Ipp16s* pdst, int len)) IPPAPI(IppStatus, ippscopy_64fc,(const Ipp64fc* psrc, Ipp64fc* pdst, int len)) Running the script produces: ipps.hpp inline IppStatus ippscopy( const Ipp8u* psrc, Ipp8u* pdst, int len) { return ippscopy_8u( psrc, pdst, len ); } inline IppStatus ippscopy( const Ipp16s* psrc, Ipp16s* pdst, int len) { return ippscopy_16s( psrc, pdst, len ); } inline IppStatus ippscopy( const Ipp64fc* psrc, Ipp64fc* pdst, int len) { return ippscopy_64fc( psrc, pdst, len ); } 4

5 Note that the inline declaration of the function reduces the cost of the function call from the C++ application to the minimum. C++ header files for each application domain contain the corresponding namespaces IPPSP (signal processing), IPPIP (image processing), and IPPCH (string manipulation) as well as the directive #include for the corresponding C header file. For example, the file ipps.hpp contains the directive #include ipps.h to ensure access to the external data structures of the domain as well as to the functions that cannot be overloaded. In the C++ header file these structures and functions are present in comments. The classes that are specific for IIR filters are developed and presented in the file ippsiir.hpp. The Intel IPP library supports two basic types of the IIR filters, that is, arbitrary order filters and biquad sections filters. Consequently, two template classes, CIirAR and CIirBO, are developed. These template classes are based on the same specially developed base template class CIir and differ in initialization methods only. The distinctive feature of IIR filters implemented in Intel IPP is the use of filter context state that sets filter parameters during initialization. The inner structure of this context is hidden from the user except for the structure name. Auxiliary template class CArgTypes provides correspondence between context and variables that are used in the class. This sample application shows the use of the CIirAR and CIirBQ classes. The application performs six simple tests that cover different filtering methods. CIir Template Class Library Reference CArgTypes CIir CIirAR CIirBQ Auxiliary template class that provides the correspondence between context and types of variables that are used in the class. Base IIR filter template class. Arbitrary order IIR filter template class. Biquad sections IIR filter template class. CArgTypes Template Class Definition template <class TState> class CArgTypes; Base CArgsTypes template class definition. Specializations template <> class CArgTypes<IppsIIRState_32f> {\ public: typedef Ipp32f TTaps; typedef Ipp32f TData; } template <> class CArgTypes<IppsIIRState_64f> {\ public: typedef Ipp64f TTaps; typedef Ipp64f TData; } 5

6 template <> class CArgTypes<IppsIIRState64f_32f> {\ public: typedef Ipp64f TTaps; typedef Ipp32f TData; } This sample uses only three context states of IIP filters. Each context specialization is given in the previous section. The Intel IPP signal processing library contains more than a dozen context states for different types of filters. To simplify the specialization for each context type, there are two macros IIRSTATE_1P and IIRSTATE_2P in the file ippsiir.hpp. For example, IIRSTATE_1P(32f); IIRSTATE_2P(64f,32f); Base CIir Class Members Creates specialization class CArgTypes for the context IppsIIRState_32f. Creates specialization class CArgTypes for the context IppsIIRState64а_32f. Construction CIir Operations SetDly GetDly Filter GetLastStatus Free Creates a CIir object. Sets filter delay line. Gets filter delay line. Performs filtering of input signal. Gets the status of the most recent operation. Releases resources. CIir::CIir CIir( ); No parameters. This constructor creates a base CIir object. CIir::SetDly IppStatus SetDly( TTaps *pdly ); PDly Pointer to the delay line to be set on filter state. This function sets new values of the filter delay line. 6

7 CIir::GetDly IppStatus GetDly( TTaps *pdly ); PDly Pointer to the delay line to be set on filter state. : The function copies the delay line values from the filter state structure and stores them into the array pdly. CIir::Filter IppStatus Filter (TData* psrc, TData* pdst, int numiters); IppStatus Filter (TData* psrcdst, int numiters); IppStatus Filter (TData* psrc, TData* pdst, int numiters, int ScaleFactor); IppStatus Filter (TData* psrcdst, int numiters, int scalefactor); IppStatus Filter (TData src, TData* pdstval); IppStatus Filter (TData src, TData* pdstval, int scalefactor); psrc pdst psrcdst Src pdstval numiters scalefactor Pointer to the source vector. Pointer to the destination vector. Pointer to source/destination vector for in-place operations. Input scalar sample to be filtered. Pointer to the output sample. Number of samples to be filtered by the function. Scale factor value for the integer filters. This overloaded function filters samples of the input vector and stores the results in the destination vector. The function provides vector, scalar, and in-place processing. CIir:: GetLastStatus IppStatus GetLastStatus(); No parameters. This function returns the status value of the last executed class member function. CIir::Free IppStatus Free( ); No parameters. 7

8 This function releases allocated resources. CIirAR Class Members Construction CiirAR Creates a CIirAR object. Operations Init Initializes arbitrary order IIR filter. Reinit Resets arbitrary order IIR filter. CIirAR::CIirAR CIirAR(int order, const TTaps* ptaps, const TTaps* dlyline ); Order ptaps dlyline Order of the IIR filter. Pointer to the array containing the taps. The number of elements in the array is 2 *(order +1). Pointer to the array containing the delay line values. The number of elements in the array is order. This constructor creates a base CIirAR object. CIirBQ Class Members Construction CiirBQ Operations Init Reinit Creates a CIirBQ object. Initializes biquad IIR filter. Resets biquad IIR filter. CIirBQ::CIirBQ CIirBQ(int numquads, const TTaps* ptaps, const TTaps* dlyline ); numquads ptaps DlyLine Number of biquads sections. Pointer to the array containing the taps. The number of elements in the array is 2 * (numquads). Pointer to the array containing the delay line values. The number of elements in the array is numquads. 8

9 This constructor creates a base CIirBQ object. Exception Handling Error handling mechanism in the sample is very simple and implemented in the constructors of classes CIirAR and CIirBQ. An exception arises when the initialization of the filter context fails. All function methods of the classes return status codes of the operation completion, which provides for several possible ways to implement error handling. Demo Application To compute the coefficients for arbitrary order and biquad filters and to verify the operability of the developed tests, a special filter has been created using the MATLAB*. This filter is a lowpass elliptic filter of 6 th order for data sampled at Hz, with a cutoff frequency of 1100 Hz, 0.5 db of ripple in the passband, and 20 db of attenuation in the stopband. The sample source file contains commented code snippets written as MATLAB scripts. Functionally, these code snippets are analogous to the operations that are performed by the demo application. To work with the C++ Intel IPP library, the file IppsCpp.cpp contains the directives #include "ippsiir.hpp" and uses the namespace IPPSP. Before running sample tests, the following procedures should be performed: memory allocation required for input, output, and temporary vectors preparation of the input signal (single impulse in our case) creation of three variables of the class CIiAR for the contexts IppsIIRState_32f, IppsIIRState_64f, IppsIIRState64f_32f filtering the 64f-data with the 64f-taps filter. The output signal obtained in the last operation is absolutely the same as its MATLAB prototype and is shown in Fig.1. In sample tests it is used as a reference signal. Each test applies a certain IIR filter implementation to the input signal and compares the result with the reference signal using the Intel IPP function ippsnormdiff_l2. If the computed value of the norm is less than or equal to 10-5, the vectors are identical. 9

10 Figure 1. Reference Output Signal double IIR ( CIirAR<IppsIIRState_64f>) double IIR Test 1: 32f-data 64f-taps IIR filter Accuracy Evaluation Test result: output signal is identical to the reference. The following functions are used in the test: Iir64f_32f.Filter ippsconvert ippsnormdiff_l2 Test 2: 32f-data 32f-taps IIR Filter Accuracy Evaluation Test result: output signal differs from the reference. The results of the test are summarized in a table, a fragment of which is shown on Fig.2. The first column contains the sample number. The second is the impulse response for the reference filter that uses double-precision floating point data for both coefficients values and input signal. The third is the impulse response for the filter that uses single-precision floating point coefficients and double-precision floating point input data. 10

11 Figure 2. Fragment of Result Table for Test Sample double IIR float IIR 0, 0, 0, 1, 0, 0, 2, 0, 0, 3, 0, 0, 4, 0, 0, 5, 0, 0, 6, 0, 0, 7, 0, 0, 8, 0, 0, 9, 0, 0, 10, , , 11, , , 12, , , 13, , , 14, , , 15, , , 16, , , 17, , , 18, , 3.812, 19, , , 20, , , 50, , , 51, , , 52, , , 53, , , 54, , , 55, , , 56, , , 57, , , 58, , , As it may be seen, such filter is critical to the precision of the filter coefficients representation. When the taps values are rounded during conversion from double to float, the filter loses its stability (see Figs.2, 3). The following functions are used in the test: Iir32f.Filter 11

12 Figure 2. Output Signal in Test 2 Double taps IIR vs Float taps IIR double IIR float IIR Test 3: Point-wise IIR Filter Accuracy Evaluation The state of the filter Iir64 is returned to the initial state using the method Reinit to zero a delay line of the filter. Then point-wise filtering is performed in the loop and the result output signal is compared with the reference. Test result: output signal is identical to the reference. The following functions are used in the test: Iir64f.Reinit Iir64f.Filter ippsnormdiff_l2 Test 4: Delay Line Compatibility for Switching from Point-wise to Vector Filtering The state of the filter Iir64 is returned to the initial state by zeroing explicitly a delay line of the filter using the overload function ippszero. Then one half of the output buffer is filled with the results of point-wise filtering, and the other half with the results of vector filtering. Thus, vector filtering inherits the delay line state after point-wise filtering. An output signal is compared with the reference. Test result: output signal is identical to the reference. 12

13 The following functions are used in the test: IppsZero Iir64f.SetDly Iir64f.Filter ippsnormdiff_l2 Test 5: In-Place IIR Filter Accuracy Evaluation The state of the filter Iir64 is returned to the initial state using the method Reinit. The single impulse is written in the input/output buffer, then in-place filtering is performed and the result signal is compared with the reference. Test result: output signal is identical to the reference. The following functions are used in the test: IppsZero Iir64f.Reinit Iir64f.Filter ippsnormdiff_l2 Test 6: Biquad IIR Filter Accuracy Evaluation Using MATLAB, the coefficients for the biquad implementation of the desired 6 th -order lowpass elliptic filter are computed. The biquad filter IirBq64f is initialized and filtering is performed. The result signal is compared with the reference. Test result: output signal is identical to the reference. The following functions are used in the test: IirBq64f - construction IirBq64f.Filter ippsnormdiff_l2 When the tests are completed, the allocated resources should be freed. Application Output Test 2 presents results in a table form (see Test 2 description). All other tests return the following message if the computed norm of difference between result and reference vectors exceeds the specified value: "TEST<number>: Outputs are different, Norm_L2 = %10.4g \n" Program output can be easily redirected to cvs-format file via command line, for example:..\ippcpp\bin > IppsCpp.exe > ippscpp.csv 13

14 Summary This sample demonstrates how to create and use the C++ classes CIirAR and CIirBQ based on the Intel IPP functions. The sample performs six simple tests that cover different filtering methods. The objectives of the sample are: to show users an easy way to provide access to the functionality of the Intel IPP libraries using the C++ technique based on the functions overloading and template classes to provide users with the basis for developing their own applications based on the Intel IPP to test partially the operability of the created C++ overloading functions, templates, and classes to evaluate the accuracy of the Intel IPP implementation of the IIR filter for input sample and filter coefficients of data of different types to show how the precision of the filter coefficients influences on the accuracy of filtering. References [1] Intel Integrated Performance Primitives 14