The Graphics State and Xgridfit Defaults
The graphics state is a collection of variables that control the behavior of TrueType instructions. These include the round state, vectors, control-value cut-in, minimum distance, single width, auto flip, dropout control, delta shift, delta base, and enable/disable instructions. The graphics state also includes the reference pointers and zone pointers, but it is not recommended that you set these directly in Xgridfit. The uses of the graphics variables are described elsewhere in this documentation: this section describes how the graphics variables are controlled in Xgridfit.
Reading and Writing the Graphics State
The most important graphics variables can be accessed in any of three ways: they can be set via a "set" instruction or a "with" block, and they can be read or set via a special variable.
A "set" instruction simply sets the graphics variable, which remains as set until the end of the glyph program, or until set by another instruction. These are the "set" instructions in Xgridfit:
- <set-auto-flip>
- <set-control-value-cut-in>
- <set-delta-base>
- <set-delta-shift>
- <set-dropout-control>
- <set-dropout-type>
- <set-dual-projection-vector>
- <set-freedom-vector>
- <set-minimum-distance>
- <set-projection-vector>
- <set-round-state>
- <set-single-width>
- <set-single-width-cut-in>
- <set-vectors>
A "with" block is a block of code enclosed by an element whose name begins "with-": a graphics variable is set before the code in the "with" block is executed, and afterwards is restored to its former state. Example:
<with-minimum-distance value="0.55"> <diagonal-stem round="no"> <line ref="line1"/> <line ref="line2"/> </diagonal-stem> </with-minimum-distance>
These are the "with" elements in Xgridfit (note that a few "set" elements do not have corresponding "with" elements):
- <with-control-value-cut-in>
- <with-delta-base>
- <with-delta-shift>
- <with-freedom-vector>
- <with-minimum-distance>
- <with-param>
- <with-projection-vector>
- <with-round-state>
- <with-single-width>
- <with-single-width-cut-in>
- <with-vectors>
A graphics variable can be read by any instruction that can read variables, and most of them can be written by any instruction that can write to variables. Here is an example of how a graphics variable might be read:
<with-minimum-distance value="minimum-distance * 0.66"> <diagonal-stem round="no"> <line ref="line1"/> <line ref="line2"/> </diagonal-stem> </with-minimum-distance>
And here is an example of how a graphics variable might be written to:
<set-equal target="minimum-distance" source="minimum-distance * 0.66"/>
The code above has the same effect as this:
<set-minimum-distance value="minimum-distance * 0.66"/>
These graphics variables can be both read and written to:
- minimum-distance
- control-value-cut-in
- single-width
- single-width-cut-in
- delta-base
- delta-shift
Each of these variables has a "default" variant, e.g. minimum-distance-default, which records the default value, that is, the value the variable has at the beginning of each glyph program. These may be written to only in the <pre-program> (where writing to them sets the default value); but they may be used elsewhere to restore a default value:
<set-minimum-distance value="minimum-distance-default"/>
There are two graphics variables that relate to the round state: round-state and custom-round-state. These are both read-only: the round state can be set only via <set-round-state> and <with-round-state>. The value of round-state can be tested against these constants:
- to-grid
- to-half-grid
- to-double-grid
- down-to-grid
- up-to-grid
- no
- custom
When round-state = custom, the value of the period, phase and threshold is stored in custom-round-state. The three values are not separated here, as they are in the <round-state> element; rather, the three values are ANDed into a single number, which is more suitable for storage and retrieval than for analysis.
There are two other read-only values in the graphics state: pixels-per-em and point-size. Of these, pixels-per-em tends to be the more useful, and it is often used to decide when to alter the outline at low resolution:
<if test="pixels-per-em < 20"> . . . </if>
Setting Defaults
A default value for a graphics variable is the value it has at the beginning of each glyph program. There are two ways to set defaults in Xgridfit: one is simply to place a "set" element anywhere in the <pre-program>. The second, and recommended, method is to include a <default> element in the top level of your program file, thus:
<default type="minimum-distance" value="0.9">
That is, in the <default> element, the type attribute identifies the graphics default to set, and the value attribute is the value. These types are available for use in <default> elements:
- minimum-distance
- control-value-cut-in
- single-width
- single-width-cut-in
- delta-base
- delta-shift
- round-state
If you want the TrueType engine to reject all attempts to set defaults (that is, if you want to use only the defaults that are standard for TrueType), include this:
<default type="use-truetype-defaults" value="yes"/>
The result will be that "set" instructions encountered in the <pre-program> will not set defaults, and <default> elements that set the graphics state will be ignored.
The Graphics State and the Storage Area
Most TrueType graphics variables are write-only; that is, the TrueType engine provides no instructions for determining their current values. Xgridfit tracks the values of graphics variables by using several reserved locations in the TrueType storage area--the same area that is used to store variables. In order to make sure that this system functions correctly, you should take the following precautions:
- If your program file contains legacy code, set <default type="legacy-storage"/> so that Xgridfit and the legacy code will not be writing to the same storage locations. The easiest way to determine the correct value for legacy-storage is to copy the maxStorage value from the maxp table. Xgridfit's conversion script convert-ttx.xsl does this for you automatically.
- Avoid using low-level <command> elements to set graphics
variables, except in legacy code. This instruction:
<command name="SMD" value="54"/>
will set the minimum distance, but subsequent attempts to read the minimum-distance graphics variable will yield mistaken results, and the <with-minimum-distance> element will restore the wrong value at the end of the block.
Other Defaults
Several important defaults other than those relating to the graphics state are also controlled with <default> elements in the top level of your program file. These set values in the TrueType maxp table or control aspects of the Xgridfit compiler's behavior:
- max-twilight-points. Sets the number of points available in the twilight zone.
- max-storage. Sets the number of locations available in the TrueType storage area. The default value is 64, which allows for 24 reserved locations used by Xgridfit and 40 variables defined by your programming. Increase or decrease this value depending on the number of variables that are likely to be in use at one time in your programs.
- max-stack. Sets the size of the run-time stack. The default is 256, which is usually large enough for Xgridfit's purposes; but if your font includes legacy programming it may have to be bigger.
- legacy-storage. As explained above, the amount of storage to be reserved for the use of legacy programming. This is determined automatically when an older font is converted for use with Xgridfit.
- function-base tells Xgridfit where to start numbering functions. Use this if you have declared some functions with the num attribute (to support legacy code) and you are not satisfied with Xgridfit's standard way of handling that situation (starting the numbering after the highest numbered function).