1Font::TTF::Manual(3) User Contributed Perl Documentation Font::TTF::Manual(3)
2
6 Font::TTF::Manual - Information regarding the whole module set
7
9 This document looks at the whole issue of how the various modules in
10 the TrueType Font work together. As such it is partly information on
11 this font system and partly information on TrueType fonts in general.
12 Due to the inter-relation between so many tables in a TrueType font,
14 different tables will make expectations as to which other tables exist.
15 At the very least a font should consist of a "head" table and a "maxp"
16 table. The system has been designed around the expectation that the
17 necessary tables for font rendering in the Windows environment exist.
18 But inter table dependencies have been kept to what are considered nec‐
19 essary.
20 This module set is not meant as a simple to use, mindless, font editing
22 suite, but as a low-level, get your hands dirty, know what you are
23 doing, set of classes for those who understand the intricacies (and
24 there are many) of TrueType fonts. To this end, if you get something
25 wrong in the data structures, etc. then this module set won't tell you
26 and will happily create fonts which don't work.
27 At the time of writing, not every TrueType table in existence has been
29 implemented! Only the core basic tables of TrueType 1.0 (i.e. no embed‐
30 ded bitmap tables, no postscript type tables, no OpenType tables and no
31 GX tables) have been implemented. If you want to help by implementing
32 another table or two, then please go ahead and send me your code. For a
33 full list of tables, see Font::TTF::Font.
34 Design Principles
36 PERL is not C++. C++ encourages methods to be written for changing and
38 reading each instance variable in a class. If we did this in this PERL
39 program the results would be rather large and slow. Instead, since most
40 access will be read access, we expose as much of the inner storage of
41 an object to user access directly via hash lookup. The advantage this
42 gives are great. For example, by following an instance variable chain,
43 looking up the "yMax" parameter for a particular glyph becomes:
44 $f->{'loca'}{'glyphs'}[$glyph]{'yMax'}
46 Or, if we are feeling very lazy and don't mind waiting:
48 $f->{'loca'}{'glyphs'}[$f->{'cmap'}->ms_lookup(0x41)]{'yMax'}
50 The disadvantage of this method is that it behoves module users to
52 behave themselves. Thus it does not hold your hand and ensure that if
53 you make a change to a table, that the table is marked as dirty, or
54 that other tables are updated accordingly.
55 It is up to the application developer to understand the implications of
57 the changes they make to a font, and to take the necessary action to
58 ensure that the data they get out is what they want. Thus, you could go
59 and change the "yMax" value on a glyph and output a new font with this
60 change, but it is up to you to ensure that the font's bounding box
61 details in the "head" table are correct, and even that your changing
62 "yMax" is well motivated.
63 To help with using the system, each module (or table) will not only
65 describe the methods it supports, which are relatively few, but also
66 the instance variables it supports, which are many. Most of the vari‐
67 ables directly reflect table attributes as specified in the OpenType
68 specification, available from Microsoft ("www.microsoft.com/typography"
69 in http::), Adobe and Apple. A list of the names used is also given in
70 each module, but not necessarily with any further description. After
71 all, this code is not a TrueType manual as well!
72 Conventions
74 There are various conventions used in this system.
76 Firstly we consider the documentation conventions regarding instance
78 variables. Each instance variable is marked indicating whether it is a
79 (P)rivate variable which users of the module are not expected to read
80 and certainly not write to or a (R)ead only variable which users may
81 well want to read but not write to.
82
84 This section examines various methods and how the various modules work
85 with these methods.
86 read and read_dat
88 Before the data structures for a table can be accessed, they need to be
90 filled in from somewhere. The usual way to do this is to read an exist‐
91 ing TrueType font. This may be achieved by:
92 $f = Font::TTF::Font->open($filename) ⎪⎪ die "Unable to read $filename";
94 This will open an existing font and read its directory header. Notice
96 that at this point, none of the tables in the font have been read.
97 (Actually, the "head" and "maxp" tables are read at this point too
98 since they contain the commonly required parameters of):
99 $f->{'head'}{'unitsPerEm'}
101 $f->{'maxp'}{'numGlyphs'}
102 In order to be able to access information from a table, it is first
104 necessary to "read" it. Consider trying to find the advance width of a
105 space character (U+0020). The following code should do it:
106 $f = Font::TTF::Font->open($ARGV[0]);
108 $snum = $f->{'cmap'}->ms_lookup(0x0020);
109 $sadv = $f->{'hmtx'}{'advance'}[$snum];
110 print $sadv;
111 This would result in the value zero being printed, which is far from
113 correct. But why? The first line would correctly read the font direc‐
114 tory. The second line would, incidently, correctly locate the space
115 character in the Windows cmap (assuming a non symbol encoded font). The
116 third line would not succeed in its task since the "hmtx" table has not
117 been filled in from the font file. To achieve what we want we would
118 first need to cause it to be read:
119 $f->{'hmtx'}->read;
121 $sadv = $f->{'hmtx'}{'advance'}[$snum];
122 Or for those who are too lazy to write multiple lines, "read" returns
124 the object it reads. Thus we could write:
125 $sadv = $f->{'hmtx'}->read->{'advance'}[$snum];
127 Why, if we always have to read tables before accessing information from
129 them, did we not have to do this for the "cmap" table? The answer lies
130 in the method call. It senses that the table hasn't been read and reads
131 it for us. This will generally happen with all method calls, it is only
132 when we do direct data access that we have to take the responsibility
133 to read the table first.
134 Reading a table does not necessarily result in all the data being
136 placed into internal data structures. In the case of a simple table
137 "read" is sufficient. In fact, the normal case is that "read_dat"
138 reads the data from the file into an instance variable called ' dat'
139 (including the space) and not into the data structures.
140 This is true except for the "glyph" class which represents a single
142 glyph. Here the process is reversed. Reading a "glyph" reads the data
143 for the glyph into the ' dat' instance variable and sets various header
144 attributes for the glyph ("xMin", "numContours", etc.). The data is
145 converted out of the variable into data structures via the "read_dat"
146 method.
147 The aim, therefore, is that "read" should do the natural thing (read
149 into data structures for those tables and elements for which it is
150 helpful -- all except "glyph" at present) and "read_dat" should do the
151 unnatural thing: read just the binary data for normal tables and con‐
152 vert binary data to data structures for "glyph"s.
153 In summary, therefore, use "read" unless you want to hack around with
155 the internals of glyphs in which case see Font::TTF::Glyph for more
156 details.
157 update
159 The aim of this method is to allow the various data elements in a
161 "read" font to update themselves. All tables know how to update them‐
162 selves. All tables also contain information which cannot be updated but
163 is new knowledge in the font. As a result, certain tables do nothing
164 when they are updated. We can, therefore, build an update hierarchy of
165 tables, with the independent tables at the bottom and "Font" at the
166 top:
167 +--loca
169 ⎪
170 glyf--+--maxp
171 ⎪
172 +---+--head
173 ⎪
174 hmtx------+--hhea
175 cmap-----OS/2
177 name--
179 post--
181 There is an important universal dependency which it is up to the user
183 to keep up to date. This is "maxp/numOfGlyphs" which is used to iterate
184 over all the glyphs. Note that the glyphs themselves are not held in
185 the "glyph" table but in the "loca" table, so adding glyphs, etc. auto‐
186 matically involves keeping the "loca" table up to date.
187 Creating fonts
189 Suppose we were creating a font from scratch. How much information do
191 we need to supply and how much will "update" do for us?
192 The following information is required:
194 $f->{'loca'}{'glyphs'}
196 $f->{'head'}{'upem'}
197 $f->{'maxp'}{'numGlyphs'} (doesn't come from $f->{'loca'}{'glyphs'})
198 $f->{'hmtx'}{'advance'}
199 $f->{'post'}['format'}
200 $f->{'post'}{'VAL'}
201 $f->{'cmap'}
202 $f->{'name'}
203 Pretty much everything else is calculated for you. Details of what is
205 needed for a glyph may be found in Font::TTF::Glyph. Once we have all
206 the information we need (and there is lots more that you could add)
207 then we simply
208 $f->dirty; # mark all tables dirty
210 $f->update; # update the font
211
213 Martin Hosken Martin_Hosken@sil.org. See Font::TTF::Font for copyright
214 and licensing.
215perl v5.8.8 2005-06-14 Font::TTF::Manual(3)