Blame doc/ru/common.html

7a004b
7a004b
7a004b
<meta charset="UTF-8">
7a004b
<link href="style.css" rel="stylesheet" type="text/css">
7a004b
<title>Запуск и общие функции - Helianthus</title>
7a004b
7a004b
7a004b
77a314
  

Helianthus

77a314
  
77a314
  

Helianthus: Документация

77a314
  

Установка

7a004b
  

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

7a004b
  

Клавиатура и мышь

7a004b
  

Рисование

cece70
  

Шрифты и текст

cece70
  

Текстуры и анимация

cece70
  

Буфер кадра

7a004b
  

Спрайты

7a004b
  

Группы спрайтов

7a004b
  

Звук

e9aada
  

Пользовательский интерфейс

7a004b
  
7a004b
  

Все функции

7a004b
7a004b
7a004b
7a004b

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

7a004b
7a004b

Для подключения и использования библиотеки Helianthus нужно:

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

7a004b
7a004b

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

7a004b
7a004b
7a004b
#include <helianthus.h>
7a004b
7a004b
void init() {
7a004b
    // Здесь будут команды для начальной загрузки.
7a004b
    // Они выполнятся только один раз в самом начале.
7a004b
}
7a004b
7a004b
void draw() {
7a004b
    // Здесь будут команды для движения и рисования.
7a004b
    // Во время работы программы они будут запускаться
7a004b
    // несколько раз в секунду.
7a004b
}
7a004b
7a004b
int main() {
d38577
    windowSetInit(&init); 
d38577
    windowSetDraw(&draw);
d38577
    windowRun();
7a004b
    return 0;
7a004b
}
7a004b
7a004b
7a004b
d38577

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

1badb6
d38577

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

1badb6
d38577

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

1badb6
e9aada

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

1badb6
d38577

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

1badb6
e9aada

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

e9aada
1badb6

Также Helianthus предоставляет некоторые общие функции которые не представлены в стандартном я зыке C:

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

1badb6
7a004b

Функции:

7a004b
d38577

void windowSetInit(Callback init);

7a004b
d38577

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

7a004b
7a004b

Параметры:

7a004b
7a004b

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

7a004b
d38577

void windowSetDraw(Callback draw);

7a004b
7a004b

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

7a004b
7a004b

Параметры:

7a004b
7a004b

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

7a004b
d38577

void windowSetDeinit(Callback deinit);

1badb6
d38577

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

1badb6
1badb6

Параметры:

1badb6
1badb6

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

1badb6
d38577

void windowRun();

7a004b
7a004b

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

7a004b
d38577

void windowStop();

7a004b
acc470

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

7a004b
7a004b
7a004b
void draw() {
7a004b
    …
cece70
    if (keyWentDown("escape")) {
d38577
        windowStop()
7a004b
    }
7a004b
    …
7a004b
}
7a004b
7a004b
7a004b
d38577

int windowGetWidth();

7a004b
d38577

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

7a004b
d38577

void windowSetWidth(int width);

7a004b
d38577

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

7a004b
7a004b

Параметры:

7a004b
7a004b

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

7a004b
d38577

int windowGetHeight();

7a004b
d38577

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

7a004b
d38577

void windowSetHeight(int height);

7a004b
d38577

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

cece70
cece70

Параметры:

cece70
cece70

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

cece70
d38577

void windowSetSize(int width, int height);

cece70
d38577

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

7a004b
7a004b

Параметры:

7a004b
cece70

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

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

7a004b
d38577

int windowGetResizable();

1badb6
1badb6

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

1badb6
d38577

void windowSetResizable(int resizable);

1badb6
d38577

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

1badb6
1badb6

Параметры:

1badb6
1badb6

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

1badb6
d38577

const char* windowGetTitle();

1badb6
1badb6

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

1badb6
d38577

void windowSetTitle(const char *title);

1badb6
d38577

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

1badb6
1badb6

Параметры:

1badb6
1badb6

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

1badb6
d38577

void windowSetFrameRate(double frameRate);

7a004b
d38577

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

7a004b
7a004b

Параметры:

7a004b
7a004b

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

7a004b
d38577

void windowSetVariableFrameRate();

cece70
d38577

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

cece70
d38577

double windowGetMinFrameRate();

cece70
d38577

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

cece70
d38577

double windowGetMaxFrameRate();

cece70
d38577

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

cece70
d38577

double windowSetFrameRateEx(double minFrameRate, double maxFrameRate);

cece70
cece70

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

cece70
cece70

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

cece70
d38577

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

cece70
cece70

Параметры:

7a004b
cece70

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

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

cece70
d38577

double windowGetFrameTime();

cece70
d38577

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

7a004b
d38577

int windowGetFrameCount();

7a004b
d38577

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

7a004b
d38577

double windowGetSeconds();

7a004b
d38577

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

d38577
d38577

double windowGetMonotonicSeconds();

d38577
d38577

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

d38577
d38577

unsigned long long windowGetMonotonicMilliseconds();

d38577
d38577

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

7a004b
e9aada

const char* windowGetClipboardText();

e9aada
e9aada

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

e9aada
e9aada

void windowSetClipboardText(const char *text);

e9aada
e9aada

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

e9aada
e9aada

Параметры:

e9aada
e9aada

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

e9aada
e9aada

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

e9aada
e9aada

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

e9aada
e9aada

Параметры:

e9aada
e9aada

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

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

e9aada
7a004b

int randomNumber(int min, int max);

7a004b
d38577

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

7a004b
7a004b

Параметры:

7a004b
7a004b

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

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

7a004b
7a004b

double randomFloat();

7a004b
d38577

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

7a004b
cece70

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

cece70
cece70

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

cece70
cece70

Параметры:

cece70
cece70

x — указатель на переменную хранящую координату x;

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

cece70
1badb6

Directory openDirectory(const char *path);

1badb6
1badb6

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

1badb6
1badb6

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

1badb6
d38577

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

1badb6
1badb6

Пример:

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

Параметры:

1badb6
1badb6

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

1badb6
d38577

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

d38577
d38577

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

d38577
d38577

Параметры:

d38577
d38577

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

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

d38577
1badb6

void closeDirectory(Directory directory);

1badb6
1badb6

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

1badb6
1badb6

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

1badb6
1badb6

int directoryGetCount(Directory directory);

1badb6
1badb6

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

1badb6
1badb6

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

1badb6
d38577

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

d38577
d38577

Параметры:

d38577
d38577

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

d38577
d38577

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

d38577
d38577

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

1badb6
1badb6

Параметры:

1badb6
1badb6

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

1badb6
1badb6

int fileExists(const char *path);

1badb6
1badb6

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

1badb6
1badb6

Параметры:

1badb6
1badb6

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

1badb6
1badb6

int directoryExists(const char *path);

1badb6
1badb6

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

1badb6
1badb6

Параметры:

1badb6
1badb6

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

1badb6
1badb6

void messageBox(const char *message);

1badb6
1badb6

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

1badb6
1badb6

Параметры:

1badb6
1badb6

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

1badb6
cece70

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

cece70
cece70

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

cece70
cece70

Параметры:

cece70
cece70

question — текст задаваемого вопроса;

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

cece70
cece70

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

cece70
cece70

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

cece70
cece70

Параметры:

cece70
cece70

question — текст задаваемого вопроса;

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

cece70
cece70

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

1badb6
cece70

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

1badb6
1badb6

Параметры:

1badb6
1badb6

question — сообщение для пользователя;

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

1badb6
d38577

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

d38577
d38577

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

d38577
d38577

Параметры:

d38577
d38577

question — сообщение для пользователя;

d38577
format — строка форматирования.

d38577
cece70

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

1badb6
cece70

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

1badb6
1badb6

Параметры:

1badb6
1badb6

question — сообщение для пользователя;

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

1badb6
7a004b
7a004b
7a004b