# source:project/wiki/eggref/5/gl-math@37636

Last change on this file since 37636 was 37501, checked in by Kooda, 18 months ago

Update docs for C5 gl-math and hypergiant

File size: 29.9 KB
Line
1
2== gl-math
3[[toc:]]
4A small math library aimed at gamedev that provides 4x4 float matrix, vector, and quaternion operations. Uses the [[https://github.com/AlexCharlton/hypermath|hypermath]] library.
5
6
7=== Requirements
8* srfi-1
9* matchable
10
11
12=== Documentation
13gl-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:
14
15* Matrix functions only operate on 4x4 matrices
16* Matrix functions can accept either f32vectors or pointers
17* No container is used to represent matrices
18
19Additionally, gl-math is one fifth the compiled size of glm, has a more straight-forward code-base, and complete documentation.
20
21gl-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.
22
23gl-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)}}).
24
25
26==== Matrix operations
27<procedure> (print-mat4 MATRIX)</procedure>
28
29Prints the given {{MATRIX}} to {{(current-output-port)}}.
30
31<procedure> (copy-mat4 MATRIX [RESULT])</procedure>
32
33Make 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.
34
35<procedure> (m* A B [RESULT])</procedure>
36
37Multiply 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.
38
39<procedure> (m*s A S [RESULT])</procedure>
40
41Multiply 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.
42
43<procedure> (m+ A B [RESULT])</procedure>
44
45Add 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.
46
47<procedure> (m- A B [RESULT])</procedure>
48
49Subtract 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.
50
51<procedure> (mat4-identity [RESULT])</procedure>
52
53Return 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.
54
55<procedure> (translation VECTOR [RESULT])</procedure>
56
57Return 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.
58
59<procedure> (translate VECTOR MATRIX)</procedure>
60
61Translate {{MATRIX}} by {{VECTOR}}.
62
63<procedure> (x-rotation ANGLE [RESULT])</procedure>
64
65Return 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.
66
67<procedure> (rotate-x ANGLE MATRIX)</procedure>
68
69Rotate {{MATRIX}} around the x-axis by {{ANGLE}} radians.
70
71<procedure> (y-rotation ANGLE [RESULT])</procedure>
72
73Return 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.
74
75<procedure> (rotate-y ANGLE MATRIX)</procedure>
76
77Rotate {{MATRIX}} around the y-axis by {{ANGLE}} radians.
78
79<procedure> (z-rotation ANGLE [RESULT])</procedure>
80
81Return 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.
82
83<procedure> (rotate-z ANGLE MATRIX)</procedure>
84
85Rotate {{MATRIX}} around the z-axis by {{ANGLE}} radians.
86
87<procedure> (axis-angle-rotation AXIS ANGLE [RESULT])</procedure>
88
89Return 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.
90
91<procedure> (rotate-axis-angle AXIS ANGLE MATRIX)</procedure>
92
93Rotate {{MATRIX}} around the vector {{AXIS}} by {{ANGLE}} radians.
94
95<procedure> (quaternion-rotation Q [RESULT])</procedure>
96
97Return 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.
98
99<procedure> (rotate-quaternion Q MATRIX)</procedure>
100
101Rotate {{MATRIX}} by the quaternion {{Q}}.
102
103<procedure> (ypr-rotation YAW PITCH ROLL [RESULT])</procedure>
104
105Return 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.
106
107<procedure> (rotate-ypr YAW PITCH ROLL MATRIX)</procedure>
108
109Rotate {{MATRIX}} by {{ROLL}} radians around the z-axis followed by {{PITCH}} radians around the x-axis followed by {{YAW}} radians around the y-axis.
110
111<procedure> (2d-scaling SCALE-X SCALE-Y [RESULT])</procedure>
112
113Return 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.
114
115<procedure> (scale-2d SCALE-X SCALE-Y MATRIX)</procedure>
116
117Scale the x and y axis of {{MATRIX}} by {{SCALE-X}} and {{SCALE-Y}}.
118
119<procedure> (3d-scaling SCALE-X SCALE-Y SCALE-Z [RESULT])</procedure>
120
121Return 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.
122
123<procedure> (scale-3d SCALE-X SCALE-Y SCALE-Z MATRIX)</procedure>
124
125Scale the x, y, and z axis of {{MATRIX}} by {{SCALE-X}}, {{SCALE-Y}}, and {{SCALE-Z}}.
126
127<procedure> (scaling SCALE [RESULT])</procedure>
128
129Return 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.
130
131<procedure> (scale SCALE MATRIX)</procedure>
132
133Scale the x, y, and z axis of {{MATRIX}} by {{SCALE}}.
134
135<procedure> (flip-x MATRIX)</procedure>
136
137Flip (mirror) {{MATRIX}} along the x-axis.
138
139<procedure> (flip-y MATRIX)</procedure>
140
141Flip (mirror) {{MATRIX}} along the y-axis.
142
143<procedure> (flip-z MATRIX)</procedure>
144
145Flip (mirror) {{MATRIX}} along the z-axis.
146
147<procedure> (translate-rotate-scale-2d VECTOR ANGLE SCALE [RESULT])</procedure>
148
149Efficiently 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.
150
151<procedure> (transpose MATRIX [RESULT])</procedure>
152
153Transpose {{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.
154
155<procedure> (inverse MATRIX [RESULT])</procedure>
156
157Invert {{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.
158
159<procedure> (fast-inverse-transpose MATRIX [RESULT])</procedure>
160
161Efficiently 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.
162
163
164==== Projection matrices
165<procedure> (ortho WIDTH HEIGHT NEAR FAR [RESULT])</procedure>
166
167Create 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.
168
169<procedure> (ortho-viewport LEFT RIGHT NEAR FAR VIEWPORT-LEFT VIEWPORT-RIGHT VIEWPORT-BOTTOM VIEWPORT-TOP [RESULT])</procedure>
170
171Create 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.
172
173<procedure> (perspective WIDTH HEIGHT NEAR FAR ANGLE [RESULT])</procedure>
174
175Create 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.
176
177<procedure> (frustum LEFT RIGHT BOTTOM TOP NEAR FAR [RESULT])</procedure>
178
179Create 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.
180
181<procedure> (frustum-viewport LEFT RIGHT BOTTOM TOP NEAR FAR VIEWPORT-LEFT VIEWPORT-RIGHT VIEWPORT-BOTTOM VIEWPORT-TOP [RESULT])</procedure>
182
183Create 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.
184
185
186==== Camera functions
187<procedure> (look-at EYE OBJ UP [RESULT])</procedure>
188
189Create 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.
190
191<procedure> (camera-inverse CAMERA [RESULT])</procedure>
192
193Invert {{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.
194
195
196==== Vector operations
197<procedure> (make-point X Y Z [NON-GC?])</procedure>
198<procedure> (point-x POINT)</procedure>
199<procedure> (point-y POINT)</procedure>
200<procedure> (point-z POINT)</procedure>
201<procedure> (point-x-set! POINT)</procedure>
202<procedure> (point-y-set! POINT)</procedure>
203<procedure> (point-z-set! POINT)</procedure>
204
205Vector 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).
206
207<procedure> (v+ A B [RESULT])</procedure>
208
209Return 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.
210
211<procedure> (v- A B [RESULT])</procedure>
212
213Return 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.
214
215<procedure> (v* V S [RESULT])</procedure>
216
217Return 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.
218
219<procedure> (cross-product A B [RESULT])</procedure>
220
221Return 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.
222
223<procedure> (dot-product A B)</procedure>
224
225Return the result of the dot product between the vectors {{A}} and {{B}}.
226
227<procedure> (vector-magnitude V)</procedure>
228
229Return the magnitude of vector {{V}}.
230
231<procedure> (normalize! V)</procedure>
232
233Destructively normalize the vector {{V}}.
234
235<procedure> (m*vector! MATRIX VECTOR)</procedure>
236
237Destructively multiply {{VECTOR}} by {{MATRIX}}.
238
239<procedure> (m*vector-array! MATRIX VECTORS stride: [STRIDE] length: [LENGTH])</procedure>
240
241Destructively 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}}.
242
243<procedure> (lerp A B T [RESULT])</procedure>
244
245Linear 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.
246
247
248==== Quaternion operations
249Quaternions 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.
250
251The 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.
252
253<procedure> (make-quaternion X Y Z W [NON-GC?])</procedure>
254<procedure> (quaternion-x POINT)</procedure>
255<procedure> (quaternion-y POINT)</procedure>
256<procedure> (quaternion-z POINT)</procedure>
257<procedure> (quaternion-w POINT)</procedure>
258<procedure> (quaternion-x-set! POINT)</procedure>
259<procedure> (quaternion-y-set! POINT)</procedure>
260<procedure> (quaternion-z-set! POINT)</procedure>
261<procedure> (quaternion-w-set! POINT)</procedure>
262
263Quaternion 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).
264
265<procedure> (quaternion-normalize! Q)</procedure>
266
267Destructively normalize the quaternion {{Q}}.
268
269<procedure> (quaternion-inverse Q [RESULT])</procedure>
270
271Return 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.
272
273<procedure> (quaternion-cross-product A B [RESULT])</procedure>
274
275Return 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.
276
277<procedure> (quaternion-axis-angle-rotation AXIS ANGLE [RESULT])</procedure>
278
279Return 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.
280
281<procedure> (quaternion-rotate-axis-angle AXIS ANGLE Q)</procedure>
282
283Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the vector {{AXIS}}.
284
285<procedure> (quaternion-x-rotation ANGLE [RESULT])</procedure>
286
287Return 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.
288
289<procedure> (quaternion-rotate-x ANGLE Q)</procedure>
290
291Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the x-axis.
292
293<procedure> (quaternion-y-rotation ANGLE [RESULT])</procedure>
294
295Return 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.
296
297<procedure> (quaternion-rotate-y ANGLE Q)</procedure>
298
299Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the y-axis.
300
301<procedure> (quaternion-z-rotation ANGLE [RESULT])</procedure>
302
303Return 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.
304
305<procedure> (quaternion-rotate-z ANGLE Q)</procedure>
306
307Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the z-axis.
308
309<procedure> (quaternion-ypr-rotation YAW PITCH ROLL [RESULT])</procedure>
310
311Return 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.
312
313<procedure> (quaternion-rotate-ypr YAW PITCH ROLL Q)</procedure>
314
315Rotate 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.
316
317<procedure> (quaternion-rotate-point! Q P)</procedure>
318
319Destructively rotate the point {{P}} by the unit quaternion {{Q}}.
320
321<procedure> (slerp A B T [RESULT])</procedure>
322
323Spherical 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.
324
325
326==== Angle operations
328
329Converts {{ANGLE}} from degrees to radians.
330
332
333Converts {{ANGLE}} from radians to degrees.
334
335<constant> pi</constant>
336<constant> pi/2</constant>
337
338
339=== Example
340<enscript highlight="scheme">
341(import gl-math)
342
343(define projection-matrix
344  (perspective 640 480 0.1 100 70))
345
346(define view-matrix
347  (look-at (make-point 1 0 3)
348           (make-point 0 0 0)
349           (make-point 0 1 0)))
350
351(define model-matrix (mat4-identity))
352
353(print-mat4 (m* projection-matrix
354                (m* view-matrix model-matrix)))
355</enscript>
356
357
358=== Version history
359
360==== Version 0.9.1
3614 April 2019
362
363* Fix a bug in make-quaternion
364* point and quaternion constructors and setters now convert arguments to flonum automatically
365
366
367==== Version 0.9.0
36815 March 2019
369
370* Maintenance given to [[/users/kooda|Kooda]]
371* Port to CHICKEN 5
372
373
374==== Version 0.8.0
3757 August 2014
376
378
379
380==== Version 0.7.0
382
383
384==== Version 0.6.0
3858 October 2014
386
388
389
390==== Version 0.5.2
39110 September 2014
392
393* {{m*vector-array!}}: Stride is given in bytes when vector is a pointer
394
395'''Version 0.5.0'''
396
3972 September 2014
398
399* Many new vector and quaternion functions
400* Functions that previously accepted vectors as individual floats, now accept them as f32vectors
401
402
403==== Version 0.4.1
40430 August 2014
405
406* Fix {{m*vector-array!}}
407
408'''Version 0.4.0'''
409
41027 July 2014
411
413
414
415==== Version 0.3.2
41621 July 2014
417
418* Allow pointer to array of vectors to be passed to {{m*vector-array!}}
419* Fix error forms
420
421'''Version 0.3.1'''
422
42323 June 2014
424
425* Matrix vector multiplication
426
427
428==== Version 0.2.0
42921 June 2014
430
431* Each transformation function now has two variants: one that initializes a matrix, and one that operates on a matrix
432* Provide {{pi/2}}
433* Provide quaternion and YPR rotation
435* Fix optional arguments for matrix operations
436* Fix a bug in {{look-at}}
437
438
439==== Version 0.1.0
44017 June 2014
441
442* Initial release
443
444
445=== Source repository
446Source available [[https://www.upyum.com/cgit.cgi/gl-math/|here]].
447
448Bug reports and patches welcome! Bugs can be reported to kooda@upyum.com
449
450
451=== Authors
452Alex Charlton
453