--[[

	Unicode text layouting and rendering engine in Terra with a C API.
	Written by Cosmin Apreutesei. Public Domain.

	A pure-Lua prototype of this library is at github.com/luapower/tr.
	Discuss at luapower.com/forum or at github.com/luapower/terra-tr/issues.

	Leverages harfbuzz, freetype, fribidi and libunibreak for text shaping,
	glyph rasterization, bidi reordering and line breaking respectively.

	Scaling and blitting a raster image onto another is out of the scope of
	the library. A module for doing that with `cairo` is included separately.

	NOTE: This is the implementation module. In here, invalid input data is
	undefined behavior and changing layout properties does not keep the
	internal state consistent. Use `tr_api` instead which takes care of that.

	Processing stages from rich text description to pixels on screen:

	* itemization     : split text into an array of segments (or segs).
	* shaping         : shape segments into arrays of glyphs (called glyph runs).
	* line-wrapping   : word-wrap segments and group them into an array of lines.
	* bidi-reordering : re-order mixed-direction segments on each line.
	* line-spacing    : compute each line's `y` based on the heights of its segments.
	* aligning        : align lines horizontally and vertically inside a box.
	* clipping        : mark which lines and segments as visible inside a box.
	* rasterization   : convert glyph outlines into bitmaps that are cached.
	* painting        : draw the visible text plus any selections and carets.

	The API for driving this process is:

	tr_itemize.t   shape()     itemization and shaping.
	tr_wrap.t      wrap()      line-wrapping.
	tr_align.t     spaceout()  line-spacing.
	tr_align.t     align()     justification and aligning.
	tr_clip.t      clip()      clipping.
	tr_paint.t     paint()     painting, with on-demand rasterization.

	The renderer object keeps four LRU caches: one for glyph runs, one for
	glyph images, one for memory fonts and one for memory-mapped fonts.
	Shaping looks-into and adds-to the glyph run cache. Rasterization
	looks-into and adds-to the glyph image cache. Fonts are loaded and cached
	when the span's font_id is set in tr_api. Glyph runs and fonts are
	ref-counted in the cache so while the layout is alive, even if the cache
	size limit is reached, segs won't lose their glyph runs and fonts will
	remain available for reshaping and rasterization.

	Also, there's two levels of rasterization: for glyph images and for entire
	glyph runs. With subpixel resolution, more than one image might end up
	being created for each subpixel offset encountered, which is why
	rasterization is done on-demand by painting.

]]

See the source code for more info.