doc/parts/namespace/Shapes-Graphics.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="formats/html.xsl"?>
   3
   4 <!-- This file is part of Shapes.                                           -->
   5 <!--                                                                        -->
   6 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   7 <!-- it under the terms of the GNU General Public License as published by   -->
   8 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   9 <!-- any later version.                                                     -->
  10 <!--                                                                        -->
  11 <!-- Shapes is distributed in the hope that it will be useful,              -->
  12 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  13 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  14 <!-- GNU General Public License for more details.                           -->
  15 <!--                                                                        -->
  16 <!-- You should have received a copy of the GNU General Public License      -->
  17 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  18 <!--                                                                        -->
  19 <!-- Copyright 2015 Henrik Tidefelt                                         -->
  20
  21
  22 <book>
  23   <namespace>..Shapes..Graphics</namespace>
  24   <description>
  25     <p>Handling the things with visual representation on a <str-2D /> canvas.</p>
  26   </description>
  27
  28   <title><self /></title>
  29   <up-link><parent-namespace /></up-link>
  30   <base href=<!--#expand-next-string-->"$(BASE)" />
  31   <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  32   <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  33   <external>
  34     <!--#include virtual="^/toc.xml" -->
  35   </external>
  36
  37   <top>
  38     <alphabetical-index/>
  39     <p>A graphical object in <str-Shapes /> is basically something thay can be drawn on a <str-2D /> canvas.  Many of these objects get created by first working out their geometry using things in <namespace name="..Shapes..Geometry" />, and then stroking or filling to get the graphics.</p>
  40   </top>
  41
  42
  43   <section id="namespace/shapes/graphics/elementary">
  44     <title>Elementary <str-2D /></title>
  45     <body>
  46
  47 <system-binding name="null">
  48   <simple-value>
  49     <type><named-type name="Drawable" /></type>
  50     <description>
  51       <p>An empty <str-2D /> graphics value.  Useful in folds, for instance.</p>
  52     </description>
  53     <see-also>
  54       <value namespace="..Shapes..Graphics3D" name="null" />
  55     </see-also>
  56   </simple-value>
  57 </system-binding>
  58
  59 <system-binding name="newGroup">
  60   <hot>
  61     <constructor-of><named-statetype name="Group" /></constructor-of>
  62     <description></description>
  63   </hot>
  64 </system-binding>
  65
  66     </body>
  67   </section> <!-- end of namespace/shapes/graphics/elementary -->
  68
  69   <section id="namespace/shapes/graphics/pointlike">
  70     <title>Empty and pointlike graphics</title>
  71     <body>
  72
  73 <system-binding name="pointpicture">
  74   <simple-value>
  75     <type><named-type name="Drawable" /></type>
  76     <description>
  77       <p>An invisible <str-2D /> graphics value with a point-like bounding box at the origin.</p>
  78     </description>
  79   </simple-value>
  80 </system-binding>
  81
  82 <system-binding name="spot">
  83   <function>
  84     <case constructor-of="Drawable">
  85       <arguments>
  86         <arg>
  87           <type><named-type name="Coords" /></type>
  88         </arg>
  89       </arguments>
  90       <dynamic-references><dynamic namespace="..Shapes..Traits" name="width" /> <dynamic namespace="..Shapes..Traits" name="stroking" /></dynamic-references>
  91       <description>
  92         <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>
  93         <p>Note that spots can also be made by stroking a closed singelton path with a round cap style.  That is,
  94 <pre>
  95 [spot pt]
  96 </pre>
  97 is equivalent to
  98 <pre>
  99 @cap:CAP_ROUND | [stroke emptypath--pt--cycle]
 100 </pre>
 101         </p>
 102         <p>Also note that using <value name="spot" /> is much more efficient than using <value name="fill" /> on a circular path.</p>
 103         <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>
 104         <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:
 105 <pre>
 106 @cap:CAP_ROUND | [stroke pt--(+(0m,0m))]
 107 </pre>
 108 </p>
 109       </description>
 110       <see-also>
 111         <dynamic name="spot" />
 112       </see-also>
 113     </case>
 114   </function>
 115 </system-binding>
 116
 117 <dynamic-variable name="spot">
 118   <type><named-type name="Drawable" /></type>
 119   <default><inline>dynamic [spot (0m,0m)]</inline></default>
 120   <constraint><em>Cannot be changed!</em></constraint>
 121   <description>
 122     <p>A function call with fixed arguments (or no arguments at all) is like a dynamic variable, and then a dynamic variable is generally preferred over the function call since using a dynamic variable emphasizes the dynamic nature of the expression.  Since the need for a spot at the origin (which can then be transformed to any desired position) is so frequent, this dynamic variable is simply an alternative to calling <value name="spot" /> with the origin as argument.</p>
 123     <p>The value of this dynamic variable will depend on other dynamic variables, compare <value name="spot" />.</p>
 124   </description>
 125 </dynamic-variable>
 126
 127     </body>
 128   </section><!-- End of namespace/shapes/graphics/pointlike -->
 129
 130   <section id="namespace/shapes/graphics/clipping">
 131     <title>Clipping</title>
 132     <body>
 133
 134 <system-binding name="clip">
 135   <function>
 136     <case constructor-of="Drawable">
 137       <arguments>
 138         <arg identifier="obj">
 139           <type><named-type name="Drawable" /></type>
 140         </arg>
 141         <arg identifier="mask">
 142           <type><union-type><named-type name="Path" /><named-type name="Text" /><named-type name="SoftMask" /></union-type></type>
 143         </arg>
 144       </arguments>
 145       <dynamic-references></dynamic-references>
 146       <description>
 147         <p>Clips <arg name="obj" /> according to <arg name="mask" />.</p>
 148         <p>When <arg name="mask" /> is a <named-type name="Path" />, the <em>nonzero winding rule</em> is used.</p>
 149         <p>When <arg name="mask" /> is a <named-type name="Text" />, <str-Shapes /> follows <str-PDF /> with respect to the interpreation of the <dynamic namespace="..Shapes..Text" name="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 namespace="..Shapes..Text" 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>
 150         <p>If the goal is to crop <arg name="obj" /> to control the size of the end result, then <value namespace="..Shapes..Layout" name="bboxed" /> should be used instead.</p>
 151         <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>
 152         <example-with-output title="Clipping with the nonzero winding rule" internal-id="example:clip-winding-rule">
 153           <image pdf="doc/clip-winding-rule_3.pdf" jpg="doc/clip-winding-rule_y_big.jpg" />
 154 <source file="doc/clip-winding-rule.shape">
 155 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clip-winding-rule.shape" -->]]>
 156 </source>
 157 <caption>
 158   <p>When clipping a path with <value name="clip" />, the <em>nonzero winding rule</em> is applied.</p>
 159 </caption>
 160         </example-with-output>
 161         <example-with-output title="Clipping with respect to text" internal-id="example:clip-text">
 162           <image pdf="doc/clip-text_3.pdf" jpg="doc/clip-text_y_big.jpg" />
 163 <source file="doc/clip-text.shape">
 164 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clip-text.shape" -->]]>
 165 </source>
 166 <caption>
 167   <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>
 168 </caption>
 169         </example-with-output>
 170       </description>
 171       <see-also>
 172         <value namespace="..Shapes..Layout" name="bboxed" /> <value name="clipodd" /> <value namespace="..Shapes..Geometry" name="winding" />
 173       </see-also>
 174     </case>
 175   </function>
 176 </system-binding>
 177
 178 <system-binding name="clipodd">
 179   <function>
 180     <case constructor-of="Drawable">
 181       <arguments>
 182         <arg identifier="obj">
 183           <type><named-type name="Drawable" /></type>
 184         </arg>
 185         <arg identifier="mask">
 186           <type><named-type name="Path" /></type>
 187         </arg>
 188       </arguments>
 189       <dynamic-references></dynamic-references>
 190       <description>
 191         <p>Clips <arg name="obj" /> according to <arg name="mask" />, applying the <em>even-odd winding rule</em>.</p>
 192         <example-with-output title="Clipping with the even-odd winding rule" internal-id="example:clipodd-winding-rule">
 193           <image pdf="doc/clipodd-winding-rule_3.pdf" jpg="doc/clipodd-winding-rule_y_big.jpg" />
 194 <source file="doc/clipodd-winding-rule.shape">
 195 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/clipodd-winding-rule.shape" -->]]>
 196 </source>
 197 <caption>
 198   <p>When clipping a path with <value name="clipodd" />, the <em>even-odd winding rule</em> is applied.</p>
 199 </caption>
 200         </example-with-output>
 201       </description>
 202       <see-also><value name="clip" /> <value namespace="..Shapes..Geometry" name="winding" /></see-also>
 203     </case>
 204   </function>
 205 </system-binding>
 206
 207     </body>
 208   </section> <!-- end of namespace/shapes/graphics/clipping -->
 209
 210   <section id="namespace/shapes/graphics/painting">
 211     <title>Painting paths</title>
 212     <body>
 213
 214 <system-binding name="stroke">
 215   <function>
 216     <case constructor-of="Drawable">
 217       <arguments>
 218         <arg identifier="path">
 219           <type><named-type name="Path" /></type>
 220         </arg>
 221         <arg identifier="head">
 222           <default><value name="NO_ARROW" /></default>
 223           <type><named-type name="ArrowHead" /></type>
 224         </arg>
 225         <arg identifier="tail">
 226           <default><value name="NO_ARROW" /></default>
 227           <type><named-type name="ArrowHead" /></type>
 228         </arg>
 229       </arguments>
 230       <dynamic-references><dynamic namespace="..Shapes..Traits" name="width" /> <dynamic namespace="..Shapes..Traits" name="stroking" /> <dynamic name="dash" /> <dynamic name="cap" /> <dynamic name="join" /> <dynamic name="miterlimit" /></dynamic-references>
 231       <description>
 232         <p>Paints the <arg name="path" /> argument by stroking it.  Properties such as color (<dynamic namespace="..Shapes..Traits" name="stroking" />), width, <abbr-etc /> are taken from the dynamic environment.</p>
 233         <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>
 234       </description>
 235     </case>
 236     <case constructor-of="Drawable3D">
 237       <arguments>
 238         <arg identifier="path">
 239           <type><named-type name="Path3D" /></type>
 240         </arg>
 241         <arg identifier="head">
 242           <default><value name="NO_ARROW" /></default>
 243           <type><named-type name="ArrowHead3D" /></type>
 244         </arg>
 245         <arg identifier="tail">
 246           <default><value name="NO_ARROW" /></default>
 247           <type><named-type name="ArrowHead3D" /></type>
 248         </arg>
 249       </arguments>
 250       <dynamic-references><dynamic namespace="..Shapes..Traits" name="width" /> <dynamic namespace="..Shapes..Traits" name="stroking" /> <dynamic name="dash" /> <dynamic name="cap" /> <dynamic name="join" /> <dynamic name="miterlimit" /></dynamic-references>
 251       <description>
 252         <p>Compare with the <str-2D /> case.</p>
 253         <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 namespace="..Shapes..Graphics3D" name="facing" />.</p>
 254       </description>
 255     </case>
 256   </function>
 257 </system-binding>
 258
 259 <system-binding name="fill">
 260   <function>
 261     <case constructor-of="Drawable">
 262       <arguments>
 263         <arg identifier="path">
 264           <type><named-type name="Path" /></type>
 265         </arg>
 266       </arguments>
 267       <dynamic-references><dynamic namespace="..Shapes..Traits" name="nonstroking" /></dynamic-references>
 268       <description>
 269         <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>
 270         <example-with-output title="Filling with the nonzero winding rule" internal-id="example:fill-winding-rule">
 271           <image pdf="doc/fill-winding-rule_3.pdf" jpg="doc/fill-winding-rule_y_big.jpg" />
 272 <source file="doc/fill-winding-rule.shape">
 273 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/fill-winding-rule.shape" -->]]>
 274 </source>
 275 <caption>
 276   <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>
 277 </caption>
 278         </example-with-output>
 279       </description>
 280       <see-also>
 281         <value namespace="..Shapes..Geometry" name="winding" />
 282       </see-also>
 283     </case>
 284     <case constructor-of="Drawable3D">
 285       <arguments>
 286         <arg identifier="path">
 287           <type><named-type name="Path3D" /></type>
 288         </arg>
 289         <arg identifier="tiebreaker">
 290           <default>0</default>
 291           <type><named-type name="Length" /></type>
 292         </arg>
 293       </arguments>
 294       <dynamic-references><dynamic namespace="..Shapes..Traits" name="nonstroking" /></dynamic-references>
 295       <description>
 296         <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 namespace="..Shapes..Traits" name="nonstroking" />.</p>
 297         <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>
 298       </description>
 299     </case>
 300   </function>
 301 </system-binding>
 302
 303 <system-binding name="fillstroke">
 304   <function>
 305     <case constructor-of="Drawable">
 306       <arguments>
 307         <arg identifier="path">
 308           <type><named-type name="Path" /></type>
 309         </arg>
 310         <arg identifier="head">
 311           <default><value name="NO_ARROW" /></default>
 312           <type><named-type name="ArrowHead" /></type>
 313         </arg>
 314         <arg identifier="tail">
 315           <default><value name="NO_ARROW" /></default>
 316           <type><named-type name="ArrowHead" /></type>
 317         </arg>
 318       </arguments>
 319       <dynamic-references><dynamic namespace="..Shapes..Traits" name="stroking" /><dynamic namespace="..Shapes..Traits" name="nonstroking" /></dynamic-references>
 320       <description>
 321         <p>A combination of <value name="fill" /> followed by <value name="stroke" />.</p>
 322       </description>
 323     </case>
 324     <case constructor-of="Drawable3D">
 325       <arguments>
 326         <arg identifier="path">
 327           <type><named-type name="Path3D" /></type>
 328         </arg>
 329         <arg identifier="head">
 330           <default><value name="NO_ARROW" /></default>
 331           <type><named-type name="ArrowHead3D" /></type>
 332         </arg>
 333         <arg identifier="tail">
 334           <default><value name="NO_ARROW" /></default>
 335           <type><named-type name="ArrowHead3D" /></type>
 336         </arg>
 337       </arguments>
 338       <dynamic-references><dynamic namespace="..Shapes..Traits" name="stroking" /><dynamic namespace="..Shapes..Traits" name="nonstroking" /></dynamic-references>
 339       <description>
 340         <p>A combination of <value name="fill" /> followed by <value name="stroke" />.</p>
 341       </description>
 342     </case>
 343   </function>
 344 </system-binding>
 345
 346 <system-binding name="fillodd">
 347   <function>
 348     <case constructor-of="Drawable">
 349       <arguments>
 350         <arg>
 351           <type><named-type name="Path" /></type>
 352         </arg>
 353       </arguments>
 354       <dynamic-references><dynamic namespace="..Shapes..Traits" name="nonstroking" /></dynamic-references>
 355       <description>
 356         <p>Paints the <arg name="path" /> (that shall be closed) argument by filling it with the color <dynamic namespace="..Shapes..Traits" name="nonstroking" />, using the <em>even-odd rule</em>.</p>
 357         <example-with-output title="Filling with the even-odd rule" internal-id="example:fillodd-winding-rule">
 358           <image pdf="doc/fillodd-winding-rule_3.pdf" jpg="doc/fillodd-winding-rule_y_big.jpg" />
 359 <source file="doc/fillodd-winding-rule.shape">
 360 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/fillodd-winding-rule.shape" -->]]>
 361 </source>
 362 <caption>
 363   <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>
 364 </caption>
 365         </example-with-output>
 366       </description>
 367       <see-also>
 368         <value namespace="..Shapes..Geometry" name="winding" />
 369       </see-also>
 370     </case>
 371   </function>
 372 </system-binding>
 373
 374 <system-binding name="NO_ARROW">
 375   <simple-value>
 376     <type><named-type name="ArrowHead" /></type>
 377     <description>
 378       <p>Value that can be passed to <value name="stroke" /> to indicate that no arrowhead shall be drawn.  This special value will be recognized, and handled efficiently.</p>
 379     </description>
 380   </simple-value>
 381 </system-binding>
 382
 383     </body>
 384   </section> <!-- end of namespace/shapes/graphics/painting -->
 385
 386   <section id="namespace/shapes/graphics/externals">
 387     <title>Externally created content</title>
 388     <body>
 389
 390 <system-binding name="TeX">
 391   <function>
 392     <case constructor-of="Drawable">
 393       <arguments>
 394         <arg>
 395           <type><named-type name="String" /></type>
 396         </arg>
 397       </arguments>
 398       <dynamic-references><dynamic namespace="..Shapes..Layout" name="TeX_bleed" /></dynamic-references>
 399       <description>
 400         <p>Sends the string to <str-pdfLateX /> and returns the resulting piece of typeset text.</p>
 401         <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 namespace="..Shapes..Layout" name="TeX_bleed" />, you can at least try to avoid the problem of the final result getting cropped too tight.</p>
 402         <p>If the expression is a string literal, it is handled more efficiently than if the string must be obtained by evaluation.</p>
 403       </description>
 404     </case>
 405   </function>
 406 </system-binding>
 407
 408 <system-binding name="import">
 409   <function>
 410     <case>
 411       <arguments>
 412         <arg>
 413           <type><named-type name="String" /></type>
 414         </arg>
 415       </arguments>
 416       <result>
 417         <type>
 418           <function-type>
 419             <arguments>
 420               <arg><type><named-type name="Integer" /></type></arg>
 421             </arguments>
 422             <result><named-type name="Drawable" /></result>
 423           </function-type>
 424         </type>
 425       </result>
 426       <dynamic-references></dynamic-references>
 427       <description>
 428         <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>
 429         <p>Vector functions have a field called <fieldname>size</fieldname> which will give the page count in the document.</p>
 430       </description>
 431     </case>
 432   </function>
 433 </system-binding>
 434
 435 <system-binding name="import_raster">
 436   <function>
 437     <case constructor-of="RasterImage">
 438       <arguments>
 439         <arg identifier="filename">
 440           <type><named-type name="String" /></type>
 441         </arg>
 442         <arg identifier="resolution">
 443           <type><named-type name="Length" /></type>
 444           <default><physical><scalar>1</scalar><unit>bp</unit></physical></default>
 445         </arg>
 446         <arg identifier="override">
 447           <type><named-type name="Boolean" /></type>
 448           <default><const-true /></default>
 449         </arg>
 450         <arg identifier="kind">
 451           <type><named-type name="Symbol" /></type>
 452           <default><value-the-void /></default>
 453         </arg>
 454       </arguments>
 455       <dynamic-references></dynamic-references>
 456       <description>
 457         <p>The argument <arg name="filename" /> should name file with raster image data.  If <arg name="kind" /> is <value-the-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>
 458         <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>
 459         <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>
 460       </description>
 461     </case>
 462   </function>
 463 </system-binding>
 464
 465     </body>
 466   </section> <!-- end of namespace/shapes/graphics/externals -->
 467
 468 </book>