1 | |
---|
2 | == gl-math |
---|
3 | [[toc:]] |
---|
4 | A 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 |
---|
13 | gl-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 | |
---|
19 | Additionally, gl-math is one fifth the compiled size of glm, has a more straight-forward code-base, and complete documentation. |
---|
20 | |
---|
21 | gl-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 | |
---|
23 | gl-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 | |
---|
29 | Prints the given {{MATRIX}} to {{(current-output-port)}}. |
---|
30 | |
---|
31 | <procedure> (copy-mat4 MATRIX [RESULT])</procedure> |
---|
32 | |
---|
33 | Make 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 | |
---|
37 | Multiply 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 | |
---|
41 | Multiply 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 | |
---|
45 | Add 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 | |
---|
49 | Subtract 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 | |
---|
53 | Return 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 | |
---|
57 | Return 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 | |
---|
61 | Translate {{MATRIX}} by {{VECTOR}}. |
---|
62 | |
---|
63 | <procedure> (x-rotation ANGLE [RESULT])</procedure> |
---|
64 | |
---|
65 | Return 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 | |
---|
69 | Rotate {{MATRIX}} around the x-axis by {{ANGLE}} radians. |
---|
70 | |
---|
71 | <procedure> (y-rotation ANGLE [RESULT])</procedure> |
---|
72 | |
---|
73 | Return 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 | |
---|
77 | Rotate {{MATRIX}} around the y-axis by {{ANGLE}} radians. |
---|
78 | |
---|
79 | <procedure> (z-rotation ANGLE [RESULT])</procedure> |
---|
80 | |
---|
81 | Return 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 | |
---|
85 | Rotate {{MATRIX}} around the z-axis by {{ANGLE}} radians. |
---|
86 | |
---|
87 | <procedure> (axis-angle-rotation AXIS ANGLE [RESULT])</procedure> |
---|
88 | |
---|
89 | Return 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 | |
---|
93 | Rotate {{MATRIX}} around the vector {{AXIS}} by {{ANGLE}} radians. |
---|
94 | |
---|
95 | <procedure> (quaternion-rotation Q [RESULT])</procedure> |
---|
96 | |
---|
97 | Return 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 | |
---|
101 | Rotate {{MATRIX}} by the quaternion {{Q}}. |
---|
102 | |
---|
103 | <procedure> (ypr-rotation YAW PITCH ROLL [RESULT])</procedure> |
---|
104 | |
---|
105 | Return 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 | |
---|
109 | Rotate {{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 | |
---|
113 | Return 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 | |
---|
117 | Scale 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 | |
---|
121 | Return 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 | |
---|
125 | Scale the x, y, and z axis of {{MATRIX}} by {{SCALE-X}}, {{SCALE-Y}}, and {{SCALE-Z}}. |
---|
126 | |
---|
127 | <procedure> (scaling SCALE [RESULT])</procedure> |
---|
128 | |
---|
129 | Return 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 | |
---|
133 | Scale the x, y, and z axis of {{MATRIX}} by {{SCALE}}. |
---|
134 | |
---|
135 | <procedure> (flip-x MATRIX)</procedure> |
---|
136 | |
---|
137 | Flip (mirror) {{MATRIX}} along the x-axis. |
---|
138 | |
---|
139 | <procedure> (flip-y MATRIX)</procedure> |
---|
140 | |
---|
141 | Flip (mirror) {{MATRIX}} along the y-axis. |
---|
142 | |
---|
143 | <procedure> (flip-z MATRIX)</procedure> |
---|
144 | |
---|
145 | Flip (mirror) {{MATRIX}} along the z-axis. |
---|
146 | |
---|
147 | <procedure> (translate-rotate-scale-2d VECTOR ANGLE SCALE [RESULT])</procedure> |
---|
148 | |
---|
149 | Efficiently 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 | |
---|
153 | Transpose {{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 | |
---|
157 | Invert {{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 | |
---|
161 | Efficiently 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 | |
---|
167 | Create 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 | |
---|
171 | Create 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 | |
---|
175 | Create 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 | |
---|
179 | Create 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 | |
---|
183 | Create 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 | |
---|
189 | Create 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 | |
---|
193 | Invert {{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 | |
---|
205 | Vector 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 | |
---|
209 | Return 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 | |
---|
213 | Return 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 | |
---|
217 | Return 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 | |
---|
221 | Return 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 | |
---|
225 | Return the result of the dot product between the vectors {{A}} and {{B}}. |
---|
226 | |
---|
227 | <procedure> (vector-magnitude V)</procedure> |
---|
228 | |
---|
229 | Return the magnitude of vector {{V}}. |
---|
230 | |
---|
231 | <procedure> (normalize! V)</procedure> |
---|
232 | |
---|
233 | Destructively normalize the vector {{V}}. |
---|
234 | |
---|
235 | <procedure> (m*vector! MATRIX VECTOR)</procedure> |
---|
236 | |
---|
237 | Destructively multiply {{VECTOR}} by {{MATRIX}}. |
---|
238 | |
---|
239 | <procedure> (m*vector-array! MATRIX VECTORS stride: [STRIDE] length: [LENGTH])</procedure> |
---|
240 | |
---|
241 | Destructively 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 | |
---|
245 | Linear 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 |
---|
249 | Quaternions 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 | |
---|
251 | The 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 | |
---|
263 | Quaternion 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 | |
---|
267 | Destructively normalize the quaternion {{Q}}. |
---|
268 | |
---|
269 | <procedure> (quaternion-inverse Q [RESULT])</procedure> |
---|
270 | |
---|
271 | Return 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 | |
---|
275 | Return 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 | |
---|
279 | Return 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 | |
---|
283 | Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the vector {{AXIS}}. |
---|
284 | |
---|
285 | <procedure> (quaternion-x-rotation ANGLE [RESULT])</procedure> |
---|
286 | |
---|
287 | Return 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 | |
---|
291 | Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the x-axis. |
---|
292 | |
---|
293 | <procedure> (quaternion-y-rotation ANGLE [RESULT])</procedure> |
---|
294 | |
---|
295 | Return 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 | |
---|
299 | Rotate the quaternion {{Q}} by a rotation of {{ANGLE}} radians around the y-axis. |
---|
300 | |
---|
301 | <procedure> (quaternion-z-rotation ANGLE [RESULT])</procedure> |
---|
302 | |
---|
303 | Return 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 | |
---|
307 | Rotate 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 | |
---|
311 | Return 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 | |
---|
315 | Rotate 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 | |
---|
319 | Destructively rotate the point {{P}} by the unit quaternion {{Q}}. |
---|
320 | |
---|
321 | <procedure> (slerp A B T [RESULT])</procedure> |
---|
322 | |
---|
323 | Spherical 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 |
---|
327 | <procedure> (degrees->radians ANGLE)</procedure> |
---|
328 | |
---|
329 | Converts {{ANGLE}} from degrees to radians. |
---|
330 | |
---|
331 | <procedure> (radians->degrees ANGLE)</procedure> |
---|
332 | |
---|
333 | Converts {{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 |
---|
361 | 4 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 |
---|
368 | 15 March 2019 |
---|
369 | |
---|
370 | * Maintenance given to [[/users/kooda|Kooda]] |
---|
371 | * Port to CHICKEN 5 |
---|
372 | |
---|
373 | |
---|
374 | ==== Version 0.8.0 |
---|
375 | 7 August 2014 |
---|
376 | |
---|
377 | * Add {{m*}}, {{m+}}, {{m-}} |
---|
378 | |
---|
379 | |
---|
380 | ==== Version 0.7.0 |
---|
381 | * Add {{frustum}}, {{frustum-viewport}} |
---|
382 | |
---|
383 | |
---|
384 | ==== Version 0.6.0 |
---|
385 | 8 October 2014 |
---|
386 | |
---|
387 | * Add {{fast-inverse-transpose}} |
---|
388 | |
---|
389 | |
---|
390 | ==== Version 0.5.2 |
---|
391 | 10 September 2014 |
---|
392 | |
---|
393 | * {{m*vector-array!}}: Stride is given in bytes when vector is a pointer |
---|
394 | |
---|
395 | '''Version 0.5.0''' |
---|
396 | |
---|
397 | 2 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 |
---|
404 | 30 August 2014 |
---|
405 | |
---|
406 | * Fix {{m*vector-array!}} |
---|
407 | |
---|
408 | '''Version 0.4.0''' |
---|
409 | |
---|
410 | 27 July 2014 |
---|
411 | |
---|
412 | * Add {{copy-mat4}} |
---|
413 | |
---|
414 | |
---|
415 | ==== Version 0.3.2 |
---|
416 | 21 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 | |
---|
423 | 23 June 2014 |
---|
424 | |
---|
425 | * Matrix vector multiplication |
---|
426 | |
---|
427 | |
---|
428 | ==== Version 0.2.0 |
---|
429 | 21 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 |
---|
434 | * Remove unhelpful composite operations |
---|
435 | * Fix optional arguments for matrix operations |
---|
436 | * Fix a bug in {{look-at}} |
---|
437 | |
---|
438 | |
---|
439 | ==== Version 0.1.0 |
---|
440 | 17 June 2014 |
---|
441 | |
---|
442 | * Initial release |
---|
443 | |
---|
444 | |
---|
445 | === Source repository |
---|
446 | Source available [[https://www.upyum.com/cgit.cgi/gl-math/|here]]. |
---|
447 | |
---|
448 | Bug reports and patches welcome! Bugs can be reported to kooda@upyum.com |
---|
449 | |
---|
450 | |
---|
451 | === Authors |
---|
452 | Alex Charlton |
---|
453 | |
---|
454 | Adrien (Kooda) Ramos |
---|
455 | |
---|
456 | |
---|
457 | === Licence |
---|
458 | BSD |
---|
459 | |
---|