1Font::TTFMetrics(3)   User Contributed Perl Documentation  Font::TTFMetrics(3)
2
3
4

NAME

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

SYNOPSIS

9         use Font::TTFMetrics;
10
11         my $metrics = Font::TTFMetrics->new("somefont.ttf");
12         my $ascent = $metrics->get_ascent();
13

DESCRIPTION

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
27       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
38       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
52       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
75       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
84       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
88         fIUnits * pointsize * resolution /(72 * units_per_em)
89
90       An example from the true type specification at
91       <http://www.microsoft.com/typography/otspec/TTCH01.htm>:
92
93       A font-feature of 550 units when used with 18 pt on screen (typically
94       72 dpi resolution) will be
95
96         550 * 18 * 72 / ( 72 * 2048 ) = 4.83 pixels long.
97
98       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
101       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
105        "Something \x{70ff}" is perfectly valid.
106

CONSTRUCTOR

108   new()
109       Creates and returns a "Font::TTFMetrics" object.
110
111        Usage   : my $metrics = Font::TTFMetrics->new($file);
112        Args    : $file - TTF filename.
113        Returns : A Font::TTFMetrics object.
114

METHODS

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
120        Usage   : $metrics->is_symbol();
121        Args    : Nothing.
122        Returns : True if the font is a Symbol font, false otherwise.
123
124   char_width()
125       Returns the advance width of a single character, in font units.
126
127        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
131   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
137        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
141   get_leading()
142       "Leading" is the gap between two lines. The value is present in the
143       "OS/2" table of the font.
144
145        Usage   : $metrics->get_leading();
146        Args    : None.
147        Returns : A scalar Integer.
148
149   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
153        Usage   : $metrics->get_units_per_em();
154        Args    : None.
155        Returns : A scalar integer.
156
157   get_ascent()
158       "Ascent" is the distance between the baseline to the top of the glyph.
159
160        Usage   : $metrics->get_ascent();
161        Args    : None.
162        Returns : A scalar integer.
163
164   get_descent()
165       "Descent" is the negative distance from the baseline to the lowest
166       point of the glyph.
167
168        Usage   : $metrics->get_descent();
169        Args    : None.
170        Returns : A scalar integer.
171
172   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
177        Usage   : $metrics->is_bold()
178        Args    : None.
179        Returns : True if the font is a bold font, returns false otherwise.
180
181   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
185        Usage   : $metrics->is_italic()
186        Args    : None
187        Returns : True if the font italic, false otherwise
188
189   get_font_family()
190       Returns the family name of the font.
191
192        Usage   : $metrics->get_font_family()
193        Args    : None
194        Returns : A scalar
195
196   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
203        Usage   : $metrics->get_subfamily()
204        Args    : None
205        Returns : A scalar.
206
207   is_fixed_pitch()
208       Returns true for a fixed-pitched font like courier.
209
210        Usage   : $metrics->is_fixed_pitch()
211        Args    : None
212        Returns : True for a fixed-pitched font, false otherwise
213

SEE ALSO

215       Font::TTF, Pastel::Font::TTF.
216

COPYRIGHTS

218       Copyright (c) 2003 by Malay <curiouser@ccmb.res.in>. All rights
219       reserved.
220
221       This program is free software; you can redistribute it and/or modify it
222       under the same terms as Perl itself.
223
224
225
226perl v5.32.1                      2021-01-27               Font::TTFMetrics(3)
Impressum