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

Last change on this file since 32663 was 32663, checked in by acharlton, 5 years ago

wiki/gl-math: Update to 0.8.0

File size: 29.7 KB
Line 
1== gl-math
2[[toc:]]
3A small math library aimed at gamedev that provides 4x4 float matrix, vector, and quaternion operations. Uses the [[https://github.com/AlexCharlton/hypermath|hypermath]] library.
4
5
6=== Requirements
7* matchable
8
9
10=== Documentation
11gl-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:
12
13* Matrix functions only operate on 4x4 matrices
14* Matrix functions can accept either f32vectors or pointers
15* No container is used to represent matrices
16
17Additionally, gl-math is one fifth the compiled size of glm, has a more straight-forward code-base, and complete documentation.
18
19gl-math expects matrices, vectors, and quaternions to be f32vectors or pointers. f32vectors must be 16 elements long, 3 elements long, or 4 elements long for matrices, vectors, or quaternions, respectively. The memory pointed to should likewise be an array of 16, 3, or 4 floats . If a function accepts more than one matrix, vector, or quaternion, all must be of the same type.
20
21gl-math operates on matrices in a column-major fashion in correspondence with OpenGL (e.g. translation components are at indices 12, 13, and 14). Vectors are arranged as ({{(x y z)}}), and quaternions as ({{(x y z w)}}).
22
23
24==== Matrix operations
25<procedure> (print-mat4 MATRIX)</procedure>
26
27Prints the given {{MATRIX}} to {{(current-output-port)}}.
28
29<procedure> (copy-mat4 MATRIX [RESULT])</procedure>
30
31Make 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.
32
33<procedure> (m* A B [RESULT])</procedure>
34
35Multiply 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.
36
37<procedure> (m*s A S [RESULT])</procedure>
38
39Multiply matrix {{A}} by scalar {{S}}. If the matrix {{RESULT}} is given, it will be modified to contain the results of the multiplication. If {{RESULT}} is {{#t}}, {{A}} 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, {{A}} must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.
40
41<procedure> (m+ A B [RESULT])</procedure>
42
43Add matrix {{A}} with 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.
44
45<procedure> (m- A B [RESULT])</procedure>
46
47Subtract matrix {{B}} from matrix {{A}}. 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.
48
49<procedure> (mat4-identity [RESULT])</procedure>
50
51Return 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.
52
53<procedure> (translation VECTOR [RESULT])</procedure>
54
55Return the translation matrix given by {{VECTOR}}. 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.
56
57<procedure> (translate VECTOR MATRIX)</procedure>
58
59Translate {{MATRIX}} by {{VECTOR}}.
60
61<procedure> (x-rotation ANGLE [RESULT])</procedure>
62
63Return 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.
64
65<procedure> (rotate-x ANGLE MATRIX)</procedure>
66
67Rotate {{MATRIX}} around the x-axis by {{ANGLE}} radians.
68
69<procedure> (y-rotation ANGLE [RESULT])</procedure>
70
71Return 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.
72
73<procedure> (rotate-y ANGLE MATRIX)</procedure>
74
75Rotate {{MATRIX}} around the y-axis by {{ANGLE}} radians.
76
77<procedure> (z-rotation ANGLE [RESULT])</procedure>
78
79Return 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.
80
81<procedure> (rotate-z ANGLE MATRIX)</procedure>
82
83Rotate {{MATRIX}} around the z-axis by {{ANGLE}} radians.
84
85<procedure> (axis-angle-rotation AXIS ANGLE [RESULT])</procedure>
86
87Return the rotation matrix given by a rotation of {{ANGLE}} radians around the vector {{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.
88
89<procedure> (rotate-axis-angle AXIS ANGLE MATRIX)</procedure>
90
91Rotate {{MATRIX}} around the vector {{AXIS}} by {{ANGLE}} radians.
92
93<procedure> (quaternion-rotation Q [RESULT])</procedure>
94
95Return the rotation matrix given by the quaternion {{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.
96
97<procedure> (rotate-quaternion Q MATRIX)</procedure>
98
99Rotate {{MATRIX}} by the quaternion {{Q}}.
100
101<procedure> (ypr-rotation YAW PITCH ROLL [RESULT])</procedure>
102
103Return the rotation matrix given by rotating by {{ROLL}} radians around the z-axis followed by {{PITCH}} radians around the x-axis followed by {{YAW}} 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.
104
105<procedure> (rotate-ypr YAW PITCH ROLL MATRIX)</procedure>
106
107Rotate {{MATRIX}} by {{ROLL}} radians around the z-axis followed by {{PITCH}} radians around the x-axis followed by {{YAW}} radians around the y-axis.
108
109<procedure> (2d-scaling SCALE-X SCALE-Y [RESULT])</procedure>
110
111Return 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.
112
113<procedure> (scale-2d SCALE-X SCALE-Y MATRIX)</procedure>
114
115Scale the x and y axis of {{MATRIX}} by {{SCALE-X}} and {{SCALE-Y}}.
116
117<procedure> (3d-scaling SCALE-X SCALE-Y SCALE-Z [RESULT])</procedure>
118
119Return 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.
120
121<procedure> (scale-3d SCALE-X SCALE-Y SCALE-Z MATRIX)</procedure>
122
123Scale the x, y, and z axis of {{MATRIX}} by {{SCALE-X}}, {{SCALE-Y}}, and {{SCALE-Z}}.
124
125<procedure> (scaling SCALE [RESULT])</procedure>
126
127Return 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.
128
129<procedure> (scale SCALE MATRIX)</procedure>
130
131Scale the x, y, and z axis of {{MATRIX}} by {{SCALE}}.
132
133<procedure> (flip-x MATRIX)</procedure>
134
135Flip (mirror) {{MATRIX}} along the x-axis.
136
137<procedure> (flip-y MATRIX)</procedure>
138
139Flip (mirror) {{MATRIX}} along the y-axis.
140
141<procedure> (flip-z MATRIX)</procedure>
142
143Flip (mirror) {{MATRIX}} along the z-axis.
144
145<procedure> (translate-rotate-scale-2d VECTOR ANGLE SCALE [RESULT])</procedure>
146
147Efficiently create a matrix translated by {{VECTOR}}, 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.
148
149<procedure> (transpose MATRIX [RESULT])</procedure>
150
151Transpose {{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.
152
153<procedure> (inverse MATRIX [RESULT])</procedure>
154
155Invert {{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.
156
157<procedure> (fast-inverse-transpose MATRIX [RESULT])</procedure>
158
159Efficiently inverse the transpose the unscaled {{MATRIX}}. If {{MATRIX}} has been scaled, this will produce incorrect results: {{inverse}} then {{transpose}} should be used instead. 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.
160
161
162==== Projection matrices
163<procedure> (ortho WIDTH HEIGHT NEAR FAR [RESULT])</procedure>
164
165Create 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.
166
167<procedure> (ortho-viewport LEFT RIGHT NEAR FAR VIEWPORT-LEFT VIEWPORT-RIGHT VIEWPORT-BOTTOM VIEWPORT-TOP [RESULT])</procedure>
168
169Create an orthographic projection matrix mapping the {{LEFT}}, {{RIGHT}}, {{TOP}}, {{BOTTOM}}, {{NEAR}}, {{FAR}} cube to a viewport of {{VIEWPORT-LEFT}}, {{VIEWPORT-RIGHT}}, {{VIEWPORT-TOP}}, {{VIEWPORT-BOTTOM}}. 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.
170
171<procedure> (perspective WIDTH HEIGHT NEAR FAR ANGLE [RESULT])</procedure>
172
173Create an perspective projection matrix with a field of view of {{ANGLE}} degrees. 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.
174
175<procedure> (frustum LEFT RIGHT BOTTOM TOP NEAR FAR [RESULT])</procedure>
176
177Create a perspective projection matrix defined by a frustum with a near side of {{LEFT}}, {{RIGHT}}, {{TOP}}, {{BOTTOM}}, {{NEAR}}, and a far side at {{FAR}}. 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.
178
179<procedure> (frustum-viewport LEFT RIGHT BOTTOM TOP NEAR FAR VIEWPORT-LEFT VIEWPORT-RIGHT VIEWPORT-BOTTOM VIEWPORT-TOP [RESULT])</procedure>
180
181Create a perspective projection matrix mapping the {{LEFT}}, {{RIGHT}}, {{TOP}}, {{BOTTOM}}, {{NEAR}}, {{FAR}} frustum to a viewport of {{VIEWPORT-LEFT}}, {{VIEWPORT-RIGHT}}, {{VIEWPORT-BOTTOM}}, {{VIEWPORT-TOP}}. 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.
182
183
184==== Camera functions
185<procedure> (look-at EYE OBJ UP [RESULT])</procedure>
186
187Create a “look-at” style camera matrix. The camera is positioned at point {{EYE}}, pointing towards the point {{OBJ}}. {{UP}} 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.
188
189<procedure> (camera-inverse CAMERA [RESULT])</procedure>
190
191Invert {{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.
192
193
194==== Vector operations
195<procedure> (make-point X Y Z [NON-GC?])</procedure>
196<procedure> (point-x POINT)</procedure>
197<procedure> (point-y POINT)</procedure>
198<procedure> (point-z POINT)</procedure>
199<procedure> (point-x-set! POINT)</procedure>
200<procedure> (point-y-set! POINT)</procedure>
201<procedure> (point-z-set! POINT)</procedure>
202
203Vector constructor, getters, and setters. If {{NON-GC?}} is {{#t}}, the point is created in a non-garbage-collected area (the memory will still be freed when there are no more references to the vector).
204
205<procedure> (v+ A B [RESULT])</procedure>
206
207Return the result of the addition of vectors {{A}} and {{B}}. If the vector {{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.
208
209<procedure> (v- A B [RESULT])</procedure>
210
211Return the result of the subtraction of vector {{B}} from {{A}}. If the vector {{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.
212
213<procedure> (v* V S [RESULT])</procedure>
214
215Return the result of the multiplication of vector {{A}} with scalar {{S}}. If the vector {{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.
216
217<procedure> (cross-product A B [RESULT])</procedure>
218
219Return the result of the cross product between the vectors {{A}} and {{B}}. If the vector {{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.
220
221<procedure> (dot-product A B)</procedure>
222
223Return the result of the dot product between the vectors {{A}} and {{B}}.
224
225<procedure> (vector-magnitude V)</procedure>
226
227Return the magnitude of vector {{V}}.
228
229<procedure> (normalize! V)</procedure>
230
231Destructively normalize the vector {{V}}.
232
233<procedure> (m*vector! MATRIX VECTOR)</procedure>
234
235Destructively multiply {{VECTOR}} by {{MATRIX}}.
236
237<procedure> (m*vector-array! MATRIX VECTORS stride: [STRIDE] length: [LENGTH])</procedure>
238
239Destructively multiply the array of 3 element floats {{VECTORS}} by {{MATRIX}}. {{VECTORS}} may be given as an f32vector, a u8vector or a pointer. The keyword {{STRIDE}} specifies the number of elements between consecutive vectors, given in number of floats (which must be at least 3) when {{VECTORS}} is an f32vector and in bytes when {{VECTORS}} is a u8vector or a pointer. When {{VECTORS}} is given as a pointer, the keyword {{LENGTH}} must be provided, specifying the number of vectors in {{VECTORS}}.
240
241<procedure> (lerp A B T [RESULT])</procedure>
242
243Linear interpolation between the points {{A}} and {{B}} with the interpolation parameter {{T}} which must be between 0 and 1. If the vector {{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.
244
245
246==== Quaternion operations
247Quaternions are expected to be normalized before they are used in certain functions ({{quaternion-normalize!}} may be used to do so). All the provided functions that create quaternions, create unit quaternions.
248
249The order of quaternion cross-multiplication is the inverse of the “standard” order, so a quaternion that has undergone a series or rotations will represent the same rotation as a marix that has gone through the same series, in the same order.
250
251<procedure> (make-quaternion X Y Z W [NON-GC?])</procedure>
252<procedure> (quaternion-x POINT)</procedure>
253<procedure> (quaternion-y POINT)</procedure>
254<procedure> (quaternion-z POINT)</procedure>
255<procedure> (quaternion-w POINT)</procedure>
256<procedure> (quaternion-x-set! POINT)</procedure>
257<procedure> (quaternion-y-set! POINT)</procedure>
258<procedure> (quaternion-z-set! POINT)</procedure>
259<procedure> (quaternion-w-set! POINT)</procedure>
260
261Quaternion constructor, getters, and setters. If {{NON-GC}} is {{#t}}, the quaternion is created in a non-garbage-collected area (the memory will still be freed when there are no more references to the quaternion).
262
263<procedure> (quaternion-normalize! Q)</procedure>
264
265Destructively normalize the quaternion {{Q}}.
266
267<procedure> (quaternion-inverse Q [RESULT])</procedure>
268
269Return the inverse of the unit quaternion {{Q}}. If the quaternion {{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.
270
271<procedure> (quaternion-cross-product A B [RESULT])</procedure>
272
273Return the cross-product of the quaternions {{A}} and {{B}}. If the quaternion {{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.
274
275<procedure> (quaternion-axis-angle-rotation AXIS ANGLE [RESULT])</procedure>
276
277Return the quaternion corresponding to a rotation of {{ANGLE}} radians around the vector {{AXIS}}. If the quaternion {{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.
278
279<procedure> (quaternion-rotate-axis-angle AXIS ANGLE Q)</procedure>
280
281Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the vector {{AXIS}}.
282
283<procedure> (quaternion-x-rotation ANGLE [RESULT])</procedure>
284
285Return the quaternion corresponding to a rotation of {{ANGLE}} radians around the x-axis. If the quaternion {{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.
286
287<procedure> (quaternion-rotate-x ANGLE Q)</procedure>
288
289Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the x-axis.
290
291<procedure> (quaternion-y-rotation ANGLE [RESULT])</procedure>
292
293Return the quaternion corresponding to a rotation of {{ANGLE}} radians around the y-axis. If the quaternion {{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.
294
295<procedure> (quaternion-rotate-y ANGLE Q)</procedure>
296
297Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the y-axis.
298
299<procedure> (quaternion-z-rotation ANGLE [RESULT])</procedure>
300
301Return the quaternion corresponding to a rotation of {{ANGLE}} radians around the z-axis. If the quaternion {{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.
302
303<procedure> (quaternion-rotate-z ANGLE Q)</procedure>
304
305Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the z-axis.
306
307<procedure> (quaternion-ypr-rotation YAW PITCH ROLL [RESULT])</procedure>
308
309Return the quaternion corresponding to a rotation of {{ROLL}} radians around the z-axis followed by {{PITCH}} radians around the x-axis followed by {{YAW}} radians around the y-axis. If the quaternion {{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.
310
311<procedure> (quaternion-rotate-ypr YAW PITCH ROLL Q)</procedure>
312
313Rotate the quaternion {{Q}} by {{ROLL}} radians around the z-axis followed by {{PITCH}} radians around the x-axis followed by {{YAW}} radians around the y-axis.
314
315<procedure> (quaternion-rotate-point! Q P)</procedure>
316
317Destructively rotate the point {{P}} by the unit quaternion {{Q}}.
318
319<procedure> (slerp A B T [RESULT])</procedure>
320
321Spherical linear interpolation between the quaternions {{A}} and {{B}} with the interpolation parameter {{T}} which must be between 0 and 1. If the quaternion {{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.
322
323
324==== Angle operations
325<procedure> (degrees->radians ANGLE)</procedure>
326
327Converts {{ANGLE}} from degrees to radians.
328
329<procedure> (radians->degrees ANGLE)</procedure>
330
331Converts {{ANGLE}} from radians to degrees.
332
333<constant> pi</constant>
334<constant> pi/2</constant>
335
336
337=== Example
338<enscript highlight="scheme">    
339(import chicken scheme)
340(use gl-math)
341
342(define projection-matrix
343  (perspective 640 480 0.1 100 70))
344
345(define view-matrix
346  (look-at (make-point 1 0 3)
347           (make-point 0 0 0)
348           (make-point 0 1 0)))
349
350(define model-matrix (mat4-identity))
351
352(print-mat4 (m* projection-matrix
353                (m* view-matrix model-matrix)))
354</enscript>
355
356
357=== Version history
358
359==== Version 0.8.0
3607 August 2014
361
362* Add {{m*}}, {{m+}}, {{m-}}
363
364
365==== Version 0.7.0
366* Add {{frustum}}, {{frustum-viewport}}
367
368
369==== Version 0.6.0
3708 October 2014
371
372* Add {{fast-inverse-transpose}}
373
374
375==== Version 0.5.2
37610 September 2014
377
378* {{m*vector-array!}}: Stride is given in bytes when vector is a pointer
379
380'''Version 0.5.0'''
381
3822 September 2014
383
384* Many new vector and quaternion functions
385* Functions that previously accepted vectors as individual floats, now accept them as f32vectors
386
387
388==== Version 0.4.1
38930 August 2014
390
391* Fix {{m*vector-array!}}
392
393'''Version 0.4.0'''
394
39527 July 2014
396
397* Add {{copy-mat4}}
398
399
400==== Version 0.3.2
40121 July 2014
402
403* Allow pointer to array of vectors to be passed to {{m*vector-array!}}
404* Fix error forms
405
406'''Version 0.3.1'''
407
40823 June 2014
409
410* Matrix vector multiplication
411
412
413==== Version 0.2.0
41421 June 2014
415
416* Each transformation function now has two variants: one that initializes a matrix, and one that operates on a matrix
417* Provide {{pi/2}}
418* Provide quaternion and YPR rotation
419* Remove unhelpful composite operations
420* Fix optional arguments for matrix operations
421* Fix a bug in {{look-at}}
422
423
424==== Version 0.1.0
42517 June 2014
426
427* Initial release
428
429
430=== Source repository
431Source available on [[https://github.com/AlexCharlton/gl-math|GitHub]].
432
433Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
434
435
436=== Author
437Alex Charlton
438
439
440=== Licence
441BSD
Note: See TracBrowser for help on using the repository browser.