| blob | f29f094a9939dd98e86b2f2ad0b7686225c38c28 |
1 <section id="bindings/functions">
2 <title>Functions</title>
3 <top>
4 <p>These are the functions!</p>
6 <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>
8 <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:
9 </p>
10 <pre>
11 facing: [../facing scale:true distort:true ...]
12 </pre>
13 </top>
15 <system-binding identifier="affinetransform">
16 <function>
17 <case constructor-of="Transform">
18 <arguments>
19 <arg>
20 <type><named-type name="FloatPair" /></type>
21 </arg>
22 <arg>
23 <type><named-type name="FloatPair" /></type>
24 </arg>
25 <arg>
26 <type><named-type name="Coords" /></type>
27 </arg>
28 </arguments>
29 <dynamic-references></dynamic-references>
30 <description>Construct transform from multiplier for x and y coordinates, followed by a shift.</description>
31 </case>
32 </function>
33 </system-binding>
35 <system-binding identifier="affinetransform3D">
36 <function>
37 <case constructor-of="Transform3D">
38 <arguments>
39 <arg>
40 <type><named-type name="FloatTriple" /></type>
41 </arg>
42 <arg>
43 <type><named-type name="FloatTriple" /></type>
44 </arg>
45 <arg>
46 <type><named-type name="FloatTriple" /></type>
47 </arg>
48 <arg>
49 <type><named-type name="Coords3D" /></type>
50 </arg>
51 </arguments>
52 <dynamic-references></dynamic-references>
53 <description>Construct transform from multiplier for x, y, and z coordinates, followed by a shift.</description>
54 </case>
55 </function>
56 </system-binding>
58 <system-binding identifier="shift">
59 <function>
60 <case constructor-of="Transform">
61 <arguments>
62 <arg>
63 <type><named-type name="Coords" /></type>
64 </arg>
65 </arguments>
66 <dynamic-references></dynamic-references>
67 <description>Construct transform.</description>
68 </case>
69 <case constructor-of="Transform3D">
70 <arguments>
71 <arg>
72 <type><named-type name="Coords3D" /></type>
73 </arg>
74 </arguments>
75 <dynamic-references></dynamic-references>
76 <description>Construct transform.</description>
77 </case>
78 </function>
79 </system-binding>
81 <system-binding identifier="rotate">
82 <function>
83 <case constructor-of="Transform">
84 <arguments>
85 <arg identifier="angle">
86 <type><named-type name="Float" /></type>
87 </arg>
88 </arguments>
89 <dynamic-references></dynamic-references>
90 <description>Construct transform.</description>
91 </case>
92 </function>
93 </system-binding>
95 <system-binding identifier="rotate3D">
96 <function>
97 <case constructor-of="Transform3D">
98 <arguments>
99 <arg identifier="dir">
100 <type><named-type name="FloatTriple" /></type>
101 </arg>
102 <arg identifier="angle">
103 <type><named-type name="Float" /></type>
104 </arg>
105 </arguments>
106 <dynamic-references></dynamic-references>
107 <description>Construct rotation transform about given direction.</description>
108 </case>
109 </function>
110 </system-binding>
112 <system-binding identifier="scale">
113 <function>
114 <case constructor-of="Transform">
115 <arguments>
116 <arg identifier="r">
117 <type><named-type name="Float" /></type>
118 <default>1</default>
119 </arg>
120 <arg identifier="x">
121 <type><named-type name="Float" /></type>
122 <default>1</default>
123 </arg>
124 <arg identifier="y">
125 <type><named-type name="Float" /></type>
126 <default>1</default>
127 </arg>
128 </arguments>
129 <dynamic-references></dynamic-references>
130 <description>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" />.</description>
131 </case>
132 </function>
133 </system-binding>
135 <system-binding identifier="scale3D">
136 <function>
137 <case constructor-of="Transform3D">
138 <arguments>
139 <arg identifier="r">
140 <type><named-type name="Float" /></type>
141 <default>1</default>
142 </arg>
143 <arg identifier="x">
144 <type><named-type name="Float" /></type>
145 <default>1</default>
146 </arg>
147 <arg identifier="y">
148 <type><named-type name="Float" /></type>
149 <default>1</default>
150 </arg>
151 <arg identifier="z">
152 <type><named-type name="Float" /></type>
153 <default>1</default>
154 </arg>
155 </arguments>
156 <dynamic-references></dynamic-references>
157 <description>Construct transform that scales x by <arg name="r" /><char-cdot /><arg name="x" />, and similarly with y and z.</description>
158 </case>
159 </function>
160 </system-binding>
162 <system-binding identifier="inverse">
163 <function>
164 <case constructor-of="Transform">
165 <arguments>
166 <arg>
167 <type><named-type name="Transform" /></type>
168 </arg>
169 </arguments>
170 <dynamic-references></dynamic-references>
171 <description>Constructs the inverse of a transform. This is only possible if the linear part of the transform is non-singular.</description>
172 </case>
173 <case constructor-of="Transform3D">
174 <arguments>
175 <arg>
176 <type><named-type name="Transform3D" /></type>
177 </arg>
178 </arguments>
179 <dynamic-references></dynamic-references>
180 <description>Constructs the inverse of a transform. This is only possible if the linear part of the transform is non-singular.</description>
181 </case>
182 </function>
183 </system-binding>
185 <system-binding identifier="spot">
186 <function>
187 <case constructor-of="Drawable">
188 <arguments>
189 <arg>
190 <type><named-type name="Coords" /></type>
191 </arg>
192 </arguments>
193 <dynamic-references><dynvar name="width" /> <dynvar name="stroking" /></dynamic-references>
194 <description>
195 <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>
196 <p>Note that spots can also be made by stroking a closed singelton path with a round cap style. That is,
197 <pre>
198 [spot pt]
199 </pre>
200 is equivalent to
201 <pre>
202 @cap:CAP_ROUND | [stroke emptypath--pt--cycle]
203 </pre>
204 </p>
205 <p>Also note that using <binding name="spot" /> is much more efficient than using <binding name="fill" /> on a circular path.</p>
206 <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:
207 <pre>
208 @cap:CAP_ROUND | [stroke pt--(+(0m,0m))]
209 </pre>
210 </p>
211 </description>
212 </case>
213 </function>
214 </system-binding>
216 <system-binding identifier="stroke">
217 <function>
218 <case constructor-of="Drawable">
219 <arguments>
220 <arg identifier="path">
221 <type><named-type name="Path" /></type>
222 </arg>
223 <arg identifier="head">
224 <default><binding name="NO_ARROW" /></default>
225 <type><named-type name="ArrowHead" /></type>
226 </arg>
227 <arg identifier="tail">
228 <default><binding name="NO_ARROW" /></default>
229 <type><named-type name="ArrowHead" /></type>
230 </arg>
231 </arguments>
232 <dynamic-references><dynvar name="width" /> <dynvar name="stroking" /> <dynvar name="dash" /> <dynvar name="cap" /> <dynvar name="join" /> <dynvar name="miterlimit" /></dynamic-references>
233 <description>
234 <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>
235 <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>
236 </description>
237 </case>
238 <case constructor-of="Drawable3D">
239 <arguments>
240 <arg identifier="path">
241 <type><named-type name="Path3D" /></type>
242 </arg>
243 <arg identifier="head">
244 <default><binding name="NO_ARROW" /></default>
245 <type><named-type name="ArrowHead3D" /></type>
246 </arg>
247 <arg identifier="tail">
248 <default><binding name="NO_ARROW" /></default>
249 <type><named-type name="ArrowHead3D" /></type>
250 </arg>
251 </arguments>
252 <dynamic-references><dynvar name="width" /> <dynvar name="stroking" /> <dynvar name="dash" /> <dynvar name="cap" /> <dynvar name="join" /> <dynvar name="miterlimit" /></dynamic-references>
253 <description>
254 <p>Compare with the <str-2D /> case.</p>
255 <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>
256 </description>
257 </case>
258 </function>
259 </system-binding>
261 <system-binding identifier="fill">
262 <function>
263 <case constructor-of="Drawable">
264 <arguments>
265 <arg identifier="path">
266 <type><named-type name="Path" /></type>
267 </arg>
268 </arguments>
269 <dynamic-references><dynvar name="nonstroking" /></dynamic-references>
270 <description>
271 <p>Paints the <arg name="path" /> (that shall be closed) argument by filling it. The fill color is taken from <dynvar>nonstroking</dynvar>.</p>
272 </description>
273 </case>
274 <case constructor-of="Drawable3D">
275 <arguments>
276 <arg identifier="path">
277 <type><named-type name="Path3D" /></type>
278 </arg>
279 <arg identifier="tiebreaker">
280 <default>0</default>
281 <type><named-type name="Length" /></type>
282 </arg>
283 </arguments>
284 <dynamic-references><dynvar name="nonstroking" /></dynamic-references>
285 <description>
286 <p>Paints the <arg name="path" /> (that shall be closed) argument by filling it. The fill color is taken from <dynvar>nonstroking</dynvar>.</p>
287 </description>
288 </case>
289 </function>
290 </system-binding>
292 <system-binding identifier="list">
293 <function>
294 <case constructor-of="SingleList">
295 <arguments>
296 <sink>
297 </sink>
298 </arguments>
299 <description>
300 <p>Constructs a list of the arguments.</p>
301 <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>
302 </description>
303 </case>
304 </function>
305 </system-binding>
307 <system-binding identifier="cons">
308 <function>
309 <case constructor-of="ConsPair">
310 <arguments>
311 <arg identifier="car"></arg>
312 <arg identifier="cdr"></arg>
313 </arguments>
314 <description>
315 <p>Constructs a cons pair. The arguments are not forced, which allows infinite data structures to be defined.</p>
316 </description>
317 </case>
318 </function>
319 </system-binding>
321 <system-binding identifier="range">
322 <function>
323 <case constructor-of="SingleList">
324 <arguments>
325 <arg identifier="begin">
326 <type><named-type name="Integer" /></type>
327 </arg>
328 <arg identifier="end">
329 <type><named-type name="Integer" /></type>
330 </arg>
331 <arg identifier="step">
332 <type><named-type name="Integer" /></type>
333 </arg>
334 <arg identifier="count">
335 <type><named-type name="Integer" /></type>
336 </arg>
337 </arguments>
338 <description>
339 <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>
340 <p>See the float case for the semantics of the various argument combinations.</p>
341 </description>
342 </case>
343 <case constructor-of="SingleList">
344 <arguments>
345 <arg identifier="begin">
346 <type><named-type name="Float" /></type>
347 </arg>
348 <arg identifier="end">
349 <type><named-type name="Float" /></type>
350 </arg>
351 <arg identifier="step">
352 <type><named-type name="Float" /></type>
353 </arg>
354 <arg identifier="count">
355 <type><named-type name="Integer" /></type>
356 </arg>
357 </arguments>
358 <description>
359 <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>
360 <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>
361 </description>
362 </case>
363 <case constructor-of="SingleList">
364 <arguments>
365 <arg identifier="begin">
366 <type><named-type name="Length" /></type>
367 </arg>
368 <arg identifier="end">
369 <type><named-type name="Length" /></type>
370 </arg>
371 <arg identifier="step">
372 <type><named-type name="Length" /></type>
373 </arg>
374 <arg identifier="count">
375 <type><named-type name="Integer" /></type>
376 </arg>
377 </arguments>
378 <description>
379 <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>
380 <p>See the float case for the semantics of the various argument combinations.</p>
381 </description>
382 </case>
383 <body>
384 <example-with-output title="Range construction" internal-id="example/ranges">
385 <source file="features/ranges.shape">
386 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/ranges.shape" -->]]>
387 </source>
388 <stdout>
389 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/ranges.stdout" -->]]>
390 </stdout>
391 </example-with-output>
392 </body>
393 </function>
394 </system-binding>
396 <system-binding identifier="reverse">
397 <function>
398 <case constructor-of="Path">
399 <arguments>
400 <arg>
401 <type><named-type name="Path" /></type>
402 </arg>
403 </arguments>
404 <dynamic-references></dynamic-references>
405 <description>
406 <p>Construct path where the order of pathpoints in the representation is reversed. The constructed path looks identical to the original.</p>
407 </description>
408 </case>
409 <case constructor-of="Path3D">
410 <arguments>
411 <arg>
412 <type><named-type name="Path3D" /></type>
413 </arg>
414 </arguments>
415 <dynamic-references></dynamic-references>
416 <description>
417 <p>Analogous to the the <str-2D /> case.</p>
418 </description>
419 </case>
420 </function>
421 </system-binding>
423 <system-binding identifier="meetpaths">
424 <function>
425 <case constructor-of="Path">
426 <arguments>
427 <arg>
428 <type><named-type name="Path" /></type>
429 </arg>
430 <arg>
431 <type><named-type name="Path" /></type>
432 </arg>
433 </arguments>
434 <dynamic-references></dynamic-references>
435 <description>
436 <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>
437 <p>Hopefully, the example below expresses the idea more clearly.</p>
438 <example-with-output title="Merging paths" internal-id="example/meetpaths">
439 <image pdf="showcase/mergepaths_3.pdf" jpg="showcase/mergepaths_y_big.jpg" />
440 <source file="showcase/mergepaths.shape">
441 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)showcase/mergepaths.shape" -->]]>
442 </source>
443 <caption>
444 <p>Application of <binding name="meetpaths" />. Note that the interesting stuff is found in <a extension="linkpaths" />.</p>
445 </caption>
446 </example-with-output>
447 </description>
448 </case>
449 <case constructor-of="Path3D">
450 <arguments>
451 <arg>
452 <type><named-type name="Path3D" /></type>
453 </arg>
454 <arg>
455 <type><named-type name="Path3D" /></type>
456 </arg>
457 </arguments>
458 <dynamic-references></dynamic-references>
459 <description>
460 <p>Analogous to the the <str-2D /> case.</p>
461 </description>
462 </case>
463 </function>
464 </system-binding>
466 <system-binding identifier="upsample_balance">
467 <function>
468 <case constructor-of="Path">
469 <arguments>
470 <arg>
471 <type><named-type name="Path" /></type>
472 </arg>
473 </arguments>
474 <dynamic-references></dynamic-references>
475 <description>
476 <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>
477 </description>
478 </case>
479 <case constructor-of="Path3D">
480 <arguments>
481 <arg>
482 <type><named-type name="Path3D" /></type>
483 </arg>
484 </arguments>
485 <dynamic-references></dynamic-references>
486 <description>
487 <p>Analogous to the the <str-2D /> case.</p>
488 </description>
489 </case>
490 </function>
491 </system-binding>
493 <system-binding identifier="upsample_inflections">
494 <function>
495 <case constructor-of="Path">
496 <arguments>
497 <arg>
498 <type><named-type name="Path" /></type>
499 </arg>
500 </arguments>
501 <dynamic-references></dynamic-references>
502 <description>
503 <p>Add samples at inflection points.</p>
504 </description>
505 </case>
506 </function>
507 </system-binding>
509 <system-binding identifier="upsample_bends">
510 <function>
511 <case constructor-of="Path">
512 <arguments>
513 <arg identifier="angle">
514 <type><named-type name="Float" /></type>
515 </arg>
516 <arg identifier="path">
517 <type><named-type name="Path" /></type>
518 </arg>
519 </arguments>
520 <dynamic-references></dynamic-references>
521 <description>
522 <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>
523 </description>
524 </case>
525 </function>
526 </system-binding>
528 <system-binding identifier="upsample_every">
529 <function>
530 <case constructor-of="Path">
531 <arguments>
532 <arg identifier="period">
533 <type><named-type name="Length" /></type>
534 </arg>
535 <arg identifier="path">
536 <type><named-type name="Path" /></type>
537 </arg>
538 </arguments>
539 <dynamic-references></dynamic-references>
540 <description>
541 <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>
542 </description>
543 </case>
544 <case constructor-of="Path3D">
545 <arguments>
546 <arg identifier="period">
547 <type><named-type name="Length" /></type>
548 </arg>
549 <arg identifier="path">
550 <type><named-type name="Path3D" /></type>
551 </arg>
552 </arguments>
553 <dynamic-references></dynamic-references>
554 <description>
555 <p>Analogous to the the <str-2D /> case.</p>
556 </description>
557 </case>
558 </function>
559 </system-binding>
561 <system-binding identifier="maximizer">
562 <function>
563 <case constructor-of="PathSlider">
564 <arguments>
565 <arg>
566 <type><named-type name="Path" /></type>
567 </arg>
568 <arg>
569 <type><named-type name="FloatPair" /></type>
570 </arg>
571 </arguments>
572 <dynamic-references></dynamic-references>
573 <description>
574 <p>Finds the first point on the path where the global maximum in the given direction is attained.</p>
575 </description>
576 </case>
577 <case constructor-of="PathSlider3D">
578 <arguments>
579 <arg>
580 <type><named-type name="Path3D" /></type>
581 </arg>
582 <arg>
583 <type><named-type name="FloatTriple" /></type>
584 </arg>
585 </arguments>
586 <dynamic-references></dynamic-references>
587 <description>
588 <p>Analogous to the the <str-2D /> case.</p>
589 </description>
590 </case>
591 </function>
592 </system-binding>
594 <system-binding identifier="pathpoint_maximizer">
595 <function>
596 <case constructor-of="PathSlider">
597 <arguments>
598 <arg>
599 <type><named-type name="Path" /></type>
600 </arg>
601 <arg>
602 <type><named-type name="FloatPair" /></type>
603 </arg>
604 </arguments>
605 <dynamic-references></dynamic-references>
606 <description>
607 <p>Finds the first path point on the path where the global maximum in the given direction is attained.</p>
608 </description>
609 </case>
610 <case constructor-of="PathSlider3D">
611 <arguments>
612 <arg>
613 <type><named-type name="Path3D" /></type>
614 </arg>
615 <arg>
616 <type><named-type name="FloatTriple" /></type>
617 </arg>
618 </arguments>
619 <dynamic-references></dynamic-references>
620 <description>
621 <p>Analogous to the the <str-2D /> case.</p>
622 </description>
623 </case>
624 </function>
625 </system-binding>
627 <system-binding identifier="controlling_maximizer">
628 <function>
629 <case constructor-of="Coords">
630 <arguments>
631 <arg>
632 <type><named-type name="Path" /></type>
633 </arg>
634 <arg>
635 <type><named-type name="FloatPair" /></type>
636 </arg>
637 </arguments>
638 <dynamic-references></dynamic-references>
639 <description>
640 <p>Finds the a point among the control points of the path, where the global maximum in the given direction is attained.</p>
641 </description>
642 </case>
643 <case constructor-of="Coords3D">
644 <arguments>
645 <arg>
646 <type><named-type name="Path3D" /></type>
647 </arg>
648 <arg>
649 <type><named-type name="FloatTriple" /></type>
650 </arg>
651 </arguments>
652 <dynamic-references></dynamic-references>
653 <description>
654 <p>Analogous to the the <str-2D /> case.</p>
655 </description>
656 </case>
657 </function>
658 </system-binding>
660 <system-binding identifier="approximator">
661 <function>
662 <case constructor-of="PathSlider">
663 <arguments>
664 <arg>
665 <type><named-type name="Path" /></type>
666 </arg>
667 <arg>
668 <type><named-type name="Coords" /></type>
669 </arg>
670 </arguments>
671 <dynamic-references></dynamic-references>
672 <description>
673 <p>Finds the first point on the path where the global minimum in distance to the given point is attained.</p>
674 </description>
675 </case>
676 <case constructor-of="PathSlider3D">
677 <arguments>
678 <arg>
679 <type><named-type name="Path3D" /></type>
680 </arg>
681 <arg>
682 <type><named-type name="Coords3D" /></type>
683 </arg>
684 </arguments>
685 <dynamic-references></dynamic-references>
686 <description>
687 <p>Analogous to the the <str-2D /> case.</p>
688 </description>
689 </case>
690 </function>
691 </system-binding>
693 <system-binding identifier="pathpoint_approximator">
694 <function>
695 <case constructor-of="PathSlider">
696 <arguments>
697 <arg>
698 <type><named-type name="Path" /></type>
699 </arg>
700 <arg>
701 <type><named-type name="Coords" /></type>
702 </arg>
703 </arguments>
704 <dynamic-references></dynamic-references>
705 <description>
706 <p>Finds the first path point on the path where the global minimum in distance to the given point is attained.</p>
707 </description>
708 </case>
709 <case constructor-of="PathSlider3D">
710 <arguments>
711 <arg>
712 <type><named-type name="Path3D" /></type>
713 </arg>
714 <arg>
715 <type><named-type name="Coords3D" /></type>
716 </arg>
717 </arguments>
718 <dynamic-references></dynamic-references>
719 <description>
720 <p>Analogous to the the <str-2D /> case.</p>
721 </description>
722 </case>
723 </function>
724 </system-binding>
726 <system-binding identifier="intersection">
727 <function>
728 <case constructor-of="PathSlider">
729 <arguments>
730 <arg>
731 <type><named-type name="Path" /></type>
732 </arg>
733 <arg>
734 <type><named-type name="Path" /></type>
735 </arg>
736 </arguments>
737 <dynamic-references><dynvar name="handler_NoIntersection" /></dynamic-references>
738 <description>
739 <p>Finds the first point on the first path where it intersects with the second path.</p>
740 <p>If no intersection is found, the error handler <dynvar name="handler_NoIntersection" /> is called with the two paths as argumets.</p>
741 </description>
742 </case>
743 </function>
744 </system-binding>
746 <system-binding identifier="facet">
747 <function>
748 <case constructor-of="Drawable3D">
749 <arguments>
750 <arg identifier="path">
751 <type><named-type name="Path" /></type>
752 </arg>
753 <arg identifier="n1">
754 <type><template-type name="N" /></type>
755 </arg>
756 <arg identifier="n2">
757 <type><template-type name="N" /></type>
758 </arg>
759 <arg identifier="n3">
760 <type><template-type name="N" /></type>
761 </arg>
762 <arg identifier="tiebreaker">
763 <type><named-type name="Length" /></type>
764 <default>0</default>
765 </arg>
766 <arg identifier="double">
767 <type><named-type name="Boolean" /></type>
768 </arg>
769 </arguments>
770 <dynamic-references><dynvar name="nonstroking" /> <dynvar name="reflections" /> <dynvar name="autointensity" /> <dynvar name="autoscattering" /> <dynvar name="viewresolution" /> <dynvar name="shadeorder" /></dynamic-references>
771 <type-templates>
772 <template name="N">
773 <description>
774 <p>Type of surface normal. Should either be <named-type name="SurfaceNormalGray" /> or <named-type name="SurfaceNormalRGB" />.</p>
775 </description>
776 </template>
777 </type-templates>
778 <description>
779 <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>
780 <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>
781 <p>Please refer to the documentation on the many dynamic variables accessed by this function, to learn how these affect the light computations.</p>
782 </description>
783 </case>
784 </function>
785 </system-binding>
788 </section>