BearLibTerminal — различия между версиями

Материал из Клуб любителей рогаликов
Перейти к: навигация, поиск
(Nim)
 
(не показаны 23 промежуточные версии 3 участников)
Строка 1: Строка 1:
 +
__NOTOC__
 
BearLibTerminal — это небольшая (в интерфейсном плане) библиотека для организации терминал-подобного окна, вывода текста, обработки простого ввода.  
 
BearLibTerminal — это небольшая (в интерфейсном плане) библиотека для организации терминал-подобного окна, вывода текста, обработки простого ввода.  
  
Строка 4: Строка 5:
  
 
Достойными внимания особенностями терминала являются:
 
Достойными внимания особенностями терминала являются:
 +
* Легкость использования Unicode.
 +
* Использование тайловых (в виде картинки) и векторных (TrueType) шрифтов.
 +
* Расширенный вывод символов: композиция, центрирование, смещение.
 
* Высокая скорость вывода (в основе лежит OpenGL).
 
* Высокая скорость вывода (в основе лежит OpenGL).
* Возможность использования тайловых (в виде картинки) и векторных (TrueType) шрифтов.
+
* Поддержка как клавиатуры, так и мыши.
* Легкость использования Unicode.
+
* Сборки под Windows, Linux и OS X.
* Полная TrueColor палитра.
+
* Привязки к нескольким языкам: С/С++, C#, Lua, Pascal, Python, Ruby.
* Возможность комбинации нескольких символов в одном знакоместе.
 
* Поддержка ввода с клавиатуры и мыши.
 
  
 
BearLibTerminal не является:
 
BearLibTerminal не является:
 
* Фреймворком roguelike: в библиотеке нет и никогда не будет генераторов случайных чисел, уровней или имен персонажей, механизмов расчета FOV/LOS и освещения, средств для работы с файлами или сетью.
 
* Фреймворком roguelike: в библиотеке нет и никогда не будет генераторов случайных чисел, уровней или имен персонажей, механизмов расчета FOV/LOS и освещения, средств для работы с файлами или сетью.
* Графическим движком общего назначения: функциональность библиотеки сознательно ограничивается функциональностью псевдотерминала.
+
* Графическим движком общего назначения: функциональность библиотеки сознательно ограничивается функциональностью псевдотерминала ''(спорное утверждение для версий 0.9+)''.
  
Похожие инструменты: [[Tinycurses]], [[libtcod]].
+
Похожие инструменты: [[Tinycurses]], [[libtcod]].  
<div style="margin-top: 0.5em;">__TOC__</div>
 
  
== Интерфейс библиотеки ==
+
== Документация ==
BearLibTerminal оформлен в виде динамически подключаемой библиотеки (.dll). Используемое [http://ru.wikipedia.org/wiki/%D0%A1%D0%BE%D0%B3%D0%BB%D0%B0%D1%88%D0%B5%D0%BD%D0%B8%D0%B5_%D0%B2%D1%8B%D0%B7%D0%BE%D0%B2%D0%B0 соглашение вызова] — cdecl.
+
Наиболее актуальная документация размещена на сайте библиотеки:
=== terminal_open ===
+
* [http://foo.wyrd.name/ru:bearlibterminal:reference Описание API]
<syntaxhighlight lang="cpp">
 
int terminal_open(int codepage);
 
</syntaxhighlight>
 
Для начала работы с библиотекой необходимо вызвать функцию terminal_open. Эта функция принимает один параметр -- номер кодировки, которую использует приложение. Подробно о кодировках и их использовании в BearLibTerminal [будет] рассказано в [[#Кодировки|отдельном параграфе]]. В большинстве случаев подойдет значение по умолчанию, <tt>CODEPAGE_DEFAULT</tt>.
 
До вызова <code>terminal_open</code> все остальные функции библиотеки мгновенно завершаются, не выполняя никаких действий.
 
Вызов <code>terminal_open</code> не приводит к немедленному выводу окна терминала на экран, окно отображается в момент первого вызова функции <code>[[#terminal_refresh]]</code>.
 
=== terminal_close ===
 
<syntaxhighlight lang="cpp">
 
void terminal_close();
 
</syntaxhighlight>
 
Симметричный <code>terminal_open</code> вызов, закрывающий терминал и освобождающий используемые библиотекой ресурсы. Поведение программы, не вызвавшей terminal_open перед своим завершением, неопределено.
 
=== terminal_options ===
 
<syntaxhighlight lang="cpp">
 
// ANSI/UTF-8
 
int terminal_options(const char* options, ...);
 
int terminal_options_noformat(const char* options);
 
  
// UTF-16
+
== Установка ==
int terminal_woptions(const wchar_t* options, ...);
+
В большинстве случаев нужно взять заголовочный файл/враппер и бинарник динамической библиотеки из архива, который можно скачать [http://foo.wyrd.name/ru:bearlibterminal#скачать на сайте] библиотеки или [http://rlgclub.ru/forum/viewtopic.php?f=26&t=851 по ссылкам] в первом сообщении форума.
int terminal_woptions_noformat(const wchar_t* options);
 
</syntaxhighlight>
 
Данная функция представляет собой универсальный способ задания разнообразных настроек библиотеки. Опции задаются в виде строки с парами параметр-значение, разделенными точкой с запятой:<br/>
 
<code>option1=value1; option2=value2; ...</code>
 
  
В библиотеке имеются два варианта функции, с суффиксом "noformat" и без. Вариант без суффикса (с переменным числом аргументов) позволяет использовать в С/С++ привычное форматирование передаваемой строки:
+
==== C/C++ ====
<syntaxhighlight lang="cpp">
+
Используется заголовочный файл BearLibTerminal.h
terminal_options("size=%dx%d", width, height);
 
</syntaxhighlight>
 
Вариант с суффиксом "noformat" не производит подобного форматирования и может быть использован при вызове функций из программы, написанной на других языках программирования, предоставляющих собственные механизмы форматирования строк.
 
==== Перечень доступных параметров ====
 
{| class="wikitable"
 
|-
 
|Наименование
 
|Значение по умолчанию
 
|Описание
 
|-
 
|colspan="3" style="background-color: #dddddd;"|''Настройки окна''
 
|-
 
|size
 
|80x25
 
|Размер окна терминала в знакоместах, в формате ''ШИРИНА''x''ВЫСОТА''.
 
|-
 
|title
 
|BearLibTerminal
 
|Заголовок окна терминала.
 
|-
 
|icon
 
|app.ico
 
|Имя <tt>.ico</tt>-файла с иконкой, которая будет использована для окна.
 
|-
 
|colspan="3" style="background-color: #dddddd;"|''Настройки шрифта''
 
|-
 
|font.name
 
|default
 
|Имя файла шрифта, векторного <tt>.ttf</tt> или тайлового <tt>.bmp</tt>/<tt>.png</tt>
 
|-
 
|font.size
 
|10
 
|Размер шрифта: высота символа для векторного шрифта, размер одного тайла для тайлового шрифта.
 
|-
 
|font.mode
 
|normal
 
|Режим растеризации при использовании векторного шрифта: <tt>monochrome</tt>, <tt>normal</tt> или <tt>lcd</tt>.
 
|-
 
|font.codepage
 
|utf-8
 
|Кодовая страница тайлового шрифта.
 
|-
 
|colspan="3" style="background-color: #dddddd;"|''Настройки ввода''
 
|-
 
|input.events
 
|keypress
 
|Фильтр событий ввода, комбинация из флагов <tt>none</tt>, <tt>keypress</tt>, <tt>keyrelease</tt>, <tt>mousemove</tt>, <tt>mousescroll</tt>, <tt>all</tt>.
 
|-
 
|input.timeout
 
|infinite
 
|Таймаут ожидания события ввода: <tt>infinite</tt>, <tt>immediate</tt> или численное значение в миллисекундах.
 
|-
 
|input.precise_mousemove
 
|false
 
|Флаг, указывающий, будет ли считаться движением мыши попиксельное (true) или познакоместное (false) перемещение указателя.
 
|-
 
|input.cursor_symbol
 
|95 (ASCII 0x5F, подчеркивание)
 
|Код символа, используемого в качестве курсора в terminal_get_str.
 
|-
 
|input.cursor_blink_rate
 
|500
 
|Скорость мерцания курсора в terminal_get_str, в миллисекундах.
 
|-
 
|colspan="3" style="background-color: #dddddd;"|''Настройки вывода''
 
|-
 
|output.postformat
 
|true
 
|Флаг, включающий или выключающий постформатирование при выводе текста.
 
|-
 
|colspan="3" style="background-color: #dddddd;"|''Настройки логгирования''
 
|-
 
|log.file
 
|bearlibterminal.log
 
|Имя файла, куда в библиотека будет писать свой лог. Файл не ротируется, логгирование попросту производится в конец указанного файла.
 
|-
 
|log.level
 
|error
 
|Уровень важности логгирования: <tt>none</tt>, <tt>fatal</tt>, <tt>error</tt>, <tt>warning</tt>, <tt>info</tt>, <tt>debug</tt>, <tt>trace</tt>
 
|}
 
==== Настройки окна ====
 
''<подробно про настройки окна>''
 
==== Настройки шрифта ====
 
''<подробно про настройки шрифта>''
 
==== Настройки ввода ====
 
''<подробно про настройки ввода>''
 
  
=== terminal_put ===
+
При использовании MSVC приложение линкуется с "интерфейсной библиотекой" BearLibTerminal.lib
<syntaxhighlight lang="cpp">
 
void terminal_put(int x, int y, int code);
 
</syntaxhighlight>
 
Одна из основных функций библиотеки, позволяет вывести символ в знакоместо с указанными координатами.
 
  
Диапазон возможных для вывода кодов символов не ограничен выбранной при вызове <code>terminal_open</code> кодировкой (см. [[#Кодировки]]).
+
При использовании MinGW приложение нужно линковать непосредственно с BearLibTerminal.dll (файл .lib содержит лишь перечень функций для MSVC).
  
В зависимости от выбранного режима смешения, выводимый символ может заменить собой все содержимое указанного знакоместа или быть добавленным поверх уже имеющихся (см. <tt>[[#terminal_blending]]</tt>).
+
При использовании GCC под Linux приложение линкуется с libBearLibTerminal.so
=== terminal_color ===
 
<syntaxhighlight lang="cpp">
 
void terminal_color(color_t color);
 
</syntaxhighlight>
 
Устанавливает основной цвет выводимого текста. Параметром функции является целое беззнаковое 32-битное число, представляющее цвет в формате ARGB, например 0xFFFF0000 -- сплошной красный, 0x800000FF -- полупрозрачный синий.
 
  
См. [[#color_from_argb]], [[#color_from_name]], [[#Постформатирование]].
+
==== C# ====
=== terminal_bkcolor ===
+
Используется враппер BearLibTerminal.cs, который должен быть включен в состав проекта.
<syntaxhighlight lang="cpp">
 
void terminal_bkcolor(color_t color);
 
</syntaxhighlight>
 
Аналогичная <code>terminal_color</code> функция, но устанавливающая цвет фона выводимых символов.
 
  
В зависимости от режима смешения, цвет фона может применяется к знакоместу только в случае, если символ является первым в знакоместе (см. <tt>[[#terminal_blending]]</tt>).
+
==== Nim ====
=== terminal_blending ===
+
Используется враппер [https://github.com/bearlib/terminal-nim BearLibTerminal.nim], который должен быть включен в состав проекта.
<syntaxhighlight lang="cpp">
 
void terminal_blending(int mode);
 
</syntaxhighlight>
 
Функция устанавливает режим смешения для вывода символов: <code>BLENDING_NONE</code> или <code>BLENDING_ADDITIVE</code>.
 
  
В режиме <code>BLENDING_NONE</code> выводимый символ полностью замещает содержимое соответствующего знакоместа, цвет фона устанавливается в выбранный посредством <tt>[[#terminal_bkcolor]]</tt> цвет. Это обычное поведение терминал-подобных приложений.
+
==== Lua ====
 +
Интерфейс для Lua включен непосредственно в библиотеку.
  
В режиме <code>BLENDING_ADDITIVE</code> выводимый символ "накладывается" на уже имеющиеся в ячейке символы, причем каждый отдельный символ в получившейся "стопке" может иметь индивидуальный цвет. Таким образом можно комбинировать глифы и/или тайлы для получения более сложных фигур. Цвет фона знакоместа обновляется только при выводе самого первого символа.
+
Под Windows достаточно использовать любой динамически собранный интерпретатор Lua, например [https://github.com/rjpcomputing/luaforwindows Lua for Windows]. Вызов <code>require "BearLibTerminal"</code> подгрузит файл BearLibTerminal.dll как бинарный модуль.
=== terminal_printf ===
 
<syntaxhighlight lang="cpp">
 
// ANSI/UTF-8
 
size_t terminal_printf(int x, int y, const char* format, ...);
 
size_t terminal_printf_noformat(int x, int y, const char* s);
 
  
// UTF-16
+
Под Linux файл библиотеки имеет имя libBearLibTerminal.so, но так как бинарные модули Lua не имеют префикса lib, придется переименовать его в BearLibTerminal.so
size_t terminal_wprintf(int x, int y, const wchar_t* format, ...);
 
size_t terminal_wprintf_noformat(int x, int y, const wchar_t* s);
 
</syntaxhighlight>
 
...
 
=== terminal_clear ===
 
<syntaxhighlight lang="cpp">
 
void terminal_clear();
 
</syntaxhighlight>
 
Функция очистки экрана. Содержимое всех ячеек-знакомест удаляется, цвет фона устанавливается в выбранный посредством <tt>[[#terminal_bkcolor]]</tt> цвет.
 
=== terminal_clear_area ===
 
<syntaxhighlight lang="cpp">
 
void terminal_clear_area(int x, int y, int w, int h);
 
</syntaxhighlight>
 
Функция частичной очистки экрана. Содержимое ячеек-знакомест в указанной области экрана удаляется, цвет фона устанавливается в выбранный посредством <tt>[[#terminal_bkcolor]]</tt> цвет.
 
=== terminal_refresh ===
 
<syntaxhighlight lang="cpp">
 
void terminal_refresh();
 
</syntaxhighlight>
 
Функция обновления экрана. Эта функция должна быть вызвана, чтобы изменения содержимого терминала на самом деле отобразились на экране.
 
  
Окно терминала инициализируется и выводится на экран при первом вызове <code>terminal_refresh</code>.
+
==== FreePascal/Delphi ====
=== terminal_has_input ===
+
Используется враппер BearLibTerminal.pas, который должен быть включен в состав проекта.
<syntaxhighlight lang="cpp">
 
int terminal_has_input();
 
</syntaxhighlight>
 
Позволяет узнать, есть ли события в очереди ввода. Возвращает 0, если очередь пуста или 1, если есть непрочитанные события.
 
  
См. [[#Ввод]]
+
==== Python ====
=== terminal_get ===
+
Для Python есть пакеты библиотеки для Windows, Linux и OS X (включающие в себя соответствующий бинарный файл: .dll/.so/.dylib). Поэтому для установки достаточно просто выполнить:
<syntaxhighlight lang="cpp">
 
int terminal_get();
 
</syntaxhighlight>
 
Возвращает код следующего событие из очереди ввода.
 
  
Если очередь ввода пуста, поведение зависит от параметра ''input.timeout'':
+
<code>pip install bearlibterminal</code>
* ''infinite'': выполнение программы блокируется до поступления следующего события ввода.
 
* ''N'' (где N -- некоторое неотрицательное значение): выполнение программы блокируется до поступления события ввода, но не более чем на N миллисекунд, по истечении которых возвращается -1.
 
  
Если ''input.timeout'' равен нулю, блокирования выполнения программы не производится, в случае пустой очереди ввода функция немедленно возвращает -1.
+
Команда установки может отличаться: для Python3 утилита pip обычно называется pip3, также может быть полезно добавить флаг --user (установка только для текущего пользователя).
  
См. [[#Ввод]]
+
==== Ruby ====
=== terminal_get_str ===
+
Используется враппер BearLibTerminal.rb, который должен быть включен в состав проекта.
<syntaxhighlight lang="cpp">
 
int terminal_get_str(int x, int y, char* buffer, int max); // ANSI/UTF-8
 
int terminal_get_wstr(int x, int y, wchar_t* buffer, int max); // UTF-16
 
</syntaxhighlight>
 
Функция чтения текста с клавиатуры с учетом локалей и раскладок пользователя.
 
  
В процессе работы функции ввод полностью обрабатывается терминалом. Набираемые пользователем символы добавляются к строке в буфере <code>buffer</code>, при этом максимальный размер получаемой строки ограничивается <code>max</code> символами. В это время содержимое строки и курсор ввода отображается в терминале начиная с позиции (<code>x</code>, <code>y</code>).
+
== Примеры использования ==
 +
"Hello, world" на нескольких языках:
  
''TODO: картинка-иллюстрация''
+
==== C/C++ ====
 +
<source lang="cpp">
 +
#include <BearLibTerminal.h>
  
Чтение очереди ввода функцией <code>terminal_get_str</code> производится до:
+
TERMINAL_TAKE_CARE_OF_WINMAIN // Но можно и самостоятельно определить WinMain
* Подтверждения ввода (поступления события VK_RETURN), функция возвращает количество введенных символов (может быть и 0).
 
* Отмены ввода (поступления события VK_ESCAPE или VK_CLOSE), функция возвращает -2 (TERMINAL_INPUT_CANCELLED).
 
* Истечения отведенного промежутка времени (таймаута), функция возвращает -1 (TERMINAL_INPUT_TIMED_OUT).
 
  
Величина таймаута, в течении которого производится ввод и в течении которого вводимая строка отображается на экране зависит от значения параметра '''input.timeout''':
+
int main()
* ''infinite'': неограниченно, до поступления событий VK_RETURN, VK_ESCAPE или VK_CLOSE.
+
{
* ''N'' (где N -- некоторое неотрицательное значение): N миллисекунд.
+
  terminal_open();
  
Если ''input.timeout'' равен нулю, блокирования ввода и отображения вводимой строки на экране не производится, функция обрабатывает доступные сообщения в очереди ввода и немедленно завершается, возвращая одно из перечисленных выше значений.
+
  // Выводим текст
 +
  terminal_printf(1, 1, "Hello, world!");
 +
  terminal_refresh();
  
По завершении, <code>terminal_get_str</code> убирает введенную строку и курсор ввода с экрана, восстанавливая предыдущее содержимое использованных ячеек-знакомест.
+
  // Ждем, пока пользователь не закроет окно
 +
  while (terminal_read() != VK_CLOSE);
  
Иначе говоря, при значении ''input.timeout'' = ''infinite'' (значение по умолчанию), функция <code>terminal_get_str</code> производит чтение строки "до победного конца": до подтверждения или отмены ввода, полностью забирая на себя ответственность по отображению вводимого текста на экране. Пользователю библиотеки остается лишь проверить возвращенное значение и, в случае успешного завершения, использовать готовую строку в буфере <code>buffer</code>.
+
  terminal_close();
 
+
}
Значение ''input.timeout'', равное или большее нуля, позволяет организовать "неблокирующий" ввод строки. Результат выполнения <code>terminal_getstr</code> появляется на экране на N миллисекунд, по истечении которых можно быстро обновить анимацию и продожить ввод дальше -- и так до тех пор, пока функция не вернет неотрицатильное значение (пользователь завершил ввод) или -2 (пользователь отменил ввод).
+
</source>
 
 
Размер передаваемого в функцию буфера должен быть достаточно большим, чтобы вместить максимально возможную вводимую строку. Так как параметр max указывается в символах, это означает, что для вызова в кодировке UTF-8 (<code>terminal_get_str</code>) буфер должен быть размером не менее max*3+1 (каждый символ может занять до трех байт + нуль-терминатор), а для UTF-16 вызова (<code>terminal_get_wstr</code>) -- не менее max+1.
 
  
См. [[#Ввод]]
+
==== Python ====
=== terminal_state ===
+
<source lang="python">
<syntaxhighlight lang="cpp">
+
from bearlibterminal import terminal
int terminal_state(int code);
 
</syntaxhighlight>
 
...
 
=== terminal_use_image ===
 
<syntaxhighlight lang="cpp">
 
int terminal_use_image(int code, const char* file); // ANSI/UTF-8
 
int terminal_use_wimage(int code, const wchar_t* file); // UTF-16
 
</syntaxhighlight>
 
Функция, позволяющая загрузить и использовать в качестве спрайта произвольное изображение. В параметре ''code'' указывается код "символа", с которым будет ассоциировано изображение, а в параметре -- имя файла с изображением. Допускается загрузка из PNG, BMP и JPEG.
 
Загруженное изображение выводится на экране вместо символа с указанным кодом:
 
<syntaxhighlight lang="cpp">
 
terminal_use_image(0xE000, "tile1.png");
 
terminal_put(10, 10, 0xE000);
 
</syntaxhighlight>
 
В приведенном случае вместо символа с кодом 0xE000 (которого в шрифте все равно нет, так как это код из специально оставленной пустой области Unicode), на экране начиная с позиции (10, 10) будет отрисована картинка из файла "tile1.png".
 
  
Следует учитывать порядок отрисовки. Все клетки в BearLibTerminal отрисовываются строго построчно, слева направо, строки сверху вниз. Обычно символы вписываются в границы клеток, не пересекаются и порядок вывода не имеет значения. Однако это может играть роль при выводе спрайтов:
+
terminal.open()
<syntaxhighlight lang="cpp">
 
terminal_use_image(0xE001, "tile2.png");
 
terminal_printf(20, 20, "a[uE001]b");
 
</syntaxhighlight>
 
Допустим, что картинка-спрайт из "tile2.png" имеет размер больше одного знакоместа. Тогда в 20 строке сначала будет выведен символ "a" (20 колонка), затем в картинка-спрайт (21 колонка), затем в символ "b" (22 колонка). Спрайт больше одного знакоместа и занял больше одной колонки, но символ "b" был отрисован позже и, тем самым, поверх спрайта.
 
  
''TODO: картинка-иллюстрация''
+
# Выводим текст
 +
terminal.printf(2, 1, 'Hello, world!')
 +
terminal.refresh()
  
Следует отметить, что спрайт всегда выводится начиная с левого верхнего угла клетки. С версии библиотеки R8, на размер спрайта особых ограничений не накладывается; разработчик должен сам следить, чтобы картинка аккуратно вписывалась в остальное текстовое содержимое на экране.
+
# Ждем, пока пользователь не закроет окно
=== color_from_argb ===
+
while terminal.read() != terminal.TK_CLOSE:
<syntaxhighlight lang="cpp">
+
  pass
color_t color_from_argb(int a, int r, int g, int b);
 
</syntaxhighlight>
 
Простая вспомогательная функция, собирающая из отдельных R, G, B и A компонент одно 32-битное число, которым представляется цвет в библиотеке (0xAARRGGBB).
 
=== color_from_name ===
 
<syntaxhighlight lang="cpp">
 
color_t color_from_name(const char* name);
 
</syntaxhighlight>
 
Данная функция возвращает цвет (его числовое представление) по имени из встроенной в библиотеку палитры. Эта палитра практически полностью повторяет [http://doryen.eptalys.net/data/libtcod/doc/1.5.2/html2/color.html палитру] из libtcod. Имя указывается в виде "оттенок" или "яркость оттенок", где возможными значениями являются:
 
{| class="wikitable"
 
|-
 
|Яркость
 
|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
 
|}
 
Также, по имени цвет можно использовать в тегах ''color'' и ''bkcolor'' функции <code>terminal_printf</code>:
 
<syntaxhighlight lang="cpp">
 
terminal_color(color_from_name("lighter gray")); // Основным цветом выбран светло-серый
 
terminal_printf(1, 1, "You see a [color=dark red]glowing[/color] stone."); // Слово glowing будет темно-красным
 
</syntaxhighlight>
 
== Кодировки ==
 
...
 
== Ввод ==
 
...
 
== Примеры ==
 
<syntaxhighlight lang="cpp">
 
#include <bearlibterminal.h>
 
#include <Windows.h>
 
  
int CALLBACK WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
+
terminal.close()
{
+
</source>
terminal_open(CODEPAGE_DEFAULT);
 
 
// Выводим текст
 
terminal_printf(1, 1, "Hello, world!");
 
terminal_refresh();
 
  
// Ждем, пока пользователь не закроет окно
+
==== FreePascal/Delphi ====
while ( terminal_get() != VK_CLOSE );
+
<source lang="delphi">
 
terminal_close();
 
}
 
</syntaxhighlight>
 
BTW, зависимость от Windows.h будет исправлена со временем.
 
 
 
<syntaxhighlight lang="pascal">
 
 
uses
 
uses
   BeaRLibTerminal,
+
   BeaRLibTerminal;
  Windows;
 
  
 
begin
 
begin
   terminal_open(CODEPAGE_DEFAULT);
+
   terminal_open();
 
   
 
   
 
   // Выводим текст
 
   // Выводим текст
   terminal_printf(1, 1, 'Hello, world!');
+
   terminal_print(1, 1, 'Hello, world!');
 
   terminal_refresh();
 
   terminal_refresh();
  
 
   // Ждем, пока пользователь не закроет окно
 
   // Ждем, пока пользователь не закроет окно
   while ( terminal_get() <> VK_CLOSE ) do ;  
+
   while (terminal_read() <> TK_CLOSE) do;  
 
   
 
   
 
   terminal_close();
 
   terminal_close();
 
end.
 
end.
</syntaxhighlight>
+
</source>
 +
 
 +
==== C# ====
 +
<source lang="csharp">
 +
using System;
 +
using BearLib;
 +
 
 +
namespace HelloWorld
 +
{
 +
  static class Program
 +
  {
 +
    static void Main()
 +
    {
 +
      Terminal.Open();
 +
 
 +
      // Выводим текст
 +
      Terminal.Print(1, 1, "Hello, world!");
 +
      Terminal.Refresh();
 +
 
 +
      // Ждем, пока пользователь не закроет окно
 +
      while (Terminal.Read() != Terminal.Keys.Close);
 +
 
 +
      Terminal.Close();
 +
    }
 +
  }
 +
}
 +
</source>
 +
 
 +
==== Nim ====
 +
<source lang="nimrod">
 +
import BearLibTerminal
 +
 
 +
terminal_open()
 +
 
 +
# Выводим текст
 +
discard terminal_print(1, 1, "Hello, world!")
 +
terminal_refresh()
 +
 
 +
var key = terminal_read()
 +
 
 +
# Ждем, пока пользователь не закроет окно
 +
while key != TK_CLOSE and key != TK_ESCAPE:
 +
  key = terminal_read()
 +
 
 +
terminal_close()
 +
</source>
 +
 
 +
==== Lua ====
 +
<source lang="lua">
 +
local T = require "BearLibTerminal"
 +
 
 +
T.open()
 +
-- Выводим текст
 +
T.print(1, 1, "Hello, World!")
 +
T.refresh()
 +
repeat
 +
key = T.read()
 +
-- Ждем, пока пользователь не закроет окно
 +
until key == T.TK_CLOSE or key == T.TK_ESCAPE
 +
T.close()
 +
</source>
  
 
[[Category:BeaRLib]]
 
[[Category:BeaRLib]]

Текущая версия на 20:21, 11 сентября 2017

BearLibTerminal — это небольшая (в интерфейсном плане) библиотека для организации терминал-подобного окна, вывода текста, обработки простого ввода.

Большое количество roguelike совершенно осознанно используют аскетичное символьное/псевдографическое оформление. Однако, использование стандартных средств вывода (командной строки ОС) сопряжено с досадными ограничениями скорости вывода, цветовой гаммы, используемого шрифта. Нетривиальной задачей оказывается и применение расширенного набора символов, например нескольких языков и псевдографики. BearLibTerminal позволяет обойти упомянутые ограничения оставаясь в рамках простой концепции "терминала": пользователю предоставляется прямоугольная сетка ячеек-знакомест, средства для вывода текста и чтения ввода с клавиатуры.

Достойными внимания особенностями терминала являются:

  • Легкость использования Unicode.
  • Использование тайловых (в виде картинки) и векторных (TrueType) шрифтов.
  • Расширенный вывод символов: композиция, центрирование, смещение.
  • Высокая скорость вывода (в основе лежит OpenGL).
  • Поддержка как клавиатуры, так и мыши.
  • Сборки под Windows, Linux и OS X.
  • Привязки к нескольким языкам: С/С++, C#, Lua, Pascal, Python, Ruby.

BearLibTerminal не является:

  • Фреймворком roguelike: в библиотеке нет и никогда не будет генераторов случайных чисел, уровней или имен персонажей, механизмов расчета FOV/LOS и освещения, средств для работы с файлами или сетью.
  • Графическим движком общего назначения: функциональность библиотеки сознательно ограничивается функциональностью псевдотерминала (спорное утверждение для версий 0.9+).

Похожие инструменты: Tinycurses, libtcod.

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

Наиболее актуальная документация размещена на сайте библиотеки:

Установка

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

C/C++

Используется заголовочный файл BearLibTerminal.h

При использовании MSVC приложение линкуется с "интерфейсной библиотекой" BearLibTerminal.lib

При использовании MinGW приложение нужно линковать непосредственно с BearLibTerminal.dll (файл .lib содержит лишь перечень функций для MSVC).

При использовании GCC под Linux приложение линкуется с libBearLibTerminal.so

C#

Используется враппер BearLibTerminal.cs, который должен быть включен в состав проекта.

Nim

Используется враппер BearLibTerminal.nim, который должен быть включен в состав проекта.

Lua

Интерфейс для Lua включен непосредственно в библиотеку.

Под Windows достаточно использовать любой динамически собранный интерпретатор Lua, например Lua for Windows. Вызов require "BearLibTerminal" подгрузит файл BearLibTerminal.dll как бинарный модуль.

Под Linux файл библиотеки имеет имя libBearLibTerminal.so, но так как бинарные модули Lua не имеют префикса lib, придется переименовать его в BearLibTerminal.so

FreePascal/Delphi

Используется враппер BearLibTerminal.pas, который должен быть включен в состав проекта.

Python

Для Python есть пакеты библиотеки для Windows, Linux и OS X (включающие в себя соответствующий бинарный файл: .dll/.so/.dylib). Поэтому для установки достаточно просто выполнить:

pip install bearlibterminal

Команда установки может отличаться: для Python3 утилита pip обычно называется pip3, также может быть полезно добавить флаг --user (установка только для текущего пользователя).

Ruby

Используется враппер BearLibTerminal.rb, который должен быть включен в состав проекта.

Примеры использования

"Hello, world" на нескольких языках:

C/C++

<source lang="cpp">

  1. include <BearLibTerminal.h>

TERMINAL_TAKE_CARE_OF_WINMAIN // Но можно и самостоятельно определить WinMain

int main() {

 terminal_open();
 // Выводим текст
 terminal_printf(1, 1, "Hello, world!");
 terminal_refresh();
 // Ждем, пока пользователь не закроет окно
 while (terminal_read() != VK_CLOSE); 
 terminal_close();

} </source>

Python

<source lang="python"> from bearlibterminal import terminal

terminal.open()

  1. Выводим текст

terminal.printf(2, 1, 'Hello, world!') terminal.refresh()

  1. Ждем, пока пользователь не закроет окно

while terminal.read() != terminal.TK_CLOSE:

 pass

terminal.close() </source>

FreePascal/Delphi

<source lang="delphi"> uses

 BeaRLibTerminal;

begin

 terminal_open();

 // Выводим текст
 terminal_print(1, 1, 'Hello, world!');
 terminal_refresh();
 // Ждем, пока пользователь не закроет окно
 while (terminal_read() <> TK_CLOSE) do; 

 terminal_close();

end. </source>

C#

<source lang="csharp"> using System; using BearLib;

namespace HelloWorld {

 static class Program
 {
   static void Main()
   {
     Terminal.Open();
     // Выводим текст
     Terminal.Print(1, 1, "Hello, world!");
     Terminal.Refresh();
     // Ждем, пока пользователь не закроет окно
     while (Terminal.Read() != Terminal.Keys.Close);
     Terminal.Close();
   }
 }

} </source>

Nim

<source lang="nimrod"> import BearLibTerminal

terminal_open()

  1. Выводим текст

discard terminal_print(1, 1, "Hello, world!") terminal_refresh()

var key = terminal_read()

  1. Ждем, пока пользователь не закроет окно

while key != TK_CLOSE and key != TK_ESCAPE:

 key = terminal_read()

terminal_close() </source>

Lua

<source lang="lua"> local T = require "BearLibTerminal"

T.open() -- Выводим текст T.print(1, 1, "Hello, World!") T.refresh() repeat key = T.read() -- Ждем, пока пользователь не закроет окно until key == T.TK_CLOSE or key == T.TK_ESCAPE T.close() </source>