Element Reference
<absolute>
Converts negative to positive numbers; positive numbers stay positive. Use the result-to attribute to assign the result to a variable or control value. If there is no result-to attribute and value is a variable or control value, the result is written to value.
<absolute value="line-width" result-to="lw"/>
Schema
absolute = element absolute { attlist.absolute, empty }
attlist.absolute &=
attribute value { text }?,
attribute result-to { text }?
<add>
Adds value1 to value2. If there is no result-to attribute, Xgridfit attempts to write the result to value1.
<add value1="line-width" value2="1p"/>
Schema
add = element add { attlist.add, empty }
attlist.add &=
attribute value1 { text }?,
attribute value2 { text }?,
attribute result-to { text }?
<align>
Moves one or more points along the freedom vector until aligned with a reference point. Points are "aligned" when their distance from each other, measured along the projection vector, is zero. When the projection vector is "x," aligned points end up stacked vertically; when it is "y" they end up in a horizontal line. When the projection vector is set to a line, the aligned points end up arrayed along an imaginary line orthogonal to the projection vector.
The <align> element must contain at least one point to align. It may contain any number of <point>s, <range>s and <set>s. An optional <reference> element contains the point to align with. If the reference point is omitted, the current setting of RP0 is used.
<align> can and frequently should be nested inside a <move> element, in which case points are aligned relative to the point that is the target of the <move>. In both of the following cases point "m" is aligned with point "r":
<align>
<reference>
<point num="r"/>
</reference>
<point num="m"/>
</align>
<move>
<point num="r"/>
<align>
<point num="m"/>
</align>
</move>
Schema
align = element align { attlist.align, reference?, (point | range | set)* }
attlist.align &= attribute compile-if { text } ?
<align-midway>
Must contain two <point> elements. Moves these along the freedom vector until they are aligned midway between their original positions. Measurement is along the projection vector.
<align-midway>
<point num="a"/>
<point num="b"/>
</align-midway>
Schema
align-midway =
element align-midway { attlist.align-midway, point, point }
attlist.align-midway &= empty
<asm>
Xgridfit copies the contents of the <asm> element literally into the output file on the assumption that it is valid code that will be recognized as such by FontForge. This is not in fact a valid assumption; however, the <asm> element is retained in Xgridfit as a rough-and-ready way to import legacy code into Xgridfit. Use the <command> element to embed TrueType instructions in Xgridfit code.
Schema
asm = element asm { attlist.asm, text }
attlist.asm &= empty
<call-function>
Calls a function (defined via the <function> element) by name. Parameters may be passed to the function by including several <with-param> elements; or, if the function is to be called repeatedly, several <param-set> elements, each containing the <with-param> elements for one call to the function.
If the function returns a value, it can be assigned to a variable via the result-to attribute. Note, however, that if a <call-function> element contains more than one <param-set>, only the value returned by the last iteration of the function is returned.
<call-function name="cap-serif-width">
<param-set>
<with-param name="ref-pt" value="left-left"/>
<with-param name="move-pt" value="top-serif-end"/>
</param-set>
<param-set>
<with-param name="ref-pt" value="left-left"/>
<with-param name="move-pt" value="bottom-serif-end"/>
</param-set>
</call-function>
Schema
Note: the function-id attribute is deprecated.
call-function =
element call-function { attlist.call-function, (param-set* | with-param*) }
attlist.call-function &=
attribute name { xsd:IDREF }?,
attribute function-id { xsd:IDREF }?,
attribute result-to { text }?
<call-macro>
Causes a macro to be compiled and its code inserted at the present location. If parameters have been defined for the macro, the <call-macro> element must contain either one or more <with-param> elements, one for each parameter defined in the <macro> element, or several <param-set> elements if the macro is to be compiled and inserted at this place more than once. Parameters may be omitted for each <param> element with a value attribute.
<call-macro name="lc-vert-stem-with-serif">
<with-param name="anchor" value="left-left"/>
<with-param name="distance-from-anchor" value="hn-width"/>
<with-param name="stem-a" value="right-right"/>
<with-param name="serif-a" value="right-serif-right"/>
<with-param name="stem-b" value="right-left"/>
<with-param name="serif-b" value="right-serif-left"/>
</call-macro>
Schema
Note: The macro-id attribute is deprecated.
call-macro =
element call-macro { attlist.call-macro, (param-set* | with-param*) }
attlist.call-macro &=
attribute name { xsd:IDREF }?,
attribute macro-id { xsd:IDREF }?
<ceiling>
Yields the smallest integer greater than or equal to value.
Schema
ceiling = element ceiling { attlist.ceiling, empty }
attlist.ceiling &=
attribute value { text }?,
attribute result-to { text }?
<command>
This element can express any command except for PUSHB or PUSHW. name is the name of the command; modifier, is simply copied into brackets after the instruction that is generated. This element
<command name="MIRP" modifier="10110"/>
is compiled to "MIRP[10110]". The modifier attribute lacks portability, since it is copied in literally. A better solution is to use <modifier> elements within the <command> element, thus:
<command name="MIRP">
<modifier type="rp0" value="yes"/>
<modifier type="minimum-distance" value="no"/>
<modifier type="round" value="no"/>
<modifier type="color" value="black"/>
</command>
Though verbose, this style allows Xgridfit to check the input code and has the potential to allow Xgridfit to vary the syntax of its output. (Since FontForge now produces only FontForge scripts, the latter capability is not exploited.)
Schema
command = element command { attlist.command, modifier* }
attlist.command &=
attribute name { text },
attribute modifier { text }?
<compile-if>
Code within <compile-if> is compiled only if the test attribute evaluates to true (non-zero). The compiler must be able to evaluate test at compile time: thus it may contain only constants, number literals, control value indexes and a few operators (+ - = != > < >= <= or and not).
Here is a simple example of <compile-if>:
<compile-if test="bold-italic">
<delta>
<delta-set size="3" distance="-2">
<point num="pt"/>
</delta-set>
</delta>
</compile-if>
The delta is compiled and inserted in the output code only if bold-italic (a global constant is non-zero.
The <compile-if> element may also contain an <else> element, which must come last, as with <if>. If test evaluates to false (zero), the code contained in the <else> is compiled.
Schema
compile-if = element compile-if { attlist.compile-if, programming*, else? }
attlist.compile-if &=
attribute test { text }
<constant>
A constant is a named number. The name of the constant goes in the "name" attribute, and the value goes in "num." The "num" can be an integer, either of the two kinds of fixed-point number (e.g. "2.3" for a distance on the grid or "1.0v" for a component of a vector). It can also be the name of another constant, in which case it creates an alias for that constant, or relative to another constant:
<constant name="bottom-left" num="3"/>
<constant name="bottom" num="bottom-left"/>
<constant name="bottom-right" num="bottom + 4"/>
Constants can be referenced just about anywhere that numbers are called for. To refer to a constant belonging to another glyph program, use the glyph's ps-name followed by a slash and the name of the constant, e.g.
<point specifier="macron/bottom"/>
This is useful when instructing composite glyphs.
Constants can be declared at the beginning of a <glyph> program, or as a child of the <xgridfit> element.
Schema
constant = element constant { attlist.constant, empty }
attlist.constant &=
attribute name { text },
attribute value { text }
<contour>
Specifies a contour to be shifted by a <shift> instruction.
Schema
contour = element contour { attlist.contour, empty }
attlist.contour &=
attribute num { text },
attribute zone { "twilight" | "glyph" }?
Attributes
- num
- The number of this contour or a name associated with it via a constant.
- zone
- The zone that contains this contour. As a rule, you do not need this attribute when the contour is in the glyph zone. In fact, it must be very rare indeed that a whole contour is in the twilight zone.
<control-value>
The font's Control Value Table is built from the <control-value> elements. Each <control-value> has an name (which must be unique) and a numerical value. The index of the <control-value> is generated by Xgridfit, and no attempt should be made to predict it: Xgridfit instructions should use only the names of <control-value>s, though the index may be derived and used at run time.
<control-value name="curved-char-bottom" value="-25"/>
<control-value name="lc-x-height" value="850"/>
<control-value name="lc-descender-depth" value="-555"/>
<control-value name="lc-ascender-height" value="1485"/>
Schema
Note that the <control-values> element is deprecated: it is no longer necessary to enclose <control-value> elements in this container.
control-values =
element control-values { attlist.control-values, control-value+ }
attlist.control-values &= attribute xml:id { xsd:ID }?
control-value = element control-value { attlist.control-value, empty }
attlist.control-value &=
attribute name { xsd:ID },
attribute value { text }
<control-value-delta>
The <control-value-delta> element works like the <delta> element, but operates on the Control Value Table rather than on a point. It should normally be invoked in the <pre-program>. Each <delta-set> inside a control-value-delta element must have cv, size and distance attributes, but it may not contain a point.
The setting of the vectors has no effect on the <control-value-delta>. Rather, the <delta-set> specifies an amount to add to or subtract from the value stored there.
<control-value-delta>
<delta-set cv="pq-char-width" size="6" distance="-8"/>
<delta-set cv="pq-char-width" size="9" distance="-8"/>
</control-value-delta>
Schema
control-value-delta =
element control-value-delta {
attlist.control-value-delta, delta-set+
}
attlist.control-value-delta &= empty
<control-value-index>
Assigns the index of a control value to a variable. Use this if you need to get such an index for any reason, since the <set-equal> instruction yields the value, not the index, of a control value.
Schema
control-value-index =
element control-value-index { attlist.control-value-index, empty }
attlist.control-value-index &=
attribute value { text },
attribute result-to { text }
Attributes
- value
- Name of the <control-value> element for which we want the index. No other kind of value is recognized here.
- result-to
- Name of a variable in which to store the control value index. Only a variable is permitted here--not, for example, the name of another control value.
<declarations>
The <declarations> element is deprecated. It is no longer to enclose <constant>, <range>, <set> and <line> declarations in this element.
Schema
declarations =
element declarations {
attlist.declarations, (constant | range | set | line)*
}
attlist.declarations &= empty
<default>
This element, which may appear as a child of <xgridfit>, declares a default value. If the type is "minimum-distance," "control-value-cut-in," "single-width," "single-width-cut-in," "delta-base," "delta-shift" or "round-state," Xgridfit also inserts code in the prep program to set a font-wide default in the TrueType engine. Another way of setting these defaults is simply to include elements that set these values in the <pre-program>, and the effect is the same. 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"/>
In addition to TrueType defaults, stored in the font file, this element controls several defaults that govern how Xgridfit operates.
Schema
\default = element default { attlist.default, empty }
attlist.default &=
attribute type {
"minimum-distance"
| "control-value-cut-in"
| "single-width"
| "single-width-cut-in"
| "delta-base"
| "delta-shift"
| "delta-break"
| "max-twilight-points"
| "max-instructions"
| "max-storage"
| "legacy-storage"
| "max-stack"
| "use-truetype-defaults"
| "round-state"
| "function-base"
},
attribute value { text }
<delta>
A delta instruction moves points at particular sizes. The <delta> element may contain any number of <delta-set> elements, each one specifying a point to move, a size at which to move it, and a distance to move it.
The direction of the move is determined by the current setting of the freedom vector. The available specifications are fuzzy as to the details. You will experience no surprises when the vectors are set to x or y; you may experiment with the vectors set at other angles.
<delta>
<delta-set size="3" distance="8">
<point num="p1"/>
</delta-set>
<delta-set size="4" distance="8">
<point num="p1"/>
</delta-set>
</delta>
Schema
delta = element delta { attlist.delta, delta-set* }
attlist.delta &= attribute compile-if { text } ?
<delta-set>
The <delta-set> element encapsulates the essential information about a single delta move or adjustment: the resolution at which to apply the delta, the magnitude of the adjustment, and the point or control value that will be affected.
The resolution is determined by the size attribute, which can be a number from 0 to 47. It is added to the value set by the <set-delta-base> or <with-delta-base> instruction to obtain the resolution (in pixels per em) at which the move should take place. The default delta base is 9; if you don't change it, a size of "0" means 9 ppem, "9" means 18 ppem, and so forth up to "47," which means 56 ppem.
The distance attribute is the distance to shift the point along the freedom vector, or the amount to add to or subtract from the control value. Legal values are from -8 to 8 (excluding 0). When moving points, negative numbers shift against the direction of the freedom vector (generally down or left) and positive numbers shift in the direction of the freedom vector.
The default unit by which pixels are moved and control values adjusted is 1/8 pixel. The unit is controlled by means of the <set-delta-shift> or the <with-delta-shift> instruction.
Each <delta-set> that is the child of a <delta> element must contain precisely one <point>, except that when the <delta> is a child of a <move> the point can implicitly be the <point> moved by the <move>. A <delta-set> that is the child of a <control-value-delta> element may not contain a <point>, but it must have a cv attribute.
All attribute values in a <delta-set> and a child <point> must be capable of being resolved to numerical values at compile time. Variables and function parameters are not permitted.
Schema
delta-set = element delta-set { attlist.delta-set, point? }
attlist.delta-set &=
attribute cv { text }?,
attribute size { text },
attribute distance { text }
<diagonal-stem>
Given two lines (making up a diagonal stem), makes the second line parallel to the first, subject to the operation of the Control Value cut-in. If one <align> element is present, the points it contains are aligned with the second line; if there are two, the first set of points is aligned with the first line and the second set with the second line. You may, and often should, set a new minimum distance value with the min-amount attribute. At the end of this instruction the minimum distance will be reset to its former value.
Usually it doesn't make a lot of sense to round the distance when calling this instruction; and yet the default value of round is yes for compatibility with other, similar instructions. You'll probably want to set the round attribute to no; but if you have several <diagonal-stem> instructions together, enclose them in a <with-round-state round="no"> element to turn off rounding beforehand and on again afterwards. In this case, do not include the round attribute with the <diagonal-stem> elements.
By default this instruction does not set the Freedom Vector, since the best setting of that vector varies with circumstances. If you want the Freedom Vector to be the same as the Projection Vector, set freedom-vector="yes".
This instruction is not suitable for use inside a function (though you may do so if the <line> elements contain points rather than ref attributes). Also, I'm not sure whether it will work if the various points are in different zones. It may, but I don't guarantee it.
<with-minimum-distance value="diag-min-dist">
<with-round-state round="no">
<diagonal-stem distance="cap-thick-diag" save-vectors="yes">
<line ref="left-diag-left-line"/>
<line ref="left-diag-right-line"/>
</diagonal-stem>
<diagonal-stem distance="cap-thin-diag" save-vectors="yes">
<line ref="right-diag-right-line"/>
<line ref="right-diag-left-line"/>
</diagonal-stem>
</with-round-state>
</with-minimum-distance>
Schema
diagonal-stem =
element diagonal-stem { attlist.diagonal-stem, line, line, align* }
attlist.diagonal-stem &=
attribute distance { xsd:IDREF },
[ a:defaultValue = "yes" ] attribute round { text }?,
[ a:defaultValue = "yes" ] attribute cut-in { YESNO }?,
[ a:defaultValue = "yes" ] attribute min-distance { YESNO }?,
attribute min-amount { text }?,
[ a:defaultValue = "no" ] attribute freedom-vector { YESNO }?,
[ a:defaultValue = "no" ] attribute save-vectors { YESNO }?
Attributes
- distance
- A value from a <control-value> element: this controls the width of the diagonal stem.
- round
- Whether and how to round the distance the point is to be moved. The default value is yes, which means to round it according to the current setting (to the grid, if you haven't changed it). If you specify no, no rounding will be done. The other values specify one of the standard kinds of rounding or a custom round-state defined as a globally visible element (a child of <xgridfit>). Setting the round state with this attribute has no effect except in this instruction: the round state returns to its former value after the instruction is executed. If several <diagonal-stem> instructions use the same round state, it is more efficient to call <set-round-state> before and after that group than to include a round attribute with each one. That is also true if the round value is to be no: in that case call <set-round-state round-state="no"/> before and omit the round attribute for the <diagonal-stem> instructions.
- cut-in
- Whether to use the Control Value cut-in. Legal values are yes and no; the default is yes. If the value of this attribute is no, the value of the round attribute must also be no. (This is a peculiarity of the TrueType instruction set and has nothing to do with Xgridfit.) This attribute has an effect only when a distance is specified.
- min-distance
- Whether to maintain a minimum distance between the points in the first line and the points in the second: legal values are yes (the default) and no.
- min-amount
- The value of the minimum-distance setting in pixels. The default value of this setting (1p) is more often than not appropriate for vertical and horizontal stems, but usually needs to be changed for diagonal stems to look their best. This attribute applies only to the present instruction. The minimum-distance setting resumes its former value after this instruction.
- color
- Distance type: black, white or gray (the default).
- freedom-vector
- Set this to yes if you want the Freedom Vector to be the same as the Projection Vector. The default is no.
- save-vectors
- If yes, both the Projection Vector and the Freedom Vector are guaranteed to be the same after this intruction as they were before. The default is no.
<disable-instructions>
Disables the instructions associated with glyphs. The TrueType specification does not say that instructions in the <pre-program> are disabled: presumably they are not. This instruction is available only in the <pre-program>.
Schema
disable-instructions =
element disable-instructions { attlist.disable-instructions, empty }
attlist.disable-instructions &= empty
<divide>
Divides dividend by divisor. If result-to is not specified, Xgridfit attempts to write the result to dividend.
Schema
divide = element divide { attlist.divide, empty }
attlist.divide &=
attribute dividend { text }?,
attribute divisor { text }?,
attribute result-to { text }?
<else>
Provides the "else" clause for an <if> or <compile-if> element. The <else> must be the last child of the parent element.
Schema
else = element else { attlist.else, programming* }
attlist.else &= empty
<enable-instructions>
Enables the instructions associated with glyphs. This instruction is available only in the <pre-program>.
Schema
enable-instructions =
element enable-instructions { attlist.enable-instructions, empty }
attlist.enable-instructions &= empty
<flip-off>
<flip-on>
"Flips" a range of points so that they all become either on-line points or off-line points. The <flip-off> and <flip-on> elements must contain a single <range> element. The range operated upon always runs from the lowest point to the highest. The <range> element may contain a zone attribute, in which case the operation takes place in the specified zone.
Schema
flip-on =
element flip-on { attlist.flip-on, range }
attlist.flip-on &= empty
flip-off =
element flip-off { attlist.flip-off, range }
attlist.flip-off &= empty
<floor>
Yields the greatest integer less than or equal to value, which is either an integer representing 64ths of a pixel or a fixed-point number. The returned value, if looked at as an integer, is either zero or a multiple of 64.
Schema
floor = element floor { attlist.floor, empty }
attlist.floor &=
attribute value { text }?,
attribute result-to { text }?
<font-file>
The <font-file> element is deprecated. Use <infile> and <outfile> instead. This element names the FontForge .sfd file to which this Xgridfit program file will add instructions.
Schema
font-file = element font-file { attlist.font-file, text }
attlist.font-file &= empty
<formula>
A formula is a block containing arithmetical instruction elements. Within the <formula> the behavior of these elements is modified slightly: when a result-to attribute is missing, they do not attempt to write their result back to one of the values passed to them, but rather leave it on the stack, thus making it available to the following instruction element. Further, while Xgridfit normally issues a warning when an arithmetic element takes a value from the stack or leaves a result on the stack, within a formula this is the expected behavior and so the warning is suppressed. The instructions within the formula should be chained, the result of one operation being used as an argument for the following one; this results in tight code being generated. Example:
<formula result-to="minimum-distance">
<round value="lc-vert-stem"/>
<multiply value2="0.8p"/>
</formula>
This rounds the control-value "lc-vert-stem," multiplies it by 0.8, and sets the minimum distance in the graphics state to the result. The original entry in the control-value table is unchanged. By contrast, if this <round> element were not the child of a <formula>, the result would be written back to the control-value table.
Schema
formula = element formula { attlist.formula, vars }
attlist.formula &= attribute result-to { text }?
<function>
The font's fpgm table is built from the <function> elements in the Xgridfit program. Each function gets a name and, optionally, parameters. Functions are called by name using the <call-function> element. Normally Xgridfit takes care of indexing functions and making sure the right number is used to call them.
A function may also have a num attribute: this is used to define the function in the fpgm table and ensures that any legacy programming can continue to call older functions by number. Xgridfit assigns a number automatically to any function that lacks a num attribute.
A function that returns a value must have the attribute return="yes"; within such a function an instruction may assign a value to the special variable "return". The return value must be a single number; lines, vectors, and other structures consisting of two or more numbers cannot be returned.
A <function> may contain any number of <param> elements and any number of <variable> elements, followed by programming.
<function name="lc-standard-serif">
<!-- Regulates vertical distances within a serif -->
<param name="base"/>
<param name="bottom-left"/>
<param name="bottom-right"/>
<param name="top-left"/>
<param name="top-right"/>
<with-vectors axis="y">
<mdap>
<point num="base"/>
</mdap>
<mirp distance="lc-serif-height" set-rp0="yes">
<point num="top-left"/>
</mirp>
<align>
<point num="top-right"/>
</align>
<mirp distance="lc-serif-height" set-rp0="yes">
<point num="bottom-left"/>
</mirp>
<align>
<point num="bottom-right"/>
</align>
</with-vectors>
</function>
Schema
Note: The <functions> element is deprecated.
functions =
element functions {
attlist.functions, legacy-functions?, (xg.xi.include | function)+
}
attlist.functions &= attribute xml:id { xsd:ID }?
function =
element function {
attlist.function, (params?|param*), (variables?|variable*), programming*
}
attlist.function &=
attribute xml:id { xsd:ID },
attribute num { text }?,
[ a:defaultValue = "no" ] attribute return { YESNO }?
<get-coordinate>
Gets the coordinate of a point, measured along the current projection vector. If the projection vector is set to x, for example, the result will be the horizontal distance of the point from the grid origin (0,0). The result-to attribute may be the name of a variable, a control value, or a graphics state variable.
<get-coordinate result-to="v">
<point num="p"/>
</get-coordinate>
Schema
get-coordinate =
element get-coordinate { attlist.get-coordinate, point }
attlist.get-coordinate &=
[ a:defaultValue = "yes" ] attribute grid-fitted { YESNO }?,
attribute result-to { text }?
Attributes
- grid-fitted
- If "yes," coordinate is from the grid-fitted outline; if "no," it is from the original outline. The default is "yes."
- result-to
- Where to put the result. If this attribute is omitted, a warning is displayed and the vaue is left on the stack.
<glyph>
The <glyph> element contains instructions relating to an individual glyph. It typically begins with declarations of <constant>s, <range>s, <set>s, <line>s; and <variable>s. Finally, of course, the instructions for the glyph, which more often than not are organized into two blocks, one for the y axis and one for the x axis. A glyph program normally ends with <interpolate-untouched-points/>.
<glyph ps-name="sample-glyph">
<constant name="last" num="50"/>
. . .
<variable id="v"/>
<with-vectors axis="y">
<!-- programming here -->
</with-vectors>
<with-vectors axis="x">
<!-- more programming here -->
</with-vectors>
<interpolate-untouched-points/>
</glyph>
Schema
glyph =
element glyph {
attlist.glyph,
((declarations?, variables?) |
(constant|variable|range|line|set)*),
programming*
}
attlist.glyph &= attribute ps-name { text }
Attribute
- ps-name
- The PostScript name of the glyph. It must match the PostScript name of the glyph in the font.
<if>
Contains instructions that are executed only if the expression in the test attribute is true. If the test is false, and an <else> element is the last child of this <if>, the instructions in the <else> element are executed. From the behavior of FreeType it appears that ifs may be nested; but I can only assume that they can be nested in Windows and OS X.
The test attribute contains an expression, e.g.
<if test="minimum-distance = 1p">
For more on expressions, see the Expressions section of this documentation. In the TrueType language, where all data is numeric, a non-zero value is considered true and zero false. So the test attribute can be used to tell whether a value is zero. This
test="round(lc-vert-stem) != 0"
is equivalent to this:
test="round(lc-vert-stem)"
The <if> element may contain an <else> clause, which must come last.
<if test="boolean-expression">
<!-- programming -->
<else>
<!-- alternative programming -->
</else>
</if>
Schema
if = element if { attlist.if, programming*, else? }
attlist.if &=
attribute test { text },
[ a:defaultValue = "or" ] attribute priority { "and" | "or" }?
Attributes
- test
- The condition to test for.
- priority
- Whether to process "and" or "or" operators first. This attribute is deprecated: you should use parentheses to modify the priorities of operators in an expression.
<infile>
Contains the name of a file to which TrueType instructions are to be added. This may be either a FontForge source file (.sfd) or a TrueType font (.ttf). If an <outfile> element is not present this is also the name of the file to be output.
<infile>MyFont.sfd</infile>
<outfile>MyFont.ttf</outfile>
Schema
infile = element infile { attlist.infile, text }
attlist.infile &= empty
<interpolate>
To "interpolate" a point is to move it so that its position relative to two reference points is what it was in the original outline. If the distance between the two reference points is not what it was in the original outline, the point is positioned so that its relationship to the reference points is proportionally correct.
The <interpolate> element must contain at least one point to interpolate. It may contain any number of <point>s, <range>s and <set>s. Like most other elements that move points, it may contain a <reference> element; but this element must contain two <point>s, not just one.
This instruction may be nested inside a <move> element containing a reference point, in which case no reference points are needed in the <interpolate> element: the points it contains are automatically interpolated between the <move> element's reference point and its moved point. These two <interpolate> elements do the same thing:
<interpolate>
<reference>
<point num="top"/>
<point num="bottom"/>
</reference>
<point num="bar-top-left"/>
</interpolate>
<move>
<reference>
<point num="bottom"/>
</reference>
<point num="top"/>
<interpolate>
<point num="bar-top-left"/>
</interpolate>
</move>
Schema
interpolate =
element interpolate {
attlist.interpolate, reference?, (point | range | set)*
}
attlist.interpolate &= attribute compile-if { text } ?
<interpolate-untouched-points>
Interpolates all points that have not been moved or "touched" by instructions so that they are positioned correctly relative to points that have been moved. Most of the time you will want to place this instruction at the end of the program for each glyph.
Schema
interpolate-untouched-points =
element interpolate-untouched-points {
attlist.interpolate-untouched-points, empty
}
attlist.interpolate-untouched-points &= attribute axis { "x" | "y" }?
Attribute
- axis
- Interpolation always takes place along the x or the y axis. If you omit this attribute, interpolation takes place along both axes.
<legacy-functions>
Stores functions from a font that has been converted for use with Xgridfit. Normally this should not be created or edited by hand: see Conversion for further details.
Schema
legacy-functions =
element legacy-functions {
attlist.legacy-functions, programming*
}
attlist.legacy-functions &=
attribute highest { text },
attribute count { text }
<line>
A <line> is defined by its two end-points. These points need not be adjacent.
When a <line> has a name attribute, another <line> may refer to it by name. You may name the <line> the first time you use it or declare it in a <line> element among the declarations at the beginning of a <glyph>. For example, if you declare the line thus:
<line name="line-2b">
<point num="b"/>
<point num="a"/>
</line>
then you can use an abbreviated form whenever you need it:
<set-freedom-vector>
<line ref="line-2b"/>
</set-freedom-vector>
If both points that define a <line> are in the same zone, you may use the optional zone attribute on the <line> to indicate this. Most instructions that take a <line> as an argument allow one point to be in one zone and the other point in the other: in such cases place the zone attributes on the <point>s. The exception is the <move-point-to-intersection> instruction, which requires that each of the two lines it takes as arguments be entirely in a zone. For this instruction, place the zone attributes on the <line>s, never on the <point>s.
Schema
line = element line { attlist.line, point* }
attlist.line &=
attribute zone { "twilight" | "glyph" }?,
attribute name { text }?,
attribute ref { text }?
<macro>
A macro is a stretch of code that is compiled and inserted into the program stream wherever a <call-macro> element is encountered. Macros resemble functions in syntax: they begin with <param> definitions followed by program code, which can access all global variables and values (e.g. control values, graphics variables, constants and variables declared as children of <xgridfit>). Macros can be called from a <function>, <pre-program> or <glyph>, and variables and values local to these structures can be accessed by passing them as parameters.
A function cannot be called from a macro, nor one macro from another.
Macro parameters are fundamentally different from function parameters. A function parameter is passed to the function on the stack at run time; the macro parameter, on the other hand, is swapped at compile time for the value parameter, which is then evaluated as any value is evaluated at run time. When passing variables or control values, there is no rule governing whether they are passed to the macro by value or by reference; rather, they are evaluated according to the rule that governs evaluation of variables for the particular instruction where they occur.
Schema
Note: The <macros> element is deprecated.
macros =
element macros {
attlist.macros, (xg.xi.include | macro)+
}
attlist.macros &= attribute xml:id { xsd:ID }?
macro =
element macro {
attlist.macro, (params?|param*), programming*
}
attlist.macro &=
attribute name { xsd:ID },
attribute xml:id { xsd:ID }?
<maximum>
Yields the greater of the two values value1 and value2.
<maximum value1="lc-vert-stem" value2="1p" result-to="lc-vert-stem"/>
Schema
maximum = element maximum { attlist.maximum, empty }
attlist.maximum &=
attribute value1 { text }?,
attribute value2 { text }?,
attribute result-to { text }?
<mdap>
Corresponds to the MDAP instruction
Will round a point to the grid if the round attribute is not no; otherwise will just touch the point (i.e. mark it as moved).
<mdap>
<point num="p"/>
</mdap>
Schema
mdap = element mdap { attlist.mdap, reference?, point }
attlist.mdap &= [ a:defaultValue = "yes" ] attribute round { text }?
Attributes
- round
- Whether and how to round. This is the same as the round attribute in the <move> element.
<mdrp>
Corresponds to the MDRP instruction.
This will also take care of setting RP0 beforehand if a reference point is supplied. If no reference point is supplied, the current value of RP0 is used.
<mdrp>
<reference>
<point num="r"/>
</reference>
<point num="p"/>
</mdrp>
Schema
mdrp = element mdrp { attlist.mdrp, reference?, point }
attlist.mdrp &=
[ a:defaultValue = "yes" ] attribute round { text }?,
[ a:defaultValue = "yes" ] attribute min-distance { YESNO }?,
[ a:defaultValue = "no" ] attribute set-rp0 { YESNO }?,
[ a:defaultValue = "gray" ]
attribute color { "gray" | "black" | "white" }?
Attributes
- round
- Whether/how to round the distance from the reference point.
- min-distance
- Whether to maintain a minimum distance from the reference point.
- set-rp0
- Whether to set RP0 to the moved point after the move.
- color
- Or distance-type, or compensation for engine characteristics. Whatever. It's got to be gray, black or white, and here gray is the default.
<measure-distance>
Measures the distance between two points and returns an F26dot6 number. The measurement is performed along the projection vector, and the result may be positive or negative depending on the relationship of the distance to the direction of the vector. Another way of putting it is that the order of the two points in this instruction is significant; reverse them and you reverse the sign of the result.
<measure-distance result-to="v">
<point num="p1"/>
<point num="p2"/>
</measure-distance>
Schema
measure-distance =
element measure-distance { attlist.measure-distance, point, point }
attlist.measure-distance &=
[ a:defaultValue = "yes" ] attribute grid-fitted { YESNO }?,
attribute result-to { text }?
Attributes
- grid-fitted
- If yes, measurement is taken in the grid-fitted outline; if no, in the original outline. The default is "yes."
- result-to
- Where to put the result, e.g. a variable or a control value. If no result-to attribute is provided, a warning message is printed and the value is left on the stack.
<message>
The <message> element produces no TrueType code, but rather causes a message to be output at compile-time via the <xsl:message> element. This may help with debugging.
Schema
message = element message { attlist.message, text }
attlist.message &= empty
<miap>
Corresponds to the MIAP instruction.
As with mirp, it will try to separate rounding and the cvt cut-in.
Must contain one point element.
Schema
miap = element miap { attlist.miap, reference?, point }
attlist.miap &=
attribute distance { text },
[ a:defaultValue = "yes" ] attribute round { text }?,
[ a:defaultValue = "yes" ] attribute cut-in { YESNO }?
Attributes
- distance
- Distance relative to grid origin
- round
- Whether/how to round the distance
- cut-in
- Whether to use the cvt cut-in
<minimum>
Yields the lesser of the two values value1 and value2.
<minimum value1="lc-vert-stem" value2="1p" result-to="lc-vert-stem"/>
Schema
minimum = element minimum { attlist.minimum, empty }
attlist.minimum &=
attribute value1 { text }?,
attribute value2 { text }?,
attribute result-to { text }?
<mirp>
Corresponds to the MIRP instruction, but attempts, insofar as it is practical, to separate rounding and the cvt cut-in. You can specify round="no" and cut-in="yes" or both no or both yes, but not round="yes" and cut-in="no". That produces an error-message.
This will take care of setting RP0 beforehand if a reference point is included.
<mirp distance="lc-x-height">
<reference>
<point num="p1"/>
</reference>
<point num="p2"/>
</mirp>
Schema
mirp = element mirp { attlist.mirp, reference?, point }
attlist.mirp &=
attribute distance { xsd:IDREF },
[ a:defaultValue = "yes" ] attribute round { text }?,
[ a:defaultValue = "yes" ] attribute cut-in { YESNO }?,
[ a:defaultValue = "yes" ] attribute min-distance { YESNO }?,
[ a:defaultValue = "no" ] attribute set-rp0 { YESNO }?,
[ a:defaultValue = "gray" ]
attribute color { "gray" | "black" | "white" }?
Attributes
- distance
- distance (from a <control-value> element) relative to the reference point (or to RP0 if that was set by a previous instruction).
- round
- whether/how to round the distance. If yes is specified, the round bit is set and nothing more is done: so the current round state is used. If to-grid, to-half-grid or to to-double-grid, the round state is set as specified, the instruction is executed, and then the earlier round state is restored. The default is yes.
- cut-in
- whether to use the cvt cut-in. If rounding is used, this will always be yes, even if you set it to no.
- min-distance
- whether to observe the current minimum distance (1p unless you set it differently using set-minimum-distance). The default is yes.
- set-rp0
- whether to set reference point 0 to point at the moved point after the instruction is executed. The default value is no.
- color
- Or distance-type, or compensation for engine characteristics. Whatever. It's got to be gray, black or white, and here gray is the default.
<move>
Moves a point and, optionally, aligns other points with it or moves other points in relation to it. For details, see the section on moving points.
Schema
move =
element move {
attlist.move, reference?, point, delta*, align*, interpolate*, shift*, move*, delta*
}
attlist.move &=
attribute distance { xsd:IDREF }?,
attribute pixel-distance { text }?,
[ a:defaultValue = "yes" ] attribute round { text }?,
[ a:defaultValue = "yes" ] attribute cut-in { text }?,
[ a:defaultValue = "yes" ] attribute min-distance { text }?,
[ a:defaultValue = "gray" ]
attribute color { "gray" | "black" | "white" }?,
attribute compile-if { text }?
Attributes
- distance
- A value from a <control-value> element. If a distance is specified, the target point is positioned that distance either from the reference point or from the grid origin. If a distance is not specified, the distance from the original outline is used. In either case, the distance is measured along the projection vector.
- pixel-distance
- A distance in pixels. If a pixel-distance is specified, the target point is positioned that distance either from the reference point or from the grid origin. The distance and pixel-distance attributes are not compatible. If a distance attribute is present, the pixel-distance attribute is not consulted.
- round
- Whether and how to round the distance or pixel-distance. The default value is yes, which means to round it according to the current setting (to the grid, if you haven't changed it). If you specify no, no rounding will be done. To use one of the standard round states, use to-grid, to-half-grid, to-double-grid, down-to-grid or up-to-grid. To use a custom round state defined in the top level of the program (as a child of <xgridfit>), use its name. Finally, any number (constant, variable) is passed to SROUND for the TrueType engine to interpret. Setting the round state with this attribute has no effect except in this instruction: the round state returns to its former value after the instruction is executed. If several <move> instructions use the same round state, it is more efficient to enclose them in a <with-round-state> element than to include a round attribute with each one. That is also true if the round value is to be no: in that case use <with-round-state round="no"> and omit the round attribute for the <move> instructions.
- cut-in
- Whether to use the Control Value cut-in; or a cut-in value to use. Legal values are yes, no or any number; the default value is yes. If the value of this attribute is no, the value of the round attribute must also be no. (This is a peculiarity of the TrueType instruction set and has nothing to do with Xgridfit.) This attribute has an effect only when the distance attribute is present.
- min-distance
- Whether to maintain a minimum distance between the reference point and the target point; or the minimum distance to use: legal values are yes (the default), no, or any number. This attribute has an effect only when there is a reference point.
- color
- Distance type: black, white or gray (the default). This applies only when there is a reference point.
<move-point-to-intersection>
Moves a point to the intersection of two lines. Each of the lines must be wholly in a single zone, so if specifying the zone use the zone attribute of the <line> elements rather than the zone attributes of the <point> elements that make up the lines.
<move-point-to-intersection>
<point num="p"/>
<line>
<point num="l1p1"/>
<point num="l1p2"/>
</line>
<line>
<point num="l2p1"/>
<point num="l2p2"/>
</line>
</move-point-to-intersection>
Schema
move-point-to-intersection =
element move-point-to-intersection {
attlist.move-point-to-intersection, point, line, line
}
attlist.move-point-to-intersection &= empty
<multiply>
Multiplies value1 by value2. If there is no result-to attribute, Xgridfit attempts to write the result to value1.
<multiply value1="lc-vert-stem" value2="3.3" result-to="v"/>
Schema
multiply = element multiply { attlist.multiply, empty }
attlist.multiply &=
attribute value1 { text }?,
attribute value2 { text }?,
attribute result-to { text }?
<negate>
Converts positive to negative numbers; negative numbers stay negative. If the result-to attribute is not present, Xgridfit attempts to write the result back to value. Failing that, it issues a warning and leaves the result on the stack.
<negate value="v"/>
Schema
negate = element negate { attlist.negate, empty }
attlist.negate &=
attribute value { text }?,
attribute result-to { text }?
<no-round>
Like round, but without the rounding. That is, it may apply a correction for the "color" of the distance, but it will not round the distance. If the result-to attribute is not present, Xgridfit attempts to write the result back to value. Failing that, it issues a warning and leaves the result on the stack.
<round value="v1" color="black" result-to="v2"/>
Schema
no-round = element no-round { attlist.no-round, empty }
attlist.no-round &=
attribute value { text }?,
[ a:defaultValue = "gray" ]
attribute color { "gray" | "black" | "white" }?,
attribute result-to { text }?
<outfile>
Contains the name of a file to write. If the filename ends .sfd it is assumed that a FontForge source file is desired, and the generated FontForge script ends with a "Save" command. If the filename ends .ttf it is assumed that a TrueType font is desired, and the generated FontForge script ends with a "Generate" command. It is an error if the filename has any other suffix.
If the <outfile> element is omitted, <infile> is used instead.
The fmflags attribute indicates flags to pass to FontForge when generating a TrueType font. It has no effect when the <outfile> is a FontForge source file. For a list of these flags, see the documentation for the Generate command. Probably the most likely to be used is "2048" (generate old-style kern table).
<infile>MyFont.sfd</infile>
<outfile fmflags="2048">MyFont.ttf</outfile>
Schema
outfile = element outfile { attlist.outfile, text }
attlist.outfile &=
attribute fmflags { xsd:int }?
<params>
<param>
This element is deprecated. <param> elements should be the first children of the <function> and <macro> elements that contain them.
Schema
params = element params { attlist.params, param+ }
attlist.params &= empty
param = element param { attlist.param, empty }
attlist.param &=
attribute name { text },
attribute value { text }?
<param-set>
Contains a set of parameters (each encoded as a <with-param> element) to be passed to a function or macro. There may be more than one of these in a <call-function> or <call-macro> element; and in that case the function is called repeatedly (via LOOPCALL) until the list of <param-set> elements is exhausted; or the macro code is compiled and inserted repeatedly.
Schema
param-set = element param-set { attlist.param-set, with-param+ }
attlist.param-set &= attribute opt { YESNO }?
Attribute
- opt
- If set to "yes," forces optimization in pushing function parameters onto the stack. That is, instructs Xgridfit to push all parameters with a single PUSHB command. Use this if you are sure that all parameters can be determined by the compiler (i.e. they are not determined at run-time) and that they are all between 0 and 255, but Xgridfit is not optimizing. If you get this wrong, that is, if you force optimization when it really ought not to be used, incorrect code will be generated and your glyph program will fail. Still, it may be worth a try since the failure will probably be obvious. Conversely, set this to "no" if Xgridfit is incorrectly optimizing the parameters in a function call. This probably won't happen, since Xgridfit optimizes rather conservatively, but it's here just in case.
<point>
The <point> element defines a point. It is used in all instructions that manipulate or refer to points.
Schema
point = element point { attlist.point, empty }
attlist.point &=
attribute num { text },
attribute offset { text }?,
attribute zone { "twilight" | "glyph" }?
Attributes
- num
- The number of a point. This may be a number literal, the name of a <constant>, a variable, or a function parameter. To refer to a point in a glyph other than the one whose glyph program is currently running (as you may have occasion to do when instructing composite glyphs), use the syntax "g/p", where g is the ps-name of the glyph, and p is the point being referred to (it must be the name of a <constant> declared in the other glyph).
- offset
- Number (can be positive or negative) to add to the point identified in num. If num is a variable or function parameter, Xgridfit will generate code to add it at run time. Otherwise Xgridfit will add it at compile time. Offset must be a number literal or a <constant>. It may, like num, refer to a <constant> declared in another glyph via "g/p" syntax. This element is deprecated. You should ins tead use an addition or subtraction expression in the num attribute.
- zone
- The zone that contains this point. Instructions will take note of this attribute, when present, and adjust the zone pointers appropriately. The glyph zone is always the default zone. When a point is in the glyph zone it is generally redundant to include an attribute zone="glyph," and doing so may also cause unnecessary (though harmless) code to be generated. N.B. For instructions that deal with lists of points, include the zone attribute only in the first.
<pre-program>
The prep table (or CVT program) is made from the <pre-program> element. It contains instructions that are executed before a font is rasterized, or whenever it is about to be rasterized in a new size. A typical thing to do in the <pre-program> is to adjust control values, e.g. rounding or applying deltas to them. Another is to set defaults: an instruction that assigns a value to a graphic variable sets a default when it is executed in the <pre-program>. For example, if executed in the <pre-program> this instruction:
<set-minimum-distance value="0.9">
ensures that the minimum-distance graphics variable is always 0.9 pixels at the beginning of any glyph program.
The <pre-program> element must be present, even if it is empty.
Schema
pre-program =
element pre-program { attlist.pre-program, (variables?|variable*), programming* }
attlist.pre-program &= attribute xml:id { xsd:ID }?
<profile>
The <profile> element is deprecated. There is no reason at all to use it.
Schema
profile =
element profile {
attlist.profile, (infile | outfile | font-file | round-state
| \default | constant | variable)*
}
attlist.profile &= attribute xml:id { xsd:ID }?
<push>
The <push> element does the work of the various PUSHB and PUSHW instructions: it may be used in combination with <command> to insert low-level TrueType commands into your Xgridfit programming in a portable way. Its content is a whitespace-delmited list of numbers, identifiers and expressions that can be resolved to numbers at compile time. 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>
Xgridfit always pushes all the numbers contained in the <push> element with one instruction. It uses a PUSHB instruction where possible; otherwise a PUSHW instruction.
Including an identifier or expression that cannot be resolved to a single number at compile time generates an error message. So does an empty <push></push> element.
See also the similar <to-stack> element.
Schema
push = element push { attlist.push, text }
attlist.push &= empty
<range>
A <range> is a collection of contiguous points defined by its end-points. It can be used in any instruction that operates on more than one point: <shift>, <align>, <interpolate>, <shift-absolute>, <toggle-points>. The order of points in the <range> is not significant. Example:
<align>
<reference>
<point num="bottom"/>
</reference>
<range>
<point num="bottom - 2"/>
<point num="bottom + 2"/>
</range>
</align>
If "bottom" is point 17, the <range> begins with 15 and ends with 19. But any reference point in the parent element of the <range> is excluded from the <range>, so this <range> actually represents points 15, 16, 18 and 19. The same is true of implicit reference points supplied by a <move> element that is the parent of the parent of the <range>:
<move>
<point num="bottom"/>
<align>
<range>
<point num="bottom - 2"/>
<point num="bottom + 2"/>
</range>
</align>
</move>
Here the points in the <range> are aligned with "bottom" after it has been moved by the <move> instruction; but "bottom" itself is not part of the <range>. The code above is functionally identical to this:
<move>
<point num="bottom"/>
<align>
<point num="bottom - 2"/>
<point num="bottom - 1"/>
<point num="bottom + 1"/>
<point num="bottom + 2"/>
</align>
</move>
The latter generates more efficient code than the example with the <range>, but the <range> is more flexible, since its endpoints, its size, and the points to be excluded need not be known until run-time. This makes the <range> ideal for use in functions.
All the points in a <range> must be in the same zone, determined by the optional zone attribute on the <range> element. Any zone attributes on the <point>s within the <range> are ignored.
Schema
range = element range { attlist.range, point* }
attlist.range &=
attribute name { text }?,
attribute ref { text }?,
attribute zone { "twilight" | "glyph" }?
<reference>
In any instruction that can position a point or other structure with reference to one or more points, the <reference> element holds the reference point(s). This element generally contains precisely one point, but when it is the child of an <interpolate> element it must contain two points. In the following example, point p2 is moved relative to point p1:
<move>
<reference>
<point num="p1"/>
</reference>
<point num="p2"/>
</move>
Schema
reference = element reference { attlist.reference, point+ }
attlist.reference &= empty
<round>
Rounds a number representing a distance according to the current round state, applies whatever correction is appropriate for the "color" of the distance, and returns the result.
<round value="lc-vert-stem" color="black" result-to="new-cvt"/>
Schema
round = element round { attlist.round, empty }
attlist.round &=
attribute value { text }?,
[ a:defaultValue = "gray" ]
attribute color { "gray" | "black" | "white" }?,
attribute result-to { text }?
<!ATTLIST round
value CDATA #IMPLIED
color (gray | black | white)
"gray"
result-to CDATA #IMPLIED>
<round-state>
Declares a custom round state whose name can be passed to <set-round-state>, <with-round-state>, or any element that takes a round attribute. For an explanation of the period, phase and threshold attribute, see above. Note that only a limited number of values is permitted for each of these attributes. This element is permitted only at the top level of a program, as a child of <xgridfit>.
<round-state name="my-round" period="two-pixel"
phase="three-quarters"
threshold="three-quarters"/>
Schema
round-state = element round-state { attlist.round-state, empty }
attlist.round-state &=
attribute name { text },
attribute period { "half-pixel" | "one-pixel" | "two-pixel" },
attribute phase {
"zero" | "one-quarter" | "one-half" | "three-quarters"
},
attribute threshold {
"period-minus-one"
| "minus-three-eighths"
| "minus-one-quarter"
| "minus-one-eighth"
| "zero"
| "one-eighth"
| "one-quarter"
| "three-eighths"
| "one-half"
| "five-eighths"
| "three-quarters"
| "seven-eighths"
| "one"
| "nine-eighths"
| "five-quarters"
| "eleven-eighths"
}
<set>
A <set> is an arbitrary collection of points, defined by the <point> elements contained in the <set> element. The <set> can be used by any element that accepts a collection of points: <align>, <interpolate>, <shift>, <shift-absolute>, <toggle-points>.
A <set> can be used only in a <glyph> program, or it can be referenced in a <macro> called by a <glyph> program. The name of a <set> can be passed to a macro as a parameter.
Xgridfit must be able to resolve the num attributes of all <point>s in a <set> at compile time. It is an error to attempt to reference a variable in a <set>.
When a <set> is used in an element that has reference points, either explicitly via the <reference> element or implicitly via an enclosing <move> element, any reference points repeated in the set are excluded. This works only when the <reference> points can be resolved at compile time.
A <set> may be preferable to a <range> when all point numbers are known at compile time and the range is short, including perhaps three or four points. The code generated by Xgridfit on encountering a <set> is less flexible, but vastly more efficient than that generated on encountering a <range>.
A <set> may be defined thus among the declarations at the beginning of a <glyph>:
<set name="bar-bottom-left-corner">
<point num="bar-bottom-left"/>
<point num="bar-bottom-left + 1"/>
<point num="bar-bottom-left + 2"/>
</set>
<set name="bar-bottom-right-corner">
<point num="bar-bottom-right"/>
<point num="bar-bottom-right - 1"/>
<point num="bar-bottom-right - 2"/>
</set>
It can then be referenced whenever needed:
<move distance="cap-horz-stem">
<reference>
<point num="bar-top-left"/>
</reference>
<point num="bar-bottom-left"/>
<shift>
<set ref="bar-bottom-left-corner"/>
<set ref="bar-bottom-right-corner"/>
</shift>
</move>
Schema
set = element set { attlist.set, point* }
attlist.set &=
attribute name { text }?,
attribute ref { text }?,
attribute zone { "twilight" | "glyph" }?
<set-auto-flip>
When "on" (the default setting), the TrueType engine automatically adjusts the signs of control values when executing MIRP and MIAP instructions. This works very well, so there is rarely a reason to set this to "off."
Schema
set-auto-flip = element set-auto-flip { attlist.set-auto-flip, empty }
attlist.set-auto-flip &= attribute value { "on" | "off" }
<set-control-value-cut-in>
<with-control-value-cut-in>
The value is a distance on the grid. If the difference between a distance from a <control-value> element and the original distance is greater than this, the original distance is used. The effect is generally to use the <control-value> distance at low resolutions and the original distance at high resolutions. This can be used to promote evenness at small sizes, where a 1-pixel difference between the width of (say) p and b can look bad. The default value is 17/16: that is, 1.0625p or 68.
<set-control-value-cut-in value="1.1"/>
Schema
set-control-value-cut-in =
element set-control-value-cut-in {
attlist.set-control-value-cut-in, empty
}
attlist.set-control-value-cut-in &= attribute value { text }
with-control-value-cut-in =
element with-control-value-cut-in {
attlist.with-control-value-cut-in, programming*
}
attlist.with-control-value-cut-in &= attribute value { text }
<set-coordinate>
Moves a point to a coordinate determined by the freedom and projection vectors. On the rare occasions when you need a command like this one, it is probably better to use <move> with the pixel-distance attribute.
Schema
set-coordinate =
element set-coordinate { attlist.set-coordinate, point }
attlist.set-coordinate &= attribute coordinate { text }
Attribute
- coordinate
- The new coordinate in pixels.
<set-delta-base>
<with-delta-base>
Sets the number that is added to the "size" attribute of a <delta-set> element to get the resolutioni at which an adjustment should take place. The default value is 9, and that rarely needs to be changed.
<with-delta-base value="56">
<delta>
<delta-set size="12" distance="-8">
<point num="p"/>
</delta-set>
</delta>
</with-delta-base>
Schema
set-delta-base =
element set-delta-base { attlist.set-delta-base, empty }
attlist.set-delta-base &= attribute value { text }
with-delta-base =
element with-delta-base { attlist.with-delta-base, programming* }
attlist.with-delta-base &= attribute value { text }
<set-delta-shift>
<with-delta-shift>
The unit by which a delta instruction shifts a point. If the unit is "2," the smallest shift is half a pixel; if "4," it is a quarter of a pixel; if "8" (the default) it is one eighth, and so on.
<set-delta-shift value="32"/>
Schema
set-delta-shift =
element set-delta-shift { attlist.set-delta-shift, empty }
attlist.set-delta-shift &=
attribute units-per-pixel { "2" | "4" | "8" | "16" | "32" | "64" }
with-delta-shift =
element with-delta-shift { attlist.with-delta-shift, programming* }
attlist.with-delta-shift &=
attribute units-per-pixel { "2" | "4" | "8" | "16" | "32" | "64" }
<set-dropout-control>
Sets up dropout control. For details, see the TrueType specification.
Schema
set-dropout-control =
element set-dropout-control { attlist.set-dropout-control, empty }
attlist.set-dropout-control &=
attribute threshold { text },
attribute flags { text }?
<set-dropout-type>
Sets dropout type. For details, see the TrueType specification. Possible values for value are 0, 1 and 2.
Schema
set-dropout-type =
element set-dropout-type { attlist.set-dropout-type, empty }
attlist.set-dropout-type &= attribute value { text }
<set-dual-projection-vector>
Like <set-projection-vector>, but the dual projection vector can be set only from a line, and it uses the original positions in the outline of the points that constitute the line rather than their current positions (assuming they have moved).
The dual projection vector is not used by every instruction: just by <interpolate>, <get-coordinate>, <measure-distance>, <mirp>, <mdrp>, and <move> (only when a "relative-to" point is present). This vector lasts only until a new projection vector is set; then it gets canceled.
One or both points in the line may be in the twilight zone. See the explanation for <set-vectors>.
<with-projection-vector>
<set-dual-projection-vector to-line="orthogonal">
<line ref="line-a"/>
<set-dual-projection-vector>
<!-- programming here; then the end of the with-projection-vector
block returns the dual projection vector to its former value. -->
</with-projection-vector>
Schema
set-dual-projection-vector =
element set-dual-projection-vector {
attlist.set-dual-projection-vector, line
}
attlist.set-dual-projection-vector &=
[ a:defaultValue = "parallel" ]
attribute to-line { "orthogonal" | "parallel" }?
<set-equal>
Set target (variable, control value, or any of the graphics state variables that Xgridfit can write to) equal to source, which can be an expression or any number type that Xgridfit can handle.
<!-- This is the equivalent of a := b; in C. -->
<set-equal target="a" source="b"/>
Schema
set-equal = element set-equal { attlist.set-equal, empty }
attlist.set-equal &=
attribute target { text },
attribute source { text }
<set-freedom-vector>
<with-freedom-vector>
Just like <set-vectors>, but sets only the freedom vector.
Schema
set-freedom-vector =
element set-freedom-vector { attlist.set-freedom-vector, line? }
attlist.set-freedom-vector &=
attribute axis { "x" | "y" }?,
[ a:defaultValue = "parallel" ]
attribute to-line { "orthogonal" | "parallel" }?,
attribute x-component { text }?,
attribute y-component { text }?
with-freedom-vector =
element with-freedom-vector {
attlist.with-freedom-vector, line?, programming*
}
attlist.with-freedom-vector &=
attribute axis { "x" | "y" }?,
[ a:defaultValue = "parallel" ]
attribute to-line { "orthogonal" | "parallel" }?,
attribute x-component { text }?,
attribute y-component { text }?
<set-minimum-distance>
<with-minimum-distance>
The minimum-distance property is used by several instructions when the "min-distance" attribute is "yes." The default minimum distance is one pixel (1.0, 1p, 64), but can be set to another value here.
<with-minimum-distance value="0.85">
<!-- The distance between p1 and p2 must be at least 0.85 pixel. -->
<move round="no">
<reference>
<point num="p1"/>
</reference>
<point num="p2"/>
</move>
</with-minimum-distance>
Schema
set-minimum-distance =
element set-minimum-distance { attlist.set-minimum-distance, empty }
attlist.set-minimum-distance &= attribute value { text }
with-minimum-distance =
element with-minimum-distance {
attlist.with-minimum-distance, programming*
}
attlist.with-minimum-distance &= attribute value { text }
<set-projection-vector>
<with-projection-vector>
Just like <set-vectors>, but sets only the projection vector.
Schema
set-projection-vector =
element set-projection-vector { attlist.set-projection-vector, line? }
attlist.set-projection-vector &=
attribute axis { "x" | "y" }?,
[ a:defaultValue = "parallel" ]
attribute to-line { "orthogonal" | "parallel" }?,
attribute x-component { text }?,
attribute y-component { text }?
with-projection-vector =
element with-projection-vector {
attlist.with-projection-vector, line?, programming*
}
attlist.with-projection-vector &=
attribute axis { "x" | "y" }?,
[ a:defaultValue = "parallel" ]
attribute to-line { "orthogonal" | "parallel" }?,
attribute x-component { text }?,
attribute y-component { text }?
<set-round-state>
<with-round-state>
Sets the round state. If the round attribute matches the name of a <round-state>, that round state is used. If not, one of TrueType's prefabricated round states may be used:
- to-grid
- to-half-grid
- to-double-grid
- up-to-grid
- down-to-grid
If the round attribute is not one of these, and not one of the custom round-states, Xgridfit tries to resolve it as a number, constant, variable or function parameter and use that as an argument to SROUND. You had better know what you're doing if you intend to use a raw number in this way; it is safer, more intelligible and just as effective to supply a custom <round-state> element.
The distinction between the element beginning with "set" and the one beginning with "with" is the same as it is for the vector-setting elements: briefly, the round state set by the "set" element affects the instructions that follow it; the round state set by the "with" instruction affects only the instructions that it contains.
Xgridfit generates instructions that keep track of the round state (since the TrueType engine provides no way to read it), but it may lose track if Xgridfit instructions are not used exclusively.
<with-round-state round="to-half-grid">
<move>
<point num="v-point"/>
</move>
</with-round-state>
Schema
set-round-state =
element set-round-state { attlist.set-round-state, empty }
attlist.set-round-state &= attribute round { text }
with-round-state =
element with-round-state { attlist.with-round-state, programming* }
attlist.with-round-state &= attribute round { text }
<set-single-width>
<with-single-width>
The size of the single width, in FUnits, i.e. the units of the grid the font was designed on (usually 2048 or 1000 units per em). Presumably this width is converted to the current grid, and it is that converted value that the single-width cut-in is compared to.
Schema
set-single-width =
element set-single-width { attlist.set-single-width, empty }
attlist.set-single-width &= attribute value { text }
with-single-width =
element with-single-width { attlist.with-single-width, programming* }
attlist.with-single-width &= attribute value { text }
<set-single-width-cut-in>
<with-single-width-cut-in>
When the <mirp> or <mdrp> instruction is used, or when <move> is used relative to a point, a single width (determined by <set-single-width> or <with-single-width>) may be used rather than a control value or the original distance if this condition is met: the absolute (either positive or negative) difference between the original outline and the single width is less than the single-width cut-in. The relevant distances are in pixels.
The single width feature appears to be used rarely.
Schema
set-single-width-cut-in =
element set-single-width-cut-in {
attlist.set-single-width-cut-in, empty
}
attlist.set-single-width-cut-in &= attribute value { text }
with-single-width-cut-in =
element with-single-width-cut-in {
attlist.with-single-width-cut-in, programming*
}
attlist.with-single-width-cut-in &= attribute value { text }
<set-vectors>
<with-vectors>
Sets both the projection vector and the freedom vector to the same value. They can be set to "x" or "y" via the axis attribute; to a line by including a line element as the content of the <set-vectors> element or the first child of the <with-vectors> element; or by passing "raw" values via the x-component and y-component attributes.
Xgridfit looks first for an axis attribute, next for a <line>, and finally for x-component and y-component attributes (neither is used unless both are present). If it finds none of these and the present element is <with-vectors>, Xgridfit simply stores the present vectors on the stack and restores them at the end of the block. If the present element is <set-vectors>, Xgridfit prints a warning and attempts to find "raw" vector values on the stack.
The "raw" values passed in via x-component and y-component are constrained in ways that make them difficult to calculate, at least in a TrueType program, but the x-component/y-component method is useful to restore values that have been saved via <store-projection-vector> or <store-freedom-vector>. For example, to copy one vector to another, you can do this:
<variable name="x-comp"/>
<variable name="y-comp"/>
<store-freedom-vector x-component="x-comp" y-component="y-comp"/>
<set-projection-vector x-component="x-comp" y-component="y-comp"/>
But because of the way these instructions can leave values on the stack and take them from the stack again, this is easier and more efficient:
<store-freedom-vector/>
<set-projection-vector/>
When setting vectors to a line, one or both points in the line can be in the twilight zone. You can include a zone attribute in the <line> element or one in either or both <point> elements. Include a zone attribute in the <line> element if both points are in the twilight zone. This is the same as including an attribute zone="twilight" in both points. If only one point is in the twilight zone, include the zone attribute for that point.
Here are several examples:
<with-vectors axis="x">
<!-- programming that moves points horizontally. -->
</with-vectors>
<with-vectors to-line="orthogonal">
<line ref="diagonal-line"/>
<!-- programming that moves points along a line orthogonal to
diagonal-line. -->
</with-vectors>
<set-vectors to-line="parallel">
<line ref="diagonal-line"/>
</set-vectors>
<!-- Subsequent programming will move points along a line parallel
to diagonal-line. -->
Schema
set-vectors = element set-vectors { attlist.set-vectors, line? }
attlist.set-vectors &=
attribute axis { "x" | "y" }?,
[ a:defaultValue = "parallel" ]
attribute to-line { "orthogonal" | "parallel" }?,
attribute x-component { text }?,
attribute y-component { text }?
with-vectors =
element with-vectors { attlist.with-vectors, line?, programming* }
attlist.with-vectors &=
attribute axis { "x" | "y" }?,
[ a:defaultValue = "parallel" ]
attribute to-line { "orthogonal" | "parallel" }?,
attribute x-component { text }?,
attribute y-component { text }?
Attributes
- axis
- The axis to which the vectors should be set. Permitted values are x and y.
- to-line
- Whether the vectors should be parallel or orthogonal (perpendicular) to the line being used to set the vector. The default value is parallel.
- x-component
- The x component of the vector to set. This has no effect unless the y-component attribute is included as well.
- y-component
- The y component of the vector to set. This has no effect unless the x-component attribute is included as well.
<shift>
Shifts one or more points, ranges, sets, contours and zones by the distance between the current position of the reference point and its original position. Note that this does not guarantee that the shifted elements will maintain their original distance from the reference point (use <move> or <mdrp> for that).
The <shift> element may contain points, ranges, sets, contours and zones in any combination and order. The following is perfectly correct:
<shift>
<reference>
<point num="ref-pt"/>
</reference>
<point num="move-pt-1"/>
<range ref="move-rg-1"/>
<contour num="0"/>
<point num="move-pt-2"/>
<range ref="move-rg-2"/>
</shift>
But note that all the points are shifted first, then all the ranges or sets, then all the contours, and finally any zones. The order of child elements in the <shift> element is not significant.
Schema
shift =
element shift {
attlist.shift, reference?, (point | range | set | contour | zone)*
}
attlist.shift &=
[ a:defaultValue = "1" ] attribute reference-ptr { "1" | "2" }?,
attribute compile-if { text } ?
Attributes
- reference-ptr
- Addresses a technical detail: the SHP, SHC and SHZ instructions can use either RP1 or RP2, and this attribute determines which. Chiefly useful if the RP you want to use has already been set; otherwise the default (RP1) should do fine. Xgridfit automatically sets this correctly when a <shift> instruction is nested inside a <move> instruction.
<shift-absolute>
Moves one or more points along the freedom vector by a fixed amount (expressed in pixels); it does not use the projection vector. The <shift-absolute> element must contain at least one point to shift: that is, a <range>, <set> or <point> element. It may contain any number of <point>s, <range>s and <set>s.
Schema
shift-absolute =
element shift-absolute { attlist.shift-absolute, (point | range | set)* }
attlist.shift-absolute &= attribute pixel-distance { text }
Attribute
- pixel-distance
- The distance (in pixels) to shift the points.
<srp>
Does the work of SRP0, SRP1, SRP2. But it should rarely be necessary to set the reference pointers explicitly.
Schema
srp = element srp { attlist.srp, point }
attlist.srp &= attribute whichpointer { text }
Attribute
- whichpointer
- determines which of the three reference points to set. It may be "0," "1" or "2."
<store-projection-vector>
<store-freedom-vector>
These instructions store a vector as two numbers, an x-component and a y-component. The x-component and y-component attributes, if given, must be identifiers for variables:
<store-projection-vector x-component="vx" y-component="vy"/>
If these attributes are not given, a warning is printed and the values are left on the stack, where they will be picked up correctly by a following set instruction. For example, this code sets the projection vector to be the same as the freedom vector:
<store-freedom-vector/>
<set-projection-vector/>
Note that a with block will not pick up the components of a vector from the stack.
Schema
store-projection-vector =
element store-projection-vector {
attlist.store-projection-vector, empty
}
attlist.store-projection-vector &=
attribute x-component { text }?,
attribute y-component { text }?
store-freedom-vector =
element store-freedom-vector { attlist.store-freedom-vector, empty }
attlist.store-freedom-vector &=
attribute x-component { text }?,
attribute y-component { text }?
Attributes
- x-component
- The x-component of the vector. Both the x-component and the y-component must be present if either is present; otherwise the one that is present is ignored, and the two components of the vector are left on the stack.
- y-component
- The y-component of the vector.
<subtract>
Subtracts minuend - subtrahend. If result-to is not specified, Xgridfit attempts to write the result to minuend.
Schema
subtract = element subtract { attlist.subtract, empty }
attlist.subtract &=
attribute minuend { text }?,
attribute subtrahend { text }?,
attribute result-to { text }?
<szp>
Does the work of SZP0, SZP1, SZP2. But these should rarely be needed (use the zone attributes of the point element instead).
Schema
szp = element szp { attlist.szp, empty }
attlist.szp &=
attribute whichpointer { text },
attribute zone { "twilight" | "glyph" }
<toggle-points>
Any of the points that are on-line become off-line, and any that are off-line become on-line. The <toggle-points> element must contain at least one point to toggle: that is, a <range>, <set> or <point> element. It may contain any number of <point>s, <set>s and <range>s.
Schema
toggle-points =
element toggle-points { attlist.toggle-points, (point | range | set)* }
attlist.toggle-points &= empty
<to-stack>
The content is any number literal, constant, variable, expression or other item that can be resolved to a number either at compile time or at run-time. This number is placed on top of the stack, where it can be used by a primitive TrueType <command>.
This element resembles <push>, but differs in two important respects. First, while <push> may contain a list of values, <to-stack> may contain only one. Second, while <push> can accept only values that resolve to numbers at compile time (number literals, constants, control-value indices, and simple addition and subtraction expressions), <to-stack> can accept any value recognized by Xgridfit. In essence, <to-stack> provides direct access to Xgridfit's mechanism for recognizing numbers of different types, resolving identifiers, and parsing expressions.
Here is an example of the use of <to-stack> 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:
<to-stack>line-2-a</to-stack>
<to-stack>cvt</to-stack>
<command name="MIRP">
<modifier type="set-rp0" value="yes"/>
<modifier type="minimum-distance" value="yes"/>
<modifier type="round" value="yes"/>
<modifier type="color" value="gray"/>
</command>
Schema
to-stack = element to-stack { attlist.to-stack, text }
attlist.to-stack &= empty
<untouch>
A point that has been moved is "touched." This untouches it so that it will be affected by the <interpolate-untouched-points> instruction.
Schema
untouch = element untouch { attlist.untouch, point }
attlist.untouch &= empty
<variable>
Variables are spaces in the TrueType Storage Area. They are declared in <variable> elements; Xgridfit takes care of indexing the Storage Area.
<variable name="var-name"/>
Most variables are local to a glyph program, function or pre-program. Variable declarations may come among the declarations at the beginning of a <glyph> program; after <param> elements in a <function>, and at the beginning of the <pre-program>. A global variable may be declared anywhere in the top level of the program, as a child of <xgridfit> (it is good form to group variable declarations together); a value may be assigned to a global variable in the <pre-program> and read by code in any <glyph> or <function> or elsewhere in the <pre-program>. It makes little sense to attempt to assign a value to a global variable in a <glyph> or <function>, and an attempt to do so is certain to have unpredictable results.
Variables must be written to before they can be read from. (Freetype initializes them to zero, but the Microsoft rasterizer gives an error if a variable is read before it is written.)
A variable is named via its name attribute. This must be unique in the file in the case of a global variable, but in the case of local variables unique only in the <glyph> program or <function>. Several names are reserved and should be avoided when naming variables and constants, since they belong to pre-defined variables and constants:
- Current size (all read-only):
- pixels-per-em
- point-size
- Values of the round-state variable (constants):
- to-grid
- to-half-grid
- to-double-grid
- down-to-grid
- up-to-grid
- no
- custom
- Graphics variables:
Writing to these changes the graphics state. The "default" variables can be written to only in the <pre-program>. Trying to write to them elsewhere produces a compile error. Actually, it is never necessary to write to a "default" variable since writing to one of the other variables in the <pre-program> automatically writes to the "default" variable as well. So treat the "default" variables as read-only variables.
- round-state (can be written to only via <set-round-state> and <with-round-state>)
- custom-round-state (can be written to only via <set-round-state> and <with-round-state>)
- minimum-distance
- minimum-distance-default
- control-value-cut-in
- control-value-cut-in-default
- single-width
- single-width-default
- single-width-cut-in
- single-width-cut-in-default
- delta-base delta-base-default
- delta-shift delta-shift-default
Schema
Note: the id attribute and the <variables> element are deprecated.
variables = element variables { attlist.variables, variable+ }
attlist.variables &= empty
variable = element variable { attlist.variable, empty }
attlist.variable &=
attribute name { text }?,
attribute id { text }?
<with-control-value-cut-in>
See <set-control-value-cut-in>
<with-delta-base>
See <set-delta-base>
<with-delta-shift>
<with-freedom-vector>
<with-minimum-distance>
<with-param>
Defines a value to be passed to a function or macro. The value may be any of the value-types that Xgridfit handles. Note that all values are resolved to numbers before a call to a function takes place: Xgridfit does not pass parameters to functions by reference. A result of this is that if a variable or control value is passed to a function, these things cannot be written to.
In general there will be a <with-param> element for every <param> element that appears in the function or macro being called. However, a <with-param> element may be omitted if the matching <param> contains a default value.
The order of <with-param> elements in a <param-set>, <call-function> or <call-macro> element is not significant.
If the <with-param> element is part of a call to a macro, the value passed can be a <set>, <range> or <line>. The name of such a structure can be passed via the value attribute, or the structure itself can be passed as the child of <with-param>. When <with-param> contains a <set>, <range> or <line>, the value attribute is optional.
Schema
Note: the param-id attribute is deprecated.
with-param = element with-param { attlist.with-param, (set | range | line)? }
attlist.with-param &=
attribute name { text }?,
attribute param-id { text }?,
attribute value { text }?,
attribute offset { text }?
Attributes
- name
- Identifies which parameter this is. It must match the "name" attribute in one of the <param> elements in the <function> or macro. Note: param-id, which does the same job, is deprecated.
- value
- The value to be passed to the function. It may be any of the various kinds of values used in Xgridfit: e.g. number literal, constant, variable, or a function parameter if this function is being called from within another function.
- offset
- Deprecated in function calls, and not guaranteed to work at all in calls to macros. Number to be added to a point specifier to further identify a point. The value must be a number literal or a constant; it may be either positive or negative.
<with-projection-vector>
<with-round-state>
<with-single-width>
<with-single-width-cut-in>
<with-vectors>
See <set-vectors>
<xgridfit>
The root element of an Xgridfit program file.
Schema
xgridfit =
element xgridfit {
attlist.xgridfit,
profile?,
(control-values?|control-value*),
(functions?|function*),
(macros?|macro*),
pre-program?,
(xg.xi.include | glyph)*
}
attlist.xgridfit &= attribute xml:id { xsd:ID }?
<zone>
A zone to be shifted by a <shift> instruction.
Schema
zone = element zone { attlist.zone, empty }
attlist.zone &= attribute zone { "twilight" | "glyph" }