Low-level elements

Though Xgridfit tries to provide as much functionality as possible in its high-level programming constructs, there may well be times when you feel you need to write low-level, "raw" instructions, either because Xgridfit does not meet some particular need or because a job can be done most efficiently with low-level instructions. Xgridfit provides three elements to help you write low-level code.

<command>

The <command> element will insert any TrueType instruction into your Xgridfit program. If the command reads values from the stack or writes to it, it is up to you to manage the stack yourself. Here is a simple example:

      <command name="ALIGNRP"/>

A number of instructions take one or more bits as modifiers. For example, the MIAP instruction, which positions a point at a grid coordinate read from the control-value table, takes a single modifier bit that indicates whether the control-value should be rounded before the point is positioned. The modifier can be noted in more than one way, even when entered in FontForge:

      MIAP[1]
      MIAP[rnd]

There are two ways to insert modifiers in Xgridfit: one is compact, easy and possibly non-portable, and the other is verbose but portable. The compact method is to include a modifier attribute containing a string which is to be copied verbatim into Xgridfit's output code:

      <command name="MIAP" modifier="1"/>
      <command name="MIRP" modifier="01100"/>

The verbose method is to include one or more <modifier> elements as children of <command>. Each element defines a bit:

      <command name="MIAP">
        <modifier type="round" value="yes"/>
      </command>

      <command name="MIRP">
        <modifier type="set-rp0" value="no"/>
        <modifier type="round" value="yes"/>
        <modifier type="minimum-distance" value="yes"/>
        <modifier type="color" value="gray"/>
      </command>

At present there is no advantage, aside from legibility (and who cares about that?), to using <modifier>. But if Xgridfit at some future time acquires the ability to produce input for some font production program other than FontForge, the verbose method is guaranteed to work while the compact method is not.

It is not necessary to provide a <modifier> for every bit that can accompany an instruction: all modifier types have defaults. Here are the modifier types, with all possible values, and with defaults in bold:

set-rp0: yes, no.
round: yes, no.
minimum-distance: yes, no.
color: gray, black, white.
grid-fitted: yes, no.
to-line: parallel, orthogonal.
axis: x, y.
ref-ptr: 1, 0.

If you are planning to write low-level code, you presumably know already which instructions have modifier bits and what those bits do. If you do not, consult the TrueType Reference Manual.

<push>

Many TrueType instructions operate upon values they pop from the stack; thus you must have have a way to move values onto the stack. TrueType provides a variety of PUSH instructions, depending on how the values are stored in the program code (as bytes or words) and how many values need to be pushed. Xgridfit reduces this variety to a single element: <push>, which takes a list of values. These are valid Xgridfit <push> instructions:

        <push>2 5 89 67</push>

        <push>
          left
          right
          lc-vertical-stem
          -1
        </push>

        <push> 0.58p 2.0 to-grid </push>

        <push>1 (top + 3) 512</push>

	<push>minimum-distance</push>

Notice that all expressions containing whitespace must be enclosed in parentheses.

The Xgridfit <push> element may invoke the TrueType PUSHB and PUSHW instructions, which push number literals onto the stack; but it can also handle variables and other values that can be resolved only at run-time. In other words, it is a general-purpose element for moving numbers of all kinds onto the stack. The list of values in a single <push> element can be heterogeneous: some bytes, some words, some variables.

Here is an example of the use of <push> in a fragment of code from a function, in which the point line-2-a and the control-value cvt have been passed in as parameters:

      <push>line-2-a cvt</push>
      <command name="MIRP">
        <modifier type="color" value="black"/>
      </command>

This code fragment also shows, incidentally, how a <command> element can be abbreviated by accepting defaults. It is functionally the same as this:

      <command name="MIRP">
        <modifier type="set-rp0" value="yes"/>
        <modifier type="minimum-distance" value="yes"/>
        <modifier type="round" value="yes"/>
        <modifier type="color" value="black"/>
      </command>

<to-stack>

<to-stack>, an element for moving a single value onto the stack, is deprecated as of Xgridfit version 1.11, as <push> can perform the same function.