<html>
<head>
<meta charset="UTF-8" />
<link rel="stylesheet" type="text/css" href="style.css" />
<title>Запуск и общие функции - Helianthus</title>
</head>
<body>
<div class="navigation">
<p><a href="https://coolbug.org/users/bw/helianthus/ru.html">Helianthus</a></p>
<hr />
<p><a href="index.html">Helianthus: Документация</a></p>
<p><a href="install.html">Установка</a></p>
<p><a href="common.html">Запуск и общие функции</a></p>
<p><a href="input.html">Клавиатура и мышь</a></p>
<p><a href="drawing.html">Рисование</a></p>
<p><a href="font.html">Шрифты и текст</a></p>
<p><a href="animation.html">Текстуры и анимация</a></p>
<p><a href="framebuffer.html">Буфер кадра</a></p>
<p><a href="sprites.html">Спрайты</a></p>
<p><a href="groups.html">Группы спрайтов</a></p>
<p><a href="sound.html">Звук</a></p>
<hr />
<p><a href="functions.html">Все функции</a></p>
</div>
<div class="content">
<h1>Запуск и общие функции</h1>
<p>Для подключения и использования библиотеки Helianthus нужно:<br />
- подключить файл <i><helianthus.h></i><br />
- создать и зарегистрировать функции для начальной загрузки и для перерисовки кадра (см. <a href="common.html#worldSetInit">worldSetInit</a> и <a href="common.html#worldSetDraw">worldSetDraw</a>)<br />
- также вы можете зарегистрировать функцию для выполнения каких-либо действий при завершении программы (<a href="common.html#worldSetDeinit">worldSetDeinit</a>);<br />
- вызвать функцию <a href="common.html#worldRun">worldRun</a> для запуска вашей программы</p>
<p>Вот что должно получиться:</p>
<pre>
#include <helianthus.h>
void init() {
// Здесь будут команды для начальной загрузки.
// Они выполнятся только один раз в самом начале.
}
void draw() {
// Здесь будут команды для движения и рисования.
// Во время работы программы они будут запускаться
// несколько раз в секунду.
}
int main() {
worldSetInit(&init);
worldSetDraw(&draw);
worldRun();
return 0;
}
</pre>
<p>После завершения работы Helianthus (при окончании выполнения функции <a href="common.html#worldRun">worldRun</a>) все созданные вами объекты библиотеки будут удалены автоматически. Если вы хотите удалить что-то вручную, смотрите функции удаления для соответствующих объектов (<a href="sprites.html#spriteDestroy">spriteDestroy</a>, <a href="groups.html#groupDestroy">groupDestroy</a>, <a href="sound.html#soundDestroy">soundDestroy</a>, <a href="font.html#fontDestroy">fontDestroy</a>, <a href="font.html#textLayoutDestroy">textLayoutDestroy</a>, <a href="animation.html#animationDestroy">animationDestroy</a>, <a href="framebuffer.html#framebufferDestroy">framebufferDestroy</a>, <a href="common.html#closeDirectory">closeDirectory</a>).</p>
<p>Вы можете задать размер окна программы функциями <a href="common.html#worldSetSize">worldSetSize</a>, <a href="common.html#worldSetWidth">worldSetWidth</a>, <a href="common.html#worldSetHeight">worldSetHeight</a> и задать заголовок окна функцией <a href="common.html#worldSetTitle">worldSetTitle</a>. В отличие от большинства функций Helianthus эти функции можно вызывать до запуска <a href="common.html#worldRun">worldRun</a>.</p>
<p>Изначально окно имеет фиксированный размер, который вы можете менять только из программы, командами указанными выше. Однако вы можете это изменить и разрешить пользователю изменять размер окна, смотрите функцию <a href="common.html#worldSetResizable">worldSetResizable</a>.</p>
<p>Окно программы непрерывно перерисовывается с частотой 24 кадра в секунду. Частоту перерисовки вы можете поменять при помощи функции <a href="common.html#worldSetFrameRate">worldSetFrameRate</a>.</p>
<p>Программа ведёт отсчёт времени и кадров с момента запуска вы можете получить значение этих счётчиков пи помощи функций <a href="common.html#worldGetSeconds">worldGetSeconds</a> и <a href="common.html#worldGetFrameCount">worldGetFrameCount</a>. Длительность одного кадра (длительность предыдущего отрисованного кадра) можно узнать вызвав функцию <i>world</i><i>Frame</i><i>Time</i>.</p>
<p>Также Helianthus предоставляет некоторые общие функции которые не представлены в стандартном я зыке C:<br />
- помощники в генерации случайных чисел (<a href="common.html#randomNumber">randomNumber</a>, <a href="common.html#randomFloat">randomFloat</a>);<br />
- функция поворота вектора <a href="common.html#rotateVector">rotateVector</a>;<br />
- функции для чтения папок (см. <a href="common.html#openDirectory">openDirectory</a>);<br />
- функции проверки существования файлов и папок — <a href="common.html#fileExists">fileExists</a>, <a href="common.html#directoryExists">directoryExists</a>.<br />
- функции для создания всплывающих окон с текстовыми сообщениями (<a href="common.html#messageBox">messageBox</a>, <a href="common.html#questionBox">questionBox</a>, <a href="common.html#questionBox3">questionBox3</a>) и окон для ввода текста (<a href="common.html#askText">askText</a>, <a href="common.html#askTextEx">askTextEx</a>).</p>
<h2>Функции:</h2>
<h3 id="worldSetInit">void worldSetInit(Callback init);</h3>
<p>Задать функцию для начальной инициализации (загрузки). Эта функция будет запущена только один раз в самом начале работы программы, как только будет вызвана функция <a href="common.html#worldRun">worldRun</a>.</p>
<h4>Параметры:</h4>
<p><i>init</i> — указатель на функцию начальной инициализации (загрузки). Функция быть работать без параметров и не должна возвращать значение.</p>
<h3 id="worldSetDraw">void worldSetDraw(Callback draw);</h3>
<p>Задать основную функцию вашей программы — функцию для перерисовки кадра. Во время работы программы заданная функция будет запускаться несколько раз в секунду перед перерисовкой каждого кадра. Поместите в неё команды для движения и рисования.</p>
<h4>Параметры:</h4>
<p><i>draw</i> — указатель на функцию перерисовки кадра. Функция быть работать без параметров и не должна возвращать значение.</p>
<h3 id="worldSetDeinit">void worldSetDeinit(Callback deinit);</h3>
<p>Задать функцию для выполнения каких-либо действий при завершении программы. Эта функция будет запущена только один раз при окончании работы программы, непосредственно перед завершением выполнения функции <a href="common.html#worldRun">worldRun</a>.</p>
<h4>Параметры:</h4>
<p><i>deinit</i> — указатель на функцию которая будет выполнена перед завершением программы.</p>
<h3 id="worldRun">void worldRun();</h3>
<p>Запустить вашу программу на Helianthus. Перед вызовом этой функции нужно зарегистрировать функции начальной загрузки и перерисовки кадра (см. выше)</p>
<h3 id="worldStop">void worldStop();</h3>
<p>Остановить и закрыть программу. Программа всегда закрывается если пользователь нажмёт на крестик в верхнем правом углу окна, но вы можете добавить и свои способы выхода из программы. Например, в функцию перерисовки вы можете вставить возможность выхода по нажатию клавиши Esc (см. также раздел <a href="input.html" />«Клавиатура и мышь»</a>):</p>
<pre>
void draw() {
…
if (keyWentDown("escape")) {
worldStop()
}
…
}
</pre>
<h3 id="worldGetWidth">int worldGetWidth();</h3>
<p>Возвращает ширину окна в пикселях. См. также <a href="common.html#worldSetWidth">worldSetWidth</a>.</p>
<h3 id="worldSetWidth">void worldSetWidth(int width);</h3>
<p>Установить ширину окна. Эту функцию можно вызывать до вызова <a href="common.html#worldRun">worldRun</a>. См. также <a href="common.html#worldGetWidth">worldGetWidth</a>, <a href="common.html#worldSetHeight">worldSetHeight</a>, <a href="common.html#worldSetSize">worldSetSize</a>.</p>
<h4>Параметры:</h4>
<p><i>width</i> — новая ширина окна.</p>
<h3 id="worldGetHeight">int worldGetHeight();</h3>
<p>Возвращает высоту окна в пикселях. См. также <a href="common.html#worldSetHeight">worldSetHeight</a>.</p>
<h3 id="worldSetHeight">void worldSetHeight(int height);</h3>
<p>Установить высоту окна. Эту функцию можно вызывать до вызова <a href="common.html#worldRun">worldRun</a>. См. также <a href="common.html#worldGetHeight">worldGetHeight</a>, <a href="common.html#worldSetWidth">worldSetWidth</a>, <a href="common.html#worldSetSize">worldSetSize</a>.</p>
<h4>Параметры:</h4>
<p><i>height</i> — новая высота окна.</p>
<h3 id="worldSetSize">void worldSetSize(int width, int height);</h3>
<p>Установить сразу и ширину и высоту окна. Эту функцию можно вызывать до вызова <a href="common.html#worldRun">worldRun</a>. См. также <a href="common.html#worldSetWidth">worldSetWidth</a>, <a href="common.html#worldSetHeight">worldSetHeight</a>.</p>
<h4>Параметры:</h4>
<p><i>width</i> — новая ширина окна;<br />
<i>height</i> — новая высота окна.</p>
<h3 id="worldGetResizable">int worldGetResizable();</h3>
<p>Возвращает <i>TRUE</i> если пользователь имеет возможность изменять размер окна, в противном случае возвращает <i>FALSE</i>.</p>
<h3 id="worldSetResizable">void worldSetResizable(int resizable);</h3>
<p>Включает или выключает возможность измерения размеров окна пользователем. Когда включено пользователь может менять размер окна растягивая его, хватаясь за границы, и, появляется кнопка для разворачивания окна на весь экран. Эту функцию можно вызывать до вызова <a href="common.html#worldRun">worldRun</a>.</p>
<h4>Параметры:</h4>
<p><i>resizable</i> — если <i>TRUE</i>, то разрешает пользователю изменять размер окна.</p>
<h3 id="worldGetTitle">const char* worldGetTitle();</h3>
<p>Возвращает установленный ранее заголовок окна (строка текста).</p>
<h3 id="worldSetTitle">void worldSetTitle(const char *title);</h3>
<p>Установить заголовок окна. Эту функцию можно вызывать до вызова <a href="common.html#worldRun">worldRun</a>.</p>
<h4>Параметры:</h4>
<p><i>title</i> — новый заголовок окна.</p>
<h3 id="worldSetFrameRate">void worldSetFrameRate(double frameRate);</h3>
<p>Установить фиксированную частоту перерисовки окна. Эту функцию можно вызывать до вызова <a href="common.html#worldRun">worldRun</a>. См. также: <a href="common.html#worldSetFrameRateEx">worldSetFrameRateEx</a>, <a href="common.html#worldSetVariableFrameRate">worldSetVariableFrameRate</a>.</p>
<h4>Параметры:</h4>
<p><i>frameRate</i> — количество кадров в секунду, от 1 до 100.</p>
<h3 id="worldSetVariableFrameRate">void worldSetVariableFrameRate();</h3>
<p>Установить переменную частоту перерисовки окна в диапазоне от 1 до 100 кадров в секунду. См. также: <a href="common.html#worldSetFrameRateEx">worldSetFrameRateEx</a>.</p>
<h3 id="worldGetMinFrameRate">double worldGetMinFrameRate();</h3>
<p>Возвращает ранее установленную минимальную частоту перерисовки окна. См. также: <a href="common.html#worldSetFrameRateEx">worldSetFrameRateEx</a>.</p>
<h3 id="worldGetMaxFrameRate">double worldGetMaxFrameRate();</h3>
<p>Возвращает ранее установленную максимальную частоту перерисовки окна. См. также: <i>worldSetFrameRateEx()</i>.</p>
<h3 id="worldSetFrameRateEx">double worldSetFrameRateEx(double minFrameRate, double maxFrameRate);</h3>
<p>Установить переменную частоту перерисовки окна. В этом режиме Helianthus будет стараться перерисовать окно как можно быстрее — но не быстрее заданной максимальной частоты. Реальная частота кадров будет зависеть от скорости компьютера. Если скорость компьютера и сложность рисуемой сцены не позволяют обеспечить даже минимальной частоты перерисовки, то Helianthus будет подменять реальное время имитируя для вашего приложения работу на скорости соответствующей минимальной частоте кадров — как результат происходящее на экране движение замедлится.</p>
<p>Казалось бы это очевидное поведение, но нет. В большинству программ, и, наверное, в вашей будущей программе тоже, скорость движения объектов связана со счётчиком времени. И если кадр будет рисоваться очень медленно — более секунды, то за время одного кадра движущийся объект может пройти очень большое расстояние. При этом пользователь будет лишён возможности как-то наблюдать за движением или повлиять на него. Будет лучше в этой ситуации замедлить движение объекта, но за то нарисовать несколько дополнительных кадров, показывающих промежуточные точки движения. Для этого и устанавливается минимальная частота кадров.</p>
<p>См. также: <a href="common.html#worldGetMinFrameRate">worldGetMinFrameRate</a>, <a href="common.html#worldGetMaxFrameRate">worldGetMaxFrameRate</a>, <a href="common.html#worldSetVariableFrameRate">worldSetVariableFrameRate</a>.</p>
<h4>Параметры:</h4>
<p><i>minFrameRate</i> — минимальная частота кадров;<br />
<i>maxFrameRate</i> — максимальная частота кадров.</p>
<h3 id="worldGetFrameTime">double worldGetFrameTime();</h3>
<p>Возвращает длительность отрисовки предыдущего кадра в секундах. Для первого кадра возвращается расчётное значение длительности. См. также <i>world</i><i>Set</i><i>FrameRate</i><i>Ex</i>.</p>
<h3 id="worldGetFrameCount">int worldGetFrameCount();</h3>
<p>Возвращает количество кадров прошедшее с момента запуска программы (с момента вызова функции <a href="common.html#worldRun">worldRun</a>. См. также <a href="common.html#worldGetSeconds">worldGetSeconds</a>.</p>
<h3 id="worldGetSeconds">double worldGetSeconds();</h3>
<p>Возвращает количество секунд прошедшее с момента запуска программы (с момента вызова функции <a href="common.html#worldRun">worldRun</a>. Это время может отставать от реального, если компьютер слишком медленно рисовал кадры. См. также <a href="common.html#worldSetFrameRateEx">worldSetFrameRateEx</a>, <a href="common.html#worldGetFrameCount">worldGetFrameCount</a>.</p>
<h3 id="randomNumber">int randomNumber(int min, int max);</h3>
<p>Возвращает случайное целое число от <i>min</i> до <i>max</i> включительно.</p>
<h4>Параметры:</h4>
<p><i>min</i> — минимальное значение для случайного числа;<br />
<i>max</i> — максимальное значение для случайного числа.</p>
<h3 id="randomFloat">double randomFloat();</h3>
<p>Возвращает случайное дробное число в диапазоне от 0 до 1.</p>
<h3 id="rotateVector">void rotateVector(double *x, double *y, double angle);</h3>
<p>Повернуть вектор (x, y) на угол angle. Функция принимает два указателя на координаты вектора, повёрнутый вектор записывается по указанным адресам вместо старого.</p>
<h4>Параметры:</h4>
<p><i>x</i> — указатель на переменную хранящую координату x;<br />
<i>y</i> — указатель на переменную хранящую координату y;<br />
<i>angle</i> — угол поворота в градусах.</p>
<h3 id="openDirectory">Directory openDirectory(const char *path);</h3>
<p>Если папка существует, то функция читает список файлов в папке и сохраняет этот список в памяти. Возвращает значение типа <i>Directory</i>, которое является адресом в памяти — указателем на описание списка внутри библиотеки Helianthus.</p>
<p>Если папка не существует или её по какой-то причине невозможно открыть, то функция возвращает нулевой указатель (<i>NULL</i>).</p>
<p>Имена файлов можно получить при помощи функций <a href="common.html#directoryGetCount">directoryGetCount</a> и <a href="common.html#directoryGet">directoryGet</a>. После использования список нужно удалить функцией <a href="common.html#closeDirectory">closeDirectory</a>.</p>
<p>Пример:</p>
<pre>
Directory dir = openDirectory("my/directory");
if (dir) {
for(int i = 0; i < directoryGetCount(dir); ++i) {
printf("file: %s", directoryGet(dir, i));
}
closeDirectory(dir);
}
</pre>
<h4>Параметры:</h4>
<p><i>path</i> — путь к папке.</p>
<h3 id="closeDirectory">void closeDirectory(Directory directory);</h3>
<p>Удаляет ранее загруженный список файлов из памяти. См. также <a href="common.html#openDirectory">openDirectory</a>.</p>
<p><b>Важно:</b> Скорее всего у вас в программе останется переменная в которой хранился указатель на список. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на список файлов. Вы можете занести в эту переменную другую список файлов, но использовать старое значение переменной больше нельзя это приведёт к ошибкам и непредсказуемому поведению программы.</p>
<h3 id="directoryGetCount">int directoryGetCount(Directory directory);</h3>
<p>Возвращает количество файлов в списке. См. также <a href="common.html#openDirectory">openDirectory</a> и <a href="common.html#directoryGet">directoryGet</a>.</p>
<h3 id="directoryGet">const char* directoryGet(Directory directory, int i);</h3>
<p>Возвращает имя файла с указанным номером из ранее открытого списка. См. также <a href="common.html#openDirectory">openDirectory</a> и <a href="common.html#directoryGet">directoryGet</a>.</p>
<h4>Параметры:</h4>
<p><i>i</i> — номер файла в списке.</p>
<h3 id="fileExists">int fileExists(const char *path);</h3>
<p>Возвращает <i>TRUE</i> (число 1) если файл по заданному пути существует, иначе возвращает <i>FALSE</i> (число 0).</p>
<h4>Параметры:</h4>
<p><i>path</i> — путь к проверяемому файлу.</p>
<h3 id="directoryExists">int directoryExists(const char *path);</h3>
<p>Возвращает <i>TRUE</i> (число 1) если папке по заданному пути существует, иначе возвращает <i>FALSE</i> (число 0).</p>
<h4>Параметры:</h4>
<p><i>path</i> — путь к проверяемой папке.</p>
<h3 id="messageBox">void messageBox(const char *message);</h3>
<p>Показать окно с текстовым сообщением. Работа программы будет приостановлена, до тех пор пока пользователь не закроет окно (нажав на кнопку OK, например).</p>
<h4>Параметры:</h4>
<p><i>message</i> — текстовое сообщение.</p>
<h3 id="questionBox">int questionBox(const char *question, const char *answer0, const char *answer1);</h3>
<p>Функция показывает на экране окно вопроса с двумя вариантами ответа. Работа программы будет приостановлена до тех пор пока пользователь не выберет один из вариантов или не закроет окно вопроса (что равносильно выбору варианта номер 0). Функция возвращает номер выбранного ответа — 0 или 1. См. также: <a href="common.html#messageBox">messageBox</a>, <a href="common.html#questionBox3">questionBox3</a>.</p>
<h4>Параметры:</h4>
<p><i>question</i> — текст задаваемого вопроса;<br />
<i>answer0</i> — такст варианта ответа номер 0, этот вариант выбирается если пользователь закрывает окно вопроса или нажимает клавишу Esc. Удобно использовать с текстом «Нет» или «Отмена»;<br />
<i>answer1</i> — текст варианта ответа номер 1, этот вариант выбирается по-умолчанию если пользователь нажимает клавишу Enter. Удобно использовать с текстом «Да» или «OK».</p>
<h3 id="questionBox3">int questionBox3(const char *question, const char *answer0, const char *answer1, const char *answer2);</h3>
<p>Функция показывает на экране окно вопроса с тремя вариантами ответа. Работа программы будет приостановлена до тех пор пока пользователь не выберет один из вариантов или не закроет окно вопроса (что равносильно выбору варианта номер 0). Функция возвращает номер выбранного ответа — 0, 1 или 2. См. также: <a href="common.html#messageBox">messageBox</a>, <a href="common.html#questionBox">questionBox</a>.</p>
<h4>Параметры:</h4>
<p><i>question</i> — текст задаваемого вопроса;<br />
<i>answer0</i> — такст варианта ответа номер 0, этот вариант выбирается если пользователь закрывает окно вопроса или нажимает клавишу Esc. Удобно использовать с текстом «Отмена» в наборе Да/Нет/Отмена;<br />
<i>answer</i><i>1</i> — такст варианта ответа номер 1. Удобно использовать с текстом «Нет» в наборе Да/Нет/Отмена;<br />
<i>answer</i><i>2</i> — текст варианта ответа номер 2, этот вариант выбирается по-умолчанию если пользователь нажимает клавишу Enter. Удобно использовать с текстом «Да» в наборе Да/Нет/Отмена.</p>
<h3 id="askText">int askText(const char *question, char *answer, int maxAnswerSize);</h3>
<p>Создаёт окно для ввода текста. Пользователю будет предоставлена для редактирования строка текста из параметра <i>answer</i>. Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. Возвращает <i>TRUE</i> (число 1) при успешном вводе и <i>FALSE</i> (число 0) если пользователь отменил ввод. См. также <a href="common.html#askTextEx">askTextEx</a>.</p>
<h4>Параметры:</h4>
<p><i>question</i> — сообщение для пользователя;<br />
<i>answer</i> — указатель на строку куда будет сохранён ответ, также этот параметр используется чтобы задать начальное значение для текстового поля;<br />
<i>maxAnswerSize</i> — максимальный размер для строки ответа в байтах включая ограничивающий нулевой байт.</p>
<h3 id="askTextEx">int askTextEx(const char *question, char *answer, int maxAnswerSize, int multiline, int password);</h3>
<p>Создаёт окно для ввода текста. Пользователю будет предоставлен для редактирования текст из параметра <i>answer</i>. Позволяет работать с многострочным текстом и прятать вводимые символы (для ввода пароля). Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. Возвращает <i>TRUE</i> (число 1) при успешном вводе и <i>FALSE</i> (число 0) если пользователь отменил ввод. См. также <a href="common.html#askText">askText</a>.</p>
<h4>Параметры:</h4>
<p><i>question</i> — сообщение для пользователя;<br />
<i>answer</i> — указатель на строку куда будет сохранён ответ, также этот параметр используется чтобы задать начальное значение для текстового поля;<br />
<i>maxAnswerSize</i> — максимальный размер для строки ответа в байтах включая ограничивающий нулевой байт;<br />
<i>multiline</i> — если <i>TRUE</i>, то будет отображаться поле для ввода многострочного текста;<br />
<i>password</i> — если <i>TRUE</i>, то вводимые символы будут спрятаны (можно использовать для ввода паролей).</p>
</div>
</body>
</html>