Font::...::Face(3pm)

📦
version 0.16 · 7 versions
, in ubuntu stonking

💖 NAME 💖

Font::FreeType::Face — the font typefaces you get when you load stuff up from Font::FreeType, bestie. It's a Perl module (a 3pm situation), and it's giving main character energy for every font face in your life ✨

🌸 SYNOPSIS 🌸

use Font::FreeType;

my $freetype = Font::FreeType->new;
my $face = $freetype->face('Vera.ttf');

That's literally it, no cap 🫶

🦋 DESCRIPTION 🦋

Okay so this class is the whole vibe-check for a font face (or typeface, same thing, don't come for me) that got loaded from a font file. Usually one face = all the info in the font file (think a TTF file), but lowkey it's possible to have multiple faces chilling in a single file. Iconic of them honestly.

🚨 Do NOT use this module directly. Like, ever. The class gets loaded automatically from Font::FreeType, iykyk. You make a new Font::FreeType::Face object from a filename by using the "Font::FreeType->face()" method. That's the way. 💅

💅 METHODS 💅

Unless otherwise stated, every single method here will die if there's an error. So wrap things up if you're feeling fragile, bestie 😭

  • ascender() — the height above the baseline of the 'top' of the font's glyphs, scaled to the current size of the face. Very top-of-the-world of it.
  • attach_file(filename) — tells FreeType about an ancillary file it needs for reading the font. Ngl, this hasn't been tested yet 🙈
  • current_face_index() — the index number of the current font face. Usually it's zero, which is the default. Peep "Font::FreeType->face()" for how to load other faces out of the same file.
  • descender() — the depth below the baseline of the 'bottom' of the font's glyphs, scaled to the current size of the face. Plot twist: it actually represents the distance moving up from the baseline, so it's usually negative. Math is mathing 💀
  • family_name() — a string with the name of the family this font claims to be from. (Claims! The audacity.)
  • fixed_sizes() — in scalar context, returns the number of fixed sizes (of embedded bitmaps) available in the font. In list context, returns a list of hashes detailing those sizes. Each hash can contain the following keys, but they'll be absent if that info isn't available:
    • size — size of the glyphs in points. Only available with Freetype 2.1.5 or newer.
    • height — height of the bitmaps in pixels.
    • width — width of the bitmaps in pixels.
    • x_res_dpi, y_res_dpi — the resolution the bitmaps were designed for, in dots per inch. Only available with Freetype 2.1.5 or newer.
    • x_res_ppem, y_res_ppem — the resolution the bitmaps were designed for, in pixels per em. Only available with Freetype 2.1.5 or newer.
  • foreach_char(code-ref) — iterates through all the characters in the font and calls your code-ref for each one in turn. Glyphs that don't correspond to Unicode characters get ignored, sorry bestie. Every time your callback gets called, $_ is set to a Font::FreeType::Glyph object for the current glyph. Want an example? There's a program called list-characters.pl in the distribution. Go look 👀
  • foreach_glyph(code-ref) — iterates through all the glyphs in the font and calls your code-ref for each one in turn. Same deal: each time your callback fires, $_ is set to a Font::FreeType::Glyph object for the current glyph.
  • glyph_from_char(character, fallback = 0) — returns a Font::FreeType::Glyph object for the glyph matching the first character in the string you hand over. Heads up though: currently non-ASCII characters are not likely to work with this, so you might be way better off using the glyph_from_char_code() method below plus Perl's "ord" function. Returns undef if the glyph isn't available in the font and fallback isn't defined; otherwise — i.e. if fallback = true — returns the font's missing glyph.
  • glyph_from_char_code(char-code, fallback = 0) — returns a Font::FreeType::Glyph object for the glyph matching Unicode character char-code. FreeType supports using other character sets, but this module doesn't yet. Returns undef if the glyph isn't available in the font and fallback isn't defined; otherwise — i.e. if fallback = true — returns the font's missing glyph.
  • get_name_index(name) — looks up a glyph by name and returns the index for that glyph in the font. Returns 0 if the name is not found.
  • glyph_from_index(index) — returns a Font::FreeType::Glyph object for the glyph at the given index. Simple, clean, slay.
  • glyph_from_name(name, fallback = 0) — looks up a glyph by name and returns a Font::FreeType::Glyph object. Returns undef if the glyph isn't available in the font and fallback isn't defined; otherwise — i.e. if fallback = true — returns the font's missing glyph.
  • has_glyph_names() — true if individual glyphs have names. If they do, you can grab those names with the name() method on Font::FreeType::Glyph objects. Also peep has_reliable_glyph_names() below 👇
  • has_horizontal_metrics() / has_vertical_metrics() — these return true if the font contains metrics for the corresponding directional layout. Most fonts have horizontal metrics, describing (for example) how characters should be spaced out across a page when written horizontally like English. Some fonts — Chinese ones, for example — may also have vertical metrics, letting you typeset down the page. Obsessed with the range 🌀
  • has_kerning() — true if the font provides kerning information. See the kerning() method below.
  • has_reliable_glyph_names() — true if the font contains reliable PostScript glyph names. Some fonts contain bad glyph names, and that is not the vibe. This method always returns false when used with Freetype versions earlier than 2.1.1. Also peep has_glyph_names() above.
  • height() — the line height of the text, i.e. the distance between the baselines of two lines of text.
  • is_bold() — true if the font claims to be in a bold style. Bold of it to claim that 💪
  • is_fixed_width() — true if all the characters in the font are the same width. Will be true for monospaced fonts like Courier.
  • is_italic() — returns true if the font claims to be in an italic style. Lean into it 🌀
  • is_scalable() — true if the font has a scalable outline, meaning it can be rendered nicely at virtually any size. Returns false for bitmap fonts.
  • is_sfnt() — true if the font file is in the 'sfnt' format, meaning it's either TrueType or OpenType. Not much use yet, but future versions of this library might give you access to extra information about sfnt fonts. Stay tuned ✨
  • kerning(left-glyph-index, right-glyph-index, [mode]) — returns the suggested kerning adjustment between two glyphs. In scalar context it returns a single value, which should be added to the position of the second glyph on the x axis for horizontal layouts, or on the y axis for vertical layouts.
📌 Note: currently it always returns the x axis kerning, but that'll get fixed when vertical layouts are handled properly.

For example, assuming $left and $right are two Font::FreeType::Glyph objects:

my $kern_distance = $face->kerning($left->index, $right->index);

In list context this returns two values corresponding to the x and y axes, which should be treated the same way.

The mode argument controls how the kerning is calculated, with these options available:

  • FT_KERNING_DEFAULT — grid-fitting (hinting) and scaling are done. Use this when rendering glyphs to bitmaps, to make the kerning take the resolution of the output in to account.
  • FT_KERNING_UNFITTED — scaling is done, but not hinting. Use this when extracting the outlines of glyphs. If you used the "FT_LOAD_NO_HINTING" option when creating the face then use this when calculating the kerning.
  • FT_KERNING_UNSCALED — leave the measurements in font units, without scaling and without hinting. Raw. Unbothered. 💅
  • load_flags() — retrieve the load_flags option used.
  • load_flags(load_flags) — setting the load_flags option. Returns the newly set value.
  • number_of_faces() — the number of faces contained in the file this one was created from. Usually there's only one. Peep "Font::FreeType->face()" for how to load the others if there are more.
  • number_of_glyphs() — the number of glyphs in the font face.
  • postscript_name() — a string containing the PostScript name of the font, or undef if it doesn't have one.
  • set_char_size(width, height, x_res, y_res) — sets the size at which glyphs should be rendered. Metrics get scaled to match too. The width and height will usually be the same, and they're in points. The resolution is in dots-per-inch. When generating PostScript outlines, a resolution of 72 will scale to PostScript points.
  • set_pixel_size(width, height) — sets the size at which bitmapped fonts will be loaded. Bitmap fonts get automatically set to the first available standard size, so you usually don't need this.
  • style_name() — a string describing the style of the font, like 'Roman' or 'Demi Bold'. Most TrueType fonts are just 'Regular'. Respectfully, live a little 🎀
  • underline_position() / underline_thickness() — the suggested position and thickness of underlining for the font, or undef if the information isn't provided. Currently in font units, but that's likely to change in a future version. Don't get attached.
  • units_per_em() — the size of the em square used by the font designer. You can use this to scale font-specific measurements to the right size, although FreeType usually does that for you. Usually this is 2048 for TrueType fonts.
  • charmap() — the current active charmap for this face.
  • charmaps() — an array of the charmaps of the face.
  • bounding_box() — the outline's bounding box for this face. It's giving perimeter, it's giving boundaries ✨

👑 SEE ALSO 👑

  • Font::FreeType
  • Font::FreeType::Glyph
  • Font::FreeType::CharMap

Go read those next, bestie, they're the whole friend group 🫶

🌈 AUTHOR 🌈

Geoff Richards <qef@laxan.com>

Copyright 2004, Geoff Richards.

This library 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 lil doc shipped with perl v5.42.3 and is dated 2026-08-19 — so if you're reading it in the future, hiii, hope your glyphs are all rendering correctly 💖🎀🦋

📦 where this page comes from