# Font::TTF::Font - perldoc - [phpMan]

## NAME
    [Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown) - Memory representation of a font

## 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.

        $f = [Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)->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->{'loca'}->glyphs_do(sub { $_[0]->read; });
        $f->{'loca'}->glyphs_do(sub { $_[0]->read_dat; });
        # NB. no need to $g->update since $f->{'glyf'}->out will do it for us

        $f->out($ARGV[1]);
        $f->release;            # clear up memory forcefully!

## 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:

        $f->{$tablename}->read;

    Classes are included that support many of the different TrueType tables. For those for which no
    special code exists, the table type "table" is used, which defaults to [Font::TTF::Table](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ATable/markdown). The
    current tables which are supported are:

        table       [Font::TTF::Table](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ATable/markdown)      - for unknown tables
        EBDT        [Font::TTF::EBDT](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AEBDT/markdown)
        EBLC        [Font::TTF::EBLC](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AEBLC/markdown)
        Feat        [Font::TTF::GrFeat](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGrFeat/markdown)
        GDEF        [Font::TTF::GDEF](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGDEF/markdown)
        GPOS        [Font::TTF::GPOS](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGPOS/markdown)
        GSUB        [Font::TTF::GSUB](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGSUB/markdown)
        Glat        [Font::TTF::Glat](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGlat/markdown)
        Gloc        [Font::TTF::Gloc](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGloc/markdown)
        LTSH        [Font::TTF::LTSH](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ALTSH/markdown)
        OS/2        [Font::TTF::OS_2](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AOS2/markdown)
        PCLT        [Font::TTF::PCLT](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3APCLT/markdown)
        Sill        [Font::TTF::Sill](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ASill/markdown)
        Silf        [Font::TTF::Silf](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ASilf/markdown)
        bsln        [Font::TTF::Bsln](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ABsln/markdown)
        cmap        [Font::TTF::Cmap](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ACmap/markdown)       - see also [Font::TTF::OldCmap](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AOldCmap/markdown)
        cvt         [Font::TTF::Cvt_](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ACvt/markdown)
        fdsc        [Font::TTF::Fdsc](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFdsc/markdown)
        feat        [Font::TTF::Feat](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFeat/markdown)
        fmtx        [Font::TTF::Fmtx](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFmtx/markdown)
        fpgm        [Font::TTF::Fpgm](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFpgm/markdown)
        glyf        [Font::TTF::Glyf](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGlyf/markdown)       - see also [Font::TTF::Glyph](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGlyph/markdown)
        hdmx        [Font::TTF::Hdmx](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AHdmx/markdown)
        head        [Font::TTF::Head](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AHead/markdown)
        hhea        [Font::TTF::Hhea](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AHhea/markdown)
        hmtx        [Font::TTF::Hmtx](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AHmtx/markdown)
        kern        [Font::TTF::Kern](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AKern/markdown)       - see alternative [Font::TTF::AATKern](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AAATKern/markdown)
        loca        [Font::TTF::Loca](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ALoca/markdown)
        maxp        [Font::TTF::Maxp](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AMaxp/markdown)
        mort        [Font::TTF::Mort](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AMort/markdown)       - see also [Font::TTF::OldMort](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AOldMort/markdown)
        name        [Font::TTF::Name](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AName/markdown)
        post        [Font::TTF::Post](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3APost/markdown)
        prep        [Font::TTF::Prep](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3APrep/markdown)
        prop        [Font::TTF::Prop](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AProp/markdown)
        vhea        [Font::TTF::Vhea](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AVhea/markdown)
        vmtx        [Font::TTF::Vmtx](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AVmtx/markdown)
        DSIG        [FONT::TTF::DSIG](https://www.chedong.com/phpMan.php/perldoc/FONT%3A%3ATTF%3A%3ADSIG/markdown)

    Links are:

    [Font::TTF::Table](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ATable/markdown) [Font::TTF::EBDT](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AEBDT/markdown) [Font::TTF::EBLC](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AEBLC/markdown) [Font::TTF::GrFeat](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGrFeat/markdown) [Font::TTF::GDEF](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGDEF/markdown)
    [Font::TTF::GPOS](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGPOS/markdown) [Font::TTF::GSUB](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGSUB/markdown) [Font::TTF::Glat](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGlat/markdown) [Font::TTF::Gloc](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGloc/markdown) [Font::TTF::LTSH](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ALTSH/markdown) [Font::TTF::OS_2](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AOS2/markdown)
    [Font::TTF::PCLT](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3APCLT/markdown) [Font::TTF::Sill](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ASill/markdown) [Font::TTF::Silf](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ASilf/markdown) [Font::TTF::Bsln](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ABsln/markdown) [Font::TTF::Cmap](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ACmap/markdown) [Font::TTF::Cvt_](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ACvt/markdown)
    [Font::TTF::Fdsc](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFdsc/markdown) [Font::TTF::Feat](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFeat/markdown) [Font::TTF::Fmtx](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFmtx/markdown) [Font::TTF::Fpgm](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFpgm/markdown) [Font::TTF::Glyf](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGlyf/markdown) [Font::TTF::Hdmx](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AHdmx/markdown)
    [Font::TTF::Head](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AHead/markdown) [Font::TTF::Hhea](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AHhea/markdown) [Font::TTF::Hmtx](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AHmtx/markdown) [Font::TTF::Kern](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AKern/markdown) [Font::TTF::Loca](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ALoca/markdown) [Font::TTF::Maxp](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AMaxp/markdown)
    [Font::TTF::Mort](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AMort/markdown) [Font::TTF::Name](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AName/markdown) [Font::TTF::Post](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3APost/markdown) [Font::TTF::Prep](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3APrep/markdown) [Font::TTF::Prop](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AProp/markdown) [Font::TTF::Vhea](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AVhea/markdown)
    [Font::TTF::Vmtx](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AVmtx/markdown) [Font::TTF::OldCmap](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AOldCmap/markdown) [Font::TTF::Glyph](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AGlyph/markdown) [Font::TTF::AATKern](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AAATKern/markdown) [Font::TTF::OldMort](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AOldMort/markdown)
    [Font::TTF::DSIG](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ADSIG/markdown)

## INSTANCE VARIABLES
    Instance variables begin with a space (and have lengths greater than the 4 characters which make
    up table names).

    nocsum
        This is used during output to disable the creation of the file checksum in the head table.
        For example, during DSIG table creation, this flag will be set to ensure that the file
        checksum is left at zero.

    noharmony
        If set, do not harmonize the script and lang trees of GPOS and GSUB tables. See
        [Font::TTF::Ttopen](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ATtopen/markdown) for more info.

    nocompress
        Is the default value controlling WOFF 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](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ATable/markdown)
        objects may override this default. See [Font::TTF::Table](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3ATable/markdown) for more info.

    fname (R)
        Contains the filename of the font which this object was read from.

    INFILE (P)
        The file handle which reflects the source file for this font.

    OFFSET (P)
        Contains the offset from the beginning of the read file of this particular font directory,
        thus providing support for TrueType Collections.

    WOFF
        Contains a reference to a "[Font::TTF::Woff](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AWoff/markdown)" object.

## METHODS
  [Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)->AddTable($tablename, $class)
    Adds the given class to be used when representing the given table name. It also 'requires' the
    class for you.

  [Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont%3A%3Aread/markdown)
    before using a table.

  [Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)->new(%props)
    Creates a new font object and initialises with the given properties. This is primarily for use
    when a TTF 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.

  [Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)->open($fname)
    Reads the header and directory for the given font file and creates appropriate objects for each
    table in the font.

  $f->read
    Reads a Truetype font directory starting from location "$self-"{' OFFSET'}> in the file. This
    has been separated from the "open" function to allow support for embedded TTFs for example in
    TTCs. Also reads the "head" and "maxp" tables immediately.

  $f->out($fname [, @tablelist])
    Writes a TTF 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)

    In many cases the user simply wants to output all the tables in alphabetical order. This can be
    done by not including a @tablelist, in which case the subroutine will output all the defined
    tables in the font in alphabetical order.

    Returns $f on success and undef on failure, including warnings.

    All output files must include the "head" table.

  $f->out_xml($filename [, @tables])
    Outputs the font in XML format

  $f->XML_start($context, $tag, %attrs)
    Handles start messages from the XML parser. Of particular interest to us are <font> and <table>.

  $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).

  $f->dirty
    Dirties all the tables in the font

  $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:

        &func($table, $name);

    May optionally take a list of table names in which case func is called for each of them in the
    given order.

  $f->release
    Releases ALL of the memory used by the TTF font and all of its component objects. After calling
    this method, do NOT expect to have anything left in the "[Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)" object.

    NOTE, that it is important that you call this method on any "[Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)" 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 'release()' 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 "[Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)" object; it'll have no internal state whatsoever.

    Developer note: As part of the brute-force cleanup done here, this method will throw a warning
    message whenever unexpected key values are found within the "[Font::TTF::Font](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont/markdown)" 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.

## 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:

    Post
        Version 4 format types are not supported yet.

    Cmap
        Format type 2 (MBCS) has not been implemented yet and therefore may cause somewhat spurious
        results for this table type.

    Kern
        Only type 0 & type 2 tables are supported (type 1 & type 3 yet to come).

    TTC and WOFF
        The current [Font::TTF::Font::out](https://www.chedong.com/phpMan.php/perldoc/Font%3A%3ATTF%3A%3AFont%3A%3Aout/markdown) method does not support the writing of TrueType Collections
        or WOFF files.

    DSIG
        Haven't figured out how to correctly calculate and output digital signature (DSIG) table

    In addition there are weaknesses or features of this module library

    *   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.

    *   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.

    Apart from these, I try to keep the code in a state of "no known bugs", which given the amount
    of testing this code has had, is not a guarantee of high quality, yet.

    For more details see the appropriate class files.

## AUTHOR
    Martin Hosken <<http://scripts.sil.org/FontUtils>>.

## LICENSING
    Copyright (c) 1998-2016, SIL International (<http://www.sil.org>)

    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 LICENSE.