Introduction

STLL is a simple text layouting engine specifically designed for all the applications that need good text output with support for many languages including ones with writing systems that to right to left (like Hebrew).

There are a lot of simple text output libraries out there, but all of them only support basic left to right text, not formatting no font organisation.

There is also Pango. But Pango is way too big and way too complicated for smaller applications.

This library is supposed to be in the middle between the heavyweight Pango and the trivial libraries like SDL_ttf. It is supposed to support all line-based text systems. Column based support is not planned.

Current home of the library is at github.

Design Goals

STLL has the following design goals

support all line based writing systems (as far as I know there is no actively used writing system in the world that is purely column based).
simple interface: the interface for normal tasks should be plain and easy.
high quality: the output of the library should be as high quality as feasible, which means: exact letter placement with interpolation, wherever possible sub-pixel placement of letters, proper gamma calculations to get the right glyph strokes
speed and low memory consumption are not a priority. But as long as you do not want to layout Megabytes of text the code should be fast enough

Dependencies

STLL depends on some libraries. The following libraries must be installed

harfbuzz: used for layouting text
freetype: used for reading and rendering fonts
linebreak or unibreak: implementation of the unicode line-break and word-break algorithm
fribidi: implementation of the unicode bidi algorithm

optionally the following needs to be installed

SDL, glfw, glew: when available the corresponding examples are build
pugixml, libxml2: when available XHTML parser using the corresponding xml-library will be build
doxygen, lconv: used for tests and documentation
boost: used to compile the tests and in example 3 to load the compressed hyphenation dictionary

Getting started

First, install all required libraries and tools.

On Debian/Wheezy, you can accomplish this via:

1 aptitude install libsdl1.2-dev libfreetype6-dev libharfbuzz-dev libglib2.0-dev libfribidi-dev libboost-test-dev libpugixml-dev liblinebreak2-dev lcov doxygen

On Debian/Jessie and above, you can accomplish this via:

1 aptitude install libsdl1.2-dev libfreetype6-dev libharfbuzz-dev libglib2.0-dev libfribidi-dev libboost-test-dev libpugixml-dev libunibreak-dev lcov doxygen

Clone the Git repository:

1 git clone https://github.com/stll/STLL.git

2 cd STLL

Build the library via CMake:

1 cmake .

2 make

You may want to run the test suite afterwards:

1 make test

Design of the library

The library is split into some parts that can be used independently and that are designed in a way that allows you to limit your dependencies.

Freetype wrapper

The first part is a small Freetype 2 wrapper, that only wraps the library and font face structures of the library into classes. It also provides some helper functions to handle fonts and to avoid loading the same font multiple times.

This part of the library has only freetype and boost as a dependency.

XML Library wrapper

STLL is written in such a way that it can use different XML libraries. There is one header that abstracts away the DOM tree creation and traversing.

Paragraph Layouter

The next part of the library is the layouter. The layouter will create a text layout out of a given text with additional layouting information.

The layout is just a collection of drawing commands that a system dependent graphics library can use to output the text.

If you have only very simple layouting tasks like some simple texts in a rectangular box or so, you can use this part only and stay away from the rest.

This part of the library has additional dependencies: fribidi, harfbuzz and liblinebreak or libunibreak. All these libraries are used to layout the text according to unicode specifications.

XHTML Layouter

This part of the library contains a more complex layouter that can be used for more complicated text output like an on-line help system.

It implements a part of the HTML5 specification but uses XHTML syntax for it. It uses a simple CSS emulation to define the looks of your text.

The XHTML layouter uses the paragraph layouter to layout single paragraphs of text.

This part introduces pugixml or libxml2 as dependency for the parsing.

Output Drivers

The library also contains a few drivers for different graphic libraries to output the generated layouts. Right now we have drivers for

SDL
OpenGL (different versions of the API)

Of course these drivers will add a dependency on the corresponding graphics library.

Additional Tools

Finally some additional tools are probably going to be added:

Hyphenation library. This will automatically add soft hyphens to XHTML or normal text to improve the output of the text when using longer texts.
'Ellipsiation'. In some GUI elements there might not be enough space for the complete text. This library will automatically shorten the text until it has a certain maximal length by replacing text with '...'