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

NAME

6       Font::TTF::Manual - Information regarding the whole module set
7

INTRODUCTION

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
13       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
21       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
28       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
35   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
44           $f->{'loca'}{'glyphs'}[$glyph]{'yMax'}
45
46       Or, if we are feeling very lazy and don't mind waiting:
47
48           $f->{'loca'}{'glyphs'}[$f->{'cmap'}->ms_lookup(0x41)]{'yMax'}
49
50       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
55       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
63       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
73   Conventions
74       There are various conventions used in this system.
75
76       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

METHODS

83       This section examines various methods and how the various modules work
84       with these methods.
85
86   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
91           $f = Font::TTF::Font->open($filename) || die "Unable to read $filename";
92
93       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
98           $f->{'head'}{'unitsPerEm'}
99           $f->{'maxp'}{'numGlyphs'}
100
101       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
105           $f = Font::TTF::Font->open($ARGV[0]);
106           $snum = $f->{'cmap'}->ms_lookup(0x0020);
107           $sadv = $f->{'hmtx'}{'advance'}[$snum];
108           print $sadv;
109
110       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
118           $f->{'hmtx'}->read;
119           $sadv = $f->{'hmtx'}{'advance'}[$snum];
120
121       Or for those who are too lazy to write multiple lines, "read" returns
122       the object it reads. Thus we could write:
123
124           $sadv = $f->{'hmtx'}->read->{'advance'}[$snum];
125
126       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
133       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
139       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
146       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
152       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
156   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
165              +--loca
166              |
167        glyf--+--maxp
168              |
169              +---+--head
170                  |
171        hmtx------+--hhea
172
173        cmap-----OS/2
174
175        name--
176
177        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
184   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
188       The following information is required:
189
190           $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
199       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
204           $f->dirty;          # mark all tables dirty
205           $f->update;         # update the font
206

AUTHOR

208       Martin Hosken <http://scripts.sil.org/FontUtils>.  (see CONTRIBUTORS
209       for other authors).
210

LICENSING

212       Copyright (c) 1998-2016, SIL International (http://www.sil.org)
213
214       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.
216
217
218
219perl v5.30.1                      2020-01-30              Font::TTF::Manual(3)
Impressum