/usr/share/doc/xgridfit/html/functions.html is in xgridfit-doc 2.3-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>xgridfit</title>
<link rel="stylesheet" href="oeg.css" media="screen" type="text/css" />
<link rel="stylesheet" href="parchment.css" media="screen"
type="text/css" title="parchment" />
<link rel="alternate stylesheet" href="legible.css" media="screen"
type="text/css" title="legible" />
<style type="text/css" media="print"> @import "oeg.print.css"; </style>
<meta name="AUTHOR" content="Peter S. Baker" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
<div id="jumplist">
<a href="http://sourceforge.net"><img src="" width="125" height="37" border="0" alt="SourceForge.net Logo" /></a>
<a href="http://xgridfit.sourceforge.net/">Home Page</a>
<a href="http://sourceforge.net/projects/xgridfit">Project Page</a>
<a href="http://sourceforge.net/project/showfiles.php?group_id=159705">Download</a>
<a href="http://xgridfit.cvs.sourceforge.net/xgridfit/xgridfit/">CVS repository</a>
<hr/>
<a href="#functions">Functions</a>
<a href="#macros">Macros</a>
<a href="#glyph">Glyph Programs</a>
<a href="#callable">Callable Parameters</a>
<a href="#nesting">Nesting and Recursion</a>
</div>
<div id="content">
<h1>Functions, Macros and Glyph Programs</h1>
<p>
Functions and macros are blocks of code that you write once and
invoke wherever they are needed. The compiled code for a function
is stored separately from other code in a font; the function is
"called" at run time. The compiled code for a macro is inserted in
the program stream at the place where it is called: after
compilation there is nothing to distinguish the macro code from
any other code in a glyph program. Both the function and the macro
can take parameters--that is, values passed to the function or
macro from the code that calls it and then consulted or operated
upon by the function or macro.
</p>
<p>
A <glyph> program can be called from another <glyph>
program, very much as a macro is called. This feature is useful
for hinting accented glyphs if you prefer not to use TrueType
components. Like a macro, a <glyph> program can take
parameters.
</p>
<h2 id="functions">Functions</h2>
<p>
In most programming languages, the great value of a function is
that it can act upon information that is not known until passed in
one or more parameters at run time, and it can operate on a value
and return it transformed. And yet there is no standard way to
pass parameters to a TrueType function, and no way to return a
value from it. In TrueType, functions are numbered rather than
named as in most programming languages. Xgridfit overcomes these
limitations, providing for the naming of functions, enabling the
passing of parameters, and providing a mechanism for returning
values.
</p>
<h3>Defining functions</h3>
<p>
Each function for a font is defined in a <function>
element. Each <function> is identified by a <tt>name</tt>
attribute. If the function takes parameters, these must be defined
in <param> elements, which come first in the function:
</p>
<pre>
<function name="my-function">
<param name="first-param"/>
<param name="second-param"/>
. . .
</function></pre>
<p>
A function parameter is a read-only value: it can be referenced in
any instruction element that reads values:
</p>
<pre>
<function name="my-function">
<param name="ref-point"/>
<param name="move-point"/>
<move>
<reference>
<point num="ref-point"/>
</reference>
<point num="move-point"/>
</move>
</function></pre>
<p>
A parameter may have a default value, used if the parameter is not
specified when the function is called. The value may be a number
literal or a global constant. Specify the default value with the
<tt>value</tt> attribute (e.g. <tt>value="0"</tt>).
</p>
<p>
A function may return one value (and that value, like all others
in Xgridfit, must be a number). A function that returns a value
must have the attribute <tt>return="yes"</tt>. Then, within, the
function, assign a value to "return," e.g.
</p>
<pre>
<set-equal target="return" source="control-value(stem-width) / 2"/></pre>
<p>
For a way around the one-value return limitation, see "Passing
parameters by reference" below.
</p>
<h3>Calling functions</h3>
<p>
A function may be called (its code executed) from a glyph program,
the pre-program, or another function. To call a function, use the
<call-function> element, which may contain one or more
<with-param> elements, one for each of the function's
parameters:
</p>
<pre>
<call-function name="cap-half-standard-serif">
<with-param name="base" value="bottom"/>
<with-param name="near-base" value="bottom-serif-bottom"/>
<with-param name="opposite-base" value="bottom-serif-top"/>
</call-function>
</pre>
<p>
It frequently makes sense to call a function repeatedly, once for
each instance of some visible feature (such as a serif). In that
case the content of <call-function> may be several
<param-set> elements, each containing one or more
<with-param> elements specifing the parameters for one
running of the function:
</p>
<pre>
<call-function name="auto-cap-vert-serif">
<param-set>
<with-param name="base" value="top-right"/>
</param-set>
<param-set>
<with-param name="base" value="top-left"/>
</param-set>
<param-set>
<with-param name="base" value="bottom-right"/>
</param-set>
<param-set>
<with-param name="base" value="bottom-left"/>
</param-set>
</call-function>
</pre>
<p>
The function is called once for each <param-set> using
TrueType's efficient LOOPCALL instruction.
</p>
<p>
The list of parameters for each call to the function must be
complete, except for any parameters with default values. Omitting
a parameter generates a fatal compile error. The order of
parameters in a call is not significant.
</p>
<p>
A parameter <tt>value</tt> can be any value or expression, as long
as it can be resolved to a number at run time. It cannot be a more
complex structure--a <line>, <range> or <set>.
Variables are by default passed to functions by value, while
control values are passed by reference. This may seem like an
inconsistency, but it is the behavior that is most often
wanted. It can easily be overridden, as the next section explains.
</p>
<p>
Global constants and variables are visible from a function; and
the function can contain its own variables, defined in
<variable> elements just after the <param> elements.
</p>
<p>
A <call-function> element for a function that returns a
value should ordinarily have a <tt>result-to</tt> attribute
specifying a variable, control value, or a graphics variable that
can be written to. If this element is missing, the Xgridfit
compiler issues a warning and the value is left on the stack.
</p>
<h3 id="function-variant">Function Variants</h3>
<p>
Function variants are alternative versions of a function to be
used at different sizes or resolutions. Define function variants
by including one or more <variant> elements at the end of a
function definition, thus:
</p>
<pre>
<function name="myfunc">
<param name="myparam"/>
<!-- default function programming -->
<variant test="pixels-per-em &lt; 20">
<!-- programming to be used at less than 20 pixels per em. -->
</variant>
<variant test="pixels-per-em &gt; 100">
<!-- programming to be used at greater than 100 pixels per em. -->
</variant>
</function>
</pre>
<p>
Though you define functions with variants along with other
functions (those that lack variants), the TrueType engine actually
defines them when the <pre-program> is run. Thus the
<tt>test</tt> attribute of the <variant> element, which
determines whether a particular variant is to be used, may be
based on whatever is known at that time--typically size and
resolution information.
</p>
<p>
A function variant cannot have its own <param> or
<variable> definitions; it always uses those of the function
in which it is embedded. In the example above, the
<tt>myparam</tt> parameter is visible inside the <variant>
elements just as it is in the default programming (that which is
not inside a <variant> element and which is used if none of
the <tt>test</tt> attribute evaluate as true at run-time).
</p>
<p>
If you have defined more than one <variant> for a function,
the <tt>test</tt> attributes should be exclusive: that is, no more
than one should evaluate as true at any given time. If you do the
following:
</p>
<pre>
<function name="myfunc">
. . .
<variant test="pixels-per-em &lt; 20">
. . .
</variant>
<variant test="pixels-per-em &lt;= 10">
. . .
</variant>
</function>
</pre>
<p>
then at 10 pixels-per-em the TrueType engine will first define the
first function variant and then overwrite it with the second. This
should not produce an error, but it certainly is an inefficient
way of doing things. This is far better:
</p>
<pre>
<function name="myfunc">
. . .
<variant test="pixels-per-em &lt; 20 and pixels-per-em &gt; 10">
. . .
</variant>
<variant test="pixels-per-em &lt;= 10">
. . .
</variant>
</function>
</pre>
<p>
The advantage of using function variants over using <if>
elements within functions to produce different behavior depending
on size or resolution is that in the former case the decision
which programming to use is made just once, when the
<pre-program> is run, while in the latter case the decision
is made over and over again, whenever the function is called.
</p>
<h3>Passing parameters by reference</h3>
<p>
Suppose you want to write a function that returns a vector. The
function can return only a single number, but a vector is a
structure consisting of two numbers: x and y coordinates. The
limitation on the return from a function can be overcome by
passing two variables to the function by reference so that the
function can store the vector in those variables. Use the
<tt>index()</tt> operator to do so:
</p>
<pre>
<variable name="vector-x"/>
<variable name="vector-y"/>
. . .
<call-function name="get-vector-from-line">
<with-param name="line-a" value="a"/>
<with-param name="line-b" value="b"/>
<with-param name="x" value="index(vector-x)"/>
<with-param name="y" value="index(vector-y)"/>
</call-function></pre>
<p>
Since a number in TrueType carries no type information with it,
the code inside your function must recognize that the parameters
<tt>x</tt> and <tt>y</tt> are references to variables instead of
the values of variables, and that they can be written to. Use the
<tt>variable()</tt> operator for this purpose.
</p>
<pre>
<function name="get-vector-from-line">
<param name="line-a"/>
<param name="line-b"/>
<param name="x"/>
<param name="y"/>
<with-projection-vector to-line="parallel">
<line>
<point num="line-a"/>
<point num="line-b"/>
</line>
<store-projection-vector x-component="variable(x)"
y-component="variable(y)"/>
</with-projection-vector>
</function></pre>
<p>
After the function returns the vector will be stored in variables
<tt>vector-x</tt> and <tt>vector-y</tt>.
</p>
<h2 id="macros">Macros</h2>
<p>
A macro is a good way to regulate features (such as serifs) that
occur frequently and yet do not require large or complex stretches
of code. Using a macro can save the overhead of a function call
and bypass the somewhat bulky code required to read function
parameters. The downside of macros is that, since the compiled
code is inserted repeatedly into the font, they can increase the
font's size significantly. Macros, then, are most useful for
features that are very frequent but also fairly simple.
</p>
<p>
Each macro is defined in a <macro> element. Here is a macro
definition that regulates a standard vertical stem with attached
serif when one point on the stem is anchored to another point:
</p>
<pre>
<macro name="lc-vert-stem-serif-anchor-dist">
<param name="anchor"/>
<param name="distance-from-anchor"/>
<param name="stem-a"/>
<param name="serif-a"/>
<param name="stem-b"/>
<param name="serif-b"/>
<move distance="distance-from-anchor">
<reference>
<point num="anchor"/>
</reference>
<point num="stem-a"/>
<move distance="lc-serif-width">
<point num="serif-a"/>
</move>
<move distance="lc-vert-stroke">
<point num="stem-b"/>
<move distance="lc-serif-width">
<point num="serif-b"/>
</move>
</move>
</move>
</macro>
</pre>
<p>
Here is a call to that macro:
</p>
<pre>
<call-macro name="lc-vert-stem-serif-anchor-dist">
<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></pre>
<p>
The compiled code, once inserted in the font, is twenty-four bytes
in length.
</p>
<p>
Like a function, a macro can take parameters (and the
<param> element can contain a <tt>value</tt> attribute with
a default value). The <tt>value</tt> of the <param> or
<with-param> element is substituted at compile time rather
than passed at run time. The <call-macro> element may
contain <with-param> elements, if the macro code is to be
compiled and inserted just once where the <call-macro>
element occurs. Alternatively, the <call-macro> element may
contain any number of <param-set> elements, each containing
a complete set of <with-param> elements, and the macro code
is inserted for each one.
</p>
<h3>Macro parameters</h3>
<p>
Though macro parameters look like function parameters, they are
much more flexible. The Xgridfit compiler substitutes the
<tt>value</tt> in the <with-param> element for the
identifier that references the <param> inside the macro;
then it proceeds to resolve the <tt>value</tt> as it would any
other value. Thus the <tt>value</tt> passed as a parameter may be
any kind of expression. The name of a <line>, <range>
or <set> can also be passed, and referenced by a
<tt>ref</tt> inside the macro.
</p>
<p>
You may not only pass a <line>, <range> or <set>
by name, but also declare it as the content of a
<with-param> element. This is a convenience when you do not
need to use the structure elsewhere in the glyph program:
</p>
<pre>
<with-param name="s">
<set>
<point num="p1"/>
<point num="p2"/>
<point num="p3"/>
</set>
</with-param>
</pre>
<p>
When <with-param> has content the <tt>value</tt> attribute
is optional: assign it some arbitrary value if your macro code <a
href="points.html#nan-test">tests for the presence of a
parameter</a>.
</p>
<h3>Macros and conditional compilation</h3>
<p>
You can make macros more flexible by using conditional
compilation. Any stretch of code may be compiled conditionally by
enclosing it in a <a
href="if.html#compile-if"><compile-if></a> element, and a
<move>, <align>, <interpolate>, <shift> or
<delta> element can be compiled conditionally by including
the <tt>compile-if</tt> attribute. The <tt>test</tt> attribute of
<compile-if> and the <tt>compile-if</tt> attribute may
contain only expressions that can be evaluated at compile
time. But since point numbers in Xgridfit are usually constants,
and thus known at compile time, it is usually possible to base
conditional compilation on point numbers. For example, the
following macro takes eleven parameters, of which six are optional:
it can control a visual structure that is either more or less
complex:
</p>
<pre>
<macro name="lc-vertical-stem-with-serif-anchor">
<param name="anchor"/>
<param name="distance-from-anchor" value="-1"/>
<param name="stem-a"/>
<param name="stem-a1" value="-1"/>
<param name="stem-a2" value="-1"/>
<param name="serif-a"/>
<param name="stem-b"/>
<param name="stem-b1" value="-1"/>
<param name="stem-b2" value="-1"/>
<param name="serif-b"/>
<param name="serif-top" value="-1"/>
<compile-if test="distance-from-anchor &gt;= 0">
<move distance="distance-from-anchor">
<reference>
<point num="anchor"/>
</reference>
<point num="stem-a"/>
<move distance="lc-serif-width">
<point num="serif-a"/>
</move>
</move>
<else>
<move>
<reference>
<point num="anchor"/>
</reference>
<point num="stem-a"/>
<move distance="lc-serif-width">
<point num="serif-a"/>
</move>
</move>
</else>
</compile-if>
<align compile-if="stem-a1 &gt;= 0 and stem-a2 &lt; 0">
<point num="stem-a1"/>
</align>
<align compile-if="stem-a1 &gt;= 0 and stem-a2 &gt;= 0">
<point num="stem-a1"/>
<point num="stem-a2"/>
</align>
<move distance="lc-vert-stroke">
<reference>
<point num="stem-a"/>
</reference>
<point num="stem-b"/>
<align compile-if="stem-b1 &gt;= 0 and stem-b2 &lt; 0">
<point num="stem-b1"/>
</align>
<align compile-if="stem-b1 &gt;= 0 and stem-b2 &gt;= 0">
<point num="stem-b1"/>
<point num="stem-b2"/>
</align>
<move distance="lc-serif-width">
<point num="serif-b"/>
</move>
</move>
<compile-if test="serif-top &gt;= 0">
<move distance="ascender-serif-x-width">
<reference>
<point num="stem-a"/>
</reference>
<point num="serif-top"/>
</move>
</compile-if>
</macro>
</pre>
<p>
This macro can control the points of a simple structure like this one
</p>
<table>
<tr>
<td>
<img src="l-bottom.png" alt="l"/>
</td>
</tr>
</table>
<p>
with this call:
</p>
<pre>
<call-macro name="lc-vertical-stem-with-serif-anchor">
<with-param name="anchor" value="an"/>
<with-param name="stem-a" value="a"/>
<with-param name="stem-b" value="b"/>
<with-param name="serif-a" value="c"/>
<with-param name="serif-b" value="d"/>
</call-macro>
</pre>
<p>
If points must be aligned with "stem-a" or "stem-b," they can be
passed via parameters "stem-a1," "stem-b1," and so on. If there is
a top serif, as on a lower-case <b>i</b>, the end point for that
serif can also be passed to the macro, and the appropriate code
will be compiled:
</p>
<table>
<tr>
<td>
<img src="i-no-dot.png" alt="l"/>
</td>
</tr>
</table>
<pre>
<call-macro name="lc-vertical-stem-with-serif-anchor">
<with-param name="anchor" value="an"/>
<with-param name="stem-a" value="a"/>
<with-param name="stem-b" value="b"/>
<with-param name="serif-a" value="c"/>
<with-param name="serif-b" value="d"/>
<with-param name="serif-top" value="e"/>
</call-macro>
</pre>
<h2 id="glyph">Glyph Programs</h2>
<p>
A glyph program may stand by itself and also be called from within
another glyph program. It is a simple matter to prepare a glyph
program to play such a dual role, and equally simple to call the
program. It is handy to be able to call a glyph program if, like a
number of font makers, you prefer to avoid using the TrueType
component mechanism to make accented glyphs. If you are adding
instructions to, say, <b>eacute</b>, then as long as the
outlines that constitute the <b>e</b> and the <b>acute</b>
portions of the glyph are identical to those of the <b>e</b> and
<b>acute</b> glyphs, it makes sense to call the glyph programs
for <b>e</b> and <b>acute</b> to instruct the composite. The
resulting glyph program might look something like this:
</p>
<pre>
<glyph ps-name="eacute">
<constant name="last" value="89"/>
<call-glyph ps-name="e">
<with-param name="interpolate" value="0"/>
<with-param name="left-sidebearing" value="last + 1"/>
<with-param name="right-sidebearing" value="last + 2"/>
</call-glyph>
<call-glyph ps-name="acute" variables="no">
<with-param name="offset" value="66"/>
<with-param name="left-sidebearing" value="last + 1"/>
</call-glyph>
</glyph>
</pre>
<p>
The first elements in the <glyph> program being called must
be <param> elements; these are exactly like the
<param> elements in functions and macros. Because a
<glyph> program must be able to run by itself as well as be
called, the <tt>value</tt> attribute, which supplies a default
value for the <param>, is usually obligatory.
</p>
<p>
The glyph program may take one special parameter, named
<tt>offset</tt>. If the <tt>offset</tt> parameter is present, then
its value is automatically added to all point numbers. The
sensible default value for <tt>offset</tt> will usually be
zero. With the <tt>offset</tt> parameter, the beginning of the
glyph program for <b>acute</b> might look like this:
</p>
<pre>
<glyph ps-name="acute">
<param name="offset" value="0"/>
<param name="left-sidebearing" value="last + 1"/>
<constant name="last" value="17"/>
<constant name="bottom" value="3"/>
<constant name="top" value="10"/>
. . .
</pre>
<p>
Note that the Xgridfit compiler cannot always recognize which
numbers are point numbers. It will always handle <point>
elements correctly, but when point numbers are passed as
parameters to functions, macros, and other glyph programs, you
must either add the <tt>offset</tt> value manually or (perhaps
better) use the <tt>point</tt> operator to indicate to the
compiler that the number is a point:
</p>
<pre>
<with-param name="p" value="pt + offset"/>
<with-param name="p" value="point(pt)"/>
</pre>
<p>
You must do the same in <push> elements and in all
expressions that do not appear in <point> elements. To avoid
complications, it might be best to arrange glyphs in such a way
that offsets are not needed for the more complex features. In the
glyph program for <b>eacute</b>, illustrated above, <b>acute</b>
is less complex than <b>e</b>, so <b>acute</b> has the offset.
</p>
<p>
An important difference between a glyph program run by the
TrueType engine and one called by another glyph program is that
the TrueType engine sets the various graphics variables to their
default values before running the program; it does not perform the
same service for the called glyph program. If your program has
changed the graphics state, you should set the variables you've
changed to their default values before calling a glyph
program. For most graphics variables (those whose state Xgridfit
tracks), you may do this by calling <restore-default>,
including the <tt>name</tt> attribute with one of the following
values:
</p>
<ul>
<li>minimum-distance</li>
<li>control-value-cut-in</li>
<li>single-width</li>
<li>single-width-cut-in</li>
<li>delta-base</li>
<li>delta-shift</li>
<li>round-state</li>
<li>all</li>
</ul>
<p>
The <tt>all</tt> option sets all of the above graphics variables
to the defaults set by your Xgridfit program, or the TrueType
defaults if you have not explicitly set any defaults. It also sets
several graphics variables that Xgridfit does not track (the
freedom and projection vectors and the auto-flip toggle) to their
TrueType defaults. The <tt>all</tt> option is an expensive one, of
course; it is best to be aware of the condition in which your
program so far has left the graphics state and call
<restore-default> only for those graphics variables that
must be reset.
</p>
<h2 id="callable">Callable Parameters</h2>
<p>
A parameter to a macro or glyph program (but not a function) may
contain code to be executed within the called code block. A call
to a glyph program, for example, might look like this:
</p>
<pre>
<call-glyph ps-name="dieresis">
<with-param name="offset" value="A/total"/>
<with-param name="delta">
<delta>
<delta-set size="3" distance="4">
<point num="dieresis/left-left + A/total"/>
</delta-set>
</delta>
</with-param>
</call-glyph>
</pre>
<p>
Within the glyph program, the parameter is "called" with the
<call-param> element:
</p>
<pre>
<call-param name="delta"/>
</pre>
<p>
The parameter is declared at the top of the macro or glyph
program. It is like other parameters, except that a <tt>value</tt>
attribute, if present, is ignored, and that the <param>
element can contain code to be executed if a <with-param>
element of that <tt>name</tt> is not found in the call to the
macro or glyph program. In the following <param> element,
for example, the default code simply touches a point:
</p>
<pre>
<param name="delta">
<move round="no">
<point num="left-left"/>
</move>
</param>
</pre>
<p>
It is an error if no <param> is found to match the
<call-param> element. However, if there is no matching
<with-param> element in the call to the macro or glyph
program and the <param> contains no default code, that is
not an error. In that case, the Xgridfit compiler issues a warning
and does nothing.
</p>
<p>
The <call-param> element can pass no parameters to the
called code: if it contains <with-param> elements, they are
ignored. When writing code to be passed via a parameter to a macro
or glyph program, it is important to take context into
account. Constants, variables, and other elements declared within,
say, a <glyph> element are not visible from outside of
it. Thus, in the <call-glyph> example above, the
<tt>left-left</tt> point in the called glyph must be referenced
via glyph/constant syntax as <tt>dieresis/left-left</tt>. But for
the <param> example this is not necessary, since the default
code is declared within the glyph program itself.
</p>
<h2 id="nesting">Nesting and Recursion</h2>
<p>
A TrueType function can call another TrueType function, including
itself. Before Xgridfit version 2.2 there were significant
limitations on the ability of macros to call other macros and of
called glyph programs to call macros. But in version 2.2 these
limitations have been removed. Thus it is practical to construct a
macro that does a complex job by calling several macros that do
simple jobs. For example:
</p>
<pre>
<macro name="single-serif">
<param name="base"/>
<param name="serif-end"/>
<move distance="serif-width">
<reference>
<point num="base"/>
</reference>
<point num="serif-end"/>
</move>
</macro>
<macro name="double-serif">
<param name="left-base"/>
<param name="left-serif-end"/>
<param name="right-base"/>
<param name="right-serif-end"/>
<call-macro name="single-serif">
<with-param name="base" value="left-base"/>
<with-param name="serif-end" value="left-serif-end"/>
</call-macro>
<call-macro name="single-serif">
<with-param name="base" value="right-base"/>
<with-param name="serif-end" value="right-serif-end"/>
</call-macro>
</macro>
</pre>
<p>
It is also perfectly all right for a macro to call itself
recursively; though it must be remembered that recursion, for a
macro, is in the compilation, not in the execution. Thus this
macro:
</p>
<pre>
<macro name="touch-points">
<param name="first"/>
<param name="last"/>
<move round="no">
<point num="first"/>
</move>
<compile-if test="first < last">
<call-macro name="touch-points">
<with-param name="first" value="first + 1"/>
<with-param name="last" value="last"/>
</call-macro>
</compile-if>
</macro>
</pre>
<p>
if called like this:
</p>
<pre>
<call-macro name="touch-points">
<with-param name="first" value="0"/>
<with-param name="last" value="2"/>
</call-macro>
</pre>
<p>
will generate code that looks like this:
</p>
<pre>
PUSHB_1
0
MDAP[0]
PUSHB_1
1
MDAP[0]
PUSHB_1
2
MDAP[0]
</pre>
<p>
which may or may not be what you want.
</p>
</div>
</body>
</html>
|