1Font::TTF::Font(3) User Contributed Perl Documentation Font::TTF::Font(3)
2
6 Font::TTF::Font - Memory representation of a font
7
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 $f = Font::TTF::Font->open($ARGV[0]);
14 # force a read of all the tables
16 $f->tables_do(sub { $_[0]->read; });
17 # 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 $f->out($ARGV[1]);
24 $f->release; # clear up memory forcefully!
25
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 $f->{$tablename}->read;
34 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 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 Links are:
79 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
93 Instance variables begin with a space (and have lengths greater than
94 the 4 characters which make up table names).
95 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 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 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 fname (R)
116 Contains the filename of the font which this object was read from.
117 INFILE (P)
119 The file handle which reflects the source file for this font.
120 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 WOFF
127 Contains a reference to a "Font::TTF::Woff" object.
128
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 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 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 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 $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 $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 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 Returns $f on success and undef on failure, including warnings.
168 All output files must include the "head" table.
170 $f->out_xml($filename [, @tables])
172 Outputs the font in XML format
173 $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 $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 $f->dirty
184 Dirties all the tables in the font
185 $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 &func($table, $name);
191 May optionally take a list of table names in which case func is called
193 for each of them in the given order.
194 $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 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 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
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 Post
222 Version 4 format types are not supported yet.
223 Cmap
225 Format type 2 (MBCS) has not been implemented yet and therefore may
226 cause somewhat spurious results for this table type.
227 Kern
229 Only type 0 & type 2 tables are supported (type 1 & type 3 yet to
230 come).
231 TTC and WOFF
233 The current Font::TTF::Font::out method does not support the
234 writing of TrueType Collections or WOFF files.
235 DSIG
237 Haven't figured out how to correctly calculate and output digital
238 signature (DSIG) table
239 In addition there are weaknesses or features of this module library
241 • 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 • 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 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 For more details see the appropriate class files.
255
257 Martin Hosken <http://scripts.sil.org/FontUtils>.
258
260 Copyright (c) 1998-2016, SIL International (http://www.sil.org)
261 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.
264perl v5.36.0 2023-01-20 Font::TTF::Font(3)