Xgridfit
Author: Peter S. Baker

Home Page Project Page Download CVS repository

Integers Grid Distance Vector Setting Control Values Expressions

# Number Types

The TrueType engine provides no facilities for conversion between number types and no type-checking. If you pass a negative integer to an instruction that accepts only unsigned integers, you will receive no notice of your error before your glyph program crashes. You can catch many run-time errors relating to invalid numbers by testing your font in Rogier van Dalen's TrueTypeViewer.

Xgridfit does distinguish several different types of number literal, and it does prevent your doing truly outrageous things--for example, using a fixed-point number (which normally expresses distance on the raster grid) to index a control value. But as TrueType does no internal type-checking, a program compiled by Xgridfit does not do so either. Xgridfit will not catch an error that cannot be caught at compile time. So while you can't do this:

    <point num="2.5"/>

You can do this (and you will get no error-message, though it makes no sense):

    <variable name="p"/>
    <set-equal target="p" source="2.5"/>
    <move-point>
      <point num="p"/>
    </move-point>

It is largely up to you to make sure the numbers you are using are appropriate.

## Integers

Integers present little difficulty, since it is generally obvious whether a number may be signed and if there are limits on its size. At present Xgridfit does not distinguish between signed and unsigned integers or between integers of various sizes. This may change in a future release.

To represent an integer value, simply type the number with no decimal point, e.g. "-64," "23."

## Grid distance ("F26Dot6")

There are three ways to write these numbers. One is as an integer, in 64ths of a pixel (the smallest unit this kind of number can express): thus "32" is half a pixel, "64" is one pixel, and so on. A second way is to type a decimal point anywhere in the number: "0.5" for half a pixel, "1.0" for one pixel, and so on. A third way is as a number with the suffix "p": thus "1p" is one pixel, "1.5p" is one and a half pixels, and so on. These numbers may be signed: "-64," "-0.25," "-1p" and so on.

Note that, if you write F26dot6 numbers as decimals, the number you write may be rounded to the nearest 64th of a pixel: for example, 1.1p comes to 70.4 64ths; Xgridfit rounds it to 70/64 (= 1.09375). This is due to the limitations of the TrueType engine; it is not a problem with Xgridfit.

All arithmetic operations return F26dot6 numbers. You should keep in mind that the limited precision of these numbers constrains the kind of math you can do in Xgridfit and the TrueType engine.

## Vector-setting numbers ("EF2Dot14")

These numbers may be written either as integers between 16384 and -16384 or as decimal values with suffix "v" (e.g. "1.0v," "0.785v"--the zero is needed for validation). For further constraints on these numbers, see Vectors.

## Control Values

To work with control values you must understand three distinct numerical types. When you set up the Control Value Table, you must supply numbers (signed integers) corresponding to the units of the grid on which you designed the glyphs in your font:

    <control-values>
      <control-value name="baseline" value="0"/>
      <control-value name="lc-round-bottom" value="-23"/>
      <control-value name="cap-round-bottom" value="-27"/>
      <control-value name="lc-x-height" value="850"/>
    </control-values>

But before any of your programming ever runs, the TrueType engine converts these values to grid-units ("F26Dot6" numbers), whose exact values depend on the resolution at which the font is now being rasterized (measured in pixels-per-em). Finally, all control values are stored in an array indexed with unsigned integers.

Xgridfit encourages you to access control values by id; indeed, the `distance` attributes of <move> and other instructions will accept only these symbolic identifiers, not numbers or variables (this is so, at least, if you validate with the schema). But the index of a control-value may be retrieved, if wanted, with the <control-value-index> element:

    <control-value-index value="lc-vert-stem" result-to="v"/>

where `value` is the `name` of an entry in the Control Value Table and `result-to` is a variable in which to store the index.

Xgridfit converts the `name` of a control value to an index whenever appropriate: especially in the `distance` attributes of the point-moving instructions <move>, <diagonal-stem>, <mirp> and <miap>. When passing a control value to a function it is the index that gets passed, and in any expression involving operators, the name of a control-value resolves to the index. (Thus a shorthand way to get the index of a control value is to put it in an expression, e.g. "lc-vert-stem + 0".)

When the `name` of a control value is used in an arithmetic instruction (including <set-equal>), it is the value that gets used, not the index. The `name` of a control value can also be passed to the <set-minimum-distance> instruction, and in that case the value is used, not the index. The same is true of <shift-absolute> <set-coordinate>, <move> with `pixel-distance` attribute, <set-control-value-cut-in>, <set-single-width-cut-in>, and <set-single-width>. If you need the value rather than the index in an expression, use the `control-value` operator with any expression that resolves to an index into the Control Value Table:

    control-value(lc-vert-stem)      <!-- The name of a control value -->
    control-value(0)                 <!-- An unsigned integer -->
    control-value(baseline + 3)      <!-- An expression -->

## Expressions

Expressions have no type, and, except where the schema forbids it, can be used to express any sort of value at all. The schema insists that only the `name` of a <control-value> can be used in the `distance` attribute of an instruction that moves a point; but even here you can use an expression if you don't validate: the attribute `distance="2.5 * foo"` will be acceptable to the Xgridfit compiler, if you can justify it to yourself.