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
19 necessary.
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
30 embedded bitmap tables, no postscript type tables, no OpenType tables
31 and no GX tables) have been implemented. If you want to help by
32 implementing another table or two, then please go ahead and send me
33 your code. For a 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
37 reading each instance variable in a class. If we did this in this PERL
38 program the results would be rather large and slow. Instead, since most
39 access will be read access, we expose as much of the inner storage of
40 an object to user access directly via hash lookup. The advantage this
41 gives are great. For example, by following an instance variable chain,
42 looking up the "yMax" parameter for a particular glyph becomes:
43 $f->{'loca'}{'glyphs'}[$glyph]{'yMax'}
45 Or, if we are feeling very lazy and don't mind waiting:
47 $f->{'loca'}{'glyphs'}[$f->{'cmap'}->ms_lookup(0x41)]{'yMax'}
49 The disadvantage of this method is that it behoves module users to
51 behave themselves. Thus it does not hold your hand and ensure that if
52 you make a change to a table, that the table is marked as dirty, or
53 that other tables are updated accordingly.
54 It is up to the application developer to understand the implications of
56 the changes they make to a font, and to take the necessary action to
57 ensure that the data they get out is what they want. Thus, you could go
58 and change the "yMax" value on a glyph and output a new font with this
59 change, but it is up to you to ensure that the font's bounding box
60 details in the "head" table are correct, and even that your changing
61 "yMax" is well motivated.
62 To help with using the system, each module (or table) will not only
64 describe the methods it supports, which are relatively few, but also
65 the instance variables it supports, which are many. Most of the
66 variables directly reflect table attributes as specified in the
67 OpenType specification, available from Microsoft
68 (<http://www.microsoft.com/typography>), Adobe and Apple. A list of the
69 names used is also given in each module, but not necessarily with any
70 further description. After all, this code is not a TrueType manual as
71 well!
72 Conventions
74 There are various conventions used in this system.
75 Firstly we consider the documentation conventions regarding instance
77 variables. Each instance variable is marked indicating whether it is a
78 (P)rivate variable which users of the module are not expected to read
79 and certainly not write to or a (R)ead only variable which users may
80 well want to read but not write to.
81
83 This section examines various methods and how the various modules work
84 with these methods.
85 read and read_dat
87 Before the data structures for a table can be accessed, they need to be
88 filled in from somewhere. The usual way to do this is to read an
89 existing TrueType font. This may be achieved by:
90 $f = Font::TTF::Font->open($filename) || die "Unable to read $filename";
92 This will open an existing font and read its directory header. Notice
94 that at this point, none of the tables in the font have been read.
95 (Actually, the "head" and "maxp" tables are read at this point too
96 since they contain the commonly required parameters of):
97 $f->{'head'}{'unitsPerEm'}
99 $f->{'maxp'}{'numGlyphs'}
100 In order to be able to access information from a table, it is first
102 necessary to "read" it. Consider trying to find the advance width of a
103 space character (U+0020). The following code should do it:
104 $f = Font::TTF::Font->open($ARGV[0]);
106 $snum = $f->{'cmap'}->ms_lookup(0x0020);
107 $sadv = $f->{'hmtx'}{'advance'}[$snum];
108 print $sadv;
109 This would result in the value zero being printed, which is far from
111 correct. But why? The first line would correctly read the font
112 directory. The second line would, incidently, correctly locate the
113 space character in the Windows cmap (assuming a non symbol encoded
114 font). The third line would not succeed in its task since the "hmtx"
115 table has not been filled in from the font file. To achieve what we
116 want we would first need to cause it to be read:
117 $f->{'hmtx'}->read;
119 $sadv = $f->{'hmtx'}{'advance'}[$snum];
120 Or for those who are too lazy to write multiple lines, "read" returns
122 the object it reads. Thus we could write:
123 $sadv = $f->{'hmtx'}->read->{'advance'}[$snum];
125 Why, if we always have to read tables before accessing information from
127 them, did we not have to do this for the "cmap" table? The answer lies
128 in the method call. It senses that the table hasn't been read and reads
129 it for us. This will generally happen with all method calls, it is only
130 when we do direct data access that we have to take the responsibility
131 to read the table first.
132 Reading a table does not necessarily result in all the data being
134 placed into internal data structures. In the case of a simple table
135 "read" is sufficient. In fact, the normal case is that "read_dat"
136 reads the data from the file into an instance variable called ' dat'
137 (including the space) and not into the data structures.
138 This is true except for the "glyph" class which represents a single
140 glyph. Here the process is reversed. Reading a "glyph" reads the data
141 for the glyph into the ' dat' instance variable and sets various header
142 attributes for the glyph ("xMin", "numContours", etc.). The data is
143 converted out of the variable into data structures via the "read_dat"
144 method.
145 The aim, therefore, is that "read" should do the natural thing (read
147 into data structures for those tables and elements for which it is
148 helpful -- all except "glyph" at present) and "read_dat" should do the
149 unnatural thing: read just the binary data for normal tables and
150 convert binary data to data structures for "glyph"s.
151 In summary, therefore, use "read" unless you want to hack around with
153 the internals of glyphs in which case see Font::TTF::Glyph for more
154 details.
155 update
157 The aim of this method is to allow the various data elements in a
158 "read" font to update themselves. All tables know how to update
159 themselves. All tables also contain information which cannot be updated
160 but is new knowledge in the font. As a result, certain tables do
161 nothing when they are updated. We can, therefore, build an update
162 hierarchy of tables, with the independent tables at the bottom and
163 "Font" at the top:
164 +--loca
166 |
167 glyf--+--maxp
168 |
169 +---+--head
170 |
171 hmtx------+--hhea
172 cmap-----OS/2
174 name--
176 post--
178 There is an important universal dependency which it is up to the user to
179 keep up to date. This is C<maxp/numOfGlyphs> which is used to iterate over all
180 the glyphs. Note that the glyphs themselves are not held in the C<glyph> table
181 but in the C<loca> table, so adding glyphs, etc. automatically involves keeping
182 the C<loca> table up to date.
183 Creating fonts
185 Suppose we were creating a font from scratch. How much information do
186 we need to supply and how much will "update" do for us?
187 The following information is required:
189 $f->{'loca'}{'glyphs'}
191 $f->{'head'}{'upem'}
192 $f->{'maxp'}{'numGlyphs'} (doesn't come from $f->{'loca'}{'glyphs'})
193 $f->{'hmtx'}{'advance'}
194 $f->{'post'}['format'}
195 $f->{'post'}{'VAL'}
196 $f->{'cmap'}
197 $f->{'name'}
198 Pretty much everything else is calculated for you. Details of what is
200 needed for a glyph may be found in Font::TTF::Glyph. Once we have all
201 the information we need (and there is lots more that you could add)
202 then we simply
203 $f->dirty; # mark all tables dirty
205 $f->update; # update the font
206
208 Martin Hosken <http://scripts.sil.org/FontUtils>. (see CONTRIBUTORS
209 for other authors).
210
212 Copyright (c) 1998-2016, SIL International (http://www.sil.org)
213 This module is released under the terms of the Artistic License 2.0.
215 For details, see the full text of the license in the file LICENSE.
216perl v5.36.0 2023-01-20 Font::TTF::Manual(3)