Visual TrueType Private Table Formats

[アーティクル]
09/08/2021

The following tables are used by Visual TrueType to store hinting source data. These tables should be removed from a font prior to shipping the font (e.g., using VTT’s “Ship Font” option in the “Tools” menu).

TSI0 (Glyph Program Text Indices)

This table contains the information needed to access the glyph program text string data (stored in table TSI1) for the individual glyphs, as well as for three tables used by Visual TrueType (Pre-program, Font program, and CVT). This table should have the same size as table TSI2.

Type	Name	Comments
uint16	glyphIndex	Glyph Index associated with this block of text (search via this field)
uint16	textLength	Length of text (or 0x8000 to indicate any value larger than 32767); does not include null termination character.
uint16	textOffset	Offset from start of TSI1 table
uint32	textOffset	Offset from start of TSI1 table

For text with a length less than 32768, the actual length should be placed in the textLength field. For text with a length greater than 32767, the value 0x8000 should be placed in the textLength field.

This record is repeated once for each valid glyph index (“normal records”), and is then followed by five more entries (“extra records”) at the end, as follows:

“Magic number” used to check for validity. For this entry, the glyphIndex field must be set to 0xFFFE and the textOffset field is set to the magic number (0xABFC1F34).
Offset to Pre-program source data. Set the glyphIndex field to 0xFFFA.
Offset to CVT source data. Set the glyphIndex field to 0xFFFB.
Reserved. Set the glyphIndex field to 0xFFFC.
Offset to Font program source data. Set the glyphIndex field to 0xFFFD.

The table will then have the following structure:

glyphIndex	textLength	textOffset	Comment
0	length	actual offset	“normal” glyph index data
. . .	. . .	. . .	“normal” glyph index data
numGlyphs-1	length	actual offset	“normal” glyph index data
0xFFFE	0	0xABFC1F34	“extra” record (magic number)
0xFFFA	length	actual offset	“extra” record (ppgm data)
0xFFFB	length	actual offset	“extra” record (cvt data)
0xFFFC	length	actual offset	“extra” record (reserved)
0xFFFD	length	actual offset	“extra” record (fpgm data)

Because the actual length of a record may or may not be stored in the textLength field, follow these rules to determine the actual length:

If the length stored in the record is less than 32768, then the actual length is the length noted in the record.
If the length stored in the record is 32768 (0x8000), then the actual length is computed as follows:
- For the last “extra” record (the very last record of the table), the length is the difference between the total length of the TSI1 table and the textOffset of the final record.
- For the last “normal” record (the last record just prior to the record containing the “magic number”), the length is the difference between the textOffset of the record following the “magic number” record and the textOffset of the last “normal” record.
- For all other records with a length of 0x8000, the length is the difference between the textOffset of the record in question and the textOffset of the next record.

The entries must be in glyphIndex order and textOffset order—except for the magic number entry.

NOTE: VTT expects that glyph indices are contiguous with no gaps. (Thus, the glyphIndex field is redundant for normal glyphs).

NOTE: VTT expects the "extra" records to be present, even if they are not used.

TSI1 (Glyph Program Text UTF-8 Text Dump)

This table contains straight text information: a series of glyph programs dumped end-to-end with no delimiters. Table TSI0 provides the index and length data indicating the text for each glyph. Text data should be UTF-8 encoded.

TSI2 (VTT Talk Text Indices)

This table contains the information needed to access the Text string data (stored in table TSI3) for the individual glyphs’ VTT Talk information. The TSI2 table is organized similar to the TSI0 table, and should have the same size as the TSI0 table.

Type	Name	Description
uint16	glyphIndex	Glyph Index associated with this block of text (search via this field)
uint16	textLength	Length of text (or 0x8000 to indicate any value larger than 32767)
uint32	textOffset	Offset from start of TSI3 table

For text with a length less than 32768, the actual length should be placed in the textLength field.

For text with a length greater than 32767, the value 0x8000 should be placed in the textLength field.

This record is repeated once for each valid glyph index, and is then followed by five extra entries at the end, as follows:

“Magic number” used to check for validity. For this entry, the glyphIndex field must be set to 0xFFFE and the textOffset field is set to the magic number (0xABFC1F34).
Reserved. Set the glyphIndex field to 0xFFFA.
Reserved. Set the glyphIndex field to 0xFFFB.
Reserved. Set the glyphIndex field to 0xFFFC.
Reserved. Set the glyphIndex field to 0xFFFD

The table will then have the following structure:

glyphIndex	textLength	textOffset	Comment*
0	length	actual offset	“normal” VTT Talk data
. . .	. . .	. . .	“normal” VTT Talk data
numGlyphs-1	length	actual offset	“normal” VTT Talk data
0xFFFE	0	0xABFC1F34	“extra” record (magic number)
0xFFFA	length	actual offset	“extra” record (reserved)
0xFFFB	length	actual offset	“extra” record (reserved)
0xFFFC	length	actual offset	“extra” record (reserved)
0xFFFD	length	actual offset	“extra” record (reserved)

Because the actual length of a record may or may not be stored in the textLength field, follow these rules to determine the actual length:

If the length stored in the record is less than 32768, then the actual length is the length noted in the record.
If the length stored in the record is 32768 (0x8000), then the actual length is computed as follows:
- For the last “extra” record (the very last record of the table), the length is the difference between the total length of the TSI3 table and the textOffset of the final record.
- For the last “normal” record (the last record just prior to the record containing the “magic number”), the length is the difference between the textOffset of the record following the “magic number” record and the textOffset of the last normal record.
- For all other records with a length of 0x8000, the length is the difference between the textOffset of the record in question and the textOffset of the next record.

TSI3 (VTT Talk UTF-8 Text Dump)

This table contains straight text information: a series of VTT Talk commands dumped end-to-end with no delimiters. Table TSI2 provides the index and length data indicating the text for each glyph. Text data should be UTF-8 encoded.

TSI4 Obsolete

TSI5 (VTT Character Group Flag)

This table contains character group information for each glyph. The table is a series of records in glyph index order.

Type	Name	Description
uint16	charGroup	Character group flag

The character group flags are defined as follows:

Value	Description
1	Other (undefined)
2	Uppercase
3	Lowercase
4	Figure
5	Non-Latin

TSIC (VTT Variation CVT window source)

The TSIC table contains the "source" data for the Variation CVT window and thus the cvar table that VTT generates. It includes a list of all the variation design space locations that appear in this window, as well as any CVT values that vary at those locations.

The Variation CVT view in Visual TrueType contains a populated combo-box of locations in variation space. Initially these locations are a union of locations found in named instances, locations found in existing cvar, and locations found across the gvar table. Users can also add locations to this list, either to add additional rows to the cvar table, or to provide a location for proofing, by clicking the + button. All of the locations in the list at save time appear as TSICRecords in the TSIC table. Each TSICRecord list the CVTs and CVT values that the user varied at that location. Locations that were added by the user merely for proofing will have no corresponding varied CVT values.

TSIC Header

Type	Name	Description
uint16	majorVersion	Major version – set to 1
uint16	minorVersion	Minor version – set to 1
uint16	flags	TSIC flags – set to 0
uint16	axisCount	Must equal the axisCount field in the fvar table
uint16	recordCount	TSIC record count
uint16	reserved	Set to 0
Tag	AxisArray[axisCount]	Array of axis tags (must match fvar order)
F2Dot14	RecordLocations[recordCount][axisCount]	Array of locations in variation space that correspond to each TSIC record; each location is an array of axis values in the order specified in AxisArray.
TSICRecord	TSICRecords[recordCount]	Array of TSIC records

AxisArray is an array of axis tags that specifies the order of axis values in the RecordLocations array, and must match the tags and order defined in the fvar table. Visual TrueType will invalidate data if axisCount and/or AxisArray do not agree with corresponding data in the fvar table.

RecordLocations and TSICRecords are parallel arrays: RecordLocations provides the coordinates in variation design space for each TSICRecord.

TSIC Record

Type	Name	Description
uint16	flags	Record flags - set to 0
uint16	numCVTEntries	Number of CVT number/value pairs (zero if location only)
uint16	nameLength	Length of optional user record name (zero if no name)
uint16	NameArray[nameLength]	Unicode 16 name
uint16	CVTArray[numCVTEntries]	CVT number array
FWORD	CVTValueArray[numCVTEntries]	CVT value

The TSICRecord lists the CVTs and CVT values that the user varied. CVTArray and CVTValueArray are parallel arrays that specify CVT numbers and their corresponding CVT values. The CVT number/value pairs will be the source data for the corresponding location represented by the record. Note that the CVT values is a value, not a delta. If a CVT does not have an entry it is assumed to be default.

Optionally, the TSICRecord can also supply a name for the location represented by the record to be used in the location dropdown list in the Variation CVT window. When pre-populating this list, VTT will use names defined in named instances in the fvar table whenever possible.