| blob | 4d73bcb5d435a4a1edf6ec92adea932e786fd9d8 |
1 <!-- This file is part of Shapes. -->
2 <!-- -->
3 <!-- Shapes is free software: you can redistribute it and/or modify -->
4 <!-- it under the terms of the GNU General Public License as published by -->
5 <!-- the Free Software Foundation, either version 3 of the License, or -->
6 <!-- any later version. -->
7 <!-- -->
8 <!-- Shapes is distributed in the hope that it will be useful, -->
9 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of -->
10 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -->
11 <!-- GNU General Public License for more details. -->
12 <!-- -->
13 <!-- You should have received a copy of the GNU General Public License -->
14 <!-- along with Shapes. If not, see <http://www.gnu.org/licenses/>. -->
15 <!-- -->
16 <!-- Copyright 2008, 2009, 2010, 2015 Henrik Tidefelt -->
18 <section id="bindings/functions">
19 <title>Functions</title>
20 <top>
21 <p>These are the functions!</p>
23 <p>After all, <str-Shapes /> is a special-purpose language aimed at the production of graphics. Hence, functions for path drawing, creation of affine transforms, and path computations are a very important part of the language.</p>
25 <p>Remember <value name="immerse" /> and <value name="facing" />, and in particular the <arg name="scale" /> and <arg name="distort" /> options to <value name="facing" />. The following is quite nice:
26 </p>
27 <pre>
28 facing: [../facing scale:true distort:true ...]
29 </pre>
30 </top>
32 <system-binding name="abs">
33 <summary>Modulus of scalar values, norm of vectors, and length of paths</summary>
34 <function>
35 <top>
36 <p>This is the function invoked by the syntax <syntax name="abs-call" />. The binding is useful when the function needs to be passed around as a value, or if one does not like the special syntax.</p>
37 <p>Common to all cases of this function, is that the result is some kind of non-negative scalar (that is, a <named-type name="Float" />, <named-type name="Length" />, or <named-type name="Integer" />).</p>
38 </top>
39 <case>
40 <arguments>
41 <arg>
42 <type><named-type name="Float" /></type>
43 </arg>
44 </arguments>
45 <result>
46 <type><named-type name="Float" /></type>
47 </result>
48 <dynamic-references></dynamic-references>
49 <description><p>Absolute value.</p></description>
50 </case>
51 <case>
52 <arguments>
53 <arg>
54 <type><named-type name="Integer" /></type>
55 </arg>
56 </arguments>
57 <result>
58 <type><named-type name="Integer" /></type>
59 </result>
60 <dynamic-references></dynamic-references>
61 <description><p>Absolute value.</p></description>
62 </case>
63 <case>
64 <arguments>
65 <arg>
66 <type><named-type name="Length" /></type>
67 </arg>
68 </arguments>
69 <result>
70 <type><named-type name="Length" /></type>
71 </result>
72 <dynamic-references></dynamic-references>
73 <description><p>Unsigned length.</p></description>
74 </case>
75 <case>
76 <arguments>
77 <arg>
78 <type><named-type name="FloatPair" /></type>
79 </arg>
80 </arguments>
81 <result>
82 <type><named-type name="Float" /></type>
83 </result>
84 <dynamic-references></dynamic-references>
85 <description><p>Euclidean norm.</p></description>
86 </case>
87 <case>
88 <arguments>
89 <arg>
90 <type><named-type name="Coords" /></type>
91 </arg>
92 </arguments>
93 <result>
94 <type><named-type name="Length" /></type>
95 </result>
96 <dynamic-references></dynamic-references>
97 <description><p>Euclidean norm.</p></description>
98 </case>
99 <case>
100 <arguments>
101 <arg>
102 <type><named-type name="FloatTriple" /></type>
103 </arg>
104 </arguments>
105 <result>
106 <type><named-type name="Float" /></type>
107 </result>
108 <dynamic-references></dynamic-references>
109 <description><p>Euclidean norm.</p></description>
110 </case>
111 <case>
112 <arguments>
113 <arg>
114 <type><named-type name="Coords3D" /></type>
115 </arg>
116 </arguments>
117 <result>
118 <type><named-type name="Length" /></type>
119 </result>
120 <dynamic-references></dynamic-references>
121 <description><p>Euclidean norm.</p></description>
122 </case>
123 <case>
124 <arguments>
125 <arg>
126 <type><named-type name="Path" /></type>
127 </arg>
128 </arguments>
129 <result>
130 <type><named-type name="Length" /></type>
131 </result>
132 <dynamic-references></dynamic-references>
133 <description><p>Length of path.</p></description>
134 </case>
135 <case>
136 <arguments>
137 <arg>
138 <type><named-type name="Path3D" /></type>
139 </arg>
140 </arguments>
141 <result>
142 <type><named-type name="Length" /></type>
143 </result>
144 <dynamic-references></dynamic-references>
145 <description><p>Length of path.</p></description>
146 </case>
147 <case>
148 <arguments>
149 <arg>
150 <type><named-type name="Dash" /></type>
151 </arg>
152 </arguments>
153 <result>
154 <type><named-type name="Length" /></type>
155 </result>
156 <dynamic-references></dynamic-references>
157 <description><p>Length of dash pattern.</p></description>
158 </case>
159 </function>
160 </system-binding>
162 <system-binding name="affinetransform">
163 <function>
164 <case constructor-of="Transform">
165 <arguments>
166 <arg>
167 <type><named-type name="FloatPair" /></type>
168 </arg>
169 <arg>
170 <type><named-type name="FloatPair" /></type>
171 </arg>
172 <arg>
173 <type><named-type name="Coords" /></type>
174 </arg>
175 </arguments>
176 <dynamic-references></dynamic-references>
177 <description><p>Construct transform from multiplier for x and y coordinates, followed by a shift.</p></description>
178 </case>
179 </function>
180 </system-binding>
182 <system-binding name="affinetransform3D">
183 <function>
184 <case constructor-of="Transform3D">
185 <arguments>
186 <arg>
187 <type><named-type name="FloatTriple" /></type>
188 </arg>
189 <arg>
190 <type><named-type name="FloatTriple" /></type>
191 </arg>
192 <arg>
193 <type><named-type name="FloatTriple" /></type>
194 </arg>
195 <arg>
196 <type><named-type name="Coords3D" /></type>
197 </arg>
198 </arguments>
199 <dynamic-references></dynamic-references>
200 <description><p>Construct transform from multiplier for x, y, and z coordinates, followed by a shift.</p></description>
201 </case>
202 </function>
203 </system-binding>
205 <system-binding name="shift">
206 <function>
207 <case constructor-of="Transform">
208 <arguments>
209 <arg>
210 <type><named-type name="Coords" /></type>
211 </arg>
212 </arguments>
213 <dynamic-references></dynamic-references>
214 <description><p>Construct transform.</p></description>
215 </case>
216 <case constructor-of="Transform3D">
217 <arguments>
218 <arg>
219 <type><named-type name="Coords3D" /></type>
220 </arg>
221 </arguments>
222 <dynamic-references></dynamic-references>
223 <description><p>Construct transform.</p></description>
224 </case>
225 </function>
226 </system-binding>
228 <system-binding name="rotate">
229 <function>
230 <case constructor-of="Transform">
231 <arguments>
232 <arg identifier="angle">
233 <type><named-type name="Float" /></type>
234 </arg>
235 </arguments>
236 <dynamic-references></dynamic-references>
237 <description><p>Construct transform.</p></description>
238 </case>
239 </function>
240 </system-binding>
242 <system-binding name="rotate3D">
243 <function>
244 <case constructor-of="Transform3D">
245 <arguments>
246 <arg identifier="dir">
247 <type><named-type name="FloatTriple" /></type>
248 </arg>
249 <arg identifier="angle">
250 <type><named-type name="Float" /></type>
251 </arg>
252 </arguments>
253 <dynamic-references></dynamic-references>
254 <description><p>Construct rotation transform about given direction.</p></description>
255 </case>
256 </function>
257 </system-binding>
259 <system-binding name="scale">
260 <function>
261 <case constructor-of="Transform">
262 <arguments>
263 <arg identifier="r">
264 <type><named-type name="Float" /></type>
265 <default>1</default>
266 </arg>
267 <arg identifier="x">
268 <type><named-type name="Float" /></type>
269 <default>1</default>
270 </arg>
271 <arg identifier="y">
272 <type><named-type name="Float" /></type>
273 <default>1</default>
274 </arg>
275 </arguments>
276 <dynamic-references></dynamic-references>
277 <description><p>Construct transform that scales x by <arg name="r" /><char-cdot /><arg name="x" />, and y by <arg name="r" /><char-cdot /><arg name="y" />.</p></description>
278 </case>
279 </function>
280 </system-binding>
282 <system-binding name="scale3D">
283 <function>
284 <case constructor-of="Transform3D">
285 <arguments>
286 <arg identifier="r">
287 <type><named-type name="Float" /></type>
288 <default>1</default>
289 </arg>
290 <arg identifier="x">
291 <type><named-type name="Float" /></type>
292 <default>1</default>
293 </arg>
294 <arg identifier="y">
295 <type><named-type name="Float" /></type>
296 <default>1</default>
297 </arg>
298 <arg identifier="z">
299 <type><named-type name="Float" /></type>
300 <default>1</default>
301 </arg>
302 </arguments>
303 <dynamic-references></dynamic-references>
304 <description><p>Construct transform that scales x by <arg name="r" /><char-cdot /><arg name="x" />, and similarly with y and z.</p></description>
305 </case>
306 </function>
307 </system-binding>
309 <system-binding name="inverse">
310 <function>
311 <case constructor-of="Transform">
312 <arguments>
313 <arg>
314 <type><named-type name="Transform" /></type>
315 </arg>
316 </arguments>
317 <dynamic-references></dynamic-references>
318 <description><p>Constructs the inverse of a transform. This is only possible if the linear part of the transform is non-singular.</p></description>
319 </case>
320 <case constructor-of="Transform3D">
321 <arguments>
322 <arg>
323 <type><named-type name="Transform3D" /></type>
324 </arg>
325 </arguments>
326 <dynamic-references></dynamic-references>
327 <description><p>Constructs the inverse of a transform. This is only possible if the linear part of the transform is non-singular.</p></description>
328 </case>
329 </function>
330 </system-binding>
332 <system-binding name="spot">
333 <function>
334 <case constructor-of="Drawable">
335 <arguments>
336 <arg>
337 <type><named-type name="Coords" /></type>
338 </arg>
339 </arguments>
340 <dynamic-references><dynamic name="width" /> <dynamic name="stroking" /></dynamic-references>
341 <description>
342 <p>Paints a round spot at the given coordinates. The width and color of the spot is as if the spot was a stroke, see <value name="stroke" />.</p>
343 <p>Note that spots can also be made by stroking a closed singelton path with a round cap style. That is,
344 <pre>
345 [spot pt]
346 </pre>
347 is equivalent to
348 <pre>
349 @cap:CAP_ROUND | [stroke emptypath--pt--cycle]
350 </pre>
351 </p>
352 <p>Also note that using <value name="spot" /> is much more efficient than using <value name="fill" /> on a circular path.</p>
353 <p>Rather than making the origin the default value for the argument, the dynamic variable <dynamic name="spot" /> is provided to make the dynamic nature of the expression more obvious compared to <inline>[spot]</inline>.</p>
354 <p>Some <str-PDF /> viewers fail to do the obvious thing when a singleton path is painted with a stroke, and if you are targeting such viewers you could either change the implementation of <value name="spot" /> using the command line option <a part="man" id="AllowSingletonPaths">--spot-pair=yes</a>, or use <value name="stroke" /> on a path between two points at the same location instead of using <value name="spot" />, like so:
355 <pre>
356 @cap:CAP_ROUND | [stroke pt--(+(0m,0m))]
357 </pre>
358 </p>
359 </description>
360 <see-also>
361 <dynamic name="spot" />
362 </see-also>
363 </case>
364 </function>
365 </system-binding>
367 <system-binding name="stroke">
368 <function>
369 <case constructor-of="Drawable">
370 <arguments>
371 <arg identifier="path">
372 <type><named-type name="Path" /></type>
373 </arg>
374 <arg identifier="head">
375 <default><value name="NO_ARROW" /></default>
376 <type><named-type name="ArrowHead" /></type>
377 </arg>
378 <arg identifier="tail">
379 <default><value name="NO_ARROW" /></default>
380 <type><named-type name="ArrowHead" /></type>
381 </arg>
382 </arguments>
383 <dynamic-references><dynamic name="width" /> <dynamic name="stroking" /> <dynamic name="dash" /> <dynamic name="cap" /> <dynamic name="join" /> <dynamic name="miterlimit" /></dynamic-references>
384 <description>
385 <p>Paints the <arg name="path" /> argument by stroking it. Properties such as color (<dynamic name="stroking" />), width, <abbr-etc /> are taken from the dynamic environment.</p>
386 <p>The arguments <arg name="head" /> and <arg name="tail" /> define arrowheads at the corresponding ends of the stroke. An arrowhead is defined by a function that takes the path as argument, and returns a tuple with fields <field name="picture" /> and <field name="cut" />. Here, <field name="picture" /> shall be the grahpics that is the actual arrowhead, while <field name="cut" /> tells how much the stroke shall be shortened to not interfere with the arrowhead. Note that the arrowhead and the stroke usually overlap, but that it is not desirable that the stroke goes all the way to the point of the arrowhead.</p>
387 </description>
388 </case>
389 <case constructor-of="Drawable3D">
390 <arguments>
391 <arg identifier="path">
392 <type><named-type name="Path3D" /></type>
393 </arg>
394 <arg identifier="head">
395 <default><value name="NO_ARROW" /></default>
396 <type><named-type name="ArrowHead3D" /></type>
397 </arg>
398 <arg identifier="tail">
399 <default><value name="NO_ARROW" /></default>
400 <type><named-type name="ArrowHead3D" /></type>
401 </arg>
402 </arguments>
403 <dynamic-references><dynamic name="width" /> <dynamic name="stroking" /> <dynamic name="dash" /> <dynamic name="cap" /> <dynamic name="join" /> <dynamic name="miterlimit" /></dynamic-references>
404 <description>
405 <p>Compare with the <str-2D /> case.</p>
406 <p>Note that defining arrow heads is much more intricate in <str-3D /> than in <str-2D />, and generally requires knowledge of from what angle the arrowhead will later be viewed. If one is really eager to work around this “problem”, then what one is typically looking for is a way to delay the definition of the arrowhead until the viewing angle is known. The key to the solution is <value name="facing" />.</p>
407 </description>
408 </case>
409 </function>
410 </system-binding>
412 <system-binding name="fill">
413 <function>
414 <case constructor-of="Drawable">
415 <arguments>
416 <arg identifier="path">
417 <type><named-type name="Path" /></type>
418 </arg>
419 </arguments>
420 <dynamic-references><dynamic name="nonstroking" /></dynamic-references>
421 <description>
422 <p>Paints the <arg name="path" /> (that shall be closed) argument by filling it using the <em>nonzero winding rule</em>. The fill color is taken from <dynvar name ="nonstroking" />.</p>
423 <example-with-output title="Filling with the nonzero winding rule" internal-id="example:fill-winding-rule">
424 <image pdf="doc/fill-winding-rule_3.pdf" jpg="doc/fill-winding-rule_y_big.jpg" />
425 <source file="doc/fill-winding-rule.shape">
426 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/fill-winding-rule.shape" -->]]>
427 </source>
428 <caption>
429 <p>When filling a path with <value name="fill" />, the <em>nonzero winding rule</em> is applied. This example is a reconstruction of the corresponding example in the <str-PDF /> reference.</p>
430 </caption>
431 </example-with-output>
432 </description>
433 <see-also>
434 <value name="winding" />
435 </see-also>
436 </case>
437 <case constructor-of="Drawable3D">
438 <arguments>
439 <arg identifier="path">
440 <type><named-type name="Path3D" /></type>
441 </arg>
442 <arg identifier="tiebreaker">
443 <default>0</default>
444 <type><named-type name="Length" /></type>
445 </arg>
446 </arguments>
447 <dynamic-references><dynamic name="nonstroking" /></dynamic-references>
448 <description>
449 <p>Paints the <arg name="path" /> (that shall be closed) argument by filling it <em>nonzero winding rule</em>. The fill color is taken from <dynamic name="nonstroking" />.</p>
450 <p>Note that although winding rules don't really make any sense in <str-3D />, some rule must nevertheless be applied to the path once it has been projected to <str-2D />. Then, the <em>nonzero winding rule</em> is the simplest and hence most reasonable choice.</p>
451 </description>
452 </case>
453 </function>
454 </system-binding>
456 <system-binding name="fillodd">
457 <function>
458 <case constructor-of="Drawable">
459 <arguments>
460 <arg>
461 <type><named-type name="Path" /></type>
462 </arg>
463 </arguments>
464 <dynamic-references><dynamic name="nonstroking" /></dynamic-references>
465 <description>
466 <p>Paints the <arg name="path" /> (that shall be closed) argument by filling it with the color <dynamic name="nonstroking" />, using the <em>even-odd rule</em>.</p>
467 <example-with-output title="Filling with the even-odd rule" internal-id="example:fillodd-winding-rule">
468 <image pdf="doc/fillodd-winding-rule_3.pdf" jpg="doc/fillodd-winding-rule_y_big.jpg" />
469 <source file="doc/fillodd-winding-rule.shape">
470 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/fillodd-winding-rule.shape" -->]]>
471 </source>
472 <caption>
473 <p>When filling a path with <value name="fillodd" />, the <em>even-odd rule</em> is applied. This example is a reconstruction of the corresponding example in the <str-PDF /> reference.</p>
474 </caption>
475 </example-with-output>
476 </description>
477 <see-also>
478 <value name="winding" />
479 </see-also>
480 </case>
481 </function>
482 </system-binding>
485 <system-binding name="TeX">
486 <function>
487 <case constructor-of="Drawable">
488 <arguments>
489 <arg>
490 <type><named-type name="String" /></type>
491 </arg>
492 </arguments>
493 <dynamic-references><dynamic name="TeX_bleed" /></dynamic-references>
494 <description>
495 <p>Sends the string to <str-pdfLateX /> and returns the resulting piece of typeset text.</p>
496 <p>The origin of the produced label is the same as in <str-LaTeX />; at the leftmost point of the baseline. Unfortunately, fonts lie about their bounding boxes to make them look smaller, and this will cause the produced label to be slightly cropped when imported. At the moment, I can't think of a good way to get around this problem, since a tight bounding box is important for layout purposes. By controlling the size of the bleed box using <dynamic name="TeX_bleed" />, you can at least try to avoid the problem of the final result getting cropped too tight.</p>
497 <p>If the expression is a string literal, it is handled more efficiently than if the string must be obtained by evaluation.</p>
498 </description>
499 </case>
500 </function>
501 </system-binding>
504 <system-binding name="list">
505 <function>
506 <case constructor-of="SingleList">
507 <arguments>
508 <sink>
509 </sink>
510 </arguments>
511 <description>
512 <p>Constructs a list of the arguments.</p>
513 <p>The value created when called with no arguments is recognized by <value name="null?" />, and should be used as a null marker for <named-type name="ConsPair" /> lists.</p>
514 </description>
515 <see-also><value name="unlist" /></see-also>
516 </case>
517 </function>
518 </system-binding>
520 <system-binding name="unlist">
521 <function>
522 <case constructor-of="Structure">
523 <arguments>
524 <arg>
525 <type><named-type name="SingleList" /></type>
526 </arg>
527 </arguments>
528 <description>
529 <p>Converts a list to a structure, being the inverse of <value name="list" /> in the sense that
530 <pre>
531 <![CDATA[\ lst → ( list [] <>[unlist lst] )]]>
532 </pre>
533 is the identity for <named-type name="SingleList" /> values, and
534 <pre>
535 <![CDATA[\ struct → [unlist ( list [] <>struct )]]]>
536 </pre>
537 is the identify for <named-type name="Structure" /> values without named parts.</p>
538 <p>Note how this function may be used to define a Scheme-like <inline>apply</inline> function:
539 <pre>
540 <![CDATA[apply: \ fun args → ( fun [] <>[unlist args] )]]>
541 </pre>
542 </p>
543 </description>
544 <see-also><value name="list" /></see-also>
545 </case>
546 </function>
547 </system-binding>
549 <system-binding name="cons">
550 <function>
551 <case constructor-of="ConsPair">
552 <arguments>
553 <arg identifier="car"></arg>
554 <arg identifier="cdr"></arg>
555 </arguments>
556 <description>
557 <p>Constructs a cons pair. The arguments are not forced, which allows infinite data structures to be defined.</p>
558 </description>
559 </case>
560 </function>
561 </system-binding>
563 <system-binding name="range">
564 <function>
565 <case constructor-of="SingleList">
566 <arguments>
567 <arg identifier="begin">
568 <type><named-type name="Integer" /></type>
569 </arg>
570 <arg identifier="end">
571 <type><named-type name="Integer" /></type>
572 </arg>
573 <arg identifier="step">
574 <type><named-type name="Integer" /></type>
575 </arg>
576 <arg identifier="count">
577 <type><named-type name="Integer" /></type>
578 </arg>
579 </arguments>
580 <description>
581 <p>Constructs a range of <named-type name="Integer" /> values. One of the arguments must be omitted, and it is forbidden to provide <arg name="begin" />, <arg name="end" />, and <arg name="count" /> at the same time. It is allowed to omit both <arg name="step" /> and <arg name="count" />, in which case <arg name="step" /> defaults to (a positive) 1.</p>
582 <p>See the <named-type name="Float" /> case for the semantics of the various argument combinations, and notes on efficiency.</p>
583 </description>
584 </case>
585 <case constructor-of="SingleList">
586 <arguments>
587 <arg identifier="begin">
588 <type><named-type name="Float" /></type>
589 </arg>
590 <arg identifier="end">
591 <type><named-type name="Float" /></type>
592 </arg>
593 <arg identifier="step">
594 <type><named-type name="Float" /></type>
595 </arg>
596 <arg identifier="count">
597 <type><named-type name="Integer" /></type>
598 </arg>
599 </arguments>
600 <description>
601 <p>Constructs a range of <named-type name="Float" /> values. One of the arguments must be omitted. It is allowed to omit both <arg name="step" /> and <arg name="count" />, in which case <arg name="step" /> defaults to (a positive) 1.</p>
602 <p>If <arg name="step" /> is provided, it determines the step length. If <arg name="count" /> is provided, it determines the number of elements in the constructed range, which will begin at <arg name="begin" /> if <arg name="begin" /> is provided, and end at <arg name="end" /> if <arg name="end" /> is provided (note that achieving this using <arg name="step" /> may be inconvenient or even difficult due to problems with numeric precision). If neither <arg name="step" /> nor <arg name="count" /> is provided, <arg name="step" /> defaults to 1.</p>
603 <p>When both <arg name="begin" /> and <arg name="end" /> are provided, the range starts at <arg name="begin" />, and ends at a value with is not <em>past</em> <arg name="end" />. This is not like in <str-C-plus-plus />, where <em>end</em> refers to a point in a range which itself is past the end of the range.</p>
604 <p><em>Note on efficiency:</em> The result is constructed in constant time and space, and is particularly efficient for left folds. Semantically, it is as if the whole range was stored element by element in a long list, but the kernel just stores the first element, the step, and the total number of elements. During a left fold, at two values in the range are stored in memory at the same time. A right fold, on the other hand, will require all elements to be constructed before they can be destructed again. Hence, when possible, right folds should be avoided in favor of left folds over a range constructed with elements in the reverse order.</p>
605 </description>
606 </case>
607 <case constructor-of="SingleList">
608 <arguments>
609 <arg identifier="begin">
610 <type><named-type name="Length" /></type>
611 </arg>
612 <arg identifier="end">
613 <type><named-type name="Length" /></type>
614 </arg>
615 <arg identifier="step">
616 <type><named-type name="Length" /></type>
617 </arg>
618 <arg identifier="count">
619 <type><named-type name="Integer" /></type>
620 </arg>
621 </arguments>
622 <description>
623 <p>Constructs a range of <named-type name="Length" /> values. One of the arguments must be omitted, and it is forbidden to omit both <arg name="step" /> and <arg name="count" />.</p>
624 <p>See the <named-type name="Float" /> case for the semantics of the various argument combinations, and notes on efficiency.</p>
625 </description>
626 </case>
627 <body>
628 <example-with-output title="Range construction" internal-id="example:ranges">
629 <source file="features/ranges.blank">
630 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/ranges.blank" -->]]>
631 </source>
632 <stdout>
633 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/ranges.stdout" -->]]>
634 </stdout>
635 </example-with-output>
636 </body>
637 <see-also><value name="span" /></see-also>
638 </function>
639 </system-binding>
641 <system-binding name="span">
642 <function>
643 <case constructor-of="Span">
644 <arguments>
645 <arg identifier="begin"></arg>
646 <arg identifier="end"></arg>
647 <arg identifier="step"></arg>
648 <arg identifier="count"></arg>
649 </arguments>
650 <description>
651 <p>Calling <self /> is like calling <value name="range" />, except that the arguments may use the special <syntax name="last-expr" /> expression to refer to the last position in a container. Since the container will generally not be known at the time of the call, the arguments are not evaluated immediately, but stored as thunks inside <named-type name="Span" /> value.</p>
652 <p>Since a <self /> should be used to select ranges of valid container positions, there are more defaults available when calling <self /> compared to <value name="range" />. For instance, a span including all but the first two positions in a container can be constructed as
653 <pre>
654 <![CDATA[[span begin:'2]]]>
655 </pre>
656 and a span including all but the last two positions as
657 <pre>
658 <![CDATA[[span end:%last-'2]]]>
659 </pre>
660 </p>
661 <p>Note that a <named-type name="Span" /> value is not automatically expanded to <named-type name="SingleList" /> whenever a <named-type name="SingleList" /> is expected, so it is up to the methods of the container types to accept <named-type name="Span" /> values and expand them.</p>
662 </description>
663 <see-also>
664 <value name="range" /> <named-type name="String" />
665 </see-also>
666 </case>
667 </function>
668 </system-binding>
670 <system-binding name="reverse">
671 <function>
672 <case constructor-of="Path">
673 <arguments>
674 <arg>
675 <type><named-type name="Path" /></type>
676 </arg>
677 </arguments>
678 <dynamic-references></dynamic-references>
679 <description>
680 <p>Construct path where the order of pathpoints in the representation is reversed. The constructed path looks identical to the original.</p>
681 </description>
682 </case>
683 <case constructor-of="Path3D">
684 <arguments>
685 <arg>
686 <type><named-type name="Path3D" /></type>
687 </arg>
688 </arguments>
689 <dynamic-references></dynamic-references>
690 <description>
691 <p>Analogous to the the <str-2D /> case.</p>
692 </description>
693 </case>
694 </function>
695 </system-binding>
697 <system-binding name="meetpaths">
698 <function>
699 <case constructor-of="Path">
700 <arguments>
701 <arg>
702 <type><named-type name="Path" /></type>
703 </arg>
704 <arg>
705 <type><named-type name="Path" /></type>
706 </arg>
707 </arguments>
708 <dynamic-references></dynamic-references>
709 <description>
710 <p>Merge the two paths by merging the <field name="end" /> point of the first path with the <field name="begin" /> point of the second path. It is not required for the two paths to intersect; the merge operation is defined anyway by replacing the two merged points with one at the mean, taking one interpolation point form each path. Use this to avoid vanishing spline segments when joining two consecutive paths.</p>
711 <p>Hopefully, the example below expresses the idea more clearly.</p>
712 <example-with-output title="Merging paths" internal-id="example:meetpaths">
713 <image pdf="showcase/mergepaths_3.pdf" jpg="showcase/mergepaths_y_big.jpg" />
714 <source file="showcase/mergepaths.shape">
715 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)showcase/mergepaths.shape" -->]]>
716 </source>
717 <caption>
718 <p>Application of <value name="meetpaths" />. Note that the interesting stuff is found in <a extension="linkpaths" />.</p>
719 </caption>
720 </example-with-output>
721 </description>
722 </case>
723 <case constructor-of="Path3D">
724 <arguments>
725 <arg>
726 <type><named-type name="Path3D" /></type>
727 </arg>
728 <arg>
729 <type><named-type name="Path3D" /></type>
730 </arg>
731 </arguments>
732 <dynamic-references></dynamic-references>
733 <description>
734 <p>Analogous to the the <str-2D /> case.</p>
735 </description>
736 </case>
737 </function>
738 </system-binding>
740 <system-binding name="winding">
741 <function>
742 <case>
743 <arguments>
744 <arg identifier="path">
745 <type><named-type name="Path" /></type>
746 </arg>
747 <arg identifier="origin">
748 <type><named-type name="Coords" /></type>
749 </arg>
750 </arguments>
751 <result>
752 <type><named-type name="Integer" /></type>
753 </result>
754 <dynamic-references></dynamic-references>
755 <description>
756 <p>Counts the number of counter-clockwise turns that <arg name="path" /> makes about <arg name="origin" />. It is required that <arg name="path" /> be closed.</p>
757 <p>The winding number is used to define filling and clipping.</p>
758 <example-with-output title="Winding numbers" internal-id="example:winding-numbers">
759 <image pdf="doc/winding-numbers_3.pdf" jpg="doc/winding-numbers_y_big.jpg" />
760 <source file="doc/winding-numbers.shape">
761 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/winding-numbers.shape" -->]]>
762 </source>
763 <caption>
764 <p>Winding numbers computed by <value name="winding" />.</p>
765 </caption>
766 </example-with-output>
767 <example-with-output title="Argument variation integrals" internal-id="example:argument-variation">
768 <image pdf="features/argument_3.pdf" jpg="features/argument_y_big.jpg" />
769 <source file="features/argument.shape">
770 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/argument.shape" -->]]>
771 </source>
772 <caption>
773 <p>Using <value name="winding" /> to compute the argument variation integral for open paths.</p>
774 </caption>
775 </example-with-output>
776 </description>
777 <see-also>
778 <value name="fill" /> <value name="fillodd" /> <value name="clip" /> <value name="clipodd" />
779 </see-also>
780 </case>
781 </function>
782 </system-binding>
784 <system-binding name="upsample_balance">
785 <function>
786 <case constructor-of="Path">
787 <arguments>
788 <arg>
789 <type><named-type name="Path" /></type>
790 </arg>
791 </arguments>
792 <dynamic-references></dynamic-references>
793 <description>
794 <p>Divide each spline segment in two such that the velocity is continuous at the new path point. This will make the distance to the two interpolation points at the new path point equal, hence the name. It turns out that this happens at spline time 0.5, so the implementation is very cheap.</p>
795 </description>
796 </case>
797 <case constructor-of="Path3D">
798 <arguments>
799 <arg>
800 <type><named-type name="Path3D" /></type>
801 </arg>
802 </arguments>
803 <dynamic-references></dynamic-references>
804 <description>
805 <p>Analogous to the the <str-2D /> case.</p>
806 </description>
807 </case>
808 </function>
809 </system-binding>
811 <system-binding name="upsample_inflections">
812 <function>
813 <case constructor-of="Path">
814 <arguments>
815 <arg>
816 <type><named-type name="Path" /></type>
817 </arg>
818 </arguments>
819 <dynamic-references></dynamic-references>
820 <description>
821 <p>Add samples at inflection points.</p>
822 </description>
823 </case>
824 </function>
825 </system-binding>
827 <system-binding name="upsample_bends">
828 <function>
829 <case constructor-of="Path">
830 <arguments>
831 <arg identifier="angle">
832 <type><named-type name="Float" /></type>
833 </arg>
834 <arg identifier="path">
835 <type><named-type name="Path" /></type>
836 </arg>
837 </arguments>
838 <dynamic-references></dynamic-references>
839 <description>
840 <p>Add samples at inflection points, and so that each segment bends at most <arg name="angle" />. Segments that need upsampling (after inflections have been removed) are sampled evenly with respect to direction.</p>
841 </description>
842 </case>
843 </function>
844 </system-binding>
846 <system-binding name="upsample_every">
847 <function>
848 <case constructor-of="Path">
849 <arguments>
850 <arg identifier="period">
851 <type><named-type name="Length" /></type>
852 </arg>
853 <arg identifier="path">
854 <type><named-type name="Path" /></type>
855 </arg>
856 </arguments>
857 <dynamic-references></dynamic-references>
858 <description>
859 <p>Add sample points such that each segment is at most <arg name="period" /> long. Segments that need upsampling are sampled evenly with respect to arc length.</p>
860 </description>
861 </case>
862 <case constructor-of="Path3D">
863 <arguments>
864 <arg identifier="period">
865 <type><named-type name="Length" /></type>
866 </arg>
867 <arg identifier="path">
868 <type><named-type name="Path3D" /></type>
869 </arg>
870 </arguments>
871 <dynamic-references></dynamic-references>
872 <description>
873 <p>Analogous to the the <str-2D /> case.</p>
874 </description>
875 </case>
876 </function>
877 </system-binding>
879 <system-binding name="maximizer">
880 <function>
881 <case constructor-of="PathSlider">
882 <arguments>
883 <arg>
884 <type><named-type name="Path" /></type>
885 </arg>
886 <arg>
887 <type><named-type name="FloatPair" /></type>
888 </arg>
889 </arguments>
890 <dynamic-references></dynamic-references>
891 <description>
892 <p>Finds the first point on the path where the global maximum in the given direction is attained.</p>
893 </description>
894 </case>
895 <case constructor-of="PathSlider3D">
896 <arguments>
897 <arg>
898 <type><named-type name="Path3D" /></type>
899 </arg>
900 <arg>
901 <type><named-type name="FloatTriple" /></type>
902 </arg>
903 </arguments>
904 <dynamic-references></dynamic-references>
905 <description>
906 <p>Analogous to the the <str-2D /> case.</p>
907 </description>
908 </case>
909 </function>
910 </system-binding>
912 <system-binding name="pathpoint_maximizer">
913 <function>
914 <case constructor-of="PathSlider">
915 <arguments>
916 <arg>
917 <type><named-type name="Path" /></type>
918 </arg>
919 <arg>
920 <type><named-type name="FloatPair" /></type>
921 </arg>
922 </arguments>
923 <dynamic-references></dynamic-references>
924 <description>
925 <p>Finds the first path point on the path where the global maximum in the given direction is attained.</p>
926 </description>
927 </case>
928 <case constructor-of="PathSlider3D">
929 <arguments>
930 <arg>
931 <type><named-type name="Path3D" /></type>
932 </arg>
933 <arg>
934 <type><named-type name="FloatTriple" /></type>
935 </arg>
936 </arguments>
937 <dynamic-references></dynamic-references>
938 <description>
939 <p>Analogous to the the <str-2D /> case.</p>
940 </description>
941 </case>
942 </function>
943 </system-binding>
945 <system-binding name="controlling_maximizer">
946 <function>
947 <case constructor-of="Coords">
948 <arguments>
949 <arg>
950 <type><named-type name="Path" /></type>
951 </arg>
952 <arg>
953 <type><named-type name="FloatPair" /></type>
954 </arg>
955 </arguments>
956 <dynamic-references></dynamic-references>
957 <description>
958 <p>Finds the a point among the control points of the path, where the global maximum in the given direction is attained.</p>
959 </description>
960 </case>
961 <case constructor-of="Coords3D">
962 <arguments>
963 <arg>
964 <type><named-type name="Path3D" /></type>
965 </arg>
966 <arg>
967 <type><named-type name="FloatTriple" /></type>
968 </arg>
969 </arguments>
970 <dynamic-references></dynamic-references>
971 <description>
972 <p>Analogous to the the <str-2D /> case.</p>
973 </description>
974 </case>
975 </function>
976 </system-binding>
978 <system-binding name="approximator">
979 <function>
980 <case constructor-of="PathSlider">
981 <arguments>
982 <arg>
983 <type><named-type name="Path" /></type>
984 </arg>
985 <arg>
986 <type><named-type name="Coords" /></type>
987 </arg>
988 </arguments>
989 <dynamic-references></dynamic-references>
990 <description>
991 <p>Finds the first point on the path where the global minimum in distance to the given point is attained.</p>
992 <p>The algorithm and related tolerances are described in <a part="algo-tol" id="algorithm/approximators/point" />.</p>
993 </description>
994 </case>
995 <case constructor-of="PathSlider">
996 <arguments>
997 <arg>
998 <type><named-type name="Path" /></type>
999 </arg>
1000 <arg>
1001 <type><named-type name="Path" /></type>
1002 </arg>
1003 </arguments>
1004 <dynamic-references></dynamic-references>
1005 <description>
1006 <p>Finds a point on the first path where the global minimum in distance to the second path is attained. If there are intersections, the earliest of these is returned</p>
1007 <p>The algorithm and related tolerances are described in <a part="algo-tol" id="algorithm/approximators/path" />.</p>
1008 <p>Additional information from the computation is stored in the <field name="info" /> field of the returned <named-type name="PathSlider" />. This structure, in turn, has fields accordning to the following table.</p>
1009 <structure-fields-table>
1010 <title>The <field name="info" /> <named-type name="Structure" /> returned by <value name="approximator" /></title>
1011 <type-field name="dist">
1012 <type><named-type name="Length" /></type>
1013 <description>Distance between paths at optimum.</description>
1014 </type-field>
1015 <type-field name="other">
1016 <type><named-type name="PathSlider" /></type>
1017 <description>The “time” along the second path at optimum.</description>
1018 </type-field>
1019 </structure-fields-table>
1020 </description>
1021 </case>
1022 <case constructor-of="PathSlider3D">
1023 <arguments>
1024 <arg>
1025 <type><named-type name="Path3D" /></type>
1026 </arg>
1027 <arg>
1028 <type><named-type name="Coords3D" /></type>
1029 </arg>
1030 </arguments>
1031 <dynamic-references></dynamic-references>
1032 <description>
1033 <p>Analogous to the the <str-2D /> case.</p>
1034 </description>
1035 </case>
1036 <case constructor-of="PathSlider">
1037 <arguments>
1038 <arg>
1039 <type><named-type name="Path3D" /></type>
1040 </arg>
1041 <arg>
1042 <type><named-type name="Path3D" /></type>
1043 </arg>
1044 </arguments>
1045 <dynamic-references></dynamic-references>
1046 <description>
1047 <p>Analogous to the the <str-2D /> case. However, note that the meaning of <em>intersection</em> is not quite clear in the <str-3D /> case, and hence we shall not be precise regarding among which times the earliest is taken if there are several “intersections”.</p>
1048 </description>
1049 </case>
1050 </function>
1051 </system-binding>
1053 <system-binding name="pathpoint_approximator">
1054 <function>
1055 <case constructor-of="PathSlider">
1056 <arguments>
1057 <arg>
1058 <type><named-type name="Path" /></type>
1059 </arg>
1060 <arg>
1061 <type><named-type name="Coords" /></type>
1062 </arg>
1063 </arguments>
1064 <dynamic-references></dynamic-references>
1065 <description>
1066 <p>Finds the first path point on the path where the global minimum in distance to the given point is attained.</p>
1067 </description>
1068 </case>
1069 <case constructor-of="PathSlider3D">
1070 <arguments>
1071 <arg>
1072 <type><named-type name="Path3D" /></type>
1073 </arg>
1074 <arg>
1075 <type><named-type name="Coords3D" /></type>
1076 </arg>
1077 </arguments>
1078 <dynamic-references></dynamic-references>
1079 <description>
1080 <p>Analogous to the the <str-2D /> case.</p>
1081 </description>
1082 </case>
1083 </function>
1084 </system-binding>
1086 <system-binding name="intersection">
1087 <function>
1088 <case constructor-of="PathSlider">
1089 <arguments>
1090 <arg>
1091 <type><named-type name="Path" /></type>
1092 </arg>
1093 <arg>
1094 <type><named-type name="Path" /></type>
1095 </arg>
1096 </arguments>
1097 <dynamic-references><dynamic name="handler_NoIntersection" /></dynamic-references>
1098 <description>
1099 <p>Finds the first point on the first path where it intersects with the second path.</p>
1100 <p>If no intersection is found, the error handler <dynamic name="handler_NoIntersection" /> is called with the two paths as argumets.</p>
1101 <p>Additional information from the computation is stored in the <field name="info" /> field of the returned <named-type name="PathSlider" />. This structure, in turn, has fields accordning to the following table.</p>
1102 <structure-fields-table>
1103 <title>The <field name="info" /> <named-type name="Structure" /> returned by <value name="intersection" /></title>
1104 <type-field name="other">
1105 <type><named-type name="PathSlider" /></type>
1106 <description>The “time” of the intersection according to the second path.</description>
1107 </type-field>
1108 </structure-fields-table>
1109 </description>
1110 </case>
1111 </function>
1112 </system-binding>
1114 <system-binding name="bbox">
1115 <function>
1116 <case constructor-of="Path">
1117 <arguments>
1118 <arg identifier="obj">
1119 <type><named-type name="Drawable" /></type>
1120 </arg>
1121 <arg identifier="type">
1122 <type><named-type name="Symbol" /></type>
1123 <default><inline>'bounding</inline></default>
1124 </arg>
1125 </arguments>
1126 <dynamic-references></dynamic-references>
1127 <description>
1128 <p>Returns the <em>bounding box</em> or the <em>bleed box</em> of <arg name="obj" />, depending on the parameter <arg name="type" />.</p>
1129 <p>The allowed values for <arg name="type" /> are { <inline>'bounding</inline>, <inline>'bleed</inline> }.</p>
1130 </description>
1131 <see-also><value name="bboxed" /></see-also>
1132 </case>
1133 </function>
1134 </system-binding>
1136 <system-binding name="bboxed">
1137 <function>
1138 <case constructor-of="Drawable">
1139 <arguments>
1140 <arg identifier="obj">
1141 <type><named-type name="Drawable" /></type>
1142 </arg>
1143 <arg identifier="path">
1144 <type><named-type name="Path" /></type>
1145 </arg>
1146 <arg identifier="type">
1147 <type><named-type name="Symbol" /></type>
1148 <default><inline>'bounding</inline></default>
1149 </arg>
1150 </arguments>
1151 <dynamic-references></dynamic-references>
1152 <description>
1153 <p>Creates an object with the same content as <arg name="obj" />, but with different boxes (note that, here, <em>box</em> refers to a convex path — not necessarily a rectangle). One or both of the new objects boxes is set to <arg name="path" />, depending on the parameter <arg name="type" />.</p>
1154 <p>The allowed values for <arg name="type" /> are { <inline>'bounding</inline>, <inline>'bleed</inline>, <inline>'both</inline> }.</p>
1155 <note>
1156 <p>Generally, the <em>bounding box</em> is the convex path used for layout of an object. The <em>bleed box</em> is used by the compiler to determine where to crop the final contents of a page. Making the bleed box slightly bigger than the bounding box can be a good idea for content that may look squeezed (or even get cropped) if appearing by the border of a page.</p>
1157 </note>
1158 </description>
1159 <see-also><value name="bbox" /> <value name="clip" /> <value name="clipodd" /> <value name="TeX" /></see-also>
1160 </case>
1161 </function>
1162 </system-binding>
1164 <system-binding name="clip">
1165 <function>
1166 <case constructor-of="Drawable">
1167 <arguments>
1168 <arg identifier="obj">
1169 <type><named-type name="Drawable" /></type>
1170 </arg>
1171 <arg identifier="mask">
1172 <type><union-type><named-type name="Path" /><named-type name="Text" /><named-type name="SoftMask" /></union-type></type>
1173 </arg>
1174 </arguments>
1175 <dynamic-references></dynamic-references>
1176 <description>
1177 <p>Clips <arg name="obj" /> according to <arg name="mask" />.</p>
1178 <p>When <arg name="mask" /> is a <named-type name="Path" />, the <em>nonzero winding rule</em> is used.</p>
1179 <p>When <arg name="mask" /> is a <named-type name="Text" />, <str-Shapes /> follows <str-PDF /> with respect to the interpreation of the <dynamic name="text_rendering"/> captured in <arg name="mask" />. That is, the text will be painted as usual as a background to the clipped <arg name="obj" />. Hence, if one is interested in pure clipping, the corresponding rendering mode is obtained by <inline>[textmode]</inline> (see <value name="textmode" />). Since clipping with respect to a text is assumed to be a way of painting that text, the bounding box becomes that of <arg name="mask" /> in this case, no matter what parts of this mask that acutally has any content.</p>
1180 <p>If the goal is to crop <arg name="obj" /> to control the size of the end result, then <value name="bboxed" /> should be used instead.</p>
1181 <p>At the moment, we refrain from including an example of clipping with a <named-type name="SoftMask" /> since the implementation of this feature seems buggy in most <str-PDF /> viewers. (At least it would be good if the tool we use to generate bitmap images for this documentation was able to produce correct results before we include an example.)</p>
1182 <example-with-output title="Clipping with the nonzero winding rule" internal-id="example:clip-winding-rule">
1183 <image pdf="doc/clip-winding-rule_3.pdf" jpg="doc/clip-winding-rule_y_big.jpg" />
1184 <source file="doc/clip-winding-rule.shape">
1185 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clip-winding-rule.shape" -->]]>
1186 </source>
1187 <caption>
1188 <p>When clipping a path with <value name="clip" />, the <em>nonzero winding rule</em> is applied.</p>
1189 </caption>
1190 </example-with-output>
1191 <example-with-output title="Clipping with respect to text" internal-id="example:clip-text">
1192 <image pdf="doc/clip-text_3.pdf" jpg="doc/clip-text_y_big.jpg" />
1193 <source file="doc/clip-text.shape">
1194 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clip-text.shape" -->]]>
1195 </source>
1196 <caption>
1197 <p>Clipping with respect to a text is typically a way of painting that text. Clipping is combined with the effect of painting the text as usual, but as the topmost part of this figure shows, the <em>none</em> rendering mode can be used to do pure clipping.</p>
1198 </caption>
1199 </example-with-output>
1200 </description>
1201 <see-also>
1202 <value name="bboxed" /> <value name="clipodd" /> <value name="winding" />
1203 </see-also>
1204 </case>
1205 </function>
1206 </system-binding>
1208 <system-binding name="clipodd">
1209 <function>
1210 <case constructor-of="Drawable">
1211 <arguments>
1212 <arg identifier="obj">
1213 <type><named-type name="Drawable" /></type>
1214 </arg>
1215 <arg identifier="mask">
1216 <type><named-type name="Path" /></type>
1217 </arg>
1218 </arguments>
1219 <dynamic-references></dynamic-references>
1220 <description>
1221 <p>Clips <arg name="obj" /> according to <arg name="mask" />, applying the <em>even-odd winding rule</em>.</p>
1222 <example-with-output title="Clipping with the even-odd winding rule" internal-id="example:clipodd-winding-rule">
1223 <image pdf="doc/clipodd-winding-rule_3.pdf" jpg="doc/clipodd-winding-rule_y_big.jpg" />
1224 <source file="doc/clipodd-winding-rule.shape">
1225 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clipodd-winding-rule.shape" -->]]>
1226 </source>
1227 <caption>
1228 <p>When clipping a path with <value name="clipodd" />, the <em>even-odd winding rule</em> is applied.</p>
1229 </caption>
1230 </example-with-output>
1231 </description>
1232 <see-also><value name="clip" /> <value name="winding" /></see-also>
1233 </case>
1234 </function>
1235 </system-binding>
1237 <system-binding name="font">
1238 <function>
1239 <case constructor-of="Font">
1240 <arguments>
1241 <arg identifier="family">
1242 <type><named-type name="String" /></type>
1243 </arg>
1244 <arg identifier="style">
1245 <type><named-type name="String" /></type>
1246 <default><value name="void" /></default>
1247 </arg>
1248 <arg identifier="outline">
1249 <type><named-type name="Boolean" /></type>
1250 <default><const-false /></default>
1251 </arg>
1252 </arguments>
1253 <dynamic-references></dynamic-references>
1254 <description>
1255 <p>Locates and loads a font, which can be assigned to <dynamic name="text_font" />. Currently, the only supported font format is TrueType. This function requires the <str-Shapes /> compiler to be built with both FreeType and FontConfig.</p>
1256 <p>The two arguments <arg name="family" /> and <arg name="style" /> are used to point out a particular font. If <arg name="outline" /> is <const-true />, the font will not produce text that references glyphs inside a font program stored in the <str-PDF /> file, but the glyphs will be drawn as filled paths without any connection to characters. Outlining the font has the advantage that no font program needs to be stored in the <str-PDF /> file, but there are several drawbacks:
1257 <ul>
1258 <li>It will not be possible for viewing applications to search or copy the text.</li>
1259 <li>Outlining each glyph may produce bigger files when there is a lot of text.</li>
1260 <li>Outlining may slow down display of the <str-PDF />, and rules out font-rendering techniques that are normally used to enhance the visual appearance of text.</li>
1261 </ul>
1262 Besides these differences, there result should look the same no matter whether fonts are outlined or not. This implies that bounding boxes of outlined fonts are computed exactly as for non-outlined fonts, even though the glyph outlines would allow more “accurate” boxes to be computed.</p>
1263 <p>The font is located using FontConfig, so if <self /> fails to find your font, this is most likely an issue with FontConfig, and not with <str-Shapes />. To check what fonts FontConfig knows about, one can use the command line utility <em>fc-list</em>. For instance, calling <self /> with <arg name="family" /> equal to <em>Santa Fe LET</em>, and not passing anything for <arg name="style" />, should correspond to the command line call
1264 <command-line>
1265 fc-list 'Santa Fe LET':font-format=TrueType
1266 </command-line>
1267 and if <arg name="style" /> was set to <em>Regular</em> (which Santa Fe LET does not provide; the only style is called <em>Plain</em>), that would correspond to
1268 <command-line>
1269 fc-list 'Santa Fe LET':style=Regular:font-format=TrueType
1270 </command-line>
1271 This way, you can experiment with font families and styles in the terminal before trying to select the font in your <str-Shapes /> program.</p>
1272 </description>
1273 <see-also><dynamic name="text_font" /></see-also>
1274 </case>
1275 </function>
1276 </system-binding>
1278 <system-binding name="textmode">
1279 <function>
1280 <case constructor-of="TextRenderingMode">
1281 <arguments>
1282 <arg identifier="fill">
1283 <type><named-type name="Boolean" /></type>
1284 <default><const-false /></default>
1285 </arg>
1286 <arg identifier="stroke">
1287 <type><named-type name="Boolean" /></type>
1288 <default><const-false /></default>
1289 </arg>
1290 </arguments>
1291 <dynamic-references></dynamic-references>
1292 <description>
1293 <p>Constructs a value that specifies a text rendering mode, which can be assigned to <dynamic name="text_rendering" />.</p>
1294 <p>If both arguments are false, the rendering mode will cause the text not to display at all, which is useful when clipping.</p>
1295 </description>
1296 <see-also><dynamic name="text_rendering" /> <value name="clip" /></see-also>
1297 </case>
1298 </function>
1299 </system-binding>
1301 <system-binding name="kerning">
1302 <function>
1303 <case constructor-of="KernedText">
1304 <arguments>
1305 <sink>
1306 <type><union-type><named-type name="String" /><named-type name="Float" /></union-type></type>
1307 </sink>
1308 </arguments>
1309 <dynamic-references></dynamic-references>
1310 <description>
1311 <p>Manual kerning. Each <named-type name="Float" /> value between <named-type name="String" /> values will subtract horizontal distance between the adjacent glyphs when the text is added to a <named-state-type name="Text" /> object. The distance is interpreted in units of the font size.</p>
1312 </description>
1313 <see-also><value name="kern" /></see-also>
1314 </case>
1315 </function>
1316 </system-binding>
1318 <system-binding name="kern">
1319 <function>
1320 <case constructor-of="KernedText">
1321 <arguments>
1322 <sink>
1323 <type><union-type><named-type name="String" /><named-type name="Float" /></union-type></type>
1324 </sink>
1325 </arguments>
1326 <dynamic-references><dynamic name="text_font" /></dynamic-references>
1327 <description>
1328 <p>Interleaves automatically kerned text with manual kernings.</p>
1329 <p>Automatic kerning needs support by the metrics of the current font must, and it is forbidden to call this function unless the current font indicates that kern pairs supported by having its <field name="kerning?" /> field set to <const-true />.</p>
1330 </description>
1331 <see-also><value name="kerning" /></see-also>
1332 </case>
1333 </function>
1334 </system-binding>
1336 <system-binding name="svg_path">
1337 <function>
1338 <case constructor-of="Path">
1339 <arguments>
1340 <arg identifier="d">
1341 <type><named-type name="String" /></type>
1342 </arg>
1343 <arg identifier="xunit">
1344 <type><named-type name="Lenth" /></type>
1345 <default><physical><scalar>1</scalar><unit>bp</unit></physical></default>
1346 </arg>
1347 <arg identifier="yunit">
1348 <type><named-type name="Lenth" /></type>
1349 <default><physical><scalar>1</scalar><unit>bp</unit></physical></default>
1350 </arg>
1351 <arg identifier="multi">
1352 <type><named-type name="Boolean" /></type>
1353 </arg>
1354 <arg identifier="singletons">
1355 <type><named-type name="Boolean" /></type>
1356 <default><const-true /></default>
1357 </arg>
1358 </arguments>
1359 <dynamic-references></dynamic-references>
1360 <description>
1361 <p>Interpret the string <arg name="d" /> as an <str-SVG /> description of a path. Generally, converting coordinates from the <str-SVG /> model to <str-Shapes /> is cumbersome, as it basically requires a drawing area in the <str-Shapes /> world to be defined and related to <str-SVG /> coordinates. However, by disregarding the shift part of the true coordinate transform, only scaling remains to be determined, and for this there is <arg name="xunit" /> and <arg name="yunit" />.</p>
1362 <p>The argument <arg name="multi" /> is optional. If provided, <const-true /> means that a <named-type name="MultiPath" /> will be returned (generally containing several sub paths of type <named-type name="Path" />), and <const-false /> means that there must be exactly one sub path, which will be returned as a <named-type name="Path" />.</p>
1363 <p>If <arg name="singletons" /> is false, paths with zero duration are ignored.</p>
1364 <p>Use this function when you'd rather use a graphical tool to define paths than writing the <str-Shapes /> code by hand. For instance, paths can be created with <a href="http://www.gimp.org/">Gimp</a>, and exported in <str-SVG /> format.</p>
1365 <p>Note that <str-SVG /> graphics is typically located below the origin, while <str-Shapes /> (and <str-PDF />) programs typically locate graphics above the origin. When determining how to shift the returned path, and this is done using <str-SVG /> information, it must be remembered that the <str-SVG /> <eq>y</eq> coordinate is increasing downwards.</p>
1366 </description>
1367 </case>
1368 </function>
1369 </system-binding>
1371 <system-binding name="import">
1372 <function>
1373 <case>
1374 <arguments>
1375 <arg>
1376 <type><named-type name="String" /></type>
1377 </arg>
1378 </arguments>
1379 <result>
1380 <type>
1381 <function-type>
1382 <arguments>
1383 <arg><type><named-type name="Integer" /></type></arg>
1384 </arguments>
1385 <result><named-type name="Drawable" /></result>
1386 </function-type>
1387 </type>
1388 </result>
1389 <dynamic-references></dynamic-references>
1390 <description>
1391 <p>The given string should name a <str-PDF /> file, and the pages of the file will be returned as a vector-function, mapping <eq>0</eq> to the first page in the document, <eq>1</eq> to the second page, and so forth.</p>
1392 <p>Vector functions have a field called <fieldname>size</fieldname> which will give the page count in the document.</p>
1393 </description>
1394 </case>
1395 </function>
1396 </system-binding>
1398 <system-binding name="import_raster">
1399 <function>
1400 <case constructor-of="RasterImage">
1401 <arguments>
1402 <arg identifier="filename">
1403 <type><named-type name="String" /></type>
1404 </arg>
1405 <arg identifier="resolution">
1406 <type><named-type name="Length" /></type>
1407 <default><physical><scalar>1</scalar><unit>bp</unit></physical></default>
1408 </arg>
1409 <arg identifier="override">
1410 <type><named-type name="Boolean" /></type>
1411 <default><const-true /></default>
1412 </arg>
1413 <arg identifier="kind">
1414 <type><named-type name="Symbol" /></type>
1415 <default><value name="void" /></default>
1416 </arg>
1417 </arguments>
1418 <dynamic-references></dynamic-references>
1419 <description>
1420 <p>The argument <arg name="filename" /> should name file with raster image data. If <arg name="kind" /> is <value name="void" />, the file type is inferred from the filename extension. Currently, the only supported formats are <str-PNG /> and <str-JPEG />, which may be selected using the symbols <inline>'PNG</inline> or <inline>'JPEG</inline>.</p>
1421 <p>The length <arg name="resolution" /> is the size of each pixel, both horizontally and vertically, unless <arg name="override" /> is false and the imported file specifies the resolution instead. If <arg name="override" /> is false, but a <str-JPEG /> file only specifies the aspect ratio of the pixels, the resolution will be computed such that the area of each pixel equals the area of a square pixel with side <arg name="resolution" />.</p>
1422 <p>The origin is at the lower left corner of the image. The physical dimensions of the image will be the product of the density and the number of pixels in the corresponding dimensions of the image.</p>
1423 </description>
1424 </case>
1425 </function>
1426 </system-binding>
1428 <system-binding name="facet">
1429 <function>
1430 <case constructor-of="Drawable3D">
1431 <arguments>
1432 <arg identifier="path">
1433 <type><named-type name="Path" /></type>
1434 </arg>
1435 <arg identifier="n1">
1436 <type><template-type name="N" /></type>
1437 </arg>
1438 <arg identifier="n2">
1439 <type><template-type name="N" /></type>
1440 </arg>
1441 <arg identifier="n3">
1442 <type><template-type name="N" /></type>
1443 </arg>
1444 <arg identifier="tiebreaker">
1445 <type><named-type name="Length" /></type>
1446 <default>0</default>
1447 </arg>
1448 <arg identifier="double">
1449 <type><named-type name="Boolean" /></type>
1450 </arg>
1451 </arguments>
1452 <dynamic-references><dynamic name="nonstroking" /> <dynamic name="reflections" /> <dynamic name="autointensity" /> <dynamic name="autoscattering" /> <dynamic name="viewresolution" /> <dynamic name="shadeorder" /></dynamic-references>
1453 <type-templates>
1454 <template name="N">
1455 <description>
1456 <p>Type of surface normal. Should either be <named-type name="SurfaceNormalGray" /> or <named-type name="SurfaceNormalRGB" />.</p>
1457 </description>
1458 </template>
1459 </type-templates>
1460 <description>
1461 <p>The only required argument is <arg name="path" />, which must be a flat polygon. The three arguments of type <template-type name="N" /> will be described shortly. The parameter <arg name="tiebreaker" /> has the same meaning as for <value name="fill" />, and <arg name="double" /> tells whether the surface should be visible when viewed from the back. Surfaces that are not visisble when viewed from the back allow more efficient rendering when they cover a solid body, so that one knows that the inside of the body surface should never be visible. The default value for <arg name="double" /> depends on the presence of surface normals; if there are none, it defaults to true, otherwise it defaults to false unless the surface normals disagree on which is the visible side.</p>
1462 <p>Up to three surface normals may be provided (provide <arg name="n1" /> before <arg name="n2" /> and so forth). A surface normal has a location on the surface and specifies both a normal direction to be used in light computations (although the surface is physically flat, it can be treated as if curved in the light model), and a color. See <value name="facetnormal" /> for more details on how to construct surface normals. If no facet normal is provided, one is computed by using the physical normal direction of <arg name="path" />, with color determined by <dynamic name="nonstroking" />. If just one facet normal is provided, it defines a constant normal direction and color over the whole facet. If more than one is provided, normal direction and color are interpolated over the facet.</p>
1463 <p>Please refer to the documentation on the many dynamic variables accessed by this function, to learn how these affect the light computations.</p>
1464 </description>
1465 </case>
1466 </function>
1467 </system-binding>
1469 <system-binding name="Schur_decomp">
1470 <function>
1471 <case>
1472 <arguments>
1473 <arg identifier="tf">
1474 <type><named-type name="Transform3D" /></type>
1475 </arg>
1476 <arg identifier="rank">
1477 <type><named-type name="Integer" /></type>
1478 </arg>
1479 <arg identifier="canonical">
1480 <type><named-type name="Boolean" /></type>
1481 <default><const-false /></default>
1482 </arg>
1483 </arguments>
1484 <result>
1485 <type>
1486 <structure-type>
1487 <field name="Q"><type><named-type name="Transform3D" /></type></field>
1488 <field name="U"><type><named-type name="Transform3D" /></type></field>
1489 </structure-type>
1490 </type>
1491 </result>
1492 <description>
1493 <p>Computes a rigid body coordinate transform that brings the transform <arg name="tf" /> into a simple form. The linear part of the coordinate transform is given by the real Schur decomposition, ensuring that a real eigenvalue is associated with the third basis vector. (Hence, if there is a 2 by 2 block in the Schur form, it will be in the upper left part.) The translational part of the coordinate transform is computed to make the translational part in the new coordinates small. The <arg name="rank"/> parameter determines how many equation to use when the translational part is computed. If <arg name="rank" /> is not provided, it is determined automatically from singular values. A <arg name="rank" /> of zero means that the translational part of the coordinate transform shall not be used at all. If <arg name="canonical" /> is set, the coordinate transform is made special (that is, it preserves orientation), and if there is an extra degree of freedom in the coodinate transform due to complex eigenvalues in the linear part of <arg name="tf" />, it is used to minimize the angle of rotation in the coordinate transform.</p>
1494 <p>Note that the rank shall <em>not</em> be selected full (that is, <eq>3</eq>) if <arg name="tf" /> is a rigid body transformation; use <eq>2</eq> if the rotation is not close to zero, and <eq>0</eq> otherwise (or use the automatic selection). Compare Chasles' theorem, which says that the new transform will in general have a non-trivial translational part.</p>
1495 <p>This function may be used to find a rotation's eigenvector (that is, the direction of the rotation), as the eigenvector will be in the third column of the linear part of the change of coordinates.
1496 <pre>
1497 tf: [rotate3D angle:25° dir:(1,2,3)]
1498 •stdout << [Schur_decomp tf].Q.Lz
1499 </pre>
1500 </p>
1501 <example-with-output title="Schur decomposition" internal-id="example:schur_decomp">
1502 <source file="doc/schur.blank">
1503 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/schur.blank" -->]]>
1504 </source>
1505 <stdout>
1506 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/schur.stdout" -->]]>
1507 </stdout>
1508 <caption>
1509 <p>The generalization of real Schur decomposition to also include a translation. It can be seen that rank <eq>2</eq> is selected for a rigid body transform with non-trivial rotation. It is also seen that, whithout setting the <arg name="canonical" /> flag, the coordinate transform may not preserve orientation.</p>
1510 </caption>
1511 </example-with-output>
1512 </description>
1513 </case>
1514 </function>
1515 </system-binding>
1517 <system-binding name="error">
1518 <function>
1519 <case>
1520 <arguments>
1521 <arg identifier="kind"><type><named-type name="Symbol" /></type></arg>
1522 <arg identifier="source"><type><named-type name="String" /></type></arg>
1523 <arg identifier="message"><type><named-type name="String" /></type></arg>
1524 <arg identifier="details"><default><value name="void" /></default></arg>
1525 <arg identifier="cause"><default><value name="void" /></default></arg>
1526 </arguments>
1527 <description>
1528 <p>Constructs an <named-type name="Exception" /> located to the point where <self /> was called, and passes it to <escape name="error" />. For most values of <arg name="kind" />, <arg name="cause" /> is not used; when used, it provides additional information used to format <arg name="message" />.</p>
1529 <p>The values of <arg name="kind" /> used by the core (see <named-type name="Exception" />) affect how <arg name="message" /> is formatted, and the value of <arg name="kind" /> must be in agreement with how it is used by the core (with some exceptions explained below).</p>
1530 <p>If <arg name="kind" /> is <inline>'type_mismatch</inline>, the expected type shall be described in <arg name="message" />, and the value causing the error (not a description of its type!) shall be passed in <arg name="cause" />.</p>
1531 </description>
1532 </case>
1533 </function>
1534 </system-binding>
1536 <system-binding name="typeof">
1537 <function>
1538 <case constructor-of="Class">
1539 <arguments>
1540 <arg><type><named-type name="Object" /></type></arg>
1541 </arguments>
1542 <description>
1543 <p>Returns the most specific type of the argument.</p>
1544 </description>
1545 </case>
1546 </function>
1547 </system-binding>
1549 </section>