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

NAME

6       Font::TTF::Ttopen - Opentype superclass for standard Opentype lookup
7       based tables (GSUB and GPOS)
8

DESCRIPTION

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

INSTANCE VARIABLES

15       The instance variables of an opentype table form a complex sub-module
16       hierarchy.
17
18       Version
19           This contains the version of the table as a floating point number
20
21       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
25           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
29           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
37           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
41           LANG_TAGS
42                   This contains an array of language tag strings (each 4
43                   bytes) corresponding to the languages listed by this script
44
45           $lang   Each language is a hash containing its information:
46
47                   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
51                   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
55                   RE-ORDER    This indicates re-ordering information, and has
56                               not been set. The value should always be 0.
57
58                   DEFAULT     This holds the index of the default feature, if
59                               there is one, or -1 otherwise.
60
61                   FEATURES    This is an array of feature tags for all the
62                               features enabled for this language
63
64       FEATURES
65           The features section of instance variables corresponds to the
66           feature table in the opentype table.
67
68           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
73           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
77           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
81           PARMS   If FeatureParams are defined for this feature, this
82                   contains a reference to the corresponding FeatureParams
83                   object.  Otherwise set to null.
84
85           LOOKUPS This is an array containing indices to lookups in the
86                   LOOKUP instance variable of the table
87
88           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
92       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
97           OFFSET  This name is preceded by a space and contains the offset
98                   from the start of the table to this particular lookup
99
100           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
104           FLAG    Holds the lookup flag bits
105
106           FILTER  Holds the MarkFilteringSet (that is, the index into
107                   GDEF->MARKSETS) for the lookup.
108
109           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
115                   OFFSET      This is preceded by a space and gives the
116                               offset relative to the start of the table for
117                               this subtable
118
119                   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
124                   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
134                   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
149                               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
160                               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
165                               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
171                               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
180                                               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
193                                               LOOKUP_INDEX        The index
194                                                                   to a lookup
195                                                                   to be acted
196                                                                   upon on the
197                                                                   match
198                                                                   string.
199
200                   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
205                   PRE_CLASS   This is the offset to the class definition for
206                               the before match glyphs
207
208                   POST_CLASS  This is the offset to the class definition for
209                               the after match glyphs.
210
211                   ACTION_TYPE This string holds the type of information held
212                               in the ACTION variable of a RULE.  It is
213                               subclass specific.
214
215                   MATCH_TYPE  This holds the type of information in the MATCH
216                               array of a RULE. This is subclass specific.
217
218                   ADJUST      This corresponds to a single action for all
219                               items in a coverage table. The meaning is
220                               subclass specific.
221
222                   CACHE       This key starts with a space
223
224                               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

METHODS

236   $t->read
237       Reads the table passing control to the subclass to handle the subtable
238       specifics
239
240   $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
246   $t->extension()
247       Returns the lookup number for the extension table that allows access to
248       32-bit offsets.
249
250   $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
258   $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
262   $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
268   $t->dirty
269       Setting GPOS or GSUB dirty means that OS/2 may need updating, so set it
270       dirty.
271
272   $t->maxContext
273       Returns the length of the longest opentype rule in this table.
274
275   $t->update
276       Perform various housekeeping items:
277
278       For all lookups, set/clear 0x0010 bit of flag words based on 'FILTER'
279       value.
280
281       Sort COVERAGE table and RULES for all lookups.
282
283       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

Internal Functions & Methods

288       Most of these methods are used by subclasses for handling such things
289       as coverage tables.
290
291   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
295   $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
299   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
308       Uses tricks for Tie::Refhash
309
310   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
319       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
324   $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
330   $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

BUGS

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

AUTHOR

344       Martin Hosken <http://scripts.sil.org/FontUtils>.
345

LICENSING

347       Copyright (c) 1998-2016, SIL International (http://www.sil.org)
348
349       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.
351
352
353
354perl v5.38.0                      2023-07-20              Font::TTF::Ttopen(3)
Impressum