Xgridfit
Author: Peter S. Baker

Home Page Project Page Download CVS repository

Local Variables Global Variables Graphics Variables Reserving Variable Space

# Variables

In TrueType programming, most of the work you'd normally expect variables to do is handled by control values, which are great for storing and manipulating the fixed-point numbers that measure distance on the raster grid. If you need storage for some other kind of number, or temporary storage for a fixed-point number, you may wish to use an Xgridfit variable.

Variables are Xgridfit's way of providing access to the TrueType "Storage Area," which stores 32-bit numbers and no other data types (such as strings). Any of the number types known to TrueType can be stored there; but TrueType provides no way to store type information with these numbers, or to check types. Think of variables as handy places to store numbers temporarily, but don't expect the sorts of conveniences provided by the variables of general-purpose programming languages such as Java and Python.

All Xgridfit variables must be declared before they are used. You must assign a value to a variable before you can read it. In addition, you must initialize the storage area for your font by estimating the number of variables that are likely to be in use at any one time.

It is a simple matter to write to a variable. You can reference the variable by name in the `target` attribute of the <set-equal> element, or you can reference it in the `result-to` attribute of any of the elements that have it, including <round>, <measure-distance> and <get-coordinate>. When you call a function that returns a value, you may store the return value in a variable via the `result-to` attribute of the <call-function> element.

Once a variable has been written to, you can access the value by referencing the variable by name in almost any attribute that accepts a number value--for example, the `num` attribute of the <point> element. A variable can also be used anywhere in an expression.

## Local Variables

Local variables are those which are visible only within the <pre-program>, glyph program, or function where they are declared. Local variables are temporary: a variable declared within a glyph program exists only while the glyph program is running, and afterwards the storage location it occupied is freed for other uses. The same is true of variables declared within functions and the <pre-program>.

Local variables must be declared in <variable> elements at the top of the <pre-program>, after the <param> elements element in a function, or with the <constant>, <range>, <set> and <line> elements at the beginning of a glyph program. You cannot declare variables within smaller scopes (such as if-blocks and with-blocks). The variable declarations for the asterisk in Junicode-Bold look like this:

      <variable name="up-x"/>
      <variable name="up-y"/>
      <variable name="down-x"/>
      <variable name="down-y"/>
      <variable name="half-min"/>

The TrueType engine stores no type information at all: The declaration merely signals to the engine how many spaces will be required in the Storage Area and associates names with spaces. It is possible to initialize a variable by including a `value` attribute in the declaration:

      <variable name="v" value="50"/>

## Global Variables

A global variable is one that is visible anywhere that programming is allowed: in the <pre-program> and in any function or glyph program. It must be declared in top level of he program, as a child of <xgridfit>:

      <variable name="global-var"/>

A global variable should be initialized in the <pre-program>, and after that its value may be read by glyph programs and functions. It cannot be initialized with a `value` attribute. If a glyph program or function alters a global variable, or if you attempt to use a global variable to make one glyph program communicate with another, you are in terra incognita: the specifications are not informative about the way variables are handled in such situations. It seems a poor idea, in any case, to try to make glyph programs communicate with each other, since it is impossible to predict the order in which they will be run.

## Graphics Variables

Several pre-declared variables can be used to query the graphics state or (usually) to set a graphics variable. These are detailed in the section of this documentation on the Graphics State.

## Reserving Variable Space

Xgridfit reserves twenty-four spaces in the Storage Area for its own purposes. By default it reserves forty more spaces for variables. You may change this number with a <default> element:

      <default type="max-storage" value = "80"/>

In figuring the number of spaces you need to reserve, start with the 24 that Xgridfit requires, then add the number of global variables, the largest number of variables declared in any one glyph program, and the largest number of variables declared in any one function. If one function with variables calls another function with variables, you will have to increase the number accordingly.