/*****************************************************************************
*                                                                            *
*   GBLACKMANHARRIS.SPL Copyright (C) 2012 DSP Development Corporation       *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Generates a Blackman-Harris window                          *
*                                                                            *
*   Revisions:    8 May 2012  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_GBLACKMANHARRIS

    GBLACKMANHARRIS

    Purpose: Generates a four term Blackman-Harris Window.

    Syntax:  GBLACKMANHARRIS(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:
             gblackmanharris(100, .01)

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

                 w[k] = 0.35875 - 0.48829 * cos(2 * pi * (k-1) / (N-1)) 
                                + 0.14128 * cos(4 * pi * (k-1) / (N-1)) 
                                - 0.01168 * cos(6 * pi * (k-1) / (N-1))

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

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

                 w[k] = 0.35875 - 0.48829 * cos(2 * pi * (k-1) / N) 
                                + 0.14128 * cos(4 * pi * (k-1) / N) 
                                - 0.01168 * cos(6 * pi * (k-1) / N)

    Remarks:
             The periodic Blackman-Harris 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)
                        - a3 * cos(6*pi*(k-1)/N)

             where:

             a0 = 0.35875
             a1 = 0.48829
             a2 = 0.14128
             a3 = 0.01168

             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 BLACKMANHARRIS function to automatically create
             and multiply a Blackman-Harris window with a series.  For
             example:

               blackmanharris(W2)

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

             Blackman, Blackman-Harris, 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, four term Blackman-Harris window */
gblackmanharris(n, dx, sym)
{
        local m, i, k, w;

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

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

        /* blackman coefficients */                
        a = {0.35875, 0.48829, 0.14128, 0.01168};

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

        return(w);
}


gblackmanharris_parse_args(n, dx, sym)
{
        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("gblackmanharris - 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);
}