TTF v1.0.0 Manual

Michael R Sweet

Copyright © 2018-2024 by Michael R Sweet

Contents

Introduction

TTF is a simple C library for using TrueType and OpenType font files.

Using the TTF Library

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_data*/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.

Functions

ttfCreate

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

Parameters

filename Filename
idx Font number to create in collection (0-based)
err_cb Error callback or NULL to log to stderr
err_data Error callback data

Return Value

New font object

Discussion

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_data" 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_data, const char *message)
{
  fprintf(stderr, "ERROR: %sn", message);
}

ttfDelete

Free all memory used for a font family object.

void ttfDelete(ttf_t *font);

Parameters

font Font

ttfGetAscent

Get the maximum height of non-accented characters.

int ttfGetAscent(ttf_t *font);

Parameters

font Font

Return Value

Ascent in 1000ths

ttfGetBounds

Get the bounds of all characters in a font.

ttf_rect_t *ttfGetBounds(ttf_t *font, ttf_rect_t *bounds);

Parameters

font Font
bounds Bounds buffer

Return Value

Bounds or NULL on error

Discussion

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.

ttfGetCMap

Get the Unicode to glyph mapping table.

const int *ttfGetCMap(ttf_t *font, size_t *num_cmap);

Parameters

font Font
num_cmap Number of entries in table

Return Value

CMap table

ttfGetCapHeight

Get the height of capital letters.

int ttfGetCapHeight(ttf_t *font);

Parameters

font Font

Return Value

Capital letter height in 1000ths

ttfGetCopyright

Get the copyright text for a font.

const char *ttfGetCopyright(ttf_t *font);

Parameters

font Font

Return Value

Copyright text

ttfGetDescent

Get the maximum depth of non-accented characters.

int ttfGetDescent(ttf_t *font);

Parameters

font Font

Return Value

Descent in 1000ths

ttfGetExtents

Get the extents of a UTF-8 string.

ttf_rect_t *ttfGetExtents(ttf_t *font, float size, const char *s, ttf_rect_t *extents);

Parameters

font Font
size Font size
s String
extents Extents of the string

Return Value

Pointer to extents or NULL on error

Discussion

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.

ttfGetFamily

Get the family name of a font.

const char *ttfGetFamily(ttf_t *font);

Parameters

font Font

Return Value

Family name

ttfGetItalicAngle

Get the italic angle.

float ttfGetItalicAngle(ttf_t *font);

Parameters

font Font

Return Value

Angle in degrees

ttfGetMaxChar

Get the last character in the font.

int ttfGetMaxChar(ttf_t *font);

Parameters

font Font

Return Value

Last character in font

ttfGetMinChar

Get the first character in the font.

int ttfGetMinChar(ttf_t *font);

Parameters

font Font

Return Value

First character in font

ttfGetNumFonts

Get the number of fonts in this collection.

size_t ttfGetNumFonts(ttf_t *font);

Parameters

font Font

Return Value

Number of fonts

ttfGetPostScriptName

Get the PostScript name of a font.

const char *ttfGetPostScriptName(ttf_t *font);

Parameters

font Font

Return Value

PostScript name

ttfGetStretch

Get the font "stretch" value...

ttf_stretch_t ttfGetStretch(ttf_t *font);

Parameters

font Font

Return Value

Stretch value

ttfGetStyle

Get the font style.

ttf_style_t ttfGetStyle(ttf_t *font);

Parameters

font Font

Return Value

Style

ttfGetVersion

Get the version number of a font.

const char *ttfGetVersion(ttf_t *font);

Parameters

font Font

Return Value

Version number

ttfGetWeight

Get the weight of a font.

ttf_weight_t ttfGetWeight(ttf_t *font);

Parameters

font Font

Return Value

Weight

ttfGetWidth

Get the width of a single character.

int ttfGetWidth(ttf_t *font, int ch);

Parameters

font Font
ch Unicode character

Return Value

Width in 1000ths

ttfGetXHeight

Get the height of lowercase letters.

int ttfGetXHeight(ttf_t *font);

Parameters

font Font

Return Value

Lowercase letter height in 1000ths

ttfIsFixedPitch

Determine whether a font is fixedpitch.

bool ttfIsFixedPitch(ttf_t *font);

Parameters

font Font

Return Value

true if fixed pitch, false otherwise

Data Types

ttf_err_cb_t

Font error callback

typedef void (*ttf_err_cb_t)(void *data, const char *message);

ttf_rect_t

Bounding rectangle

typedef struct ttf_rect_s ttf_rect_t;

ttf_stretch_t

Font stretch

typedef enum ttf_stretch_e ttf_stretch_t;

ttf_style_t

Font style

typedef enum ttf_style_e ttf_style_t;

ttf_t

Font object

typedef struct _ttf_s ttf_t;

ttf_variant_t

Font variant

typedef enum ttf_variant_e ttf_variant_t;

ttf_weight_t

Font weight

typedef enum ttf_weight_e ttf_weight_t;

Structures

ttf_rect_s

Bounding rectangle

struct ttf_rect_s {
    float bottom;
    float left;
    float right;
    float top;
};

Members

bottom Bottom offset
left Left offset
right Right offset
top Top offset

Constants

ttf_stretch_e

Font stretch

Constants

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_style_e

Font style

Constants

TTF_STYLE_ITALIC Italic font
TTF_STYLE_NORMAL Normal font
TTF_STYLE_OBLIQUE Oblique (angled) font

ttf_variant_e

Font variant

Constants

TTF_VARIANT_NORMAL Normal font
TTF_VARIANT_SMALL_CAPS Font whose lowercase letters are small capitals

ttf_weight_e

Font weight

Constants

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)