doc/parts/bindings/3D.sxml

   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 Henrik Tidefelt                                         -->
  17
  18 <section id="bindings/3D">
  19 <title><str-3D /> related stuff</title>
  20 <top>
  21 <p>The bindings that are related to <str-3D /> are kept aside in this section, so that users not interested in <str-3D /> graphics can safely choose not to read this section.</p>
  22 </top>
  23
  24 <system-binding name="view">
  25         <function>
  26                 <case constructor-of="Geometric">
  27                         <arguments>
  28                                 <arg>
  29                                         <type><named-type name="Geometric3D" /></type>
  30                                 </arg>
  31                         </arguments>
  32                         <dynamic-references><dynamic name="eyez" /></dynamic-references>
  33                         <description>
  34                                 <p>Apply pin-hole camera projection.  The geometry of the projection is documented under <dynamic name="eyez" />.</p>
  35                                 <p>Exactly how <str-3D /> objects, if they can at all, behave when being projected, depend on the exact object type.  <named-type name="Drawable3D" /> objects will result in <named-type name="Drawable" /> objects, the operation is generally very complicated if occlusions are to be taken into account.  (What makes it difficult is that <str-Shapes /> deals with scalable graphics, and cannot resort to a pixel <eq>z</eq>-buffer.)  There are three <str-3D /> graphics container types with different behaviors.  First, <named-type name="Group3D" /> takes no consideration of occlusions, and just puts the projections of its part on top of each other in the order in which they appear in the data structure.  The two remaining types tries to respect occlusions, and the reader is referred to the documentation of these types to find out more about their algorithms, see <named-type name="ZBuffer" /> and <named-type name="ZSorter" />.</p>
  36                         </description>
  37                         <see-also><value name="immerse" /></see-also>
  38                 </case>
  39         </function>
  40 </system-binding>
  41
  42 <system-binding name="immerse">
  43         <function>
  44                 <case constructor-of="Geometric3D">
  45                         <arguments>
  46                                 <arg>
  47                                         <type><named-type name="Geometric" /></type>
  48                                 </arg>
  49                         </arguments>
  50                         <dynamic-references></dynamic-references>
  51                         <description>
  52                                 <p>Move object from <str-2D /> to <str-3D /> by equipping it with a <eq>z = 0</eq> coordinate.  The operation is reversed by <value name="view" />.</p>
  53                         </description>
  54                 </case>
  55         </function>
  56         <see-also><value name="view" /> <value name="facing" /></see-also>
  57 </system-binding>
  58
  59 <system-binding name="facing">
  60         <function>
  61                 <case constructor-of="Drawable3D">
  62                         <arguments>
  63                                 <arg identifier="obj">
  64                                         <type><named-type name="Drawable" /></type>
  65                                 </arg>
  66                                 <arg identifier="scale">
  67                                         <type><named-type name="Boolean" /></type>
  68                                         <default>false</default>
  69                                 </arg>
  70                                 <arg identifier="distort">
  71                                         <type><named-type name="Boolean" /></type>
  72                                         <default>false</default>
  73                                 </arg>
  74                         </arguments>
  75                         <description>
  76                                 <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>
  77                                 <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>
  78                         </description>
  79                 </case>
  80                 <case constructor-of="Drawable3D">
  81                         <arguments>
  82                                 <arg identifier="obj">
  83                                         <type>
  84                                                 <function-type>
  85                                                         <arguments>
  86                                                                 <arg><type><named-type name="Transform3D" /></type></arg>
  87                                                         </arguments>
  88                                                         <result><named-type name="Drawable" /></result>
  89                                                 </function-type>
  90                                         </type>
  91                                 </arg>
  92                         </arguments>
  93                         <dynamic-references><dynstate name="all" /></dynamic-references>
  94                         <description>
  95                                 <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>
  96
  97                                 <note>
  98                                         <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>
  99                                         <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>
 100                                 </note>
 101
 102                                 <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>
 103
 104                                 <example-with-output title="Example" internal-id="example:facing-function">
 105                                         <image pdf="features/facefun_3.pdf" jpg="features/facefun_y_big.jpg" />
 106 <source file="features/facefun.shape">
 107 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/facefun.shape" -->]]>
 108 </source>
 109                                 </example-with-output>
 110                         </description>
 111                 </case>
 112         </function>
 113         <see-also><value name="immerse" /></see-also>
 114 </system-binding>
 115
 116
 117 </section>