This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Library and faces

Library

make-library → library

Initialises a new FreeType library (FT_Init_FreeType) and returns a library.

destroy-library library

Destroys every face, glyph and stroker still live in library, then the library itself. A library that is already destroyed is left alone. Returns no values.

with-library (var) &body body

Binds var to a fresh library around body and calls destroy-library on exit.

library-live-p library → boolean

True until destroy-library.

library-version library → major, minor, patch

The version of the FreeType library that was loaded, as three values:

(ft2:library-version lib)   ; => 2, 14, 3

A live library prints with its version: #<LIBRARY 2.14.3 {…}>.

library-handle library → pointer

The raw FT_Library, for use with cl-ft2/ffi. It stays valid until destroy-library. Signals :invalid-library-handle if the library has been destroyed.

---

Opening faces

open-face library source &key (index 0) instance → face

Opens face number index of source in library.

• source is one of:

  • a string, passed to FreeType as a native filename, unchanged. Characters such as [ and ], common in variable font names like Inter[wght].ttf, are safe, because the string is never parsed as a Lisp namestring.
  • a pathname, converted with uiop:native-namestring.
  • a vector of (unsigned-byte 8) holding the font data. The octets are copied into foreign memory that the face owns, so you may reuse or discard the vector.

  These make up the type font-source; anything else is a type-error.

• index selects a face in a font collection (.ttc, .otc, .dfont). face-num-faces says how many there are. It must be in 0..65535.

• instance, for a variable font, selects a named instance by its index from 0, as face-named-instances lists them. The face then reports that instance's style name. nil (the default) means no named instance.

(ft2:open-face lib "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf")
(ft2:open-face lib #p"~/fonts/NotoSansCJK.ttc" :index 2)
(ft2:open-face lib "Inter.ttf" :instance 3)
(ft2:open-face lib (alexandria:read-file-into-byte-vector "font.otf"))

Errors: :cannot-open-resource (missing or unreadable file), :unknown-file-format (not a font), :invalid-file-format, :invalid-table or :invalid-offset (a damaged font). For a non-zero index or an instance, the report also suggests checking how many faces or instances exist.

destroy-face face

Destroys face. Before the FT_Face is destroyed, it calls release-face-dependent on every registered face dependent, and it frees the font buffer of a face opened from octets. A face that is already destroyed is left alone.

with-face (var library source &key index instance) &body body

Binds var to (open-face library source …) around body and calls destroy-face on exit.

face-live-p face → boolean

True until destroy-face or destroy-library.

face-library face → library

The library the face was opened in.

face-handle face → pointer

The raw FT_Face, valid until destroy-face. See FFI layer and Face dependents.

A live face prints as #<FACE "DejaVu Sans" "Book" {…}>.

---

Identity and format

Function	Returns	DejaVu Sans
face-family-name face	family name, or nil	"DejaVu Sans"
face-style-name face	style name, or nil	"Book"
face-postscript-name face	PostScript name, or nil	"DejaVuSans"
face-font-format face	FreeType's format name: "TrueType", "CFF", "Type 1", "BDF", "PCF", "Windows FNT", …	"TrueType"
face-num-faces face	number of faces in the file (more than 1 for a collection)	1
face-index face	this face's index in the file, as given to open-face's :index. The named instance is reported separately, by face-named-instance	0
face-num-glyphs face	number of glyphs. Valid glyph indexes are 0 to n − 1	6253

Flags

face-flags face → list of keywords

The FT_FACE_FLAG_… bits that are set, as keywords:

Keyword	Meaning
:scalable	outline font that can be scaled to any size
:fixed-sizes	has bitmap strikes (face-strikes)
:fixed-width	monospaced
:sfnt	TrueType / OpenType container
:horizontal	has horizontal metrics (almost always)
:vertical	has vertical metrics (vhea/vmtx)
:kerning	has a legacy kern table that kerning can read
:fast-glyphs	obsolete
:multiple-masters	variable font or Adobe Multiple Masters
:glyph-names	stores glyph names (glyph-index-name)
:external-stream	opened from a custom stream (never set by cl-ft2)
:hinter	has its own hinting bytecode
:cid-keyed	CID-keyed font
:tricky	needs its own hinting to look right (some CJK fonts)
:color	has color glyphs (COLR/CPAL, CBDT, sbix)
:variation	variation coordinates have been set away from the named instance or defaults
:svg	has an SVG table
:sbix	has an sbix table
:sbix-overlay	sbix glyphs are drawn over the outline

(ft2:face-flags face)   ; => (:SCALABLE :SFNT :HORIZONTAL :KERNING :GLYPH-NAMES :HINTER)

face-style-flags face → list

:italic and/or :bold. Instance counts that FreeType packs into the high bits are masked off.

Predicates

Function	True when
face-scalable-p	:scalable is set
face-fixed-width-p	:fixed-width is set
face-has-kerning-p	:kerning is set
face-has-glyph-names-p	:glyph-names is set
face-italic-p	:italic is a style flag
face-bold-p	:bold is a style flag
face-variable-p	:multiple-masters is set (see Font variations)

Global metrics (font units)

All in font units. Divide by face-units-per-em and multiply by the pixel size, or use face-size-metrics (see Sizes and transforms) for the scaled values.

Function	Meaning	DejaVu Sans
face-units-per-em	font units per em square; 0 for a bitmap-only face	2048
face-ascender	typographic ascender	1901
face-descender	typographic descender (usually negative)	−483
face-height	default baseline-to-baseline distance	2384
face-max-advance-width	largest horizontal advance
face-max-advance-height	largest vertical advance
face-underline-position	position of the underline's centre
face-underline-thickness	underline thickness
face-bounding-box	xmin, ymin, xmax, ymax (four values) enclosing every glyph	−2090, −948, 3673, 2524

These metrics describe only scalable faces. For a bitmap-only face they are meaningless, so use the strike's metrics instead.