Font::TTFMetrics(3)

💖 Font::TTFMetrics 💖

okay bestie, so this is the Font::TTFMetrics page from the User Contributed Perl Documentation, manual section 3. It's giving "let me read your fonts for you" and honestly? iconic. 🎀

---

✨ NAME ✨

Font::TTFMetrics — a parser for the TTF file. that's it, that's the whole name. short, sweet, slays. 💅

---

✨ SYNOPSIS ✨

use Font::TTFMetrics;

my $metrics = Font::TTFMetrics->new("somefont.ttf");
my $ascent = $metrics->get_ascent();

like. look at her. four lines and she already ate. 👑

---

✨ DESCRIPTION ✨

Font::TTFMetrics wraps up all the font metrics of a true type font file for you. A true type font file is literally stuffed with several tables, and you have to parse every single one before you can get any useful info out of the font. 🙈

There's already an excellent module on CPAN for parsing TTF fonts, written by Martin Hosken, called Font::TTF. But ngl, in the author's opinion, using Font::TTF requires you to have intimate knowledge of the TTF font format, and bestie, that's a lot. So this module was written to support using TTF in the Pastel 2D graphics library in Perl.

Three things prompted the author to write this:

1. A fast module to access TTF files was needed. 🏃‍♀️
2. All the access required was read-only. no writing, just vibes.
3. A user friendly, higher level API to access TTF files was wanted. 🫶

Every font file actually contains several pieces of information, and the most important one is how a particular character will display on screen. The shape of a character (a glyph) is determined by a series of points. Those points are generally lines, or points on a curved path. For the details, go read the TTF specification. Remember: the points actually determine the outline of the curve. ✏️

A TTF file stores the glyph shape in the glyf table of the font. The very first glyph described in that table is always a particular glyph called the "missing-glyph", which gets shown in case the font file doesn't contain the glyph that a piece of software is asking for. (yes, even fonts have a "sorry bestie, don't have it" face. 😭)

Each character in a computer is actually a number. You can find out what number corresponds to a character by calling ord() on it. That value is called the ordinal value of the character. If you just use common english, the number for any character typically falls between 32-126, which is commonly called ASCII. If you use extra characters that aren't commonly found on a keyboard, like "degree", then your character code falls between 0-255, commonly called the LATIN-1 character set. Unicode is a way to use characters with ordinal values beyond 255. The good thing about it is that the UTF8 encoding in perl works silently in the background and you can intermix characters with any ordinal value. 🌈

That, of course, does not mean you'll be able to use a character with any ordinal value for display. The font file must contain the corresponding glyph. no glyph, no show. 💀

The way to extract the glyph for a character is by looking into the cmap table of the font. This table contains the character ordinal number and a corresponding index. That index is used to look into the glyf table to extract the shape of the character. Which means: if you just substitute another index for a particular ordinal number, you can actually display a different character — a mechanism known as "glyph substitution". ✨

As you can guess, there's one more way to display a particular character instead of what it should display, in a more font specific manner. If you just add a particular offset to a glyph ordinal value and provide the index for this added value in the cmap table, you can generate a completely different glyph. This mechanism works for a particular type of font supplied by Microsoft called symbol fonts. Examples of these are symbol.ttf and wingding. Both of these fonts don't supply any glyphs corresponding to LATIN-1 character sets, but they do have ordinal values in the range 61472-61695.

But notice: if you fire up your word-processor and change the font to symbol and type any character on the keyboard, you get a display. For example, if you type A (ordinal value 65), what you get is greek capital alpha. Here's how that works: as soon as the word-processor finds out you're using a symbol font (you can call the is_symbol() method to find that out), it just adds 61440 to any character you type and then queries the cmap table for the glyph. math, but make it fonts. 🧮💅

One more important aspect of using a TTF file is finding the width of a string. The easiest way to find this is to query the htmx table, which contains the advance width of each character, add up all the advance widths of the individual characters in the string, and then go look into the kern table, which contains the kerning value for a pair of glyphs, and deduct those values from the total width. You also need to deduct the left-side bearing of the first character and the right-side bearing of the last character from the total width. 📏

Users of this module should keep in mind that all the values returned from this module are in font-units and should be converted to pixel units by:

fIUnits * pointsize * resolution /(72 * units_per_em)

An example from the true type specification at http://www.microsoft.com/typography/otspec/TTCH01.htm:

A font-feature of 550 units when used with 18 pt on screen (typically 72 dpi resolution) will be

550 * 18 * 72 / ( 72 * 2048 ) = 4.83 pixels long.

Note that the units_per_em value is 2048, which is typical for a TTF file. This value can be obtained by calling the get_units_per_em() call. 🌸

This module also takes full advantage of the unicode support of Perl. Any strings that you pass to any function call in this module can have unicode built into it. That means a string like:

"Something \x{70ff}"

is perfectly valid. 🦋

---

🎀 CONSTRUCTOR 🎀

new()

Creates and returns a Font::TTFMetrics object. she's born. ✨

Usage   : my $metrics = Font::TTFMetrics->new($file);
Args    : $file - TTF filename.
Returns : A Font::TTFMetrics object.

---

💅 METHODS 💅

is_symbol()

Returns true if the font is a Symbol font from Microsoft. Remember that Wingding is also a symbol font. 👑

Usage   : $metrics->is_symbol();
Args    : Nothing.
Returns : True if the font is a Symbol font, false otherwise.

char_width()

Returns the advance width of a single character, in font units.

Usage   : $font->char_width('a');
Args    : A single perl character. Can be even a unicode.
Returns : A scalar value. The width of the character in font units.

string_width()

Given a string, the function returns the width of the string in font units. At present the function only calculates the advance width of each character and deducts the calculated kerning from the whole length. If someone has any better idea then let the author know. 🫶

Usage   : $font->string_width("Some string");
Args    : A perl string. Can be embedded unicode.
Returns : A scalar indicating the width of the whole string in font units.

get_leading()

"Leading" is the gap between two lines. The value is present in the OS/2 table of the font.

Usage   : $metrics->get_leading();
Args    : None.
Returns : A scalar Integer.

get_units_per_em()

Get units_per_em of the font. This value is present in the head table of the font and for TTF is generally 2048.

Usage   : $metrics->get_units_per_em();
Args    : None.
Returns : A scalar integer.

get_ascent()

"Ascent" is the distance between the baseline and the top of the glyph. ⬆️

Usage   : $metrics->get_ascent();
Args    : None.
Returns : A scalar integer.

get_descent()

"Descent" is the negative distance from the baseline to the lowest point of the glyph. ⬇️

Usage   : $metrics->get_descent();
Args    : None.
Returns : A scalar integer.

is_bold()

Returns true if the font is a bold variation of the font. That means if you call this function on arial.ttf, it returns false. If you call this function on arialb.ttf it returns true. 💪

Usage   : $metrics->is_bold()
Args    : None.
Returns : True if the font is a bold font, returns false otherwise.

is_italic()

Returns true if the font is the italic version of the font. That means if you call this function on arialbi.ttf or ariali.ttf it returns true. slanted and serving. 🦋

Usage   : $metrics->is_italic()
Args    : None
Returns : True if the font italic, false otherwise

get_font_family()

Returns the family name of the font.

Usage   : $metrics->get_font_family()
Args    : None
Returns : A scalar

get_subfamily()

Returns the style variation of the font in text. Note that depending on this, the description might actually be pretty confusing. Call is_bold() and/or is_italic() to determine the style. For example, a "demi" version of the font is not "bold" by text. But in display, this is actually a bold variation. In this case is_bold() will return true. the plot twist of font metadata. 😭

Usage   : $metrics->get_subfamily()
Args    : None
Returns : A scalar.

is_fixed_pitch()

Returns true for a fixed-pitched font like courier. every character same width, no favorites. 🎀

Usage   : $metrics->is_fixed_pitch()
Args    : None
Returns : True for a fixed-pitched font, false otherwise

---

👀 SEE ALSO 👀

Font::TTF, Pastel::Font::TTF.

---

💜 COPYRIGHTS 💜

Copyright (c) 2003 by Malay <curiouser@ccmb.res.in>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🌈

---

and that's the whole page bestie!! 🫶 this was rendered from perl v5.42.0, dated 2025-07-25, and you were reading Font::TTFMetrics(3) the entire time. mwah. 💋💖✨