Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Font::TTF::Ttopen(3)  User Contributed Perl Documentation Font::TTF::Ttopen(3)

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

       Handles all the script, lang, feature, lookup stuff for a
       Font::TTF::Gsub/Font::TTF::Gpos table leaving the class specifics to
       the subclass

       The instance variables of an opentype table form	a complex sub-module

	   This	contains the version of	the table as a floating	point number

	   The scripts list is a hash of script	tags. Each script tag (of the
	   form	$t->{'SCRIPTS'}{$tag}) has information below it.

	   OFFSET  This	variable is preceded by	a space	and gives the offset
		   from	the start of the table (not the	table section) to the
		   script table	for this script

	   REFTAG  This	variable is preceded by	a space	and gives a
		   corresponding script	tag to this one	such that the offsets
		   in the file are the same. When writing, it is up to the
		   caller to ensure that the REFTAGs are set correctly,	since
		   these will be used to assume	that the scripts are
		   identical. Note that	REFTAG must refer to a script which
		   has no REFTAG of its	own.

	   DEFAULT This	corresponds to the default language for	this script,
		   if there is one, and	contains the same information as an
		   itemised language

		   This	contains an array of language tag strings (each	4
		   bytes) corresponding	to the languages listed	by this	script

	   $lang   Each	language is a hash containing its information:

		   OFFSET      This variable is	preceded by a a	space and
			       gives the offset	from the start of the whole
			       table to	the language table for this language

		   REFTAG      This variable is	preceded by a space and	has
			       the same	function as for	the script REFTAG,
			       only for	the languages within a script.

		   RE-ORDER    This indicates re-ordering information, and has
			       not been	set. The value should always be	0.

		   DEFAULT     This holds the index of the default feature, if
			       there is	one, or	-1 otherwise.

		   FEATURES    This is an array	of feature tags	for all	the
			       features	enabled	for this language

	   The features	section	of instance variables corresponds to the
	   feature table in the	opentype table.

		   This	array gives the	ordered	list of	feature	tags for this
		   table. It is	used during reading and	writing	for converting
		   between feature index and feature tag.

	   The rest of the FEATURES variable is	itself a hash based on the
	   feature tag for each	feature. Each feature has the following

	   OFFSET  This	attribute is preceded by a space and gives the offset
		   relative to the start of the	whole table of this particular

	   PARMS   If FeatureParams are	defined	for this feature, this
		   contains a reference	to the corresponding FeatureParams
		   object.  Otherwise set to null.

	   LOOKUPS This	is an array containing indices to lookups in the
		   LOOKUP instance variable of the table

	   INDEX   This	gives the feature index	for this feature and is	used
		   during reading and writing for converting between feature
		   tag and feature index.

	   This	variable is an array of	lookups	in order and is	indexed	via
	   the features	of a language of a script. Each	lookup contains
	   subtables and other information:

	   OFFSET  This	name is	preceded by a space and	contains the offset
		   from	the start of the table to this particular lookup

	   TYPE	   This	is a subclass specific type for	a lookup. It
		   stipulates the type of lookup and hence subtables within
		   the lookup

	   FLAG	   Holds the lookup flag bits

	   FILTER  Holds the MarkFilteringSet (that is,	the index into
		   GDEF->MARKSETS) for the lookup.

	   SUB	   This	holds an array of subtables which are subclass
		   specific. Each subtable must	have an	OFFSET.	The other
		   variables described here are	an abstraction used in both
		   the GSUB and	GPOS tables which are the target subclasses of
		   this	class.

		   OFFSET      This is preceded	by a space and gives the
			       offset relative to the start of the table for
			       this subtable

		   FORMAT      Gives the sub-table sub format for this GSUB
			       subtable. It is assumed that this value is
			       correct when it comes time to write the

		   COVERAGE    Most lookups consist of a coverage table
			       corresponding to	the first glyph	to match. The
			       offset of this coverage table is	stored here
			       and the coverage	table looked up	against	the
			       GSUB table proper. There	are two	lookups
			       without this initial coverage table which is
			       used to index into the RULES array.  These
			       lookups have one	element	in the RULES array
			       which is	used for the whole match.

		   RULES       The rules are a complex array. In most cases,
			       each element of the array corresponds to	an
			       element in the coverage table (governed by the
			       coverage	index).	 In a few caess, such as when
			       there is	no coverage table, then	there is
			       considered to be	only one element in the	rules
			       array. Each element of the array	is itself an
			       array corresponding to the possibly multiple
			       string matches which may	follow the initial
			       glyph. Each element of this array is a hash
			       with fixed keys corresponding to	information
			       needed to match a glyph string or act upon it.
			       Thus the	RULES element is an array of arrays of
			       hashes which contain the	following keys:

			       MATCH	       This contains a sequence	of
					       elements	held as	an array. The
					       elements	may be glyph ids
					       (gid), class ids	(cids),	or
					       offsets to coverage tables.
					       Each element corresponds	to one
					       glyph in	the glyph string. See
					       MATCH_TYPE for details of how
					       the different element types are

			       PRE	       This array holds	the sequence
					       of elements preceding the first
					       match element and has the same
					       form as the MATCH array.

			       POST	       This array holds	the sequence
					       of elements to be tested	for
					       following the match string and
					       is of the same form as the
					       MATCH array.

			       ACTION	       This array holds	information
					       regarding what should be	done
					       if a match is found.  The array
					       may either hold glyph ids
					       (which are used to replace or
					       insert or whatever glyphs in
					       the glyph string) or 2 element
					       arrays consisting of:

					       OFFSET		   Offset from
								   the start
								   of the
								   string that
								   the lookup
								   start at

					       LOOKUP_INDEX	   The index
								   to a	lookup
								   to be acted
								   upon	on the

		   CLASS       For those lookups which use class categories
			       rather than glyph ids for matching this is the
			       offset to the class definition used to
			       categories glyphs in the	match string.

		   PRE_CLASS   This is the offset to the class definition for
			       the before match	glyphs

		   POST_CLASS  This is the offset to the class definition for
			       the after match glyphs.

		   ACTION_TYPE This string holds the type of information held
			       in the ACTION variable of a RULE.  It is
			       subclass	specific.

		   MATCH_TYPE  This holds the type of information in the MATCH
			       array of	a RULE.	This is	subclass specific.

		   ADJUST      This corresponds	to a single action for all
			       items in	a coverage table. The meaning is
			       subclass	specific.

		   CACHE       This key	starts with a space

			       A hash of other tables (such as coverage
			       tables, classes,	anchors, device	tables)	based
			       on the offset given in the subtable to that
			       other information.  Note	that the documentation
			       is particularly unhelpful here in that such
			       tables are given	as offsets relative to the
			       beginning of the	subtable not the whole GSUB
			       table. This includes those items	which are
			       stored relative to another base within the

       Reads the table passing control to the subclass to handle the subtable

   $t->read_sub($fh, $lookup, $index)
       This stub is to allow subclasses	to read	subtables of lookups in	a
       table specific manner. A	reference to the lookup	is passed in along
       with the	subtable index.	The file is located at the start of the
       subtable	to be read

       Returns the lookup number for the extension table that allows access to
       32-bit offsets.

       Writes this Opentype table to the output	calling	$t->out_sub for	each
       sub table at the	appropriate point in the output. The assumption	is
       that on entry the number	of scripts, languages, features, lookups, etc.
       are all resolved	and the	relationships fixed. This includes a LANG_TAGS
       list for	a script, and that all scripts and languages in	their
       respective dictionaries either have a REFTAG or contain real data.

       Asks the	subclass to count the number of	subtables for a	particular
       lookup and to return that value.	Used in	out().

   $t->out_sub($fh, $lookup, $index)
       This stub is to allow subclasses	to output subtables of lookups in a
       table specific manner. A	reference to the lookup	is passed in along
       with the	subtable index.	The file is located at the start of the
       subtable	to be output

       Setting GPOS or GSUB dirty means	that OS/2 may need updating, so	set it

       Returns the length of the longest opentype rule in this table.

       Perform various housekeeping items:

       For all lookups,	set/clear 0x0010 bit of	flag words based on 'FILTER'

       Sort COVERAGE table and RULES for all lookups.

       Unless $t->{' PARENT'}{'	noharmony'} is true, update will make sure
       that GPOS and GSUB include the same scripts and languages. Any added
       scripts and languages will have empty feature sets.

Internal Functions & Methods
       Most of these methods are used by subclasses for	handling such things
       as coverage tables.

       Internal	function to copy the top level of a dictionary to create a new
       dictionary.  Only the top level is copied.

   $t->read_cover($cover_offset, $lookup_loc, $lookup, $fh, $is_cover)
       Reads a coverage	table and stores the results in	$lookup->{' CACHE'},
       that is,	if it has not been read	already.

   ref_cache($obj, $cache, $offset [, $template])
       Internal	function to keep track of the local positioning	of subobjects
       such as coverage	and class definition tables, and their offsets.	 What
       happens is that the cache is a hash of sub objects indexed by the
       reference (using	a string mashing of the	reference name which is	valid
       for the duration	of the reference) and holds a list of locations	in the
       output string which should be filled in with the	offset to the sub
       object when the final string is output in out_final.

       Uses tricks for Tie::Refhash

   out_final($fh, $out,	$cache_list, $state)
       Internal	function to actually output everything to the file handle
       given that now we know the offset to the	first sub object to be output
       and which sub objects are to be output and what locations need to be
       updated,	we can now generate everything.	$cache_list is an array	of two
       element arrays. The first element is a cache object, the	second is an
       offset to be subtracted from each reference to that object made in the

       If $state is 1, then the	output is not sent to the filehandle and the
       return value is the string to be	output.	If $state is absent or 0 then
       output is not limited by	storing	in a string first and the return value
       is "";

   $self->read_context($lookup,	$fh, $type, $fmt, $cover, $count, $loc)
       Internal	method to read context (simple and chaining context) lookup
       subtables for the GSUB and GPOS table types. The	assumed	values for
       $type correspond	to those for GSUB, so GPOS should adjust the values
       upon calling.

   $self->out_context($lookup, $fh, $type, $fmt, $ctables, $out, $num)
       Provides	shared behaviour between GSUB and GPOS tables during output
       for context (chained and	simple)	rules. In addition, support is
       provided	here for type 4	GSUB tables, which are not used	in GPOS. The
       value for $type corresponds to the type in a GSUB table so calling from
       GPOS should adjust the value accordingly.

       o   No way to share cachable items (coverage tables, classes, anchors,
	   device tables) across different lookups. The	items are always
	   output after	the lookup and repeated	if necessary. Within lookup
	   sharing is possible.

       Martin Hosken <>.

       Copyright (c) 1998-2016,	SIL International (

       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.

perl v5.24.1			  2016-08-03		  Font::TTF::Ttopen(3)


Want to link to this manual page? Use this URL:

home | help