Common Lisp Package: FREETYPE2

This is a general Freetype 2 wrapper for Common Lisp using CFFI. It's geared toward both using Freetype directly by providing a simplified API, as well as providing access to the underlying C structures and functions for use with other libraries which may also use Freetype.

README:

FUNCTION

Public

BITMAP-CONVERT (BITMAP ALIGNMENT &OPTIONAL (LIBRARY *LIBRARY*))

=> NEW-BITMAP Convert `BITMAP` to an 8bpp bitmap with `ALIGNMENT`-byte alignment.

BITMAP-NEW (&OPTIONAL (LIBRARY *LIBRARY*))

=> BITMAP Create a new FT_Bitmap.

BITMAP-TO-ARRAY (BITMAP)

=> ARRAY Convert `BITMAP` from internal `FT_Bitmap`'s internal representation to a native array. This is specified for a `FT-BITMAP-PIXEL-FORMAT` of `:MONO`, `:GRAY`, `:LCD`, and `:LCD-V`. Note that for :LCD and :LCD-V, the result is a either 3\*width or 3\*height, respectively. This may change in the future.

CHECK-FONT-FILE (PATHNAME &OPTIONAL (LIBRARY *LIBRARY*))

=> NUM-FACES or NIL Verify `PATHNAME` is a supported format by calling `FT_Open_Face` with a negative face index. If the face is supported, return the number of faces in the file. Otherwise, NIL.

DEFAULT-LOAD-RENDER (FACE CHAR VERTICAL-P)

=> BITMAP, ADVANCE, TOP, LEFT This is the default `LOAD-FUNCTION` for `DO-STRING-RENDER`. It is also called in the case that a custom `LOAD-FUNCTION` returns `NIL`, convenient for caching. Custom functions must be compatible, though any (non-`NIL`) value may be returned in the place of `BITMAP`. Note that cl-freetype2 does nothing else for you. If you want your cache populated, you must do this yourself, for instance, within the [`DO-STRING-RENDER`](#DO-STRING-RENDER) loop.

EXTRACT-FREETYPE (LIBRARY)

=> LIBRARY When retrieving an `FT-LIBRARY` handle from an object, using the resulting wrapper is unsafe because it's dependent on the object. Instead, use `EXTRACT-FREETYPE` to create a separate version. Note that this does **not** make it safe to discard the original handle, only extract references to it.

FACE-ASCENDER-PIXELS (FACE)

Return the max ascender for FACE, in pixels.

FACE-DESCENDER-PIXELS (FACE)

Return the max descender for FACE, in pixels.

FACE-METRICS (FACE)

=> x-ppem, y-ppem, x-scale, y-scale, ascender, descender, height, max-advance Return the *face* metrics for `FACE` as floating point values. If a size has not been selected for `FACE`, the results are undefined.

FIXED-FACE-P (FACE)

=> boolean Check if `FACE` is fixed-width according to its flags

FREETYPE-VERSION (&OPTIONAL (LIBRARY *LIBRARY*))

=> version-major, version-minor, version-patch Return the version of the library according to `FT_Library_Version`. This may differ from the constants acquired at compile-time.

GET-ADVANCE (FACE CHAR-OR-CODE &OPTIONAL LOAD-FLAGS)

=> advance-float Get the advance in `FACE` for `CHAR-OR-CODE`, optionally specifying `LOAD-FLAGS`. This attempts to use `FT_Get_Advance` to efficiently retrieve an advance. In this case, `LOAD-FLAGS` are not used. Failing this, this will load the glyph and retrieve the advance using `GET-LOADED-ADVANCE`, specifying `VERTICAL-P` by whether the :vertical-layout face-flag is set. This is generally slower, but many fonts do not have a facility for fast advance retrieval.

GET-CHAR-INDEX (FACE CHAR-OR-CODE)

=> index Get the index in `FACE` for `CHAR-OR-CODE`, which may be either a character, or an integer code.

GET-FSTYPE-FLAGS (FACE)

=> flags Get the fsType flags for `FACE`.

GET-GLYPH (FACE-OR-GLYPHSLOT)

=> GLYPH Get the `FT_Glyph` from `FACE-OR-GLYPHSLOT`.

GET-GLYPH-NAME (FACE CHAR-OR-CODE)

=> name-string Get the symbolic name and length in `FACE` for `CHAR-OR-CODE`.

GET-KERNING (FACE CHAR1 CHAR2 &OPTIONAL MODE)

=> kerning-float Get the kerning between `CHAR1` and `CHAR2` for `FACE`, optionally specifying the kerning mode `MODE`. By default this returns the kerning in *pixels*. If `MODE` is specified, an untranslated value is returned as per `FT`_Get_Kerning with the given flags.

GET-LOADED-ADVANCE (FACE VERTICAL-P)

=> advance-float Get the glyph advance value in `FACE` for the already-loaded glyph. If `VERTICAL-P` is true, get the vertical advance, otherwise, get the horizontal advance.

GET-NAME-INDEX (FACE GLYPH-NAME)

=> index Get the index for the glyph named `GLYPH-NAME` for `FACE`.

GET-OUTLINE (FACE-OR-GLYPHSLOT &OPTIONAL CHAR-OR-CODE)

=> OUTLINE-COPY Retrieve an outline *copy* from `FACE-OR-GLYPHSLOT`. If `CHAR-OR-CODE` is not nil, it will be loaded, and its outline retrieved. In this case, `FACE-OR-GLYPHSLOT` must be an `FT-FACE`. If you wish to retrieve the original outline, you may use `GET-GLYPH` and `FT-OUTLINEGLYPH-OUTLINE`, but you *must* retain the glyph for the outline to remain valid.

GET-POSTSCRIPT-NAME (FACE)

=> name-string Get the PostScript name for the Type1 or TrueType font `FACE`.

GET-STRING-ADVANCES (FACE STRING &OPTIONAL LOAD-FLAGS)

=> ARRAY Get an array of advances for the string `STRING` for face `FACE`, optionally specifying `LOAD-FLAGS`.

GET-STRING-KERNING (FACE STRING &OPTIONAL MODE)

=> ARRAY Return an array of kerning values for each pair of characters in `STRING`, for `FACE`, optionally specifying the kerning mode `MODE`. The results are as per `GET-KERNING`.

GET-TRACK-KERNING (FACE POINT-SIZE DEGREE)

=> ARRAY Return the track kerning at `POINT-SIZE` for `FACE` given `DEGREE`. See the documentation for `FT_Get_Track_Kerning`. It seems that only a few Type 1 fonts use this.

LOAD-CHAR (FACE CHAR-OR-CODE &OPTIONAL (LOAD-FLAGS DEFAULT))

Load a glyph in `FACE` for `CHAR-OR-CODE`, optionally specifying `LOAD-FLAGS`. `CHAR-OR-CODE` may be specified as per [`GET-CHAR-INDEX`](#GET-CHAR-INDEX).

LOAD-GLYPH (FACE GLYPH-INDEX &OPTIONAL (LOAD-FLAGS DEFAULT))

Load a glyph in `FACE` for `GLYPH-INDEX`, optionally specifying `LOAD-FLAGS`. Note that this requires a *glyph index*. To directly load a character or code, use [`LOAD-CHAR`](#LOAD-CHAR).

MAKE-FREETYPE

=> LIBRARY Create and initialize an `FT_Library` handle. This will warn if the library version differs from what cl-freetype2 was compiled with.

NEW-FACE (PATHNAME &OPTIONAL (INDEX 0) (LIBRARY *LIBRARY*))

Make a new `FT-FACE` from `PATHNAME`, optionally specifying `INDEX` as the face index.

OUTLINE-CHECK (OUTLINE)

=> boolean Validate `OUTLINE`.

OUTLINE-COPY (LIBRARY OUTLINE)

=> OUTLINE-COPY Make a copy of `OUTLINE`. Make sure `LIBRARY` is going to be valid for the life of the resulting copy. This means that if you got the value from an `FT_Face`, `FT_Glyph`, or similar parent, **that parent** must be valid, _along with_ the library itself, or use `EXTRACT-LIBRARY` to get a fresh handle.

OUTLINE-EMBOLDEN (OUTLINE STRENGTH)

Embolden `OUTLINE` by at most 4\*`STRENGTH` pixels.

OUTLINE-GET-BBOX (OUTLINE)

=> BBOX Get an exact bounding box for `OUTLINE`. This may differ from the CBox; refer to the FreeType2 API Reference for `FT_Outline_Get_BBox`.

OUTLINE-GET-CBOX (OUTLINE)

=> BBOX Get the control box for `OUTLINE`. This may differ from the BBox; refer to the FreeType2 API Reference for `FT_Outline_Get_CBox`.

OUTLINE-GET-ORIENTATION (OUTLINE)

=> [:fill-left | :fill-right | :none] Return the fill orientation for `OUTLINE`.

OUTLINE-REVERSE (OUTLINE)

Reverse the drawing direction of `OUTLINE`. See [OUTLINE-GET-ORIENTATION](#OUTLINE-GET-ORIENTATION) and the FreeType API Reference for `FT_Outline_Reverse`.

OUTLINE-TRANSFORM (OUTLINE MATRIX)

Transform `OUTLINE` using the 2x2 matrix `MATRIX`.

OUTLINE-TRANSLATE (OUTLINE X Y)

Translate `OUTLINE` by `X`,`Y`.

RENDER-GLYPH (FACE-OR-GLYPHSLOT &OPTIONAL (RENDER-MODE NORMAL))

Render the loaded glyph in `FACE-OR-GLYPHSLOT`, optionally specifying `RENDER-MODE`. Return the rendered glyphslot.

SET-CHAR-SIZE (FACE CHAR-WIDTH CHAR-HEIGHT HORZ-RESOLUTION VERT-RESOLUTION)

Set the size for `FACE` to `CHAR-WIDTH` and `CHAR-HEIGHT`, specified in 1/64 **points**. `HORZ-RESOLUTION` and `VERT-RESOLUTION` specify the DPI. If either `CHAR-WIDTH` or `CHAR-HEIGHT` are 0, the other value is used.

SET-PIXEL-SIZES (FACE PIXEL-WIDTH PIXEL-HEIGHT)

Set the size for `FACE` in **pixels** to `PIXEL-WIDTH` and `PIXEL-HEIGHT`. Especially useful for fixed-size bitmap fonts.

SET-TRANSFORM (FACE MATRIX DELTA)

Set the tranformation matrix for `FACE` to `MATRIX`, a 2x2 transformation matrix specified as per [`CONVERT-MATRIX`](cl-freetype2-types.html#CONVERT-MATRIX), and `DELTA`, a translation vector specified as per [`CONVERT-VECTOR`](cl-freetype2-types.html#CONVERT-VECTOR).

STRING-PIXEL-HEIGHT (FACE STRING &OPTIONAL (LOAD-FLAGS '(DEFAULT)))

Get the pixel height of STRING in FACE given LOAD-FLAGS.

STRING-PIXEL-WIDTH (FACE STRING &OPTIONAL (LOAD-FLAGS '(DEFAULT)))

Get the pixel width of STRING in FACE given LOAD-FLAGS.

Private

ABLIT (ARR1 ARR2 &KEY (X 0) (Y 0))

Destructivly copy arr2 into arr1 for 2- and 3-dimensional (Y:X, Y:X:RGB(A)) arrays. X and Y may be specified as a 2D offset into ARR1.

ABLIT-FROM-NONZERO (ARR1 ARR2 &KEY (X 0) (Y 0))

Destructivly copy arr2 into arr1 for 2- and 3-dimensional (Y:X, Y:X:RGB(A)) arrays. X and Y may be specified as a 2D offset into ARR1. Copying is started from the first nonzero element in each row. This is a hack to make kerned fonts render properly with the toy interface.

Undocumented

FLAT-ARRAY (ARR)

NTH-GRAY-PIXEL (ROW N)

NTH-MONO-PIXEL (ROW N)

ROW-WIDTH (ARR)

TOY-STRING-TO-ARRAY (FACE STRING DIRECTION)

TRGREY (I)

MACRO

Public

DO-CHAR-DECOMPOSE ((FACE CHAR-OR-CODE) DECOMPOSE-LAMBDA &BODY BODY)

Load `CHAR-OR-CODE` in `FACE`, and iterate the outline, passing the operation, a point, and up to two more points to `BODY`. `DECOMPOSE-LAMBDA` should be specified as per `DO-OUTLINE-DECOMPOSE`.

DO-OUTLINE-DECOMPOSE (OUTLINE DECOMPOSE-LAMBDA &BODY BODY)

Iterate `OUTLINE`, passing the operation, a point, and up to two more points to `BODY`. `DECOMPOSE-LAMBDA` must support passing up to four arguments, e.g., `(OP POINT POINT2 POINT3)`, `(OP POINT &rest POINTS)`, etc. `OP` will be one of `:moveto`, `:lineto`, `:conicto`, or `:cubicto`. `POINT` will always be the endpoint. In the case of `:conicto`, `POINT2` is the control point. In the case of `:cubicto`, `POINT2` is the first control point, and `POINT3` is the second control point.

DO-STRING-RENDER ((FACE STRING BITMAP-VAR X-VAR Y-VAR &KEY (DIRECTION LEFT-RIGHT) (LOAD-FUNCTION 'DEFAULT-LOAD-RENDER) (BASELINE-Y-P NIL) (OFFSETS-P T) (WITH-CHAR NIL)) &BODY BODY)

Load, render, and compute metrics for each character in STRING in an optimal manner. `FACE` should be set up appropriately (e.g., size). `BITMAP-VAR` is passed to the block as an ft-bitmap, `X-VAR` and `Y-VAR` are coordinates for each glyph. `DIRECTION` may be specified as `:left-right`, `:right-left`, `:up-down`, or `:down-up`. `LOAD-FUNCTION` by default loads and renders a glyph, returning an `FT-BITMAP`. A custom function may be used in place to assist in caching. cl-freetype2 does not do any caching itself. See the documentation for [`DEFAULT-LOAD-RENDER`](#DEFAULT-LOAD-RENDER) for details. `BASELINE-Y-P`, if set (not default), will give `Y` in terms of *baseline* rather than an offset to the upper edge. `OFFSETS-P`, if set (default), will calculate `LEFT` offset into `X`. This is critical for correct inter-glyph spacing, but some things (e.g. Cairo) calculate this separately.

WITH-OPEN-FACE ((VAR PATHNAME &OPTIONAL (INDEX 0) (LIBRARY '*LIBRARY*)) &BODY BODY)

Make a new `FT-FACE` on the stack from `PATHNAME`, closing and freeing at the end of `BODY`

VARIABLE

Public

*LIBRARY*

The default library handle. This is initialized when cl-freetype2 loads. No locking or other precautions are taken, so multithreaded code should take care to block or use separate instances.

Private

Undocumented

*OUTLINE-FUNCS*