/*****************************************************************************
*                                                                            *
*   BLACKMAN.SPL   Copyright (C) 2004,2010 DSP Development Corporation       *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Multiplies a series with a Blackman Window                 *
*                                                                            *
*   Revisions:    19 Mar 2004  RRR  Creation                                 *
*                 21 Jul 2010  RRR  symmetry flag                            *
*                                                                            *
*****************************************************************************/


#if @HELP_BLACKMAN

    BLACKMAN

    Purpose: Multiplies a series with a 3 Point Blackman window

    Syntax:  BLACKMAN(s, ampflag, "sym")

                    s - A series or array

              ampflag - Optional, an integer, the correction factor.

                        0: do not correct amplitude (default)
                        1: correct amplitude
                        2: correct RMS 
                        3: correct mean squared amplitude

                "sym" - Optional. A string, the symmetry mode.

                        "symmetric" : Starting and ending points are equal
                                      (default).

                        "periodic"  : Periodically extended window. Conforms 
                                      to ISO standard.
   Alternate Syntax:  
             
             BLACKMAN(N, ampflag, "sym")

                    N - An integer, the length of the window.

              ampflag - Optional, an integer, the correction factor.

                        0: do not correct amplitude (default)
                        1: correct amplitude
                        2: correct RMS 
                        3: correct mean squared amplitude

                "sym" - Optional. A string, the symmetry mode.

                        "symmetric" : Starting and ending points are equal
                                      (default).

                        "periodic"  : Periodically extended window. Conforms 
                                      to ISO standard.

    Returns: A series or array

    Example:
             W1: gsin(1000, .001, 45)
             W2: spectrum(blackman(W1))
             W3: spectrum(blackman(W1, 1))

             The MAX of W2 == 0.539 and the MAX of W3 == 1.0. The amplitude
             of the spectrum in W3 has been corrected to take into account
             amplitude effects of the Hamming window.

   Example:
             blackman(1000, "periodic")

             returns a 1000 point periodic blackman window.

    Remarks:
             If the input is an integer rather than a series, the N
             point blackman window is returned.

             If ampflag == 1, the correction factor is the mean of
             the spectral window. This assures that the spectrum of a
             sinusoid of amplitude 1.0 has a peak of 1.0.

             If ampflag == 2, the correction is applied as follows:

             w = blackman(s) * rms(s) / rms(blackman(s))

             sqrt(area(psd(w))) == rms(s)    approximately

             If ampflag == 3, the correction is applied as follows:

             w = blackman(s) / sqrt(win * win / length(win))

             where win is the windowing function.

             The "sym" flag controls the window symmetry as follows: 

             "Symmetric" sets the first and last points to be equal. 
             An N point symmetric window can be constructed by creating
             an N-1 point periodic window and setting the Nth point to
             the value of the first point.

             "Periodic" or "iso" creates a periodic window function
             useful in spectrum analysis applications. "Periodic" or
             "iso" conforms to the ISO 18431-1 standard for windowing
             functions.

             See GBLACKMAN for more details on the Blackman window.

    See Also:
             Flattop
             Gblackman
             Hamming
             Hanning
             Kaiser
             Winfunc
#endif


/* multiply a series with a blackman window */
SERIES blackman(s, ampflag, sym)
{
        return(winfunc(5, s, ampflag, sym));
}