TTF v1.1.0 Manual
Michael R Sweet
Copyright © 2018-2025 by Michael R Sweet
Michael R Sweet
Copyright © 2018-2025 by Michael R Sweet
TTF is a simple C library for using TrueType and OpenType font files.
The TTF library has a single header file:
#include <ttf.h>
Use the pkg-config command to get the proper compiler and linker options:
CFLAGS = `pkg-config --cflags ttf`
LIBS = `pkg-config --libs ttf`
cc -o myprogram `pkg-config --cflags ttf` myprogram.c `pkg-config --libs ttf`
The ttfCreate function opens a font file, returning a pointer to a ttf_t object:
ttf_t *font = ttfCreate("FILENAME.ttf", /*idx*/0, /*err_cb*/NULL, /*err_cbdata*/NULL);
The returned pointer can be used with the other TTF library functions to provide various bits of metadata and measure the bounds of a given string of Unicode text. Once you are done with the font data, use the ttfDelete function to free the memory that was used.
If you already have a font file loaded in memory, the ttfCreateData function can be used to create a ttf_t object from the buffer:
ttf_t *font = ttfCreateData(data, datasize, /*idx*/0, /*err_cb*/NULL, /*err_cbdata*/NULL);
The error callback function ("err_cb") and data ("err_cbdata") allow you to specify a function that will receive any error messages that are ordinarily displayed to the standard error file. The callback receives the data pointer and a message string, for example the following callback will display the error message to the standard output file instead:
void
my_error_cb(void *err_cbdata, const char *message)
{
(void)err_cbdata;
puts(message);
}
TTF also provides a ttf_cache_t object representing a cache of available fonts. The [`ttfCacheCreate] function creates a cache of fonts that are provided by the operating system and/or installed by the user:
ttf_cache_t *cache = ttfCacheCreate("my-application-name", /*err_cb*/NULL, /*err_cbdata*/NULL);
The error callback function and data are the same as you would provide to the ttfCreate or ttfCreateData functions.
Once loaded, you can access the available fonts using the ttfCacheFind or ttfCacheGetFont functions, for example:
// Find Helvetica
ttf_t *font = ttfCacheFind(cache, "Helvetica", TTF_STYLE_NORMAL, TTF_WEIGHT_400, TTF_STRETCH_NORMAL);
// List all fonts
size_t i, num_fonts = ttfCacheGetNumFonts(cache);
for (i = 0; i < num_fonts; i ++)
{
font = ttfCacheGetFont(cache, i);
puts(ttfGetFamily(font));
}
Note: Do not call
ttfDeleteon fonts obtained from the cache. Instead, callttfCacheDeleteto free all fonts in the cache.
Add a font to the cache.
void ttfCacheAdd(ttf_cache_t *cache, ttf_t *font, const char *filename);
| cache | Font cache |
|---|---|
| font | Font |
| filename | Filename/URL or NULL for in-memory |
This function adds the specified font to the cache.
Note: Once added, the cache takes over management of the font. Do not callttfDeletewith the font pointer. Instead, the font will be freed when you callttfCacheDeleteto free the cache.
Create a cache of system and user fonts.
ttf_cache_t *ttfCacheCreate(const char *appname, ttf_err_cb_t err_cb, void *err_cbdata);
| appname | Application name |
|---|---|
| err_cb | Error callback function |
| err_cbdata | Error callback data |
Font cache
This function creates a cache of system and user fonts, loading any
previously cached results for the named application "appname".
The "err_cb" and "err_cbdata" arguments specify a callback function and data
pointer for receiving error messages. If NULL, errors are sent to the
stderr file. The callback function receives the data pointer and a text
message string, for example:
void my_err_cb(void *err_cbdata, const char *message)
{
fprintf(stderr, "ERROR: %s\n", message);
}
Delete a cache.
void ttfCacheDelete(ttf_cache_t *cache);
| cache | Font cache |
|---|
This function deletes a cache, freeing any loaded fonts.
Find a font in the cache.
ttf_t *ttfCacheFind(ttf_cache_t *cache, const char *family, ttf_style_t style, ttf_weight_t weight, ttf_stretch_t stretch);
| cache | Font cache |
|---|---|
| family | Family name |
| style | Font style or TTF_STYLE_UNSPEC |
| weight | Font weight or TTF_WEIGHT_UNSPEC |
| stretch | Font stretch or TTF_STRETCH_UNSPEC |
Font or NULL if no matching font found
This function finds a font in the cache. The returned ttf_t object is
managed by the cache and should not be deleted.
Get the font family at index N.
const char *ttfCacheGetFamily(ttf_cache_t *cache, size_t n);
| cache | Font cache |
|---|---|
| n | Font index starting at 0 |
Font family name or NULL
Get the font filename at index N.
const char *ttfCacheGetFilename(ttf_cache_t *cache, size_t n);
| cache | Font cache |
|---|---|
| n | Font index starting at 0 |
Font filename/URL or NULL if none
Get the font at index N
ttf_t *ttfCacheGetFont(ttf_cache_t *cache, size_t n);
| cache | Font cache |
|---|---|
| n | Font index starting at 0 |
Font
This function gets a font from the cache. The returned ttf_t object is
managed by the cache and should not be deleted.
Get the font index for the composite font at index N.
size_t ttfCacheGetIndex(ttf_cache_t *cache, size_t n);
| cache | Font cache |
|---|---|
| n | Cached font index starting at 0 |
Composite font index
Get the number of fonts in the cache.
size_t ttfCacheGetNumFonts(ttf_cache_t *cache);
| cache | Font cache |
|---|
Number of fonts
Get the font stretch at index N.
ttf_stretch_t ttfCacheGetStretch(ttf_cache_t *cache, size_t n);
| cache | Font cache |
|---|---|
| n | Font index starting at 0 |
Font stretch or TTF_STRETCH_UNSPEC
Get the font style at index N.
ttf_style_t ttfCacheGetStyle(ttf_cache_t *cache, size_t n);
| cache | Font cache |
|---|---|
| n | Font index starting at 0 |
Font style or TTF_STYLE_UNSPEC
Get the font weight at index N.
ttf_weight_t ttfCacheGetWeight(ttf_cache_t *cache, size_t n);
| cache | Font cache |
|---|---|
| n | Font index starting at 0 |
Font weight or TTF_WEIGHT_UNSPEC
Test for the presence of a Unicode character in a font.
bool ttfContainsChar(ttf_t *font, int ch);
| font | Font |
|---|---|
| ch | Unicode character |
true if font contains the character, false otherwise
Test for the presence of all characters in a UTF-8 (Unicode) string in a font.
bool ttfContainsChars(ttf_t *font, const char *s);
| font | Font |
|---|---|
| s | UTF-8 string |
true if font contains the characters in the string, false otherwise
Create a new font object for the named font file.
ttf_t *ttfCreate(const char *filename, size_t idx, ttf_err_cb_t err_cb, void *err_cbdata);
| filename | Filename |
|---|---|
| idx | Font number to create in collection (0-based) |
| err_cb | Error callback or NULL to log to stderr |
| err_cbdata | Error callback data |
New font object
This function creates a new font object for the named TrueType or OpenType
font file or collection. The "filename" argument specifies the name of the
file to read.
The "idx" argument specifies the font to load from a collection - the first
font is number 0. Once created, you can call the ttfGetNumFonts
function to determine whether the loaded font file is a collection with more
than one font.
The "err_cb" and "err_cbdata" arguments specify a callback function and data
pointer for receiving error messages. If NULL, errors are sent to the
stderr file. The callback function receives the data pointer and a text
message string, for example:
void my_err_cb(void *err_cbdata, const char *message)
{
fprintf(stderr, "ERROR: %s\n", message);
}
Create a new font object from a memory buffer.
ttf_t *ttfCreateData(const void *data, size_t datasize, size_t idx, ttf_err_cb_t err_cb, void *err_cbdata);
| data | Buffer |
|---|---|
| datasize | Size of buffer in bytes |
| idx | Font number to create in collection (0-based) |
| err_cb | Error callback or NULL to log to stderr |
| err_cbdata | Error callback data |
New font object
This function creates a new font object from a memory buffer. The "data"
argument specifies a pointer to the first byte of data and the "datasize"
argument specifies the length of the memory buffer in bytes.
Note: The caller is responsible for ensuring that the memory buffer is
available until the font object is deleted with ttfDelete.0. Once created, you can call the ttfGetNumFonts
function to determine whether the loaded font file is a collection with more
than one font.NULL, errors are sent to the
stderr file. The callback function receives the data pointer and a text
message string, for example:
void my_err_cb(void *err_cbdata, const char *message)
{
fprintf(stderr, "ERROR: %s\n", message);
}
Free all memory used for a font family object.
void ttfDelete(ttf_t *font);
| font | Font |
|---|
Get the maximum height of non-accented characters.
int ttfGetAscent(ttf_t *font);
| font | Font |
|---|
Ascent in 1000ths
Get the bounds of all characters in a font.
ttf_rect_t *ttfGetBounds(ttf_t *font, ttf_rect_t *bounds);
| font | Font |
|---|---|
| bounds | Bounds buffer |
Bounds or NULL on error
This function gets the bounds of all characters in a font. The "bounds"
argument is a pointer to a ttf_rect_t structure that will be filled with
the limits for characters in the font scaled to a 1000x1000 unit square.
Get the Unicode to glyph mapping table.
const int *ttfGetCMap(ttf_t *font, size_t *num_cmap);
| font | Font |
|---|---|
| num_cmap | Number of entries in table |
CMap table
Get the height of capital letters.
int ttfGetCapHeight(ttf_t *font);
| font | Font |
|---|
Capital letter height in 1000ths
Get the copyright text for a font.
const char *ttfGetCopyright(ttf_t *font);
| font | Font |
|---|
Copyright text
Get the maximum depth of non-accented characters.
int ttfGetDescent(ttf_t *font);
| font | Font |
|---|
Descent in 1000ths
Get the extents of a UTF-8 string.
ttf_rect_t *ttfGetExtents(ttf_t *font, float size, const char *s, ttf_rect_t *extents);
| font | Font |
|---|---|
| size | Font size |
| s | String |
| extents | Extents of the string |
Pointer to extents or NULL on error
This function computes the extents of the UTF-8 string "s" when rendered
using the specified font "font" and size "size". The "extents" argument is
a pointer to a ttf_rect_t structure that is filled with the extents of a
simple rendering of the string with no kerning or rewriting applied. The
values are scaled using the specified font size.
Get the family name of a font.
const char *ttfGetFamily(ttf_t *font);
| font | Font |
|---|
Family name
Get the italic angle.
float ttfGetItalicAngle(ttf_t *font);
| font | Font |
|---|
Angle in degrees
Get the kerned extents of a string.
size_t ttfGetKernedExtents(ttf_t *font, float size, const char *s, ttf_rect_t *extents, size_t max_adjs, double *adjs);
| font | Font |
|---|---|
| size | Font size |
| s | String |
| extents | Kerned extents of string |
| max_adjs | Maximum number of kerning adjustments |
| adjs | Array of kerning adjustments |
Number of kerned pairs
This function computes the kerned extents of the UTF-8 string "s" when
rendered using the specified font "font" and size "size". The "extents"
argument is a pointer to a ttf_rect_t structure that is filled with the
extents of a kerned rendering of the string with no rewriting applied. The
"adjs" argument specifies and array of double values up to "max_adjs" long
containing the kerning adjustments between each pair of characters. The
extent and adjustment values are scaled using the specified font size.
Get the last character in the font.
int ttfGetMaxChar(ttf_t *font);
| font | Font |
|---|
Last character in font
Get the first character in the font.
int ttfGetMinChar(ttf_t *font);
| font | Font |
|---|
First character in font
Get the number of fonts in this collection.
size_t ttfGetNumFonts(ttf_t *font);
| font | Font |
|---|
Number of fonts
Get the PostScript name of a font.
const char *ttfGetPostScriptName(ttf_t *font);
| font | Font |
|---|
PostScript name
Get the font "stretch" value...
ttf_stretch_t ttfGetStretch(ttf_t *font);
| font | Font |
|---|
Stretch value
Get the font style.
ttf_style_t ttfGetStyle(ttf_t *font);
| font | Font |
|---|
Style
Get the version number of a font.
const char *ttfGetVersion(ttf_t *font);
| font | Font |
|---|
Version number
Get the weight of a font.
ttf_weight_t ttfGetWeight(ttf_t *font);
| font | Font |
|---|
Weight
Get the width of a single character.
int ttfGetWidth(ttf_t *font, int ch);
| font | Font |
|---|---|
| ch | Unicode character |
Width in 1000ths
Get the height of lowercase letters.
int ttfGetXHeight(ttf_t *font);
| font | Font |
|---|
Lowercase letter height in 1000ths
Determine whether a font is fixedpitch.
bool ttfIsFixedPitch(ttf_t *font);
| font | Font |
|---|
true if fixed pitch, false otherwise
Font cache
typedef struct _ttf_cache_s ttf_cache_t;
Font error callback
typedef void (*ttf_err_cb_t)(void *data, const char *message);
Bounding rectangle
typedef struct ttf_rect_s ttf_rect_t;
Font stretch
typedef enum ttf_stretch_e ttf_stretch_t;
Font style
typedef enum ttf_style_e ttf_style_t;
Font object
typedef struct _ttf_s ttf_t;
Font weight
typedef enum ttf_weight_e ttf_weight_t;
Bounding rectangle
struct ttf_rect_s {
float bottom;
float left;
float right;
float top;
};
| bottom | Bottom offset |
|---|---|
| left | Left offset |
| right | Right offset |
| top | Top offset |
Font stretch
| TTF_STRETCH_CONDENSED | condensed |
|---|---|
| TTF_STRETCH_EXPANDED | expanded |
| TTF_STRETCH_EXTRA_CONDENSED | extra-condensed |
| TTF_STRETCH_EXTRA_EXPANDED | extra-expanded |
| TTF_STRETCH_NORMAL | normal |
| TTF_STRETCH_SEMI_CONDENSED | semi-condensed |
| TTF_STRETCH_SEMI_EXPANDED | semi-expanded |
| TTF_STRETCH_ULTRA_CONDENSED | ultra-condensed |
| TTF_STRETCH_ULTRA_EXPANDED | ultra-expanded |
| TTF_STRETCH_UNSPEC | Unspecified |
Font style
| TTF_STYLE_ITALIC | Italic font |
|---|---|
| TTF_STYLE_NORMAL | Normal font |
| TTF_STYLE_OBLIQUE | Oblique (angled) font |
| TTF_STYLE_UNSPEC | Unspecified |
Font weight
| TTF_WEIGHT_100 | Weight 100 (Thin) |
|---|---|
| TTF_WEIGHT_200 | Weight 200 (Extra/Ultra-Light) |
| TTF_WEIGHT_300 | Weight 300 (Light) |
| TTF_WEIGHT_400 | Weight 400 (Normal/Regular) |
| TTF_WEIGHT_500 | Weight 500 (Medium) |
| TTF_WEIGHT_600 | Weight 600 (Semi/Demi-Bold) |
| TTF_WEIGHT_700 | Weight 700 (Bold) |
| TTF_WEIGHT_800 | Weight 800 (Extra/Ultra-Bold) |
| TTF_WEIGHT_900 | Weight 900 (Black/Heavy) |
| TTF_WEIGHT_UNSPEC | Unspecified |