xgridfit
Author: Peter S. Baker

Home Page Project Page Download CVS repository

Reading and Writing Setting Defaults Engine and Glyph Info Graphics and Storage Area Other Defaults

# 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 &lt; 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

To reset any of these to the default value you have set (or to the TrueType default if you have not set one yourself), pass one of these types to <restore-default>, thus:

        <restore-default name="delta-shift"/>

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.

## Getting Information about the Engine and Glyph

You can get a limited amount of information about the TrueType engine. These read-only values are available for use in such contexts as <if> elements and expressions:

- `engine-version`: returns a number that corresponds to a specific version of the TrueType engine (or "scaler"). (This is different from a version number such as "Xgridfit version 1.6."). The result can be tested against any of these constants:
  - engine-mac-6-init (1)
  - engine-mac-7 (2)
  - engine-windows-3-1 (3)
  - engine-freetype-1 (3)
  - engine-kanjitalk-6-1 (4)
  - engine-ms-1-5 (33)
  - engine-ms-1-6 (34)
  - engine-ms-1-6-plus (36)
  - engine-ms-1-7 (35)
  - engine-freetype-2 (35)
  - engine-ms-1-8 (37)
  - engine-ms-1-9 (38)
  Here's a snippet of code to illustrate:

      	<if test="engine-version = engine-freetype-2">
      	  <!-- code here -->
      	</if>

- `is-cleartype-enabled`. This value will be true (non-zero) if Microsoft's ClearType system is enabled.
- `is-compatible-width-enabled`. This value will be true if "compatible-width" ClearType is enabled. In this system, the engine makes sure that use of ClearType does not change the text layout.
- `is-symmetrical-smoothing-enabled`. True if "symmetrical smoothing" ClearType is enabled. If you have a use for this, you presumably know what "symmetrical smoothing" is.
- `is-BGR-order`. According to the Microsoft specification, this is true if "ClearType is processing the LCD stripes in BGR (Blue, Green, Red) order."

You can also get information about the current glyph, which may influence whether or how to write instructions:

- `is-glyph-rotated`. True (non-zero) if the current glyph has been rotated.
- `is-glyph-stretched`. True if the current glyph has been stretched.
- `is-glyph-grayscale`. True if the current glyph has been rasterized for grayscale.
- `is-glyph-transformed`. True if one or more of the above three transformations has been performed.

## 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 utility `ttx2xgf` does this for you automatically. (N.B. Merge-mode manages the storage area 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).
- `init-graphics` tells Xgridfit whether or not to initialize variables that will help it to track the graphics state. Usually this is necessary, so the default is "yes"; but if this value is "no," it is not done. This setting may be overridden by including the `init-graphics` attribute on any <glyph> element.
- `color` is the "color" used for those elements that can perform rounding (chiefly <move>, but also <mirp>, <mdrp>, <round> and <no-round>; also the round() operator) when no other color is specified. Possible values are "black," "white" and "gray"; the default is "gray."
- `auto-instr` tells the compiler (running in merge-mode) to generate code that makes FontForge auto-instruct a font.
- `auto-hint` tells the compiler (running in merge-mode) to generate code that makes FontForge auto-hint a font before auto-instructing it. This has no effect except when `auto-instr` is "yes," and then its default value is "yes."
- `combine-prep` tells the compiler (running in merge-mode) to append the <pre-program> generated by Xgridfit to the one that is already in the font or that is generated by the FontForge auto-instructor. The default value is "yes."
- `delete-all` tells the compiler to delete all TrueType programming and data before installing Xgridfit code in a font. It is always "yes" if `auto-instr` is "yes."
- `cv-num-in-compile-if` tells the Xgridfit compiler (running in merge-mode) to resolve any control-value index as a number rather than as a symbol for use in the `test` attribute of the <compile-if> element and in the `compile-if` attribute on various elements. The default value is "no."