/*! ****************************************************************************
\ingroup FIR_FILTER_DESIGN_GROUP
\fn int DSPL_API  fir_linphase(int ord, double w0, double w1, int filter_type, 
int win_type, double win_param, double* h)
\brief
Function calculates linear-phase FIR filter coefficients by window method

FIR filter transfer function is
\f[
H(z) = \sum_{n = 0}^{ord} h_n z^{-n}.
\f]

\param[in]  ord
Filter order. \n
Number of FIR filter coefficients is `ord+1`. \n 
\n

\param[in]  w0
Normalized cutoff frequency for lowpass and highpass filter,
or left cutoff frequency for bandpass or bandstop filter. \n 
\n

\param[in]  w1
Right normalized cutoff frequency for bandpass or bandstop filter. \n
This parameter is ignored for lowpass or highpass filters. \n 
Frequecny `w1` must be higher than `w0`. \n 
\n

\param[in]  filter_type
Filter type. \n
This parameter can be one of follow: \n
\verbatim
DSPL_FILTER_LPF   - lowpass  filter;
DSPL_FILTER_HPF   - highpass filter;
DSPL_FILTER_BPASS - bandpass filter;
DSPL_FILTER_BSTOP - bandstop filter.
\endverbatim
\n 
\n

\param [in]  win_type
Window function type. \n
This parameter can be one of follow: \n
\verbatim
-------------------------------------------------------------------------
 win_type                    |  Description
-----------------------------|-------------------------------------------
 DSPL_WIN_BARTLETT           | Nonparametric Bartlett window
-----------------------------|-------------------------------------------
 DSPL_WIN_BARTLETT_HANN      | Nonparametric Bartlett-Hann window
-----------------------------|-------------------------------------------
 DSPL_WIN_BLACKMAN           | Nonparametric  Blackman window 
-----------------------------|-------------------------------------------
 DSPL_WIN_BLACKMAN_HARRIS    | Nonparametric Blackman-Harris window
-----------------------------|-------------------------------------------
 DSPL_WIN_BLACKMAN_NUTTALL   | Nonparametric Blackman-Nuttall
-----------------------------|-------------------------------------------
 DSPL_WIN_CHEBY              | Parametric Dolph-Chebyshev window.
                             | Parametr  `win_param` sets sidelobe attenuation 
                             | level in dB.
-----------------------------|-------------------------------------------
 DSPL_WIN_COS                | Nonparametric Cosine window
-----------------------------|-------------------------------------------
 DSPL_WIN_FLAT_TOP           | Nonparametric maxflat window
-----------------------------|-------------------------------------------
 DSPL_WIN_GAUSSIAN           | Nonparametric Gauss window
-----------------------------|-------------------------------------------
 DSPL_WIN_HAMMING            | Nonparametric Hamming window
-----------------------------|-------------------------------------------
 DSPL_WIN_HANN               | Nonparametric Hann window
-----------------------------|-------------------------------------------
 DSPL_WIN_KAISER             | Parametric Kaiser window
-----------------------------|-------------------------------------------
 DSPL_WIN_LANCZOS            | Nonparametric Lanczos window
-----------------------------|-------------------------------------------
 DSPL_WIN_NUTTALL            | Nonparametric Nuttall window
-----------------------------|-------------------------------------------
 DSPL_WIN_RECT               | Nonparametric rectangular window
-------------------------------------------------------------------------
\endverbatim
\n 
\n

\param [in]  win_param
Parameter value for parametric windows. \n
This parameter is used for parametric windows only and is ignored for
nonparametric windows. \n 
\n

\param[out]  h
Pointer to the linear-phase FIR filter coefficients vector. \n
Vector size is `[ord+1 x 1]`. \n
Memoru must be allocated. \n 
\n

\note
Only symmetric windows can achieve linear-phase FIR filter. \n \n
Bandstop filter type (`filter_type = DSPL_FILTER_BSTOP`) requires 
only even filter order `ord`. 
If `filter_type = DSPL_FILTER_BSTOP` and  `ord` is odd then function 
returns `ERROR_FILTER_ORD` code.
\n

\return
`RES_OK` if filter coefficients is calculated successfully. \n 
Else \ref ERROR_CODE_GROUP "code error".


Example:

\include fir_linphase_test.c

This function calculates coeffictiens of lowpass, highpass, bandpass 
 and bandstop linear-phase FIR filters by using different kind of windows.
 Also program calculates filter magnitudes and plots. \n 

\image html fir_linphase_test.png


\author Sergey Bakhurin www.dsplib.org 
***************************************************************************** */