SCHRIFT(3)

💖 SCHRIFT(3) — the libschrift era 💖

okay bestie, this is the Library Functions Manual page for SCHRIFT(3), aka libschrift — the lightweight TrueType font rendering library. grab a strawberry drink 🍓 because we're doing font math and it's lowkey iconic.

---

🌸 NAME 🌸

schrift, libschrift — Lightweight TrueType font rendering library

---

✨ SYNOPSIS ✨

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);

---

🦋 DESCRIPTION 🦋

So sft_version() is the lil function you call when you wanna know which version of schrift you're dealing with. schrift uses semantic versioning, so the returned string is literally of the form "MAJOR.MINOR.PATCH". slay.

🎀 Loading fonts 🎀

sft_loadfile() will load a font from a given filename — by mapping it into memory, bestie. Meanwhile sft_loadmem() can be handed an arbitrary memory address and size (in bytes). This is what lets you load fonts from ZIP file streams etc. 💅

Once a particular font is no longer needed, its memory should be freed again by calling sft_freefont(). Important caveat: if the font has been loaded with sft_loadmem(), the underlying memory region will have to be freed separately. don't forget, or it's giving leak era 😭

💅 the SFT structure 💅

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. so default vibe = Y points up; set SFT_DOWNWARD_Y and it's downward. got it? 🫶

🌈 Glyph ids 🌈

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.

⭐ Querying metrics ⭐

sft_lmetrics() calculates the typographic metrics necessary 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_gmetrics() 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. 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

🧚 Rendering glyphs 🧚

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.

---

🔥 RETURN VALUES 🔥

• 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.

yes bestie, that list really does include sft_hmetrics() and sft_extents() — iykyk, we keep the details exactly as the page says. 👑

---

🍓 EXAMPLES 🍓

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

---

👑 AUTHORS 👑

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

---

💀 CAVEATS 💀

• 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 yet.
• schrift currently does not implement font hinting and probably never will.

---

kisses from Debian, dated January 30, 2021 — this has been SCHRIFT(3), mwah 💋 periodt.