1 # 2 # Copyright (C) 2015 The Android Open Source Project 3 # 4 # Licensed under the Apache License, Version 2.0 (the "License"); 5 # you may not use this file except in compliance with the License. 6 # You may obtain a copy of the License at 7 # 8 # http://www.apache.org/licenses/LICENSE-2.0 9 # 10 # Unless required by applicable law or agreed to in writing, software 11 # distributed under the License is distributed on an "AS IS" BASIS, 12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 # See the License for the specific language governing permissions and 14 # limitations under the License. 15 # 16 17 header: 18 summary: Quaternion Functions 19 description: 20 The following functions manipulate quaternions. 21 end: 22 23 function: rsQuaternionAdd 24 version: 9 23 25 ret: void 26 arg: rs_quaternion* q, "Destination quaternion to add to." 27 arg: const rs_quaternion* rhs, "Quaternion to add." 28 summary: Add two quaternions 29 description: 30 Adds two quaternions, i.e. <code>*q += *rhs;</code> 31 inline: 32 q->w += rhs->w; 33 q->x += rhs->x; 34 q->y += rhs->y; 35 q->z += rhs->z; 36 test: none 37 end: 38 39 function: rsQuaternionConjugate 40 version: 9 23 41 ret: void 42 arg: rs_quaternion* q, "Quaternion to modify." 43 summary: Conjugate a quaternion 44 description: 45 Conjugates the quaternion. 46 inline: 47 q->x = -q->x; 48 q->y = -q->y; 49 q->z = -q->z; 50 test: none 51 end: 52 53 function: rsQuaternionDot 54 version: 9 23 55 ret: float 56 arg: const rs_quaternion* q0, "First quaternion." 57 arg: const rs_quaternion* q1, "Second quaternion." 58 summary: Dot product of two quaternions 59 description: 60 Returns the dot product of two quaternions. 61 inline: 62 return q0->w*q1->w + q0->x*q1->x + q0->y*q1->y + q0->z*q1->z; 63 test: none 64 end: 65 66 function: rsQuaternionGetMatrixUnit 67 version: 9 23 68 ret: void 69 arg: rs_matrix4x4* m, "Resulting matrix." 70 arg: const rs_quaternion* q, "Normalized quaternion." 71 summary: Get a rotation matrix from a quaternion 72 description: 73 Computes a rotation matrix from the normalized quaternion. 74 inline: 75 float xx = q->x * q->x; 76 float xy = q->x * q->y; 77 float xz = q->x * q->z; 78 float xw = q->x * q->w; 79 float yy = q->y * q->y; 80 float yz = q->y * q->z; 81 float yw = q->y * q->w; 82 float zz = q->z * q->z; 83 float zw = q->z * q->w; 84 85 m->m[0] = 1.0f - 2.0f * ( yy + zz ); 86 m->m[4] = 2.0f * ( xy - zw ); 87 m->m[8] = 2.0f * ( xz + yw ); 88 m->m[1] = 2.0f * ( xy + zw ); 89 m->m[5] = 1.0f - 2.0f * ( xx + zz ); 90 m->m[9] = 2.0f * ( yz - xw ); 91 m->m[2] = 2.0f * ( xz - yw ); 92 m->m[6] = 2.0f * ( yz + xw ); 93 m->m[10] = 1.0f - 2.0f * ( xx + yy ); 94 m->m[3] = m->m[7] = m->m[11] = m->m[12] = m->m[13] = m->m[14] = 0.0f; 95 m->m[15] = 1.0f; 96 test: none 97 end: 98 99 function: rsQuaternionLoadRotateUnit 100 version: 9 23 101 ret: void 102 arg: rs_quaternion* q, "Destination quaternion." 103 arg: float rot, "Angle to rotate by, in radians." 104 arg: float x, "X component of the vector." 105 arg: float y, "Y component of the vector." 106 arg: float z, "Z component of the vector." 107 summary: Quaternion that represents a rotation about an arbitrary unit vector 108 description: 109 Loads a quaternion that represents a rotation about an arbitrary unit vector. 110 inline: 111 rot *= (float)(M_PI / 180.0f) * 0.5f; 112 float c = cos(rot); 113 float s = sin(rot); 114 115 q->w = c; 116 q->x = x * s; 117 q->y = y * s; 118 q->z = z * s; 119 test: none 120 end: 121 122 function: rsQuaternionSet 123 version: 9 23 124 ret: void 125 arg: rs_quaternion* q, "Destination quaternion." 126 arg: float w, "W component." 127 arg: float x, "X component." 128 arg: float y, "Y component." 129 arg: float z, "Z component." 130 summary: Create a quaternion 131 description: 132 Creates a quaternion from its four components or from another quaternion. 133 inline: 134 q->w = w; 135 q->x = x; 136 q->y = y; 137 q->z = z; 138 test: none 139 end: 140 141 function: rsQuaternionSet 142 version: 9 23 143 ret: void 144 arg: rs_quaternion* q 145 arg: const rs_quaternion* rhs, "Source quaternion." 146 inline: 147 q->w = rhs->w; 148 q->x = rhs->x; 149 q->y = rhs->y; 150 q->z = rhs->z; 151 test: none 152 end: 153 154 # NOTE: The following inline definitions depend on each other. The order must be preserved 155 # for the compilation to work. 156 157 function: rsQuaternionLoadRotate 158 version: 9 23 159 ret: void 160 arg: rs_quaternion* q, "Destination quaternion." 161 arg: float rot, "Angle to rotate by." 162 arg: float x, "X component of a vector." 163 arg: float y, "Y component of a vector." 164 arg: float z, "Z component of a vector." 165 summary: Create a rotation quaternion 166 description: 167 Loads a quaternion that represents a rotation about an arbitrary vector 168 (doesn't have to be unit) 169 inline: 170 const float len = x*x + y*y + z*z; 171 if (len != 1) { 172 const float recipLen = 1.f / sqrt(len); 173 x *= recipLen; 174 y *= recipLen; 175 z *= recipLen; 176 } 177 rsQuaternionLoadRotateUnit(q, rot, x, y, z); 178 test: none 179 end: 180 181 function: rsQuaternionNormalize 182 version: 9 23 183 ret: void 184 arg: rs_quaternion* q, "Quaternion to normalize." 185 summary: Normalize a quaternion 186 description: 187 Normalizes the quaternion. 188 inline: 189 const float len = rsQuaternionDot(q, q); 190 if (len != 1) { 191 const float recipLen = 1.f / sqrt(len); 192 q->w *= recipLen; 193 q->x *= recipLen; 194 q->y *= recipLen; 195 q->z *= recipLen; 196 } 197 test: none 198 end: 199 200 function: rsQuaternionMultiply 201 version: 9 23 202 ret: void 203 arg: rs_quaternion* q, "Destination quaternion." 204 arg: float scalar, "Scalar to multiply the quaternion by." 205 summary: Multiply a quaternion by a scalar or another quaternion 206 description: 207 Multiplies a quaternion by a scalar or by another quaternion, e.g 208 <code>*q = *q * scalar;</code> or <code>*q = *q * *rhs;</code>. 209 inline: 210 q->w *= scalar; 211 q->x *= scalar; 212 q->y *= scalar; 213 q->z *= scalar; 214 test: none 215 end: 216 217 function: rsQuaternionMultiply 218 version: 9 23 219 ret: void 220 arg: rs_quaternion* q 221 arg: const rs_quaternion* rhs, "Quaternion to multiply the destination quaternion by." 222 inline: 223 rs_quaternion qtmp; 224 rsQuaternionSet(&qtmp, q); 225 226 q->w = qtmp.w*rhs->w - qtmp.x*rhs->x - qtmp.y*rhs->y - qtmp.z*rhs->z; 227 q->x = qtmp.w*rhs->x + qtmp.x*rhs->w + qtmp.y*rhs->z - qtmp.z*rhs->y; 228 q->y = qtmp.w*rhs->y + qtmp.y*rhs->w + qtmp.z*rhs->x - qtmp.x*rhs->z; 229 q->z = qtmp.w*rhs->z + qtmp.z*rhs->w + qtmp.x*rhs->y - qtmp.y*rhs->x; 230 rsQuaternionNormalize(q); 231 test: none 232 end: 233 234 function: rsQuaternionSlerp 235 version: 9 23 236 ret: void 237 arg: rs_quaternion* q, "Result quaternion from the interpolation." 238 arg: const rs_quaternion* q0, "First input quaternion." 239 arg: const rs_quaternion* q1, "Second input quaternion." 240 arg: float t, "How much to interpolate by." 241 summary: Spherical linear interpolation between two quaternions 242 description: 243 Performs spherical linear interpolation between two quaternions. 244 inline: 245 if (t <= 0.0f) { 246 rsQuaternionSet(q, q0); 247 return; 248 } 249 if (t >= 1.0f) { 250 rsQuaternionSet(q, q1); 251 return; 252 } 253 254 rs_quaternion tempq0, tempq1; 255 rsQuaternionSet(&tempq0, q0); 256 rsQuaternionSet(&tempq1, q1); 257 258 float angle = rsQuaternionDot(q0, q1); 259 if (angle < 0) { 260 rsQuaternionMultiply(&tempq0, -1.0f); 261 angle *= -1.0f; 262 } 263 264 float scale, invScale; 265 if (angle + 1.0f > 0.05f) { 266 if (1.0f - angle >= 0.05f) { 267 float theta = acos(angle); 268 float invSinTheta = 1.0f / sin(theta); 269 scale = sin(theta * (1.0f - t)) * invSinTheta; 270 invScale = sin(theta * t) * invSinTheta; 271 } else { 272 scale = 1.0f - t; 273 invScale = t; 274 } 275 } else { 276 rsQuaternionSet(&tempq1, tempq0.z, -tempq0.y, tempq0.x, -tempq0.w); 277 scale = sin(M_PI * (0.5f - t)); 278 invScale = sin(M_PI * t); 279 } 280 281 rsQuaternionSet(q, tempq0.w*scale + tempq1.w*invScale, tempq0.x*scale + tempq1.x*invScale, 282 tempq0.y*scale + tempq1.y*invScale, tempq0.z*scale + tempq1.z*invScale); 283 test: none 284 end: 285 286 # New versions. Same signatures but don't contain a body. 287 function: rsQuaternionAdd 288 version: 24 289 ret: void 290 arg: rs_quaternion* q 291 arg: const rs_quaternion* rhs 292 test: none 293 end: 294 295 function: rsQuaternionConjugate 296 version: 24 297 ret: void 298 arg: rs_quaternion* q 299 test: none 300 end: 301 302 function: rsQuaternionDot 303 version: 24 304 ret: float 305 arg: const rs_quaternion* q0 306 arg: const rs_quaternion* q1 307 test: none 308 end: 309 310 function: rsQuaternionGetMatrixUnit 311 version: 24 312 ret: void 313 arg: rs_matrix4x4* m 314 arg: const rs_quaternion* q 315 test: none 316 end: 317 318 function: rsQuaternionLoadRotateUnit 319 version: 24 320 ret: void 321 arg: rs_quaternion* q 322 arg: float rot 323 arg: float x 324 arg: float y 325 arg: float z 326 test: none 327 end: 328 329 function: rsQuaternionSet 330 version: 24 331 ret: void 332 arg: rs_quaternion* q 333 arg: float w 334 arg: float x 335 arg: float y 336 arg: float z 337 test: none 338 end: 339 340 function: rsQuaternionSet 341 version: 24 342 ret: void 343 arg: rs_quaternion* q 344 arg: const rs_quaternion* rhs 345 test: none 346 end: 347 348 # NOTE: The following inline definitions depend on each other. The order must be preserved 349 # for the compilation to work. 350 351 function: rsQuaternionLoadRotate 352 version: 24 353 ret: void 354 arg: rs_quaternion* q 355 arg: float rot 356 arg: float x 357 arg: float y 358 arg: float z 359 test: none 360 end: 361 362 function: rsQuaternionNormalize 363 version: 24 364 ret: void 365 arg: rs_quaternion* q 366 test: none 367 end: 368 369 function: rsQuaternionMultiply 370 version: 24 371 ret: void 372 arg: rs_quaternion* q 373 arg: float scalar 374 test: none 375 end: 376 377 function: rsQuaternionMultiply 378 version: 24 379 ret: void 380 arg: rs_quaternion* q 381 arg: const rs_quaternion* rhs 382 test: none 383 end: 384 385 function: rsQuaternionSlerp 386 version: 24 387 ret: void 388 arg: rs_quaternion* q 389 arg: const rs_quaternion* q0 390 arg: const rs_quaternion* q1 391 arg: float t 392 test: none 393 end: 394
