SCHRIFT(3) Library Functions Manual SCHRIFT(3)

schrift, libschrift — Lightweight TrueType font rendering library

library “libschrift”
#include <schrift.h>

const char *
sft_version(void);

SFT_Font *
sft_loadmem(const void *mem, unsigned long size);

SFT_Font *
sft_loadfile(const char *filename);

void
sft_freefont(SFT_Font *font);

int
sft_lmetrics(const SFT *sft, SFT_LMetrics *metrics);

int
sft_lookup(const SFT *sft, SFT_UChar codepoint, SFT_Glyph *glyph);

int
sft_gmetrics(const SFT *sft, SFT_Glyph glyph, SFT_GMetrics *metrics);

int
sft_kerning(const SFT *sft, SFT_Glyph leftGlyph, SFT_Glyph rightGlyph, SFT_Kerning *kerning);

int
sft_render(const SFT *sft, SFT_Glyph glyph, SFT_Image image);

The function () may be called to determine the version of schrift. Since schrift uses semantic versioning, the returned string is of the form "MAJOR.MINOR.PATCH".

() will load a font from a given filename (by mapping it into memory), whereas () can be given an arbitrary memory address and size (in bytes). This allows loading fonts from ZIP file streams etc.

Once a particular font is no longer needed, its memory should be freed again by calling (). If the font has been loaded with sft_loadmem(), the underlying memory region will have to be freed separately.

Most functions take a SFT as their primary argument. This is a structure to be filled out by the caller. It bundles multiple commonly needed parameters. The fields are as follows:

font
The font to render with
xScale
The width of one em-square in pixels
yScale
The height of one em-square in pixels
xOffset
The horizontal offset to be applied before rendering to an image (Useful for subpixel-accurate positioning)
yOffset
The vertical offset to be applied before rendering to an image (Useful for subpixel-accurate positioning)
flags
A bitfield of binary flags

If the SFT_DOWNWARD_Y flag is set, the Y axis is interpreted to point downwards. Per default, it points upwards.

schrift operates in terms of glyph ids (of type SFT_Glyph), which are font-specific identifiers assigned to renderable symbols (glyphs). The way to obtain a glyph id is to call (). This function takes a Unicode codepoint in codepoint and writes its corresponding glyph id into the variable pointed to by glyph.

() calculates the typographic metrics neccessary for laying out multiple lines of text.

This function writes its output into the structure pointed to by metrics. The fields are as follows:

ascender
The distance from the baseline to the visual top of the text
descender
The distance from the baseline to the visual bottom of the text
lineGap
The default amount of horizontal padding between consecutive lines

When displaying multiple glyphs in a line, you have to keep track of the pen position. () tells you where to draw the next glyph with respect to the pen position, and how to update it after rendering the glyph.

This function writes its output into the structure pointed to by metrics. The fields are as follows:

advanceWidth
How much the pen position should advance to the right after rendering the glyph
leftSideBearing
The offset that should be applied along the X axis from the pen position to the edge of the glyph image
yOffset
An offset along the Y axis relative to the pen position that should be applied when displaying the glyph
minWidth
The minimum width that an image needs such that the glyph can be properly rendered into it
minHeight
The minimum height that an image needs such that the glyph can be properly rendered into it

Some sequences of glyphs may look awkward if they're layed out naively. For example, the gap between the two characters "VA" might look disproportionally large. Kerning is a way to combat this artifact, by slightly moving the second character closer or further away by a small amount. () may be used to retrieve kerning information for a given pair of glyph ids.

This function writes its output into the structure pointed to by kerning. The fields are as follows:

xShift
An amount that should be added to the pen's X position in-between the two glyphs
yShift
An amount that should be added to the pen's Y position in-between the two glyphs

To actually render a glyph into a easily-displayable raster image, use ().

Other than most functions, sft_render() takes a structure in image that is to be filled out by the caller. The fields are as follows:

pixels
A pointer to an array of bytes, width * height in size
width
The number of pixels in a row of the image
height
The number of pixels in a column of the image

The image will be rendered into the memory provided in pixels. Each byte corresponds to one pixel, with rows of the image being directly adjacent in memory without padding between them. Glyphs are rendered "white on black", meaning the background has a pixel value of 0, and the foreground goes up to a value of 255. Pixel values follow a linear color ramp, unlike conventional computer screens. That is to say, they are . These properties make it very easy to use images rendered with sft_render() as alpha masks.

sft_loadmem() and sft_loadfile() return NULL on error.

sft_lmetrics(), sft_lookup(), sft_hmetrics(), sft_kerning(), sft_extents(), and sft_render() all return 0 on success and -1 on error.

See the source code of the for a detailed example of real-world usage of schrift.

Thomas Oltmann <thomas.oltmann.hhg@gmail.com>

The only text encoding that schrift understands is Unicode.

Similarly, the only kind of font file supported right now are TrueType (.ttf) fonts (Some OpenType fonts might work too, as OpenType is effectively a superset of TrueType).

As of v0.10.2, there is no support for right-to-left scripts .

schrift currently does not implement font hinting and probably never will.

January 30, 2021 Void Linux