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