Scope and limitations

cl-ft2 covers what FreeType is good at: opening fonts, scaling, hinting, rasterising, outlines, stroking and variations. Some jobs that FreeType can partly do are deliberately left to other libraries in the same text stack.

Left to other libraries

Need	Use	Why
Text shaping: GPOS kerning, ligatures, mark positioning, contextual forms, complex scripts	HarfBuzz (cl-harfbuzz)	FreeType does not shape. kerning reads only the legacy kern table, which most modern OpenType fonts do not carry.
OpenType tables: GSUB/GPOS features, name, OS/2, color layers (COLR/CPAL) as data	HarfBuzz's typed OpenType APIs	It parses and validates these tables properly. COLRv0 glyphs still render through cl-ft2 as :bgra bitmaps with :color.
Bidi, script runs, line breaking, grapheme clusters, normalization	ICU (cl-icu)	Not FreeType's domain.
Layout: lines, paragraphs, alignment, hit testing	cl-textrender	Built on cl-icu and cl-harfbuzz.
Finding installed fonts by family or style	fontconfig, or bundle your fonts	cl-ft2 opens the path or octets you give it.

FreeType features not bound

Feature	Instead
Cache subsystem (FTC_*)	Cache bitmaps, outline lists or glyph objects in Lisp hash tables. They are ordinary Lisp data or explicitly destroyed objects.
Custom input streams (FT_Stream, FT_Open_Face with FT_Open_Args)	open-face accepts octet vectors, so read the data however you like.
LCD filter selection (FT_Library_SetLcdFilter)	Define it through cl-ffi; see FFI layer.
Glyph slot hinting deltas (lsb_delta, rsb_delta)	Read them through cl-ft2/ffi; see FFI layer.
FT_Outline_Embolden, FT_GlyphSlot_Oblique	Use a stroker with :border :outside, and face-transform-matrix with a shear.
Module properties (FT_Property_Set), such as hinting engine or darkening	Call through cl-ffi on library-handle.
Multiple sizes per face (FT_New_Size, FT_Activate_Size)	Open the font once per size.
SVG glyph rendering hooks	Load with :no-svg and use an outline or bitmap fallback.
Adobe Multiple Masters-specific APIs (FT_Set_MM_Design_Coordinates)	The variation API covers MM fonts through the same interface.

Behaviour to be aware of

• Not thread-safe. Use one library per thread, or a lock. See Core concepts.
• One glyph slot per face. Every load replaces it, including loads by other code that uses the same FT_Face, such as a HarfBuzz font.
• No finalizers. Destroy objects with destroy-… or the with-… macros. destroy-library destroys everything made in a library.
• FreeType 2.13.1 or newer is required at run time. With older versions some variation functions (FT_Get_Default_Named_Instance) are missing.
• Integer pixel sizes. size-metrics-x-ppem and -y-ppem are integers even for fractional face-size sizes. The scales and the glyphs themselves are exact.