Библиотека Helianthus позволяет вам загружать и использовать в ваших программах различные изображения (текстуры) из файлов PNG. Также вы можете использовать анимированные текстуры — для создания анимации нужно все кадры в формате PNG разместить в одной папке и указать эту папку в качестве имени файла для загрузки. Для вашего удобства и сокращения количества используемых функций и одиночная текстура и анимация представлены в Helianthus в качестве одного и того же типа объектов — это всё анимации. Просто для одиночной текстуры количество кадров анимации равно одному. Количество кадров для загруженной анимации можно узнать при помощи функции animationGetFramesCount.
+
+
Чтобы загрузить текстуру используйте функцию createAnimation, которая возвращает значение типа Animation, которое по сути является адресом в памяти — указателем на описание текстуры внутри библиотеки Helianthus. Библиотека запоминает пути к загружаемым файлам, и, в случае многократной загрузки одного и того же файла не расходует лишнюю память, а работает лишь с одной копией изображения. Это изображение будет выгружено из памяти в тот момент когда будет удалена (animationDestroy) последняя использующая его анимация.
Анимация загружается установленной на паузу — то есть по-умолчанию она не воспроизводится. Запустить воспроизведение можно функцией animationPlay, снова поставить на паузу — animationPause. Кроме того анимация по-умолчанию зациклена, то есть когда она проиграет до конца — она сразу же начинается сначала. Вы можете это изменить используя функцию animationSetLoop.
+
+
Ещё один важный параметр анимации это скорость её воспроизведения. По-умолчанию она равна общей частоте перерисовки кадров (см. worldSetFrameRate), но если задан диапазон частоты — переменная частота кадров (worldSetFrameRateEx), то берётся значение из этого диапазона ближайшее к 24 кадрам в секунду. Если вас это не устраивает, задайте свою частоту смены кадров функцией animationSetFps.
Текстуры и анимации описанные выше — это уже загруженные на видеокарту данные и читать или менять пиксели в них нельзя. Для того чтобы работать с пикселями напрямую вам нужно загрузить их в оперативную память из файла — imageLoad, из текстуры — imageFromGLTexture и animationGetGLTexId или из пикселей на экране — imageFromViewport.
+
+
В отличие от анимации данные изображения не сгруппированы в структуру, а представлены в виде трёх отдельных переменных: ширина изображения, высота изображения и указатель на данные — массив пикселей. Данные это простая последовательность байтов — пикселив них записаны по строкам сверху вниз слева направо. Каждый пиксель — это четыре байта в формате RGBA — красный, зелёный, синий и непрозрачность (alpha). Для хранения этих данных выделяется оперативная память и прежде чем закончить с ними работу и забыть нужно эту память освободить функцией free из стандартного модуля <stdlib.h>. Сложновато? Да. Но ведь это низкоуровневые функции и прибегать к ним вам придётся только в редких случаях — если вам не хватило базового функционала.
+
+
Читать и записывать отдельные пиксели можно либо вручную высчитав номера отдельных байтов или при помощи функций imageGetPixel, imageSetPixel — которые сделают эти вычисления за вас.
+
+
Полученное изображение можно сохранить в файл — imageSave, отправить на видеокарту в виде текстуры OpenGL — imageToGLTexture или создать из изображения однокадровую анимацию — createAnimationFromImage.
+
+
Вот пример работы с изображениями:
+
+
+// Все три переменные представленные ниже
+// необходимы для работы с одним единственным изображением.
+// Если вы захотите работать одновременно с двумя изображениями,
+// то вам придётся завести дополнительную
+// тройку аналогичных переменных.
+int width = 0, height = 0; // Сюда будут записаны
+ // ширина и высота изображения.
+void *data = NULL; // Это указатель на данные изображения,
+ // пока он указывает в никуда.
+
+// Попытаемся загрузить изображения
+// будьте готовы к тому, что это не всегда удастся -
+// вдруг кто-то удалит файл, например.
+if (imageLoad("image.png", &width, &height, &data)) {
+ // Ура! Файл существует и нам даже удалось его загрузить.
+ // Поставим синий пиксель в координатах 10, 2.
+ // Если, конечно, в загруженном изображении
+ // есть эти координаты.
+ if (width > 10 && height > 2)
+ imageSetPixel(data, 10, 2, colorByName("blue"));
+
+ // Сохраним изображение в другой файлы
+ // будьте осторожны если такой файл уже существует,
+ // то он будет перезапиан!
+ imageSave("image2.png", width, heigh, data);
+
+ // Мы закончили работу с изображением -
+ // нужно освободить выделенную для его данных память.
+ free(data);
+
+ // Обнулим указатель на данные. Это необязательно,
+ // просто на всякий случай. Это немножко защитит нас
+ // от наших ошибок. Если мы вдруг попытаемся использовать
+ // нулевой указатель, то в большинстве случаев увидим
+ // явную ошибку и её источник. И сможем её исправить.
+ // Использование же ненулевого указателя на уже
+ // освобождённую память приведёт к совершенно
+ // не предсказуемым ошибкам в совсем других
+ // частях программы.
+ data = NULL;
+} else {
+ // Не удалось загрузить изображение,
+ // возможно файла нет или он есть, но повреждён,
+ // или ещё что-то случилось.
+ // Сообщим-ка пользователю об этой проблеме.
+ printf("Ничего не получилось, увы :(");
+}
+
+
Загрузить текстуру из файла PNG или цепочку кадров в формате PNG из папки. Эквивалентно вызову createAnimationEx. со включенным сглаживанием (smooth) и отключенными повторами (horWrap, vertWrap).
+
+
Параметры:
+
+
path — путь к файлу или папке.
+
+
Animation createAnimationEx(const char *path, int smooth, int horWrap, int vertWrap);
+
+
Загрузить текстуру из файла PNG или цепочку кадров анимации в формате PNG из папки.
+
+
Если в качестве пути указана папка, из неё будут загружены все изображения и отсортированы в алфавитном порядке. Частота кадров для вновь созданной анимации будет равна частоте перерисовки экрана (worldSetFrameRate). Если задан диапазон частоты (worldSetFrameRateEx), то из этого диапазона будет выбрана частота ближайшая к 24-м кадрам в секунду.
+
+
Если файл не удалось загрузить файл(ы), то функция вернёт анимацию с нулевым количеством кадров.
+
+
Helianthus запоминает пути к загружаемым файлам, и, в случае многократной загрузки одного и того же файла не расходует лишнюю память, а работает лишь с одной копией изображения. Это изображение будет выгружено из памяти в тот момент когда будет удалена (animationDestroy) последняя использующая его анимация.
+
+
Если параметр smooth равен TRUE, то загруженная текстура будет отображаться сглаженной — вы не увидите резких переходов между пикселями (трилинейная фильтрация).
+
+
Параметры horWrap и vertWrap включают (TRUE) или выключают (FALSE) бесконечное повторение узора текстуры по горизонтали и вертикали соответственно.
path — путь к файлу или папке;
+smooth — включить сглаживание (TRUE или FALSE);
+horWrap — включить бесконечное повторение узора текстуры по горизонтали (TRUE или FALSE);
+vertWrap — включить бесконечное повторение узора текстуры по горизонтали (TRUE или FALSE).
+
+
Animation createAnimationFromGLTexId(unsigned int texid);
+
+
Создать однокадровую анимацию из текстуры OpenGL. Будьте внимательны, не удаляйте текстуру из OpenGL (glDeteteTextures) до тех пор пока существует хотя бы одна анимация её использующая. И более того анимация при своём удалении сама удалит эту текстуру из OpenGL. Если вы создали несколько анимаций с одной и той же текстурой, то текстура будет удалена при удалении последней использующей её анимации. Вы можете отключить автоматическое удаление текстуры обратившись к функции animationGLTexIdSetOwnership.
+
+
Настройки повторения узора текстуры и сглаживания уже содержатся в текстуре OpenGL.
Animation createAnimationFromImage(int width, int height, const void *pixels, int wrap);
+
+
Создать однокадровую анимацию из изображения в памяти. Пиксели должны идти один за другим по строкам сверху вниз, слева на право. По 4 байта на пиксель, по одному байту на каждый из каналов: красный, зелёный, синий, альфа каналы, именно в таком порядке. При загрузке создаётся копия текстуры в видеопамяти, и исходные данные больше не требуются, их можно выгрузить из памяти.
width — ширина изображения;
+height — высота изображения;
+pixels — указатель на первый байт первого пикселя в формате RGBA32;
+wrap — включить бесконечное повторение узора текстуры во всех направлениях (TRUE или FALSE).
+
+
Animation createAnimationFromImageEx(int width, int height, const void *pixels, int horWrap, int vertWrap, int smooth, int mipMap);
+
+
Создать однокадровую анимацию из изображения в памяти. Пиксели должны идти один за другим по строкам сверху вниз, слева на право. По 4 байта на пиксель, по одному байту на каждый из каналов: красный, зелёный, синий, альфа каналы, именно в таком порядке. При загрузке создаётся копия текстуры в видеопамяти, и исходные данные больше не требуются, их можно выгрузить из памяти.
+
+
Вы можете включить или выключить бесконечное повторение узора текстуры по горизонтали и/или вертикали (параметры horWrap и vertWrap соответственно).
+
+
Также вы можете включить сглаживание пикселей изображения (smooth) и включить построение mip-уровней (mipMap). Если вы пока не знаете, что такое mip-уровни, то просто включайте их всегда, когда нужно сглаживание и выключайте, когда сглаживание не нужно. Если же вы не знаете требуется или нет вам сглаживание текстуры, то ответ один — требуется — включайте и сглаживание и mip-уровни.
width — ширина изображения;
+height — высота изображения;
+pixels — указатель на первый байт первого пикселя в формате RGBA32;
+horWrap — включить бесконечное повторение узора текстуры по горизонтали (TRUE или FALSE);
+vertWrap — включить бесконечное повторение узора текстуры по вертикали (TRUE или FALSE);
+smooth — включить сглаживание (TRUE или FALSE);
+mipMap — включить построение mip-уровней (TRUE или FALSE).
Создать новую динамическую текстуру связанную с заданным буфером кадра. Содержимое этой текстуры будет изменяться всякий раз когда вы рисуете в этом буфере кадра. Мгновенно, без каких либо дополнительных затрат на копирование. Дополнительную информацию смотрите в разделе «Буфер кадра».
+
+
Не удаляйте буфер кадра пока не удалите все связанные с ним анимации.
+
+
Если вам нужно зафиксировать именно копию текущего состояния буфера кадра, то используйте функцию createAnimationFromViewport в сочетании с функцией target.
+
+
Параметры:
+
+
framebuffer — буфер кадра.
+
+
Animation createAnimationFromViewport();
+
+
Создать новую текстуру (однокадровую анимацию) скопировав изображение с экрана.
+
+
Если точнее — из текущей области вывода OpenGL (glViewport) — обычно это и есть вся площадь окна. Но если вы переключили буфер кадра функцией target, то текстура будет взята из этого буфера кадра.
+
+
Текстура создаётся с выключенным повтором узора, но со включенным сглаживанием и mip-уровнями.
Animation createAnimationFromViewportEx(int horWrap, int vertWrap, int smooth, int mipMap);
+
+
Функция работает аналогично функции createAnimationFromViewport, но позволяет вам задать повторения узора текстуры по горизонтали и/или вертикали (параметры horWrap, vertWrap) и включить или выключить сглаживание (smooth) и mip-уровни. Подробнее обо всех этих параметрах смотрите в описании функции createAnimationFromImageEx.
+
+
Параметры:
+
+
horWrap — включить бесконечное повторение узора текстуры по горизонтали (TRUE или FALSE);
+vertWrap — включить бесконечное повторение узора текстуры по вертикали (TRUE или FALSE);
+smooth — включить сглаживание (TRUE или FALSE);
+mipMap — включить построение mip-уровней (TRUE или FALSE).
+
+
Animation createAnimationEmpty();
+
+
Создать пустую анимацию — анимацию с нулевым количеством кадров. См. также animationInsert.
+
+
void animationDestroy(Animation animation);
+
+
Удалить анимацию.
+
+
Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на анимацию. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на анимацию, анимацию уже удалена. Вы можете занести в эту переменную другую анимацию, но использовать старое значение переменной больше нельзя это приведёт к ошибкам и непредсказуемому поведению программы.
+
+
Animation animationClone(Animation animation);
+
+
Создать копию анимации, которая будет иметь собственные параметрами позиции воспроизведения и частоты кадров. Функция не размножает копии изображений в оперативной памяти — все клоны ссылаются на одни те же изображения. Библиотека Helianthus контролирует сколько анимаций используют конкретный кадр в данный момент времени и выгружают этот кадр из памяти только тогда, когда удалена последняя анимация его использовавшая.
Animation animationCloneEx(Animation animation, int start, int count);
+
+
Создать копию анимации, которая будет иметь собственные параметрами позиции воспроизведения и частоты кадров. При помощи параметров start и count вы выбираете какие именно кадры из заданной анимации будут скопированы в новую анимацию. См. также animationClone, animationInsert.
+
+
Параметры:
+
+
start — порядковый номер кадра с которого нужно начать копирование (нумерация от нуля);
+count — количество кадров, которое нужно скопировать.
+
+
unsigned int animationGetGLTexId(Animation animation);
frame — порядковый номер кадра с для которого нужно получить идентификатор (нумерация от нуля);
+
+
void animationGLTexIdSetOwnership(unsigned int texid, int own);
+
+
Функция задаёт правила удаления текстуры с заданным идентификатором из OpenGL. Определяет кто является владельцем текстуры — библиотека Helianthus или ваша собственная программа. Если текстурой владеет Helianthus (own — TRUE), то текстуру из OpenGL удалит Helianthus сам в том момент когда ни одна анимация больше не будет на неё ссылаться. В противном случае вы сами должны позаботиться об удалении текстуры, проконтролировав при этом, что ни одна анимация больше эту текстуру не использует.
+
+
Используйте эту функцию если, например, вы не хотите чтобы Helianthus удалил из памяти вашу собственную текстуру, которую вы ему передали через функцию createAnimationFromGLTexId.
+
+
Параметры:
+
+
texid — внутренный идентификатор текстуры OpenGL;
+own — если TRUE, то об удалении текстуры из видео-памяти позаботится Helianthus, если FALSE, то удалить текстуру должена будет ваша программа.
+
+
int animationGetFramesCount(Animation animation);
+
+
Возвращает количество кадров в данной анимации.
+
+
void animationInsert(Animation animation, int index, Animation other);
+
+
Вставить все кадры из анимации other в заданную анимацию, таким образом, что бы вновь вставленные кадры начинались с номера index.
+
+
Функция не затирает старые кадры, а вставляет новые прямо в середину анимации, сдвигая при этом последние кадры.
index — определяет место (номер кадра, нумерация от нуля) в текущей анимации куда нужно вставить новые кадры;
+other — другая анимация кадры из которой нужно вставить в текущую.
+
+
void animationInsertEx(Animation animation, int index, Animation other, int start, int count);
+
+
Вставить некоторое количество подряд идущих кадров из анимации other в заданную анимацию, таким образом, что бы вновь вставленные кадры начинались с номера index.
+
+
Функция не затирает старые кадры, а вставляет новые прямо в середину анимации, сдвигая при этом последние кадры.
index — определяет место (номер кадра, нумерация от нуля) в текущей анимации куда нужно вставить новые кадры;
+other — другая анимация кадры из которой нужно вставить в текущую;
+start — номер вставляемого первого кадра из другой анимации;
+count — количество кадров для вставки.
+
+
void animationRemove(Animation animation, int start, int count);
+
+
Удалить некоторое количество (count) кадров из анимации начиная с кадра номер start.
+См. также animationInsert, animationClear.
+
+
Параметры:
+
+
start — номер первого удаляемого кадра (нумерация с нуля);
+count — количество кадров для вставки.
Возвращает TRUE если воспроизведение в данный момент включено и FALSE если выключено. См. также animationPlay, animationPause.
+
+
void animationPlay(Animation animation);
+
+
Включает воспроизведение анимации. Внутренний счётчик времени будет автоматически обновляться библиотекой Helianthus между вызовами функции перерисовки кадра (worldSetDraw).
Возвращает TRUE если анимация зациклена и FALSE если нет. См. также animationSetLoop.
+
+
void animationSetLoop(Animation animation, int loop);
+
+
Функция включает (loop - TRUE) и отключает (loop - FALSE) циклическое воспроизведение анимации, когда анимация повторяется снова и снова, вместо того чтобы остановиться на последнем кадре. См. также animationGetLoop, animationPlay.
+
+
double animationGetPos(Animation animation);
+
+
Возвращает текущую позицию анимации в секундах. См. также animationSetPos.
int imageLoad(const char *path, int *outWidth, int *outHeight, unsigned char **outPixels);
+
+
Функция загружает изображение из файла PNG. Возвращает TRUE если загрузка прошла успешно и FALSE если загрузить файл не удалось.
+
+
В результате загрузки в переменные по адресам outWidth и outHeight будут помещены соответственно ширина и высота картинки. В переменную по адресу outPixels будет помещён указатель на пиксели картинки. Пиксели записываются в формате RGBA32 — для каждого пикселя последовательно идут 4 байта отвечающие за интенсивность каждой цветовой составляющей — красный, зелёный, синий, непрозрачность (alpha) — именно в таком порядке. Пиксели записаны по строкам сверху вниз, слева на право.
Функция, в случае успешной загрузки изображения, динамически выделяет память под пиксели, и, вам после использования нужно эту память освободить обратившись к стандартной функции free.
+
+
В случае если загрузка не удалась в качестве ширины и высоты будет записан ноль, в качестве указателя на пиксели будет записан нулевой указатель — NULL.
path — путь к файлу изображения;
+outWidth — указатель на переменную куда будет записана ширина загруженного изображения в пикселях;
+outHeight — указатель на переменную куда будет записана высота загруженного изображения в пикселях;
+outPixels — указатель на переменную куда будет записан указатель на массив пикселей изображения.
+
+
int imageLoadFromMemory(const void *data, int size, int *outWidth, int *outHeight, unsigned char **outPixels);
+
+
Загрузить изображение из данных файла PNG ранее загруженных в оперативную память.
+
+
Эта функция может быть вам полезна если вы хотите хранить все ваши изображения прямо внутри исполняемого файла. Например, при помощи утилиты xxd (в Linux) или подобной ей для вашей операционной системы, вы можете сгенерировать файл на языке Си с массивом содержащим все байты файла изображения. Данная функция позволит вам распаковать изображения из этого массива и получить доступ к его пикселям.
+
+
Возвращает TRUE если загрузка прошла успешно и FALSE если распаковать изображение не удалось.
data — указатель на первый байт данных PNG;
+size — количество байт данных PNG;
+outWidth — указатель на переменную куда будет записана ширина загруженного изображения в пикселях;
+outHeight — указатель на переменную куда будет записана высота загруженного изображения в пикселях;
+outPixels — указатель на переменную куда будет записан указатель на массив пикселей изображения.
+
+
int imageSave(const char *path, int width, int height, const void *pixels);
+
+
Функция сохраняет изображение в файл PNG по заданному пути. Возвращает TRUE при успешном сохранении и FALSE если сохранить изображение не удалось.
Важно: Если файл по указанному пути уже существует, то он будет перезаписан. Вы может проверить существование файла функцией fileExists.
+
+
Параметры:
+
+
path — путь к файлу в который нужно записать изображение;
+width — ширина изображения в пикселях;
+height — высота изображения в пикселях;
+pixels — указатель на массив пикселей изображения, формат смотрите в описании к функции imageLoad.
+
+
unsigned int imageToGLTexture(int width, int height, const void *pixels, int wrap);
+
+
Загрузить изображение в текстуру OpenGL. В случае успешной функция возвращает идентификатор текстуры OpenGL, и возвращает ноль если загрузка не удалась.
+
+
Во время загрузки создаётся копия данных изображения в видео-памяти и оригинальное изображение можно выгрузить из памяти.
width — ширина изображения в пикселях;
+height — высота изображения в пикселях;
+pixels — указатель на массив пикселей изображения, формат смотрите в описании к функции imageLoad;
+wrap — если TRUE то узор текстуры будет повторяющимся по горизонтали и вертикали.
+
+
unsigned int imageToGLTextureEx(int width, int height, const void *pixels, int horWrap, int vertWrap, int smooth, int mipMap);
+
+
Загрузить изображение в текстуру OpenGL. В случае успешной функция возвращает идентификатор текстуры OpenGL, и возвращает ноль если загрузка не удалась.
+
+
Во время загрузки создаётся копия данных изображения в видео-памяти и оригинальное изображение можно выгрузить из памяти.
+
+
Вы можете включить или выключить бесконечное повторение узора текстуры по горизонтали и/или вертикали (параметры horWrap и vertWrap соответственно). Также вы можете включить сглаживание пикселей изображения (smooth, билинейная или трилинейная фильтрация) и включить построение mip-уровней (mipMap).
width — ширина изображения в пикселях;
+height — высота изображения в пикселях;
+pixels — указатель на массив пикселей изображения, формат смотрите в описании к функции imageLoad;
+horWrap — включить бесконечное повторение узора текстуры по горизонтали (TRUE или FALSE);
+vertWrap — включить бесконечное повторение узора текстуры по вертикали (TRUE или FALSE);
+smooth — включить сглаживание (TRUE или FALSE);
+mipMap — включить построение mip-уровней (TRUE или FALSE).
+
+
int imageToExistingGLTexture(unsigned int texid, int width, int height, const void *pixels);
+
+
Заменить пиксели существующей текстуры. Возвращает TRUE в случае успеха, иначе FALSE.
texid — идентификатор существующей текстуры OpenGL;
+width — ширина изображения в пикселях;
+height — высота изображения в пикселях;
+pixels — указатель на массив пикселей изображения, формат смотрите в описании к функции imageLoad.
+
+
int imageFromGLTexture(unsigned int texid, int *outWidth, int *outHeight, unsigned char **outPixels);
+
+
Получить пиксели из текстуры OpenGL. Пиксели копируются в новый массив, память для которого выделяется динамически. Поэтому вам, также как при работе с imageLoad, нужно после использования освободить выделенную под пиксели память при помощи стандартной функции free.
+
+
Функция возвращает TRUE в случае успеха, иначе FALSE.
texid — идентификатор текстуры OpenGL;
+outWidth — указатель на переменную куда будет записана ширина загруженного изображения в пикселях;
+outHeight — указатель на переменную куда будет записана высота загруженного изображения в пикселях;
+outPixels — указатель на переменную куда будет записан указатель на массив пикселей изображения.
+
+
int imageFromViewport(int *outWidth, int *outHeight, unsigned char **outPixels);
+
+
Получить пиксели изображения из текущей области вывода OpenGL. Пиксели копируются в новый массив, память для которого выделяется динамически. Поэтому вам, также как при работе с imageLoad, нужно после использования освободить выделенную под пиксели память при помощи стандартной функции free.
+
+
Функция возвращает TRUE в случае успеха, иначе FALSE.
outWidth — указатель на переменную куда будет записана ширина загруженного изображения в пикселях;
+outHeight — указатель на переменную куда будет записана высота загруженного изображения в пикселях;
+outPixels — указатель на переменную куда будет записан указатель на массив пикселей изображения.
+
+
int viewportSave(const char *path);
+
+
Сохранить изображение из текущей области рисования OpenGL в файл. Обычно используется чтобы сделать снимок экрана (сохраняется только внутренняя область окна программы).
+
+
Функция возвращает TRUE в случае успеха, иначе FALSE.
width — ширина изображения в пикселях;
+height — высота изображения в пикселях;
+pixels — указатель на массив пикселей изображения, формат смотрите в описании к функции imageLoad;
+x, y — координаты пикселя.
+
+
void imageSetPixel(int width, int height, void *pixels, int x, int y, unsigned int colorCode);
width — ширина изображения в пикселях;
+height — высота изображения в пикселях;
+pixels — указатель на массив пикселей изображения, формат смотрите в описании к функции imageLoad;
+x, y — координаты пикселя,
+colorCode — код цвета.
Камера позволяет вам перемещать позицию обзора и масштаб при рисовании спрайтов. При использовании камеры вам не надо изменять позицию всех спрайтов чтобы имитировать смену точки обзора.
+
Буфер кадра позволяет вам рисовать не только на экране, но и прямо на текстуре в видео-памяти применяя при этом те же функции рисования.
-
Для работы с камерой её нужно включить функцией cameraOn,
+
Создать буфер кадра можно функцией createFramebuffer, которая возвращает значение типа Framebuffer, которое по сути является адресом в памяти — указателем на описание буфера кадра внутри библиотеки Helianthus. Количество буферов кадра с которыми вы можете одновременно работать и их максимальные размеры зависят от вашего видео-драйвера.
После создания буфера кадра в можете создать связанную с ним однокадровую анимацию при помощи функции createAnimationFromFramebuffer. Это будет не простая анимация — изображение в ней анимации будет изменяться как только вы что-либо нарисуете на вашем буфере кадра.
-
Камера действует только на отображение спрайтов, на прочие функции рисования она не влияет.
+
Для того чтобы начать рисовать на буфере кадра вам нужно вызвать функцию target. После завершение рисования вы можете снова вернуться к рисованию на экране обратившись к функции noTarget.
Функции:
-
void cameraOn();
+
Framebuffer createFramebuffer(int width, int height);
-
Включить камеру. Спрайты будут рисоваться с учётом положения камеры.
+
Создаёт буфер кадра заданных размеров со включенным сглаживанием, но с выключенным повторением текстуры по горизонтали и вертикали. См. также createFramebufferEx, createAnimationFromFramebuffer, target.
-
void cameraOff();
+
Параметры:
-
Выключить камеру. Спрайты будут рисоваться как обычно — без учёта положения камеры.
+
width — ширина нового буфера кадра в пикселях;
+height — высота нового буфера кадра в пикселях.
-
int cameraIsActive();
+
Framebuffer createFramebufferEx(int width, int height, const void *pixels, int horWrap, int vertWrap, int smooth);
-
Возвращает TRUE если камера включена или FALSE если выключена. См. также cameraOn, cameraOff.
Данные функции возвращают координаты мыши с учётом текущего положения камеры. См. также mouseX, mouseY.
+
width — ширина нового буфера кадра в пикселях;
+height — высота нового буфера кадра в пикселях;
+pixels — указатель на массив пикселей (смотрите формат в описании функции imageLoad), которые зададут начальное изображение буфера кадра; этот параметр может быть NULL, буфер будет заполнен прозрачными писелями;
+horWrap — включить горизонтальное повторение для текстуры созданной на основе буфера кадра (TRUE или FALSE);
+vertWrap — включить вертикальное повторение для текстуры созданной на основе буфера кадра (TRUE или FALSE);
+smooth — включить сглаживание (билинейная фильтрация) для текстуры созданной на основе буфера кадра (TRUE или FALSE).
Создать буфер кадра на основе изображения загруженного из файла. Размеры буфера будут соответствовать размеру изображения и само изображение будет загружено в буфер кадра в качестве его начального состояния. Будет включено сглаживание, но отключено повторение узора текстуры по горизонтали и вертикали.
Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на буфер кадра. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на буфер кадра, буфер удалён. Вы можете занести в эту переменную другой буфер кадра, но использовать старое значение переменной больше нельзя это приведёт у ошибкам и непредсказуемому поведению программы.
+
+
void framebufferFlush(Framebuffer framebuffer);
+
+
Видео-драйвер обычно выполняет рисование не в тот момент, когда вы отправляете соответствующую команду, а откладывает этот процесс до тех под пока операционная система не затребует отобразить результат рисования на экране.
+
+
Данная функция заставляет видео-драйвер завершить все операции немедленно. Обычно вам не нужно будет её использовать, везде где это требуется Helianthus сделает это за вас. Однако, эта функция вам может понадобиться если вы используете функции OpenGL напрямую, минуя функции рисования библиотеки Helianthus.
Устанавливает матрицу проекции OpenGL таким образом, чтобы начало координат было в верхнем левом углу области вывода OpenGL, а единичный отрезок соответствовал размеру пикселя. См. также targetEx.
Устанавливает область вывода OpenGL на всю площадь заданного буфера кадра. См. также targetEx.
+
+
void viewportByWindow();
+
+
Устанавливает область вывода OpenGL на всю площадь окна. См. также targetEx.
+
+
void targetEx(Framebuffer framebuffer, int updateViewport, int updateProjection);
+
+
Устанавливает текущую область рисования. Если framebuffer не NULL, то рисование будет производиться на буфере кадра, иначе на окне. Параметры updateViewport и updateProjection позволяют вам отключить изменение области вывода OpenGL и матрици проекции соответственно. См. также target, noTarget, viewportByFramebuffer, viewportByWindow, projectionByViewport.
+
+
Параметры:
+
+
framebuffer — буфер кадра, если NULL, то окно программы будет выбрано в качестве целевого холста для рисования;
+updateViewport — задать область вывода OpenGL соответствующую новому целевому холсту (TRUE или FALSE, см. viewportByFramebuffer, viewportByWindow);
+updateProjection — задать матрицу проекции OpenGL соответствующую новой области вывода (TRUE или FALSE, см. projectionByViewport), игнорируется если updateViewport выключен.
+
+
void target(Framebuffer framebuffer);
+
+
Функция выбирает буфер кадра в качестве целевого холста для рисования. Последующие операции рисование будет проводиться на данном буфере кадра. Если вы будете работать с функциями OpenGL напрямую, минуя функции рисования Helianthus, то вам необходимо знать, что данная функция меняет область вывода (glViewport) и матрицу проекции OpenGL.
@@ -43,37 +45,31 @@ void draw() {
// несколько раз в секунду.
}
-void deinit() {
- // Команды внутри этой функции запустятся
- // только один раз в самом конце при завершении
- // работы программы.
-}
-
int main() {
worldSetInit(&init);
worldSetDraw(&draw);
- worldSetDeinit(&deinit);
worldRun();
return 0;
}
-
После завершения работы Helianthus (при окончании выполнения функции worldRun) все созданные вами объекты библиотеки будут удалены автоматически. Если вы хотите удалить что-то вручную, смотрите функции удаления для соответствующих объектов (spriteDestroy, groupDestroy, soundDestroy, fontDestroy, closeDirectory).
Изначально окно имеет фиксированный размер, который вы можете менять только из программы, командами указанными выше. Однако вы можете это изменить и разрешить пользователю изменять размер окна, смотрите функцию worldSetResizable.
Окно программы непрерывно перерисовывается с частотой 24 кадра в секунду. Частоту перерисовки вы можете поменять при помощи функции worldSetFrameRate.
-
Программа ведёт отсчёт времени и кадров с момента запуска вы можете получить значение этих счётчиков пи помощи функций worldGetSeconds и worldGetFrameCount. Длительность одного кадра можно узнать вызвав функцию worldGetTimeStep.
+
Программа ведёт отсчёт времени и кадров с момента запуска вы можете получить значение этих счётчиков пи помощи функций worldGetSeconds и worldGetFrameCount. Длительность одного кадра (длительность предыдущего отрисованного кадра) можно узнать вызвав функцию worldFrameTime.
Также Helianthus предоставляет некоторые общие функции которые не представлены в стандартном я зыке C:
- помощники в генерации случайных чисел (randomNumber, randomFloat);
+- функция поворота вектора rotateVector;
- функции для чтения папок (см. openDirectory);
- функции проверки существования файлов и папок — fileExists, directoryExists.
-- функции для создания всплывающие окна с текстовыми сообщениями (messageBox) и окон для ввода текста (askText, askTextEx).
width — новая ширина окна;
+height — новая высота окна.
int worldGetResizable();
@@ -150,7 +155,7 @@ void draw() {
void worldSetResizable(int resizable);
-
Включает или выключает возможность измерения размеров окна пользователем. Когда включено пользователь может менять размер окна растягивая его, хватаясь за границы, и, появляется кнопка для разворачивания окна на весь экран.
+
Включает или выключает возможность измерения размеров окна пользователем. Когда включено пользователь может менять размер окна растягивая его, хватаясь за границы, и, появляется кнопка для разворачивания окна на весь экран. Эту функцию можно вызывать до вызова worldRun.
Параметры:
@@ -162,27 +167,48 @@ void draw() {
void worldSetTitle(const char *title);
-
Установить заголовок окна.
+
Установить заголовок окна. Эту функцию можно вызывать до вызова worldRun.
Параметры:
title — новый заголовок окна.
-
double worldGetFrameRate();
-
-
Возвращает частоту перерисовки окна, количество кадров в секунду. См. также worldSetFrameRate.
Установить переменную частоту перерисовки окна. В этом режиме Helianthus будет стараться перерисовать окно как можно быстрее — но не быстрее заданной максимальной частоты. Реальная частота кадров будет зависеть от скорости компьютера. Если скорость компьютера и сложность рисуемой сцены не позволяют обеспечить даже минимальной частоты перерисовки, то Helianthus будет подменять реальное время имитируя для вашего приложения работу на скорости соответствующей минимальной частоте кадров — как результат происходящее на экране движение замедлится.
+
+
Казалось бы это очевидное поведение, но нет. В большинству программ, и, наверное, в вашей будущей программе тоже, скорость движения объектов связана со счётчиком времени. И если кадр будет рисоваться очень медленно — более секунды, то за время одного кадра движущийся объект может пройти очень большое расстояние. При этом пользователь будет лишён возможности как-то наблюдать за движением или повлиять на него. Будет лучше в этой ситуации замедлить движение объекта, но за то нарисовать несколько дополнительных кадров, показывающих промежуточные точки движения. Для этого и устанавливается минимальная частота кадров.
Возвращает длительность отрисовки предыдущего кадра в секундах. Для первого кадра возвращается расчётное значение длительности. См. также worldSetFrameRateEx.
int worldGetFrameCount();
@@ -190,7 +216,7 @@ void draw() {
double worldGetSeconds();
-
Возвращает количество секунд прошедшее с момента запуска программы (с момента вызова функции worldRun. См. также worldGetFrameCount.
+
Возвращает количество секунд прошедшее с момента запуска программы (с момента вызова функции worldRun. Это время может отставать от реального, если компьютер слишком медленно рисовал кадры. См. также worldSetFrameRateEx, worldGetFrameCount.
int randomNumber(int min, int max);
@@ -205,6 +231,16 @@ void draw() {
Возвращает случайное дробное число в диапазоне от 0 до 1.
Повернуть вектор (x, y) на угол angle. Функция принимает два указателя на координаты вектора, повёрнутый вектор записывается по указанным адресам вместо старого.
+
+
Параметры:
+
+
x — указатель на переменную хранящую координату x;
+y — указатель на переменную хранящую координату y;
+angle — угол поворота в градусах.
+
Directory openDirectory(const char *path);
Если папка существует, то функция читает список файлов в папке и сохраняет этот список в памяти. Возвращает значение типа Directory, которое является адресом в памяти — указателем на описание списка внутри библиотеки Helianthus.
@@ -272,9 +308,32 @@ if (dir) {
message — текстовое сообщение.
-
void askText(const char *question, char *answer, int maxAnswerSize);
+
int questionBox(const char *question, const char *answer0, const char *answer1);
+
+
Функция показывает на экране окно вопроса с двумя вариантами ответа. Работа программы будет приостановлена до тех пор пока пользователь не выберет один из вариантов или не закроет окно вопроса (что равносильно выбору варианта номер 0). Функция возвращает номер выбранного ответа — 0 или 1. См. также: messageBox, questionBox3.
+
+
Параметры:
+
+
question — текст задаваемого вопроса;
+answer0 — такст варианта ответа номер 0, этот вариант выбирается если пользователь закрывает окно вопроса или нажимает клавишу Esc. Удобно использовать с текстом «Нет» или «Отмена»;
+answer1 — текст варианта ответа номер 1, этот вариант выбирается по-умолчанию если пользователь нажимает клавишу Enter. Удобно использовать с текстом «Да» или «OK».
Функция показывает на экране окно вопроса с тремя вариантами ответа. Работа программы будет приостановлена до тех пор пока пользователь не выберет один из вариантов или не закроет окно вопроса (что равносильно выбору варианта номер 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. Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. См. также askTextEx.
+
Создаёт окно для ввода текста. Пользователю будет предоставлена для редактирования строка текста из параметра answer. Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. Возвращает TRUE (число 1) при успешном вводе и FALSE (число 0) если пользователь отменил ввод. См. также askTextEx.
Параметры:
@@ -282,9 +341,9 @@ if (dir) {
answer — указатель на строку куда будет сохранён ответ, также этот параметр используется чтобы задать начальное значение для текстового поля; maxAnswerSize — максимальный размер для строки ответа в байтах включая ограничивающий нулевой байт.
-
void askTextEx(const char *question, char *answer, int maxAnswerSize, int multiline, int password);
+
int askTextEx(const char *question, char *answer, int maxAnswerSize, int multiline, int password);
-
Создаёт окно для ввода текста. Пользователю будет предоставлен для редактирования текст из параметра answer. Позволяет работать с многострочным текстом и прятать вводимые символы (для ввода пароля). Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. См. также askText.
+
Создаёт окно для ввода текста. Пользователю будет предоставлен для редактирования текст из параметра answer. Позволяет работать с многострочным текстом и прятать вводимые символы (для ввода пароля). Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. Возвращает TRUE (число 1) при успешном вводе и FALSE (число 0) если пользователь отменил ввод. См. также askText.
Перечисленные ниже функцию позволяют рисовать на экране различные фигуры и текст.
+
Перечисленные ниже функции позволяют рисовать на экране различные фигуры и текст.
-
Для указания цвета используется его текстовое наименование.
-Вот список наименований:
+
Для указания цвета используется его числовой код. Код можно записать в виде шестнадцатеричного числа, например: 0xFF0000AA — это полупрозрачный красный (также как #FF0000AA в формате web). Однако проще всего получить код используя вспомогательные функции: colorByName, colorByRGB, colorByHSV, colorByYUV, а также их аналоги с альфа-каналом: colorByNameA, colorByRGBA, colorByHSVA, colorByYUVA.
Для рисования линий и многоугольников используются функции moveTo, lineTo, closePath, strokePath. При этом функции stroke и fill задают цвет линий и заливки. Функция strokeWeight задаёт толщину линий. Вот пример рисования красного треугольника с чёрным контуром:
Также существуют отдельные функции для рисования точек (point), линий (line), прямоугольников (rect), правильных многоугольников (regularPolygon), эллипсов (ellipse) и дуг окружности (arc), смотрите описания функций ниже.
+
+
Для очистки экрана используйте функцию clear. Функция background задаёт цвет фона — функция clear закрасит все пиксели именно этим цветом. Обратите внимание, что перед рисованием очередного кадра картинка полностью затирается цветом фона. Если вам необходимо сохранять картинку, то вам либо придётся повторить все операции рисования выполненные ранее или обратиться к разделам «Буфер кадра» и «Текстуры и анимация», чтобы узнать, как можно рисовать не на экран, а в текстуру.
+
+
Для рисования текста см. раздел «Шрифты и текст».
+
+
Трансформации и прочие преобразования
+
+
Перед рисованием вы можете сместить, повернуть или растянуть выводимое изображение при помощи функций соответственно: translate, rotate и scale. Таким образом вы можете как бы изменить позицию камеры. Отменить все вышеуказанные трансформации можно вызвав функцию noTransform. Указанные функции меняют текущую матрицу OpenGL, если вы знакомы с OpenGL, то можете менять матрицы напрямую — на работу Helianthus это не повлияет.
+
+
Также вы можете ограничить область рисования задав прямоугольник отсечения — cliprect.
+
+
Также обратите внимание на функции saveState и restoreState. Они позволяют соответственно сохранить действующие в данный момент преобразование и затем вернуться к сохранённому состоянию.
Helianthus использует библиотеку OpenGL для рисования. Вы тоже можете использовать функции OpenGL в своих программах. Helianthus спроектирована так чтобы минимально влиять на состояние OpenGL, так чтобы вы могли полноценно использовать все функции библиотеки OpenGL, если вы того захотите. Например, если вы вызвали функцию translate, то изменится только текущая матрица OpenGL, обычно, это матрица модели.
+
+
Вы можете также использовать рисование в 3D, в этом случае, если вы обратитесь к 2D функциям Helianthus — они будут выполнены в плоскости XY и координата Z будет принята равной нулю.
+
+
Функции:
+
+
unsigned int colorByName(const char *colorName);
+
+
Функция генерирует код цвета по его текстовому наименованию.
+
+
Вот список наименований: "transparent", "black", "white",
@@ -46,89 +94,191 @@
#0000ff — синий;
#00ff00aa — зелёный полупрозрачный.
-
Вы можете сгенерировать текстовое наименования для любого цвета по его числовым составляющим при помощи функций rgb и rgba.
+
Параметры:
-
Для рисования линий и многоугольников используются функции moveTo, lineTo, closePath, strokePath. При этом функции stroke и fill задают цвет линий и заливки. Функция strokeWeight задаёт толщину линий. Вот пример рисования красного треугольника с чёрным контуром:
unsigned int colorByNameA(const char *colorName, double a);
+
Генерирует код цвета по его текстовому наименованию с применением прозрачности (alpha). См. также colorByName. Если в текстовом наименовании уже заключён цвет с прозрачностью (alpha) то значения альфа-канала будут перемножены.
-
Также существуют отдельные функции для рисования прямоугольников, линий, эллипсов и дуг окружности, смотрите описания функций ниже.
+
Параметры:
-
Для вывода текста используются функции text, textAlign, textFontFamily и textSize. Смотрите их описание ниже. Вы можете загружать собственные шрифты из файлов (TrueType или OpenType) при помощи функций createFont и textFont.
+
colorName — текстовое наименование цвета;
+a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.
-
Функции:
+
unsigned int colorByRGB(double r, double g, double b);
+
+
Генерирует код цвета по трём цветовым составляющим — красный, зелёный, синий. Генерируется полностью непрозрачный цвет (альфа-канал равен 1). См. также colorByRGBA.
+
+
Параметры:
+
+
r — красная составляющая, от 0 до 1;
+g — зелёная составляющая, от 0 до 1;
+b — синяя составляющая, от 0 до 1.
-
void background(const char *color);
+
unsigned int colorByRGBA(double r, double g, double b, double a);
-
Установить цвет фона. Начиная со следующего все кадры будут рисоваться на выбранном фоне.
+
Генерирует код цвета по трём цветовым составляющим — красный, зелёный, синий — и прозрачности — альфа-канал. См. также colorByRGB.
Параметры:
-
color — текстовое наименование цвета.
+
r — красная составляющая, от 0 до 1;
+g — зелёная составляющая, от 0 до 1;
+b — синяя составляющая, от 0 до 1;
+a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.
-
void fill(const char *color);
+
unsigned int colorByHSV(double h, double s, double v);
-
Установить цвет заливки. После вызова этой функции все фигуры будут заполняться выбранным цветом. См. также noFill.
+
Генерирует код цвета по трём составляющим в системе HSV — оттенок (hue), цветность (saturation), яркость (value). Генерируется полностью непрозрачный цвет (альфа-канал равен 1). См. также colorByHSVA.
Параметры:
-
color — текстовое наименование цвета.
+
h — оттенок (hue) в градусах на цветовом круге, обычно от 0 до 360;
+s — цветность (saturation), от 0 до 1;
+v — яркость, от 0 до 1.
-
void noFill();
+
unsigned int colorByHSVA(double h, double s, double v, double a);
+
+
Генерирует код цвета по трём составляющим в системе HSV — оттенок (hue), цветность (saturation), яркость (value) — и прозрачности (alpha). См. также colorByHSV.
-
Отключить заливку фигур. После вызова этой функции все фигуры будут рисоваться без заполнения. См. также fill.
+
Параметры:
-
void stroke(const char *color);
+
h — оттенок (hue) в градусах на цветовом круге, обычно от 0 до 360;
+s — цветность (saturation), от 0 до 1;
+v — яркость, от 0 до 1;
+a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.
-
Установить цвет контура. После вызова этой функции все фигуры будут рисоваться с контуром выбранного цвета. Также эта функция задаёт цвет рисования текста См. также noStroke.
+
unsigned int colorByYUV(double y, double u, double v);
+
+
Генерирует код цвета по трём составляющим в системе YUV. Генерируется полностью непрозрачный цвет (альфа-канал равен 1). См. также colorByYUVA.
Параметры:
-
color — текстовое наименование цвета.
+
y — яркость, от 0 до 1;
+u — цветоразностный компонент U, от -1 до 1;
+v — цветоразностный компонент V, от -1 до 1.
-
void noStroke();
+
unsigned int colorByYUVA(double y, double u, double v, double a);
-
Отключить рисование контура. После вызова этой функции все фигуры будут рисоваться без прорисовки контура. См. также stroke.
+
Генерирует код цвета по трём составляющим в системе YUV и прозрачности. См. также colorByYUV.
-
Важно: Так как текст рисуется цветом контура, эта функция полностью отключает вывод текста.
+
Параметры:
+
+
y — яркость, от 0 до 1;
+u — цветоразностный компонент U, от -1 до 1;
+v — цветоразностный компонент V, от -1 до 1;
+a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.
+
+
double colorGetRed(unsigned int colorCode);
+
+
Возвращает красную составляющую цвета. См. также colorByRGBA.
+
+
double colorGetGreen(unsigned int colorCode);
+
+
Возвращает зелёную составляющую цвета. См. также colorByRGBA.
+
+
double colorBlueRed(unsigned int colorCode);
+
+
Возвращает синюю составляющую цвета. См. также colorByRGBA.
+
+
double colorGetAlpha(unsigned int colorCode);
+
+
Возвращает степень непрозрачности цвета — альфа-канал. См. также colorByRGBA.
+
+
double colorGetHue(unsigned int colorCode);
+
+
Возвращает цветовой оттенок в градусах на цветовом круге, от 0 до 360 в системе HSV. См. также colorByHSV.
+
+
double colorGetSaturation(unsigned int colorCode);
+
+
Возвращает цветность (цветовую насыщенность) для выбранного цвета в системе HSV. См. также colorByHSV.
+
+
double colorGetValue(unsigned int colorCode);
+
+
Возвращает яркость для выбранного цвета в системе HSV. См. также colorByHSV.
+
+
double colorGetYLuminance(unsigned int colorCode);
+
+
Возвращает яркость для выбранного цвета в системе YUV. См. также colorByYUV.
+
+
double colorGetUChromanance(unsigned int colorCode);
+
+
Возвращает цветоразностный компонент U для выбранного цвета в системе YUV. См. также colorByYUV.
+
+
double colorGetVChromanance(unsigned int colorCode);
-
void strokeWeight(double weight);
+
Возвращает цветоразностный компонент V для выбранного цвета в системе YUV. См. также colorByYUV.
-
Установить толщину линий и контуров. После вызова этой функции все линии и контуры будут рисоваться с заданной толщиной.
+
void background(unsigned int colorCode);
+
+
Установить цвет фона. Начиная со следующего все кадры будут рисоваться на выбранном фоне. Также влияет на поведение функции clear.
Параметры:
-
weight — толщина линии.
+
colorCode — код цвета.
+
+
void clear();
-
const char* rgb(double r, double g, double b);
+
Заполняет все пиксели цветом фона. См. также background.
-
Функция возвращает текстовое наименование цвета для заданных числовых значений яркости красной, зелёной и синей составляющих.
+
void fill(unsigned int colorCode);
-
Параметры:
+
Установить цвет заливки. После вызова этой функции все фигуры будут заполняться выбранным цветом. См. также stroke, noFill и fillTexture.
-
r — яркость красной составляющей цвета, дробное число от 0 до 1;
-g — яркость зелёной составляющей цвета, дробное число от 0 до 1;
-b — яркость синей составляющей цвета, дробное число от 0 до 1.
Функция возвращает текстовое наименование цвета для заданных числовых значений яркости красной, зелёной и синей составляющих, а также прозрачности.
+
void fillTexture(Animation animation, double x, double y, double width, diuble height, int fixed);
+
+
Установить заливку текстурой. После вызова этой функции все фигуры будут заполняться выбранной текстурой. Для заливки текстурой определяется базовый прямоугольник (по координатам x, y, width, height) в который будет смасштабировано изображение текстуры. Если текстура повторяющаяся, то её копии будут распространяться и за пределами базового прямоугольника. При помощи параметра fixed вы можете зафиксировать базовый прямоугольник текстуры в текущих координатах так, что на них в не будут влиять последующие трансформации перемещения (translate), вращения (rotate) и масштабирования (scale и zoom). См. также fill, noFill и раздел «Текстуры и анимация».
Параметры:
-
r — яркость красной составляющей цвета, дробное число от 0 до 1;
-g — яркость зелёной составляющей цвета, дробное число от 0 до 1;
-b — яркость синей составляющей цвета, дробное число от 0 до 1;
-a — прозрачность, дробное число от 0 до 1, при этом 0 — цвет полностью прозрачный, 1 — цвет непрозрачный.
+
animation — анимированная или статическая текстура;
+x, y — координаты верхнего левого угла базового прямоугольника текстуры;
+width — ширина базового прямоугольника текстуры;
+height — ширина базового прямоугольника текстуры;
+fixed — если TRUE (1 или любое другое число кроме 0), то фиксирует прямоугольник текстуры в текущих координатах — операции трансформации на него не влияют.
+
+
void noFill();
+
+
Отключить заливку фигур. После вызова этой функции все фигуры будут рисоваться без заполнения. См. также fill, fillTexture, saveState и restoreState.
+
+
void stroke(unsigned int colorCode);
+
+
Установить цвет контура. После вызова этой функции все фигуры будут рисоваться с контуром выбранного цвета. Также эта функция задаёт цвет рисования текста. См. также fill, noStroke. и раздел «Шрифты и текст».
+
+
Параметры:
+
+
colorCode — код цвета.
+
+
void strokeTexture(Animation animation, double x, double y, double width, diuble height, int fixed);
+
+
Установить заливку текстурой для контура. После вызова этой функции все фигуры будут заполняться выбранной текстурой. Для заливки текстурой определяется базовый прямоугольник (по координатам x, y, width, height) в который будет смасштабировано изображение текстуры. Если текстура повторяющаяся, то её копии будут распространяться и за пределами базового прямоугольника. При помощи параметра fixed вы можете зафиксировать базовый прямоугольник текстуры в текущих координатах так, что на них в не будут влиять последующие трансформации перемещения (translate), вращения (rotate) и масштабирования (scale и zoom). См. также stroke, noStroke и раздел «Текстуры и анимация».
+
+
Параметры:
+
+
animation — анимированная или статическая текстура;
+x, y — координаты верхнего левого угла базового прямоугольника текстуры;
+width — ширина базового прямоугольника текстуры;
+height — ширина базового прямоугольника текстуры;
+fixed — если TRUE (1 или любое другое число кроме 0), то фиксирует прямоугольник текстуры в текущих координатах — операции трансформации на него не влияют.
+
+
void noStroke();
+
+
Отключить рисование контура. После вызова этой функции все фигуры будут рисоваться без прорисовки контура. См. также stroke, strokeTexture, saveState и restoreState.
+
+
Важно: Так как текст рисуется цветом контура, эта функция полностью отключает вывод текста.
+
+
void strokeWidth(double width);
+
+
Установить толщину линий и контуров. После вызова этой функции все линии и контуры будут рисоваться с заданной толщиной. Изначально толщина равна 1.
+
+
Параметры:
+
+
width — толщина линии.
void moveTo(double x, double y);
@@ -166,6 +316,17 @@ closePath();
width — ширина прямоугольника; height — высота прямоугольника.
+
Нарисовать прямоугольник и заполнить его выбранной текстурой. Цвет контура задаётся заранее функцией stroke. См. также функции rect, fillTexture, strokeTexture и раздел «Текстуры и анимация».
+
+
Параметры:
+
+
animation — анимированная или статическая текстура;
+x, y — координаты левого верхнего угла прямоугольника;
+width — ширина прямоугольника;
+height — высота прямоугольника.
+
void ellipse(double x, double y, double width, double height);
Нарисовать эллипс. Эллипс рисуется таким чтобы от вписался в ограничивающий прямоугольник (см. функцию rect). Следовательно для того чтобы нарисовать окружность нужно передать одинаковую ширину и высоту ограничивающего прямоугольника. Цвета заполнения и контура задаются заранее функциями fill и stroke.
@@ -180,7 +341,7 @@ closePath();
Нарисовать дугу эллипса заданного ограничивающим прямоугольником. Дуга задаётся значением начального и конечного угла. Цвет линии задаётся функцией stroke.
-
Параметры:
+
Параметры:
x, y — координаты левого верхнего угла ограничивающего прямоугольника; width — ширина ограничивающего прямоугольника;
@@ -204,14 +365,14 @@ closePath();
Провести прямую линию от первой указанной точки до второй. Цвет линии задаётся функцией stroke.
-
Параметры:
+
Параметры:
x1, y1 — координаты первой точки; x2, y2 — координаты второй точки.
void point(double x, double y);
-
Нарисовать точку в указанных координатах. Цвет задаётся функцией stroke. Диаметр точки задаётся функцией strokeWeight.
+
Нарисовать точку в указанных координатах. Цвет задаётся функцией stroke. Диаметр точки задаётся функцией strokeWidth.
Параметры:
@@ -221,81 +382,147 @@ closePath();
Нарисовать правильный многоугольник заданного размера с центром в указанной точке. Цвета заполнения и контура задаются функциями fill и stroke.
-
Параметры:
+
Параметры:
x, y — координаты центра многоугольника; sides — количество сторон; size — размер многоугольника — диаметр описанной окружности.
-
void text(const char *text, double x, double y);
-
-
Вывести текст в заданной точке. Расположение текста относительно указанной точки задаётся функцией textAlign. Шрифи и размер задаются функциями textFont и textSize. Цвет текста задаётся функцией stroke.
-
-
Параметры:
-
-
text — текст для вывода;
-x, y — координаты начальной точки.
-
-
void textAlign(HAlign hor, VAlign vert);
-
-
Установить расположение текста относительно начальной точки (см. функцию text)
-
-
Параметры:
-
-
hor — горизонтальное расположение начальной точки текста, может принимать значения:
- HALIGN_LEFT — начальная точка находится по левому краю текста;
- HALIGN_CENTER — начальная точка находится в середине текста;
- HALIGN_RIGHT — начальная точка находится по правому краю текста.
-vert — вертикальное расположение начальной точки текста, может принимать значения:
- VALIGN_TOP — начальная точка находится по верхнему краю текста;
- VALIGN_CENTER — начальная точка находится в середине текста;
- VALIGN_BOTTOM — начальная точка находится по нижнему краю текста.
Задать один из установленных в системе шрифтов для вывода текста (см. функцию text). Можете посмотреть списки установленных шрифтов в любом установленном на вашем компьютере текстовом редакторе. Вернуть стандартный шрифт можно командой textFontDefault. Для загрузки шрифтов из фала смотрите функции createFont и textFont.
-
-
Параметры:
-
-
family — текстовое наименование шрифта.
-
-
void textFontDefault();
-
-
Вернуть стандартный шрифт для вывода текста. Отменяет действие функций textFont и textFontFamily.
-
-
Font createFont(const char *path);
-
-
Загрузить шрифт из файла. Функция возвращает значение типа Font, которое является адресом в памяти — указателем на описание шрифта внутри библиотеки Helianthus.
-
-
Данная функция только загружает шрифт в память, для того чтобы писать текст этим шрифтом на экране вам нужно вызвать ещё и функцию textFont. Вы может иметь множество загруженных шрифтов в программе и переключать их функцией textFont.
Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на шрифт. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на шрифт. Вы можете занести в эту переменную другой шрифт, но использовать старое значение переменной больше нельзя это приведёт у ошибкам и непредсказуемому поведению программы.
-
-
void textFont(Font font);
-
-
Выбрать ранее загруженный из файла шрифт для вывода текста (см. функции createFont и text). Вернуть стандартный шрифт можно командой textFontDefault. Для загрузки системных шрифтов смотрите функцию textFontFamily.
Задать смещение системы координат. После вызова этой функции все объекты будут рисоваться с заданным смещением. Смещение производится относительно действующей в данный момент системы координат. См. также rotate, scale и noTransform.
+
+
void rotate(double angle);
+
+
Повернуть текущую систему координат на заданный угол (angle) в градусах. См. также translate, scale и noTransform.
+
+
+
void zoom(double z);
+
+
Смасштабировать текущую систему координат на заданный коэффициент (z). Эквивалентно вызову scale(z, z). См. также translate, rotate, scale и noTransform.
+
+
void scale(double x, double y);
+
+
Смасштабировать (растянуть) текущую систему координат на заданные коэффициенты по осям x и y. См. также translate, rotate и noTransform.
void clipRect(double x, double y, double width, double height);
+
+
Задаёт прямоугольник отсечения. Все последующие операции рисования будут выполнены только внутри заданного прямоугольника. Всё что было нарисовано ранее за его пределами останется неизменным. Повторный вызов функции заменяет (а не дополняет) ранее заданную область отсечения. Если вы знакомы с OpenGL, вам будет полезно знать, что данная функция просто задаёт четыре плоскости отсечения (glClipPlane). Область отсечения применяется со всеми действующими в момент вызова функции преобразованиями системы координат, таким образом она может быть на экране не прямоугольной, а, например, иметь форму параллелограмма. См. также noClip.
Сбрасывает состояние инструментов рисования к их начальным значениям. Эквивалентно вызову resetStateEx(STATE_ALL). См. также saveState и restoreState.
+
+
void resetStateEx(unsigned int flags);
+
+
Сбрасывает выбранные состояния инструментов рисования к их начальным значениям. Аргумент flags определяет перечень состояний которые необходимо сбросить. Значение для него можно вычислить объединив операцией побитового «или» (вертикальная черта: |) несколько флагов из следующего списка:
+
+
+
+
STATE_FILL_COLOR
+
цвет заполнения, см. fill
+
+
+
STATE_FILL_TEXTURE
+
текстура заполнения, см. fillTexture
+
+
+
STATE_STROKE_COLOR
+
цвет обводки, см. stroke
+
+
+
STATE_STROKE_TEXTURE
+
текстура обводки, см. strokeTexture
+
+
+
STATE_STROKE_WIDTH
+
толщина обводки, см. strokeWidth
+
+
+
STATE_TEXT_ALIGN
+
расположение текста, см. textAlign
+
+
+
STATE_TEXT_SIZE
+
размер шрифта, см. textSize
+
+
+
STATE_TEXT_FONT
+
шрифт, см. textFont
+
+
+
STATE_TARGET_FRAMEBUFFER
+
выбранный буфер кадра, см. target
+
+
+
STATE_TARGET_VIEWPORT
+
текущая область рисования, см. viewportByFramebuffer, viewportByWindow
+
+
+
STATE_TARGET_PROJECTION
+
текущая матрица проекции, см. projectionByViewport
+
+
+
STATE_BACKGROUND
+
цвет очистки экрана (цвет фона), см. baclground
+
+
+
STATE_TRANSFORM
+
преобразования системы координат, см. translate, rotate, scale, zoom
+
+
+
STATE_CLIP
+
область отсечения, см. clipRect
+
+
+
+
+
+
+
STATE_FILL
+
объединение флагов STATE_FILL_*
+
+
+
STATE_STROKE
+
объединение флагов STATE_STROKE_*
+
+
+
STATE_TEXT
+
объединение флагов STATE_TEXT_*
+
+
+
STATE_TARGET
+
объединение флагов STATE_TARGET_*
+
+
+
STATE_ALL
+
объединение всех флагов
+
+
+
+
+
void saveState();
+
+
Запоминает состояние всех инструментов рисования для того чтобы впоследствии к ним вернуться вызвав функцию restoreState. Функция может быть вызвана несколько раз чтобы запомнить несколько состояний, при этом позже необходимо будет выполнить соответствующее количество вызовов функции restoreState. Обращение в данной функции эквивалентно вызову saveStateEx(STATE_ALL). См. также resetState.
+
+
void saveStateEx(unsigned int flags);
+
+
Запоминает выбранные состояния инструментов рисования для того чтобы впоследствии к ним вернуться вызвав функцию restoreState. Функция может быть вызвана несколько раз, при этом позже необходимо будет выполнить соответствующее количество вызовов функции restoreState. Аргумент flags определяет перечень состояний которые необходимо запомнить. Значение для него можно вычислить объединив операцией побитового «или» (вертикальная черта: |) несколько флагов из списка представленного в описании функции resetState.
+См. также saveState.
+
+
void restoreState();
+
+
Восстанавливает состояния инструментов рисования ранее сохранённые функцией saveState или saveStateEx. Если функция saveState (или saveStateEx) была вызвана несколько раз, то чтобы вернуться к первоначальному состоянию нужно вызвать restoreState аналогичное количество раз. См. также resetState.
+
+
Важно: следите за тем чтобы количество сохранений (saveState или saveStateEx) всегда совпадало с количеством восстановлений (restoreState).
diff --git a/doc/ru/font.html b/doc/ru/font.html
new file mode 100644
index 0000000..7427acd
--- /dev/null
+++ b/doc/ru/font.html
@@ -0,0 +1,163 @@
+
++
+
+Шрифты и текст - Helianthus
+
+
Для вывода текста используются функции text, textAlign и textSize. Смотрите их описание ниже. Цвет выводимого теста определяется функцией stroke.
+
+
Вы можете загружать и использовать собственные шрифты из файлов (TrueType или OpenType) при помощи функций createFont и textFont.
+
+
Прежде чем выводить текст на экран формируется его разметка — определяются координаты и размеры каждого символа. Это делается автоматически и не требует никаких дополнительных действий. Однако для больших текстов эта операция может занять некоторое время. И если вы хотите увеличить производительность своей программы, то можете выполнить разметку текста заранее вызвав функцию createTextLayout и, затем, выводить её на экран функцией textLayoutDraw.
+
+
Функции:
+
+
void text(const char *text, double x, double y);
+
+
Вывести текст в заданной точке. Расположение текста относительно указанной точки задаётся функцией textAlign. Шрифт и размер задаются функциями textFont и textSize. Цвет текста задаётся функцией stroke.
+
+
Параметры:
+
+
text — текст для вывода;
+x, y — координаты начальной точки.
+
+
void textAlign(HAlign hor, VAlign vert);
+
+
Установить расположение текста относительно начальной точки (см. функцию text)
+
+
Параметры:
+
+
hor — горизонтальное расположение начальной точки текста, может принимать значения:
+ HALIGN_LEFT — начальная точка находится по левому краю текста;
+ HALIGN_CENTER — начальная точка находится в середине текста;
+ HALIGN_RIGHT — начальная точка находится по правому краю текста.
+vert — вертикальное расположение начальной точки текста, может принимать значения:
+ VALIGN_TOP — начальная точка находится по верхнему краю текста;
+ VALIGN_CENTER — начальная точка находится в середине текста;
+ VALIGN_BOTTOM — начальная точка находится по нижнему краю текста.
Загрузить шрифт из файла. Функция возвращает значение типа Font, которое является адресом в памяти — указателем на описание шрифта внутри библиотеки Helianthus.
+
+
Данная функция только загружает шрифт в память, для того чтобы писать текст этим шрифтом на экране вам нужно вызвать ещё и функцию textFont. Вы может иметь множество загруженных шрифтов в программе и переключать их функцией textFont.
Font createFontFromMemory(const void *data, int size);
+
+
Создать шрифт из байтов файла шрифта уже загруженных в оперативную память. Функция возвращает значение типа Font, которое является адресом в памяти — указателем на описание шрифта внутри библиотеки Helianthus. См. также fontDestroy и createFont.
+
+
Параметры:
+
+
data — указатель на первый байт данных шрифта;
+size — количество байтов.
+
+
void fontClone(Font font);
+
+
Создать новый шрифт из ранее загруженного — сделать копию.
+
+
void fontDestroy(Font font);
+
+
Выгрузить шрифт из памяти.
+
+
Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на шрифт. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на шрифт. Вы можете занести в эту переменную другой шрифт, но использовать старое значение переменной больше нельзя это приведёт у ошибкам и непредсказуемому поведению программы.
+
+
void textFont(Font font);
+
+
Выбрать ранее загруженный из файла шрифт для вывода текста (см. функции createFont и text). Вернуть стандартный шрифт можно командой textFontDefault.
Вернуть стандартный шрифт для вывода текста. Отменяет действие функции textFont.
+
+
TextLayout createTextLayout(const char *text);
+
+
Создать разметку для заданного текста. Разметка определяет координаты и размер каждого символа текста. Разметка запоминает действующий на момент её создания шрифт (textFont) и выравнивание (textAlign), и, рисование данной разметки будет производиться только этим шрифтом. Однако, вы можете менять размер шрифта (textSize) и его цвет (stroke) непосредственно перед выводом данной разметки на экран. Вы можете узнать ширину (textLayoutGetWidth) и высоту (textLayoutGetHeight) текстового блока, а также выводить на экран весь текст (textLayoutDraw) или отдельные его части (textLayoutDrawSubstr) с применением разных способов заливки.
Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на разметку. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на разметку. Вы можете занести в эту переменную другую разметку, но использовать старое значение переменной больше нельзя это приведёт к ошибкам и непредсказуемому поведению программы.