Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
quat.h
Go to the documentation of this file.
1
44#ifndef BJ_QUAT_H
45#define BJ_QUAT_H
46
47#include <banjo/api.h>
48#include <banjo/math.h>
49#include <banjo/vec.h>
50#include <banjo/mat.h>
51
63 void
64) {
65 return (struct bj_vec4){ BJ_FZERO, BJ_FZERO, BJ_FZERO, BJ_F(1.0) };
66}
67
79 struct bj_vec4 a,
80 struct bj_vec4 b
81) {
82 return a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
83}
84
94 struct bj_vec4 q
95) {
96 return bj_quat_dot(q, q);
97}
98
106 struct bj_vec4 q
107) {
108 return bj_sqrt(bj_quat_norm2(q));
109}
110
121 struct bj_vec4 q
122) {
123 const bj_real n2 = bj_quat_norm2(q);
124 if (n2 <= BJ_EPSILON) {
125 return bj_quat_identity();
126 }
127 const bj_real inv = BJ_F(1.0) / bj_sqrt(n2);
128 return (struct bj_vec4){ q.x * inv, q.y * inv, q.z * inv, q.w * inv };
129}
130
144 struct bj_vec4 q
145) {
146 return (struct bj_vec4){ -q.x, -q.y, -q.z, q.w };
147}
148
162 struct bj_vec4 q
163) {
164 const bj_real n2 = bj_quat_norm2(q);
165 if (n2 <= BJ_EPSILON) {
166 return bj_quat_identity();
167 }
168 const bj_real inv = BJ_F(1.0) / n2;
169 return (struct bj_vec4){ -q.x * inv, -q.y * inv, -q.z * inv, q.w * inv };
170}
171
184 struct bj_vec4 p,
185 struct bj_vec4 q
186) {
187 return (struct bj_vec4){
188 p.w*q.x + p.x*q.w + p.y*q.z - p.z*q.y,
189 p.w*q.y - p.x*q.z + p.y*q.w + p.z*q.x,
190 p.w*q.z + p.x*q.y - p.y*q.x + p.z*q.w,
191 p.w*q.w - p.x*q.x - p.y*q.y - p.z*q.z
192 };
193}
194
210 struct bj_vec4 a,
211 struct bj_vec4 b,
212 bj_real t
213) {
214 bj_real cos_omega = bj_quat_dot(a, b);
215 struct bj_vec4 bb = b;
216 if (cos_omega < BJ_FZERO) {
217 cos_omega = -cos_omega;
218 bb.x = -b.x;
219 bb.y = -b.y;
220 bb.z = -b.z;
221 bb.w = -b.w;
222 }
223
224 /* Clamp for numerical safety */
225 if (cos_omega > BJ_F(1.0)) cos_omega = BJ_F(1.0);
226 if (cos_omega < -BJ_F(1.0)) cos_omega = -BJ_F(1.0);
227
228 if (cos_omega > BJ_F(1.0) - BJ_EPSILON) {
229 return bj_quat_normalize((struct bj_vec4){
230 a.x + t*(bb.x - a.x),
231 a.y + t*(bb.y - a.y),
232 a.z + t*(bb.z - a.z),
233 a.w + t*(bb.w - a.w)
234 });
235 }
236
237 const bj_real omega = bj_acos(cos_omega);
238 const bj_real sin_omega = bj_sin(omega);
239 if (sin_omega <= BJ_EPSILON) {
240 /* Fallback to nlerp */
241 return bj_quat_normalize((struct bj_vec4){
242 a.x + t*(bb.x - a.x),
243 a.y + t*(bb.y - a.y),
244 a.z + t*(bb.z - a.z),
245 a.w + t*(bb.w - a.w)
246 });
247 }
248
249 const bj_real wa = bj_sin((BJ_F(1.0) - t) * omega) / sin_omega;
250 const bj_real wb = bj_sin(t * omega) / sin_omega;
251 return (struct bj_vec4){
252 wa * a.x + wb * bb.x,
253 wa * a.y + wb * bb.y,
254 wa * a.z + wb * bb.z,
255 wa * a.w + wb * bb.w
256 };
257}
258
269 struct bj_vec3 axis,
270 bj_real angle_rad
271) {
272 const bj_real alen2 = axis.x*axis.x + axis.y*axis.y + axis.z*axis.z;
273 if (alen2 <= BJ_EPSILON) {
274 return bj_quat_identity();
275 }
276 const bj_real invlen = BJ_F(1.0) / bj_sqrt(alen2);
277 const struct bj_vec3 n = (struct bj_vec3){
278 axis.x * invlen, axis.y * invlen, axis.z * invlen
279 };
280 const bj_real h = angle_rad * BJ_F(0.5);
281 const bj_real s = bj_sin(h);
282 const bj_real c = bj_cos(h);
283 return (struct bj_vec4){ n.x * s, n.y * s, n.z * s, c };
284}
285
297 struct bj_vec4 q,
298 struct bj_vec3 v
299) {
300 struct bj_vec3 u = (struct bj_vec3){ q.x, q.y, q.z };
301 struct bj_vec3 t = bj_vec3_cross(u, v);
302 t.x += t.x; t.y += t.y; t.z += t.z; /* 2*(u×v) */
303 struct bj_vec3 r = (struct bj_vec3){
304 v.x + q.w * t.x + (u.y * t.z - u.z * t.y),
305 v.y + q.w * t.y + (u.z * t.x - u.x * t.z),
306 v.z + q.w * t.z + (u.x * t.y - u.y * t.x)
307 };
308 return r;
309}
310
319 struct bj_vec4 q,
320 struct bj_vec4 v
321) {
322 struct bj_vec3 r3 = bj_quat_rotate_vec3(q, (struct bj_vec3){ v.x, v.y, v.z });
323 return (struct bj_vec4){ .x = r3.x, .y = r3.y, .z = r3.z, .w = v.w };
324}
325
336 struct bj_mat4* BJ_RESTRICT M,
337 struct bj_vec4 q
338) {
339 q = bj_quat_normalize(q);
340 bj_real xx = q.x * q.x, yy = q.y * q.y, zz = q.z * q.z;
341 bj_real xy = q.x * q.y, xz = q.x * q.z, yz = q.y * q.z;
342 bj_real wx = q.w * q.x, wy = q.w * q.y, wz = q.w * q.z;
343
345
346 bj_real* m = M->m;
347 /* Column 0 */
348 m[BJ_M4(0,0)] = BJ_F(1.0) - BJ_F(2.0) * (yy + zz);
349 m[BJ_M4(0,1)] = BJ_F(2.0) * (xy + wz);
350 m[BJ_M4(0,2)] = BJ_F(2.0) * (xz - wy);
351 m[BJ_M4(0,3)] = BJ_FZERO;
352 /* Column 1 */
353 m[BJ_M4(1,0)] = BJ_F(2.0) * (xy - wz);
354 m[BJ_M4(1,1)] = BJ_F(1.0) - BJ_F(2.0) * (xx + zz);
355 m[BJ_M4(1,2)] = BJ_F(2.0) * (yz + wx);
356 m[BJ_M4(1,3)] = BJ_FZERO;
357 /* Column 2 */
358 m[BJ_M4(2,0)] = BJ_F(2.0) * (xz + wy);
359 m[BJ_M4(2,1)] = BJ_F(2.0) * (yz - wx);
360 m[BJ_M4(2,2)] = BJ_F(1.0) - BJ_F(2.0) * (xx + yy);
361 m[BJ_M4(2,3)] = BJ_FZERO;
362 /* Column 3 */
363 m[BJ_M4(3,0)] = BJ_FZERO;
364 m[BJ_M4(3,1)] = BJ_FZERO;
365 m[BJ_M4(3,2)] = BJ_FZERO;
366 m[BJ_M4(3,3)] = BJ_F(1.0);
367}
368
385 const struct bj_mat4* BJ_RESTRICT M
386) {
387 const bj_real* m = M->m;
388 bj_real m00 = m[BJ_M4(0,0)], m01 = m[BJ_M4(1,0)], m02 = m[BJ_M4(2,0)];
389 bj_real m10 = m[BJ_M4(0,1)], m11 = m[BJ_M4(1,1)], m12 = m[BJ_M4(2,1)];
390 bj_real m20 = m[BJ_M4(0,2)], m21 = m[BJ_M4(1,2)], m22 = m[BJ_M4(2,2)];
391
392 const bj_real trace = m00 + m11 + m22;
393 if (trace > BJ_FZERO) {
394 const bj_real s = bj_sqrt(trace + BJ_F(1.0)) * BJ_F(2.0);
395 const bj_real w = BJ_F(0.25) * s;
396 const bj_real x = (m21 - m12) / s;
397 const bj_real y = (m02 - m20) / s;
398 const bj_real z = (m10 - m01) / s;
399 return bj_quat_normalize((struct bj_vec4){ x, y, z, w });
400 }
401
402 if (m00 > m11 && m00 > m22) {
403 const bj_real s = bj_sqrt(BJ_F(1.0) + m00 - m11 - m22) * BJ_F(2.0);
404 const bj_real w = (m21 - m12) / s;
405 const bj_real x = BJ_F(0.25) * s;
406 const bj_real y = (m01 + m10) / s;
407 const bj_real z = (m02 + m20) / s;
408 return bj_quat_normalize((struct bj_vec4){ x, y, z, w });
409 } else if (m11 > m22) {
410 const bj_real s = bj_sqrt(BJ_F(1.0) - m00 + m11 - m22) * BJ_F(2.0);
411 const bj_real w = (m02 - m20) / s;
412 const bj_real x = (m01 + m10) / s;
413 const bj_real y = BJ_F(0.25) * s;
414 const bj_real z = (m12 + m21) / s;
415 return bj_quat_normalize((struct bj_vec4){ x, y, z, w });
416 } else {
417 const bj_real s = bj_sqrt(BJ_F(1.0) - m00 - m11 + m22) * BJ_F(2.0);
418 const bj_real w = (m10 - m01) / s;
419 const bj_real x = (m02 + m20) / s;
420 const bj_real y = (m12 + m21) / s;
421 const bj_real z = BJ_F(0.25) * s;
422 return bj_quat_normalize((struct bj_vec4){ x, y, z, w });
423 }
424}
425
426#endif /* BJ_QUAT_H */
427
General-purpose definitions for Banjo API.
#define BJ_INLINE
BJ_INLINE expands to an inline specifier appropriate for the toolchain.
Definition api.h:248
#define BJ_RESTRICT
BJ_RESTRICT expands to the appropriate restrict qualifier per toolchain.
Definition api.h:214
bj_real z
Z component.
Definition vec.h:88
bj_real x
X component.
Definition vec.h:71
bj_real w
W component (scalar part for quaternions).
Definition vec.h:89
bj_real z
Z component.
Definition vec.h:73
bj_real x
X component.
Definition vec.h:86
bj_real y
Y component.
Definition vec.h:72
bj_real y
Y component.
Definition vec.h:87
static struct bj_vec4 bj_quat_mul(struct bj_vec4 p, struct bj_vec4 q)
Hamilton product p * q.
Definition quat.h:183
static void bj_mat4_set_identity(struct bj_mat4 *restrict M)
Set a 4×4 matrix to identity.
Definition mat.h:773
static bj_real bj_quat_dot(struct bj_vec4 a, struct bj_vec4 b)
4D dot product between two quaternions.
Definition quat.h:78
static struct bj_vec4 bj_quat_normalize(struct bj_vec4 q)
Normalise a quaternion.
Definition quat.h:120
static struct bj_vec4 bj_quat_from_mat4(const struct bj_mat4 *restrict M)
Build a quaternion from a 4×4 rotation matrix.
Definition quat.h:384
static struct bj_vec4 bj_quat_slerp(struct bj_vec4 a, struct bj_vec4 b, bj_real t)
Spherical linear interpolation between two orientations.
Definition quat.h:209
#define bj_acos
Arc cosine.
Definition math.h:238
#define bj_sin
Sine.
Definition math.h:250
static struct bj_vec4 bj_quat_rotate_vec4(struct bj_vec4 q, struct bj_vec4 v)
Rotate a 4D vector by a quaternion, preserving w.
Definition quat.h:318
static void bj_quat_to_mat4(struct bj_mat4 *restrict M, struct bj_vec4 q)
Fill a 4×4 rotation matrix from a quaternion.
Definition quat.h:335
#define BJ_FZERO
Zero constant in bj_real.
Definition math.h:93
static struct bj_vec4 bj_quat_from_axis_angle(struct bj_vec3 axis, bj_real angle_rad)
Build a quaternion from a rotation axis and angle.
Definition quat.h:268
static struct bj_vec4 bj_quat_conjugate(struct bj_vec4 q)
Conjugate of a quaternion.
Definition quat.h:143
static struct bj_vec3 bj_vec3_cross(struct bj_vec3 l, struct bj_vec3 r)
3D cross product: l × r (right-hand rule).
Definition vec.h:597
#define bj_cos
Cosine.
Definition math.h:241
static bj_real bj_quat_norm2(struct bj_vec4 q)
Squared Euclidean norm.
Definition quat.h:93
#define BJ_EPSILON
Machine epsilon for bj_real when float is selected.
Definition math.h:84
static struct bj_vec4 bj_quat_identity(void)
Return the identity quaternion.
Definition quat.h:62
static struct bj_vec3 bj_quat_rotate_vec3(struct bj_vec4 q, struct bj_vec3 v)
Rotate a 3D vector by a quaternion.
Definition quat.h:296
#define BJ_F(x)
Literal suffix helper for bj_real when float is selected.
Definition math.h:82
#define bj_sqrt
Square root.
Definition math.h:251
static struct bj_vec4 bj_quat_inverse(struct bj_vec4 q)
Multiplicative inverse of a quaternion.
Definition quat.h:161
float bj_real
Selected real type for float configuration.
Definition math.h:80
#define BJ_M4(c, r)
Index a 4×4 matrix element at column c, row r. 0 <= c,r < 4.
Definition mat.h:97
static bj_real bj_quat_norm(struct bj_vec4 q)
Euclidean norm (length).
Definition quat.h:105
4×4 column-major matrix.
Definition mat.h:95
3D vector of bj_real components.
Definition vec.h:70
4D vector of bj_real components.
Definition vec.h:85
Matrix types and operations for 2D and 3D transforms.
C99 math shim with bj_real precision type and scalar utilities.
Fixed-size vector types (2D, 3D, 4D) and inline operations.