linalgebra.html

Revision 5, 112.5 kB (checked in by nail, 3 years ago)
Initial import

Line
1	<html><head>
2	<meta http-equiv="content-type" content="text/html; charset=utf-8">
3	<meta content="text/javascript" http-equiv="content-script-type">
4	<title>helix.linalgebra</title>
5	<link rel="stylesheet" type="text/css" href="candydoc/style.css">
6	<!--[if lt IE 7]><link rel="stylesheet" type="text/css" href="candydoc/ie56hack.css"><![endif]-->
7	<script language="JavaScript" src="candydoc/util.js" type="text/javascript"></script>
8	<script language="JavaScript" src="candydoc/tree.js" type="text/javascript"></script>
9	<script language="JavaScript" src="candydoc/explorer.js" type="text/javascript"></script>
10	</head><body>
11	<div id="tabarea"></div><div id="explorerclient"></div>
12	<div id="content"><script>explorer.initialize("helix.linalgebra");</script>
13	<table class="content">
14	<tr><td id="docbody"><h1>helix.linalgebra</h1><!-- Generated by Ddoc from c:\sdk\helix\trunk\helix\linalgebra.d -->
15	Module consists of basic mathematical objects oriented to working with 3D
16	graphics.
17	<br><br>
18	Those are 2,3,4-D vectors, quaternion, 3x3 and 4x4 matrices. In case of
19	specialization for 3D graphics there are always some features and deviation
20	from classical math. Here I summarize such features of helix'es linear algebra:
21	<ul> <li>In helix paradigm of column-vector is taken. So multiplication of matrix
22	by vector makes sense but multiplication of vector by matrix makes not.
23	This approach conforms to rules accepted in classical math and coincides
24	with OpenGL rules. However this is opposite to Direct3D paradigm where
25	vector is a row. So, in helix, to combine sequence of transforms specified with
26	matrices A, B, C in order A then B then C, you have to multiply them in
27	back-to-front order order: M=CBA. </li>
28	<br><br>
29
30	<li>When an issue deal with euler angles following definitions are accepted.
31	Yaw is rotation around Y, Pitch is rotaion around X, Roll is rotation around Z
32	Rotations are always applied in order: Roll then Pitch then Yaw. </li>
33	<br><br>
34
35	<li>Helix matrices use column-major memory layout. I.e. matrix
36	<table style="border-left: double 3px #666666; border-right: double 3px #666666;
37	margin-left: 3em;"> <tr><td>a</td><td>b</td><td>c</td></tr>
38	<tr><td>d</td><td>e</td><td>f</td></tr>
39	<tr><td>g</td><td>h</td><td>i</td></tr>
40	</table>
41	in memory will looks like: a, d, g, b, e, h, c, f, i. This order is the same as
42	in OpenGL API, but opposite to Direct3D API. However as mentioned above, Direct3D
43	uses vector-row paradigm that is opposite to classical math, so D3D requires
44	transposed matrix as compared to classical math to get desired transformation. As a
45	result you haven't to transpose helix matrix while transmission to API even in Direct3D
46	case. Normaly you haven't to remember about memory layout, just use it as in classical
47	math, this feature is significant only in routines that operate with data pointers
48	and plain array representation. There are reminders in such methods' documentation. </li>
49	</ul>
50
51	<br><br>
52	<b>Authors:</b><br>
53	Victor Nakoryakov, nail-mail[at]mail.ru
54
55	<br><br>
56
57
58	<script>explorer.outline.incSymbolLevel();</script>
59	<dl>
60	<script>explorer.outline.writeEnabled = true;</script>
61	<dt><span class="decl">enum
62	<span class="currsymbol">Ort</span>
63	<script>explorer.outline.addDecl('Ort');</script>
64
65	;
66	</span></dt>
67	<script>explorer.outline.writeEnabled = false;</script>
68
69
70	<dd>Defines ort names that are usualy used as indices.
71	<br><br>
72
73
74	<script>explorer.outline.incSymbolLevel();</script>
75	<dl>
76	<script>explorer.outline.writeEnabled = true;</script>
77	<dt><span class="decl">
78	<span class="currsymbol">X</span>
79	<script>explorer.outline.addDecl('X');</script>
80
81	<br>
82	<span class="currsymbol">Y</span>
83	<script>explorer.outline.addDecl('Y');</script>
84
85	<br>
86	<span class="currsymbol">Z</span>
87	<script>explorer.outline.addDecl('Z');</script>
88
89	<br>
90	<span class="currsymbol">W</span>
91	<script>explorer.outline.addDecl('W');</script>
92
93	</span></dt>
94	<script>explorer.outline.writeEnabled = false;</script>
95
96
97	<dd><br><br>
98	</dd>
99	</dl>
100	<script>explorer.outline.decSymbolLevel();</script>
101
102
103	</dd>
104
105	<script>explorer.outline.writeEnabled = true;</script>
106	<dt><span class="decl">template
107	<span class="currsymbol">LinearAlgebra</span>
108	<script>explorer.outline.addDecl('LinearAlgebra');</script>
109
110	(float_t)</span></dt>
111	<script>explorer.outline.writeEnabled = false;</script>
112
113
114	<dd>Wrapper template to provide possibility to use different float types
115	in implemented structs and routines.
116	<br><br>
117
118
119	<script>explorer.outline.incSymbolLevel();</script>
120	<dl>
121	<script>explorer.outline.writeEnabled = true;</script>
122	<dt><span class="decl">struct
123	<span class="currsymbol">Vector2</span>
124	<script>explorer.outline.addDecl('Vector2');</script>
125
126	;
127	</span></dt>
128	<script>explorer.outline.writeEnabled = false;</script>
129
130
131	<dd>Two dimensional vector.
132	<br><br>
133	For formal definition of vector, meaning of possible operations and related
134	information see <a href="http://en.wikipedia.org/wiki/Vector_(spatial)">http://en.wikipedia.org/wiki/Vector_(spatial)</a>.
135
136	<br><br>
137
138
139	<script>explorer.outline.incSymbolLevel();</script>
140	<dl>
141	<script>explorer.outline.writeEnabled = true;</script>
142	<dt><span class="decl">float_t
143	<span class="currsymbol">x</span>
144	<script>explorer.outline.addDecl('x');</script>
145
146	;
147	<br>float_t
148	<span class="currsymbol">y</span>
149	<script>explorer.outline.addDecl('y');</script>
150
151	;
152	</span></dt>
153	<script>explorer.outline.writeEnabled = false;</script>
154
155
156	<dd>Components of vector.
157	<br><br>
158
159	</dd>
160
161	<script>explorer.outline.writeEnabled = true;</script>
162	<dt><span class="decl">Vector2
163	<span class="currsymbol">nan</span>
164	<script>explorer.outline.addDecl('nan');</script>
165
166	;
167	</span></dt>
168	<script>explorer.outline.writeEnabled = false;</script>
169
170
171	<dd>Vector with both components seted to NaN.
172	<br><br>
173
174	</dd>
175
176	<script>explorer.outline.writeEnabled = true;</script>
177	<dt><span class="decl">Vector2
178	<span class="currsymbol">unitX</span>
179	<script>explorer.outline.addDecl('unitX');</script>
180
181	;
182	<br>Vector2
183	<span class="currsymbol">unitY</span>
184	<script>explorer.outline.addDecl('unitY');</script>
185
186	;
187	</span></dt>
188	<script>explorer.outline.writeEnabled = false;</script>
189
190
191	<dd>Unit vector codirectional with corresponding axis.
192	<br><br>
193
194	</dd>
195
196	<script>explorer.outline.writeEnabled = true;</script>
197	<dt><span class="decl">Vector2
198	<span class="currsymbol">opCall</span>
199	<script>explorer.outline.addDecl('opCall');</script>
200
201	(float_t <span class="funcparam">x</span>, float_t <span class="funcparam">y</span>);
202	</span></dt>
203	<script>explorer.outline.writeEnabled = false;</script>
204
205
206	<dd>Method to construct vector in C-like syntax.
207	<br><br>
208	<b>Examples:</b><br>
209	<pre class="d_code"> Vector2 myVector = Vector2(1, 2);
210	</pre>
211
212	<br><br>
213
214	</dd>
215
216	<script>explorer.outline.writeEnabled = true;</script>
217	<dt><span class="decl">void
218	<span class="currsymbol">set</span>
219	<script>explorer.outline.addDecl('set');</script>
220
221	(float_t <span class="funcparam">x</span>, float_t <span class="funcparam">y</span>);
222	</span></dt>
223	<script>explorer.outline.writeEnabled = false;</script>
224
225
226	<dd>Sets values of components to passed values.
227	<br><br>
228
229	</dd>
230
231	<script>explorer.outline.writeEnabled = true;</script>
232	<dt><span class="decl">real
233	<span class="currsymbol">norm</span>
234	<script>explorer.outline.addDecl('norm');</script>
235
236	();
237	</span></dt>
238	<script>explorer.outline.writeEnabled = false;</script>
239
240
241	<dd><b>Returns:</b><br>
242	Norm (also known as length, magnitude) of vector.
243	<br><br>
244
245	</dd>
246
247	<script>explorer.outline.writeEnabled = true;</script>
248	<dt><span class="decl">real
249	<span class="currsymbol">normSquare</span>
250	<script>explorer.outline.addDecl('normSquare');</script>
251
252	();
253	</span></dt>
254	<script>explorer.outline.writeEnabled = false;</script>
255
256
257	<dd><b>Returns:</b><br>
258	Square of vector's norm.
259	<br><br>
260
261	Since this method doesn't need calculation of square root it is better
262	to use it instead of norm() when you can. For example, if you want just
263	to know which of 2 vectors is longer it's better to compare their norm
264	squares instead of their norm.
265
266	<br><br>
267
268	</dd>
269
270	<script>explorer.outline.writeEnabled = true;</script>
271	<dt><span class="decl">void
272	<span class="currsymbol">normalize</span>
273	<script>explorer.outline.addDecl('normalize');</script>
274
275	();
276	</span></dt>
277	<script>explorer.outline.writeEnabled = false;</script>
278
279
280	<dd>Normalizes this vector.
281	<br><br>
282
283	</dd>
284
285	<script>explorer.outline.writeEnabled = true;</script>
286	<dt><span class="decl">Vector2
287	<span class="currsymbol">normalized</span>
288	<script>explorer.outline.addDecl('normalized');</script>
289
290	();
291	</span></dt>
292	<script>explorer.outline.writeEnabled = false;</script>
293
294
295	<dd><b>Returns:</b><br>
296	Normalized copy of this vector.
297	<br><br>
298
299	</dd>
300
301	<script>explorer.outline.writeEnabled = true;</script>
302	<dt><span class="decl">bool
303	<span class="currsymbol">isUnit</span>
304	<script>explorer.outline.addDecl('isUnit');</script>
305
306	(int <span class="funcparam">relprec</span> = defrelprec, int <span class="funcparam">absprec</span> = defabsprec);
307	</span></dt>
308	<script>explorer.outline.writeEnabled = false;</script>
309
310
311	<dd><b>Returns:</b><br>
312	Whether this vector is unit.
313	<br><br>
314	<b>Params:</b><br>
315	<table></table><br>
316
317	</dd>
318
319	<script>explorer.outline.writeEnabled = true;</script>
320	<dt><span class="decl">Ort
321	<span class="currsymbol">dominatingAxis</span>
322	<script>explorer.outline.addDecl('dominatingAxis');</script>
323
324	();
325	</span></dt>
326	<script>explorer.outline.writeEnabled = false;</script>
327
328
329	<dd><b>Returns:</b><br>
330	Axis for which projection of this vector on it will be longest.
331	<br><br>
332
333	</dd>
334
335	<script>explorer.outline.writeEnabled = true;</script>
336	<dt><span class="decl">bool
337	<span class="currsymbol">isnormal</span>
338	<script>explorer.outline.addDecl('isnormal');</script>
339
340	();
341	</span></dt>
342	<script>explorer.outline.writeEnabled = false;</script>
343
344
345	<dd><b>Returns:</b><br>
346	Whether all components are normalized numbers.
347	<br><br>
348
349	</dd>
350
351	<script>explorer.outline.writeEnabled = true;</script>
352	<dt><span class="decl">float_t*
353	<span class="currsymbol">ptr</span>
354	<script>explorer.outline.addDecl('ptr');</script>
355
356	();
357	</span></dt>
358	<script>explorer.outline.writeEnabled = false;</script>
359
360
361	<dd><b>Returns:</b><br>
362	float_t pointer to x component of this vector. It's like a ptr method for arrays.
363	<br><br>
364
365	</dd>
366
367	<script>explorer.outline.writeEnabled = true;</script>
368	<dt><span class="decl">float_t
369	<span class="currsymbol">opIndex</span>
370	<script>explorer.outline.addDecl('opIndex');</script>
371
372	(Ort <span class="funcparam">ort</span>);
373	</span></dt>
374	<script>explorer.outline.writeEnabled = false;</script>
375
376
377	<dd><b>Returns:</b><br>
378	Component corresponded to passed index.
379	<br><br>
380
381	</dd>
382
383	<script>explorer.outline.writeEnabled = true;</script>
384	<dt><span class="decl">void
385	<span class="currsymbol">opIndexAssign</span>
386	<script>explorer.outline.addDecl('opIndexAssign');</script>
387
388	(float_t <span class="funcparam">value</span>, Ort <span class="funcparam">ort</span>);
389	</span></dt>
390	<script>explorer.outline.writeEnabled = false;</script>
391
392
393	<dd>Assigns new value to component corresponded to passed index.
394	<br><br>
395
396	</dd>
397
398	<script>explorer.outline.writeEnabled = true;</script>
399	<dt><span class="decl">bool
400	<span class="currsymbol">opEquals</span>
401	<script>explorer.outline.addDecl('opEquals');</script>
402
403	(Vector2 <span class="funcparam">v</span>);
404	<br>Vector2
405	<span class="currsymbol">opNeg</span>
406	<script>explorer.outline.addDecl('opNeg');</script>
407
408	();
409	<br>Vector2
410	<span class="currsymbol">opAdd</span>
411	<script>explorer.outline.addDecl('opAdd');</script>
412
413	(Vector2 <span class="funcparam">v</span>);
414	<br>void
415	<span class="currsymbol">opAddAssign</span>
416	<script>explorer.outline.addDecl('opAddAssign');</script>
417
418	(Vector2 <span class="funcparam">v</span>);
419	<br>Vector2
420	<span class="currsymbol">opSub</span>
421	<script>explorer.outline.addDecl('opSub');</script>
422
423	(Vector2 <span class="funcparam">v</span>);
424	<br>void
425	<span class="currsymbol">opSubAssign</span>
426	<script>explorer.outline.addDecl('opSubAssign');</script>
427
428	(Vector2 <span class="funcparam">v</span>);
429	<br>Vector2
430	<span class="currsymbol">opMul</span>
431	<script>explorer.outline.addDecl('opMul');</script>
432
433	(real <span class="funcparam">k</span>);
434	<br>void
435	<span class="currsymbol">opMulAssign</span>
436	<script>explorer.outline.addDecl('opMulAssign');</script>
437
438	(real <span class="funcparam">k</span>);
439	<br>Vector2
440	<span class="currsymbol">opMul_r</span>
441	<script>explorer.outline.addDecl('opMul_r');</script>
442
443	(real <span class="funcparam">k</span>);
444	<br>Vector2
445	<span class="currsymbol">opDiv</span>
446	<script>explorer.outline.addDecl('opDiv');</script>
447
448	(real <span class="funcparam">k</span>);
449	<br>void
450	<span class="currsymbol">opDivAssign</span>
451	<script>explorer.outline.addDecl('opDivAssign');</script>
452
453	(real <span class="funcparam">k</span>);
454	</span></dt>
455	<script>explorer.outline.writeEnabled = false;</script>
456
457
458	<dd>Standard operators that have intuitive meaning, same as in classical math.
459	<br><br>
460	Note that division operators do no cheks of value of k, so in case of division
461	by 0 result vector will have infinity components. You can check this with isnormal()
462	method.
463
464	<br><br>
465
466	</dd>
467
468	<script>explorer.outline.writeEnabled = true;</script>
469	<dt><span class="decl">Vector2f
470	<span class="currsymbol">toVector2f</span>
471	<script>explorer.outline.addDecl('toVector2f');</script>
472
473	();
474	</span></dt>
475	<script>explorer.outline.writeEnabled = false;</script>
476
477
478	<dd><b>Returns:</b><br>
479	Copy of this vector with float type components
480	<br><br>
481
482	</dd>
483
484	<script>explorer.outline.writeEnabled = true;</script>
485	<dt><span class="decl">Vector2d
486	<span class="currsymbol">toVector2d</span>
487	<script>explorer.outline.addDecl('toVector2d');</script>
488
489	();
490	</span></dt>
491	<script>explorer.outline.writeEnabled = false;</script>
492
493
494	<dd><b>Returns:</b><br>
495	Copy of this vector with double type components
496	<br><br>
497
498	</dd>
499
500	<script>explorer.outline.writeEnabled = true;</script>
501	<dt><span class="decl">Vector2r
502	<span class="currsymbol">toVector2r</span>
503	<script>explorer.outline.addDecl('toVector2r');</script>
504
505	();
506	</span></dt>
507	<script>explorer.outline.writeEnabled = false;</script>
508
509
510	<dd><b>Returns:</b><br>
511	Copy of this vector with real type components
512	<br><br>
513
514	</dd>
515
516	<script>explorer.outline.writeEnabled = true;</script>
517	<dt><span class="decl">Vector3
518	<span class="currsymbol">xy0</span>
519	<script>explorer.outline.addDecl('xy0');</script>
520
521	();
522	<br>Vector3
523	<span class="currsymbol">x0y</span>
524	<script>explorer.outline.addDecl('x0y');</script>
525
526	();
527	</span></dt>
528	<script>explorer.outline.writeEnabled = false;</script>
529
530
531	<dd>Routines known as swizzling.
532	<br><br>
533	<b>Returns:</b><br>
534	New vector constructed from this one and having component values
535	that correspond to method name.
536
537	<br><br>
538
539	</dd>
540	</dl>
541	<script>explorer.outline.decSymbolLevel();</script>
542
543
544	</dd>
545
546	<script>explorer.outline.writeEnabled = true;</script>
547	<dt><span class="decl">real
548	<span class="currsymbol">dp</span>
549	<script>explorer.outline.addDecl('dp');</script>
550
551	(Vector2 <span class="funcparam">a</span>, Vector2 <span class="funcparam">b</span>);
552	</span></dt>
553	<script>explorer.outline.writeEnabled = false;</script>
554
555
556	<dd><b>Returns:</b><br>
557	Dot product between passed vectors.
558	<br><br>
559
560	</dd>
561
562	<script>explorer.outline.writeEnabled = true;</script>
563	<dt><span class="decl">alias
564	<span class="currsymbol">equal</span>
565	<script>explorer.outline.addDecl('equal');</script>
566
567	;
568	</span></dt>
569	<script>explorer.outline.writeEnabled = false;</script>
570
571
572	<dd>Introduces approximate equality function for Vector2.
573	<br><br>
574
575	</dd>
576
577	<script>explorer.outline.writeEnabled = true;</script>
578	<dt><span class="decl">alias
579	<span class="currsymbol">lerp</span>
580	<script>explorer.outline.addDecl('lerp');</script>
581
582	;
583	</span></dt>
584	<script>explorer.outline.writeEnabled = false;</script>
585
586
587	<dd>Introduces linear interpolaton function for Vector2.
588	<br><br>
589
590	</dd>
591
592	<script>explorer.outline.writeEnabled = true;</script>
593	<dt><span class="decl">struct
594	<span class="currsymbol">Vector3</span>
595	<script>explorer.outline.addDecl('Vector3');</script>
596
597	;
598	</span></dt>
599	<script>explorer.outline.writeEnabled = false;</script>
600
601
602	<dd>Three dimensional vector.
603	<br><br>
604	For formal definition of vector, meaning of possible operations and related
605	information see <a href="http://en.wikipedia.org/wiki/Vector_(spatial)">http://en.wikipedia.org/wiki/Vector_(spatial)</a>.
606
607	<br><br>
608
609
610	<script>explorer.outline.incSymbolLevel();</script>
611	<dl>
612	<script>explorer.outline.writeEnabled = true;</script>
613	<dt><span class="decl">float_t
614	<span class="currsymbol">x</span>
615	<script>explorer.outline.addDecl('x');</script>
616
617	;
618	<br>float_t
619	<span class="currsymbol">y</span>
620	<script>explorer.outline.addDecl('y');</script>
621
622	;
623	<br>float_t
624	<span class="currsymbol">z</span>
625	<script>explorer.outline.addDecl('z');</script>
626
627	;
628	</span></dt>
629	<script>explorer.outline.writeEnabled = false;</script>
630
631
632	<dd>Components of vector.
633	<br><br>
634
635	</dd>
636
637	<script>explorer.outline.writeEnabled = true;</script>
638	<dt><span class="decl">Vector3
639	<span class="currsymbol">nan</span>
640	<script>explorer.outline.addDecl('nan');</script>
641
642	;
643	</span></dt>
644	<script>explorer.outline.writeEnabled = false;</script>
645
646
647	<dd>Vector with all components seted to NaN.
648	<br><br>
649
650	</dd>
651
652	<script>explorer.outline.writeEnabled = true;</script>
653	<dt><span class="decl">Vector3
654	<span class="currsymbol">unitX</span>
655	<script>explorer.outline.addDecl('unitX');</script>
656
657	;
658	<br>Vector3
659	<span class="currsymbol">unitY</span>
660	<script>explorer.outline.addDecl('unitY');</script>
661
662	;
663	<br>Vector3
664	<span class="currsymbol">unitZ</span>
665	<script>explorer.outline.addDecl('unitZ');</script>
666
667	;
668	</span></dt>
669	<script>explorer.outline.writeEnabled = false;</script>
670
671
672	<dd>Unit vector codirectional with corresponding axis.
673	<br><br>
674
675	</dd>
676
677	<script>explorer.outline.writeEnabled = true;</script>
678	<dt><span class="decl">Vector3
679	<span class="currsymbol">opCall</span>
680	<script>explorer.outline.addDecl('opCall');</script>
681
682	(float_t <span class="funcparam">x</span>, float_t <span class="funcparam">y</span>, float_t <span class="funcparam">z</span>);
683	</span></dt>
684	<script>explorer.outline.writeEnabled = false;</script>
685
686
687	<dd>Method to construct vector in C-like syntax.
688	<br><br>
689	<b>Examples:</b><br>
690	<pre class="d_code"> Vector3 myVector = Vector3(1, 2, 3);
691	</pre>
692
693	<br><br>
694
695	</dd>
696
697	<script>explorer.outline.writeEnabled = true;</script>
698	<dt><span class="decl">void
699	<span class="currsymbol">set</span>
700	<script>explorer.outline.addDecl('set');</script>
701
702	(float_t <span class="funcparam">x</span>, float_t <span class="funcparam">y</span>, float_t <span class="funcparam">z</span>);
703	</span></dt>
704	<script>explorer.outline.writeEnabled = false;</script>
705
706
707	<dd>Sets values of components to passed values.
708	<br><br>
709
710	</dd>
711
712	<script>explorer.outline.writeEnabled = true;</script>
713	<dt><span class="decl">real
714	<span class="currsymbol">norm</span>
715	<script>explorer.outline.addDecl('norm');</script>
716
717	();
718	</span></dt>
719	<script>explorer.outline.writeEnabled = false;</script>
720
721
722	<dd><b>Returns:</b><br>
723	Norm (also known as length, magnitude) of vector.
724	<br><br>
725
726	</dd>
727
728	<script>explorer.outline.writeEnabled = true;</script>
729	<dt><span class="decl">real
730	<span class="currsymbol">normSquare</span>
731	<script>explorer.outline.addDecl('normSquare');</script>
732
733	();
734	</span></dt>
735	<script>explorer.outline.writeEnabled = false;</script>
736
737
738	<dd><b>Returns:</b><br>
739	Square of vector's norm.
740	<br><br>
741
742	Since this method doesn't need calculation of square root it is better
743	&nbs

helix

root/trunk/doc/linalgebra.html