Запуск и общие функции

Для подключения и использования библиотеки Helianthus нужно:
- подключить файл <helianthus.h>
- создать и зарегистрировать функции для начальной загрузки и для перерисовки кадра (см. windowSetInit и windowSetDraw)
- также вы можете зарегистрировать функцию для выполнения каких-либо действий при завершении программы (windowSetDeinit);
- вызвать функцию windowRun для запуска вашей программы.

Вот что должно получиться:

#include <helianthus.h>

void init() {
    // Здесь будут команды для начальной загрузки.
    // Они выполнятся только один раз в самом начале.
}

void draw() {
    // Здесь будут команды для движения и рисования.
    // Во время работы программы они будут запускаться
    // несколько раз в секунду.
}

int main() {
    windowSetInit(&init); 
    windowSetDraw(&draw);
    windowRun();
    return 0;
}

После завершения работы Helianthus (при окончании выполнения функции windowRun) все созданные вами объекты библиотеки будут удалены автоматически. Если вы хотите удалить что-то вручную, смотрите функции удаления для соответствующих объектов (spriteDestroy, groupDestroy, soundDestroy, fontDestroy, textLayoutDestroy, animationDestroy, framebufferDestroy, closeDirectory).

Вы можете задать размер окна программы функциями windowSetSize, windowSetWidth, windowSetHeight и задать заголовок окна функцией windowSetTitle. В отличие от большинства других функций Helianthus эти функции можно вызывать до запуска windowRun.

Изначально окно имеет фиксированный размер, который вы можете менять только из программы, командами указанными выше. Однако, вы можете это изменить и разрешить пользователю изменять размер окна, смотрите функцию windowSetResizable.

Окно программы непрерывно перерисовывается с частотой 24 кадра в секунду. Частоту перерисовки вы можете поменять при помощи функции windowSetFrameRate. Рекомендуем также ознакомиться с функцией windowSetVariableFrameRate.

Программа ведёт отсчёт времени и кадров с момента запуска вы можете получить значение этих счётчиков при помощи функций windowGetSeconds и windowGetFrameCount. Длительность одного кадра (длительность предыдущего отрисованного кадра) можно узнать вызвав функцию windowGetFrameTime.

Для получения доступа к буферу обмена (того самого с которым связаны клавиши Ctrl+C, Ctrl+V) используйте функции windowGetClipboardText и windowSetClipboardText.

Также Helianthus предоставляет некоторые общие функции которые не представлены в стандартном я зыке C:
- помощники в генерации случайных чисел (randomNumber, randomFloat);
- функция поворота вектора rotateVector;
- функции для чтения папок (см. openDirectory);
- функции проверки существования файлов и папок — fileExists, directoryExists.
- функции для создания всплывающих окон с текстовыми сообщениями (messageBox, questionBox, questionBox3) и окон для ввода текста (askText, askTextf, askTextEx).

Функции:

void windowSetInit(Callback init);

Задать функцию для начальной инициализации (загрузки). Эта функция будет запущена только один раз в самом начале работы программы, как только будет вызвана функция windowRun.

Параметры:

init — указатель на функцию начальной инициализации (загрузки). Функция быть работать без параметров и не должна возвращать значение.

void windowSetDraw(Callback draw);

Задать основную функцию вашей программы — функцию для перерисовки кадра. Во время работы программы заданная функция будет запускаться несколько раз в секунду перед перерисовкой каждого кадра. Поместите в неё команды для движения и рисования.

Параметры:

draw — указатель на функцию перерисовки кадра. Функция быть работать без параметров и не должна возвращать значение.

void windowSetDeinit(Callback deinit);

Задать функцию для выполнения каких-либо действий при завершении программы. Эта функция будет запущена только один раз при окончании работы программы, непосредственно перед завершением выполнения функции windowRun.

Параметры:

deinit — указатель на функцию которая будет выполнена перед завершением программы.

void windowRun();

Запустить вашу программу на Helianthus. Перед вызовом этой функции нужно зарегистрировать функции начальной загрузки и перерисовки кадра (см. выше)

void windowStop();

Остановить и закрыть программу. Программа всегда закрывается если пользователь нажмёт на крестик в верхнем правом углу окна, но вы можете добавить и свои способы выхода из программы. Например, в функцию перерисовки вы можете вставить возможность выхода по нажатию клавиши Esc (см. также раздел «Клавиатура и мышь»):

void draw() {
    …
    if (keyWentDown("escape")) {
        windowStop()
    }
    …
}

int windowGetWidth();

Возвращает ширину окна в пикселях. См. также windowSetWidth.

void windowSetWidth(int width);

Установить ширину окна. Эту функцию можно вызывать до вызова windowRun. См. также windowGetWidth, windowSetHeight, windowSetSize.

Параметры:

width — новая ширина окна.

int windowGetHeight();

Возвращает высоту окна в пикселях. См. также windowSetHeight.

void windowSetHeight(int height);

Установить высоту окна. Эту функцию можно вызывать до вызова windowRun. См. также windowGetHeight, windowSetWidth, windowSetSize.

Параметры:

height — новая высота окна.

void windowSetSize(int width, int height);

Установить сразу и ширину и высоту окна. Эту функцию можно вызывать до вызова windowRun. См. также windowSetWidth, windowSetHeight.

Параметры:

width — новая ширина окна;
height — новая высота окна.

int windowGetResizable();

Возвращает TRUE если пользователь имеет возможность изменять размер окна, в противном случае возвращает FALSE.

void windowSetResizable(int resizable);

Включает или выключает возможность измерения размеров окна пользователем. Когда включено пользователь может менять размер окна растягивая его, хватаясь за границы, и, появляется кнопка для разворачивания окна на весь экран. Эту функцию можно вызывать до вызова windowRun.

Параметры:

resizable — если TRUE, то разрешает пользователю изменять размер окна.

const char* windowGetTitle();

Возвращает установленный ранее заголовок окна (строка текста).

void windowSetTitle(const char *title);

Установить заголовок окна. Эту функцию можно вызывать до вызова windowRun.

Параметры:

title — новый заголовок окна.

void windowSetFrameRate(double frameRate);

Установить фиксированную частоту перерисовки окна. Эту функцию можно вызывать до вызова windowRun. См. также: windowSetFrameRateEx, windowSetVariableFrameRate.

Параметры:

frameRate — количество кадров в секунду, от 1 до 100.

void windowSetVariableFrameRate();

Установить переменную частоту перерисовки окна в диапазоне от 1 до 100 кадров в секунду. См. также: windowSetFrameRateEx.

double windowGetMinFrameRate();

Возвращает ранее установленную минимальную частоту перерисовки окна. См. также: windowSetFrameRateEx.

double windowGetMaxFrameRate();

Возвращает ранее установленную максимальную частоту перерисовки окна. См. также: windowSetFrameRateEx().

double windowSetFrameRateEx(double minFrameRate, double maxFrameRate);

Установить переменную частоту перерисовки окна. В этом режиме Helianthus будет стараться перерисовать окно как можно быстрее — но не быстрее заданной максимальной частоты. Реальная частота кадров будет зависеть от скорости компьютера. Если скорость компьютера и сложность рисуемой сцены не позволяют обеспечить даже минимальной частоты перерисовки, то Helianthus будет подменять реальное время имитируя для вашего приложения работу на скорости соответствующей минимальной частоте кадров — как результат происходящее на экране движение замедлится.

Казалось бы это очевидное поведение, но нет. В большинству программ, и, наверное, в вашей будущей программе тоже, скорость движения объектов связана со счётчиком времени. И если кадр будет рисоваться очень медленно — более секунды, то за время одного кадра движущийся объект может пройти очень большое расстояние. При этом пользователь будет лишён возможности как-то наблюдать за движением или повлиять на него. Будет лучше в этой ситуации замедлить движение объекта, но за то нарисовать несколько дополнительных кадров, показывающих промежуточные точки движения. Для этого и устанавливается минимальная частота кадров.

См. также: windowGetMinFrameRate, windowGetMaxFrameRate, windowSetVariableFrameRate.

Параметры:

minFrameRate — минимальная частота кадров;
maxFrameRate — максимальная частота кадров.

double windowGetFrameTime();

Возвращает длительность отрисовки предыдущего кадра в секундах. Для первого кадра возвращается расчётное значение длительности. См. также windowSetFrameRateEx.

int windowGetFrameCount();

Возвращает количество кадров прошедшее с момента запуска программы (с момента вызова функции windowRun. См. также windowGetSeconds.

double windowGetSeconds();

Возвращает количество секунд прошедшее с момента запуска программы (с момента вызова функции windowRun. Это время может отставать от реального, если компьютер слишком медленно рисовал кадры. См. также windowGetMonotonicSeconds, windowSetFrameRateEx, windowGetFrameCount.

double windowGetMonotonicSeconds();

Возвращает количество секунд прошедшее с момента запуска программы (с момента вызова функции windowRun. Это время не зависит от частоты перерисовки кадров и мощности компьютера. См. также windowGetSeconds, windowGetMonotonicMilliseconds.

unsigned long long windowGetMonotonicMilliseconds();

Возвращает количество миллисекунд прошедшее с момента запуска программы (с момента вызова функции windowRun. Это время не зависит от частоты перерисовки кадров и мощности компьютера. См. также windowGetMonotonicSeconds.

const char* windowGetClipboardText();

Данная функция позволяет получить текст из системного буфера обмена. Это тот буфер в который помещается текст при нажатии Ctrl+C. См. также windowSetClipboardText.

void windowSetClipboardText(const char *text);

Функция помещает текст в системный буфер обмена. См. также windowSetClipboardTextEx и windowGetClipboardText.

Параметры:

text — текст, который будет скопирован в буфер.

void windowSetClipboardTextEx(const char *text, int len);

Точно так же как и windowSetClipboardText, данная функция помещает текст в системный буфер обмена. С той лишь разницей, что в данном случае в буфер помещается не весь текст, а только указанное количество его байтов. См. также windowSetClipboardText и windowGetClipboardText.

Параметры:

text — текст, который будет скопирован в буфер;
len — количество байтов текста, которые необходимо скопировать.

int randomNumber(int min, int max);

Возвращает случайное целое число от min до max включительно. Используется стандартная функция rand() из <stdlib.h>.

Параметры:

min — минимальное значение для случайного числа;
max — максимальное значение для случайного числа.

double randomFloat();

Возвращает случайное дробное число в диапазоне от 0 до 1. Используется стандартная функция rand() из <stdlib.h>.

void rotateVector(double x, double y, double angle);

Повернуть вектор (x, y) на угол angle. Функция принимает два указателя на координаты вектора, повёрнутый вектор записывается по указанным адресам вместо старого.

Параметры:

x — указатель на переменную хранящую координату x;
y — указатель на переменную хранящую координату y;
angle — угол поворота в градусах.

Directory openDirectory(const char *path);

Если папка существует, то функция читает список файлов в папке и сохраняет этот список в памяти. Возвращает значение типа Directory, которое является адресом в памяти — указателем на описание списка внутри библиотеки Helianthus.

Если папка не существует или её по какой-то причине невозможно открыть, то функция возвращает нулевой указатель (NULL).

Имена файлов можно получить при помощи функций directoryGetCount, directoryGet и directoryGetFull. После использования список нужно удалить функцией closeDirectory. См. также openDirectoryEx.

Пример:

Directory dir = openDirectory("my/directory");
if (dir) {
    for(int i = 0; i < directoryGetCount(dir); ++i) {
        printf("file: %s", directoryGet(dir, i));
    }
    closeDirectory(dir);
}

Параметры:

path — путь к папке.

Directory openDirectoryEx(const char path, const char prefix, const char *suffix, int caseSensitive, int showFiles, int showDirectories);

Аналогично функции openDirectory, эта функция строит список имён файлов в указанной папке. Но в данном случае список фильтруется по заданным параметрам. Если папка не существует или её по какой-то причине невозможно открыть, то функция возвращает нулевой указатель (NULL). Созданный список (не NULL) после использования нужно удалить функцией closeDirectory.

Параметры:

path — путь к папке;
prefix — включать только имена начинающиеся с указанной строки;
suffix — включать только имена оканчивающиеся на указанную строку;
caseSensitive — если TRUE, то функция будет отличать большие и маленькие буквы, в противном случае заглавное и строчное написание будет считаться одним и тем же символом;
showFiles — если TRUE, то обычные файлы (не папки) будут включены в список;
showDirectories — если TRUE, то папки будут включены в список.

void closeDirectory(Directory directory);

Удаляет ранее загруженный список файлов из памяти. См. также openDirectory.

Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на список. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на список файлов. Вы можете занести в эту переменную другую список файлов, но использовать старое значение переменной больше нельзя это приведёт к ошибкам и непредсказуемому поведению программы.

int directoryGetCount(Directory directory);

Возвращает количество файлов в списке. См. также openDirectory и directoryGet.

const char* directoryGet(Directory directory, int i);

Возвращает имя файла с указанным номером из ранее открытого списка. См. также openDirectory и directoryGetFull.

Параметры:

i — номер файла в списке.

const char* directoryGetFull(Directory directory, int i);

Возвращает путь к файлу (путь к папке, указанный при открытии + имя файла) с указанным номером из ранее открытого списка. См. также openDirectory и directoryGet.

Параметры:

i — номер файла в списке.

int fileExists(const char *path);

Возвращает TRUE (число 1) если файл по заданному пути существует, иначе возвращает FALSE (число 0).

Параметры:

path — путь к проверяемому файлу.

int directoryExists(const char *path);

Возвращает TRUE (число 1) если папке по заданному пути существует, иначе возвращает FALSE (число 0).

Параметры:

path — путь к проверяемой папке.

void messageBox(const char *message);

Показать окно с текстовым сообщением. Работа программы будет приостановлена, до тех пор пока пользователь не закроет окно (нажав на кнопку OK, например).

Параметры:

message — текстовое сообщение.

int questionBox(const char question, const char answer0, const char *answer1);

Функция показывает на экране окно вопроса с двумя вариантами ответа. Работа программы будет приостановлена до тех пор пока пользователь не выберет один из вариантов или не закроет окно вопроса (что равносильно выбору варианта номер 0). Функция возвращает номер выбранного ответа — 0 или 1. См. также: messageBox, questionBox3.

Параметры:

question — текст задаваемого вопроса;
answer0 — такст варианта ответа номер 0, этот вариант выбирается если пользователь закрывает окно вопроса или нажимает клавишу Esc. Удобно использовать с текстом «Нет» или «Отмена»;
answer1 — текст варианта ответа номер 1, этот вариант выбирается по-умолчанию если пользователь нажимает клавишу Enter. Удобно использовать с текстом «Да» или «OK».

int questionBox3(const char question, const char answer0, const char answer1, const char answer2);

Функция показывает на экране окно вопроса с тремя вариантами ответа. Работа программы будет приостановлена до тех пор пока пользователь не выберет один из вариантов или не закроет окно вопроса (что равносильно выбору варианта номер 0). Функция возвращает номер выбранного ответа — 0, 1 или 2. См. также: messageBox, questionBox.

Параметры:

question — текст задаваемого вопроса;
answer0 — такст варианта ответа номер 0, этот вариант выбирается если пользователь закрывает окно вопроса или нажимает клавишу Esc. Удобно использовать с текстом «Отмена» в наборе Да/Нет/Отмена;
answer1 — такст варианта ответа номер 1. Удобно использовать с текстом «Нет» в наборе Да/Нет/Отмена;
answer2 — текст варианта ответа номер 2, этот вариант выбирается по-умолчанию если пользователь нажимает клавишу Enter. Удобно использовать с текстом «Да» в наборе Да/Нет/Отмена.

int askText(const char question, char answer, int maxAnswerSize);

Создаёт окно для ввода текста. Пользователю будет предоставлена для редактирования строка текста из параметра answer. Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. Возвращает TRUE (число 1) при успешном вводе и FALSE (число 0) если пользователь отменил ввод. См. также askTextEx.

Параметры:

int askTextf(const char question, const char format, ...);

Создаёт окно для ввода однострочного текста. Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. Введённый текст будет преобразован в переменные в соответствие со строкой форматирования (format), точно также как это делает стандартная функция scanf из модуля <stdio.h>. Возвращает количество успешно прочитанных аргументов при успешном вводе или стандартную константу EOF (обычно это -1) если пользователь отменил ввод. См. также askText.

Параметры:

question — сообщение для пользователя;
format — строка форматирования.

int askTextEx(const char question, char answer, int maxAnswerSize, int multiline, int password);

Создаёт окно для ввода текста. Пользователю будет предоставлен для редактирования текст из параметра answer. Позволяет работать с многострочным текстом и прятать вводимые символы (для ввода пароля). Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. Возвращает TRUE (число 1) при успешном вводе и FALSE (число 0) если пользователь отменил ввод. См. также askText.

Параметры:

question — сообщение для пользователя;
answer — указатель на строку куда будет сохранён ответ, также этот параметр используется чтобы задать начальное значение для текстового поля;
maxAnswerSize — максимальный размер для строки ответа в байтах включая ограничивающий нулевой байт;
multiline — если TRUE, то будет отображаться поле для ввода многострочного текста;
password — если TRUE, то вводимые символы будут спрятаны (можно использовать для ввода паролей).

Запуск и общие функции

Функции:

void windowSetInit(Callback init);

Параметры:

void windowSetDraw(Callback draw);

Параметры:

void windowSetDeinit(Callback deinit);

Параметры:

void windowRun();

void windowStop();

int windowGetWidth();

void windowSetWidth(int width);

Параметры:

int windowGetHeight();

void windowSetHeight(int height);

Параметры:

void windowSetSize(int width, int height);

Параметры:

int windowGetResizable();

void windowSetResizable(int resizable);

Параметры:

const char* windowGetTitle();

void windowSetTitle(const char *title);

Параметры:

void windowSetFrameRate(double frameRate);

Параметры:

void windowSetVariableFrameRate();

double windowGetMinFrameRate();

double windowGetMaxFrameRate();

double windowSetFrameRateEx(double minFrameRate, double maxFrameRate);

Параметры:

double windowGetFrameTime();

int windowGetFrameCount();

double windowGetSeconds();

double windowGetMonotonicSeconds();

unsigned long long windowGetMonotonicMilliseconds();

const char* windowGetClipboardText();

void windowSetClipboardText(const char *text);

Параметры:

void windowSetClipboardTextEx(const char *text, int len);

Параметры:

int randomNumber(int min, int max);

Параметры:

double randomFloat();

void rotateVector(double *x, double *y, double angle);

Параметры:

Directory openDirectory(const char *path);

Параметры:

Directory openDirectoryEx(const char *path, const char *prefix, const char *suffix, int caseSensitive, int showFiles, int showDirectories);

Параметры:

void closeDirectory(Directory directory);

int directoryGetCount(Directory directory);

const char* directoryGet(Directory directory, int i);

Параметры:

const char* directoryGetFull(Directory directory, int i);

Параметры:

int fileExists(const char *path);

Параметры:

int directoryExists(const char *path);

Параметры:

void messageBox(const char *message);

Параметры:

int questionBox(const char *question, const char *answer0, const char *answer1);

Параметры:

int questionBox3(const char *question, const char *answer0, const char *answer1, const char *answer2);

Параметры:

int askText(const char *question, char *answer, int maxAnswerSize);

Параметры:

int askTextf(const char *question, const char *format, ...);

Параметры:

int askTextEx(const char *question, char *answer, int maxAnswerSize, int multiline, int password);

Параметры:

void rotateVector(double x, double y, double angle);

Directory openDirectoryEx(const char path, const char prefix, const char *suffix, int caseSensitive, int showFiles, int showDirectories);

int questionBox(const char question, const char answer0, const char *answer1);

int questionBox3(const char question, const char answer0, const char answer1, const char answer2);

int askText(const char question, char answer, int maxAnswerSize);

int askTextf(const char question, const char format, ...);

int askTextEx(const char question, char answer, int maxAnswerSize, int multiline, int password);