src/librarian/font-optimizer/ext/Font-TTF/lib/Font/TTF/Manual.pod

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