API Reference

Separate pages covering different library parts in greater detail (work in progress):

• Configuration
• Input
• Output

The API consists of ~20 functions and a number of constants.

• Initialization and configuration: open, close, set
• Output state: color, bkcolor, composition, layer
• Output: clear, clear area, crop, refresh, put, pick, pick color, pick bkcolor, put ext, print, measure
• Input: state, check, has input, read, peek, read str
• Utility: delay, color from name, color from argb

Specifying the exact list of functions is tricky as underlying dynamic-link library exports an language-agnostic set of calls. The actual list of functions available to each programming language is slightly different.

For example, strings can be encoded using at least three character sizes: one (UTF-8 or ANSI), two (UTF-16) and four (UTF-32) bytes. Therefore for functions taking string arguments the dynamic-link library provides three separate calls. The C/C++ header file hides this fact by providing functions for more usual char and wchar_t string types, e. g. print and wprint. For some functions there are also variants with printf-like formatting, e. g. printf and wprintf. On the other hand, C# only use UTF-16 strings and formatting support is usually done by overloading the same function. So for C# there is only one printing function while C/C++ gets four.

Here the API is described briefly and mostly from pure C perspective. Language-specific peculiariries are listed on separate pages (not yet done).

open

int terminal_open();

This function initializes BearLibTerminal instance, configuring the window with default parameters: 80×25 cells, Fixedsys Excelsior font, white text on a black background. This function does not bring the window to screen. The window is not shown until the first call to refresh. Note that unless the library is initialized with successful call to open, all other library functions will do nothing but return immediately with return code (if any) indicating an error.

The function returns boolean value where false means initialization has failed. Details may be found in the log file (named bearlibterminal.log by default).

close

void terminal_close();

Symmetric to open, this function closes the window and deinitializes BearLibTerminal instance.

set

int terminal_set(const char* s); // + setf, wset, and wsetf flavours

This is probably the most complex function in BearLibTerminal API. Configuring library options and mechanics, managing fonts, tilesets and even configuration file is performed with it.

The function accepts a “configuration string” with various options described in it:

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

For an information about configuration string format, library options and overall function behavior, refer to the separate configuration page.

color

void terminal_color(color_t color);

This function sets the current foreground color which will be used by all output functions called later. The color_t type is a 32-bit unsigned integer describing color in BGRA (0xAARRGGBB) format. This numeric color representation can be constructed directly or by color from argb and color from name utility functions. For most languages including C++ there is also an overloaded version taking color name as a string (see color from name and language-specific notes).

The numeric value of current foreground color can be retrieved by reading TK_COLOR state.

bkcolor

void terminal_bkcolor(color_t color);

Similar to color this function sets the current background color. Otherwise the function behaves exactly as its foreground counterpart. Note that only the first, lowest layer of cells has background.

The numeric value of current background color can be retrieved by reading TK_BKCOLOR state.

composition

void terminal_composition(int mode);

This function sets character composition mode. When composition is off, putting a tile in a cell (by put or print) simply replaces the contents of that cell. When composition is on, however, the tile is added to the cell's tile stack. This has visual effect of combining several tiles into one. There is no enforced limit to number of tiles in a single cell. Note that each tile in the stack has its own foreground color and offset (see put ext).

Parameter mode may be one of: TK_OFF (default), TK_ON.

Current composition mode can be retrieved by reading TK_COMPOSITION state.

layer

void terminal_layer(int layer);

This function selects the current layer of character cells. The argument is an index from 0 to 255 where 0 is the lowest (default) layer. Only the first layer has background, for layers 1 and above the background color set by bkcolor has no effect. Note that clear area affects only the current layer while clear wipes the entire scene.

Layers are useful for various reasons. One is that BearLibTerminal allows tiles bigger than one character cell. But the scene is drawn cell by cell in fixed left-to-right, top-to-bottom order. This makes imposible for the big tile to properly cover cells to the right and below because those will be drawn later. With layers the scene can be separated into several parts with strict Z-ordering between them.

Another use of layers is to logically separate the scene. Layers can be cleared and updated independently, so one can place parts of the scene in separate layers and update them without touching the others (for example, animated dungeon level and static UI).

Current layer index can be read from TK_LAYER state slot.