BearLibTerminal / API

Некоторые части библиотеки описаны более подробно на отдельных страницах (в процессе):

API библиотеки состоит из ~20 функций и набора констант.

Так как библиотека предоставляет по возможности не зависящий от конкретного языка программирования набор вызовов, качественный и количественный состав функций, доступных в том или ином языке, немного отличается. На данной странице API описывается кратко и, в основном, с точки зрения С/С++. Специфичные различным языкам программирования нюансы будут описаны на отдельных страницах (что пока не готово).

open

int terminal_open();
Эта функция инициализирует библиотеку, применяя настройки по умолчанию: окно размером 80×25 знакомест, растровый шрифт Fixedsys Excelsior (встроенный), белый текст на черном фоне. Вызов этой функции не выводит окно на экран, оно не будет показано до первого вызова функции refresh.

Функция возвращает логически булево значение, где false (ноль) означает, что инициализация не удалась по той или иной причине. Детали ошибки могут быть найдены в лог-файле (по умолчанию это файл bearlibterminal.log).

close

void terminal_close();
Симметрично open, эта функция закрывает окно и деинициализирует библиотеку.

set

int terminal_set(const char* s); // + варианты setf, wset и wsetf с использованием wchar_t и/или форматирования
Это, вероятно, самая сложная функция в API. Конфигурирование опций библиотеки, управление шрифтами и тайлсетами и даже конфигурационным файлом производится с ее помощью.

Функция принимает “конфигурационную строку” со списком различных параметров:

window.title='game';
font: UbuntuMono-R.ttf, size=12;
ini.settings.tile-size=16;

Информацию о формате передаваемой строки, списке возможных опций и поведении функции см. на отдельной странице о конфигурации.

color

void terminal_color(color_t color);
Эта функция устанавливает текущий цвет вывода текста/тайлов. Тип color_t – это 32-битное целое число, представляющее цвет в формате BGRA (0xAARRGGBB). Такое численное представление может быть сконструировано вручную или посредством вызова функций color from argb и color from name. Для большинства языков программирования включая С++, есть перегруженные варианты функции color, принимающие строку с названием цвета (см. color from name).

Текущий цвета текста может быть получен посредством свойства TK_COLOR (см. state).

bkcolor

void terminal_bkcolor(color_t color);
Аналогично color, эта функция устанавливает текущий цвет фона. Только первый, самый нижний слой имеет фон.

Текущий цвет фона может быть получен посредством свойства TK_BKCOLOR (см. state).

composition

void terminal_composition(int mode);
Эта функция устанавливает режим композиции. Когда композиция отключена (по умолчанию это так), установка нового тайла в ячейку посредством функций put или print, полностью заменяет содержимое этой ячейки. Когда композиция включена, тайл добавляется поверх уже имеющихся в ячейке тайлов, что выглядит как комбинирование нескольких тайлов. Количество тайлов в одной ячейке ничем специально не ограничивается, и каждый тайл в получаемой “стопке” может иметь индивидуальные цвет и смещение (см. put ext).

Значением параметра mode может быть TK_OFF или TK_ON.

Текущее значение режима композиции можно получить посредством свойства TK_COMPOSITION (см. state).

layer

void terminal_layer(int layer);
Эта функция устанавливает текущий слой ячеек. Аргументом функции должно являться число от 0 до 255, где 0 – это самый нижний слой, выбранный по умолчанию. Только этот первый слой имеет фон, для слоев 1 и выше цвет фона, установленный функцией bkcolor, не учитывается. Нужно помнить, что clear area работает с текущим выбранным слоем, тогда как clear очищает всю сцену целиком.

Слои полезны по нескольким причинам. Одна из них заключается в том, что библиотека BearLibTerminal позволяет использовать тайлы размером больше одной ячейки. Учитывая, что ячейки отрисовываются строго слева направо и сверху вниз, оказывается невозможно расположить больший по размеру тайл таким образом, чтобы он закрывал ячейки правее и ниже, ведь те ячейки гарантированно будут отрисованы позднее. Разделив сцену на несколько слоев, можно обеспечить желаемый порядок отрисовки.

Еще одним применением слоев может быть логическое разделение сцены. Слои могут быть очищены и/или изменены независимо друг от друга, что позволяет обновлять части сцены (такие как игровой уровень или интерфейс) независимо друг от друга.

Текущий номер слоя может быть получен посредством свойства TK_LAYER (см. state).

clear

void terminal_clear();
Эта функция очищает всю сцену (все слои). Она также устанавливает цвет фона каждой ячейки нижнего, нулевого слоя в текущий выбранный цвет фона.

clear_area

void terminal_clear_area(int x, int y, int w, int h);
Эта функция очищает часть текущего выбранного слоя. Аргументы функции указывают верхний левый угол и размеры прямоугольной области, которая будет очищена. Будучи вызванной на нулевом слое, функция также устанавливает цвет фона ячеек указанной области в текущий выбранный цвет фона.

crop

void terminal_crop(int x, int y, int w, int h);
Эта функция устанавливает область кропа текущего слоя: все, что выходит за пределы указанной области в соответствующем слое, выведено не будет. Размеры области указываются в знакоместах. Для сброса кропа в слое нужно или установить высоту или ширину области нулевой или очистить всю сцену посредством clear.

refresh

void terminal_refresh();
Эта функция применяет произведенные над сценой изменения и перерисовывает содержимое окна.

BearLibTerminal не выводит тайлы на экран немедленно при вызове функций put или print. Вместо этого сцена конструируется в памяти по аналогии с двойной буферизацией. В случае, если содержимое окна по каким-то причинам будет испорчено и запрошено операционной системой заново, библиотека автоматически отрисует последнюю примененную копию сцены.

Первый вызов этой функции с момента инициализации библиотеки выводит на экран окно псевдотерминала. Между вызовом open и первым вызовом refresh окно на экране не отображается.

put

void terminal_put(int x, int y, int code);
Эта функция помещает тайл, ассоциированный с указанным кодом, в ячейку с координатами x, y. Если указанный код не соответствует ни одному загруженному тайлу, будет использован тайл “отсутствие символа” в виде прямоугольной рамки.

Коды символов должны выбираться из Юникода. Даже если установленный основной шрифт выполнен в кодовой странице ANSI или аналогичной, библиотека сопоставляет отдельные символы кодам Юникода. К примеру знак “евро” (если он вообще присутствует в шрифте) всегда будет иметь код U+20AC, кроме случаев некорректной настройки шрифта при его загрузке.

put_ext

void terminal_put_ext(int x, int y, int dx, int dy, int code, color_t* corners);
Эта функция является расширенной версией put, позволяя также указать смещение тайла относительно ячейки и/или задать отдельные цвета для каждого из углов тайла.

Параметры dx и dy задают смещение тайла в пикселях относительно его нормального положения в ячейке. При включенной композиции в ячейке может быть более одного тайла и каждый из них может иметь свое собственное смещение. Важным моментом является то, что смещение в ячейке никак не влияет на порядок вывода тайлов (ячейка за ячейкой, слева направо, сверху вниз). Даже если визуально тайл находится правее или ниже ячейки, в которой он расположен, он будет отрисован в обычном порядке и будет перекрыт другими тайлами, реально расположенными правее или ниже. Если такое поведение нежелательно, следует использовать слои.

Параметр corners должен указывать на массив из четырех color_t, описывающих цвета углов тайла в порядке против часовой стрелки, начиная с верхнего левого. Возможность указать цвета углов позволяет выводить тайлы с плавным градиентом или переходом. Также как и со смещением, каждый тайл в ячейке может иметь свой набор цветов. Если вместо массива передать NULL, для вывода тайла будет использован текущий цвет переднего плана.

pick

int terminal_pick(int x, int y, int index);
Эта функция возвращает код символа или тайла из ячейки с указанными координатами в текущем слое. Параметр index указывает порядковый номер символа/тайла для случая, если в ячейке их находится несколько. Если в ячейке нет тайла с таким порядковым номером или в ячейке вообще ничего нет, возвращается 0. Таким образом, для того, чтобы выбрать все содержимое ячейки, необходимо увеличивать параметр index до тех пор, пока функция pick не вернет 0.

Функция производит обратную трансляцию кода символа в соответствии с параметром terminal.encoding.

pick_color

color_t terminal_pick_color(int x, int y, int index);
Функция, дополняющая pick, позволяющая узнать цвет определенного символа или тайла в ячейке.

pick_bkcolor

color_t terminal_pick_bkcolor(int x, int y);
Функция, дополняющая pick, позволяющая узнать цвет фона ячейки.

print

void terminal_print(int x, int y, const char* s); // + варианты printf, wprint and wprintf с использованием wchar_t и/или форматирования
Эта функция выводит строку начиная с указанных координат. Каждый отдельный символ помещается на сцену аналогично использованию вызовов put(_ext), т. е. с учетом выбранных цветов переднего и заднего плана, текущего слоя и режима композиции.

Поведение print может быть расширено посредством использования “тегов” в выводимой строке:

  • Цвета: [color=red] или [bkcolor=gray], при этом названия цветов разбираются функцией color from name.
  • Произвольные коды символов: [U+E001] или [0xE001].
  • Комбинирование символов: a[+]^ приведет к выводу, похожему на â. Комбинирование производится размещением обоих тайлов в одной ячейке со временно задействованной композицией.
  • Пиксельное смещение: [offset=4,8]. Добавляет смещение отдельно к каждому выводимому символу.
  • Выравнивание: [align=bottom-right]. Задает расположение текста относительно указанной стартовой точки.
  • Область вывода: [bbox=16] or [bbox=32×5]. Библиотека постарается вывести строку в указанных пределах, с автопереносом если потребуется.
  • Альтернативный шрифт: [font=0xE000] (потребует отдельного объяснения).

Теги color, bkcolor, offset и font могут быть отменены размещением симметричного “закрывающего” тега, например [/color] или [/offset]. Теги могут комбинироваться в произвольном порядке, однако вложенность тегов одного типа не поддерживается: каждый открывающий тег полностью заменяет предыдущие такого же типа, каждый закрывающий – отменяет все эффекты тега этого типа. Закрывать все использованные в строке теги необязательно, так как их эффекты распространяются только на конкретный вызов функции print.

terminal_printf("[offset=%d,%d]g[+][color=red]^[/color] (red-hooded goblin)", dx, dy);

Для вывода одинарной квадратной скобки следует продублировать ее в строке.

Функция возвращает размер выводимой на экран строки с учетом примененного форматирования. По умолчанию print вернет ширину строки. Если строка содержит тег bbox, тогда максимальная ширина строки уже известна и print вернет высоту выведенной строки с учетом автопереноса.

measure

void terminal_measure(const char* s); // + варианты terminal_[w]measure[f]
Эта функция рассчитывает размер (высоту или ширину в зависимости от присутствия тега bbox, см. print), не выводя строку на экран.

state

int terminal_state(int slot);
Эта функция возвращает текущее состояние некоторого свойства или состояния библиотеки: текущий выбранный цвет, размер окна или знакоместа, состояние клавиши и т. д.

Значения большинства свойств обновляются в процессе чтения событий ввода посредством функции read, сохраняя строгую очередность изменения и согласованность во времени. Например, подобная проверка нажатия комбинации клавиш будет работать корректно даже если к моменту выполнения кода клавиши уже были отжаты:

int key = terminal_read();

if (key == TK_A)
{
    if (terminal_state(TK_SHIFT))
    {
        // Shift+A
    }
    else
    {
        // Просто A
    }
}

Поведение функции state и очереди ввода описано более подробно на отдельной, посвященной вводу странице. Там же приведен список всех свойств, которые можно запросить с помощью данной функции.

check

int terminal_check(int slot);
Это простая обертка над функцией state. Она возвращает (логически) булево значение, указывающее на ненулевое значение свойства. Во многих языках программирования нельзя непосредственно сравнивать значения численного и булевого типа, из-за чего проверка логически булевых состояний с постоянным приведением типов может быстро надоесть. Вместо этого можно использовать check для проверки логических свойств – таких, как факт нажатия клавиши.

Эта обертка добавлена в заголовочный файл С/С++ в основном для большей целостности.

has_input

int terminal_has_input();
Эта функция возвращает булево значение, сигнализирующее наличие доступных событий ввода в очереди. Возврат true функцией has_input гарантирует, что следующий вызов read вернет результат сразу же, не блокируя выполнение программы.

read

int terminal_read();
Эта функция возвращает следующее событие из очереди ввода:

int key = terminal_read();

if (key == TK_ESCAPE)
{
    // Выход
}

Если в очередь ввода пуста, вызов заблокирует выполнение до поступления нового события. Если такое блокируещее поведение нежелательно, можно проверить has input перед вызовом read.

peek

int terminal_peek();
Эта функция аналогична read, но не убирает прочитанное событие из внутренней очереди (следующий вызов peek или read вернет то же значение). Кроме того, вызов этой функции является неблокирующим: если очередь ввода пуста, функция вернет 0.

read_str

color_t terminal_read_str(int x, int y, char* buffer, int max); // + вариант read_wstr для wchar_t
Эта функция выполняет простое блокирующее чтение строки без какого-либо разбора введенного значения. В процессе выполнения вызова, пользовательский ввод отображается по указанным координатам и ограничивается по размеру и может быть легко вписан в интерфейс игры. Функция отображает ввод в текущем выбранном слое и полностью восстанавливает исходное состояние сцены перед выходом, оставляя сохранение введенной строки на экране на усмотрение приложения.

Функция возвращает размер строки, введенной пользователем и подтвержденной нажатием на Enter, или константу TK_INPUT_CANCELLED, если ввод был отменен нажатием на Escape или вовсе попыткой закрытия окна.

wchar_t s[32] = L"Привет";

if (terminal_read_wstr(2, 1, s, sizeof(s)-1) >= 0)
{
    terminal_wprintf(L"Вы ввели: \"%ls\"", s);
}

Если поведение read_str не удовлетворяет требованиям конкретного приложения, можно использовать свойства TK CHAR/TK WCHAR, позволяющие реализовать произвольный ввод строки.

delay

void terminal_delay(int period);
Эта функция предоставляет кроссплатформенный вызов, приостанавливающий выполнение текущего потока на указанное количество миллисекунд.

color_from_name

color_t color_from_name(const char* name); // + вариант color_from_wname для wchar_t
Эта функция возвращает численное представление цвета по его имени во встроенной палитре или текстовому представлению. Имя задается в формате ”[яркость ]оттенок”, например “red”, “light green” или “darker #905025”.

Возможные значения яркости: lightest, lighter, light, dark, darker, darkest.

Оттенок (базовый цвет) может быть указан несколькими способами:

  • По имени: grey (или gray), red, flame, orange, amber, yellow, lime, chartreuse, green, sea, turquoise, cyan, sky, azure, blue, han, violet, purple, fuchsia, magenta, pink, crimson, transparent.
  • В шестнадцатиричном формате: #RRGGBB or #AARRGGBB, например #80905025
  • В десятичном формате, разделенном запятыми: R,G,B or A,R,G,B например 128,200,150,75
  • Как форматированное в строку целое число, например 16744448

Новые именованные цвета могут быть добавлены в палитру вызовом set:

terminal_set("palette.octarine = #50FF25");

Или посредством конфигурационного файла:

[Palette]
lush = dark 80,255,37

Функция print использует color_from_name для разбора названий цветов в тегах.

color_from_argb

color_t color_from_argb(uint8_t alpha, uint8_t red, uint8_t green, uint8_t blue);
Эта функция является простой утилитой для сборки четырех отдельных 8-битных значений в 32-битное.