Startsida Utforska Hjälp
Logga in
godotengine
/
godot
spegling av https://github.com/godotengine/godot/
Bevaka 1
Stjärnmärk 7
Fork 0
Filer Ärenden 1
Träd: d3b42e41b0
Grenar Taggar
godot
/
doc
/
html
/
tutorial01
/
tutorial.html

tutorial.html 45 KB
Historik Rå

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903 
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"  
    2. 

  2.   "http://www.w3.org/TR/html4/loose.dtd">  
    3. 

  3. <html > 
    4. 

  4. <head><title></title> 
    5. 

  5. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 
    6. 

  6. <meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)"> 
    7. 

  7. <meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)"> 
    8. 

  8. <!-- html --> 
    9. 

  9. <meta name="src" content="tutorial.tex"> 
    10. 

  10. <meta name="date" content="2009-10-07 00:28:00"> 
    11. 

  11. <link rel="stylesheet" type="text/css" href="tutorial.css"> 
    12. 

  12. </head><body 
    13. 

  13. >
    14. 

  14.    <h3 class="sectionHead"><span class="titlemark">1   </span> <a 
    15. 

  15.  id="x1-10001"></a>Introduction to 3D Math</h3>
    16. 

  16. <!--l. 27--><p class="noindent" >
    17. 

  17.    <h4 class="subsectionHead"><span class="titlemark">1.1   </span> <a 
    18. 

  18.  id="x1-20001.1"></a>Introduction</h4>
    19. 

  19. <!--l. 29--><p class="noindent" >There are many approaches to understanding the type of 3D math used in video
    20. 

  20. games, modelling, ray-tracing, etc. The usual is through vector algebra, matrices, and
    21. 

  21. linear transformations and, while they are not completely necesary to understand
    22. 

  22. most of the aspects of 3D game programming (from the theorical point of view), they
    23. 

  23. provide a common language to communicate with other programmers or
    24. 

  24. engineers.
    25. 

  25. <!--l. 36--><p class="indent" >   This tutorial will focus on explaining all the basic concepts needed for a
    26. 

  26. programmer to understand how to develop 3D games without getting too deep into
    27. 

  27. algebra. Instead of a math-oriented language, code examples will be given instead
    28. 

  28. when possible. The reason for this is that. while programmers may have
    29. 

  29. different backgrounds or experience (be it scientific, engineering or self taught),
    30. 

  30. code is the most familiar language and the lowest common denominator for
    31. 

  31. understanding.
    32. 

  32. <!--l. 45--><p class="noindent" >
    33. 

  33.    <h4 class="subsectionHead"><span class="titlemark">1.2   </span> <a 
    34. 

  34.  id="x1-30001.2"></a>Vectors</h4>
    35. 

  35. <!--l. 48--><p class="noindent" >
    36. 

  36.    <h5 class="subsubsectionHead"><span class="titlemark">1.2.1   </span> <a 
    37. 

  37.  id="x1-40001.2.1"></a>Brief Introduction</h5>
    38. 

  38. <!--l. 50--><p class="noindent" >When writing 2D games, interfaces and other applications, the typical convention is
    39. 

  39. to define coordinates as an <span 
    40. 

  40. class="ecti-1000">x,y </span>pair, <span 
    41. 

  41. class="ecti-1000">x </span>representing the horizontal offset and <span 
    42. 

  42. class="ecti-1000">y </span>the
    43. 

  43. vertical one. In most cases, the unit for both is <span 
    44. 

  44. class="ecti-1000">pixels</span>. This makes sense given the
    45. 

  45. screen is just a rectangle in two dimensions.
    46. 

  46. <!--l. 56--><p class="indent" >   An <span 
    47. 

  47. class="ecti-1000">x,y </span>pair can be used for two purposes. It can be an absolute position (screen
    48. 

  48. cordinate in the previous case), or a relative direction, if we trace an arrow from the
    49. 

  49. origin (0,0 coordinates) to it&#8217;s position.
    50. 

  50. <div class="center" 
    51. 

  51. >
    52. 

  52. <!--l. 60--><p class="noindent" >
    53. 

  53. 

  54. <div class="tabular">
    55. 

  55.  <table id="TBL-1" class="tabular" 
    56. 

  56. cellspacing="0" cellpadding="0"  
    57. 

  57. ><colgroup id="TBL-1-1g"><col 
    58. 

  58. id="TBL-1-1"><col 
    59. 

  59. id="TBL-1-2"><col 
    60. 

  60. id="TBL-1-3"></colgroup><tr  
    61. 

  61.  style="vertical-align:baseline;" id="TBL-1-1-"><td  style="white-space:nowrap; text-align:center;" id="TBL-1-1-1"  
    62. 

  62. class="td11"><img 
    63. 

  63. src="tutorial0x.png" alt="PIC" class="graphics" width="100.375pt" height="100.375pt" ><!--tex4ht:graphics  
    64. 

  64. name="tutorial0x.png" src="0_home_red_coding_godot_doc_math_position.eps"  
    65. 

  65. --></td><td  style="white-space:nowrap; text-align:center;" id="TBL-1-1-2"  
    66. 

  66. class="td11"></td><td  style="white-space:nowrap; text-align:center;" id="TBL-1-1-3"  
    67. 

  67. class="td11"><img 
    68. 

  68. src="tutorial1x.png" alt="PIC" class="graphics" width="100.375pt" height="100.375pt" ><!--tex4ht:graphics  
    69. 

  69. name="tutorial1x.png" src="1_home_red_coding_godot_doc_math_direction.eps"  
    70. 

  70. --></td>
    71. 

  71. </tr><tr  
    72. 

  72.  style="vertical-align:baseline;" id="TBL-1-2-"><td  style="white-space:nowrap; text-align:center;" id="TBL-1-2-1"  
    73. 

  73. class="td11">         <span 
    74. 

  74. class="ecti-0700">Position                 </span></td><td  style="white-space:nowrap; text-align:center;" id="TBL-1-2-2"  
    75. 

  75. class="td11"></td><td  style="white-space:nowrap; text-align:center;" id="TBL-1-2-3"  
    76. 

  76. class="td11">         <span 
    77. 

  77. class="ecti-0700">Direction               </span></td>
    78. 

  78. </tr><tr  
    79. 

  79.  style="vertical-align:baseline;" id="TBL-1-3-"><td  style="white-space:nowrap; text-align:center;" id="TBL-1-3-1"  
    80. 

  80. class="td11">                        </td>
    81. 

  81. </tr></table></div>
    82. 

  82. </div>
    83. 

  83. <!--l. 67--><p class="indent" >   When used as a direction, this pair is called a <span 
    84. 

  84. class="ecti-1000">vector</span>, and two properties can be
    85. 

  85. observed: The first is the <span 
    86. 

  86. class="ecti-1000">magnitude </span>or <span 
    87. 

  87. class="ecti-1000">length </span>, and the second is the direction. In
    88. 

  88. two dimensions, direction can be an angle. The <span 
    89. 

  89. class="ecti-1000">magnitude </span>or <span 
    90. 

  90. class="ecti-1000">length </span>can be computed
    91. 

  91. by simply using Pithagoras theorem:
    92. 

  92. <div class="center" 
    93. 

  93. >
    94. 

  94. <!--l. 73--><p class="noindent" >
    95. 

  95. <div class="tabular"> <table id="TBL-2" class="tabular" 
    96. 

  96. cellspacing="0" cellpadding="0"  
    97. 

  97. ><colgroup id="TBL-2-1g"><col 
    98. 

  98. id="TBL-2-1"><col 
    99. 

  99. id="TBL-2-2"></colgroup><tr  
    100. 

  100.  style="vertical-align:baseline;" id="TBL-2-1-"><td  style="white-space:nowrap; text-align:center;" id="TBL-2-1-1"  
    101. 

  101. class="td11"><img 
    102. 

  102. src="tutorial2x.png" alt="&#x2218;x2-+-y2-"  class="sqrt" ></td><td  style="white-space:nowrap; text-align:center;" id="TBL-2-1-2"  
    103. 

  103. class="td11"><img 
    104. 

  104. src="tutorial3x.png" alt="&#x2218;x2-+-y2 +-z2"  class="sqrt" ></td>
    105. 

  105. </tr><tr  
    106. 

  106.  style="vertical-align:baseline;" id="TBL-2-2-"><td  style="white-space:nowrap; text-align:center;" id="TBL-2-2-1"  
    107. 

  107. class="td11">   <span 
    108. 

  108. class="ecti-0700">2D      </span></td><td  style="white-space:nowrap; text-align:center;" id="TBL-2-2-2"  
    109. 

  109. class="td11">     <span 
    110. 

  110. class="ecti-0700">3D         </span></td>
    111. 

  111. </tr><tr  
    112. 

  112.  style="vertical-align:baseline;" id="TBL-2-3-"><td  style="white-space:nowrap; text-align:center;" id="TBL-2-3-1"  
    113. 

  113. class="td11">         </td>
    114. 

  114. </tr></table></div>
    115. 

  115. </div>
    116. 

  116. <!--l. 80--><p class="indent" >   The direction can be an arbitrary angle from either the <span 
    117. 

  117. class="ecti-1000">x </span>or <span 
    118. 

  118. class="ecti-1000">y </span>axis, and could be
    119. 

  119. computed by using trigonometry, or just using the usual <span 
    120. 

  120. class="ecti-1000">atan2 </span>function present in
    121. 

  121. most math libraries. However, when dealing with 3D, the direction can&#8217;t be described
    122. 

  122. as an angle. To separate magnitude and direction, 3D uses the concept of <span 
    123. 

  123. class="ecti-1000">normal</span>
    124. 

  124. <span 
    125. 

  125. class="ecti-1000">vectors.</span>
    126. 

  126. <!--l. 88--><p class="noindent" >
    127. 

  127.    <h5 class="subsubsectionHead"><span class="titlemark">1.2.2   </span> <a 
    128. 

  128.  id="x1-50001.2.2"></a>Implementation</h5>
    129. 

  129. <!--l. 90--><p class="noindent" >Vectors are implemented in Godot Engine as a class named <span 
    130. 

  130. class="ecti-1000">Vector3 </span>for 3D, and as
    131. 

  131. both <span 
    132. 

  132. class="ecti-1000">Vector2</span>, <span 
    133. 

  133. class="ecti-1000">Point2 </span>or <span 
    134. 

  134. class="ecti-1000">Size2 </span>in 2D (they are all aliases). They are used for any
    135. 

  135. purpose where a pair of 2D or 3D values (described as <span 
    136. 

  136. class="ecti-1000">x,y </span>or <span 
    137. 

  137. class="ecti-1000">x,y,z) </span>is needed. This is
    138. 

  138. somewhat a standard in most libraries or engines. In the script API, they can be
    139. 

  139. instanced like this:
    140. 

  140.    <!--l. 98-->
    141. 

  141.    <div class="lstlisting"><span class="label"><a 
    142. 

  142.  id="x1-5001r1"></a></span>a&#x00A0;=&#x00A0;Vector3()&#x00A0;<br /><span class="label"><a 
    143. 

  143.  id="x1-5002r2"></a></span>a&#x00A0;=&#x00A0;Vector2(&#x00A0;2.0,&#x00A0;3.4&#x00A0;)
    144. 

  144.    </div>
    145. 

  145. 

  146. <!--l. 104--><p class="indent" >   Vectors also support the common operators <span 
    147. 

  147. class="ecti-1000">+, -, / and * </span>for addition,
    148. 

  148. substraction, multiplication and division.
    149. 

  149.    <!--l. 108-->
    150. 

  150.    <div class="lstlisting"><span class="label"><a 
    151. 

  151.  id="x1-5003r1"></a></span>a&#x00A0;=&#x00A0;Vector3(1,2,3)&#x00A0;<br /><span class="label"><a 
    152. 

  152.  id="x1-5004r2"></a></span>b&#x00A0;=&#x00A0;Vector3(4,5,6)&#x00A0;<br /><span class="label"><a 
    153. 

  153.  id="x1-5005r3"></a></span>c&#x00A0;=&#x00A0;Vector3()&#x00A0;<br /><span class="label"><a 
    154. 

  154.  id="x1-5006r4"></a></span>&#x00A0;<br /><span class="label"><a 
    155. 

  155.  id="x1-5007r5"></a></span>//&#x00A0;writing&#x00A0;<br /><span class="label"><a 
    156. 

  156.  id="x1-5008r6"></a></span>&#x00A0;<br /><span class="label"><a 
    157. 

  157.  id="x1-5009r7"></a></span>c&#x00A0;=&#x00A0;a&#x00A0;+&#x00A0;b&#x00A0;<br /><span class="label"><a 
    158. 

  158.  id="x1-5010r8"></a></span>&#x00A0;<br /><span class="label"><a 
    159. 

  159.  id="x1-5011r9"></a></span>//&#x00A0;is&#x00A0;the&#x00A0;same&#x00A0;as&#x00A0;writing&#x00A0;<br /><span class="label"><a 
    160. 

  160.  id="x1-5012r10"></a></span>&#x00A0;<br /><span class="label"><a 
    161. 

  161.  id="x1-5013r11"></a></span>c.x&#x00A0;=&#x00A0;a.x&#x00A0;+&#x00A0;b.x&#x00A0;<br /><span class="label"><a 
    162. 

  162.  id="x1-5014r12"></a></span>c.y&#x00A0;=&#x00A0;a.y&#x00A0;+&#x00A0;b.y&#x00A0;<br /><span class="label"><a 
    163. 

  163.  id="x1-5015r13"></a></span>c.z&#x00A0;=&#x00A0;a.z&#x00A0;+&#x00A0;b.z&#x00A0;<br /><span class="label"><a 
    164. 

  164.  id="x1-5016r14"></a></span>&#x00A0;<br /><span class="label"><a 
    165. 

  165.  id="x1-5017r15"></a></span>//&#x00A0;both&#x00A0;will&#x00A0;result&#x00A0;in&#x00A0;a&#x00A0;vector&#x00A0;containing&#x00A0;(5,7,9).&#x00A0;<br /><span class="label"><a 
    166. 

  166.  id="x1-5018r16"></a></span>//&#x00A0;the&#x00A0;same&#x00A0;happens&#x00A0;for&#x00A0;the&#x00A0;rest&#x00A0;of&#x00A0;the&#x00A0;operators.
    167. 

  167.    </div>
    168. 

  168. <!--l. 128--><p class="indent" >   Vectors also can perform a wide variety of built-in functions, their most common
    169. 

  169. usages will be explored next.
    170. 

  170. <!--l. 132--><p class="noindent" >
    171. 

  171.    <h5 class="subsubsectionHead"><span class="titlemark">1.2.3   </span> <a 
    172. 

  172.  id="x1-60001.2.3"></a>Normal Vectors</h5>
    173. 

  173. <!--l. 134--><p class="noindent" >Two points ago, it was mentioned that 3D vectors can&#8217;t describe their direction as an
    174. 

  174. agle (as 2D vectors can). Because of this, <span 
    175. 

  175. class="ecti-1000">normal vectors </span>become important for
    176. 

  176. separating a vector between <span 
    177. 

  177. class="ecti-1000">direction </span>and <span 
    178. 

  178. class="ecti-1000">magnitude.</span>
    179. 

  179. <!--l. 139--><p class="indent" >   A <span 
    180. 

  180. class="ecti-1000">normal vector </span>is a vector with a <span 
    181. 

  181. class="ecti-1000">magnitude </span>of <span 
    182. 

  182. class="ecti-1000">1. </span>This means, no matter where
    183. 

  183. the vector is pointing to, it&#8217;s length is always <span 
    184. 

  184. class="ecti-1000">1</span>.
    185. 

  185.    <div class="tabular">
    186. 

  186.  <table id="TBL-3" class="tabular" 
    187. 

  187. cellspacing="0" cellpadding="0"  
    188. 

  188. ><colgroup id="TBL-3-1g"><col 
    189. 

  189. id="TBL-3-1"></colgroup><tr  
    190. 

  190.  style="vertical-align:baseline;" id="TBL-3-1-"><td  style="white-space:nowrap; text-align:center;" id="TBL-3-1-1"  
    191. 

  191. class="td11"><img 
    192. 

  192. src="tutorial4x.png" alt="PIC" class="graphics" width="100.375pt" height="100.375pt" ><!--tex4ht:graphics  
    193. 

  193. name="tutorial4x.png" src="2_home_red_coding_godot_doc_math_normals.eps"  
    194. 

  194. --></td>
    195. 

  195. </tr><tr  
    196. 

  196.  style="vertical-align:baseline;" id="TBL-3-2-"><td  style="white-space:nowrap; text-align:center;" id="TBL-3-2-1"  
    197. 

  197. class="td11"> <span 
    198. 

  198. class="ecrm-0700">Normal vectors aroud the origin.   </span></td>
    199. 

  199. </tr><tr  
    200. 

  200.  style="vertical-align:baseline;" id="TBL-3-3-"><td  style="white-space:nowrap; text-align:center;" id="TBL-3-3-1"  
    201. 

  201. class="td11">                        </td> </tr></table>
    202. 

  202. </div>
    203. 

  203. <!--l. 148--><p class="indent" >   Normal vectors have endless uses in 3D graphics programming, so it&#8217;s
    204. 

  204. recommended to get familiar with them as much as possible.
    205. 

  205. <!--l. 152--><p class="noindent" >
    206. 

  206.    <h5 class="subsubsectionHead"><span class="titlemark">1.2.4   </span> <a 
    207. 

  207.  id="x1-70001.2.4"></a>Normalization</h5>
    208. 

  208. <!--l. 154--><p class="noindent" >Normalization is the process through which normal vectors are obtained
    209. 

  209. from regular vectors. In other words, normalization is used to reduce the
    210. 

  210. <span 
    211. 

  211. class="ecti-1000">magnitude </span>of any vector to <span 
    212. 

  212. class="ecti-1000">1</span>. (except of course, unless the vector is (0,0,0)
    213. 

  213. ).
    214. 

  214. <!--l. 159--><p class="indent" >   To normalize a vector, it must be divided by its magnitude (which should be
    215. 

  215. greater than zero):
    216. 

  216.    <!--l. 163-->
    217. 

  217.    <div class="lstlisting"><span class="label"><a 
    218. 

  218.  id="x1-7001r1"></a></span><span 
    219. 

  219. class="ecti-1000">//</span><span 
    220. 

  220. class="ecti-1000">&#x00A0;</span><span 
    221. 

  221. class="ecti-1000">a</span><span 
    222. 

  222. class="ecti-1000">&#x00A0;</span><span 
    223. 

  223. class="ecti-1000">custom</span><span 
    224. 

  224. class="ecti-1000">&#x00A0;</span><span 
    225. 

  225. class="ecti-1000">vector</span><span 
    226. 

  226. class="ecti-1000">&#x00A0;</span><span 
    227. 

  227. class="ecti-1000">is</span><span 
    228. 

  228. class="ecti-1000">&#x00A0;</span><span 
    229. 

  229. class="ecti-1000">created</span>&#x00A0;<br /><span class="label"><a 
    230. 

  230.  id="x1-7002r2"></a></span>a&#x00A0;=&#x00A0;Vector3(4,5,6)&#x00A0;<br /><span class="label"><a 
    231. 

  231.  id="x1-7003r3"></a></span><span 
    232. 

  232. class="ecti-1000">//</span><span 
    233. 

  233. class="ecti-1000">&#x00A0;</span><span 
    234. 

  234. class="ecti-1000">&#8217;</span><span 
    235. 

  235. class="ecti-1000">l</span><span 
    236. 

  236. class="ecti-1000">&#8217;</span><span 
    237. 

  237. class="ecti-1000">&#x00A0;</span><span 
    238. 

  238. class="ecti-1000">is</span><span 
    239. 

  239. class="ecti-1000">&#x00A0;</span><span 
    240. 

  240. class="ecti-1000">a</span><span 
    241. 

  241. class="ecti-1000">&#x00A0;</span><span 
    242. 

  242. class="ecti-1000">single</span><span 
    243. 

  243. class="ecti-1000">&#x00A0;</span><span 
    244. 

  244. class="ecti-1000">real</span><span 
    245. 

  245. class="ecti-1000">&#x00A0;</span><span 
    246. 

  246. class="ecti-1000">number</span><span 
    247. 

  247. class="ecti-1000">&#x00A0;</span><span 
    248. 

  248. class="ecti-1000">(</span><span 
    249. 

  249. class="ecti-1000">or</span><span 
    250. 

  250. class="ecti-1000">&#x00A0;</span><span 
    251. 

  251. class="ecti-1000">scalar</span><span 
    252. 

  252. class="ecti-1000">)</span><span 
    253. 

  253. class="ecti-1000">&#x00A0;</span><span 
    254. 

  254. class="ecti-1000">containight</span><span 
    255. 

  255. class="ecti-1000">&#x00A0;</span><span 
    256. 

  256. class="ecti-1000">the</span><span 
    257. 

  257. class="ecti-1000">&#x00A0;</span><span 
    258. 

  258. class="ecti-1000">length</span>&#x00A0;<br /><span class="label"><a 
    259. 

  259.  id="x1-7004r4"></a></span>l&#x00A0;=&#x00A0;Math.sqrt(&#x00A0;a.x<span 
    260. 

  260. class="cmsy-10">*</span>a.x&#x00A0;+&#x00A0;a.y<span 
    261. 

  261. class="cmsy-10">*</span>a.y&#x00A0;+&#x00A0;a.z<span 
    262. 

  262. class="cmsy-10">*</span>a.z&#x00A0;)&#x00A0;<br /><span class="label"><a 
    263. 

  263.  id="x1-7005r5"></a></span><span 
    264. 

  264. class="ecti-1000">//</span><span 
    265. 

  265. class="ecti-1000">&#x00A0;</span><span 
    266. 

  266. class="ecti-1000">the</span><span 
    267. 

  267. class="ecti-1000">&#x00A0;</span><span 
    268. 

  268. class="ecti-1000">vector</span><span 
    269. 

  269. class="ecti-1000">&#x00A0;</span><span 
    270. 

  270. class="ecti-1000">&#8217;</span><span 
    271. 

  271. class="ecti-1000">a</span><span 
    272. 

  272. class="ecti-1000">&#8217;</span><span 
    273. 

  273. class="ecti-1000">&#x00A0;</span><span 
    274. 

  274. class="ecti-1000">is</span><span 
    275. 

  275. class="ecti-1000">&#x00A0;</span><span 
    276. 

  276. class="ecti-1000">divided</span><span 
    277. 

  277. class="ecti-1000">&#x00A0;</span><span 
    278. 

  278. class="ecti-1000">by</span><span 
    279. 

  279. class="ecti-1000">&#x00A0;</span><span 
    280. 

  280. class="ecti-1000">its</span><span 
    281. 

  281. class="ecti-1000">&#x00A0;</span><span 
    282. 

  282. class="ecti-1000">length</span><span 
    283. 

  283. class="ecti-1000">,</span><span 
    284. 

  284. class="ecti-1000">&#x00A0;</span><span 
    285. 

  285. class="ecti-1000">by</span><span 
    286. 

  286. class="ecti-1000">&#x00A0;</span><span 
    287. 

  287. class="ecti-1000">performing</span><span 
    288. 

  288. class="ecti-1000">&#x00A0;</span><span 
    289. 

  289. class="ecti-1000">scalar</span><span 
    290. 

  290. class="ecti-1000">&#x00A0;</span><span 
    291. 

  291. class="ecti-1000">divide</span>&#x00A0;<br /><span class="label"><a 
    292. 

  292.  id="x1-7006r6"></a></span>a&#x00A0;=&#x00A0;a&#x00A0;/&#x00A0;l&#x00A0;<br /><span class="label"><a 
    293. 

  293.  id="x1-7007r7"></a></span><span 
    294. 

  294. class="ecti-1000">//</span><span 
    295. 

  295. class="ecti-1000">&#x00A0;</span><span 
    296. 

  296. class="ecti-1000">which</span><span 
    297. 

  297. class="ecti-1000">&#x00A0;</span><span 
    298. 

  298. class="ecti-1000">is</span><span 
    299. 

  299. class="ecti-1000">&#x00A0;</span><span 
    300. 

  300. class="ecti-1000">the</span><span 
    301. 

  301. class="ecti-1000">&#x00A0;</span><span 
    302. 

  302. class="ecti-1000">same</span><span 
    303. 

  303. class="ecti-1000">&#x00A0;</span><span 
    304. 

  304. class="ecti-1000">as</span>&#x00A0;<br /><span class="label"><a 
    305. 

  305.  id="x1-7008r8"></a></span>a.x&#x00A0;=&#x00A0;a.x&#x00A0;/&#x00A0;l&#x00A0;<br /><span class="label"><a 
    306. 

  306.  id="x1-7009r9"></a></span>a.y&#x00A0;=&#x00A0;a.y&#x00A0;/&#x00A0;l&#x00A0;<br /><span class="label"><a 
    307. 

  307.  id="x1-7010r10"></a></span>a.z&#x00A0;=&#x00A0;a.z&#x00A0;/&#x00A0;l
    308. 

  308. 

  309.    </div>
    310. 

  310. <!--l. 177--><p class="indent" >   Vector3 contains two built in functions for normalization:
    311. 

  311.    <!--l. 180-->
    312. 

  312.    <div class="lstlisting"><span class="label"><a 
    313. 

  313.  id="x1-7011r1"></a></span>a&#x00A0;=&#x00A0;Vector3(4,5,6)&#x00A0;<br /><span class="label"><a 
    314. 

  314.  id="x1-7012r2"></a></span>a.normalize()&#x00A0;<span 
    315. 

  315. class="ecti-1000">//</span><span 
    316. 

  316. class="ecti-1000">&#x00A0;</span><span 
    317. 

  317. class="ecti-1000">in</span><span 
    318. 

  318. class="cmsy-10">-</span><span 
    319. 

  319. class="ecti-1000">place</span><span 
    320. 

  320. class="ecti-1000">&#x00A0;</span><span 
    321. 

  321. class="ecti-1000">normalization</span>&#x00A0;<br /><span class="label"><a 
    322. 

  322.  id="x1-7013r3"></a></span>b&#x00A0;=&#x00A0;a.normalized()&#x00A0;<span 
    323. 

  323. class="ecti-1000">//</span><span 
    324. 

  324. class="ecti-1000">&#x00A0;</span><span 
    325. 

  325. class="ecti-1000">returns</span><span 
    326. 

  326. class="ecti-1000">&#x00A0;</span><span 
    327. 

  327. class="ecti-1000">a</span><span 
    328. 

  328. class="ecti-1000">&#x00A0;</span><span 
    329. 

  329. class="ecti-1000">copy</span><span 
    330. 

  330. class="ecti-1000">&#x00A0;</span><span 
    331. 

  331. class="ecti-1000">of</span><span 
    332. 

  332. class="ecti-1000">&#x00A0;</span><span 
    333. 

  333. class="ecti-1000">a</span><span 
    334. 

  334. class="ecti-1000">,</span><span 
    335. 

  335. class="ecti-1000">&#x00A0;</span><span 
    336. 

  336. class="ecti-1000">normalized</span>
    337. 

  337.    </div>
    338. 

  338. <!--l. 188--><p class="noindent" >
    339. 

  339.    <h5 class="subsubsectionHead"><span class="titlemark">1.2.5   </span> <a 
    340. 

  340.  id="x1-80001.2.5"></a>Dot Product</h5>
    341. 

  341. <!--l. 190--><p class="noindent" >The dot product is, pheraps, the most useful operation that can be applied to 3D
    342. 

  342. vectors. In the surface, it&#8217;s multiple usages are not very obvious, but in depth it can
    343. 

  343. provide very useful information between two vectors (be it direction or just points in
    344. 

  344. space).
    345. 

  345. <!--l. 195--><p class="indent" >   The dot product takes two vectors (<span 
    346. 

  346. class="ecti-1000">a </span>and <span 
    347. 

  347. class="ecti-1000">b </span>in the example) and returns a scalar
    348. 

  348. (single real number):
    349. 

  349. <div class="center" 
    350. 

  350. >
    351. 

  351. <!--l. 198--><p class="noindent" >
    352. 

  352. <!--l. 199--><p class="noindent" ><span 
    353. 

  353. class="cmmi-10">a</span><sub><span 
    354. 

  354. class="cmmi-7">x</span></sub><span 
    355. 

  355. class="cmmi-10">b</span><sub><span 
    356. 

  356. class="cmmi-7">x</span></sub> <span 
    357. 

  357. class="cmr-10">+ </span><span 
    358. 

  358. class="cmmi-10">a</span><sub><span 
    359. 

  359. class="cmmi-7">y</span></sub><span 
    360. 

  360. class="cmmi-10">b</span><sub><span 
    361. 

  361. class="cmmi-7">y</span></sub> <span 
    362. 

  362. class="cmr-10">+ </span><span 
    363. 

  363. class="cmmi-10">a</span><sub><span 
    364. 

  364. class="cmmi-7">z</span></sub><span 
    365. 

  365. class="cmmi-10">b</span><sub><span 
    366. 

  366. class="cmmi-7">z</span></sub>
    367. 

  367. </div>
    368. 

  368. <!--l. 202--><p class="indent" >   The same expressed in code:
    369. 

  369.    <!--l. 205-->
    370. 

  370.    <div class="lstlisting"><span class="label"><a 
    371. 

  371.  id="x1-8001r1"></a></span>a&#x00A0;=&#x00A0;Vector3(...)&#x00A0;<br /><span class="label"><a 
    372. 

  372.  id="x1-8002r2"></a></span>b&#x00A0;=&#x00A0;Vector3(...)&#x00A0;<br /><span class="label"><a 
    373. 

  373.  id="x1-8003r3"></a></span>&#x00A0;<br /><span class="label"><a 
    374. 

  374.  id="x1-8004r4"></a></span>c&#x00A0;=&#x00A0;a.x<span 
    375. 

  375. class="cmsy-10">*</span>b.x&#x00A0;+&#x00A0;a.y<span 
    376. 

  376. class="cmsy-10">*</span>b.y&#x00A0;+&#x00A0;a.z<span 
    377. 

  377. class="cmsy-10">*</span>b.z&#x00A0;<br /><span class="label"><a 
    378. 

  378.  id="x1-8005r5"></a></span>&#x00A0;<br /><span class="label"><a 
    379. 

  379.  id="x1-8006r6"></a></span><span 
    380. 

  380. class="ecti-1000">//</span><span 
    381. 

  381. class="ecti-1000">&#x00A0;</span><span 
    382. 

  382. class="ecti-1000">using</span><span 
    383. 

  383. class="ecti-1000">&#x00A0;</span><span 
    384. 

  384. class="ecti-1000">built</span><span 
    385. 

  385. class="cmsy-10">-</span><span 
    386. 

  386. class="ecti-1000">in</span><span 
    387. 

  387. class="ecti-1000">&#x00A0;</span><span 
    388. 

  388. class="ecti-1000">dot</span><span 
    389. 

  389. class="ecti-1000">()</span><span 
    390. 

  390. class="ecti-1000">&#x00A0;</span><span 
    391. 

  391. class="ecti-1000">function</span>&#x00A0;<br /><span class="label"><a 
    392. 

  392.  id="x1-8007r7"></a></span>&#x00A0;<br /><span class="label"><a 
    393. 

  393.  id="x1-8008r8"></a></span>c&#x00A0;=&#x00A0;a.dot(b)
    394. 

  394.    </div>
    395. 

  395. <!--l. 218--><p class="indent" >   The dot product presents several useful properties:
    396. 

  396.      <ul class="itemize1">
    397. 

  397.      <li class="itemize">If both <span 
    398. 

  398. class="ecti-1000">a </span>and <span 
    399. 

  399. class="ecti-1000">b </span>parameters to a <span 
    400. 

  400. class="ecti-1000">dot product </span>are direction vectors, dot
    401. 

  401.      product will return positive if both point towards the same direction,
    402. 

  402.      negative if both point towards opposite directions, and zero if they are
    403. 

  403.      orthogonal (one is perpendicular to the other).
    404. 

  404.      </li>
    405. 

  405.      <li class="itemize">If both <span 
    406. 

  406. class="ecti-1000">a  </span>and <span 
    407. 

  407. class="ecti-1000">b  </span>parameters to a <span 
    408. 

  408. class="ecti-1000">dot product  </span>are <span 
    409. 

  409. class="ecti-1000">normalized  </span>direction
    410. 

  410.      vectors, then the dot product will return the cosine of the angle between
    411. 

  411.      them (ranging from 1 if they are equal, 0 if they are orthogonal, and -1 if
    412. 

  412.      they are opposed (a == -b)).
    413. 

  413.      </li>
    414. 

  414.      <li class="itemize">If <span 
    415. 

  415. class="ecti-1000">a </span>is a <span 
    416. 

  416. class="ecti-1000">normalized </span>direction vector and <span 
    417. 

  417. class="ecti-1000">b </span>is a point, the dot product will
    418. 

  418.      return the distance from <span 
    419. 

  419. class="ecti-1000">b </span>to the plane passing through the origin, with
    420. 

  420.      normal <span 
    421. 

  421. class="ecti-1000">a (see item about planes)</span>
    422. 

  422. 

  423.      </li>
    424. 

  424.      <li class="itemize">More uses will be presented later in this tutorial.</li></ul>
    425. 

  425. <!--l. 236--><p class="noindent" >
    426. 

  426.    <h5 class="subsubsectionHead"><span class="titlemark">1.2.6   </span> <a 
    427. 

  427.  id="x1-90001.2.6"></a>Cross Product</h5>
    428. 

  428. <!--l. 238--><p class="noindent" >The <span 
    429. 

  429. class="ecti-1000">cross product </span>also takes two vectors <span 
    430. 

  430. class="ecti-1000">a </span>and <span 
    431. 

  431. class="ecti-1000">b</span>, but returns another vector <span 
    432. 

  432. class="ecti-1000">c </span>that is
    433. 

  433. orthogonal to the two previous ones.
    434. 

  434. <div class="center" 
    435. 

  435. >
    436. 

  436. <!--l. 242--><p class="noindent" >
    437. 

  437. <!--l. 243--><p class="noindent" ><span 
    438. 

  438. class="cmmi-10">c</span><sub><span 
    439. 

  439. class="cmmi-7">x</span></sub> <span 
    440. 

  440. class="cmr-10">= </span><span 
    441. 

  441. class="cmmi-10">a</span><sub><span 
    442. 

  442. class="cmmi-7">x</span></sub><span 
    443. 

  443. class="cmmi-10">b</span><sub><span 
    444. 

  444. class="cmmi-7">z</span></sub> <span 
    445. 

  445. class="cmsy-10">- </span><span 
    446. 

  446. class="cmmi-10">a</span><sub><span 
    447. 

  447. class="cmmi-7">z</span></sub><span 
    448. 

  448. class="cmmi-10">b</span><sub><span 
    449. 

  449. class="cmmi-7">y</span></sub>
    450. 

  450. </div>
    451. 

  451. <div class="center" 
    452. 

  452. >
    453. 

  453. <!--l. 246--><p class="noindent" >
    454. 

  454. <!--l. 247--><p class="noindent" ><span 
    455. 

  455. class="cmmi-10">c</span><sub><span 
    456. 

  456. class="cmmi-7">y</span></sub> <span 
    457. 

  457. class="cmr-10">= </span><span 
    458. 

  458. class="cmmi-10">a</span><sub><span 
    459. 

  459. class="cmmi-7">z</span></sub><span 
    460. 

  460. class="cmmi-10">b</span><sub><span 
    461. 

  461. class="cmmi-7">x</span></sub> <span 
    462. 

  462. class="cmsy-10">- </span><span 
    463. 

  463. class="cmmi-10">a</span><sub><span 
    464. 

  464. class="cmmi-7">x</span></sub><span 
    465. 

  465. class="cmmi-10">b</span><sub><span 
    466. 

  466. class="cmmi-7">z</span></sub>
    467. 

  467. </div>
    468. 

  468. <div class="center" 
    469. 

  469. >
    470. 

  470. <!--l. 250--><p class="noindent" >
    471. 

  471. <!--l. 251--><p class="noindent" ><span 
    472. 

  472. class="cmmi-10">c</span><sub><span 
    473. 

  473. class="cmmi-7">z</span></sub> <span 
    474. 

  474. class="cmr-10">= </span><span 
    475. 

  475. class="cmmi-10">a</span><sub><span 
    476. 

  476. class="cmmi-7">x</span></sub><span 
    477. 

  477. class="cmmi-10">b</span><sub><span 
    478. 

  478. class="cmmi-7">y</span></sub> <span 
    479. 

  479. class="cmsy-10">- </span><span 
    480. 

  480. class="cmmi-10">a</span><sub><span 
    481. 

  481. class="cmmi-7">y</span></sub><span 
    482. 

  482. class="cmmi-10">b</span><sub><span 
    483. 

  483. class="cmmi-7">x</span></sub>
    484. 

  484. </div>
    485. 

  485. <!--l. 254--><p class="indent" >   The same in code:
    486. 

  486.    <!--l. 257-->
    487. 

  487.    <div class="lstlisting"><span class="label"><a 
    488. 

  488.  id="x1-9001r1"></a></span>a&#x00A0;=&#x00A0;Vector3(...)&#x00A0;<br /><span class="label"><a 
    489. 

  489.  id="x1-9002r2"></a></span>b&#x00A0;=&#x00A0;Vector3(...)&#x00A0;<br /><span class="label"><a 
    490. 

  490.  id="x1-9003r3"></a></span>c&#x00A0;=&#x00A0;Vector3(...)&#x00A0;<br /><span class="label"><a 
    491. 

  491.  id="x1-9004r4"></a></span>&#x00A0;<br /><span class="label"><a 
    492. 

  492.  id="x1-9005r5"></a></span>c.x&#x00A0;=&#x00A0;a.x<span 
    493. 

  493. class="cmsy-10">*</span>b.z&#x00A0;<span 
    494. 

  494. class="cmsy-10">-</span>&#x00A0;a.z<span 
    495. 

  495. class="cmsy-10">*</span>b.y&#x00A0;<br /><span class="label"><a 
    496. 

  496.  id="x1-9006r6"></a></span>c.y&#x00A0;=&#x00A0;a.z<span 
    497. 

  497. class="cmsy-10">*</span>b.x&#x00A0;<span 
    498. 

  498. class="cmsy-10">-</span>&#x00A0;a.x<span 
    499. 

  499. class="cmsy-10">*</span>b.z&#x00A0;<br /><span class="label"><a 
    500. 

  500.  id="x1-9007r7"></a></span>c.z&#x00A0;=&#x00A0;a.x<span 
    501. 

  501. class="cmsy-10">*</span>b.y&#x00A0;<span 
    502. 

  502. class="cmsy-10">-</span>&#x00A0;a.y<span 
    503. 

  503. class="cmsy-10">*</span>b.x&#x00A0;<br /><span class="label"><a 
    504. 

  504.  id="x1-9008r8"></a></span>&#x00A0;<br /><span class="label"><a 
    505. 

  505.  id="x1-9009r9"></a></span>//&#x00A0;or&#x00A0;using&#x00A0;the&#x00A0;built<span 
    506. 

  506. class="cmsy-10">-</span>in&#x00A0;function&#x00A0;<br /><span class="label"><a 
    507. 

  507.  id="x1-9010r10"></a></span>&#x00A0;<br /><span class="label"><a 
    508. 

  508.  id="x1-9011r11"></a></span>c&#x00A0;=&#x00A0;a.cross(b)
    509. 

  509.    </div>
    510. 

  510. <!--l. 273--><p class="indent" >   The <span 
    511. 

  511. class="ecti-1000">cross product </span>also presents several useful properties:
    512. 

  512.      <ul class="itemize1">
    513. 

  513.      <li class="itemize">As mentioned, the resulting vector <span 
    514. 

  514. class="ecti-1000">c </span>is orthogonal to the input vectors <span 
    515. 

  515. class="ecti-1000">a</span>
    516. 

  516.      and <span 
    517. 

  517. class="ecti-1000">b.</span>
    518. 

  518.      </li>
    519. 

  519.      <li class="itemize">Since the <span 
    520. 

  520. class="ecti-1000">cross product </span>is anticommutative, swapping <span 
    521. 

  521. class="ecti-1000">a </span>and <span 
    522. 

  522. class="ecti-1000">b </span>will result
    523. 

  523.      in a negated vector <span 
    524. 

  524. class="ecti-1000">c.</span>
    525. 

  525. 

  526.      </li>
    527. 

  527.      <li class="itemize">if <span 
    528. 

  528. class="ecti-1000">a </span>and <span 
    529. 

  529. class="ecti-1000">b </span>are taken from two of the segmets <span 
    530. 

  530. class="ecti-1000">AB</span>, <span 
    531. 

  531. class="ecti-1000">BC </span>or <span 
    532. 

  532. class="ecti-1000">CA </span>that form a
    533. 

  533.      3D triangle, the magnitude of the resulting vector divided by 2 is the area
    534. 

  534.      of that triangle.
    535. 

  535.      </li>
    536. 

  536.      <li class="itemize">The direction of the resulting vector <span 
    537. 

  537. class="ecti-1000">c </span>in the previous triangle example
    538. 

  538.      determines  wether  the  points  A,B  and  C  are  arranged  in  clocwise  or
    539. 

  539.      counter-clockwise order.</li></ul>
    540. 

  540. <!--l. 287--><p class="noindent" >
    541. 

  541.    <h4 class="subsectionHead"><span class="titlemark">1.3   </span> <a 
    542. 

  542.  id="x1-100001.3"></a>Plane</h4>
    543. 

  543. <!--l. 290--><p class="noindent" >
    544. 

  544.    <h5 class="subsubsectionHead"><span class="titlemark">1.3.1   </span> <a 
    545. 

  545.  id="x1-110001.3.1"></a>Theory</h5>
    546. 

  546. <!--l. 292--><p class="noindent" >A plane can be considered as an infinite, flat surface that splits space in two halves,
    547. 

  547. usually one named positive and one named negative. In regular mathematics, a plane
    548. 

  548. formula is described as:
    549. 

  549. <div class="center" 
    550. 

  550. >
    551. 

  551. <!--l. 296--><p class="noindent" >
    552. 

  552. <!--l. 297--><p class="noindent" ><span 
    553. 

  553. class="cmmi-10">ax </span><span 
    554. 

  554. class="cmr-10">+ </span><span 
    555. 

  555. class="cmmi-10">by </span><span 
    556. 

  556. class="cmr-10">+ </span><span 
    557. 

  557. class="cmmi-10">cz </span><span 
    558. 

  558. class="cmr-10">+ </span><span 
    559. 

  559. class="cmmi-10">d</span>
    560. 

  560. </div>
    561. 

  561. <!--l. 300--><p class="indent" >   However, in 3D programming, this form alone is often of little use. For planes to
    562. 

  562. become useful, they must be in normalized form.
    563. 

  563. <!--l. 303--><p class="indent" >   A normalized plane consists of a <span 
    564. 

  564. class="ecti-1000">normal vector n </span>and a <span 
    565. 

  565. class="ecti-1000">distance d. </span>To normalize
    566. 

  566. a plane, a vector <span 
    567. 

  567. class="ecti-1000">n </span>and distance <span 
    568. 

  568. class="ecti-1000">d&#8217; </span>are created this way:
    569. 

  569. <!--l. 307--><p class="indent" >   <span 
    570. 

  570. class="cmmi-10">n</span><sub><span 
    571. 

  571. class="cmmi-7">x</span></sub> <span 
    572. 

  572. class="cmr-10">= </span><span 
    573. 

  573. class="cmmi-10">a</span>
    574. 

  574. <!--l. 309--><p class="indent" >   <span 
    575. 

  575. class="cmmi-10">n</span><sub><span 
    576. 

  576. class="cmmi-7">y</span></sub> <span 
    577. 

  577. class="cmr-10">= </span><span 
    578. 

  578. class="cmmi-10">b</span>
    579. 

  579. <!--l. 311--><p class="indent" >   <span 
    580. 

  580. class="cmmi-10">n</span><sub><span 
    581. 

  581. class="cmmi-7">z</span></sub> <span 
    582. 

  582. class="cmr-10">= </span><span 
    583. 

  583. class="cmmi-10">c</span>
    584. 

  584. <!--l. 313--><p class="indent" >   <span 
    585. 

  585. class="cmmi-10">d</span><span 
    586. 

  586. class="cmsy-10">&#x2032; </span><span 
    587. 

  587. class="cmr-10">= </span><span 
    588. 

  588. class="cmmi-10">d</span>
    589. 

  589. <!--l. 315--><p class="indent" >   Finally, both <span 
    590. 

  590. class="ecti-1000">n </span>and <span 
    591. 

  591. class="ecti-1000">d&#8217; </span>are both divided by the magnitude of n.
    592. 

  592. <!--l. 318--><p class="indent" >   In any case, normalizing planes is not often needed (this was mostly for
    593. 

  593. explanation purposes), and normalized planes are useful because they can be created
    594. 

  594. and used easily.
    595. 

  595. <!--l. 322--><p class="indent" >   A normalized plane could be visualized as a plane pointing towards normal <span 
    596. 

  596. class="ecti-1000">n,</span>
    597. 

  597. offseted by <span 
    598. 

  598. class="ecti-1000">d </span>in the direction of <span 
    599. 

  599. class="ecti-1000">n</span>.
    600. 

  600. <!--l. 325--><p class="indent" >   In other words, take <span 
    601. 

  601. class="ecti-1000">n</span>, multiply it by scalar <span 
    602. 

  602. class="ecti-1000">d </span>and the resulting point will be part
    603. 

  603. of the plane. This may need some thinking, so an example with a 2D normal vector
    604. 

  604. (z is 0, so plane is orthogonal to it) is provided:
    605. 

  605. <!--l. 330--><p class="indent" >   Some operations can be done with normalized planes:
    606. 

  606. 

  607.      <ul class="itemize1">
    608. 

  608.      <li class="itemize">Given any point <span 
    609. 

  609. class="ecti-1000">p</span>, the distance from it to a plane can be computed by
    610. 

  610.      doing: n.dot(p) - d
    611. 

  611.      </li>
    612. 

  612.      <li class="itemize">If the resulting distance in the previous point is negative, the point is
    613. 

  613.      below the plane.
    614. 

  614.      </li>
    615. 

  615.      <li class="itemize">Convex polygonal shapes can be defined by enclosing them in planes (the
    616. 

  616.      physics engine uses this property)</li></ul>
    617. 

  617. <!--l. 340--><p class="noindent" >
    618. 

  618.    <h5 class="subsubsectionHead"><span class="titlemark">1.3.2   </span> <a 
    619. 

  619.  id="x1-120001.3.2"></a>Implementation</h5>
    620. 

  620. <!--l. 342--><p class="noindent" >Godot Engine implements normalized planes by using the <span 
    621. 

  621. class="ecti-1000">Plane </span>class.
    622. 

  622.    <!--l. 346-->
    623. 

  623.    <div class="lstlisting"><span class="label"><a 
    624. 

  624.  id="x1-12001r1"></a></span>//creates&#x00A0;a&#x00A0;plane&#x00A0;with&#x00A0;normal&#x00A0;(0,1,0)&#x00A0;and&#x00A0;distance&#x00A0;5&#x00A0;<br /><span class="label"><a 
    625. 

  625.  id="x1-12002r2"></a></span>p&#x00A0;=&#x00A0;Plane(&#x00A0;Vector3(0,1,0),&#x00A0;5&#x00A0;)&#x00A0;<br /><span class="label"><a 
    626. 

  626.  id="x1-12003r3"></a></span>//&#x00A0;get&#x00A0;the&#x00A0;distance&#x00A0;to&#x00A0;a&#x00A0;point&#x00A0;<br /><span class="label"><a 
    627. 

  627.  id="x1-12004r4"></a></span>d&#x00A0;=&#x00A0;p.distance(&#x00A0;Vector3(4,5,6)&#x00A0;)
    628. 

  628.    </div>
    629. 

  629. <!--l. 355--><p class="noindent" >
    630. 

  630.    <h4 class="subsectionHead"><span class="titlemark">1.4   </span> <a 
    631. 

  631.  id="x1-130001.4"></a>Matrices, Quaternions and Coordinate Systems</h4>
    632. 

  632. <!--l. 357--><p class="noindent" >It is very often needed to store the location/rotation of something. In 2D, it is often
    633. 

  633. enough to store an <span 
    634. 

  634. class="ecti-1000">x,y </span>location and maybe an angle as the rotation, as that should
    635. 

  635. be enough to represent any posible position.
    636. 

  636. <!--l. 362--><p class="indent" >   In 3D this becomes a little more difficult, as there is nothing as simple as an angle
    637. 

  637. to store a 3-axis rotation.
    638. 

  638. <!--l. 365--><p class="indent" >   The first think that may come to mind is to use 3 angles, one for x, one for y and
    639. 

  639. one for z. However this suffers from the problem that it becomes very cumbersome to
    640. 

  640. use, as the individual rotations in each axis need to be performed one after another
    641. 

  641. (they can&#8217;t be performed at the same time), leading to a problem called &#8220;gimbal
    642. 

  642. lock&#8221;. Also, it becomes impossible to accumulate rotations (add a rotation to an
    643. 

  643. existing one).
    644. 

  644. <!--l. 373--><p class="indent" >   To solve this, there are two known diferent approaches that aid in solving
    645. 

  645. rotation, <span 
    646. 

  646. class="ecti-1000">Quaternions </span>and <span 
    647. 

  647. class="ecti-1000">Oriented Coordinate Systems.</span>
    648. 

  648. <!--l. 378--><p class="noindent" >
    649. 

  649.    <h5 class="subsubsectionHead"><span class="titlemark">1.4.1   </span> <a 
    650. 

  650.  id="x1-140001.4.1"></a>Oriented Coordinate Systems</h5>
    651. 

  651. <!--l. 380--><p class="noindent" ><span 
    652. 

  652. class="ecti-1000">Oriented Coordinate Systems </span>(<span 
    653. 

  653. class="ecti-1000">OCS</span>) are a way of representing a coordinate system
    654. 

  654. inside the cartesian coordinate system. They are mainly composed of 3 Vectors, one
    655. 

  655. for each axis. The first vector is the <span 
    656. 

  656. class="ecti-1000">x </span>axis, the second the <span 
    657. 

  657. class="ecti-1000">y </span>axis, and the third is the
    658. 

  658. 

  659. <span 
    660. 

  660. class="ecti-1000">z </span>axis. The OCS vectors can be rotated around freely as long as they are kept the
    661. 

  661. same length (as changing the length of an axis changes its cale), and as long as they
    662. 

  662. remain orthogonal to eachother (as in, the same as the default cartesian system,
    663. 

  663. with <span 
    664. 

  664. class="ecti-1000">y </span>pointing up, <span 
    665. 

  665. class="ecti-1000">x </span>pointing left and <span 
    666. 

  666. class="ecti-1000">z </span>pointing front, but all rotated
    667. 

  667. together).
    668. 

  668. <!--l. 391--><p class="indent" >   <span 
    669. 

  669. class="ecti-1000">Oriented Coordinate Systems </span>are represented in 3D programming as a 3x3 matrix,
    670. 

  670. where each row (or column, depending on the implementation) contains one of the
    671. 

  671. axis vectors. Transforming a Vector by a rotated OCS Matrix results in the rotation
    672. 

  672. being applied to the resulting vector. OCS Matrices can also be multiplied to
    673. 

  673. accumulate their transformations.
    674. 

  674. <!--l. 397--><p class="indent" >   Godot Engine implements OCS Matrices in the <span 
    675. 

  675. class="ecti-1000">Matrix3 </span>class:
    676. 

  676.    <!--l. 400-->
    677. 

  677.    <div class="lstlisting"><span class="label"><a 
    678. 

  678.  id="x1-14001r1"></a></span><span 
    679. 

  679. class="ecti-1000">//</span><span 
    680. 

  680. class="ecti-1000">create</span><span 
    681. 

  681. class="ecti-1000">&#x00A0;</span><span 
    682. 

  682. class="ecti-1000">a</span><span 
    683. 

  683. class="ecti-1000">&#x00A0;</span><span 
    684. 

  684. class="ecti-1000">3</span><span 
    685. 

  685. class="ecti-1000">x3</span><span 
    686. 

  686. class="ecti-1000">&#x00A0;</span><span 
    687. 

  687. class="ecti-1000">matrix</span>&#x00A0;<br /><span class="label"><a 
    688. 

  688.  id="x1-14002r2"></a></span>m&#x00A0;=&#x00A0;Matrix3()&#x00A0;<br /><span class="label"><a 
    689. 

  689.  id="x1-14003r3"></a></span><span 
    690. 

  690. class="ecti-1000">//</span><span 
    691. 

  691. class="ecti-1000">rotate</span><span 
    692. 

  692. class="ecti-1000">&#x00A0;</span><span 
    693. 

  693. class="ecti-1000">the</span><span 
    694. 

  694. class="ecti-1000">&#x00A0;</span><span 
    695. 

  695. class="ecti-1000">matrix</span><span 
    696. 

  696. class="ecti-1000">&#x00A0;</span><span 
    697. 

  697. class="ecti-1000">in</span><span 
    698. 

  698. class="ecti-1000">&#x00A0;</span><span 
    699. 

  699. class="ecti-1000">the</span><span 
    700. 

  700. class="ecti-1000">&#x00A0;</span><span 
    701. 

  701. class="ecti-1000">y</span><span 
    702. 

  702. class="ecti-1000">&#x00A0;</span><span 
    703. 

  703. class="ecti-1000">axis</span><span 
    704. 

  704. class="ecti-1000">,</span><span 
    705. 

  705. class="ecti-1000">&#x00A0;</span><span 
    706. 

  706. class="ecti-1000">by</span><span 
    707. 

  707. class="ecti-1000">&#x00A0;</span><span 
    708. 

  708. class="ecti-1000">45</span><span 
    709. 

  709. class="ecti-1000">&#x00A0;</span><span 
    710. 

  710. class="ecti-1000">degrees</span>&#x00A0;<br /><span class="label"><a 
    711. 

  711.  id="x1-14004r4"></a></span>m.rotate(&#x00A0;Vector3(0,1,0),&#x00A0;Math.deg2rad(45)&#x00A0;)&#x00A0;<br /><span class="label"><a 
    712. 

  712.  id="x1-14005r5"></a></span><span 
    713. 

  713. class="ecti-1000">//</span><span 
    714. 

  714. class="ecti-1000">transform</span><span 
    715. 

  715. class="ecti-1000">&#x00A0;</span><span 
    716. 

  716. class="ecti-1000">a</span><span 
    717. 

  717. class="ecti-1000">&#x00A0;</span><span 
    718. 

  718. class="ecti-1000">vector</span><span 
    719. 

  719. class="ecti-1000">&#x00A0;</span><span 
    720. 

  720. class="ecti-1000">v</span><span 
    721. 

  721. class="ecti-1000">&#x00A0;</span><span 
    722. 

  722. class="ecti-1000">(</span><span 
    723. 

  723. class="ecti-1000">xform</span><span 
    724. 

  724. class="ecti-1000">&#x00A0;</span><span 
    725. 

  725. class="ecti-1000">method</span><span 
    726. 

  726. class="ecti-1000">&#x00A0;</span><span 
    727. 

  727. class="ecti-1000">is</span><span 
    728. 

  728. class="ecti-1000">&#x00A0;</span><span 
    729. 

  729. class="ecti-1000">used</span><span 
    730. 

  730. class="ecti-1000">)</span>&#x00A0;<br /><span class="label"><a 
    731. 

  731.  id="x1-14006r6"></a></span>v&#x00A0;=&#x00A0;Vector3(...)&#x00A0;<br /><span class="label"><a 
    732. 

  732.  id="x1-14007r7"></a></span>result&#x00A0;=&#x00A0;m.xform(&#x00A0;v&#x00A0;)
    733. 

  733.    </div>
    734. 

  734. <!--l. 412--><p class="indent" >   However, in most usage cases, one wants to store a translation together with the
    735. 

  735. rotation. For this, an <span 
    736. 

  736. class="ecti-1000">origin </span>vector must be added to the OCS, thus transforming it
    737. 

  737. into a 3x4 (or 4x3, depending on preference) matrix. Godot engine implements this
    738. 

  738. functionality in the <span 
    739. 

  739. class="ecti-1000">Transform </span>class:
    740. 

  740.    <!--l. 419-->
    741. 

  741.    <div class="lstlisting"><span class="label"><a 
    742. 

  742.  id="x1-14010r1"></a></span>t&#x00A0;=&#x00A0;Transform()&#x00A0;<br /><span class="label"><a 
    743. 

  743.  id="x1-14011r2"></a></span>//rotate&#x00A0;the&#x00A0;transform&#x00A0;in&#x00A0;the&#x00A0;y&#x00A0;axis,&#x00A0;by&#x00A0;45&#x00A0;degrees&#x00A0;<br /><span class="label"><a 
    744. 

  744.  id="x1-14012r3"></a></span>t.rotate(&#x00A0;Vector3(0,1,0),&#x00A0;Math.deg2rad(45)&#x00A0;)&#x00A0;<br /><span class="label"><a 
    745. 

  745.  id="x1-14013r4"></a></span>//translate&#x00A0;the&#x00A0;transform&#x00A0;by&#x00A0;5&#x00A0;in&#x00A0;the&#x00A0;z&#x00A0;axis&#x00A0;<br /><span class="label"><a 
    746. 

  746.  id="x1-14014r5"></a></span>t.translate(&#x00A0;Vector3(&#x00A0;0,0,5&#x00A0;)&#x00A0;)&#x00A0;<br /><span class="label"><a 
    747. 

  747.  id="x1-14015r6"></a></span>//transform&#x00A0;a&#x00A0;vector&#x00A0;v&#x00A0;(xform&#x00A0;method&#x00A0;is&#x00A0;used)&#x00A0;<br /><span class="label"><a 
    748. 

  748.  id="x1-14016r7"></a></span>v&#x00A0;=&#x00A0;Vector3(...)&#x00A0;<br /><span class="label"><a 
    749. 

  749.  id="x1-14017r8"></a></span>result&#x00A0;=&#x00A0;t.xform(&#x00A0;v&#x00A0;)
    750. 

  750.    </div>
    751. 

  751. <!--l. 431--><p class="indent" >   Transform contains internally a Matrix3 &#8220;basis&#8221; and a Vector3 &#8220;origin&#8221; (which can
    752. 

  752. be modified individually).
    753. 

  753. <!--l. 435--><p class="noindent" >
    754. 

  754.    <h5 class="subsubsectionHead"><span class="titlemark">1.4.2   </span> <a 
    755. 

  755.  id="x1-150001.4.2"></a>Transform Internals</h5>
    756. 

  756. <!--l. 437--><p class="noindent" >Internally, the xform() process is quite simple, to apply a 3x3 transform to a vector,
    757. 

  757. the transposed axis vectors are used (as using the regular axis vectors will result on
    758. 

  758. an inverse of the desired transform):
    759. 

  759.    <!--l. 442-->
    760. 

  760.    <div class="lstlisting"><span class="label"><a 
    761. 

  761.  id="x1-15001r1"></a></span>m&#x00A0;=&#x00A0;Matrix3(...)&#x00A0;<br /><span class="label"><a 
    762. 

  762.  id="x1-15002r2"></a></span>v&#x00A0;=&#x00A0;Vector3(..)&#x00A0;<br /><span class="label"><a 
    763. 

  763.  id="x1-15003r3"></a></span>result&#x00A0;=&#x00A0;Vector3(...)&#x00A0;<br /><span class="label"><a 
    764. 

  764.  id="x1-15004r4"></a></span>&#x00A0;<br /><span class="label"><a 
    765. 

  765.  id="x1-15005r5"></a></span>x_axis&#x00A0;=&#x00A0;m.get_axis(0)&#x00A0;<br /><span class="label"><a 
    766. 

  766.  id="x1-15006r6"></a></span>y_axis&#x00A0;=&#x00A0;m.get_axis(1)&#x00A0;<br /><span class="label"><a 
    767. 

  767.  id="x1-15007r7"></a></span>z_axis&#x00A0;=&#x00A0;m.get_axis(2)&#x00A0;<br /><span class="label"><a 
    768. 

  768.  id="x1-15008r8"></a></span>&#x00A0;<br /><span class="label"><a 
    769. 

  769.  id="x1-15009r9"></a></span>result.x&#x00A0;=&#x00A0;Vector3(x_axis.x,&#x00A0;y_axis.x,&#x00A0;z_axis.x).dot(v)&#x00A0;<br /><span class="label"><a 
    770. 

  770.  id="x1-15010r10"></a></span>result.y&#x00A0;=&#x00A0;Vector3(x_axis.y,&#x00A0;y_axis.y,&#x00A0;z_axis.y).dot(v)&#x00A0;<br /><span class="label"><a 
    771. 

  771.  id="x1-15011r11"></a></span>result.z&#x00A0;=&#x00A0;Vector3(x_axis.z,&#x00A0;y_axis.z,&#x00A0;z_axis.z).dot(v)&#x00A0;<br /><span class="label"><a 
    772. 

  772.  id="x1-15012r12"></a></span>&#x00A0;<br /><span class="label"><a 
    773. 

  773.  id="x1-15013r13"></a></span>//&#x00A0;is&#x00A0;the&#x00A0;same&#x00A0;as&#x00A0;doing&#x00A0;<br /><span class="label"><a 
    774. 

  774.  id="x1-15014r14"></a></span>&#x00A0;<br /><span class="label"><a 
    775. 

  775.  id="x1-15015r15"></a></span>result&#x00A0;=&#x00A0;m.xform(v)&#x00A0;<br /><span class="label"><a 
    776. 

  776.  id="x1-15016r16"></a></span>&#x00A0;<br /><span class="label"><a 
    777. 

  777.  id="x1-15017r17"></a></span>//&#x00A0;if&#x00A0;m&#x00A0;this&#x00A0;was&#x00A0;a&#x00A0;Transform(),&#x00A0;the&#x00A0;origin&#x00A0;would&#x00A0;be&#x00A0;added&#x00A0;<br /><span class="label"><a 
    778. 

  778.  id="x1-15018r18"></a></span>//&#x00A0;like&#x00A0;this:&#x00A0;<br /><span class="label"><a 
    779. 

  779.  id="x1-15019r19"></a></span>&#x00A0;<br /><span class="label"><a 
    780. 

  780.  id="x1-15020r20"></a></span>result&#x00A0;=&#x00A0;result&#x00A0;+&#x00A0;t.get_origin()
    781. 

  781.    </div>
    782. 

  782. <!--l. 468--><p class="noindent" >
    783. 

  783.    <h5 class="subsubsectionHead"><span class="titlemark">1.4.3   </span> <a 
    784. 

  784.  id="x1-160001.4.3"></a>Using The Transform</h5>
    785. 

  785. <!--l. 470--><p class="noindent" >So, it is often desired apply sucessive operations to a transformation. For example,
    786. 

  786. let&#8217;s a assume that there is a turtle sitting at the origin (the turtle is a logo reference,
    787. 

  787. 

  788. for those familiar with it). The <span 
    789. 

  789. class="ecti-1000">y </span>axis is up, and the the turtle&#8217;s nose is pointing
    790. 

  790. towards the <span 
    791. 

  791. class="ecti-1000">z </span>axis.
    792. 

  792. <!--l. 476--><p class="indent" >   The turtle (like many other animals, or vehicles!) can only walk towards the
    793. 

  793. direction it&#8217;s looking at. So, moving the turtle around a little should be something
    794. 

  794. like this:
    795. 

  795.    <!--l. 481-->
    796. 

  796.    <div class="lstlisting"><span class="label"><a 
    797. 

  797.  id="x1-16001r1"></a></span><span 
    798. 

  798. class="ecti-1000">//</span><span 
    799. 

  799. class="ecti-1000">&#x00A0;</span><span 
    800. 

  800. class="ecti-1000">turtle</span><span 
    801. 

  801. class="ecti-1000">&#x00A0;</span><span 
    802. 

  802. class="ecti-1000">at</span><span 
    803. 

  803. class="ecti-1000">&#x00A0;</span><span 
    804. 

  804. class="ecti-1000">the</span><span 
    805. 

  805. class="ecti-1000">&#x00A0;</span><span 
    806. 

  806. class="ecti-1000">origin</span>&#x00A0;<br /><span class="label"><a 
    807. 

  807.  id="x1-16002r2"></a></span>turtle&#x00A0;=&#x00A0;Transform()&#x00A0;<br /><span class="label"><a 
    808. 

  808.  id="x1-16003r3"></a></span><span 
    809. 

  809. class="ecti-1000">//</span><span 
    810. 

  810. class="ecti-1000">&#x00A0;</span><span 
    811. 

  811. class="ecti-1000">turtle</span><span 
    812. 

  812. class="ecti-1000">&#x00A0;</span><span 
    813. 

  813. class="ecti-1000">will</span><span 
    814. 

  814. class="ecti-1000">&#x00A0;</span><span 
    815. 

  815. class="ecti-1000">walk</span><span 
    816. 

  816. class="ecti-1000">&#x00A0;</span><span 
    817. 

  817. class="ecti-1000">5</span><span 
    818. 

  818. class="ecti-1000">&#x00A0;</span><span 
    819. 

  819. class="ecti-1000">units</span><span 
    820. 

  820. class="ecti-1000">&#x00A0;</span><span 
    821. 

  821. class="ecti-1000">in</span><span 
    822. 

  822. class="ecti-1000">&#x00A0;</span><span 
    823. 

  823. class="ecti-1000">z</span><span 
    824. 

  824. class="ecti-1000">&#x00A0;</span><span 
    825. 

  825. class="ecti-1000">axis</span>&#x00A0;<br /><span class="label"><a 
    826. 

  826.  id="x1-16004r4"></a></span>turtle.translate(&#x00A0;Vector3(0,0,5)&#x00A0;)&#x00A0;<br /><span class="label"><a 
    827. 

  827.  id="x1-16005r5"></a></span><span 
    828. 

  828. class="ecti-1000">//</span><span 
    829. 

  829. class="ecti-1000">&#x00A0;</span><span 
    830. 

  830. class="ecti-1000">turtle</span><span 
    831. 

  831. class="ecti-1000">&#x00A0;</span><span 
    832. 

  832. class="ecti-1000">eyes</span><span 
    833. 

  833. class="ecti-1000">&#x00A0;</span><span 
    834. 

  834. class="ecti-1000">a</span><span 
    835. 

  835. class="ecti-1000">&#x00A0;</span><span 
    836. 

  836. class="ecti-1000">lettuce</span><span 
    837. 

  837. class="ecti-1000">&#x00A0;</span><span 
    838. 

  838. class="ecti-1000">3</span><span 
    839. 

  839. class="ecti-1000">&#x00A0;</span><span 
    840. 

  840. class="ecti-1000">units</span><span 
    841. 

  841. class="ecti-1000">&#x00A0;</span><span 
    842. 

  842. class="ecti-1000">away</span><span 
    843. 

  843. class="ecti-1000">,</span><span 
    844. 

  844. class="ecti-1000">&#x00A0;</span><span 
    845. 

  845. class="ecti-1000">will</span><span 
    846. 

  846. class="ecti-1000">&#x00A0;</span><span 
    847. 

  847. class="ecti-1000">rotate</span><span 
    848. 

  848. class="ecti-1000">&#x00A0;</span><span 
    849. 

  849. class="ecti-1000">45</span><span 
    850. 

  850. class="ecti-1000">&#x00A0;</span><span 
    851. 

  851. class="ecti-1000">degrees</span><span 
    852. 

  852. class="ecti-1000">&#x00A0;</span><span 
    853. 

  853. class="ecti-1000">right</span>&#x00A0;<br /><span class="label"><a 
    854. 

  854.  id="x1-16006r6"></a></span>turtle.rotate(&#x00A0;Vector3(0,1,0),&#x00A0;Math.deg2rad(45)&#x00A0;)&#x00A0;<br /><span class="label"><a 
    855. 

  855.  id="x1-16007r7"></a></span><span 
    856. 

  856. class="ecti-1000">//</span><span 
    857. 

  857. class="ecti-1000">&#x00A0;</span><span 
    858. 

  858. class="ecti-1000">turtle</span><span 
    859. 

  859. class="ecti-1000">&#x00A0;</span><span 
    860. 

  860. class="ecti-1000">approaches</span><span 
    861. 

  861. class="ecti-1000">&#x00A0;</span><span 
    862. 

  862. class="ecti-1000">the</span><span 
    863. 

  863. class="ecti-1000">&#x00A0;</span><span 
    864. 

  864. class="ecti-1000">lettuce</span>&#x00A0;<br /><span class="label"><a 
    865. 

  865.  id="x1-16008r8"></a></span>turtle.translate(&#x00A0;Vector3(0,0,5)&#x00A0;)&#x00A0;<br /><span class="label"><a 
    866. 

  866.  id="x1-16009r9"></a></span><span 
    867. 

  867. class="ecti-1000">//</span><span 
    868. 

  868. class="ecti-1000">&#x00A0;</span><span 
    869. 

  869. class="ecti-1000">happy</span><span 
    870. 

  870. class="ecti-1000">&#x00A0;</span><span 
    871. 

  871. class="ecti-1000">turtle</span><span 
    872. 

  872. class="ecti-1000">&#x00A0;</span><span 
    873. 

  873. class="ecti-1000">over</span><span 
    874. 

  874. class="ecti-1000">&#x00A0;</span><span 
    875. 

  875. class="ecti-1000">lettuce</span><span 
    876. 

  876. class="ecti-1000">&#x00A0;</span><span 
    877. 

  877. class="ecti-1000">is</span><span 
    878. 

  878. class="ecti-1000">&#x00A0;</span><span 
    879. 

  879. class="ecti-1000">at</span>&#x00A0;<br /><span class="label"><a 
    880. 

  880.  id="x1-16010r10"></a></span>print(turtle.get_origin())
    881. 

  881.    </div>
    882. 

  882. <!--l. 496--><p class="indent" >   As can be seen, every new action the turtle takes is based on the previous one it
    883. 

  883. took. Had the order of actions been different and the turtle would have never reached
    884. 

  884. the lettuce.
    885. 

  885. <!--l. 500--><p class="indent" >   Transforms are just that, a mean of &#8220;accumulating&#8221; rotation, translation, scale,
    886. 

  886. etc.
    887. 

  887. <!--l. 504--><p class="noindent" >
    888. 

  888.    <h5 class="subsubsectionHead"><span class="titlemark">1.4.4   </span> <a 
    889. 

  889.  id="x1-170001.4.4"></a>A Warning about Numerical Precision</h5>
    890. 

  890. <!--l. 506--><p class="noindent" >Performing several actions over a transform will slowly and gradually lead to
    891. 

  891. precision loss (objects that draw according to a transform may get jittery, bigger,
    892. 

  892. smaller, skewed, etc). This happens due to the nature of floating point numbers. if
    893. 

  893. transforms/matrices are created from other kind of values (like a position and
    894. 

  894. some angular rotation) this is not needed, but if has been accumulating
    895. 

  895. transformations and was never recreated, it can be normalized by calling the
    896. 

  896. .orthonormalize() built-in function. This function has little cost and calling it every
    897. 

  897. now and then will avoid the effects from precision loss to become visible.
    898. 

  898.  
    899. 

  899. </body></html> 
    900. 

  900. 

  901. 

  902. 

  903.