# source:project/wiki/eggref/4/gl-math@32201

Last change on this file since 32201 was 32201, checked in by acharlton, 6 years ago

wiki/gl-math: Update to 0.7.0

File size: 27.9 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> (mat4-identity [RESULT])</procedure>
38
39Return 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.
40
41<procedure> (translation VECTOR [RESULT])</procedure>
42
43Return 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.
44
45<procedure> (translate VECTOR MATRIX)</procedure>
46
47Translate {{MATRIX}} by {{VECTOR}}.
48
49<procedure> (x-rotation ANGLE [RESULT])</procedure>
50
51Return 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.
52
53<procedure> (rotate-x ANGLE MATRIX)</procedure>
54
55Rotate {{MATRIX}} around the x-axis by {{ANGLE}} radians.
56
57<procedure> (y-rotation ANGLE [RESULT])</procedure>
58
59Return 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.
60
61<procedure> (rotate-y ANGLE MATRIX)</procedure>
62
63Rotate {{MATRIX}} around the y-axis by {{ANGLE}} radians.
64
65<procedure> (z-rotation ANGLE [RESULT])</procedure>
66
67Return 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.
68
69<procedure> (rotate-z ANGLE MATRIX)</procedure>
70
71Rotate {{MATRIX}} around the z-axis by {{ANGLE}} radians.
72
73<procedure> (axis-angle-rotation AXIS ANGLE [RESULT])</procedure>
74
75Return 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.
76
77<procedure> (rotate-axis-angle AXIS ANGLE MATRIX)</procedure>
78
79Rotate {{MATRIX}} around the vector {{AXIS}} by {{ANGLE}} radians.
80
81<procedure> (quaternion-rotation Q [RESULT])</procedure>
82
83Return 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.
84
85<procedure> (rotate-quaternion Q MATRIX)</procedure>
86
87Rotate {{MATRIX}} by the quaternion {{Q}}.
88
89<procedure> (ypr-rotation YAW PITCH ROLL [RESULT])</procedure>
90
91Return 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.
92
93<procedure> (rotate-ypr YAW PITCH ROLL MATRIX)</procedure>
94
95Rotate {{MATRIX}} by {{ROLL}} radians around the z-axis followed by {{PITCH}} radians around the x-axis followed by {{YAW}} radians around the y-axis.
96
97<procedure> (2d-scaling SCALE-X SCALE-Y [RESULT])</procedure>
98
99Return 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.
100
101<procedure> (scale-2d SCALE-X SCALE-Y MATRIX)</procedure>
102
103Scale the x and y axis of {{MATRIX}} by {{SCALE-X}} and {{SCALE-Y}}.
104
105<procedure> (3d-scaling SCALE-X SCALE-Y SCALE-Z [RESULT])</procedure>
106
107Return 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.
108
109<procedure> (scale-3d SCALE-X SCALE-Y SCALE-Z MATRIX)</procedure>
110
111Scale the x, y, and z axis of {{MATRIX}} by {{SCALE-X}}, {{SCALE-Y}}, and {{SCALE-Z}}.
112
113<procedure> (scaling SCALE [RESULT])</procedure>
114
115Return 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.
116
117<procedure> (scale SCALE MATRIX)</procedure>
118
119Scale the x, y, and z axis of {{MATRIX}} by {{SCALE}}.
120
121<procedure> (flip-x MATRIX)</procedure>
122
123Flip (mirror) {{MATRIX}} along the x-axis.
124
125<procedure> (flip-y MATRIX)</procedure>
126
127Flip (mirror) {{MATRIX}} along the y-axis.
128
129<procedure> (flip-z MATRIX)</procedure>
130
131Flip (mirror) {{MATRIX}} along the z-axis.
132
133<procedure> (translate-rotate-scale-2d VECTOR ANGLE SCALE [RESULT])</procedure>
134
135Efficiently 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.
136
137<procedure> (transpose MATRIX [RESULT])</procedure>
138
139Transpose {{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.
140
141<procedure> (inverse MATRIX [RESULT])</procedure>
142
143Invert {{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.
144
145<procedure> (fast-inverse-transpose MATRIX [RESULT])</procedure>
146
147Efficiently 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.
148
149
150==== Projection matrices
151<procedure> (ortho WIDTH HEIGHT NEAR FAR [RESULT])</procedure>
152
153Create 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.
154
155<procedure> (ortho-viewport LEFT RIGHT NEAR FAR VIEWPORT-LEFT VIEWPORT-RIGHT VIEWPORT-BOTTOM VIEWPORT-TOP [RESULT])</procedure>
156
157Create 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.
158
159<procedure> (perspective WIDTH HEIGHT NEAR FAR ANGLE [RESULT])</procedure>
160
161Create 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.
162
163<procedure> (frustum LEFT RIGHT BOTTOM TOP NEAR FAR [RESULT])</procedure>
164
165Create 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.
166
167<procedure> (frustum-viewport LEFT RIGHT BOTTOM TOP NEAR FAR VIEWPORT-LEFT VIEWPORT-RIGHT VIEWPORT-BOTTOM VIEWPORT-TOP [RESULT])</procedure>
168
169Create 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.
170
171
172==== Camera functions
173<procedure> (look-at EYE OBJ UP [RESULT])</procedure>
174
175Create 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.
176
177<procedure> (camera-inverse CAMERA [RESULT])</procedure>
178
179Invert {{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.
180
181
182==== Vector operations
183<procedure> (make-point X Y Z [NON-GC?])</procedure>
184<procedure> (point-x POINT)</procedure>
185<procedure> (point-y POINT)</procedure>
186<procedure> (point-z POINT)</procedure>
187<procedure> (point-x-set! POINT)</procedure>
188<procedure> (point-y-set! POINT)</procedure>
189<procedure> (point-z-set! POINT)</procedure>
190
191Vector 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).
192
193<procedure> (v+ A B [RESULT])</procedure>
194
195Return 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.
196
197<procedure> (v- A B [RESULT])</procedure>
198
199Return 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.
200
201<procedure> (v* V S [RESULT])</procedure>
202
203Return 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.
204
205<procedure> (cross-product A B [RESULT])</procedure>
206
207Return 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.
208
209<procedure> (dot-product A B)</procedure>
210
211Return the result of the dot product between the vectors {{A}} and {{B}}.
212
213<procedure> (vector-magnitude V)</procedure>
214
215Return the magnitude of vector {{V}}.
216
217<procedure> (normalize! V)</procedure>
218
219Destructively normalize the vector {{V}}.
220
221<procedure> (m*vector! MATRIX VECTOR)</procedure>
222
223Destructively multiply {{VECTOR}} by {{MATRIX}}.
224
225<procedure> (m*vector-array! MATRIX VECTORS stride: [STRIDE] length: [LENGTH])</procedure>
226
227Destructively 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}}.
228
229<procedure> (lerp A B T [RESULT])</procedure>
230
231Linear 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.
232
233
234==== Quaternion operations
235Quaternions 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.
236
237The 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.
238
239<procedure> (make-quaternion X Y Z W [NON-GC?])</procedure>
240<procedure> (quaternion-x POINT)</procedure>
241<procedure> (quaternion-y POINT)</procedure>
242<procedure> (quaternion-z POINT)</procedure>
243<procedure> (quaternion-w POINT)</procedure>
244<procedure> (quaternion-x-set! POINT)</procedure>
245<procedure> (quaternion-y-set! POINT)</procedure>
246<procedure> (quaternion-z-set! POINT)</procedure>
247<procedure> (quaternion-w-set! POINT)</procedure>
248
249Quaternion 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).
250
251<procedure> (quaternion-normalize! Q)</procedure>
252
253Destructively normalize the quaternion {{Q}}.
254
255<procedure> (quaternion-inverse Q [RESULT])</procedure>
256
257Return 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.
258
259<procedure> (quaternion-cross-product A B [RESULT])</procedure>
260
261Return 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.
262
263<procedure> (quaternion-axis-angle-rotation AXIS ANGLE [RESULT])</procedure>
264
265Return 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.
266
267<procedure> (quaternion-rotate-axis-angle AXIS ANGLE Q)</procedure>
268
269Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the vector {{AXIS}}.
270
271<procedure> (quaternion-x-rotation ANGLE [RESULT])</procedure>
272
273Return 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.
274
275<procedure> (quaternion-rotate-x ANGLE Q)</procedure>
276
277Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the x-axis.
278
279<procedure> (quaternion-y-rotation ANGLE [RESULT])</procedure>
280
281Return 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.
282
283<procedure> (quaternion-rotate-y ANGLE Q)</procedure>
284
285Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the y-axis.
286
287<procedure> (quaternion-z-rotation ANGLE [RESULT])</procedure>
288
289Return 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.
290
291<procedure> (quaternion-rotate-z ANGLE Q)</procedure>
292
293Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the z-axis.
294
295<procedure> (quaternion-ypr-rotation YAW PITCH ROLL [RESULT])</procedure>
296
297Return 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.
298
299<procedure> (quaternion-rotate-ypr YAW PITCH ROLL Q)</procedure>
300
301Rotate 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.
302
303<procedure> (quaternion-rotate-point! Q P)</procedure>
304
305Destructively rotate the point {{P}} by the unit quaternion {{Q}}.
306
307<procedure> (slerp A B T [RESULT])</procedure>
308
309Spherical 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.
310
311
312==== Angle operations
314
315Converts {{ANGLE}} from degrees to radians.
316
318
319Converts {{ANGLE}} from radians to degrees.
320
321<constant> pi</constant>
322<constant> pi/2</constant>
323
324
325=== Example
326<enscript highlight="scheme">
327(import chicken scheme)
328(use gl-math)
329
330(define projection-matrix
331  (perspective 640 480 0.1 100 70))
332
333(define view-matrix
334  (look-at (make-point 1 0 3)
335           (make-point 0 0 0)
336           (make-point 0 1 0)))
337
338(define model-matrix (mat4-identity))
339
340(print-mat4 (m* projection-matrix
341                (m* view-matrix model-matrix)))
342</enscript>
343
344
345=== Version history
346
347==== Version 0.6.0
3488 October 2014
349
351
352
353==== Version 0.5.2
35410 September 2014
355
356* {{m*vector-array!}}: Stride is given in bytes when vector is a pointer
357
358'''Version 0.5.0'''
359
3602 September 2014
361
362* Many new vector and quaternion functions
363* Functions that previously accepted vectors as individual floats, now accept them as f32vectors
364
365
366==== Version 0.4.1
36730 August 2014
368
369* Fix {{m*vector-array!}}
370
371'''Version 0.4.0'''
372
37327 July 2014
374
376
377
378==== Version 0.3.2
37921 July 2014
380
381* Allow pointer to array of vectors to be passed to {{m*vector-array!}}
382* Fix error forms
383
384'''Version 0.3.1'''
385
38623 June 2014
387
388* Matrix vector multiplication
389
390
391==== Version 0.2.0
39221 June 2014
393
394* Each transformation function now has two variants: one that initializes a matrix, and one that operates on a matrix
395* Provide {{pi/2}}
396* Provide quaternion and YPR rotation
398* Fix optional arguments for matrix operations
399* Fix a bug in {{look-at}}
400
401
402==== Version 0.1.0
40317 June 2014
404
405* Initial release
406
407
408=== Source repository
409Source available on [[https://github.com/AlexCharlton/gl-math|GitHub]].
410
411Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
412
413
414=== Author
415Alex Charlton
416
417
418=== Licence
419BSD
Note: See TracBrowser for help on using the repository browser.