BearLibTerminal / API / Конфигурация

Функции

Конфигурирование и работа с настройками выполняется при помощи функций set и get, а также посредством конфигурационного файла.

set

Это, вероятно, самая сложная функция в API. Конфигурирование опций библиотеки, управление шрифтами и тайлсетами и даже конфигурационным файлом производится с ее помощью:

terminal_set("window: size=80x25; font: ./UbuntuMono-R.ttf, size=12");

Функция возвращает булево значение, индицирующее успех выполнения.

Можно указывать несколько опций за один вызов. Однако, эта функция работает похожим на транзакцию образом: в случае ошибки все изменения откатываются (или просто не применяются) и функция возвращает false.

Формат конфигурационной строки

Строка, передаваемая в функцию, описывает набор параметров в виде пар имя-значение, разделенных точкой с запятой:

window.title='foo'; window.size=80x25;

Параметры могут быть сгруппированы:

window: title='foo', size=80x25;

Лишние пробелы, запятые и точки с запятой игнорируются. Все переносы строк также игнорируются (на данный момент, даже внутри значений, но это может измениться).

Экранирование строковых значений кавычками опционально и требуется только если значение содержит служебные символы (запятая или точка с запятой) или если необходимо сохранить пробелы в начале или конце. Кавычки внутри строки экранируются в Pascal-стиле (удвоением символа):

window.title='I''m feeling lucky!';

Экранирование спецсимволов (таких как \n или \t) не поддерживается.

Конфигурация библиотеки

Ряд параметров непосредственно влияют на вид окна и поведение библиотеки:

Группа Опция По умолчанию Краткое описание
terminal encoding utf8 Кодировка/кодовая страница, используемая для однобайтных строк; по умолчанию это “utf-8”, что может быть изменено на какю-нибудь кодовую страницу ANSI, например windows-1251.
window size 80×25 Размер окна в знакоместах.
cellsize auto Размер знакоместа в пикселях или “auto”, если размер должен быть выведен исходя из выбранного шрифта.
title'BearLibTerminal' Заголовок окна.
icon - Имя файла *.ico с иконкой; в версии для Windows, стандартная иконка встроена в библиотеку.
resizeable false Флаг, контролирующий возможность переразмерения окна пользователем, при изменении размера окна будет сгенерировано событие TK_RESIZED.
fullscreen false Флаг, позволяющий программно перевести окно в полноэкранный режим.
input precise-mouse false Флаг контролирующий точность регистрации передвижения мыши: когда он выставлен в “true”, можно отследить любое перемещение курсора мыши, неважно насколько малое. По умолчанию событие TK_MOUSE_MOVE генерируется только если курсор мыши перемещается на другое знакоместо.
mouse-cursor true Флаг, ответственный за отображение системного указателя мыши.
cursor-symbol 0x5F Код символа/тайла, используемого функцией read_str в качестве курсора ввода.
cursor-blink-rate 500 Скорость мерцания курсора ввода в функции read str в миллисекундах.
filter- События, не попавшие в этот список, будут обработаны библиотекой автоматически и не будут возвращены функцией read.
alt-functions true Если задействовано, библиотека перехватывает и обрабатывает некоторые Alt-комбинации, например Alt+Enter (переключение в полноэкранный режим) и Alt+Плюс/Минус/Ноль (масштаб окна).
output postformatting true Флаг, задействующий обработку специальных “тегов” функцией print.
vsync true Флаг, контролирующий использование вертикальной синхронизации при выводе сцены.
log file'bearlibterminal.log' Имя файла лога.
level error Уровень логгирования: “none”, “fatal”, “error”, “warning”, “info”, “debug” или “trace”.
mode truncate Режим записи в файл: “truncate” начнет запись в файл заново (очистив предыдущее содержимое), “append” будет дописывать в конец файла.
Управление шрифтами и тайлсетами

Помимо нескольких фиксированных групп параметров библиотеки, может быть сконфигурировано неопределенное количество групп параметров, описывающих отдельный шрифт, тайл или тайлсет (см. дизайн: тайлы и слоты) в следующем формате:

[name ](font|offset): resource, param=value, ...;

Например:

font: UbuntuMono-R.ttf, size=12;
runic font: runic.png, size=8x16, codepage=437;
0x5E: curcumflex.png;
0xE000: tileset.png, size=16x16, spacing=2x1;
name

Строка, опциональное и произвольное наименование альтернативного шрифта, например 'italic' или 'runic'. Такие именованные шрифты будут доступны в функции print посредством тега [font=name]:

terminal_print(2, 1, "Its eyes are [font=italic]glowing[/font].");

offset

Число, код одиночного тайла или точка отсчета для кодов в тайлсете (при offset равном 0xE000 первый тайл будет иметь код 0xE000, второй 0xE001 и т. д.).

Все “символы”, “тайлы” и “спрайты” находятся в одном кодовом пространстве: библиотека оперирует кодами символов Юникода и не учитывает что именно изображено на соответствующей коду символа картинке, будь то буква, пиктограмма или фон для экрана меню. Таким образом, можно осознанно или нечаянно переопределить внешний вид символов:

terminal_set("0x40: at.png, align=center"); // Replace '@' (ASCII code 0x40) with a better version.

Если такое переопределение нежелательно, то рекомендуется использовать для пиктограмм и прочей несимвольной графики специально выделенный блок Юникода: Unicode Private Use Area (коды 0xE000-0xEFFF).

resource

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

terminal_setf("font: %p:%d, size=8x16, codepage=437", buffer, size);

Также возможно загрузить тайлсет непосредственно из блока BGRA пикселей в памяти. В этом случае необходимо указать размер изображения посредством параметра 'raw-size':

terminal_setf("0xE000: %p:%d, raw-size=%dx%d", pixels, W*H*4, W, H);

params

Состав параметров в группе и их смысл отличается в зависимости от типа шрифта/тайлсета:

Тип Параметр По умолчанию Краткое описание
Bitmap size Размер отдельного тайла в наборе; по умолчанию изображение рассматривается как один большой спрайт.
resize Размер, до которого необходимо переразмерить тайлы (или спрайт).
resize-filter bilinear Фильтр переразмерения: “nearest”, “bilinear” или “bicubic”.
resize-mode stretch Формат переразмерения: “stretch” (растянуть), “fit” (вписать по наибольшей стороне) или “crop” (вписать по наименьшей стороне).
raw-size Размер исходного изображения в случае загрузке из памяти (по указателю на массив пикселей).
codepage ascii Кодовая страница тайлсета, используемая в основном для загрузки шрифтов; по умолчанию “ascii”.
align center Выравнивание тайла в ячейке: “center”, “top-left”, “bottom-left”, “top-right” или “bottom-right”.
spacing 1x1 Размер ячейки выравнивания, в знакоместах.
transparent auto Цвет фона для форматов/изображений, не поддерживающих прозрачность.
TrueType size Размер шрифта или тайла, под который будет подогнан размер шрифта; это обязательный параметр.
size-reference '@' Символ, используемый в качестве основы при подгонке размера шрифта под размер тайла.
mode normal Режим растеризации шрифта: “monochrome”, “normal” или “lcd”.
codepage Инвертированная кодовая таблица для загрузки только конкретных глифов.
align center Выравнивание тайла в ячейке, то же самое, что и для растровых тайлсетов.
spacing 1x1 Размер ячейки выравнивания, то же самое, что и для растровых тайлсетов.

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

Примеры описания растровых шрифтов/тайлсетов:

font: somefont.png, size=8x16, codepage=1251;
0xE000: walls.bmp, size=32x32, spacing=4x2;
0xE100: background.jpg, resize=640x400, resize-filter=bicubic, align=top-left;

Примеры описания TrueType шрифтов/тайлсетов:

font: somefont.ttf, size=12;
0xE000: otherfont.ttf, size=8x16, codepage=1251;
0xE100: fontawesome.ttf, size=32x32, spacing=4x2, codepage=fontawesome-cp.txt;

Для того, чтобы выгрузить тайлсет, необходимо установить его “основное значение” в “none”:

0xE000: none
Обновление конфигурационного файла

С помощью функции set возможно добавление, изменение и удаление параметров из конфигурационного файла библиотеки, путем указания их в виде ini.section.property:

ini.game.tile-size = 16

В приведенном примере, библиотека обновит значение параметра “tile-size” в секции “game” конфигурационного файла:

Если указанного параметра или секции в файле нет, они будут добавлены. Для того, чтобы удалить параметр из файла, нужно указать пустое значение. Как следствие, программно установить пустое значение невозможно; вместо этого используйте осмысленное значение по умолчанию для соответствущего параметра.

get

Эта функция возвращает значение параметра (опция библиотеки или из конфигурационного файла). Если такой параметр не найден, возвращается переданное в функцию значение-заглушка:

const char* tile_size = terminal_get("ini.game.tile-size", "24");

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

В интерфейсе С/С++, память возвращаемой строки принадлежит библиотеке и указатель на нее останется валидным до следующего вызова get с тем же именем параметра. Возвращаемое значение всегда будет корректной строкой, даже если значение-заглушка не было указано (в этом случае будет возвращена пустая строка).

Конфигурационный файл

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

Файл должен быть в обычном INI-формате с некоторыми особенностями:

  • Для комментирования могут использоваться символы # и ;. Строки, начинающиеся с пробела/табуляции также игнорируются.
  • Имена секций и свойств нечуствительны к регистру (но библиотека сохранит регистр при модификации значений).
  • Допускается повтор секций.
  • Библиотека не понимает привычное экранирование посредством слеша: “\n” это строка из двух обычных символов.
  • Пробелы вокруг имени свойства и его значения игнорируются.
  • Строка может содержать группу параметров в стиле вызова set (см. формат конфигурационной строки).

Примером конфигурационного файла может быть:

# Комментарий
; Еще один комментарий
  Это строка тоже будет считаться комментарием

[BearLibTerminal]
log: file=bt.log, level=trace
font: UbuntuMono-R.ttf, size=12
window.title='Configuration file example'

[Palette]
lush = dark 80,255,37

[Game]
tile-size = 16 ; Все после точки с запятой игнорируется.

Имя конфигурационного файла не задано жестко, библиотека постарается найти подходящий файл. Если не получится обнаружить файл, названный так же, как и приложение (game.ini для game.exe), будет использован первый попавшийся INI-файл. Файлы в текущей директории имеют больший приоритет, но поиск производится и в директории с исполняемым файлом приложения.

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

[BearLibTerminal]

Параметры из секции “BearLibTerminal” применяются в качестве общей конфигурации, как будто бы они были указаны в вызове функции set. Параметры логгирования применяются первыми, остальные параметры группируются и каждая группа применяется отдельно (таким образом, если в процессе возникает ошибка, это не приводит к отмене всей конфигурации).

[Palette]

Параметры секции “Palette” будут добавлены к списку именованных цветов. Значения цвета разбираются функцией color from name.