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

NAME

6       Font::TTF::Font - Memory representation of a font
7

SYNOPSIS

9       Here is the regression test (you provide your own font). Run it once
10       and then again on the output of the first run. There should be no
11       differences between the outputs of the two runs.
12
13           $f = Font::TTF::Font->open($ARGV[0]);
14
15           # force a read of all the tables
16           $f->tables_do(sub { $_[0]->read; });
17
18           # force read of all glyphs (use read_dat to use lots of memory!)
19           # $f->{'loca'}->glyphs_do(sub { $_[0]->read; });
20           $f->{'loca'}->glyphs_do(sub { $_[0]->read_dat; });
21           # NB. no need to $g->update since $f->{'glyf'}->out will do it for us
22
23           $f->out($ARGV[1]);
24           $f->release;            # clear up memory forcefully!
25

DESCRIPTION

27       A Truetype font consists of a header containing a directory of tables
28       which constitute the rest of the file. This class holds that header and
29       directory and also creates objects of the appropriate type for each
30       table within the font.  Note that it does not read each table into
31       memory, but creates a short reference which can be read using the form:
32
33           $f->{$tablename}->read;
34
35       Classes are included that support many of the different TrueType
36       tables. For those for which no special code exists, the table type
37       "table" is used, which defaults to Font::TTF::Table. The current tables
38       which are supported are:
39
40           table       Font::TTF::Table      - for unknown tables
41           EBDT        Font::TTF::EBDT
42           EBLC        Font::TTF::EBLC
43           Feat        Font::TTF::GrFeat
44           GDEF        Font::TTF::GDEF
45           GPOS        Font::TTF::GPOS
46           GSUB        Font::TTF::GSUB
47           Glat        Font::TTF::Glat
48           Gloc        Font::TTF::Gloc
49           LTSH        Font::TTF::LTSH
50           OS/2        Font::TTF::OS_2
51           PCLT        Font::TTF::PCLT
52           Sill        Font::TTF::Sill
53           Silf        Font::TTF::Silf
54           bsln        Font::TTF::Bsln
55           cmap        Font::TTF::Cmap       - see also Font::TTF::OldCmap
56           cvt         Font::TTF::Cvt_
57           fdsc        Font::TTF::Fdsc
58           feat        Font::TTF::Feat
59           fmtx        Font::TTF::Fmtx
60           fpgm        Font::TTF::Fpgm
61           glyf        Font::TTF::Glyf       - see also Font::TTF::Glyph
62           hdmx        Font::TTF::Hdmx
63           head        Font::TTF::Head
64           hhea        Font::TTF::Hhea
65           hmtx        Font::TTF::Hmtx
66           kern        Font::TTF::Kern       - see alternative Font::TTF::AATKern
67           loca        Font::TTF::Loca
68           maxp        Font::TTF::Maxp
69           mort        Font::TTF::Mort       - see also Font::TTF::OldMort
70           name        Font::TTF::Name
71           post        Font::TTF::Post
72           prep        Font::TTF::Prep
73           prop        Font::TTF::Prop
74           vhea        Font::TTF::Vhea
75           vmtx        Font::TTF::Vmtx
76           DSIG        FONT::TTF::DSIG
77
78       Links are:
79
80       Font::TTF::Table Font::TTF::EBDT Font::TTF::EBLC Font::TTF::GrFeat
81       Font::TTF::GDEF Font::TTF::GPOS Font::TTF::GSUB Font::TTF::Glat
82       Font::TTF::Gloc Font::TTF::LTSH Font::TTF::OS_2 Font::TTF::PCLT
83       Font::TTF::Sill Font::TTF::Silf Font::TTF::Bsln Font::TTF::Cmap
84       Font::TTF::Cvt_ Font::TTF::Fdsc Font::TTF::Feat Font::TTF::Fmtx
85       Font::TTF::Fpgm Font::TTF::Glyf Font::TTF::Hdmx Font::TTF::Head
86       Font::TTF::Hhea Font::TTF::Hmtx Font::TTF::Kern Font::TTF::Loca
87       Font::TTF::Maxp Font::TTF::Mort Font::TTF::Name Font::TTF::Post
88       Font::TTF::Prep Font::TTF::Prop Font::TTF::Vhea Font::TTF::Vmtx
89       Font::TTF::OldCmap Font::TTF::Glyph Font::TTF::AATKern
90       Font::TTF::OldMort Font::TTF::DSIG
91

INSTANCE VARIABLES

93       Instance variables begin with a space (and have lengths greater than
94       the 4 characters which make up table names).
95
96       nocsum
97           This is used during output to disable the creation of the file
98           checksum in the head table. For example, during DSIG table
99           creation, this flag will be set to ensure that the file checksum is
100           left at zero.
101
102       noharmony
103           If set, do not harmonize the script and lang trees of GPOS and GSUB
104           tables. See Font::TTF::Ttopen for more info.
105
106       nocompress
107           Is the default value controlling WOFF output table compression. If
108           undef, all tables will be compressed if there is a size benefit in
109           doing so.  It may be set to an array of tagnames naming tables that
110           should not be compressed, or to a scalar integer specifying a table
111           size threshold below which tables will not be compressed.  Note
112           that individual Font::TTF::Table objects may override this default.
113           See Font::TTF::Table for more info.
114
115       fname (R)
116           Contains the filename of the font which this object was read from.
117
118       INFILE (P)
119           The file handle which reflects the source file for this font.
120
121       OFFSET (P)
122           Contains the offset from the beginning of the read file of this
123           particular font directory, thus providing support for TrueType
124           Collections.
125
126       WOFF
127           Contains a reference to a "Font::TTF::Woff" object.
128

METHODS

130   Font::TTF::Font->AddTable($tablename, $class)
131       Adds the given class to be used when representing the given table name.
132       It also 'requires' the class for you.
133
134   Font::TTF::Font->Init
135       For those people who like making fonts without reading them. This
136       subroutine will require all the table code for the various table types
137       for you. Not needed if using Font::TTF::Font::read before using a
138       table.
139
140   Font::TTF::Font->new(%props)
141       Creates a new font object and initialises with the given properties.
142       This is primarily for use when a TTF is embedded somewhere. Notice that
143       the properties are automatically preceded by a space when inserted into
144       the object. This is in order that fields do not clash with tables.
145
146   Font::TTF::Font->open($fname)
147       Reads the header and directory for the given font file and creates
148       appropriate objects for each table in the font.
149
150   $f->read
151       Reads a Truetype font directory starting from location "$self-"{'
152       OFFSET'}> in the file.  This has been separated from the "open"
153       function to allow support for embedded TTFs for example in TTCs. Also
154       reads the "head" and "maxp" tables immediately.
155
156   $f->out($fname [, @tablelist])
157       Writes a TTF file consisting of the tables in tablelist. The list is
158       checked to ensure that only tables that exist are output. (This means
159       that you cannot have non table information stored in the font object
160       with key length of exactly 4)
161
162       In many cases the user simply wants to output all the tables in
163       alphabetical order.  This can be done by not including a @tablelist, in
164       which case the subroutine will output all the defined tables in the
165       font in alphabetical order.
166
167       Returns $f on success and undef on failure, including warnings.
168
169       All output files must include the "head" table.
170
171   $f->out_xml($filename [, @tables])
172       Outputs the font in XML format
173
174   $f->XML_start($context, $tag, %attrs)
175       Handles start messages from the XML parser. Of particular interest to
176       us are <font> and <table>.
177
178   $f->update
179       Sends update to all the tables in the font and then resets all the
180       isDirty flags on each table. The data structure in now consistent as a
181       font (we hope).
182
183   $f->dirty
184       Dirties all the tables in the font
185
186   $f->tables_do(&func [, tables])
187       Calls &func for each table in the font. Calls the table in alphabetical
188       sort order as per the order in the directory:
189
190           &func($table, $name);
191
192       May optionally take a list of table names in which case func is called
193       for each of them in the given order.
194
195   $f->release
196       Releases ALL of the memory used by the TTF font and all of its
197       component objects.  After calling this method, do NOT expect to have
198       anything left in the "Font::TTF::Font" object.
199
200       NOTE, that it is important that you call this method on any
201       "Font::TTF::Font" object when you wish to destruct it and free up its
202       memory.  Internally, we track things in a structure that can result in
203       circular references, and without calling '"release()"' these will not
204       properly get cleaned up by Perl.  Once you've called this method,
205       though, don't expect to be able to do anything else with the
206       "Font::TTF::Font" object; it'll have no internal state whatsoever.
207
208       Developer note: As part of the brute-force cleanup done here, this
209       method will throw a warning message whenever unexpected key values are
210       found within the "Font::TTF::Font" object.  This is done to help ensure
211       that any unexpected and unfreed values are brought to your attention so
212       that you can bug us to keep the module updated properly; otherwise the
213       potential for memory leaks due to dangling circular references will
214       exist.
215

BUGS

217       Bugs abound aplenty I am sure. There is a lot of code here and plenty
218       of scope.  The parts of the code which haven't been implemented yet
219       are:
220
221       Post
222           Version 4 format types are not supported yet.
223
224       Cmap
225           Format type 2 (MBCS) has not been implemented yet and therefore may
226           cause somewhat spurious results for this table type.
227
228       Kern
229           Only type 0 & type 2 tables are supported (type 1 & type 3 yet to
230           come).
231
232       TTC and WOFF
233           The current Font::TTF::Font::out method does not support the
234           writing of TrueType Collections or WOFF files.
235
236       DSIG
237           Haven't figured out how to correctly calculate and output digital
238           signature (DSIG) table
239
240       In addition there are weaknesses or features of this module library
241
242       •   There is very little (or no) error reporting. This means that if
243           you have garbled data or garbled data structures, then you are
244           liable to generate duff fonts.
245
246       •   The exposing of the internal data structures everywhere means that
247           doing radical re-structuring is almost impossible. But it stop the
248           code from becoming ridiculously large.
249
250       Apart from these, I try to keep the code in a state of "no known bugs",
251       which given the amount of testing this code has had, is not a guarantee
252       of high quality, yet.
253
254       For more details see the appropriate class files.
255

AUTHOR

257       Martin Hosken <http://scripts.sil.org/FontUtils>.
258

LICENSING

260       Copyright (c) 1998-2016, SIL International (http://www.sil.org)
261
262       This module is released under the terms of the Artistic License 2.0.
263       For details, see the full text of the license in the file LICENSE.
264
265
266
267perl v5.36.0                      2022-07-22                Font::TTF::Font(3)
Impressum