libdspl-2.0/dspl/dox/ru/fft.dox

/*! *************************************************************************************************
    \ingroup DFT_GROUP
    \struct fft_t
    \brief Структура данных объекта быстрого преобразования Фурье
    
    Структура хранит указатели на массивы поворотных коэффициентов и массивов промежуточных данных
    алгоритма быстрого преобразования Фурье с прореживанием по времени.

    \param      n       Размер вектора БПФ, для которого выделена память в массивах структуры. <BR>
                        Парметр `n` должен быть равен целой степени двойки. <BR><BR>

    \param      p2      Целая степень двойки, образующая размер БПФ.<BR><BR>
                        Так \f$2^{p2} = n\f$.

    \param      w       Указатель на вектор поворотных коэффициентов алгоритма БПФ.<BR>
                        Размер вектора `[n x 1]`. <BR>
                        Память должна быть выделена и массив поворотных коэффициентов должен
                        быть заполнен функцией \ref fft_create. <BR><BR>
                        
                        
    \param      t0      Указатель на вектор промежуточных вычислений алгоритма БПФ.<BR>
                        Размер вектора `[n x 1]`. <BR>
                        Память должна быть выделена функцией \ref fft_create. <BR><BR>


    \param      t1      Указатель на вектор промежуточных вычислений алгоритма БПФ.<BR>
                        Размер вектора `[n x 1]`. <BR>
                        Память должна быть выделена функцией \ref fft_create. <BR><BR>

            
    Структура заполняется функцией \ref fft_create один раз до использования алгоритма БПФ. <BR>
    Указатель на объект данной структуры может быть многократно использован при вызвове функций БПФ.<BR>
    Перед выходом из программы выделенную память под поворотные коэффициенты и массивы промежуточных данных
    необходимо очистить функцией \ref fft_free. Например:
    
    \code
        fft_t pfft;     // объявляем объект fft_t
        int n = 64;     // Размер БПФ
        
        // обнуляем все поля и указатели. 
        // Данные шаг рекомендуется ввиду того, что некоторые
        // при создании переменной не инициализируют ее нулем.
        memset(&pfft, 0, sizeof(fft_t));
        
        int err;
        
        //создаем объект для 64-точечного БПФ
        err = fft_create(&pfft, n);
        
        // Вызов БПФ функции
        // Еще раз вызов БПФ функции
        // ....
        
        
        //очистить память объекта БПФ
        fft_free(&pfft);
    \endcode
                

    Важно отметить, что если объект `fft_t` был создан для размера БПФ равного `n`, 
    то он может быть использован для любого размера БПФ `k` меньшего размера. <BR>
    
    Например, если мы создали `fft_t` для БПФ размера `n = 64`, то мы можем использовать
    этот же объект для 32, 16, 8, 4 -точечных БПФ без необходимости пересчета поворотных коэффициентов.<BR>
    
    Также необходимо заметить, что функции БПФ самостоятельно контроллируют размер, 
    и самостоятельно выделяют память объекта БПФ при необходимости.
          
   
    \author
            Бахурин Сергей.                                                         
            www.dsplib.org 

**************************************************************************************************** */







/*! *************************************************************************************************
    \ingroup DFT_GROUP
    \fn int fft_create(fft_t *pfft, int n)
    \brief Заполнение структуры `fft_t` для алгоритма БПФ

    Функция производит выделение памяти и рассчет векторов поворотных коэффициентов 
    `n`-точечного БПФ для структуры `fft_t`.



    \param[in,out]	pfft	Указатель на структуру `fft_t`. <BR>
                            Указатель не должен быть `NULL`. <BR><BR>

    \param[in]	n	Размер БПФ \f$n\f$ (должен быть равен целой степени двойки).<BR>




    \return
    `RES_OK`            если структура заполнена успешно. <BR>
                        В противном случае \ref ERROR_CODE_GROUP "код ошибки".<BR><BR>

    \note
    Некоторые компиляторы при создании структуры не обнуляют ее содержимое. 
    Поэтому рекомендуется произвести обнуление структуры после ее объявления:
    \code
        fft_t pfft;     // объявляем объект fft_t
        int n = 64;     // Размер БПФ
        
        // обнуляем все поля и указатели. 
        // Данные шаг рекомендуется ввиду того, что некоторые 
        // компиляторы при создании переменной не инициализируют ее нулем.
        memset(&pfft, 0, sizeof(fft_t));
    
        int err;
        
        //создаем объект для 64-точечного БПФ
        err = fft_create(&pfft, n);

        // .....
                
        //очистить память объекта БПФ
        fft_free(&pfft);
    \endcode
    Перед выходом из программы выделенную в структуре память необходимо очистить функцией \ref fft_free .


    \author
            Бахурин Сергей.                                                         
            www.dsplib.org 


**************************************************************************************************** */









/*! *************************************************************************************************
    \ingroup DFT_GROUP
    \fn void fft_free(fft_t *pfft)
    \brief Очистить структуру `fft_t` алгоритма БПФ

    Функция производит очищение памяти промежуточных данных 
    и векторов поворотных коэффициентов структуры `fft_t`.



    \param[in]	pfft	Указатель на структуру `fft_t`. <BR>

    \author
            Бахурин Сергей.                                                         
            www.dsplib.org 


**************************************************************************************************** */








/*! *************************************************************************************************
    \ingroup DFT_GROUP
    \fn int fft_shift(double* x, int n, double* y)
    \brief Перестановка спектральных отсчетов дискретного преобразования Фурье

    Функция производит 
    <a href="http://ru.dsplib.org/content/dft_freq/dft_freq.html">
    перестановку спектральных отсчетов ДПФ
    </a> и переносит нулевую частоту в центр вектора ДПФ. <BR>
    Данная функция обрабатывает вещественные входные и выходные вектора и может применяться для перестановки 
    амплитудного или фазового спектра.




    \param[in]	x	Указатель на исходный вектор ДПФ. <BR>
                                    Размер вектора `[n x 1]`. <BR><BR>

    \param[in]	n	Размер ДПФ \f$n\f$ (размер векторов до и после перестановки).<BR><BR>

    \param[out]	y	Указатель на вектор результата перестановки.<BR>
                        Размер вектора `[n x 1]`. <BR>
                        Память должна быть выделена.<BR><BR>


    \return
    `RES_OK`            если перестановка произведена успешно. <BR>
                        В противном случае \ref ERROR_CODE_GROUP "код ошибки":<BR>

    \author
            Бахурин Сергей.                                                         
            www.dsplib.org 


**************************************************************************************************** */