.\" 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::Font 3"
.TH Font::TTF::Font 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::Font \- Memory representation of a font
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Here is the regression test (you provide your own font). Run it once and then
again on the output of the first run. There should be no differences between
the outputs of the two runs.
.PP
.Vb 1
\&    $f = Font::TTF::Font\->open($ARGV[0]);
\&
\&    # force a read of all the tables
\&    $f\->tables_do(sub { $_[0]\->read; });
\&
\&    # force read of all glyphs (use read_dat to use lots of memory!)
\&    # $f\->{\*(Aqloca\*(Aq}\->glyphs_do(sub { $_[0]\->read; });
\&    $f\->{\*(Aqloca\*(Aq}\->glyphs_do(sub { $_[0]\->read_dat; });
\&    # NB. no need to $g\->update since $f\->{\*(Aqglyf\*(Aq}\->out will do it for us
\&
\&    $f\->out($ARGV[1]);
\&    $f\->release;            # clear up memory forcefully!
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Truetype font consists of a header containing a directory of tables which
constitute the rest of the file. This class holds that header and directory and
also creates objects of the appropriate type for each table within the font.
Note that it does not read each table into memory, but creates a short reference
which can be read using the form:
.PP
.Vb 1
\&    $f\->{$tablename}\->read;
.Ve
.PP
Classes are included that support many of the different TrueType tables. For
those for which no special code exists, the table type \f(CW\*(C`table\*(C'\fR is used, which
defaults to Font::TTF::Table. The current tables which are supported are:
.PP
.Vb 10
\&    table       Font::TTF::Table      \- for unknown tables
\&    EBDT        Font::TTF::EBDT
\&    EBLC        Font::TTF::EBLC
\&    Feat        Font::TTF::GrFeat
\&    GDEF        Font::TTF::GDEF
\&    GPOS        Font::TTF::GPOS
\&    GSUB        Font::TTF::GSUB
\&    Glat        Font::TTF::Glat
\&    Gloc        Font::TTF::Gloc
\&    LTSH        Font::TTF::LTSH
\&    OS/2        Font::TTF::OS_2
\&    PCLT        Font::TTF::PCLT
\&    Sill        Font::TTF::Sill
\&    Silf        Font::TTF::Silf
\&    bsln        Font::TTF::Bsln
\&    cmap        Font::TTF::Cmap       \- see also Font::TTF::OldCmap
\&    cvt         Font::TTF::Cvt_
\&    fdsc        Font::TTF::Fdsc
\&    feat        Font::TTF::Feat
\&    fmtx        Font::TTF::Fmtx
\&    fpgm        Font::TTF::Fpgm
\&    glyf        Font::TTF::Glyf       \- see also Font::TTF::Glyph
\&    hdmx        Font::TTF::Hdmx
\&    head        Font::TTF::Head
\&    hhea        Font::TTF::Hhea
\&    hmtx        Font::TTF::Hmtx
\&    kern        Font::TTF::Kern       \- see alternative Font::TTF::AATKern
\&    loca        Font::TTF::Loca
\&    maxp        Font::TTF::Maxp
\&    mort        Font::TTF::Mort       \- see also Font::TTF::OldMort
\&    name        Font::TTF::Name
\&    post        Font::TTF::Post
\&    prep        Font::TTF::Prep
\&    prop        Font::TTF::Prop
\&    vhea        Font::TTF::Vhea
\&    vmtx        Font::TTF::Vmtx
\&    DSIG        FONT::TTF::DSIG
.Ve
.PP
Links are:
.PP
Font::TTF::Table 
Font::TTF::EBDT Font::TTF::EBLC Font::TTF::GrFeat
Font::TTF::GDEF Font::TTF::GPOS Font::TTF::GSUB Font::TTF::Glat Font::TTF::Gloc Font::TTF::LTSH
Font::TTF::OS_2 Font::TTF::PCLT Font::TTF::Sill Font::TTF::Silf Font::TTF::Bsln Font::TTF::Cmap Font::TTF::Cvt_
Font::TTF::Fdsc Font::TTF::Feat Font::TTF::Fmtx Font::TTF::Fpgm Font::TTF::Glyf
Font::TTF::Hdmx Font::TTF::Head Font::TTF::Hhea Font::TTF::Hmtx Font::TTF::Kern
Font::TTF::Loca Font::TTF::Maxp Font::TTF::Mort Font::TTF::Name Font::TTF::Post
Font::TTF::Prep Font::TTF::Prop Font::TTF::Vhea Font::TTF::Vmtx Font::TTF::OldCmap
Font::TTF::Glyph Font::TTF::AATKern Font::TTF::OldMort
Font::TTF::DSIG
.SH "INSTANCE VARIABLES"
.IX Header "INSTANCE VARIABLES"
Instance variables begin with a space (and have lengths greater than the 4
characters which make up table names).
.IP "nocsum" 4
.IX Item "nocsum"
This is used during output to disable the creation of the file checksum in the
head table. For example, during \s-1DSIG\s0 table creation, this flag will be set to
ensure that the file checksum is left at zero.
.IP "noharmony" 4
.IX Item "noharmony"
If set, do not harmonize the script and lang trees of \s-1GPOS\s0 and \s-1GSUB\s0 tables. See Font::TTF::Ttopen for more info.
.IP "nocompress" 4
.IX Item "nocompress"
Is the default value controlling \s-1WOFF\s0 output table compression. If undef, all tables will be compressed if there is 
a size benefit in doing so. 
It may be set to an array of tagnames naming tables that should not be compressed, or to a scalar integer specifying a 
table size threshold below which tables will not be compressed. 
Note that individual Font::TTF::Table objects may override this default. See Font::TTF::Table for more info.
.IP "fname (R)" 4
.IX Item "fname (R)"
Contains the filename of the font which this object was read from.
.IP "\s-1INFILE\s0 (P)" 4
.IX Item "INFILE (P)"
The file handle which reflects the source file for this font.
.IP "\s-1OFFSET\s0 (P)" 4
.IX Item "OFFSET (P)"
Contains the offset from the beginning of the read file of this particular
font directory, thus providing support for TrueType Collections.
.IP "\s-1WOFF\s0" 4
.IX Item "WOFF"
Contains a reference to a \f(CW\*(C`Font::TTF::Woff\*(C'\fR object.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "Font::TTF::Font\->AddTable($tablename, $class)"
.el .SS "Font::TTF::Font\->AddTable($tablename, \f(CW$class\fP)"
.IX Subsection "Font::TTF::Font->AddTable($tablename, $class)"
Adds the given class to be used when representing the given table name. It also
\&'requires' the class for you.
.SS "Font::TTF::Font\->Init"
.IX Subsection "Font::TTF::Font->Init"
For those people who like making fonts without reading them. This subroutine
will require all the table code for the various table types for you. Not
needed if using Font::TTF::Font::read before using a table.
.SS "Font::TTF::Font\->new(%props)"
.IX Subsection "Font::TTF::Font->new(%props)"
Creates a new font object and initialises with the given properties. This is
primarily for use when a \s-1TTF\s0 is embedded somewhere. Notice that the properties
are automatically preceded by a space when inserted into the object. This is in
order that fields do not clash with tables.
.SS "Font::TTF::Font\->open($fname)"
.IX Subsection "Font::TTF::Font->open($fname)"
Reads the header and directory for the given font file and creates appropriate
objects for each table in the font.
.ie n .SS "$f\->read"
.el .SS "\f(CW$f\fP\->read"
.IX Subsection "$f->read"
Reads a Truetype font directory starting from location \f(CW\*(C`$self\-\*(C'\fR{' \s-1OFFSET\s0'}> in the file.
This has been separated from the \f(CW\*(C`open\*(C'\fR function to allow support for embedded
TTFs for example in TTCs. Also reads the \f(CW\*(C`head\*(C'\fR and \f(CW\*(C`maxp\*(C'\fR tables immediately.
.ie n .SS "$f\->out($fname [, @tablelist])"
.el .SS "\f(CW$f\fP\->out($fname [, \f(CW@tablelist\fP])"
.IX Subsection "$f->out($fname [, @tablelist])"
Writes a \s-1TTF\s0 file consisting of the tables in tablelist. The list is checked to
ensure that only tables that exist are output. (This means that you cannot have
non table information stored in the font object with key length of exactly 4)
.PP
In many cases the user simply wants to output all the tables in alphabetical order.
This can be done by not including a \f(CW@tablelist\fR, in which case the subroutine will
output all the defined tables in the font in alphabetical order.
.PP
Returns \f(CW$f\fR on success and undef on failure, including warnings.
.PP
All output files must include the \f(CW\*(C`head\*(C'\fR table.
.ie n .SS "$f\->out_xml($filename [, @tables])"
.el .SS "\f(CW$f\fP\->out_xml($filename [, \f(CW@tables\fP])"
.IX Subsection "$f->out_xml($filename [, @tables])"
Outputs the font in \s-1XML\s0 format
.ie n .SS "$f\->XML_start($context, $tag, %attrs)"
.el .SS "\f(CW$f\fP\->XML_start($context, \f(CW$tag\fP, \f(CW%attrs\fP)"
.IX Subsection "$f->XML_start($context, $tag, %attrs)"
Handles start messages from the \s-1XML\s0 parser. Of particular interest to us are <font> and
<table>.
.ie n .SS "$f\->update"
.el .SS "\f(CW$f\fP\->update"
.IX Subsection "$f->update"
Sends update to all the tables in the font and then resets all the isDirty
flags on each table. The data structure in now consistent as a font (we hope).
.ie n .SS "$f\->dirty"
.el .SS "\f(CW$f\fP\->dirty"
.IX Subsection "$f->dirty"
Dirties all the tables in the font
.ie n .SS "$f\->tables_do(&func [, tables])"
.el .SS "\f(CW$f\fP\->tables_do(&func [, tables])"
.IX Subsection "$f->tables_do(&func [, tables])"
Calls &func for each table in the font. Calls the table in alphabetical sort
order as per the order in the directory:
.PP
.Vb 1
\&    &func($table, $name);
.Ve
.PP
May optionally take a list of table names in which case func is called
for each of them in the given order.
.ie n .SS "$f\->release"
.el .SS "\f(CW$f\fP\->release"
.IX Subsection "$f->release"
Releases \s-1ALL\s0 of the memory used by the \s-1TTF\s0 font and all of its component
objects.  After calling this method, do \fB\s-1NOT\s0\fR expect to have anything left in
the \f(CW\*(C`Font::TTF::Font\*(C'\fR object.
.PP
\&\fB\s-1NOTE\s0\fR, that it is important that you call this method on any
\&\f(CW\*(C`Font::TTF::Font\*(C'\fR object when you wish to destruct it and free up its memory.
Internally, we track things in a structure that can result in circular
references, and without calling '\f(CW\*(C`release()\*(C'\fR' these will not properly get
cleaned up by Perl.  Once you've called this method, though, don't expect to be
able to do anything else with the \f(CW\*(C`Font::TTF::Font\*(C'\fR object; it'll have \fBno\fR
internal state whatsoever.
.PP
\&\fBDeveloper note:\fR As part of the brute-force cleanup done here, this method
will throw a warning message whenever unexpected key values are found within
the \f(CW\*(C`Font::TTF::Font\*(C'\fR object.  This is done to help ensure that any unexpected
and unfreed values are brought to your attention so that you can bug us to keep
the module updated properly; otherwise the potential for memory leaks due to
dangling circular references will exist.
.SH "BUGS"
.IX Header "BUGS"
Bugs abound aplenty I am sure. There is a lot of code here and plenty of scope.
The parts of the code which haven't been implemented yet are:
.IP "Post" 4
.IX Item "Post"
Version 4 format types are not supported yet.
.IP "Cmap" 4
.IX Item "Cmap"
Format type 2 (\s-1MBCS\s0) has not been implemented yet and therefore may cause
somewhat spurious results for this table type.
.IP "Kern" 4
.IX Item "Kern"
Only type 0 & type 2 tables are supported (type 1 & type 3 yet to come).
.IP "\s-1TTC\s0 and \s-1WOFF\s0" 4
.IX Item "TTC and WOFF"
The current Font::TTF::Font::out method does not support the writing of TrueType
Collections or \s-1WOFF\s0 files.
.IP "\s-1DSIG\s0" 4
.IX Item "DSIG"
Haven't figured out how to correctly calculate and output digital signature (\s-1DSIG\s0) table
.PP
In addition there are weaknesses or features of this module library
.IP "\(bu" 4
There is very little (or no) error reporting. This means that if you have
garbled data or garbled data structures, then you are liable to generate duff
fonts.
.IP "\(bu" 4
The exposing of the internal data structures everywhere means that doing
radical re-structuring is almost impossible. But it stop the code from becoming
ridiculously large.
.PP
Apart from these, I try to keep the code in a state of \*(L"no known bugs\*(R", which
given the amount of testing this code has had, is not a guarantee of high
quality, yet.
.PP
For more details see the appropriate class files.
.SH "AUTHOR"
.IX Header "AUTHOR"
Martin Hosken <http://scripts.sil.org/FontUtils>.
.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