source: project/wiki/eggref/4/gl-math @ 31310

Last change on this file since 31310 was 31310, checked in by acharlton, 7 years ago

wiki/gl-math: Update to 0.4.1

File size: 15.8 KB
Line 
1
2== gl-math
3[[toc:]]
4A very small math library for gamedev that mostly provides 4x4 float matrix operations. Uses the [[https://github.com/AlexCharlton/hypermath|hypermath]] library.
5
6
7=== Requirements
8* matchable
9
10
11=== Documentation
12gl-math provides a number of functions for working with 4x4 matrices (plus a handful of others). The functionality is similar to what can be found in the [[http://wiki.call-cc.org/eggref/4/glm|glm egg]], but with some notable differences:
13
14* Matrix functions only operate on 4x4 matrices
15* Matrix functions can accept either f32vectors or pointers
16* No container is used to represent matrices
17
18Additionally, gl-math is one fifth the compiled size of glm, has a more straight-forward code-base, and complete documentation.
19
20gl-math expects matrices to be f32vectors or pointers. f32vectors must be 16 elements long. The memory pointed to should likewise be an array of 16 floats. If a function accepts more than one matrix, all matrices must be of the same type.
21
22gl-math operates on matrices in a column-major fashion in correspondence with OpenGL (e.g. translation components are at indices 12, 13, and 14).
23
24
25==== Matrix operations
26<procedure> (print-mat4 MATRIX)</procedure>
27
28Prints the given {{MATRIX}} to {{(current-output-port)}}.
29
30<procedure> (copy-mat4 MATRIX [RESULT])</procedure>
31
32Make a copy of {{MATRIX}}. If the matrix {{RESULT}} is given, it will be modified to contain the contents of {{MATRIX}}. If {{RESULT}} is {{#t}}, {{MATRIX}} must be an f32vector and the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, {{MATRIX}} must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.
33
34<procedure> (m* A B [RESULT])</procedure>
35
36Multiply matrix {{A}} by matrix {{B}}. If the matrix {{RESULT}} is given, it will be modified to contain the results of the multiplication. If {{RESULT}} is {{#t}}, {{A}} and {{B}} must be f32vectors and the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, {{A}} and {{B}} must be f32vectors and the returned value will be an f32vector located in normal garbage collected memory.
37
38<procedure> (mat4-identity [RESULT])</procedure>
39
40Return an identity matrix. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
41
42<procedure> (translation X Y Z [RESULT])</procedure>
43
44Return the translation matrix given by {{X}}, {{Y}}, and {{Z}}. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
45
46<procedure> (translate X Y Z MATRIX)</procedure>
47
48Translate {{MATRIX}} by {{X}}, {{Y}}, and {{Z}}.
49
50    void hpmXRotation(float rotation, float *mat);
51
52Create the rotation matrix of {{rotation}} radians around the X-axis in the given matrix.
53
54<procedure> (x-rotation ANGLE [RESULT])</procedure>
55
56Return the rotation matrix given by a rotation of {{ANGLE}} radians around the x-axis. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
57
58<procedure> (rotate-x ANGLE MATRIX)</procedure>
59
60Rotate {{MATRIX}} around the x-axis by {{ANGLE}} radians.
61
62<procedure> (y-rotation ANGLE [RESULT])</procedure>
63
64Return the rotation matrix given by a rotation of {{ANGLE}} radians around the y-axis. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
65
66<procedure> (rotate-y ANGLE MATRIX)</procedure>
67
68Rotate {{MATRIX}} around the y-axis by {{ANGLE}} radians.
69
70<procedure> (z-rotation ANGLE [RESULT])</procedure>
71
72Return the rotation matrix given by a rotation of {{ANGLE}} radians around the z-axis. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
73
74<procedure> (rotate-z ANGLE MATRIX)</procedure>
75
76Rotate {{MATRIX}} around the z-axis by {{ANGLE}} radians.
77
78<procedure> (rotation X Y Z ANGLE [RESULT])</procedure>
79
80Return the rotation matrix given by a rotation of {{ANGLE}} radians around the vector {{(X, Y, Z)}}. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
81
82<procedure> (rotate X Y Z ANGLE MATRIX)</procedure>
83
84Rotate {{MATRIX}} around the vector {{(X, Y, Z)}} by {{ANGLE}} radians.
85
86<procedure> (quaternion-rotation X Y Z W [RESULT])</procedure>
87
88Return the rotation matrix given by the quaternion {{(X, Y, Z, Q)}}. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
89
90<procedure> (rotate-quaternion X Y Z W MATRIX)</procedure>
91
92Rotate {{MATRIX}} by the quaternion {{(X, Y, Z, Q)}}.
93
94<procedure> (ypr-rotation YAW PITCH ROLL [RESULT])</procedure>
95
96Return the rotation matrix given by rotating by {{ROLL}} radians followed by {{PITCH}} radians followed by {{YAW}} radians. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
97
98<procedure> (rotate-ypr YAW PITCH ROLL MATRIX)</procedure>
99
100Rotate {{MATRIX}} by {{ROLL}} radians followed by {{PITCH}} radians followed by {{YAW}} radians.
101
102<procedure> (2d-scaling SCALE-X SCALE-Y [RESULT])</procedure>
103
104Return the matrix created by scaling the x and y axes by {{SCALE-X}} and {{SCALE-Y}}. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
105
106<procedure> (scale-2d SCALE-X SCALE-Y MATRIX)</procedure>
107
108Scale the x and y axis of {{MATRIX}} by {{SCALE-X}} and {{SCALE-Y}}.
109
110<procedure> (3d-scaling SCALE-X SCALE-Y SCALE-Z [RESULT])</procedure>
111
112Return the matrix created by scaling the x, y and z axes by {{SCALE-X}}, {{SCALE-Y}}, and {{SCALE-Z}}. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
113
114<procedure> (scale-3d SCALE-X SCALE-Y SCALE-Z MATRIX)</procedure>
115
116Scale the x, y, and z axis of {{MATRIX}} by {{SCALE-X}}, {{SCALE-Y}}, and {{SCALE-Z}}.
117
118<procedure> (scaling SCALE [RESULT])</procedure>
119
120Return the matrix created by scaling the x, y and z axes by {{SCALE}}. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
121
122<procedure> (scale SCALE MATRIX)</procedure>
123
124Scale the x, y, and z axis of {{MATRIX}} by {{SCALE}}.
125
126<procedure> (flip-x MATRIX)</procedure>
127
128Flip (mirror) {{MATRIX}} along the x-axis.
129
130<procedure> (flip-y MATRIX)</procedure>
131
132Flip (mirror) {{MATRIX}} along the y-axis.
133
134<procedure> (flip-z MATRIX)</procedure>
135
136Flip (mirror) {{MATRIX}} along the z-axis.
137
138<procedure> (translate-rotate-scale-2d X Y Z ANGLE SCALE [RESULT])</procedure>
139
140Efficiently create a matrix translated by {{X}}, {{Y}}, and {{Z}}, rotated around the z-axis by {{ANGLE}} radians, then scaled by {{SCALE}}. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
141
142<procedure> (transpose MATRIX [RESULT])</procedure>
143
144Transpose {{MATRIX}}. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is {{#t}}, {{MATRIX}} must be an f32vector and the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, {{MATRIX}} must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.
145
146<procedure> (inverse MATRIX [RESULT])</procedure>
147
148Invert {{MATRIX}}. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is {{#t}}, {{MATRIX}} must be an f32vector and the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, {{MATRIX}} must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.
149
150
151==== Perspective matrices
152<procedure> (ortho WIDTH HEIGHT NEAR FAR [RESULT])</procedure>
153
154Create an orthographic projection matrix. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
155
156<procedure> (perspective WIDTH HEIGHT NEAR FAR ANGLE [RESULT])</procedure>
157
158Create an perspective projection matrix. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
159
160<procedure> (frustum LEFT RIGHT BOTTOM TOP NEAR FAR [RESULT])</procedure>
161
162Create a view-frustum matrix. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
163
164
165==== Camera functions
166<procedure> (look-at EYE-X EYE-Y EYE-Z X Y Z UP-X UP-Y UP-Z [RESULT])</procedure>
167
168Create a “look-at” style camera matrix. The camera is positioned at {{(EYE-X, EYE-Y, EYE-Z)}}, pointing towards {{(X, Y, Z)}}. {{(UP-X, UP-Y, UP-Z)}} defines the camera’s up vector. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is {{#t}}, the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, the returned value will be an f32vector located in normal garbage collected memory.
169
170<procedure> (camera-inverse CAMERA [RESULT])</procedure>
171
172Invert {{CAMERA}} in an efficient fashion. This allows the camera to be constructed in an intuitive fashion by translating and rotating before inverting in order to position the scene properly. This function is far faster than the general {{inverse}} function, but the matrix {{CAMERA}} must only be a matrix representing a translation and a rotation (no scaling). If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is {{#t}}, {{CAMERA}} must be an f32vector and the returned value will be an f32vector located in non-garbage collected memory (the memory will still be freed when there are no more references to the matrix). If {{RESULT}} is not provided, {{CAMERA}} must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.
173
174
175==== Vector operations
176<procedure> (cross-product AX AY AZ BX BY BZ)</procedure>
177
178Return the result of the cross product between the vectors {{(AX, AY, AZ)}} and {{(BX, BY, BZ)}}. The resulting vector is returned as three values.
179
180<procedure> (dot-product AX AY AZ BX BY BZ)</procedure>
181
182Return the result of the dot product between the vectors {{(AX, AY, AZ)}} and {{(BX, BY, BZ)}}.
183
184<procedure> (normalize X Y Z)</procedure>
185
186Return the normalized vector {{(X, Y, Z)}}. The resulting vector is returned as three values.
187
188<procedure> (m*vector! MATRIX VECTOR)</procedure>
189
190Destructively multiply the 3 element f32vector {{VECTOR}} by {{MATRIX}}.
191
192<procedure> (m*vector-array! MATRIX VECTORS stride: [STRIDE] length: [LENGTH])</procedure>
193
194Destructively multiply the array of 3 element floats {{VECTORS}} by {{MATRIX}}. The keyword {{STRIDE}} specifies the number of elements between consecutive vectors, given in number of floats (which must be at least 3). {{VECTORS}} may be given as an f32vector or a pointer. When given as a pointer, the keyword {{LENGTH}} must be provided, specifying the number of vectors in {{VECTORS}}.
195
196
197==== Angle operations
198<procedure> (degrees->radians ANGLE)</procedure>
199
200Converts {{ANGLE}} from degrees to radians.
201
202<procedure> (radians->degrees ANGLE)</procedure>
203
204Converts {{ANGLE}} from radians to degrees.
205
206
207=== Example
208<enscript highlight="scheme">    
209(import chicken scheme)
210(use gl-math)
211
212(define projection-matrix
213  (perspective 640 480 0.1 100 70))
214
215(define view-matrix
216  (look-at 1 0 3
217           0 0 0
218           0 1 0))
219
220(define model-matrix (mat4-identity))
221
222(print-mat4 (m* projection-matrix
223                (m* view-matrix model-matrix)))
224</enscript>
225
226
227=== Version history
228
229==== Version 0.4.1
23030 August 2014
231
232* Fix {{m*vector-array!}}
233
234'''Version 0.4.0'''
235
23627 July 2014
237
238* Add {{copy-mat4}}
239
240
241==== Version 0.3.2
24221 July 2014
243
244* Allow pointer to array of vectors to be passed to {{m*vector-array!}}
245* Fix error forms
246
247'''Version 0.3.1'''
248
24923 June 2014
250
251* Matrix vector multiplication
252
253
254==== Version 0.2.0
25521 June 2014
256
257* Each transformation function now has two variants: one that initializes a matrix, and one that operates on a matrix
258* Provide {{pi/2}}
259* Provide quaternion and YPR rotation
260* Remove unhelpful composite operations
261* Fix optional arguments for matrix operations
262* Fix a bug in {{look-at}}
263
264
265==== Version 0.1.0
26617 June 2014
267
268* Initial release
269
270
271=== Source repository
272Source available on [[https://github.com/AlexCharlton/gl-math|GitHub]].
273
274Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
275
276
277=== Author
278Alex Charlton
279
280
281=== Licence
282BSD
Note: See TracBrowser for help on using the repository browser.