| blob | 64291984be5b7bf6fd503111c86287e8f59ce638 |
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 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 <binding name="immerse" /> and <binding name="facing" />, and in particular the <arg name="scale" /> and <arg name="distort" /> options to <binding 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 identifier="abs">
33 <function>
34 <top>
35 <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>
36 <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>
37 </top>
38 <case>
39 <arguments>
40 <arg>
41 <type><named-type name="Float" /></type>
42 </arg>
43 </arguments>
44 <result>
45 <type><named-type name="Float" /></type>
46 </result>
47 <dynamic-references></dynamic-references>
48 <description><p>Absolute value.</p></description>
49 </case>
50 <case>
51 <arguments>
52 <arg>
53 <type><named-type name="Integer" /></type>
54 </arg>
55 </arguments>
56 <result>
57 <type><named-type name="Integer" /></type>
58 </result>
59 <dynamic-references></dynamic-references>
60 <description><p>Absolute value.</p></description>
61 </case>
62 <case>
63 <arguments>
64 <arg>
65 <type><named-type name="Length" /></type>
66 </arg>
67 </arguments>
68 <result>
69 <type><named-type name="Length" /></type>
70 </result>
71 <dynamic-references></dynamic-references>
72 <description><p>Unsigned length.</p></description>
73 </case>
74 <case>
75 <arguments>
76 <arg>
77 <type><named-type name="FloatPair" /></type>
78 </arg>
79 </arguments>
80 <result>
81 <type><named-type name="Float" /></type>
82 </result>
83 <dynamic-references></dynamic-references>
84 <description><p>Euclidean norm.</p></description>
85 </case>
86 <case>
87 <arguments>
88 <arg>
89 <type><named-type name="Coords" /></type>
90 </arg>
91 </arguments>
92 <result>
93 <type><named-type name="Length" /></type>
94 </result>
95 <dynamic-references></dynamic-references>
96 <description><p>Euclidean norm.</p></description>
97 </case>
98 <case>
99 <arguments>
100 <arg>
101 <type><named-type name="FloatTriple" /></type>
102 </arg>
103 </arguments>
104 <result>
105 <type><named-type name="Float" /></type>
106 </result>
107 <dynamic-references></dynamic-references>
108 <description><p>Euclidean norm.</p></description>
109 </case>
110 <case>
111 <arguments>
112 <arg>
113 <type><named-type name="Coords3D" /></type>
114 </arg>
115 </arguments>
116 <result>
117 <type><named-type name="Length" /></type>
118 </result>
119 <dynamic-references></dynamic-references>
120 <description><p>Euclidean norm.</p></description>
121 </case>
122 <case>
123 <arguments>
124 <arg>
125 <type><named-type name="Path" /></type>
126 </arg>
127 </arguments>
128 <result>
129 <type><named-type name="Length" /></type>
130 </result>
131 <dynamic-references></dynamic-references>
132 <description><p>Length of path.</p></description>
133 </case>
134 <case>
135 <arguments>
136 <arg>
137 <type><named-type name="Path3D" /></type>
138 </arg>
139 </arguments>
140 <result>
141 <type><named-type name="Length" /></type>
142 </result>
143 <dynamic-references></dynamic-references>
144 <description><p>Length of path.</p></description>
145 </case>
146 <case>
147 <arguments>
148 <arg>
149 <type><named-type name="Dash" /></type>
150 </arg>
151 </arguments>
152 <result>
153 <type><named-type name="Length" /></type>
154 </result>
155 <dynamic-references></dynamic-references>
156 <description><p>Length of dash pattern.</p></description>
157 </case>
158 </function>
159 </system-binding>
161 <system-binding identifier="affinetransform">
162 <function>
163 <case constructor-of="Transform">
164 <arguments>
165 <arg>
166 <type><named-type name="FloatPair" /></type>
167 </arg>
168 <arg>
169 <type><named-type name="FloatPair" /></type>
170 </arg>
171 <arg>
172 <type><named-type name="Coords" /></type>
173 </arg>
174 </arguments>
175 <dynamic-references></dynamic-references>
176 <description><p>Construct transform from multiplier for x and y coordinates, followed by a shift.</p></description>
177 </case>
178 </function>
179 </system-binding>
181 <system-binding identifier="affinetransform3D">
182 <function>
183 <case constructor-of="Transform3D">
184 <arguments>
185 <arg>
186 <type><named-type name="FloatTriple" /></type>
187 </arg>
188 <arg>
189 <type><named-type name="FloatTriple" /></type>
190 </arg>
191 <arg>
192 <type><named-type name="FloatTriple" /></type>
193 </arg>
194 <arg>
195 <type><named-type name="Coords3D" /></type>
196 </arg>
197 </arguments>
198 <dynamic-references></dynamic-references>
199 <description><p>Construct transform from multiplier for x, y, and z coordinates, followed by a shift.</p></description>
200 </case>
201 </function>
202 </system-binding>
204 <system-binding identifier="shift">
205 <function>
206 <case constructor-of="Transform">
207 <arguments>
208 <arg>
209 <type><named-type name="Coords" /></type>
210 </arg>
211 </arguments>
212 <dynamic-references></dynamic-references>
213 <description><p>Construct transform.</p></description>
214 </case>
215 <case constructor-of="Transform3D">
216 <arguments>
217 <arg>
218 <type><named-type name="Coords3D" /></type>
219 </arg>
220 </arguments>
221 <dynamic-references></dynamic-references>
222 <description><p>Construct transform.</p></description>
223 </case>
224 </function>
225 </system-binding>
227 <system-binding identifier="rotate">
228 <function>
229 <case constructor-of="Transform">
230 <arguments>
231 <arg identifier="angle">
232 <type><named-type name="Float" /></type>
233 </arg>
234 </arguments>
235 <dynamic-references></dynamic-references>
236 <description><p>Construct transform.</p></description>
237 </case>
238 </function>
239 </system-binding>
241 <system-binding identifier="rotate3D">
242 <function>
243 <case constructor-of="Transform3D">
244 <arguments>
245 <arg identifier="dir">
246 <type><named-type name="FloatTriple" /></type>
247 </arg>
248 <arg identifier="angle">
249 <type><named-type name="Float" /></type>
250 </arg>
251 </arguments>
252 <dynamic-references></dynamic-references>
253 <description><p>Construct rotation transform about given direction.</p></description>
254 </case>
255 </function>
256 </system-binding>
258 <system-binding identifier="scale">
259 <function>
260 <case constructor-of="Transform">
261 <arguments>
262 <arg identifier="r">
263 <type><named-type name="Float" /></type>
264 <default>1</default>
265 </arg>
266 <arg identifier="x">
267 <type><named-type name="Float" /></type>
268 <default>1</default>
269 </arg>
270 <arg identifier="y">
271 <type><named-type name="Float" /></type>
272 <default>1</default>
273 </arg>
274 </arguments>
275 <dynamic-references></dynamic-references>
276 <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>
277 </case>
278 </function>
279 </system-binding>
281 <system-binding identifier="scale3D">
282 <function>
283 <case constructor-of="Transform3D">
284 <arguments>
285 <arg identifier="r">
286 <type><named-type name="Float" /></type>
287 <default>1</default>
288 </arg>
289 <arg identifier="x">
290 <type><named-type name="Float" /></type>
291 <default>1</default>
292 </arg>
293 <arg identifier="y">
294 <type><named-type name="Float" /></type>
295 <default>1</default>
296 </arg>
297 <arg identifier="z">
298 <type><named-type name="Float" /></type>
299 <default>1</default>
300 </arg>
301 </arguments>
302 <dynamic-references></dynamic-references>
303 <description><p>Construct transform that scales x by <arg name="r" /><char-cdot /><arg name="x" />, and similarly with y and z.</p></description>
304 </case>
305 </function>
306 </system-binding>
308 <system-binding identifier="inverse">
309 <function>
310 <case constructor-of="Transform">
311 <arguments>
312 <arg>
313 <type><named-type name="Transform" /></type>
314 </arg>
315 </arguments>
316 <dynamic-references></dynamic-references>
317 <description><p>Constructs the inverse of a transform. This is only possible if the linear part of the transform is non-singular.</p></description>
318 </case>
319 <case constructor-of="Transform3D">
320 <arguments>
321 <arg>
322 <type><named-type name="Transform3D" /></type>
323 </arg>
324 </arguments>
325 <dynamic-references></dynamic-references>
326 <description><p>Constructs the inverse of a transform. This is only possible if the linear part of the transform is non-singular.</p></description>
327 </case>
328 </function>
329 </system-binding>
331 <system-binding identifier="spot">
332 <function>
333 <case constructor-of="Drawable">
334 <arguments>
335 <arg>
336 <type><named-type name="Coords" /></type>
337 </arg>
338 </arguments>
339 <dynamic-references><dynvar name="width" /> <dynvar name="stroking" /></dynamic-references>
340 <description>
341 <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 <binding name="stroke" />.</p>
342 <p>Note that spots can also be made by stroking a closed singelton path with a round cap style. That is,
343 <pre>
344 [spot pt]
345 </pre>
346 is equivalent to
347 <pre>
348 @cap:CAP_ROUND | [stroke emptypath--pt--cycle]
349 </pre>
350 </p>
351 <p>Also note that using <binding name="spot" /> is much more efficient than using <binding name="fill" /> on a circular path.</p>
352 <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 <binding name="spot" /> using the command line option <a part="man" id="AllowSingletonPaths">--spot-pair=yes</a>, or use <binding name="stroke" /> on a path between two points at the same location instead of using <binding name="spot" />, like so:
353 <pre>
354 @cap:CAP_ROUND | [stroke pt--(+(0m,0m))]
355 </pre>
356 </p>
357 </description>
358 </case>
359 </function>
360 </system-binding>
362 <system-binding identifier="stroke">
363 <function>
364 <case constructor-of="Drawable">
365 <arguments>
366 <arg identifier="path">
367 <type><named-type name="Path" /></type>
368 </arg>
369 <arg identifier="head">
370 <default><binding name="NO_ARROW" /></default>
371 <type><named-type name="ArrowHead" /></type>
372 </arg>
373 <arg identifier="tail">
374 <default><binding name="NO_ARROW" /></default>
375 <type><named-type name="ArrowHead" /></type>
376 </arg>
377 </arguments>
378 <dynamic-references><dynvar name="width" /> <dynvar name="stroking" /> <dynvar name="dash" /> <dynvar name="cap" /> <dynvar name="join" /> <dynvar name="miterlimit" /></dynamic-references>
379 <description>
380 <p>Paints the <arg name="path" /> argument by stroking it. Properties such as color (<dynvar name="stroking" />), width, <abbr-etc /> are taken from the dynamic environment.</p>
381 <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>
382 </description>
383 </case>
384 <case constructor-of="Drawable3D">
385 <arguments>
386 <arg identifier="path">
387 <type><named-type name="Path3D" /></type>
388 </arg>
389 <arg identifier="head">
390 <default><binding name="NO_ARROW" /></default>
391 <type><named-type name="ArrowHead3D" /></type>
392 </arg>
393 <arg identifier="tail">
394 <default><binding name="NO_ARROW" /></default>
395 <type><named-type name="ArrowHead3D" /></type>
396 </arg>
397 </arguments>
398 <dynamic-references><dynvar name="width" /> <dynvar name="stroking" /> <dynvar name="dash" /> <dynvar name="cap" /> <dynvar name="join" /> <dynvar name="miterlimit" /></dynamic-references>
399 <description>
400 <p>Compare with the <str-2D /> case.</p>
401 <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 <binding name="facing" />.</p>
402 </description>
403 </case>
404 </function>
405 </system-binding>
407 <system-binding identifier="fill">
408 <function>
409 <case constructor-of="Drawable">
410 <arguments>
411 <arg identifier="path">
412 <type><named-type name="Path" /></type>
413 </arg>
414 </arguments>
415 <dynamic-references><dynvar name="nonstroking" /></dynamic-references>
416 <description>
417 <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>
418 <example-with-output title="Filling with the nonzero winding rule" internal-id="example/fill-winding-rule">
419 <image pdf="doc/fill-winding-rule_3.pdf" jpg="doc/fill-winding-rule_y_big.jpg" />
420 <source file="doc/fill-winding-rule.shape">
421 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/fill-winding-rule.shape" -->]]>
422 </source>
423 <caption>
424 <p>When filling a path with <binding 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>
425 </caption>
426 </example-with-output>
427 </description>
428 <see-also>
429 <binding name="winding" />
430 </see-also>
431 </case>
432 <case constructor-of="Drawable3D">
433 <arguments>
434 <arg identifier="path">
435 <type><named-type name="Path3D" /></type>
436 </arg>
437 <arg identifier="tiebreaker">
438 <default>0</default>
439 <type><named-type name="Length" /></type>
440 </arg>
441 </arguments>
442 <dynamic-references><dynvar name="nonstroking" /></dynamic-references>
443 <description>
444 <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 <dynvar name="nonstroking" />.</p>
445 <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>
446 </description>
447 </case>
448 </function>
449 </system-binding>
451 <system-binding identifier="fillodd">
452 <function>
453 <case constructor-of="Drawable">
454 <arguments>
455 <arg>
456 <type><named-type name="Path" /></type>
457 </arg>
458 </arguments>
459 <dynamic-references><dynvar name="nonstroking" /></dynamic-references>
460 <description>
461 <p>Paints the <arg name="path" /> (that shall be closed) argument by filling it with the color <dynvar name="nonstroking" />, using the <em>even-odd rule</em>.</p>
462 <example-with-output title="Filling with the even-odd rule" internal-id="example/fillodd-winding-rule">
463 <image pdf="doc/fillodd-winding-rule_3.pdf" jpg="doc/fillodd-winding-rule_y_big.jpg" />
464 <source file="doc/fillodd-winding-rule.shape">
465 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/fillodd-winding-rule.shape" -->]]>
466 </source>
467 <caption>
468 <p>When filling a path with <binding 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>
469 </caption>
470 </example-with-output>
471 </description>
472 <see-also>
473 <binding name="winding" />
474 </see-also>
475 </case>
476 </function>
477 </system-binding>
479 <system-binding identifier="list">
480 <function>
481 <case constructor-of="SingleList">
482 <arguments>
483 <sink>
484 </sink>
485 </arguments>
486 <description>
487 <p>Constructs a list of the arguments.</p>
488 <p>The value created when called with no arguments is recognized by <binding name="null?" />, and should be used as a null marker for <named-type name="ConsPair" /> lists.</p>
489 </description>
490 <see-also><binding name="unlist" /></see-also>
491 </case>
492 </function>
493 </system-binding>
495 <system-binding identifier="unlist">
496 <function>
497 <case constructor-of="Structure">
498 <arguments>
499 <arg>
500 <type><named-type name="SingleList" /></type>
501 </arg>
502 </arguments>
503 <description>
504 <p>Converts a list to a structure, being the inverse of <binding name="list" /> in the sense that
505 <pre>
506 <![CDATA[\ lst → ( list [] <>[unlist lst] )]]>
507 </pre>
508 is the identity for <named-type name="SingleList" /> values, and
509 <pre>
510 <![CDATA[\ struct → [unlist ( list [] <>struct )]]]>
511 </pre>
512 is the identify for <named-type name="Structure" /> values without named parts.</p>
513 <p>Note how this function may be used to define a Scheme-like <inline>apply</inline> function:
514 <pre>
515 <![CDATA[apply: \ fun args → ( fun [] <>[unlist args] )]]>
516 </pre>
517 </p>
518 </description>
519 <see-also><binding name="list" /></see-also>
520 </case>
521 </function>
522 </system-binding>
524 <system-binding identifier="cons">
525 <function>
526 <case constructor-of="ConsPair">
527 <arguments>
528 <arg identifier="car"></arg>
529 <arg identifier="cdr"></arg>
530 </arguments>
531 <description>
532 <p>Constructs a cons pair. The arguments are not forced, which allows infinite data structures to be defined.</p>
533 </description>
534 </case>
535 </function>
536 </system-binding>
538 <system-binding identifier="range">
539 <function>
540 <case constructor-of="SingleList">
541 <arguments>
542 <arg identifier="begin">
543 <type><named-type name="Integer" /></type>
544 </arg>
545 <arg identifier="end">
546 <type><named-type name="Integer" /></type>
547 </arg>
548 <arg identifier="step">
549 <type><named-type name="Integer" /></type>
550 </arg>
551 <arg identifier="count">
552 <type><named-type name="Integer" /></type>
553 </arg>
554 </arguments>
555 <description>
556 <p>Constructs a range of integers. 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>
557 <p>See the float case for the semantics of the various argument combinations.</p>
558 </description>
559 </case>
560 <case constructor-of="SingleList">
561 <arguments>
562 <arg identifier="begin">
563 <type><named-type name="Float" /></type>
564 </arg>
565 <arg identifier="end">
566 <type><named-type name="Float" /></type>
567 </arg>
568 <arg identifier="step">
569 <type><named-type name="Float" /></type>
570 </arg>
571 <arg identifier="count">
572 <type><named-type name="Integer" /></type>
573 </arg>
574 </arguments>
575 <description>
576 <p>Constructs a range of real numbers. 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>
577 <p>If <arg name="step" /> is provided, it determines the step length. If <arg name="count" /> is provided, it must be at least 2, and 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>
578 </description>
579 </case>
580 <case constructor-of="SingleList">
581 <arguments>
582 <arg identifier="begin">
583 <type><named-type name="Length" /></type>
584 </arg>
585 <arg identifier="end">
586 <type><named-type name="Length" /></type>
587 </arg>
588 <arg identifier="step">
589 <type><named-type name="Length" /></type>
590 </arg>
591 <arg identifier="count">
592 <type><named-type name="Integer" /></type>
593 </arg>
594 </arguments>
595 <description>
596 <p>Constructs a range of integers. One of the arguments must be omitted, and it is forbidden to omit both <arg name="step" /> and <arg name="count" />.</p>
597 <p>See the float case for the semantics of the various argument combinations.</p>
598 </description>
599 </case>
600 <body>
601 <example-with-output title="Range construction" internal-id="example/ranges">
602 <source file="features/ranges.shape">
603 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/ranges.shape" -->]]>
604 </source>
605 <stdout>
606 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/ranges.stdout" -->]]>
607 </stdout>
608 </example-with-output>
609 </body>
610 </function>
611 </system-binding>
613 <system-binding identifier="reverse">
614 <function>
615 <case constructor-of="Path">
616 <arguments>
617 <arg>
618 <type><named-type name="Path" /></type>
619 </arg>
620 </arguments>
621 <dynamic-references></dynamic-references>
622 <description>
623 <p>Construct path where the order of pathpoints in the representation is reversed. The constructed path looks identical to the original.</p>
624 </description>
625 </case>
626 <case constructor-of="Path3D">
627 <arguments>
628 <arg>
629 <type><named-type name="Path3D" /></type>
630 </arg>
631 </arguments>
632 <dynamic-references></dynamic-references>
633 <description>
634 <p>Analogous to the the <str-2D /> case.</p>
635 </description>
636 </case>
637 </function>
638 </system-binding>
640 <system-binding identifier="meetpaths">
641 <function>
642 <case constructor-of="Path">
643 <arguments>
644 <arg>
645 <type><named-type name="Path" /></type>
646 </arg>
647 <arg>
648 <type><named-type name="Path" /></type>
649 </arg>
650 </arguments>
651 <dynamic-references></dynamic-references>
652 <description>
653 <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>
654 <p>Hopefully, the example below expresses the idea more clearly.</p>
655 <example-with-output title="Merging paths" internal-id="example/meetpaths">
656 <image pdf="showcase/mergepaths_3.pdf" jpg="showcase/mergepaths_y_big.jpg" />
657 <source file="showcase/mergepaths.shape">
658 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)showcase/mergepaths.shape" -->]]>
659 </source>
660 <caption>
661 <p>Application of <binding name="meetpaths" />. Note that the interesting stuff is found in <a extension="linkpaths" />.</p>
662 </caption>
663 </example-with-output>
664 </description>
665 </case>
666 <case constructor-of="Path3D">
667 <arguments>
668 <arg>
669 <type><named-type name="Path3D" /></type>
670 </arg>
671 <arg>
672 <type><named-type name="Path3D" /></type>
673 </arg>
674 </arguments>
675 <dynamic-references></dynamic-references>
676 <description>
677 <p>Analogous to the the <str-2D /> case.</p>
678 </description>
679 </case>
680 </function>
681 </system-binding>
683 <system-binding identifier="winding">
684 <function>
685 <case>
686 <arguments>
687 <arg identifier="path">
688 <type><named-type name="Path" /></type>
689 </arg>
690 <arg identifier="origin">
691 <type><named-type name="Coords" /></type>
692 </arg>
693 </arguments>
694 <result>
695 <type><named-type name="Integer" /></type>
696 </result>
697 <dynamic-references></dynamic-references>
698 <description>
699 <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>
700 <p>The winding number is used to define filling and clipping.</p>
701 <example-with-output title="Winding numbers" internal-id="example/winding-numbers">
702 <image pdf="doc/winding-numbers_3.pdf" jpg="doc/winding-numbers_y_big.jpg" />
703 <source file="doc/winding-numbers.shape">
704 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/winding-numbers.shape" -->]]>
705 </source>
706 <caption>
707 <p>Winding numbers computed by <binding name="winding" />.</p>
708 </caption>
709 </example-with-output>
710 <example-with-output title="Argument variation integrals" internal-id="example/argument-variation">
711 <image pdf="features/argument_3.pdf" jpg="features/argument_y_big.jpg" />
712 <source file="features/argument.shape">
713 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/argument.shape" -->]]>
714 </source>
715 <caption>
716 <p>Using <binding name="winding" /> to compute the argument variation integral for open paths.</p>
717 </caption>
718 </example-with-output>
719 </description>
720 <see-also>
721 <binding name="fill" /> <binding name="fillodd" /> <binding name="clip" /> <binding name="clipodd" />
722 </see-also>
723 </case>
724 </function>
725 </system-binding>
727 <system-binding identifier="upsample_balance">
728 <function>
729 <case constructor-of="Path">
730 <arguments>
731 <arg>
732 <type><named-type name="Path" /></type>
733 </arg>
734 </arguments>
735 <dynamic-references></dynamic-references>
736 <description>
737 <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>
738 </description>
739 </case>
740 <case constructor-of="Path3D">
741 <arguments>
742 <arg>
743 <type><named-type name="Path3D" /></type>
744 </arg>
745 </arguments>
746 <dynamic-references></dynamic-references>
747 <description>
748 <p>Analogous to the the <str-2D /> case.</p>
749 </description>
750 </case>
751 </function>
752 </system-binding>
754 <system-binding identifier="upsample_inflections">
755 <function>
756 <case constructor-of="Path">
757 <arguments>
758 <arg>
759 <type><named-type name="Path" /></type>
760 </arg>
761 </arguments>
762 <dynamic-references></dynamic-references>
763 <description>
764 <p>Add samples at inflection points.</p>
765 </description>
766 </case>
767 </function>
768 </system-binding>
770 <system-binding identifier="upsample_bends">
771 <function>
772 <case constructor-of="Path">
773 <arguments>
774 <arg identifier="angle">
775 <type><named-type name="Float" /></type>
776 </arg>
777 <arg identifier="path">
778 <type><named-type name="Path" /></type>
779 </arg>
780 </arguments>
781 <dynamic-references></dynamic-references>
782 <description>
783 <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>
784 </description>
785 </case>
786 </function>
787 </system-binding>
789 <system-binding identifier="upsample_every">
790 <function>
791 <case constructor-of="Path">
792 <arguments>
793 <arg identifier="period">
794 <type><named-type name="Length" /></type>
795 </arg>
796 <arg identifier="path">
797 <type><named-type name="Path" /></type>
798 </arg>
799 </arguments>
800 <dynamic-references></dynamic-references>
801 <description>
802 <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>
803 </description>
804 </case>
805 <case constructor-of="Path3D">
806 <arguments>
807 <arg identifier="period">
808 <type><named-type name="Length" /></type>
809 </arg>
810 <arg identifier="path">
811 <type><named-type name="Path3D" /></type>
812 </arg>
813 </arguments>
814 <dynamic-references></dynamic-references>
815 <description>
816 <p>Analogous to the the <str-2D /> case.</p>
817 </description>
818 </case>
819 </function>
820 </system-binding>
822 <system-binding identifier="maximizer">
823 <function>
824 <case constructor-of="PathSlider">
825 <arguments>
826 <arg>
827 <type><named-type name="Path" /></type>
828 </arg>
829 <arg>
830 <type><named-type name="FloatPair" /></type>
831 </arg>
832 </arguments>
833 <dynamic-references></dynamic-references>
834 <description>
835 <p>Finds the first point on the path where the global maximum in the given direction is attained.</p>
836 </description>
837 </case>
838 <case constructor-of="PathSlider3D">
839 <arguments>
840 <arg>
841 <type><named-type name="Path3D" /></type>
842 </arg>
843 <arg>
844 <type><named-type name="FloatTriple" /></type>
845 </arg>
846 </arguments>
847 <dynamic-references></dynamic-references>
848 <description>
849 <p>Analogous to the the <str-2D /> case.</p>
850 </description>
851 </case>
852 </function>
853 </system-binding>
855 <system-binding identifier="pathpoint_maximizer">
856 <function>
857 <case constructor-of="PathSlider">
858 <arguments>
859 <arg>
860 <type><named-type name="Path" /></type>
861 </arg>
862 <arg>
863 <type><named-type name="FloatPair" /></type>
864 </arg>
865 </arguments>
866 <dynamic-references></dynamic-references>
867 <description>
868 <p>Finds the first path point on the path where the global maximum in the given direction is attained.</p>
869 </description>
870 </case>
871 <case constructor-of="PathSlider3D">
872 <arguments>
873 <arg>
874 <type><named-type name="Path3D" /></type>
875 </arg>
876 <arg>
877 <type><named-type name="FloatTriple" /></type>
878 </arg>
879 </arguments>
880 <dynamic-references></dynamic-references>
881 <description>
882 <p>Analogous to the the <str-2D /> case.</p>
883 </description>
884 </case>
885 </function>
886 </system-binding>
888 <system-binding identifier="controlling_maximizer">
889 <function>
890 <case constructor-of="Coords">
891 <arguments>
892 <arg>
893 <type><named-type name="Path" /></type>
894 </arg>
895 <arg>
896 <type><named-type name="FloatPair" /></type>
897 </arg>
898 </arguments>
899 <dynamic-references></dynamic-references>
900 <description>
901 <p>Finds the a point among the control points of the path, where the global maximum in the given direction is attained.</p>
902 </description>
903 </case>
904 <case constructor-of="Coords3D">
905 <arguments>
906 <arg>
907 <type><named-type name="Path3D" /></type>
908 </arg>
909 <arg>
910 <type><named-type name="FloatTriple" /></type>
911 </arg>
912 </arguments>
913 <dynamic-references></dynamic-references>
914 <description>
915 <p>Analogous to the the <str-2D /> case.</p>
916 </description>
917 </case>
918 </function>
919 </system-binding>
921 <system-binding identifier="approximator">
922 <function>
923 <case constructor-of="PathSlider">
924 <arguments>
925 <arg>
926 <type><named-type name="Path" /></type>
927 </arg>
928 <arg>
929 <type><named-type name="Coords" /></type>
930 </arg>
931 </arguments>
932 <dynamic-references></dynamic-references>
933 <description>
934 <p>Finds the first point on the path where the global minimum in distance to the given point is attained.</p>
935 <p>The algorithm and related tolerances are described in <a part="algo-tol" id="algorithm/approximators/point" />.</p>
936 </description>
937 </case>
938 <case constructor-of="PathSlider">
939 <arguments>
940 <arg>
941 <type><named-type name="Path" /></type>
942 </arg>
943 <arg>
944 <type><named-type name="Path" /></type>
945 </arg>
946 </arguments>
947 <dynamic-references></dynamic-references>
948 <description>
949 <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>
950 <p>The algorithm and related tolerances are described in <a part="algo-tol" id="algorithm/approximators/path" />.</p>
951 <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>
952 <structure-fields-table>
953 <title>The <field name="info" /> <named-type name="Structure" /> returned by <binding name="approximator" /></title>
954 <type-field name="dist">
955 <type><named-type name="Length" /></type>
956 <description>Distance between paths at optimum.</description>
957 </type-field>
958 <type-field name="other">
959 <type><named-type name="PathSlider" /></type>
960 <description>The “time” along the second path at optimum.</description>
961 </type-field>
962 </structure-fields-table>
963 </description>
964 </case>
965 <case constructor-of="PathSlider3D">
966 <arguments>
967 <arg>
968 <type><named-type name="Path3D" /></type>
969 </arg>
970 <arg>
971 <type><named-type name="Coords3D" /></type>
972 </arg>
973 </arguments>
974 <dynamic-references></dynamic-references>
975 <description>
976 <p>Analogous to the the <str-2D /> case.</p>
977 </description>
978 </case>
979 <case constructor-of="PathSlider">
980 <arguments>
981 <arg>
982 <type><named-type name="Path3D" /></type>
983 </arg>
984 <arg>
985 <type><named-type name="Path3D" /></type>
986 </arg>
987 </arguments>
988 <dynamic-references></dynamic-references>
989 <description>
990 <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>
991 </description>
992 </case>
993 </function>
994 </system-binding>
996 <system-binding identifier="pathpoint_approximator">
997 <function>
998 <case constructor-of="PathSlider">
999 <arguments>
1000 <arg>
1001 <type><named-type name="Path" /></type>
1002 </arg>
1003 <arg>
1004 <type><named-type name="Coords" /></type>
1005 </arg>
1006 </arguments>
1007 <dynamic-references></dynamic-references>
1008 <description>
1009 <p>Finds the first path point on the path where the global minimum in distance to the given point is attained.</p>
1010 </description>
1011 </case>
1012 <case constructor-of="PathSlider3D">
1013 <arguments>
1014 <arg>
1015 <type><named-type name="Path3D" /></type>
1016 </arg>
1017 <arg>
1018 <type><named-type name="Coords3D" /></type>
1019 </arg>
1020 </arguments>
1021 <dynamic-references></dynamic-references>
1022 <description>
1023 <p>Analogous to the the <str-2D /> case.</p>
1024 </description>
1025 </case>
1026 </function>
1027 </system-binding>
1029 <system-binding identifier="intersection">
1030 <function>
1031 <case constructor-of="PathSlider">
1032 <arguments>
1033 <arg>
1034 <type><named-type name="Path" /></type>
1035 </arg>
1036 <arg>
1037 <type><named-type name="Path" /></type>
1038 </arg>
1039 </arguments>
1040 <dynamic-references><dynvar name="handler_NoIntersection" /></dynamic-references>
1041 <description>
1042 <p>Finds the first point on the first path where it intersects with the second path.</p>
1043 <p>If no intersection is found, the error handler <dynvar name="handler_NoIntersection" /> is called with the two paths as argumets.</p>
1044 <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>
1045 <structure-fields-table>
1046 <title>The <field name="info" /> <named-type name="Structure" /> returned by <binding name="intersection" /></title>
1047 <type-field name="other">
1048 <type><named-type name="PathSlider" /></type>
1049 <description>The “time” of the intersection according to the second path.</description>
1050 </type-field>
1051 </structure-fields-table>
1052 </description>
1053 </case>
1054 </function>
1055 </system-binding>
1057 <system-binding identifier="bbox">
1058 <function>
1059 <case constructor-of="Path">
1060 <arguments>
1061 <arg identifier="obj">
1062 <type><named-type name="Drawable" /></type>
1063 </arg>
1064 <arg identifier="type">
1065 <type><named-type name="Symbol" /></type>
1066 <default><inline>'bounding</inline></default>
1067 </arg>
1068 </arguments>
1069 <dynamic-references></dynamic-references>
1070 <description>
1071 <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>
1072 <p>The allowed values for <arg name="type" /> are { <inline>'bounding</inline>, <inline>'bleed</inline> }.</p>
1073 </description>
1074 <see-also><binding name="bboxed" /></see-also>
1075 </case>
1076 </function>
1077 </system-binding>
1079 <system-binding identifier="bboxed">
1080 <function>
1081 <case constructor-of="Drawable">
1082 <arguments>
1083 <arg identifier="obj">
1084 <type><named-type name="Drawable" /></type>
1085 </arg>
1086 <arg identifier="path">
1087 <type><named-type name="Path" /></type>
1088 </arg>
1089 <arg identifier="type">
1090 <type><named-type name="Symbol" /></type>
1091 <default><inline>'bounding</inline></default>
1092 </arg>
1093 </arguments>
1094 <dynamic-references></dynamic-references>
1095 <description>
1096 <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>
1097 <p>The allowed values for <arg name="type" /> are { <inline>'bounding</inline>, <inline>'bleed</inline>, <inline>'both</inline> }.</p>
1098 <note>
1099 <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>
1100 </note>
1101 </description>
1102 <see-also><binding name="bbox" /> <binding name="clip" /> <binding name="clipodd" /> <binding name="TeX" /></see-also>
1103 </case>
1104 </function>
1105 </system-binding>
1107 <system-binding identifier="clip">
1108 <function>
1109 <case constructor-of="Drawable">
1110 <arguments>
1111 <arg identifier="obj">
1112 <type><named-type name="Drawable" /></type>
1113 </arg>
1114 <arg identifier="mask">
1115 <type><union-type><named-type name="Path" /><named-type name="Text" /><named-type name="SoftMask" /></union-type></type>
1116 </arg>
1117 </arguments>
1118 <dynamic-references></dynamic-references>
1119 <description>
1120 <p>Clips <arg name="obj" /> according to <arg name="mask" />.</p>
1121 <p>When <arg name="mask" /> is a <named-type name="Path" />, the <em>nonzero winding rule</em> is used.</p>
1122 <p>When <arg name="mask" /> is a <named-type name="Text" />, <str-Shapes /> follows <str-PDF /> with respect to the interpreation of the <dynvar 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 <binding 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>
1123 <p>If the goal is to crop <arg name="obj" /> to control the size of the end result, then <binding name="bboxed" /> should be used instead.</p>
1124 <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>
1125 <example-with-output title="Clipping with the nonzero winding rule" internal-id="example/clip-winding-rule">
1126 <image pdf="doc/clip-winding-rule_3.pdf" jpg="doc/clip-winding-rule_y_big.jpg" />
1127 <source file="doc/clip-winding-rule.shape">
1128 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clip-winding-rule.shape" -->]]>
1129 </source>
1130 <caption>
1131 <p>When clipping a path with <binding name="clip" />, the <em>nonzero winding rule</em> is applied.</p>
1132 </caption>
1133 </example-with-output>
1134 <example-with-output title="Clipping with respect to text" internal-id="example/clip-text">
1135 <image pdf="doc/clip-text_3.pdf" jpg="doc/clip-text_y_big.jpg" />
1136 <source file="doc/clip-text.shape">
1137 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clip-text.shape" -->]]>
1138 </source>
1139 <caption>
1140 <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>
1141 </caption>
1142 </example-with-output>
1143 </description>
1144 <see-also>
1145 <binding name="bboxed" /> <binding name="clipodd" /> <binding name="winding" />
1146 </see-also>
1147 </case>
1148 </function>
1149 </system-binding>
1151 <system-binding identifier="clipodd">
1152 <function>
1153 <case constructor-of="Drawable">
1154 <arguments>
1155 <arg identifier="obj">
1156 <type><named-type name="Drawable" /></type>
1157 </arg>
1158 <arg identifier="mask">
1159 <type><named-type name="Path" /></type>
1160 </arg>
1161 </arguments>
1162 <dynamic-references></dynamic-references>
1163 <description>
1164 <p>Clips <arg name="obj" /> according to <arg name="mask" />, applying the <em>even-odd winding rule</em>.</p>
1165 <example-with-output title="Clipping with the even-odd winding rule" internal-id="example/clipodd-winding-rule">
1166 <image pdf="doc/clipodd-winding-rule_3.pdf" jpg="doc/clipodd-winding-rule_y_big.jpg" />
1167 <source file="doc/clipodd-winding-rule.shape">
1168 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clipodd-winding-rule.shape" -->]]>
1169 </source>
1170 <caption>
1171 <p>When clipping a path with <binding name="clipodd" />, the <em>even-odd winding rule</em> is applied.</p>
1172 </caption>
1173 </example-with-output>
1174 </description>
1175 <see-also><binding name="clip" /> <binding name="winding" /></see-also>
1176 </case>
1177 </function>
1178 </system-binding>
1180 <system-binding identifier="textmode">
1181 <function>
1182 <case constructor-of="TextRenderingMode">
1183 <arguments>
1184 <arg identifier="fill">
1185 <type><named-type name="Boolean" /></type>
1186 <default><const-false /></default>
1187 </arg>
1188 <arg identifier="stroke">
1189 <type><named-type name="Boolean" /></type>
1190 <default><const-false /></default>
1191 </arg>
1192 </arguments>
1193 <dynamic-references></dynamic-references>
1194 <description>
1195 <p>Constructs a value that specifies a text rendering mode, which can be assigned to <dynvar name="text_rendering" />.</p>
1196 <p>If both arguments are false, the rendering mode will cause the text not to display at all, which is useful when clipping.</p>
1197 </description>
1198 <see-also><dynvar name="text_rendering" /> <binding name="clip" /></see-also>
1199 </case>
1200 </function>
1201 </system-binding>
1203 <system-binding identifier="svg_path">
1204 <function>
1205 <case constructor-of="Path">
1206 <arguments>
1207 <arg identifier="d">
1208 <type><named-type name="String" /></type>
1209 </arg>
1210 <arg identifier="xunit">
1211 <type><named-type name="Lenth" /></type>
1212 <default><physical><scalar>1</scalar><unit>bp</unit></physical></default>
1213 </arg>
1214 <arg identifier="yunit">
1215 <type><named-type name="Lenth" /></type>
1216 <default><physical><scalar>1</scalar><unit>bp</unit></physical></default>
1217 </arg>
1218 <arg identifier="multi">
1219 <type><named-type name="Boolean" /></type>
1220 </arg>
1221 <arg identifier="singletons">
1222 <type><named-type name="Boolean" /></type>
1223 <default><const-true /></default>
1224 </arg>
1225 </arguments>
1226 <dynamic-references></dynamic-references>
1227 <description>
1228 <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>
1229 <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>
1230 <p>If <arg name="singletons" /> is false, paths with zero duration are ignored.</p>
1231 <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>
1232 <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>
1233 </description>
1234 </case>
1235 </function>
1236 </system-binding>
1238 <system-binding identifier="import">
1239 <function>
1240 <case>
1241 <arguments>
1242 <arg>
1243 <type><named-type name="String" /></type>
1244 </arg>
1245 </arguments>
1246 <result>
1247 <type>
1248 <function-type>
1249 <arguments>
1250 <arg><type><named-type name="Integer" /></type></arg>
1251 </arguments>
1252 <result><named-type name="Drawable" /></result>
1253 </function-type>
1254 </type>
1255 </result>
1256 <dynamic-references></dynamic-references>
1257 <description>
1258 <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>
1259 <p>Vector functions have a field called <fieldname>size</fieldname> which will give the page count in the document.</p>
1260 </description>
1261 </case>
1262 </function>
1263 </system-binding>
1265 <system-binding identifier="import_raster">
1266 <function>
1267 <case constructor-of="RasterImage">
1268 <arguments>
1269 <arg identifier="filename">
1270 <type><named-type name="String" /></type>
1271 </arg>
1272 <arg identifier="resolution">
1273 <type><named-type name="Length" /></type>
1274 <default><physical><scalar>1</scalar><unit>bp</unit></physical></default>
1275 </arg>
1276 <arg identifier="kind">
1277 <type><named-type name="Symbol" /></type>
1278 <default><binding name="void" /></default>
1279 </arg>
1280 </arguments>
1281 <dynamic-references></dynamic-references>
1282 <description>
1283 <p>The argument <arg name="filename" /> should name file with raster image data. If <arg name="kind" /> is <binding name="void" />, the file type is inferred from the filename extension. Currently, the only supported format is <str-PNG />, which may be specified using either of the symbols <inline>'PNG</inline> or <inline>'png</inline>.</p>
1284 <p>The length <arg name="resolution" /> is the size of each pixel, both horizontally and vertically. Hence, the physical dimensions of the image will be the product of <arg name="resolution" /> and the number of pixels in the corresponding dimensions of the image.</p>
1285 <p>The origin is at the lower left corner of the image.</p>
1286 </description>
1287 </case>
1288 </function>
1289 </system-binding>
1291 <system-binding identifier="facet">
1292 <function>
1293 <case constructor-of="Drawable3D">
1294 <arguments>
1295 <arg identifier="path">
1296 <type><named-type name="Path" /></type>
1297 </arg>
1298 <arg identifier="n1">
1299 <type><template-type name="N" /></type>
1300 </arg>
1301 <arg identifier="n2">
1302 <type><template-type name="N" /></type>
1303 </arg>
1304 <arg identifier="n3">
1305 <type><template-type name="N" /></type>
1306 </arg>
1307 <arg identifier="tiebreaker">
1308 <type><named-type name="Length" /></type>
1309 <default>0</default>
1310 </arg>
1311 <arg identifier="double">
1312 <type><named-type name="Boolean" /></type>
1313 </arg>
1314 </arguments>
1315 <dynamic-references><dynvar name="nonstroking" /> <dynvar name="reflections" /> <dynvar name="autointensity" /> <dynvar name="autoscattering" /> <dynvar name="viewresolution" /> <dynvar name="shadeorder" /></dynamic-references>
1316 <type-templates>
1317 <template name="N">
1318 <description>
1319 <p>Type of surface normal. Should either be <named-type name="SurfaceNormalGray" /> or <named-type name="SurfaceNormalRGB" />.</p>
1320 </description>
1321 </template>
1322 </type-templates>
1323 <description>
1324 <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 <binding 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>
1325 <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 <binding 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 <dynvar 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>
1326 <p>Please refer to the documentation on the many dynamic variables accessed by this function, to learn how these affect the light computations.</p>
1327 </description>
1328 </case>
1329 </function>
1330 </system-binding>
1332 <system-binding identifier="Schur_decomp">
1333 <function>
1334 <case>
1335 <arguments>
1336 <arg identifier="tf">
1337 <type><named-type name="Transform3D" /></type>
1338 </arg>
1339 <arg identifier="rank">
1340 <type><named-type name="Integer" /></type>
1341 </arg>
1342 <arg identifier="canonical">
1343 <type><named-type name="Boolean" /></type>
1344 <default><const-false /></default>
1345 </arg>
1346 </arguments>
1347 <result>
1348 <type>
1349 <structure-type>
1350 <field name="Q"><type><named-type name="Transform3D" /></type></field>
1351 <field name="U"><type><named-type name="Transform3D" /></type></field>
1352 </structure-type>
1353 </type>
1354 </result>
1355 <description>
1356 <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>
1357 <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>
1358 <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.
1359 <pre>
1360 tf: [rotate3D angle:25° dir:(1,2,3)]
1361 •stdout << [Schur_decomp tf].Q.Lz
1362 </pre>
1363 </p>
1364 <example-with-output title="Schur decomposition" internal-id="example/schur_decomp">
1365 <source file="doc/schur.shape">
1366 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/schur.shape" -->]]>
1367 </source>
1368 <stdout>
1369 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/schur.stdout" -->]]>
1370 </stdout>
1371 <caption>
1372 <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>
1373 </caption>
1374 </example-with-output>
1375 </description>
1376 </case>
1377 </function>
1378 </system-binding>
1380 <system-binding identifier="error">
1381 <function>
1382 <case>
1383 <arguments>
1384 <arg identifier="kind"><type><named-type name="Symbol" /></type></arg>
1385 <arg identifier="source"><type><named-type name="String" /></type></arg>
1386 <arg identifier="message"><type><named-type name="String" /></type></arg>
1387 <arg identifier="details"><default><binding name="void" /></default></arg>
1388 <arg identifier="cause"><default><binding name="void" /></default></arg>
1389 </arguments>
1390 <description>
1391 <p>Constructs an <named-type name="Exception" /> located to the point where <self /> was called, and passes it to <continuation 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>
1392 <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>
1393 <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>
1394 </description>
1395 </case>
1396 </function>
1397 </system-binding>
1399 </section>