1Font::TTF::Ttopen(3) User Contributed Perl Documentation Font::TTF::Ttopen(3)
2
6 Font::TTF::Ttopen - Opentype superclass for standard Opentype lookup
7 based tables (GSUB and GPOS)
8
10 Handles all the script, lang, feature, lookup stuff for a
11 Font::TTF::Gsub/Font::TTF::Gpos table leaving the class specifics to
12 the subclass
13
15 The instance variables of an opentype table form a complex sub-module
16 hierarchy.
17 Version
19 This contains the version of the table as a floating point number
20 SCRIPTS
22 The scripts list is a hash of script tags. Each script tag (of the
23 form $t->{'SCRIPTS'}{$tag}) has information below it.
24 OFFSET This variable is preceded by a space and gives the offset
26 from the start of the table (not the table section) to the
27 script table for this script
28 REFTAG This variable is preceded by a space and gives a
30 corresponding script tag to this one such that the offsets
31 in the file are the same. When writing, it is up to the
32 caller to ensure that the REFTAGs are set correctly, since
33 these will be used to assume that the scripts are
34 identical. Note that REFTAG must refer to a script which
35 has no REFTAG of its own.
36 DEFAULT This corresponds to the default language for this script,
38 if there is one, and contains the same information as an
39 itemised language
40 LANG_TAGS
42 This contains an array of language tag strings (each 4
43 bytes) corresponding to the languages listed by this script
44 $lang Each language is a hash containing its information:
46 OFFSET This variable is preceded by a a space and
48 gives the offset from the start of the whole
49 table to the language table for this language
50 REFTAG This variable is preceded by a space and has
52 the same function as for the script REFTAG,
53 only for the languages within a script.
54 RE-ORDER This indicates re-ordering information, and has
56 not been set. The value should always be 0.
57 DEFAULT This holds the index of the default feature, if
59 there is one, or -1 otherwise.
60 FEATURES This is an array of feature tags for all the
62 features enabled for this language
63 FEATURES
65 The features section of instance variables corresponds to the
66 feature table in the opentype table.
67 FEAT_TAGS
69 This array gives the ordered list of feature tags for this
70 table. It is used during reading and writing for converting
71 between feature index and feature tag.
72 The rest of the FEATURES variable is itself a hash based on the
74 feature tag for each feature. Each feature has the following
75 structure:
76 OFFSET This attribute is preceded by a space and gives the offset
78 relative to the start of the whole table of this particular
79 feature.
80 PARMS If FeatureParams are defined for this feature, this
82 contains a reference to the corresponding FeatureParams
83 object. Otherwise set to null.
84 LOOKUPS This is an array containing indices to lookups in the
86 LOOKUP instance variable of the table
87 INDEX This gives the feature index for this feature and is used
89 during reading and writing for converting between feature
90 tag and feature index.
91 LOOKUP
93 This variable is an array of lookups in order and is indexed via
94 the features of a language of a script. Each lookup contains
95 subtables and other information:
96 OFFSET This name is preceded by a space and contains the offset
98 from the start of the table to this particular lookup
99 TYPE This is a subclass specific type for a lookup. It
101 stipulates the type of lookup and hence subtables within
102 the lookup
103 FLAG Holds the lookup flag bits
105 FILTER Holds the MarkFilteringSet (that is, the index into
107 GDEF->MARKSETS) for the lookup.
108 SUB This holds an array of subtables which are subclass
110 specific. Each subtable must have an OFFSET. The other
111 variables described here are an abstraction used in both
112 the GSUB and GPOS tables which are the target subclasses of
113 this class.
114 OFFSET This is preceded by a space and gives the
116 offset relative to the start of the table for
117 this subtable
118 FORMAT Gives the sub-table sub format for this GSUB
120 subtable. It is assumed that this value is
121 correct when it comes time to write the
122 subtable.
123 COVERAGE Most lookups consist of a coverage table
125 corresponding to the first glyph to match. The
126 offset of this coverage table is stored here
127 and the coverage table looked up against the
128 GSUB table proper. There are two lookups
129 without this initial coverage table which is
130 used to index into the RULES array. These
131 lookups have one element in the RULES array
132 which is used for the whole match.
133 RULES The rules are a complex array. In most cases,
135 each element of the array corresponds to an
136 element in the coverage table (governed by the
137 coverage index). In a few caess, such as when
138 there is no coverage table, then there is
139 considered to be only one element in the rules
140 array. Each element of the array is itself an
141 array corresponding to the possibly multiple
142 string matches which may follow the initial
143 glyph. Each element of this array is a hash
144 with fixed keys corresponding to information
145 needed to match a glyph string or act upon it.
146 Thus the RULES element is an array of arrays of
147 hashes which contain the following keys:
148 MATCH This contains a sequence of
150 elements held as an array. The
151 elements may be glyph ids
152 (gid), class ids (cids), or
153 offsets to coverage tables.
154 Each element corresponds to one
155 glyph in the glyph string. See
156 MATCH_TYPE for details of how
157 the different element types are
158 marked.
159 PRE This array holds the sequence
161 of elements preceding the first
162 match element and has the same
163 form as the MATCH array.
164 POST This array holds the sequence
166 of elements to be tested for
167 following the match string and
168 is of the same form as the
169 MATCH array.
170 ACTION This array holds information
172 regarding what should be done
173 if a match is found. The array
174 may either hold glyph ids
175 (which are used to replace or
176 insert or whatever glyphs in
177 the glyph string) or 2 element
178 arrays consisting of:
179 OFFSET Offset from
181 the start
182 of the
183 matched
184 string that
185 the lookup
186 should
187 start at
188 when
189 processing
190 the
191 substring.
192 LOOKUP_INDEX The index
194 to a lookup
195 to be acted
196 upon on the
197 match
198 string.
199 CLASS For those lookups which use class categories
201 rather than glyph ids for matching this is the
202 offset to the class definition used to
203 categories glyphs in the match string.
204 PRE_CLASS This is the offset to the class definition for
206 the before match glyphs
207 POST_CLASS This is the offset to the class definition for
209 the after match glyphs.
210 ACTION_TYPE This string holds the type of information held
212 in the ACTION variable of a RULE. It is
213 subclass specific.
214 MATCH_TYPE This holds the type of information in the MATCH
216 array of a RULE. This is subclass specific.
217 ADJUST This corresponds to a single action for all
219 items in a coverage table. The meaning is
220 subclass specific.
221 CACHE This key starts with a space
223 A hash of other tables (such as coverage
225 tables, classes, anchors, device tables) based
226 on the offset given in the subtable to that
227 other information. Note that the documentation
228 is particularly unhelpful here in that such
229 tables are given as offsets relative to the
230 beginning of the subtable not the whole GSUB
231 table. This includes those items which are
232 stored relative to another base within the
233 subtable.
234
236 $t->read
237 Reads the table passing control to the subclass to handle the subtable
238 specifics
239 $t->read_sub($fh, $lookup, $index)
241 This stub is to allow subclasses to read subtables of lookups in a
242 table specific manner. A reference to the lookup is passed in along
243 with the subtable index. The file is located at the start of the
244 subtable to be read
245 $t->extension()
247 Returns the lookup number for the extension table that allows access to
248 32-bit offsets.
249 $t->out($fh)
251 Writes this Opentype table to the output calling $t->out_sub for each
252 sub table at the appropriate point in the output. The assumption is
253 that on entry the number of scripts, languages, features, lookups, etc.
254 are all resolved and the relationships fixed. This includes a LANG_TAGS
255 list for a script, and that all scripts and languages in their
256 respective dictionaries either have a REFTAG or contain real data.
257 $t->num_sub($lookup)
259 Asks the subclass to count the number of subtables for a particular
260 lookup and to return that value. Used in out().
261 $t->out_sub($fh, $lookup, $index)
263 This stub is to allow subclasses to output subtables of lookups in a
264 table specific manner. A reference to the lookup is passed in along
265 with the subtable index. The file is located at the start of the
266 subtable to be output
267 $t->dirty
269 Setting GPOS or GSUB dirty means that OS/2 may need updating, so set it
270 dirty.
271 $t->maxContext
273 Returns the length of the longest opentype rule in this table.
274 $t->update
276 Perform various housekeeping items:
277 For all lookups, set/clear 0x0010 bit of flag words based on 'FILTER'
279 value.
280 Sort COVERAGE table and RULES for all lookups.
282 Unless $t->{' PARENT'}{' noharmony'} is true, update will make sure
284 that GPOS and GSUB include the same scripts and languages. Any added
285 scripts and languages will have empty feature sets.
286
288 Most of these methods are used by subclasses for handling such things
289 as coverage tables.
290 copy($ref)
292 Internal function to copy the top level of a dictionary to create a new
293 dictionary. Only the top level is copied.
294 $t->read_cover($cover_offset, $lookup_loc, $lookup, $fh, $is_cover)
296 Reads a coverage table and stores the results in $lookup->{' CACHE'},
297 that is, if it has not been read already.
298 ref_cache($obj, $cache, $offset [, $template])
300 Internal function to keep track of the local positioning of subobjects
301 such as coverage and class definition tables, and their offsets. What
302 happens is that the cache is a hash of sub objects indexed by the
303 reference (using a string mashing of the reference name which is valid
304 for the duration of the reference) and holds a list of locations in the
305 output string which should be filled in with the offset to the sub
306 object when the final string is output in out_final.
307 Uses tricks for Tie::Refhash
309 out_final($fh, $out, $cache_list, $state)
311 Internal function to actually output everything to the file handle
312 given that now we know the offset to the first sub object to be output
313 and which sub objects are to be output and what locations need to be
314 updated, we can now generate everything. $cache_list is an array of two
315 element arrays. The first element is a cache object, the second is an
316 offset to be subtracted from each reference to that object made in the
317 cache.
318 If $state is 1, then the output is not sent to the filehandle and the
320 return value is the string to be output. If $state is absent or 0 then
321 output is not limited by storing in a string first and the return value
322 is "";
323 $self->read_context($lookup, $fh, $type, $fmt, $cover, $count, $loc)
325 Internal method to read context (simple and chaining context) lookup
326 subtables for the GSUB and GPOS table types. The assumed values for
327 $type correspond to those for GSUB, so GPOS should adjust the values
328 upon calling.
329 $self->out_context($lookup, $fh, $type, $fmt, $ctables, $out, $num)
331 Provides shared behaviour between GSUB and GPOS tables during output
332 for context (chained and simple) rules. In addition, support is
333 provided here for type 4 GSUB tables, which are not used in GPOS. The
334 value for $type corresponds to the type in a GSUB table so calling from
335 GPOS should adjust the value accordingly.
336
338 • No way to share cachable items (coverage tables, classes, anchors,
339 device tables) across different lookups. The items are always
340 output after the lookup and repeated if necessary. Within lookup
341 sharing is possible.
342
344 Martin Hosken <http://scripts.sil.org/FontUtils>.
345
347 Copyright (c) 1998-2016, SIL International (http://www.sil.org)
348 This module is released under the terms of the Artistic License 2.0.
350 For details, see the full text of the license in the file LICENSE.
351perl v5.36.0 2023-01-20 Font::TTF::Ttopen(3)