The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Font-TTFMetrics-0.1
River stage one • 1 direct dependent • 1 total dependent
++
/ Font::TTFMetrics

NAME

Font::TTFMetrics - A parser for the TTF file.

SYNOPSIS

  use Font::TTFMetrics;

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

DESCRIPTION

Font::TTFMetrics encapsulates the font metrics of a true type font file. A true type font file contains several tables which need to be parsed before any useful information could be gathered about the font. There is the excellent module for parsing TTF font in CPAN by Martin Hosken, Font::TTF. But in my opinion the use of Font::TTF requires intimate knowledge of TTF font format. This module was written to support the use of TTF in Pastel 2D graphics library in Perl. Three factors prompted me to write this module: first, I required a fast module to access TTF file. Second, all the access required was read-only. Last, I wanted a user friendly, higher level API to access TTF file.

Each font file actually contains several informations the most important information is how a particular character will display on screen. The shape of a character (glyph) is determined by a series of points. The points are generally lines or points on curved path. For details see the TTF specification. Remember, the points actually determines the outline of the curve.TTF file stores the glyph shape in the "glyf" table of the font. The first glyph described in this table will be always a particular glyph, called "missing-glyph" which is shown in case the font file doesnot contains the glyph that a software wants.

Each character in computer is actually a number. You can find what number corresponds to the character, you can call ord() on the character. This value is called the ordinal value of the character. If you just use common english typically the number of any character falls between 32-126, commonly called as ASCII. If you use some more extra character not commonly found in key-board like "degree" then your character code will fall between 0-255, commonly called LATIN-1 character set. Unicode is a way to use charaters with ordinal values beyond 255. The good thing about it is that the UTF8 encoding in perl works silently in the backdrop and you can intermix characters with any ordinal value. This ofcourse does not mean that you will be able to use character with any ordinal values for display. The font file must contains the corresponding glyph.

The way to extract the glyph for a character is done by looking into "cmap" table of the font. This table contains the character ordinal number and a correspoding index. This index is used to look into the "glyf" table to extract the shape of the character. Thar 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 is one more way to display a particular character instead of what if 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 fonts supplied by Microsoft called symbol fonts. Example of these are symbol.ttf and wingding. Both these fonts does not supply any glyphs corresponding to LATIN-1 character sets but with ordinal values in the range of 61472-61695. But notice if you fire up your word-processor and change the font to symbol and type any character on the key board you get a display. For example, if you type A (ordinal value 65) what you get is greek capital alpha. This works this way: as soon as the word-processor find that you are using a symbol font (you can call is_symbol() method to find that) it just adds 61440 to any character you type and then queries the "cmap" table for the glyph.

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

User of this module should keep in mind that all the values returned from this modules are in font-units and should be converted to pixel unit 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 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 into it. That means a string like:

 "Something \x{70ff}" is perfectly valid.

CONSTRUCTOR

new()

Creates and returns a Font::TTFMetrics object.

 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. The function at present only calculates the advanced width of the each character and deducts the calculated kerning from the whole length. If some one has any better idea then let me 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 to 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 of 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 italic version of the font. Thar means if you call this function on arialbi.ttf or ariali.ttf it returns true.

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

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

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

is_fixed_pitch()

Returns true for a fixed-pitched font like courier.

 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.