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


#if @HELP_GBLACKMAN

    GBLACKMAN

    Purpose: Generates a three term Blackman Window.

    Syntax:  GBLACKMAN(N, spacing, "sym")

                     N - Number of points to generate.

               spacing - Spacing between points.

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

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

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

                          "iso"       : Same as "periodic".

    Returns: A series.

    Example:
             gblackman(100, .01)

             Creates a symmetric 100-point Blackman window with points
             spaced with an interval of 0.01 using the following formula:

             w[k] = 0.42 - 0.50 * cos(2*pi*(k-1)/(N-1))
                         + 0.08 * cos(4*pi*(k-1)/(N-1))

    Example:
             gblackman(100, .01, "periodic")

             Creates a periodic 100-point Blackman window with points
             spaced with an interval of 0.01 using the following formula:

             w[k] = 0.42 - 0.50 * cos(2*pi*(k-1)/N)
                         + 0.08 * cos(4*pi*(k-1)/N)

    Remarks:
             The periodic Blackman window is constructed by the following
             window generation formula:

             w[k]  = a0 - a1 * cos(2*pi*(k-1)/N)
                        + a2 * cos(4*pi*(k-1)/N)

             where:

             a0 = 0.42
             a1 = 0.50
             a2 = 0.08

             The symmetric form can be constructed by setting N to N-1.

             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" (the default) creates a periodic
             window function useful in spectrum analysis applications
             where the starting zero is preserved and the trailing zero
             is removed.  "Periodic" or "iso" conforms to the ISO
             18431-1 standard for windowing functions.

             Use the BLACKMAN function to automatically create and multiply
             a Blackman window with a series. For example:

               blackman(W2)

             multiplies Window 2 with a Blackman window calculated to the same
             length and spacing as the series in W2.

             Blackman, Hamming, Hanning, Kaiser and Flattop windows are
             useful in creating FIR filters and in preprocessing series
             for FFT calculations.

    See Also:
             Blackman
             Fft
             Gflattop
             Ghamming
             Ghanning
             Gkaiser
             Psd
             Spectrum
#endif


/* generate an N point, three term Blackman window */
gblackman(n, dx, sym)
{
        local a, w;

        (n, dx, sym) = gblackman_parse_args(n, dx, sym);

        /* special cases */
        if (n == 0) return({});
        if (n == 1) return(ones(1, 1, dx));

        /* blackman coefficients */                
        a = {0.42, 0.5, 0.08};

        /* generate window */
        w = gcoswin(a, n, dx, sym);

        return(w);
}


gblackman_parse_args(n, dx, sym)
{
        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("gblackman - number of points required");
                        
                        dx = 1.0;
                }
                
                sym = "symmetric";
        }
        
        if (isstring(dx))
        {
                temp = dx;
                dx   = (isstring(sym)) ? 1.0 : sym;
                sym  = temp;
        }

        return(n, dx, sym);
}