
/*! ****************************************************************************
\ingroup PLOT_GROUP
\fn int gnuplot_create(int argc, char* argv[], int w, int h, char* fn_png, 
                       void** hplot) 

\brief 
Создать график GNUPLOT. 

Данная функция открывает пакет GNUPLOT в зависимости от передаваемых в программу
параметров `argv`. После вызова данной функции по адресу `hplot` будет записан
handle графика и появляется возможность посылать GNUPLOT команды для отображения
графиков. 

\note С точки зрения системы, `hplot` является указателем на открытый файл, 
 в который можно записывать команды для исполнения пакетом GNUPLOT.
 
 

\param[in]  argc
Количество аргументов вызова программы. \n
(количество переменных `argv`). \n 
Данное значение не должно быть меньше единицы, потому что `argv[0]` 
хранит имя исполняемого файла программы. \n 
\n

\param[in]  argv
Указатель на массив строк параметров исполняемого файла. \n
Размер массива `argc` строк. \n
`argv[0]` хранит имя исполняемого файла программы. \n
`argv[1]` задает формат отображения графика: \n
\verbatim

--plotwin   отображать график в отдельном окне
            (данный параметр используется по умолчанию);

--plotpng   сохранить график в png-файл, заданный именем fn_png; 

--noplot    график не создавать, игнорировать все команды GNUPLOT.
\endverbatim
\n

\param[in]  w
Ширина окна графика или png-файла в пикселях. \n 
\n

\param[in]  h
Высота окна графика или png-файла в пикселях. \n 
\n

\param[in]  fn_png
Имя png-файла, в который будет сохранен график. \n 
Путь сохранения графика совпадает с путем исполняемого файла программы. \n 

\param[in, out] hplot
Указатель на адрес хэндла пакета GNUPLOT. \n 
По данному адресу будет записан указатель на текщий график. Данный указатель 
необходим для посылки команд GNUPLOT для построения графика. \n 
\n

\return
`RES_OK` --- функция выполнена успешно. \n
В противном случае \ref ERROR_CODE_GROUP "код ошибки". \n
При возникновении ошибки по адресу  `hplot` будет записан `NULL`. \n
\note
Если в `argv[1]` задан параметр `--noplot`, то функция вернет `RES_OK`,
но по адресу  `hplot` также  будет записан `NULL`. \n

После построения графиков необходимо закрыть хэндл GNUPLOT функцией 
\ref gnuplot_close. \n

Пример построения графиков синуса и косинуса привден в следующем листинге:

\include gnuplot_script_test.c

Данная программа рассчитвает значения функций синуса и косинуса, 
а также сохрянет текстовые файлы `dat/cosine.txt` и `dat/sine.txt`. \n

Сохраненные данные отображаются на трех графиках (с данными синуса, косинуса
и обоими данными):

\image html gnuplot_script_sin.png

\image html gnuplot_script_cos.png

\image html gnuplot_script_sincos.png


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





/*! ****************************************************************************
\ingroup PLOT_GROUP
\fn void gnuplot_close(void* h) 

\brief
Закрыть хэндл GNUPLOT. 

Данная функция закрывает открытый ранее хэндл GNUPLOT после передачи всех 
команд построения графиков.

\note 
С точки зрения системы, `h` является указателем на открытый файл, в который 
можно записывать команды для исполнения пакетом GNUPLOT. 
Данная функция закрывает этот файл. \n
Важно отметить, что закрытие хэндла не означает закрытия окна графика. 
После закрытия хэндла пакета, пользователь не может посылать команды построения
графика, но окно графика остается открытым, так как обрабатывается пакетом 
GNUPLOT независимо.
 

\param[in]  h
Хэндл графика GNUPLOT, который будет закрыт. \n 
\n


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









/*! ****************************************************************************
\ingroup PLOT_GROUP
\fn void gnuplot_cmd(void* h, char* cmd)

\brief
Функция посылает команду `cmd` пакету GNUPLOT, для построения 
или оформления графика, соответсвующего хэндлу `h`. 

Данная функция закрывает открытый ранее хэндл GNUPLOT после передачи всех 
команд построения графиков.

\note С точки зрения системы, `h` является указателем на открытый файл, 
в который можно записывать команды для исполнения пакетом GNUPLOT. Данная 
функция записывает в данный файл строку  `cmd`. \n 
\n
С точки зрения пользователя, вызов функции `gnuplot_cmd` равносильно выполнению
одной строки скрипта GNUPLOT. \n 
\n
Исчерпывающее описание возможностей построения графиков пакетом GNUPLOT, 
с примерами команд можно найти на 
 <a href = "http://gnuplot.sourceforge.net/demo_5.2/">сайте проекта GNUPLOT</a>. 

\param[in]  h
Хэндл графика GNUPLOT. \n 
\n


\param[in]  cmd
Тектовая строка команды построения или оформления графика. \n 
\n


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