doc/parts/namespace/Shapes-Graphics3D.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..Graphics3D</namespace>
  24   <description>
  25     <p>Handling the things in a <str-3D /> scene.</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 <str-3D /> graphical object in <str-Shapes /> is basically something that ca be projected to <str-2D />, and then results in a <str-2D /> graphical object.  This namespace is also used for the border between the <str-2D /> and <str-3D /> graphical worlds, so that <namespace name="..Shapes..Graphics" /> doesn't get disturbed by the things that only concern those that work with <str-3D /> scenes.</p>
  40     <p>Separation of <str-2D /> and <str-3D /> concerns in its current form was initiated with the introduction of namespaces in <str-Shapes />, and this separation is still work in progress.  This means that even when working purely in <str-3D />, it is still necessary to use contents of the <namespace name="..Shapes..Graphics" /> namespace from time to time.  The <binding namespace="..Shapes..Graphics" name="stroke" /> function is a typical such example; it still follows the old design where a single function is used for both <str-2D /> and <str-3D />.</p>
  41   </top>
  42
  43   <section id="namespace/shapes/graphics3d/elementary">
  44     <title>Elementary <str-3D /></title>
  45     <body>
  46
  47 <system-binding name="null">
  48   <simple-value>
  49     <type><named-type name="Drawable3D" /></type>
  50     <description>
  51       <p>The analogue of <value namespace="..Shapes..Graphics" name="null" />, but in <str-3D /> instead of <str-2D />.</p>
  52     </description>
  53   </simple-value>
  54 </system-binding>
  55
  56 <system-binding name="newGroup">
  57   <hot>
  58     <constructor-of><named-statetype name="Group3D" /></constructor-of>
  59     <description></description>
  60   </hot>
  61 </system-binding>
  62
  63     </body>
  64   </section> <!-- end of namespace/shapes/graphics3d/elementary -->
  65
  66   <section id="namespace/shapes/graphics3d/facets">
  67     <title>Facets</title>
  68     <body>
  69
  70 <system-binding name="facet">
  71   <function>
  72     <case constructor-of="Drawable3D">
  73       <arguments>
  74         <arg identifier="path">
  75           <type><named-type name="Path" /></type>
  76         </arg>
  77         <arg identifier="n1">
  78           <type><template-type name="N" /></type>
  79         </arg>
  80         <arg identifier="n2">
  81           <type><template-type name="N" /></type>
  82         </arg>
  83         <arg identifier="n3">
  84           <type><template-type name="N" /></type>
  85         </arg>
  86         <arg identifier="tiebreaker">
  87           <type><named-type name="Length" /></type>
  88           <default>0</default>
  89         </arg>
  90         <arg identifier="double">
  91           <type><named-type name="Boolean" /></type>
  92         </arg>
  93       </arguments>
  94       <dynamic-references><dynamic name="nonstroking" /> <dynamic name="reflections" /> <dynamic name="autointensity" /> <dynamic name="autoscattering" /> <dynamic name="viewresolution" /> <dynamic name="shadeorder" /></dynamic-references>
  95       <type-templates>
  96         <template name="N">
  97           <description>
  98             <p>Type of surface normal.  Should either be <named-type name="SurfaceNormalGray" /> or <named-type name="SurfaceNormalRGB" />.</p>
  99           </description>
 100         </template>
 101       </type-templates>
 102       <description>
 103         <p>The only required argument is <arg name="path" />, which must be a flat polygon.  The three arguments of type <template-type name="N" /> will be described shortly.  The parameter <arg name="tiebreaker" /> has the same meaning as for <value namespace="..Shapes..Graphics" 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>
 104         <p>Up to three surface normals may be provided (provide <arg name="n1" /> before <arg name="n2" /> and so forth).  A surface normal has a location on the surface and specifies both a normal direction to be used in light computations (although the surface is physically flat, it can be treated as if curved in the light model), and a color.  See <value name="facetnormal" /> for more details on how to construct surface normals.  If no facet normal is provided, one is computed by using the physical normal direction of <arg name="path" />, with color determined by <dynamic name="nonstroking" />.  If just one facet normal is provided, it defines a constant normal direction and color over the whole facet.  If more than one is provided, normal direction and color are interpolated over the facet.</p>
 105         <p>Please refer to the documentation on the many dynamic variables accessed by this function, to learn how these affect the light computations.</p>
 106       </description>
 107     </case>
 108   </function>
 109 </system-binding>
 110
 111     </body>
 112   </section> <!-- end of namespace/shapes/graphics3d/facets -->
 113
 114   <section id="namespace/shapes/graphics3d/scenes">
 115     <title>Scenes and light</title>
 116     <body>
 117
 118 <system-binding name="newLights">
 119   <hot>
 120     <constructor-of><named-statetype name="Lights" /></constructor-of>
 121     <description></description>
 122   </hot>
 123 </system-binding>
 124
 125 <system-binding name="newZSorter">
 126   <hot>
 127     <constructor-of><named-statetype name="Drawable3D" /></constructor-of>
 128     <description></description>
 129   </hot>
 130 </system-binding>
 131
 132 <system-binding name="newZBuf">
 133   <hot>
 134     <constructor-of><named-statetype name="Drawable3D" /></constructor-of>
 135     <description></description>
 136   </hot>
 137 </system-binding>
 138
 139     </body>
 140   </section> <!-- end of namespace/shapes/graphics3d/scenes -->
 141
 142   <section id="namespace/shapes/graphics3d/quasi">
 143     <title>Quasi <str-3D /></title>
 144     <body>
 145
 146 <system-binding name="facing">
 147   <function>
 148     <case constructor-of="Drawable3D">
 149       <arguments>
 150         <arg identifier="obj">
 151           <type><named-type name="Drawable" /></type>
 152         </arg>
 153         <arg identifier="scale">
 154           <type><named-type name="Boolean" /></type>
 155           <default>false</default>
 156         </arg>
 157         <arg identifier="distort">
 158           <type><named-type name="Boolean" /></type>
 159           <default>false</default>
 160         </arg>
 161       </arguments>
 162       <description>
 163         <p>Make a special kind of <str-3D /> object at <eq>z = 0</eq>, which will always face the viewer even after <str-3D /> transforms.  It is useful for labels and other <str-2D /> annotations that need to be positioned in terms of objects in a <str-3D /> world.</p>
 164         <p>When the object is viewed after being transformed in <str-3D />, it will just be transformed by a <str-2D /> transform, so the object never has to go truly <str-3D />.  The object will be shifted according to how its origin moved by the <str-3D /> transform.  The arguments <arg name="scale" /> and <arg name="distort" /> determine how the linear part of the <str-2D /> transform is obtained from the <str-3D /> transform.  If <arg name="scale" /> is set, the object will be scaled according to the <eq>z</eq> coordinate of its transformed origin.  If <arg name="distort" /> is set, the linear <eq>(x,y)</eq> part of the <str-3D /> transform will be used.</p>
 165       </description>
 166     </case>
 167     <case constructor-of="Drawable3D">
 168       <arguments>
 169         <arg identifier="obj">
 170           <type>
 171             <function-type>
 172               <arguments>
 173                 <arg><type><named-type name="Transform3D" /></type></arg>
 174               </arguments>
 175               <result><named-type name="Drawable" /></result>
 176             </function-type>
 177           </type>
 178         </arg>
 179       </arguments>
 180       <dynamic-references><dynstate name="all" /></dynamic-references>
 181       <description>
 182         <p>Gives the user full control of how to display the object when being viewed through a <str-3D /> transform.  The dynamic state is captured, and will be in scope later when the embedded function is invoked.</p>
 183
 184         <note>
 185           <p>The evaluation order is quite non-standard for the objects created here.  Viewing an object is generally an atomic operation from a continuation passing point of view.  Hence, when the function is applied to the transform to obtain the <str-2D /> result, this will take place in an evaluation loop of its own.  This is very likely to render generated error messages rather useless when it comes to localizing the problem.</p>
 186           <p>Since the object created here only has a meaning when being viewed, it cannot be searched (see <value name="tag" /> and <value name="find" />) for tags as long as it remains in <str-3D />.</p>
 187         </note>
 188
 189         <p>If you ever considered solving the intricate problem of generating nice arrowheads for paths in <str-3D /> by simply treating the path as if it was in <str-2D />, think again, as the example below shows!</p>
 190
 191         <example-with-output title="Example" internal-id="example:facing-function">
 192           <image pdf="features/facefun_3.pdf" jpg="features/facefun_y_big.jpg" />
 193 <source file="features/facefun.shape">
 194 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/facefun.shape" -->]]>
 195 </source>
 196         </example-with-output>
 197       </description>
 198     </case>
 199   </function>
 200   <see-also><value name="immerse" /></see-also>
 201 </system-binding>
 202
 203     </body>
 204   </section> <!-- end of namespace/shapes/graphics3d/quasi -->
 205
 206 </book>