lights FAQ Forum

Portable UI (WIP)


Text rendering API for C, Terra and LuaJIT ffi use


	Text rendering API for C, Terra and LuaJIT ffi use.

	- self-allocating constructors.
	- fatal and non-fatal error checking and reporting.
	- validation and clamping of enums, indices, counts, sizes, offsets, etc.
	- state invalidation when changing input values.
	- state checking when accessing computed values.
	- utf8 text input and output.
	- text representation for features, lang, script.
	- checking if a span property has the same value across an offset range.
	- updating span properties on an offset range with removing duplicate spans.
	- inserting and removing text at an offset with adjusting span offsets.
	- text navigation, selection and editing through cursor objects.

	- using consecutive enum values for forward ABI compatibility.
	- using enlarged number types for forward ABI compat. and clamping inf/-inf.
	- renaming functions and types to C conventions for C use.
	- binding methods and getters/setters via ffi.metatype for LuaJIT use.

	Design considerations:

	- invalid input data should never cause fatal errors or crashes. At worst
	  (eg. on invalid span offsets), nothing is displayed and some sensible
	  default is returned for computed values. Invalid API _usage_ however
	  (eg. wrong call order or missing calls) should cause an assertion failure.
	- the order in which layout and span properties are set is not important
	  in order to avoid call-order dependencies.


	- make a renderer object, supplying font load and unload callbacks.
	- make a layout object from said renderer.
	- set the text and text properties on the layout object.
	- add text spans and set text span properties on the layout object.
	- you can set any font_id except -1: the font load callback will be called
	  with your font_ids, but note: never use the same font id for a different
	  font because caches work on font_id! if you load files with embedded
	  fonts like PDFs, always generate new font ids or perfect-hash the font
	  contents and use that as an id.
	- call layout() then paint(). change any properties,
	  check if `pixels_valid` is false and issue a repaint if it is.
	- navigate, hit-test, select and edit the text with cursors.


See the source code for more info.
Pkg type:Terra
Version: 561f751
Last commit:
Author: Cosmin Apreutesei
License: Public Domain

Required by: terra.layer