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 struct SFT *sft, struct SFT_LMetrics *metrics);

int
sft_lookup(const struct SFT *sft, unsigned long codepoint, SFT_Glyph *glyph);

int
sft_hmetrics(const struct SFT *sft, SFT_Glyph glyph, struct SFT_HMetrics *metrics);

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

int
sft_extents(const struct SFT *sft, SFT_Glyph glyph, struct SFT_Extents *extents);

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

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

sft_loadfile() will load a font from a given filename (by mapping it into memory), whereas sft_loadmem() 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 sft_freefont(). If the font has been loaded with sft_loadmem(), the underlying memory region will have to be freed separately.

Most functions take a struct 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 sft_lookup(). This function takes a Unicode codepoint in codepoint and writes its corresponding glyph id into the variable pointed to by glyph.

sft_lmetrics() 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. sft_hmetrics() 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

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 phenomenon, by slightly moving the second character closer or further away by a small amount. sft_kerning() 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

sft_extents() computes bounding box information of a glyph without having to render it.

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

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

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

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 not gamma-corrected. 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 sftdemo 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.0, there is no support for right-to-left scripts yet.

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

December 20, 2020 Void Linux