doc/parts/extensions/Shapes-Geometry-circle.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 2008, 2014, 2015 Henrik Tidefelt                             -->
  20
  21
  22 <book>
  23   <within-namespace>..Shapes..Geometry</within-namespace>
  24   <extension>circle</extension>
  25   <description>
  26     <p>Functions for construction of circles and circular arcs in <str-2D />.</p>
  27   </description>
  28   <prelude />
  29   <needs></needs>
  30
  31   <title><self /></title>
  32   <meta-selflink><self-href /></meta-selflink>
  33   <up-link><parent-namespace /></up-link>
  34   <base href=<!--#expand-next-string-->"$(BASE)" />
  35   <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  36   <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  37   <external>
  38     <!--#include virtual="^/toc.xml" -->
  39   </external>
  40
  41   <top>
  42     <alphabetical-index/>
  43     <p>It may very well be argued that these bindings should be provided by the core.  Besides a wish to keep the core small (to ease maintenance), one reason not to include these in the core is to remind that constructing circular arcs in use code it really easy.</p>
  44     <p>It should be reminded that circular arcs can only be approximated using cubic splines, so there is no way to define a path perfectly following a circle.</p>
  45   </top>
  46
  47   <body>
  48
  49     <system-binding name="circle">
  50       <summary>Circular path</summary>
  51       <function>
  52         <case constructor-of="Path">
  53           <arguments>
  54             <arg identifier="r">
  55               <type><named-type name="Length" /></type>
  56             </arg>
  57           </arguments>
  58           <dynamic-references></dynamic-references>
  59           <description>
  60             <p>Construct circle in <str-2D /> space, of radius <arg name="r" />, centered at the origin.</p>
  61             <p>The circle is approximated using four spline segments, and for positive radii, it encircles the origin counter-clockwise, starting on the positive x axis.</p>
  62             <p>Use <value name="immerse" /> and <value name="rotate3D" /> to take the circle into <str-3D /> space.</p>
  63           </description>
  64         </case>
  65       </function>
  66     </system-binding>
  67
  68     <system-binding name="ccw_arc">
  69       <summary>Couter-clockwise circular arc</summary>
  70       <function>
  71         <case constructor-of="Path">
  72           <arguments>
  73             <arg identifier="z0">
  74               <type><named-type name="Coords" /></type>
  75             </arg>
  76             <arg identifier="zStart">
  77               <type><named-type name="Coords" /></type>
  78             </arg>
  79             <arg identifier="zEnd">
  80               <type><named-type name="Coords" /></type>
  81             </arg>
  82             <arg identifier="r">
  83               <type><named-type name="Length" /></type>
  84             </arg>
  85           </arguments>
  86           <dynamic-references></dynamic-references>
  87           <description>
  88             <p>Construct circular arc with counter-clockwise direction.</p>
  89             <p>The center point of the circle is <arg name="z0" />, and the radius of the arc is <arg name="r" />.  The arc starts on the ray from <arg name="z0" /> to <arg name="zStart" />, and ends on the ray from <arg name="z0" /> to <arg name="zEnd" />.</p>
  90             <p>See also <value name="..Shapes..Geometry..cw_arc" />.</p>
  91           </description>
  92         </case>
  93       </function>
  94     </system-binding>
  95
  96     <system-binding name="cw_arc">
  97       <summary>Clockwise circular arc</summary>
  98       <function>
  99         <case constructor-of="Path">
 100           <arguments>
 101             <arg identifier="z0">
 102               <type><named-type name="Coords" /></type>
 103             </arg>
 104             <arg identifier="zStart">
 105               <type><named-type name="Coords" /></type>
 106             </arg>
 107             <arg identifier="zEnd">
 108               <type><named-type name="Coords" /></type>
 109             </arg>
 110             <arg identifier="r">
 111               <type><named-type name="Length" /></type>
 112             </arg>
 113           </arguments>
 114           <dynamic-references></dynamic-references>
 115           <description>
 116             <p>Like <value name="..Shapes..Geometry..ccw_arc" />, but creates arcs with clockwise direction.</p>
 117           </description>
 118         </case>
 119       </function>
 120     </system-binding>
 121
 122   </body>
 123 </book>