MVAR — Metrics Variations Table (OpenType 1.9)
The metrics variations table is used in variable fonts to provide variations for font-wide metric values found in the OS/2 table and other font tables. For a general overview of OpenType Font Variation and terminology related to variations, see the chapter, OpenType Font Variations Overview.
The metrics variations table contains an item variation store structure to represent variation data. The item variation store and constituent formats are described in the chapter, OpenType Font Variations Common Table Formats. The item variation store is also used in the HVAR and GDEF tables, but is different from the formats for variation data used in the 'cvar' or 'gvar' tables.
The item variation store format uses delta-set indices to reference variation delta data for particular target font-data items to which they are applied. Data external to the item variation store identifies the delta-set index to be used for each given target item. Within the MVAR table, an array of value tag records identifies a set of target items, and provides the delta-set index used for each. The target items are identified by four-byte tags, with a given tag representing some font-wide value found in another table. For example, the tag 'hasc' represents the OS/2.sTypoAscender value. More details on tags are provided below.
The item variation store format uses a two-level organization for variation data: a store can have multiple item variation data subtables, and each subtable has multiple delta-set rows. A delta-set index is a two-part index: an outer index that selects a particular item variation data subtable, and an inner index that selects a particular delta-set row within that subtable. A value record specifies both the outer and inner portions of the delta-set index.
Note: Apple platforms allow for use of a font metrics ('fmtx') table to specify various font-wide metric values by reference to the X or Y coordinates of contour points for a specified “magic” glyph. OpenType Font Variations does not use the font metrics table.
The metrics variations table must be used in combination with a font variations ('fvar') table and other required or optional tables used in variable fonts. See Variation Data Tables and Miscellaneous Requirements in the OpenType Font Variations Overview chapter for additional details.
Table Formats
The metrics variations table has the following format.
Metrics variations table:
| Type | Name | Description |
|---|---|---|
| uint16 | majorVersion | Major version number of the metrics variations table — set to 1. |
| uint16 | minorVersion | Minor version number of the metrics variations table — set to 0. |
| uint16 | (reserved) | Not used; set to 0. |
| uint16 | valueRecordSize | The size in bytes of each value record — must be greater than zero. |
| uint16 | valueRecordCount | The number of value records — may be zero. |
| Offset16 | itemVariationStoreOffset | Offset in bytes from the start of this table to the item variation store table. If valueRecordCount is zero, set to zero; if valueRecordCount is greater than zero, must be greater than zero. |
| ValueRecord | valueRecords[valueRecordCount] | Array of value records that identify target items and the associated delta-set index for each. The valueTag records must be in binary order of their valueTag field. |
The valueRecordSize field indicates the size of each value record. Future, minor version updates of the MVAR table may define compatible extensions to the value record format with additional fields. Implementations must use the valueRecordSize field to determine the start of each record.
The valueRecords array is an array of value records that identify the target, font-wide measures for which variation adjustment data is provided (target items), and outer and inner delta-set indices for each item into the item variation store data.
ValueRecord:
| Type | Name | Description |
|---|---|---|
| Tag | valueTag | Four-byte tag identifying a font-wide measure. |
| uint16 | deltaSetOuterIndex | A delta-set outer index — used to select an item variation data subtable within the item variation store. |
| uint16 | deltaSetInnerIndex | A delta-set inner index — used to select a delta-set row within an item variation data subtable. |
The value records must be given in binary order of the valueTag values. Each tag identifies a font-wide measure found in some other font table. For example, if a value record has a value tag of 'hasc', this corresponds to the OS/2.sTypoAscender field. Details on the tags used within the MVAR table are provided below.
Processing
When reading a value within a variable font, such as the OS/2.sCapHeight value (the target item), the value tags array in the metrics variations table is scanned to find the tag that corresponds to that target item. Records in the array are stored in binary order of values in the valueTag fields. If the tag does not occur in the tag array, then the item is constant across the font’s variation space. If the tag does occur, however, then the delta-set index is used to reference a set of deltas within the item variation store. The two-level organization of data within the item variation store is described in the chapter OpenType Font Variations Common Table Formats. Each delta set includes different deltas that apply to variation instances falling within different regions of the variation space. The process by which the deltas are processed to derive an interpolated value for a given target item is described in the chapter, OpenType Font Variations Overview.
Value Tags
Four-byte tags are used to represent particular metric or other values. For example, the tag 'hasc' (horizontal ascent) is used to represent the OS/2.sTypoAscender value. Tags are defined for various values found in the OS/2 and Windows metrics (OS/2) table, the horizontal header ('hhea') table, the grid-fitting and scan-conversion ('gasp') table, the PostScript ('post') table, and the vertical metrics header ('vhea') table.
Note: The OS/2.usWeightClass, OS/2.usWidthClass and post.italicAngle values are not supported by variation data in the MVAR table. This is because values for these three fields correspond directly to input axis values for the 'wght', 'wdth' and 'slnt' variation axes. See the discussion of these axes in the OpenType Design-Variation Axis Tag Registry for details on the relationship between these fields and the corresponding design axes.
Tags in the metrics variations table are case sensitive. Tags defined in this table use only lowercase letters or digits.
Tags that are used in a font’s metrics variations table should be those that are documented in this table specification. A font may also use privately-defined tags, which have semantics known only by private agreement. Private-use tags must use begin with an uppercase letter and use only uppercase letters or digits. If a private-use tag is used in a given font, any application that does not recognize that tag should ignore it.
The following tags are defined:
Value tags, ordered by logical grouping:
| Tag | Mnemonic | Value represented |
|---|---|---|
| 'hasc' | horizontal ascender | OS/2.sTypoAscender |
| 'hdsc' | horizontal descender | OS/2.sTypoDescender |
| 'hlgp' | horizontal line gap | OS/2.sTypoLineGap |
| 'hcla' | horizontal clipping ascent | OS/2.usWinAscent |
| 'hcld' | horizontal clipping descent | OS/2.usWinDescent |
| 'vasc' | vertical ascender | vhea.ascent |
| 'vdsc' | vertical descender | vhea.descent |
| 'vlgp' | vertical line gap | vhea.lineGap |
| 'hcrs' | horizontal caret rise | hhea.caretSlopeRise |
| 'hcrn' | horizontal caret run | hhea.caretSlopeRun |
| 'hcof' | horizontal caret offset | hhea.caretOffset |
| 'vcrs' | vertical caret rise | vhea.caretSlopeRise |
| 'vcrn' | vertical caret run | vhea.caretSlopeRun |
| 'vcof' | vertical caret offset | vhea.caretOffset |
| 'xhgt' | x height | OS/2.sxHeight |
| 'cpht' | cap height | OS/2.sCapHeight |
| 'sbxs' | subscript em x size | OS/2.ySubscriptXSize |
| 'sbys' | subscript em y size | OS/2.ySubscriptYSize |
| 'sbxo' | subscript em x offset | OS/2.ySubscriptXOffset |
| 'sbyo' | subscript em y offset | OS/2.ySubscriptYOffset |
| 'spxs' | superscript em x size | OS/2.ySuperscriptXSize |
| 'spys' | superscript em y size | OS/2.ySuperscriptYSize |
| 'spxo' | superscript em x offset | OS/2.ySuperscriptXOffset |
| 'spyo' | superscript em y offset | OS/2.ySuperscriptYOffset |
| 'strs' | strikeout size | OS/2.yStrikeoutSize |
| 'stro' | strikeout offset | OS/2.yStrikeoutPosition |
| 'unds' | underline size | post.underlineThickness |
| 'undo' | underline offset | post.underlinePosition |
| 'gsp0' | gaspRange[0] | gasp.gaspRange[0].rangeMaxPPEM |
| 'gsp1' | gaspRange[1] | gasp.gaspRange[1].rangeMaxPPEM |
| 'gsp2' | gaspRange[2] | gasp.gaspRange[2].rangeMaxPPEM |
| 'gsp3' | gaspRange[3] | gasp.gaspRange[3].rangeMaxPPEM |
| 'gsp4' | gaspRange[4] | gasp.gaspRange[4].rangeMaxPPEM |
| 'gsp5' | gaspRange[5] | gasp.gaspRange[5].rangeMaxPPEM |
| 'gsp6' | gaspRange[6] | gasp.gaspRange[6].rangeMaxPPEM |
| 'gsp7' | gaspRange[7] | gasp.gaspRange[7].rangeMaxPPEM |
| 'gsp8' | gaspRange[8] | gasp.gaspRange[8].rangeMaxPPEM |
| 'gsp9' | gaspRange[9] | gasp.gaspRange[9].rangeMaxPPEM |
Value tags, in alphabetical order of tags:
| Tag | Mnemonic | Value represented |
|---|---|---|
| 'cpht' | cap height | OS/2.sCapHeight |
| 'gsp0' | gaspRange[0] | gasp.gaspRange[0].rangeMaxPPEM |
| 'gsp1' | gaspRange[1] | gasp.gaspRange[1].rangeMaxPPEM |
| 'gsp2' | gaspRange[2] | gasp.gaspRange[2].rangeMaxPPEM |
| 'gsp3' | gaspRange[3] | gasp.gaspRange[3].rangeMaxPPEM |
| 'gsp4' | gaspRange[4] | gasp.gaspRange[4].rangeMaxPPEM |
| 'gsp5' | gaspRange[5] | gasp.gaspRange[5].rangeMaxPPEM |
| 'gsp6' | gaspRange[6] | gasp.gaspRange[6].rangeMaxPPEM |
| 'gsp7' | gaspRange[7] | gasp.gaspRange[7].rangeMaxPPEM |
| 'gsp8' | gaspRange[8] | gasp.gaspRange[8].rangeMaxPPEM |
| 'gsp9' | gaspRange[9] | gasp.gaspRange[9].rangeMaxPPEM |
| 'hasc' | horizontal ascender | OS/2.sTypoAscender |
| 'hcla' | horizontal clipping ascent | OS/2.usWinAscent |
| 'hcld' | horizontal clipping descent | OS/2.usWinDescent |
| 'hcof' | horizontal caret offset | hhea.caretOffset |
| 'hcrn' | horizontal caret run | hhea.caretSlopeRun |
| 'hcrs' | horizontal caret rise | hhea.caretSlopeRise |
| 'hdsc' | horizontal descender | OS/2.sTypoDescender |
| 'hlgp' | horizontal line gap | OS/2.sTypoLineGap |
| 'sbxo' | subscript em x offset | OS/2.ySubscriptXOffset |
| 'sbxs' | subscript em x size | OS/2.ySubscriptXSize |
| 'sbyo' | subscript em y offset | OS/2.ySubscriptYOffset |
| 'sbys' | subscript em y size | OS/2.ySubscriptYSize |
| 'spxo' | superscript em x offset | OS/2.ySuperscriptXOffset |
| 'spxs' | superscript em x size | OS/2.ySuperscriptXSize |
| 'spyo' | superscript em y offset | OS/2.ySuperscriptYOffset |
| 'spys' | superscript em y size | OS/2.ySuperscriptYSize |
| 'stro' | strikeout offset | OS/2.yStrikeoutPosition |
| 'strs' | strikeout size | OS/2.yStrikeoutSize |
| 'undo' | underline offset | post.underlinePosition |
| 'unds' | underline size | post.underlineThickness |
| 'vasc' | vertical ascender | vhea.ascent |
| 'vcof' | vertical caret offset | vhea.caretOffset |
| 'vcrn' | vertical caret run | vhea.caretSlopeRun |
| 'vcrs' | vertical caret rise | vhea.caretSlopeRise |
| 'vdsc' | vertical descender | vhea.descent |
| 'vlgp' | vertical line gap | vhea.lineGap |
| 'xhgt' | x height | OS/2.sxHeight |
Note that the tags 'gsp0' to 'gsp9' are used to provide variation data for the rangeMaxPPEM member of records in a grid-fitting and scan-conversion procedure ('gasp') table. The last 'gasp' table entry always uses a rangeMaxPPEM value of 0xFFFF. The maximum number of value records for 'gasp' entries must never be more than one less the number of entries in the 'gasp' table.