.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Font::TTF::Manual 3"
.TH Font::TTF::Manual 3 "2016-08-03" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Font::TTF::Manual \- Information regarding the whole module set
.SH "INTRODUCTION"
.IX Header "INTRODUCTION"
This document looks at the whole issue of how the various modules in the
TrueType Font work together. As such it is partly information on this font
system and partly information on TrueType fonts in general.
.PP
Due to the inter-relation between so many tables in a TrueType font, different
tables will make expectations as to which other tables exist. At the very least
a font should consist of a \f(CW\*(C`head\*(C'\fR table and a \f(CW\*(C`maxp\*(C'\fR table. The system has
been designed around the expectation that the necessary tables for font
rendering in the Windows environment exist. But inter table dependencies have
been kept to what are considered necessary.
.PP
This module set is not meant as a simple to use, mindless, font editing suite,
but as a low-level, get your hands dirty, know what you are doing, set of
classes for those who understand the intricacies (and there are many) of
TrueType fonts. To this end, if you get something wrong in the data structures,
etc. then this module set won't tell you and will happily create fonts which
don't work.
.PP
At the time of writing, not every TrueType table in existence has been
implemented! Only the core basic tables of TrueType 1.0 (i.e. no embedded bitmap
tables, no postscript type tables, no OpenType tables and no \s-1GX\s0 tables) have
been implemented. If you want to help by implementing another table or two, then
please go ahead and send me your code. For a full list of tables, see
Font::TTF::Font.
.SS "Design Principles"
.IX Subsection "Design Principles"
\&\s-1PERL\s0 is not \*(C+. \*(C+ encourages methods to be written for changing and reading
each instance variable in a class. If we did this in this \s-1PERL\s0 program the
results would be rather large and slow. Instead, since most access will be read
access, we expose as much of the inner storage of an object to user access
directly via hash lookup. The advantage this gives are great. For example, by
following an instance variable chain, looking up the \f(CW\*(C`yMax\*(C'\fR parameter for a
particular glyph becomes:
.PP
.Vb 1
\&    $f\->{\*(Aqloca\*(Aq}{\*(Aqglyphs\*(Aq}[$glyph]{\*(AqyMax\*(Aq}
.Ve
.PP
Or, if we are feeling very lazy and don't mind waiting:
.PP
.Vb 1
\&    $f\->{\*(Aqloca\*(Aq}{\*(Aqglyphs\*(Aq}[$f\->{\*(Aqcmap\*(Aq}\->ms_lookup(0x41)]{\*(AqyMax\*(Aq}
.Ve
.PP
The disadvantage of this method is that it behoves module users to behave
themselves. Thus it does not hold your hand and ensure that if you make a change
to a table, that the table is marked as \fIdirty\fR, or that other tables are
updated accordingly.
.PP
It is up to the application developer to understand the implications of the
changes they make to a font, and to take the necessary action to ensure that the
data they get out is what they want. Thus, you could go and change the \f(CW\*(C`yMax\*(C'\fR
value on a glyph and output a new font with this change, but it is up to you to
ensure that the font's bounding box details in the \f(CW\*(C`head\*(C'\fR table are correct,
and even that your changing \f(CW\*(C`yMax\*(C'\fR is well motivated.
.PP
To help with using the system, each module (or table) will not only describe the
methods it supports, which are relatively few, but also the instance variables
it supports, which are many. Most of the variables directly reflect table
attributes as specified in the OpenType specification, available from Microsoft
(<http://www.microsoft.com/typography>), Adobe and Apple. A list of the names
used is also given in each module, but not necessarily with any further
description. After all, this code is not a TrueType manual as well!
.SS "Conventions"
.IX Subsection "Conventions"
There are various conventions used in this system.
.PP
Firstly we consider the documentation conventions regarding instance variables.
Each instance variable is marked indicating whether it is a \fB(P)\fRrivate
variable which users of the module are not expected to read and certainly not
write to or a \fB(R)\fRead only variable which users may well want to read but not
write to.
.SH "METHODS"
.IX Header "METHODS"
This section examines various methods and how the various modules work with
these methods.
.SS "read and read_dat"
.IX Subsection "read and read_dat"
Before the data structures for a table can be accessed, they need to be filled
in from somewhere. The usual way to do this is to read an existing TrueType
font. This may be achieved by:
.PP
.Vb 1
\&    $f = Font::TTF::Font\->open($filename) || die "Unable to read $filename";
.Ve
.PP
This will open an existing font and read its directory header. Notice that at
this point, none of the tables in the font have been read. (Actually, the
\&\f(CW\*(C`head\*(C'\fR and \f(CW\*(C`maxp\*(C'\fR tables are read at this point too since they contain the
commonly required parameters of):
.PP
.Vb 2
\&    $f\->{\*(Aqhead\*(Aq}{\*(AqunitsPerEm\*(Aq}
\&    $f\->{\*(Aqmaxp\*(Aq}{\*(AqnumGlyphs\*(Aq}
.Ve
.PP
In order to be able to access information from a table, it is first necessary to
\&\f(CW\*(C`read\*(C'\fR it. Consider trying to find the advance width of a space character
(U+0020). The following code should do it:
.PP
.Vb 4
\&    $f = Font::TTF::Font\->open($ARGV[0]);
\&    $snum = $f\->{\*(Aqcmap\*(Aq}\->ms_lookup(0x0020);
\&    $sadv = $f\->{\*(Aqhmtx\*(Aq}{\*(Aqadvance\*(Aq}[$snum];
\&    print $sadv;
.Ve
.PP
This would result in the value zero being printed, which is far from correct.
But why? The first line would correctly read the font directory. The second line
would, incidently, correctly locate the space character in the Windows cmap
(assuming a non symbol encoded font). The third line would not succeed in its
task since the \f(CW\*(C`hmtx\*(C'\fR table has not been filled in from the font file. To
achieve what we want we would first need to cause it to be read:
.PP
.Vb 2
\&    $f\->{\*(Aqhmtx\*(Aq}\->read;
\&    $sadv = $f\->{\*(Aqhmtx\*(Aq}{\*(Aqadvance\*(Aq}[$snum];
.Ve
.PP
Or for those who are too lazy to write multiple lines, \f(CW\*(C`read\*(C'\fR returns the
object it reads. Thus we could write:
.PP
.Vb 1
\&    $sadv = $f\->{\*(Aqhmtx\*(Aq}\->read\->{\*(Aqadvance\*(Aq}[$snum];
.Ve
.PP
Why, if we always have to read tables before accessing information from them,
did we not have to do this for the \f(CW\*(C`cmap\*(C'\fR table? The answer lies in the method
call. It senses that the table hasn't been read and reads it for us. This will
generally happen with all method calls, it is only when we do direct data access
that we have to take the responsibility to read the table first.
.PP
Reading a table does not necessarily result in all the data being placed into
internal data structures. In the case of a simple table \f(CW\*(C`read\*(C'\fR is sufficient.
In fact, the normal case is that \f(CW\*(C`read_dat\*(C'\fR reads the data from the file into
an instance variable called \f(CW\*(Aq dat\*(Aq\fR (including the space) and not into the
data structures.
.PP
This is true except for the \f(CW\*(C`glyph\*(C'\fR class which represents a single glyph. Here
the process is reversed. Reading a \f(CW\*(C`glyph\*(C'\fR reads the data for the glyph into
the \f(CW\*(Aq dat\*(Aq\fR instance variable and sets various header attributes for the glyph
(\f(CW\*(C`xMin\*(C'\fR, \f(CW\*(C`numContours\*(C'\fR, etc.). The data is converted out of the variable into
data structures via the \f(CW\*(C`read_dat\*(C'\fR method.
.PP
The aim, therefore, is that \f(CW\*(C`read\*(C'\fR should do the natural thing (read into data
structures for those tables and elements for which it is helpful \*(-- all except
\&\f(CW\*(C`glyph\*(C'\fR at present) and \f(CW\*(C`read_dat\*(C'\fR should do the unnatural thing: read just
the binary data for normal tables and convert binary data to data structures for
\&\f(CW\*(C`glyph\*(C'\fRs.
.PP
In summary, therefore, use \f(CW\*(C`read\*(C'\fR unless you want to hack around with the
internals of glyphs in which case see Font::TTF::Glyph for more details.
.SS "update"
.IX Subsection "update"
The aim of this method is to allow the various data elements in a \f(CW\*(C`read\*(C'\fR font
to update themselves. All tables know how to update themselves. All tables also
contain information which cannot be \fIupdated\fR but is new knowledge in the font.
As a result, certain tables do nothing when they are updated. We can, therefore,
build an update hierarchy of tables, with the independent tables at the bottom
and \f(CW\*(C`Font\*(C'\fR at the top:
.PP
.Vb 7
\&       +\-\-loca
\&       |
\& glyf\-\-+\-\-maxp
\&       |
\&       +\-\-\-+\-\-head
\&           |
\& hmtx\-\-\-\-\-\-+\-\-hhea
\&
\& cmap\-\-\-\-\-OS/2
\&
\& name\-\-
\&
\& post\-\-
\&There is an important universal dependency which it is up to the user to
\&keep up to date. This is C<maxp/numOfGlyphs> which is used to iterate over all
\&the glyphs. Note that the glyphs themselves are not held in the C<glyph> table
\&but in the C<loca> table, so adding glyphs, etc. automatically involves keeping
\&the C<loca> table up to date.
.Ve
.SS "Creating fonts"
.IX Subsection "Creating fonts"
Suppose we were creating a font from scratch. How much information do we need
to supply and how much will \f(CW\*(C`update\*(C'\fR do for us?
.PP
The following information is required:
.PP
.Vb 8
\&    $f\->{\*(Aqloca\*(Aq}{\*(Aqglyphs\*(Aq}
\&    $f\->{\*(Aqhead\*(Aq}{\*(Aqupem\*(Aq}
\&    $f\->{\*(Aqmaxp\*(Aq}{\*(AqnumGlyphs\*(Aq}   (doesn\*(Aqt come from $f\->{\*(Aqloca\*(Aq}{\*(Aqglyphs\*(Aq})
\&    $f\->{\*(Aqhmtx\*(Aq}{\*(Aqadvance\*(Aq}
\&    $f\->{\*(Aqpost\*(Aq}[\*(Aqformat\*(Aq}
\&    $f\->{\*(Aqpost\*(Aq}{\*(AqVAL\*(Aq}
\&    $f\->{\*(Aqcmap\*(Aq}
\&    $f\->{\*(Aqname\*(Aq}
.Ve
.PP
Pretty much everything else is calculated for you. Details of what is needed
for a glyph may be found in Font::TTF::Glyph. Once we have all the
information we need (and there is lots more that you could add) then we simply
.PP
.Vb 2
\&    $f\->dirty;          # mark all tables dirty
\&    $f\->update;         # update the font
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Martin Hosken <http://scripts.sil.org/FontUtils>.
(see \s-1CONTRIBUTORS\s0 for other authors).
.SH "LICENSING"
.IX Header "LICENSING"
Copyright (c) 1998\-2016, \s-1SIL\s0 International (http://www.sil.org)
.PP
This module is released under the terms of the Artistic License 2.0.
For details, see the full text of the license in the file \s-1LICENSE.\s0