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_linemetrics(const struct SFT *sft, double *ascent, double *descent, double *gap);

int
sft_kerning(const struct SFT *sft, unsigned long leftChar, unsigned long rightChar, double kerning[2]);

int
sft_char(const struct SFT *sft, unsigned int charCode, struct SFT_Char *chr);

sft_version() can be used to determine which version of schrift you are using. Since schrift uses semantic versioning, the returned string will usually be 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 users to load fonts from ZIP file streams etc.

Once a user is done with a particular font and does not need to access it any more, he may use sft_freefont() to free all memory reserved by the font. If the font has been loaded with sft_loadmem() the user has to additionally free the memory they passed to sft_loadmem() on their own.

The following functions all take a struct SFT as their primary argument. Details concerning this struct can be found in the next section.

sft_linemetrics() can be used to query the typographic ascender, descender, and line gap, in pixels. The ascender refers to the distance of the highest point of a line of text to it's baseline. Analogously, the descender refers to the distance to the lowest point. The line gap measures the suggested blank space between consecutive lines.

sft_kerning() can be used to find the kerning between a pair of characters (codepoints). That is, an x and y offset that should be applied to the second character, should it follow the first.

Lastly, the most important public function of schrift is sft_char() . It lets users query codepoint-specific information, like horizontal advance width, extents, etc. It can also render a specified codepoint to an in-memory image. More details can be found in the following sections.

The struct SFT is a structure to be filled out by the application. It bundles all the different parameters neccessary for drawing, like for example which font to use, or how big the text should be, into a single struct. Most functions in schrift take a struct SFT as their primary argument. 
struct SFT {
	SFT_Font *font;
	double xScale;
	double yScale;
	double x;
	double y;
	unsigned int flags;
};
The fields are as follows:
font
The font to render with.
xScale
The user-specified width of one em-square in pixels.
yScale
The user-specified height of one em-square in pixels.
x
The horizontal offset in pixels to be applied before rendering to an image. Can be used for subpixel-accurate positioning.
y
The vertical offset in pixels to be applied before rendering to an image. Can be used for subpixel-accurate positioning.
flags
A bitfield of binary flags that control various functionalities.

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

If SFT_RENDER_IMAGE is set, the function sft_char() will, when called, render a specified character into an image buffer. Otherwise, sft_char() will only return auxiliary data such as image buffer dimensions and horizontal advance width.

If SFT_CATCH_MISSING is set, the function sft_char will return immediately if called on a character that the used font does not have data for. The user then has to check whether this happened by looking at the function's return value.

sft_char() returns all relevant information except status code in a struct SFT_Char. 
struct SFT_Char {
	void *image;
	double advance;
	int x;
	int y;
	unsigned int width;
	unsigned int height;
};
The fields are as follows:
image
An 8-bit grayscale image without any padding, so each byte corresponds to one pixel. The colors are inverse to what you would expect: Text is always drawn white on black. That is because this way it is really convenient to use the image as an alpha mask. This is also the reason why the image is not gamma corrected.

This field only gets set if the flag SFT_RENDER_IMAGE was set. In this case, it is the caller's duty to later release the image's memory again by calling free() . Otherwise, if SFT_RENDER_IMAGE was not set, this field is set to NULL.

x
The X offset in pixels that the application should apply when displaying the image on the screen.
y
The Y offset in pixels that the application should apply when displaying the image on the screen.

The flag SFT_DOWNWARD_Y controls the orientation of the coordinate system that this field is relative to.

width
The width of the image in pixels.

This field gets set even if SFT_RENDER_IMAGE was not set.

height
The height of the image in pixels.

This field gets set even if SFT_RENDER_IMAGE was not set.

missing
Contains a positive value if the used font doesn't have data for the specified character, and a fallback character (the missing glyph) has been selected instead. It is 0 otherwise.

sft_loadmem() and sft_loadfile() return NULL on error. sft_linemetrics() and sft_kerning() return 0 on success and -1 on error.

sft_char() returns -1 on error, 1 if the character code isn't covered by the font and a fallback character (the missing glyph) was used instead, and 0 otherwise.

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). schrift currently does not implement font hinting and probably never will.
June 5, 2020 suckless.org