1/* 2 * Copyright (C) 2016 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// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh. 18 19/* 20 * rs_matrix.rsh: Matrix Functions 21 * 22 * These functions let you manipulate square matrices of rank 2x2, 3x3, and 4x4. 23 * They are particularly useful for graphical transformations and are compatible 24 * with OpenGL. 25 * 26 * We use a zero-based index for rows and columns. E.g. the last element of a 27 * rs_matrix4x4 is found at (3, 3). 28 * 29 * RenderScript uses column-major matrices and column-based vectors. Transforming 30 * a vector is done by postmultiplying the vector, e.g. (matrix * vector), 31 * as provided by rsMatrixMultiply(). 32 * 33 * To create a transformation matrix that performs two transformations at once, 34 * multiply the two source matrices, with the first transformation as the right 35 * argument. E.g. to create a transformation matrix that applies the 36 * transformation s1 followed by s2, call rsMatrixLoadMultiply(&combined, &s2, &s1). 37 * This derives from s2 * (s1 * v), which is (s2 * s1) * v. 38 * 39 * We have two style of functions to create transformation matrices: 40 * rsMatrixLoadTransformation and rsMatrixTransformation. The former 41 * style simply stores the transformation matrix in the first argument. The latter 42 * modifies a pre-existing transformation matrix so that the new transformation 43 * happens first. E.g. if you call rsMatrixTranslate() on a matrix that already 44 * does a scaling, the resulting matrix when applied to a vector will first do the 45 * translation then the scaling. 46 */ 47 48#ifndef RENDERSCRIPT_RS_MATRIX_RSH 49#define RENDERSCRIPT_RS_MATRIX_RSH 50 51#include "rs_vector_math.rsh" 52 53/* 54 * rsExtractFrustumPlanes: Compute frustum planes 55 * 56 * Computes 6 frustum planes from the view projection matrix 57 * 58 * Parameters: 59 * viewProj: Matrix to extract planes from. 60 * left: Left plane. 61 * right: Right plane. 62 * top: Top plane. 63 * bottom: Bottom plane. 64 * near: Near plane. 65 * far: Far plane. 66 */ 67#if !defined(RS_VERSION) || (RS_VERSION <= 23) 68static inline void __attribute__((overloadable)) 69 rsExtractFrustumPlanes(const rs_matrix4x4* viewProj, float4* left, float4* right, float4* top, 70 float4* bottom, float4* near, float4* far) { 71 // x y z w = a b c d in the plane equation 72 left->x = viewProj->m[3] + viewProj->m[0]; 73 left->y = viewProj->m[7] + viewProj->m[4]; 74 left->z = viewProj->m[11] + viewProj->m[8]; 75 left->w = viewProj->m[15] + viewProj->m[12]; 76 77 right->x = viewProj->m[3] - viewProj->m[0]; 78 right->y = viewProj->m[7] - viewProj->m[4]; 79 right->z = viewProj->m[11] - viewProj->m[8]; 80 right->w = viewProj->m[15] - viewProj->m[12]; 81 82 top->x = viewProj->m[3] - viewProj->m[1]; 83 top->y = viewProj->m[7] - viewProj->m[5]; 84 top->z = viewProj->m[11] - viewProj->m[9]; 85 top->w = viewProj->m[15] - viewProj->m[13]; 86 87 bottom->x = viewProj->m[3] + viewProj->m[1]; 88 bottom->y = viewProj->m[7] + viewProj->m[5]; 89 bottom->z = viewProj->m[11] + viewProj->m[9]; 90 bottom->w = viewProj->m[15] + viewProj->m[13]; 91 92 near->x = viewProj->m[3] + viewProj->m[2]; 93 near->y = viewProj->m[7] + viewProj->m[6]; 94 near->z = viewProj->m[11] + viewProj->m[10]; 95 near->w = viewProj->m[15] + viewProj->m[14]; 96 97 far->x = viewProj->m[3] - viewProj->m[2]; 98 far->y = viewProj->m[7] - viewProj->m[6]; 99 far->z = viewProj->m[11] - viewProj->m[10]; 100 far->w = viewProj->m[15] - viewProj->m[14]; 101 102 float len = length(left->xyz); 103 *left /= len; 104 len = length(right->xyz); 105 *right /= len; 106 len = length(top->xyz); 107 *top /= len; 108 len = length(bottom->xyz); 109 *bottom /= len; 110 len = length(near->xyz); 111 *near /= len; 112 len = length(far->xyz); 113 *far /= len; 114} 115#endif 116 117#if (defined(RS_VERSION) && (RS_VERSION >= 24)) 118extern void __attribute__((overloadable)) 119 rsExtractFrustumPlanes(const rs_matrix4x4* viewProj, float4* left, float4* righ, float4* top, 120 float4* bottom, float4* near, float4* far); 121#endif 122 123/* 124 * rsIsSphereInFrustum: Checks if a sphere is within the frustum planes 125 * 126 * Returns true if the sphere is within the 6 frustum planes. 127 * 128 * Parameters: 129 * sphere: float4 representing the sphere. 130 * left: Left plane. 131 * right: Right plane. 132 * top: Top plane. 133 * bottom: Bottom plane. 134 * near: Near plane. 135 * far: Far plane. 136 */ 137#if !defined(RS_VERSION) || (RS_VERSION <= 23) 138static inline bool __attribute__((always_inline, overloadable)) 139 rsIsSphereInFrustum(float4* sphere, float4* left, float4* right, float4* top, float4* bottom, 140 float4* near, float4* far) { 141 float distToCenter = dot(left->xyz, sphere->xyz) + left->w; 142 if (distToCenter < -sphere->w) { 143 return false; 144 } 145 distToCenter = dot(right->xyz, sphere->xyz) + right->w; 146 if (distToCenter < -sphere->w) { 147 return false; 148 } 149 distToCenter = dot(top->xyz, sphere->xyz) + top->w; 150 if (distToCenter < -sphere->w) { 151 return false; 152 } 153 distToCenter = dot(bottom->xyz, sphere->xyz) + bottom->w; 154 if (distToCenter < -sphere->w) { 155 return false; 156 } 157 distToCenter = dot(near->xyz, sphere->xyz) + near->w; 158 if (distToCenter < -sphere->w) { 159 return false; 160 } 161 distToCenter = dot(far->xyz, sphere->xyz) + far->w; 162 if (distToCenter < -sphere->w) { 163 return false; 164 } 165 return true; 166} 167#endif 168 169#if (defined(RS_VERSION) && (RS_VERSION >= 24)) 170extern bool __attribute__((overloadable)) 171 rsIsSphereInFrustum(float4* sphere, float4* left, float4* right, float4* top, float4* bottom, 172 float4* near, float4* far); 173#endif 174 175/* 176 * rsMatrixGet: Get one element 177 * 178 * Returns one element of a matrix. 179 * 180 * Warning: The order of the column and row parameters may be unexpected. 181 * 182 * Parameters: 183 * m: Matrix to extract the element from. 184 * col: Zero-based column of the element to be extracted. 185 * row: Zero-based row of the element to extracted. 186 */ 187extern float __attribute__((overloadable)) 188 rsMatrixGet(const rs_matrix4x4* m, uint32_t col, uint32_t row); 189 190extern float __attribute__((overloadable)) 191 rsMatrixGet(const rs_matrix3x3* m, uint32_t col, uint32_t row); 192 193extern float __attribute__((overloadable)) 194 rsMatrixGet(const rs_matrix2x2* m, uint32_t col, uint32_t row); 195 196/* 197 * rsMatrixInverse: Inverts a matrix in place 198 * 199 * Returns true if the matrix was successfully inverted. 200 * 201 * Parameters: 202 * m: Matrix to invert. 203 */ 204extern bool __attribute__((overloadable)) 205 rsMatrixInverse(rs_matrix4x4* m); 206 207/* 208 * rsMatrixInverseTranspose: Inverts and transpose a matrix in place 209 * 210 * The matrix is first inverted then transposed. Returns true if the matrix was 211 * successfully inverted. 212 * 213 * Parameters: 214 * m: Matrix to modify. 215 */ 216extern bool __attribute__((overloadable)) 217 rsMatrixInverseTranspose(rs_matrix4x4* m); 218 219/* 220 * rsMatrixLoad: Load or copy a matrix 221 * 222 * Set the elements of a matrix from an array of floats or from another matrix. 223 * 224 * If loading from an array, the floats should be in row-major order, i.e. the element a 225 * row 0, column 0 should be first, followed by the element at 226 * row 0, column 1, etc. 227 * 228 * If loading from a matrix and the source is smaller than the destination, the rest 229 * of the destination is filled with elements of the identity matrix. E.g. 230 * loading a rs_matrix2x2 into a rs_matrix4x4 will give: 231 * 232 * m00 m01 0.0 0.0 233 * m10 m11 0.0 0.0 234 * 0.0 0.0 1.0 0.0 235 * 0.0 0.0 0.0 1.0 236 * 237 * 238 * Parameters: 239 * destination: Matrix to set. 240 * array: Array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size. 241 * source: Source matrix. 242 */ 243extern void __attribute__((overloadable)) 244 rsMatrixLoad(rs_matrix4x4* destination, const float* array); 245 246extern void __attribute__((overloadable)) 247 rsMatrixLoad(rs_matrix3x3* destination, const float* array); 248 249extern void __attribute__((overloadable)) 250 rsMatrixLoad(rs_matrix2x2* destination, const float* array); 251 252extern void __attribute__((overloadable)) 253 rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix4x4* source); 254 255extern void __attribute__((overloadable)) 256 rsMatrixLoad(rs_matrix3x3* destination, const rs_matrix3x3* source); 257 258extern void __attribute__((overloadable)) 259 rsMatrixLoad(rs_matrix2x2* destination, const rs_matrix2x2* source); 260 261extern void __attribute__((overloadable)) 262 rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix3x3* source); 263 264extern void __attribute__((overloadable)) 265 rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix2x2* source); 266 267/* 268 * rsMatrixLoadFrustum: Load a frustum projection matrix 269 * 270 * Constructs a frustum projection matrix, transforming the box identified by 271 * the six clipping planes left, right, bottom, top, near, far. 272 * 273 * To apply this projection to a vector, multiply the vector by the created 274 * matrix using rsMatrixMultiply(). 275 * 276 * Parameters: 277 * m: Matrix to set. 278 */ 279extern void __attribute__((overloadable)) 280 rsMatrixLoadFrustum(rs_matrix4x4* m, float left, float right, float bottom, float top, 281 float near, float far); 282 283/* 284 * rsMatrixLoadIdentity: Load identity matrix 285 * 286 * Set the elements of a matrix to the identity matrix. 287 * 288 * Parameters: 289 * m: Matrix to set. 290 */ 291extern void __attribute__((overloadable)) 292 rsMatrixLoadIdentity(rs_matrix4x4* m); 293 294extern void __attribute__((overloadable)) 295 rsMatrixLoadIdentity(rs_matrix3x3* m); 296 297extern void __attribute__((overloadable)) 298 rsMatrixLoadIdentity(rs_matrix2x2* m); 299 300/* 301 * rsMatrixLoadMultiply: Multiply two matrices 302 * 303 * Sets m to the matrix product of lhs * rhs. 304 * 305 * To combine two 4x4 transformaton matrices, multiply the second transformation matrix 306 * by the first transformation matrix. E.g. to create a transformation matrix that applies 307 * the transformation s1 followed by s2, call rsMatrixLoadMultiply(&combined, &s2, &s1). 308 * 309 * Warning: Prior to version 21, storing the result back into right matrix is not supported and 310 * will result in undefined behavior. Use rsMatrixMulitply instead. E.g. instead of doing 311 * rsMatrixLoadMultiply (&m2r, &m2r, &m2l), use rsMatrixMultiply (&m2r, &m2l). 312 * rsMatrixLoadMultiply (&m2l, &m2r, &m2l) works as expected. 313 * 314 * Parameters: 315 * m: Matrix to set. 316 * lhs: Left matrix of the product. 317 * rhs: Right matrix of the product. 318 */ 319extern void __attribute__((overloadable)) 320 rsMatrixLoadMultiply(rs_matrix4x4* m, const rs_matrix4x4* lhs, const rs_matrix4x4* rhs); 321 322extern void __attribute__((overloadable)) 323 rsMatrixLoadMultiply(rs_matrix3x3* m, const rs_matrix3x3* lhs, const rs_matrix3x3* rhs); 324 325extern void __attribute__((overloadable)) 326 rsMatrixLoadMultiply(rs_matrix2x2* m, const rs_matrix2x2* lhs, const rs_matrix2x2* rhs); 327 328/* 329 * rsMatrixLoadOrtho: Load an orthographic projection matrix 330 * 331 * Constructs an orthographic projection matrix, transforming the box identified by the 332 * six clipping planes left, right, bottom, top, near, far into a unit cube 333 * with a corner at (-1, -1, -1) and the opposite at (1, 1, 1). 334 * 335 * To apply this projection to a vector, multiply the vector by the created matrix 336 * using rsMatrixMultiply(). 337 * 338 * See https://en.wikipedia.org/wiki/Orthographic_projection . 339 * 340 * Parameters: 341 * m: Matrix to set. 342 */ 343extern void __attribute__((overloadable)) 344 rsMatrixLoadOrtho(rs_matrix4x4* m, float left, float right, float bottom, float top, float near, 345 float far); 346 347/* 348 * rsMatrixLoadPerspective: Load a perspective projection matrix 349 * 350 * Constructs a perspective projection matrix, assuming a symmetrical field of view. 351 * 352 * To apply this projection to a vector, multiply the vector by the created matrix 353 * using rsMatrixMultiply(). 354 * 355 * Parameters: 356 * m: Matrix to set. 357 * fovy: Field of view, in degrees along the Y axis. 358 * aspect: Ratio of x / y. 359 * near: Near clipping plane. 360 * far: Far clipping plane. 361 */ 362extern void __attribute__((overloadable)) 363 rsMatrixLoadPerspective(rs_matrix4x4* m, float fovy, float aspect, float near, float far); 364 365/* 366 * rsMatrixLoadRotate: Load a rotation matrix 367 * 368 * This function creates a rotation matrix. The axis of rotation is the (x, y, z) vector. 369 * 370 * To rotate a vector, multiply the vector by the created matrix using rsMatrixMultiply(). 371 * 372 * See http://en.wikipedia.org/wiki/Rotation_matrix . 373 * 374 * Parameters: 375 * m: Matrix to set. 376 * rot: How much rotation to do, in degrees. 377 * x: X component of the vector that is the axis of rotation. 378 * y: Y component of the vector that is the axis of rotation. 379 * z: Z component of the vector that is the axis of rotation. 380 */ 381extern void __attribute__((overloadable)) 382 rsMatrixLoadRotate(rs_matrix4x4* m, float rot, float x, float y, float z); 383 384/* 385 * rsMatrixLoadScale: Load a scaling matrix 386 * 387 * This function creates a scaling matrix, where each component of a vector is multiplied 388 * by a number. This number can be negative. 389 * 390 * To scale a vector, multiply the vector by the created matrix using rsMatrixMultiply(). 391 * 392 * Parameters: 393 * m: Matrix to set. 394 * x: Multiple to scale the x components by. 395 * y: Multiple to scale the y components by. 396 * z: Multiple to scale the z components by. 397 */ 398extern void __attribute__((overloadable)) 399 rsMatrixLoadScale(rs_matrix4x4* m, float x, float y, float z); 400 401/* 402 * rsMatrixLoadTranslate: Load a translation matrix 403 * 404 * This function creates a translation matrix, where a number is added to each element of 405 * a vector. 406 * 407 * To translate a vector, multiply the vector by the created matrix using 408 * rsMatrixMultiply(). 409 * 410 * Parameters: 411 * m: Matrix to set. 412 * x: Number to add to each x component. 413 * y: Number to add to each y component. 414 * z: Number to add to each z component. 415 */ 416extern void __attribute__((overloadable)) 417 rsMatrixLoadTranslate(rs_matrix4x4* m, float x, float y, float z); 418 419/* 420 * rsMatrixMultiply: Multiply a matrix by a vector or another matrix 421 * 422 * For the matrix by matrix variant, sets m to the matrix product m * rhs. 423 * 424 * When combining two 4x4 transformation matrices using this function, the resulting 425 * matrix will correspond to performing the rhs transformation first followed by 426 * the original m transformation. 427 * 428 * For the matrix by vector variant, returns the post-multiplication of the vector 429 * by the matrix, ie. m * in. 430 * 431 * When multiplying a float3 to a rs_matrix4x4, the vector is expanded with (1). 432 * 433 * When multiplying a float2 to a rs_matrix4x4, the vector is expanded with (0, 1). 434 * 435 * When multiplying a float2 to a rs_matrix3x3, the vector is expanded with (0). 436 * 437 * Starting with API 14, this function takes a const matrix as the first argument. 438 * 439 * Parameters: 440 * m: Left matrix of the product and the matrix to be set. 441 * rhs: Right matrix of the product. 442 */ 443extern void __attribute__((overloadable)) 444 rsMatrixMultiply(rs_matrix4x4* m, const rs_matrix4x4* rhs); 445 446extern void __attribute__((overloadable)) 447 rsMatrixMultiply(rs_matrix3x3* m, const rs_matrix3x3* rhs); 448 449extern void __attribute__((overloadable)) 450 rsMatrixMultiply(rs_matrix2x2* m, const rs_matrix2x2* rhs); 451 452#if !defined(RS_VERSION) || (RS_VERSION <= 13) 453extern float4 __attribute__((overloadable)) 454 rsMatrixMultiply(rs_matrix4x4* m, float4 in); 455#endif 456 457#if !defined(RS_VERSION) || (RS_VERSION <= 13) 458extern float4 __attribute__((overloadable)) 459 rsMatrixMultiply(rs_matrix4x4* m, float3 in); 460#endif 461 462#if !defined(RS_VERSION) || (RS_VERSION <= 13) 463extern float4 __attribute__((overloadable)) 464 rsMatrixMultiply(rs_matrix4x4* m, float2 in); 465#endif 466 467#if !defined(RS_VERSION) || (RS_VERSION <= 13) 468extern float3 __attribute__((overloadable)) 469 rsMatrixMultiply(rs_matrix3x3* m, float3 in); 470#endif 471 472#if !defined(RS_VERSION) || (RS_VERSION <= 13) 473extern float3 __attribute__((overloadable)) 474 rsMatrixMultiply(rs_matrix3x3* m, float2 in); 475#endif 476 477#if !defined(RS_VERSION) || (RS_VERSION <= 13) 478extern float2 __attribute__((overloadable)) 479 rsMatrixMultiply(rs_matrix2x2* m, float2 in); 480#endif 481 482#if (defined(RS_VERSION) && (RS_VERSION >= 14)) 483extern float4 __attribute__((overloadable)) 484 rsMatrixMultiply(const rs_matrix4x4* m, float4 in); 485#endif 486 487#if (defined(RS_VERSION) && (RS_VERSION >= 14)) 488extern float4 __attribute__((overloadable)) 489 rsMatrixMultiply(const rs_matrix4x4* m, float3 in); 490#endif 491 492#if (defined(RS_VERSION) && (RS_VERSION >= 14)) 493extern float4 __attribute__((overloadable)) 494 rsMatrixMultiply(const rs_matrix4x4* m, float2 in); 495#endif 496 497#if (defined(RS_VERSION) && (RS_VERSION >= 14)) 498extern float3 __attribute__((overloadable)) 499 rsMatrixMultiply(const rs_matrix3x3* m, float3 in); 500#endif 501 502#if (defined(RS_VERSION) && (RS_VERSION >= 14)) 503extern float3 __attribute__((overloadable)) 504 rsMatrixMultiply(const rs_matrix3x3* m, float2 in); 505#endif 506 507#if (defined(RS_VERSION) && (RS_VERSION >= 14)) 508extern float2 __attribute__((overloadable)) 509 rsMatrixMultiply(const rs_matrix2x2* m, float2 in); 510#endif 511 512/* 513 * rsMatrixRotate: Apply a rotation to a transformation matrix 514 * 515 * Multiply the matrix m with a rotation matrix. 516 * 517 * This function modifies a transformation matrix to first do a rotation. The axis of 518 * rotation is the (x, y, z) vector. 519 * 520 * To apply this combined transformation to a vector, multiply the vector by the created 521 * matrix using rsMatrixMultiply(). 522 * 523 * Parameters: 524 * m: Matrix to modify. 525 * rot: How much rotation to do, in degrees. 526 * x: X component of the vector that is the axis of rotation. 527 * y: Y component of the vector that is the axis of rotation. 528 * z: Z component of the vector that is the axis of rotation. 529 */ 530extern void __attribute__((overloadable)) 531 rsMatrixRotate(rs_matrix4x4* m, float rot, float x, float y, float z); 532 533/* 534 * rsMatrixScale: Apply a scaling to a transformation matrix 535 * 536 * Multiply the matrix m with a scaling matrix. 537 * 538 * This function modifies a transformation matrix to first do a scaling. When scaling, 539 * each component of a vector is multiplied by a number. This number can be negative. 540 * 541 * To apply this combined transformation to a vector, multiply the vector by the created 542 * matrix using rsMatrixMultiply(). 543 * 544 * Parameters: 545 * m: Matrix to modify. 546 * x: Multiple to scale the x components by. 547 * y: Multiple to scale the y components by. 548 * z: Multiple to scale the z components by. 549 */ 550extern void __attribute__((overloadable)) 551 rsMatrixScale(rs_matrix4x4* m, float x, float y, float z); 552 553/* 554 * rsMatrixSet: Set one element 555 * 556 * Set an element of a matrix. 557 * 558 * Warning: The order of the column and row parameters may be unexpected. 559 * 560 * Parameters: 561 * m: Matrix that will be modified. 562 * col: Zero-based column of the element to be set. 563 * row: Zero-based row of the element to be set. 564 * v: Value to set. 565 */ 566extern void __attribute__((overloadable)) 567 rsMatrixSet(rs_matrix4x4* m, uint32_t col, uint32_t row, float v); 568 569extern void __attribute__((overloadable)) 570 rsMatrixSet(rs_matrix3x3* m, uint32_t col, uint32_t row, float v); 571 572extern void __attribute__((overloadable)) 573 rsMatrixSet(rs_matrix2x2* m, uint32_t col, uint32_t row, float v); 574 575/* 576 * rsMatrixTranslate: Apply a translation to a transformation matrix 577 * 578 * Multiply the matrix m with a translation matrix. 579 * 580 * This function modifies a transformation matrix to first do a translation. When 581 * translating, a number is added to each component of a vector. 582 * 583 * To apply this combined transformation to a vector, multiply the vector by the 584 * created matrix using rsMatrixMultiply(). 585 * 586 * Parameters: 587 * m: Matrix to modify. 588 * x: Number to add to each x component. 589 * y: Number to add to each y component. 590 * z: Number to add to each z component. 591 */ 592extern void __attribute__((overloadable)) 593 rsMatrixTranslate(rs_matrix4x4* m, float x, float y, float z); 594 595/* 596 * rsMatrixTranspose: Transpose a matrix place 597 * 598 * Transpose the matrix m in place. 599 * 600 * Parameters: 601 * m: Matrix to transpose. 602 */ 603extern void __attribute__((overloadable)) 604 rsMatrixTranspose(rs_matrix4x4* m); 605 606extern void __attribute__((overloadable)) 607 rsMatrixTranspose(rs_matrix3x3* m); 608 609extern void __attribute__((overloadable)) 610 rsMatrixTranspose(rs_matrix2x2* m); 611 612#endif // RENDERSCRIPT_RS_MATRIX_RSH 613