1Font::TTFMetrics(3) User Contributed Perl Documentation Font::TTFMetrics(3)
2
6 Font::TTFMetrics - A parser for the TTF file.
7
9 use Font::TTFMetrics;
10 my $metrics = Font::TTFMetrics->new("somefont.ttf");
12 my $ascent = $metrics->get_ascent();
13
15 "Font::TTFMetrics" encapsulates the font metrics of a true type font
16 file. A true type font file contains several tables which need to be
17 parsed before any useful information could be gathered about the font.
18 There is the excellent module for parsing TTF font in CPAN by Martin
19 Hosken, "Font::TTF". But in my opinion the use of "Font::TTF" requires
20 intimate knowledge of TTF font format. This module was written to
21 support the use of TTF in "Pastel" 2D graphics library in Perl. Three
22 factors prompted me to write this module: first, I required a fast
23 module to access TTF file. Second, all the access required was read-
24 only. Last, I wanted a user friendly, higher level API to access TTF
25 file.
26 Each font file actually contains several informations the most
28 important information is how a particular character will display on
29 screen. The shape of a character (glyph) is determined by a series of
30 points. The points are generally lines or points on curved path. For
31 details see the TTF specification. Remember, the points actually
32 determines the outline of the curve.TTF file stores the glyph shape in
33 the "glyf" table of the font. The first glyph described in this table
34 will be always a particular glyph, called "missing-glyph" which is
35 shown in case the font file doesnot contains the glyph that a software
36 wants.
37 Each character in computer is actually a number. You can find what
39 number corresponds to the character, you can call "ord()" on the
40 character. This value is called the ordinal value of the character. If
41 you just use common english typically the number of any character falls
42 between 32-126, commonly called as ASCII. If you use some more extra
43 character not commonly found in key-board like "degree" then your
44 character code will fall between 0-255, commonly called LATIN-1
45 character set. Unicode is a way to use charaters with ordinal values
46 beyond 255. The good thing about it is that the UTF8 encoding in perl
47 works silently in the backdrop and you can intermix characters with any
48 ordinal value. This ofcourse does not mean that you will be able to use
49 character with any ordinal values for display. The font file must
50 contains the corresponding glyph.
51 The way to extract the glyph for a character is done by looking into
53 "cmap" table of the font. This table contains the character ordinal
54 number and a correspoding index. This index is used to look into the
55 "glyf" table to extract the shape of the character. Thar means if you
56 just substitute another index for a particular ordinal number you can
57 actually display a different character, a mechanism known as "glyph
58 substitution". As you can guess there is one more way to display a
59 particular character instead of what if should display in a more font
60 specific manner. If you just add a particular offset to a glyph ordinal
61 value and provide the index for this added value in the "cmap" table,
62 you can generate a completely different glyph. This mechanism works for
63 a particular type of fonts supplied by Microsoft called symbol fonts.
64 Example of these are symbol.ttf and wingding. Both these fonts does not
65 supply any glyphs corresponding to LATIN-1 character sets but with
66 ordinal values in the range of 61472-61695. But notice if you fire up
67 your word-processor and change the font to symbol and type any
68 character on the key board you get a display. For example, if you type
69 A (ordinal value 65) what you get is greek capital alpha. This works
70 this way: as soon as the word-processor find that you are using a
71 symbol font (you can call "is_symbol()" method to find that) it just
72 adds 61440 to any character you type and then queries the "cmap" table
73 for the glyph.
74 One more important aspect of using a TTF file is to find the width of a
76 string. The easiest way to find this to query "htmx" table, which
77 contains advanced width of each character, add up all the advance
78 widths of the individual characters in the string and then go look into
79 "kern" table, which contains the kerning value for pair of glyphs add
80 deduct these values from the total width. You need to deduct also the
81 left-side bearing of the first character and the right-side bearing of
82 the last character from the total width.
83 User of this module should keep in mind that all the values returned
85 from this modules are in font-units and should be converted to pixel
86 unit by:
87 fIUnits * pointsize * resolution /(72 * units_per_em)
89 An example from the true type specification at
91 <http://www.microsoft.com/typography/otspec/TTCH01.htm>:
92 A font-feature of 550 units when used with 18 pt on screen (typically
94 72 dpi resolution) will be
95 550 * 18 * 72 / ( 72 * 2048 ) = 4.83 pixels long.
97 Note that the "units_per_em" value is 2048 which is typical for a TTF
99 file. This value can be obtained by calling "get_units_per_em()" call.
100 This module also takes full advantage of the unicode support of Perl.
102 Any strings that you pass to any function call in this module can have
103 unicode built into into it. That means a string like:
104 "Something \x{70ff}" is perfectly valid.
106
108 new()
109 Creates and returns a "Font::TTFMetrics" object.
110 Usage : my $metrics = Font::TTFMetrics->new($file);
112 Args : $file - TTF filename.
113 Returns : A Font::TTFMetrics object.
114
116 is_symbol()
117 Returns true if the font is a Symbol font from Microsoft. Remember that
118 Wingding is also a symbol font.
119 Usage : $metrics->is_symbol();
121 Args : Nothing.
122 Returns : True if the font is a Symbol font, false otherwise.
123 char_width()
125 Returns the advance width of a single character, in font units.
126 Usage : $font->char_width('a');
128 Args : A single perl character. Can be even a unicode.
129 Returns : A scalar value. The width of the character in font units.
130 string_width()
132 Given a string the function returns the width of the string in font
133 units. The function at present only calculates the advanced width of
134 the each character and deducts the calculated kerning from the whole
135 length. If some one has any better idea then let me know.
136 Usage : $font->string_width("Some string");
138 Args : A perl string. Can be embedded unicode.
139 Returns : A scalar indicating the width of the whole string in font units.
140 get_leading()
142 "Leading" is the gap between two lines. The value is present in the
143 "OS/2" table of the font.
144 Usage : $metrics->get_leading();
146 Args : None.
147 Returns : A scalar Integer.
148 get_units_per_em()
150 Get "units_per_em" of the font. This value is present in the "head"
151 table of the font and for TTF is generally 2048.
152 Usage : $metrics->get_units_per_em();
154 Args : None.
155 Returns : A scalar integer.
156 get_ascent()
158 "Ascent" is the distance between the baseline to the top of the glyph.
159 Usage : $metrics->get_ascent();
161 Args : None.
162 Returns : A scalar integer.
163 get_descent()
165 "Descent" is the negative distance from the baseline to the lowest
166 point of the glyph.
167 Usage : $metrics->get_descent();
169 Args : None.
170 Returns : A scalar integer.
171 is_bold()
173 Returns true if the font is a bold variation of the font. That means if
174 you call this function of arial.ttf, it returns false. If you call this
175 function on arialb.ttf it returns true.
176 Usage : $metrics->is_bold()
178 Args : None.
179 Returns : True if the font is a bold font, returns false otherwise.
180 is_italic()
182 Returns true if the font is italic version of the font. Thar means if
183 you call this function on arialbi.ttf or ariali.ttf it returns true.
184 Usage : $metrics->is_italic()
186 Args : None
187 Returns : True if the font italic, false otherwise
188 get_font_family()
190 Returns the family name of the font.
191 Usage : $metrics->get_font_family()
193 Args : None
194 Returns : A scalar
195 get_subfamily()
197 Reuturns the style variation of the font in text. Note that depending
198 on this description might actully be pretty confusing. Call "is_bold()"
199 and/or "is_italic()" to detemine the style. For example a "demi"
200 version of the font is not "bold" by text. But in display this in
201 actually bold variation. In this case "is_bold()" will return true.
202 Usage : $metrics->get_subfamily()
204 Args : None
205 Returns : A scalar.
206 is_fixed_pitch()
208 Returns true for a fixed-pitched font like courier.
209 Usage : $metrics->is_fixed_pitch()
211 Args : None
212 Returns : True for a fixed-pitched font, false otherwise
213
215 Font::TTF, Pastel::Font::TTF.
216
218 Copyright (c) 2003 by Malay <curiouser@ccmb.res.in>. All rights
219 reserved.
220 This program is free software; you can redistribute it and/or modify it
222 under the same terms as Perl itself.
223perl v5.36.0 2022-07-22 Font::TTFMetrics(3)