diff options
author | Jean-Luc Brouillet <jeanluc@google.com> | 2014-09-05 17:44:48 -0700 |
---|---|---|
committer | Jean-Luc Brouillet <jeanluc@google.com> | 2014-09-08 15:40:58 -0700 |
commit | 1bb2eed69caa28cf8198d58db7d9134cc2f563f5 (patch) | |
tree | a13139843a108be78b86d4f1eef0fe574055c1a7 | |
parent | 33164686a7ac88d4eda38201be4127937e9c12b0 (diff) | |
download | rs-1bb2eed69caa28cf8198d58db7d9134cc2f563f5.tar.gz |
Improve rsMatrix* documentation, fix bugs
Improves the user-facing documentation. Fix the incorrect row & column
naming on the Get/Set API. Fix a bug where rsMatrixLoadMultiply could
not have the destination be one of the source,
e.g. rsMatrixLoadMultiply(&l, &l, &r)
Change-Id: I42207aacf4ebe815d4a79db2aaa9c44f85864696
-rw-r--r-- | driver/runtime/rs_matrix.c | 66 | ||||
-rw-r--r-- | rsMatrix2x2.cpp | 8 | ||||
-rw-r--r-- | rsMatrix2x2.h | 12 | ||||
-rw-r--r-- | rsMatrix3x3.cpp | 10 | ||||
-rw-r--r-- | rsMatrix3x3.h | 12 | ||||
-rw-r--r-- | rsMatrix4x4.cpp | 13 | ||||
-rw-r--r-- | rsMatrix4x4.h | 13 | ||||
-rw-r--r-- | scriptc/rs_matrix.rsh | 308 |
8 files changed, 305 insertions, 137 deletions
diff --git a/driver/runtime/rs_matrix.c b/driver/runtime/rs_matrix.c index 052e829a..064f2339 100644 --- a/driver/runtime/rs_matrix.c +++ b/driver/runtime/rs_matrix.c @@ -170,33 +170,33 @@ rsMatrixLoad(rs_matrix2x2 *m, const rs_matrix2x2 *s) { extern void __attribute__((overloadable)) -rsMatrixSet(rs_matrix4x4 *m, uint32_t row, uint32_t col, float v) { - m->m[row * 4 + col] = v; +rsMatrixSet(rs_matrix4x4 *m, uint32_t col, uint32_t row, float v) { + m->m[col * 4 + row] = v; } extern float __attribute__((overloadable)) -rsMatrixGet(const rs_matrix4x4 *m, uint32_t row, uint32_t col) { - return m->m[row * 4 + col]; +rsMatrixGet(const rs_matrix4x4 *m, uint32_t col, uint32_t row) { + return m->m[col * 4 + row]; } extern void __attribute__((overloadable)) -rsMatrixSet(rs_matrix3x3 *m, uint32_t row, uint32_t col, float v) { - m->m[row * 3 + col] = v; +rsMatrixSet(rs_matrix3x3 *m, uint32_t col, uint32_t row, float v) { + m->m[col * 3 + row] = v; } extern float __attribute__((overloadable)) -rsMatrixGet(const rs_matrix3x3 *m, uint32_t row, uint32_t col) { - return m->m[row * 3 + col]; +rsMatrixGet(const rs_matrix3x3 *m, uint32_t col, uint32_t row) { + return m->m[col * 3 + row]; } extern void __attribute__((overloadable)) -rsMatrixSet(rs_matrix2x2 *m, uint32_t row, uint32_t col, float v) { - m->m[row * 2 + col] = v; +rsMatrixSet(rs_matrix2x2 *m, uint32_t col, uint32_t row, float v) { + m->m[col * 2 + row] = v; } extern float __attribute__((overloadable)) -rsMatrixGet(const rs_matrix2x2 *m, uint32_t row, uint32_t col) { - return m->m[row * 2 + col]; +rsMatrixGet(const rs_matrix2x2 *m, uint32_t col, uint32_t row) { + return m->m[col * 2 + row]; } extern float2 __attribute__((overloadable)) @@ -238,6 +238,9 @@ rsMatrixMultiply(rs_matrix3x3 *m, float2 in) { extern void __attribute__((overloadable)) rsMatrixLoadMultiply(rs_matrix4x4 *ret, const rs_matrix4x4 *lhs, const rs_matrix4x4 *rhs) { + // Use a temporary variable to support the case where one of the inputs + // is also the destination, e.g. rsMatrixLoadMultiply(&left, &left, &right); + rs_matrix4x4 result; for (int i=0 ; i<4 ; i++) { float ri0 = 0; float ri1 = 0; @@ -250,22 +253,24 @@ rsMatrixLoadMultiply(rs_matrix4x4 *ret, const rs_matrix4x4 *lhs, const rs_matrix ri2 += rsMatrixGet(lhs, j, 2) * rhs_ij; ri3 += rsMatrixGet(lhs, j, 3) * rhs_ij; } - rsMatrixSet(ret, i, 0, ri0); - rsMatrixSet(ret, i, 1, ri1); - rsMatrixSet(ret, i, 2, ri2); - rsMatrixSet(ret, i, 3, ri3); + rsMatrixSet(&result, i, 0, ri0); + rsMatrixSet(&result, i, 1, ri1); + rsMatrixSet(&result, i, 2, ri2); + rsMatrixSet(&result, i, 3, ri3); } + rsMatrixLoad(ret, &result); } extern void __attribute__((overloadable)) rsMatrixMultiply(rs_matrix4x4 *lhs, const rs_matrix4x4 *rhs) { - rs_matrix4x4 r; - rsMatrixLoadMultiply(&r, lhs, rhs); - rsMatrixLoad(lhs, &r); + rsMatrixLoadMultiply(lhs, lhs, rhs); } extern void __attribute__((overloadable)) rsMatrixLoadMultiply(rs_matrix3x3 *ret, const rs_matrix3x3 *lhs, const rs_matrix3x3 *rhs) { + // Use a temporary variable to support the case where one of the inputs + // is also the destination, e.g. rsMatrixLoadMultiply(&left, &left, &right); + rs_matrix3x3 result; for (int i=0 ; i<3 ; i++) { float ri0 = 0; float ri1 = 0; @@ -276,21 +281,23 @@ rsMatrixLoadMultiply(rs_matrix3x3 *ret, const rs_matrix3x3 *lhs, const rs_matrix ri1 += rsMatrixGet(lhs, j, 1) * rhs_ij; ri2 += rsMatrixGet(lhs, j, 2) * rhs_ij; } - rsMatrixSet(ret, i, 0, ri0); - rsMatrixSet(ret, i, 1, ri1); - rsMatrixSet(ret, i, 2, ri2); + rsMatrixSet(&result, i, 0, ri0); + rsMatrixSet(&result, i, 1, ri1); + rsMatrixSet(&result, i, 2, ri2); } + rsMatrixLoad(ret, &result); } extern void __attribute__((overloadable)) rsMatrixMultiply(rs_matrix3x3 *lhs, const rs_matrix3x3 *rhs) { - rs_matrix3x3 r; - rsMatrixLoadMultiply(&r, lhs, rhs); - rsMatrixLoad(lhs, &r); + rsMatrixLoadMultiply(lhs, lhs, rhs); } extern void __attribute__((overloadable)) rsMatrixLoadMultiply(rs_matrix2x2 *ret, const rs_matrix2x2 *lhs, const rs_matrix2x2 *rhs) { + // Use a temporary variable to support the case where one of the inputs + // is also the destination, e.g. rsMatrixLoadMultiply(&left, &left, &right); + rs_matrix2x2 result; for (int i=0 ; i<2 ; i++) { float ri0 = 0; float ri1 = 0; @@ -299,15 +306,14 @@ rsMatrixLoadMultiply(rs_matrix2x2 *ret, const rs_matrix2x2 *lhs, const rs_matrix ri0 += rsMatrixGet(lhs, j, 0) * rhs_ij; ri1 += rsMatrixGet(lhs, j, 1) * rhs_ij; } - rsMatrixSet(ret, i, 0, ri0); - rsMatrixSet(ret, i, 1, ri1); + rsMatrixSet(&result, i, 0, ri0); + rsMatrixSet(&result, i, 1, ri1); } + rsMatrixLoad(ret, &result); } extern void __attribute__((overloadable)) rsMatrixMultiply(rs_matrix2x2 *lhs, const rs_matrix2x2 *rhs) { - rs_matrix2x2 r; - rsMatrixLoadMultiply(&r, lhs, rhs); - rsMatrixLoad(lhs, &r); + rsMatrixLoadMultiply(lhs, lhs, rhs); } diff --git a/rsMatrix2x2.cpp b/rsMatrix2x2.cpp index 622113ce..91accbee 100644 --- a/rsMatrix2x2.cpp +++ b/rsMatrix2x2.cpp @@ -42,6 +42,9 @@ void Matrix2x2::load(const rs_matrix2x2 *v) { } void Matrix2x2::loadMultiply(const rs_matrix2x2 *lhs, const rs_matrix2x2 *rhs) { + // Use a temporary variable to support the case where one of the inputs + // is also the destination, e.g. left.loadMultiply(left, right); + Matrix2x2 temp; for (int i=0 ; i<2 ; i++) { float ri0 = 0; float ri1 = 0; @@ -50,9 +53,10 @@ void Matrix2x2::loadMultiply(const rs_matrix2x2 *lhs, const rs_matrix2x2 *rhs) { ri0 += ((const Matrix2x2 *)lhs)->get(j, 0) * rhs_ij; ri1 += ((const Matrix2x2 *)lhs)->get(j, 1) * rhs_ij; } - set(i, 0, ri0); - set(i, 1, ri1); + temp.set(i, 0, ri0); + temp.set(i, 1, ri1); } + load(&temp); } void Matrix2x2::transpose() { diff --git a/rsMatrix2x2.h b/rsMatrix2x2.h index 4fbd1c2a..f908c0c3 100644 --- a/rsMatrix2x2.h +++ b/rsMatrix2x2.h @@ -25,12 +25,12 @@ namespace android { namespace renderscript { struct Matrix2x2 : public rs_matrix2x2 { - inline float get(uint32_t x, uint32_t y) const { - return m[x*2 + y]; + inline float get(uint32_t col, uint32_t row) const { + return m[col*2 + row]; } - inline void set(uint32_t x, uint32_t y, float v) { - m[x*2 + y] = v; + inline void set(uint32_t col, uint32_t row, float v) { + m[col*2 + row] = v; } void loadIdentity(); @@ -42,9 +42,7 @@ struct Matrix2x2 : public rs_matrix2x2 { void transpose(); void multiply(const rs_matrix2x2 *rhs) { - Matrix2x2 tmp; - tmp.loadMultiply(this, rhs); - load(&tmp); + loadMultiply(this, rhs); } }; diff --git a/rsMatrix3x3.cpp b/rsMatrix3x3.cpp index 3f9a2d18..4f27fcc2 100644 --- a/rsMatrix3x3.cpp +++ b/rsMatrix3x3.cpp @@ -46,6 +46,9 @@ void Matrix3x3::load(const rs_matrix3x3 *v) { } void Matrix3x3::loadMultiply(const rs_matrix3x3 *lhs, const rs_matrix3x3 *rhs) { + // Use a temporary variable to support the case where one of the inputs + // is also the destination, e.g. left.loadMultiply(left, right); + Matrix3x3 temp; for (int i=0 ; i<3 ; i++) { float ri0 = 0; float ri1 = 0; @@ -56,10 +59,11 @@ void Matrix3x3::loadMultiply(const rs_matrix3x3 *lhs, const rs_matrix3x3 *rhs) { ri1 += ((const Matrix3x3 *)lhs)->get(j, 1) * rhs_ij; ri2 += ((const Matrix3x3 *)lhs)->get(j, 2) * rhs_ij; } - set(i, 0, ri0); - set(i, 1, ri1); - set(i, 2, ri2); + temp.set(i, 0, ri0); + temp.set(i, 1, ri1); + temp.set(i, 2, ri2); } + load(&temp); } void Matrix3x3::transpose() { diff --git a/rsMatrix3x3.h b/rsMatrix3x3.h index 05249b15..5c10846a 100644 --- a/rsMatrix3x3.h +++ b/rsMatrix3x3.h @@ -25,12 +25,12 @@ namespace android { namespace renderscript { struct Matrix3x3 : public rs_matrix3x3 { - inline float get(uint32_t x, uint32_t y) const { - return m[x*3 + y]; + inline float get(uint32_t col, uint32_t row) const { + return m[col*3 + row]; } - inline void set(uint32_t x, uint32_t y, float v) { - m[x*3 + y] = v; + inline void set(uint32_t col, uint32_t row, float v) { + m[col*3 + row] = v; } void loadIdentity(); @@ -42,9 +42,7 @@ struct Matrix3x3 : public rs_matrix3x3 { void transpose(); void multiply(const rs_matrix3x3 *rhs) { - Matrix3x3 tmp; - tmp.loadMultiply(this, rhs); - load(&tmp); + loadMultiply(this, rhs); } }; diff --git a/rsMatrix4x4.cpp b/rsMatrix4x4.cpp index c6f96d8d..f166c57e 100644 --- a/rsMatrix4x4.cpp +++ b/rsMatrix4x4.cpp @@ -250,6 +250,9 @@ void Matrix4x4::loadTranslate(float x, float y, float z) { } void Matrix4x4::loadMultiply(const rs_matrix4x4 *lhs, const rs_matrix4x4 *rhs) { + // Use a temporary variable to support the case where one of the inputs + // is also the destination, e.g. left.loadMultiply(left, right); + Matrix4x4 temp; for (int i=0 ; i<4 ; i++) { float ri0 = 0; float ri1 = 0; @@ -262,11 +265,12 @@ void Matrix4x4::loadMultiply(const rs_matrix4x4 *lhs, const rs_matrix4x4 *rhs) { ri2 += ((const Matrix4x4 *)lhs)->get(j,2) * rhs_ij; ri3 += ((const Matrix4x4 *)lhs)->get(j,3) * rhs_ij; } - set(i,0, ri0); - set(i,1, ri1); - set(i,2, ri2); - set(i,3, ri3); + temp.set(i,0, ri0); + temp.set(i,1, ri1); + temp.set(i,2, ri2); + temp.set(i,3, ri3); } + load(&temp); } void Matrix4x4::loadOrtho(float left, float right, float bottom, float top, float near, float far) { @@ -299,6 +303,7 @@ void Matrix4x4::loadPerspective(float fovy, float aspect, float near, float far) loadFrustum(left, right, bottom, top, near, far); } +// Note: This assumes that the input vector (in) is of length 3. void Matrix4x4::vectorMultiply(float *out, const float *in) const { out[0] = (m[0] * in[0]) + (m[4] * in[1]) + (m[8] * in[2]) + m[12]; out[1] = (m[1] * in[0]) + (m[5] * in[1]) + (m[9] * in[2]) + m[13]; diff --git a/rsMatrix4x4.h b/rsMatrix4x4.h index 44c33d1d..8e4a5867 100644 --- a/rsMatrix4x4.h +++ b/rsMatrix4x4.h @@ -25,12 +25,12 @@ namespace android { namespace renderscript { struct Matrix4x4 : public rs_matrix4x4 { - float get(uint32_t x, uint32_t y) const { - return m[x*4 + y]; + float get(uint32_t col, uint32_t row) const { + return m[col*4 + row]; } - void set(uint32_t x, uint32_t y, float v) { - m[x*4 + y] = v; + void set(uint32_t col, uint32_t row, float v) { + m[col*4 + row] = v; } void loadIdentity(); @@ -48,6 +48,7 @@ struct Matrix4x4 : public rs_matrix4x4 { void loadFrustum(float l, float r, float b, float t, float n, float f); void loadPerspective(float fovy, float aspect, float near, float far); + // Note: This assumes that the input vector (in) is of length 3. void vectorMultiply(float *v4out, const float *v3in) const; bool inverse(); @@ -58,9 +59,7 @@ struct Matrix4x4 : public rs_matrix4x4 { void multiply(const rs_matrix4x4 *rhs) { - Matrix4x4 tmp; - tmp.loadMultiply(this, rhs); - load(&tmp); + loadMultiply(this, rhs); } void rotate(float rot, float x, float y, float z) { Matrix4x4 tmp; diff --git a/scriptc/rs_matrix.rsh b/scriptc/rs_matrix.rsh index ebff7f48..34b9532e 100644 --- a/scriptc/rs_matrix.rsh +++ b/scriptc/rs_matrix.rsh @@ -15,8 +15,35 @@ */ /** @file rs_matrix.rsh - * \brief Matrix routines + * \brief Matrix functions. * + * These functions let you manipulate square matrices of rank 2x2, 3x3, and 4x4. + * They are particularly useful for graphical transformations and are + * compatible with OpenGL. + * + * A few general notes: + * + * \li We use a zero-based index for rows and columns. E.g. the last element of + * a \ref rs_matrix4x4 is found at (3, 3). + * + * \li RenderScript uses column-based vectors. Transforming a vector is done by + * postmultiplying the vector, e.g. <em>(matrix * vector)</em>, as provided by + * \ref rsMatrixMultiply. + * + * \li To create a transformation matrix that performs two transformations at + * once, multiply the two source matrices, with the first transformation as the + * right argument. E.g. to create a transformation matrix that applies the + * transformation \e s1 followed by \e s2, call + * </c>rsMatrixLoadMultiply(&combined, &s2, &s1)</c>. + * This derives from <em>s2 * (s1 * v)</em>, which is <em>(s2 * s1) * v</em>. + * + * \li We have two style of functions to create transformation matrices: + * rsMatrixLoad<em>Transformation</em> and rsMatrix<em>Transformation</em>. The + * former style simply stores the transformation matrix in the first argument. + * The latter modifies a pre-existing transformation matrix so that the new + * transformation happens first. E.g. if you call \ref rsMatrixTranslate + * on a matrix that already does a scaling, the resulting matrix when applied + * to a vector will first do the translation then the scaling. * */ @@ -24,54 +51,60 @@ #define __RS_MATRIX_RSH__ /** - * Set one element of a matrix. + * Set an element of a matrix. + * + * @param m The matrix that will be modified. + * @param col The zero-based column of the element to be set. + * @param row The zero-based row of the element to be set. + * @param v The value to set. * - * @param m The matrix to be set - * @param row - * @param col - * @param v + * \warning The order of the column and row parameters may be + * unexpected. * * @return void */ _RS_RUNTIME void __attribute__((overloadable)) -rsMatrixSet(rs_matrix4x4 *m, uint32_t row, uint32_t col, float v); +rsMatrixSet(rs_matrix4x4 *m, uint32_t col, uint32_t row, float v); /** * \overload */ _RS_RUNTIME void __attribute__((overloadable)) -rsMatrixSet(rs_matrix3x3 *m, uint32_t row, uint32_t col, float v); +rsMatrixSet(rs_matrix3x3 *m, uint32_t col, uint32_t row, float v); /** * \overload */ _RS_RUNTIME void __attribute__((overloadable)) -rsMatrixSet(rs_matrix2x2 *m, uint32_t row, uint32_t col, float v); +rsMatrixSet(rs_matrix2x2 *m, uint32_t col, uint32_t row, float v); /** - * Get one element of a matrix. + * Returns one element of a matrix. + * + * @param m The matrix to extract the element from. + * @param col The zero-based column of the element to be extracted. + * @param row The zero-based row of the element to extracted. * - * @param m The matrix to read from - * @param row - * @param col + * \warning The order of the column and row parameters may be + * unexpected. * * @return float */ _RS_RUNTIME float __attribute__((overloadable)) -rsMatrixGet(const rs_matrix4x4 *m, uint32_t row, uint32_t col); +rsMatrixGet(const rs_matrix4x4 *m, uint32_t col, uint32_t row); /** * \overload */ _RS_RUNTIME float __attribute__((overloadable)) -rsMatrixGet(const rs_matrix3x3 *m, uint32_t row, uint32_t col); +rsMatrixGet(const rs_matrix3x3 *m, uint32_t col, uint32_t row); /** * \overload */ _RS_RUNTIME float __attribute__((overloadable)) -rsMatrixGet(const rs_matrix2x2 *m, uint32_t row, uint32_t col); +rsMatrixGet(const rs_matrix2x2 *m, uint32_t col, uint32_t row); /** * Set the elements of a matrix to the identity matrix. * - * @param m + * @param m The matrix to set. */ extern void __attribute__((overloadable)) rsMatrixLoadIdentity(rs_matrix4x4 *m); /** @@ -86,7 +119,13 @@ extern void __attribute__((overloadable)) rsMatrixLoadIdentity(rs_matrix2x2 *m); /** * Set the elements of a matrix from an array of floats. * - * @param m + * The array of floats should be in row-major order, i.e. the element a + * <em>row 0, column 0</em> should be first, followed by the element at + * <em>row 0, column 1</em>, etc. + * + * @param m The matrix to set. + * @param v The array of values to set the matrix to. These arrays should be + * 4, 9, or 16 floats long, depending on the matrix size. */ extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix4x4 *m, const float *v); /** @@ -98,18 +137,29 @@ extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix3x3 *m, const fl */ extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix2x2 *m, const float *v); /** - * \overload + * Set the elements of a matrix from another matrix. + * + * If the source matrix is smaller than the destination, the rest of the + * destination is filled with elements of the identity matrix. E.g. + * loading a rs_matrix2x2 into a rs_matrix4x4 will give: + * + * \htmlonly<table> + * <tr><td>m00</td><td>m01</td><td>0.0</td><td>0.0</td></tr> + * <tr><td>m10</td><td>m11</td><td>0.0</td><td>0.0</td></tr> + * <tr><td>0.0</td><td>0.0</td><td>1.0</td><td>0.0</td></tr> + * <tr><td>0.0</td><td>0.0</td><td>0.0</td><td>1.0</td></tr> + * </table>\endhtmlonly + * + * @param m The matrix to set. + * @param v The source matrix. */ extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix4x4 *m, const rs_matrix4x4 *v); /** * \overload */ extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix4x4 *m, const rs_matrix3x3 *v); - /** - * Set the elements of a matrix from another matrix. - * - * @param m + * \overload */ extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix4x4 *m, const rs_matrix2x2 *v); /** @@ -124,11 +174,19 @@ extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix2x2 *m, const rs /** * Load a rotation matrix. * - * @param m - * @param rot - * @param x - * @param y - * @param z + * This function creates a rotation matrix. The axis of rotation is the + * <em>(x, y, z)</em> vector. + * + * To rotate a vector, multiply the vector by the created matrix + * using \ref rsMatrixMultiply. + * + * See http://en.wikipedia.org/wiki/Rotation_matrix . + * + * @param m The matrix to set. + * @param rot How much rotation to do, in degrees. + * @param x The x component of the vector that is the axis of rotation. + * @param y The y component of the vector that is the axis of rotation. + * @param z The z component of the vector that is the axis of rotation. */ extern void __attribute__((overloadable)) rsMatrixLoadRotate(rs_matrix4x4 *m, float rot, float x, float y, float z); @@ -136,10 +194,16 @@ rsMatrixLoadRotate(rs_matrix4x4 *m, float rot, float x, float y, float z); /** * Load a scale matrix. * - * @param m - * @param x - * @param y - * @param z + * This function creates a scaling matrix, where each component of a + * vector is multiplied by a number. This number can be negative. + * + * To scale a vector, multiply the vector by the created matrix + * using \ref rsMatrixMultiply. + * + * @param m The matrix to set. + * @param x The multiple to scale the x components by. + * @param y The multiple to scale the y components by. + * @param z The multiple to scale the z components by. */ extern void __attribute__((overloadable)) rsMatrixLoadScale(rs_matrix4x4 *m, float x, float y, float z); @@ -147,20 +211,38 @@ rsMatrixLoadScale(rs_matrix4x4 *m, float x, float y, float z); /** * Load a translation matrix. * - * @param m - * @param x - * @param y - * @param z + * This function creates a translation matrix, where a + * number is added to each element of a vector. + * + * To translate a vector, multiply the vector by the created matrix + * using \ref rsMatrixMultiply. + * + * @param m The matrix to set. + * @param x The number to add to each x component. + * @param y The number to add to each y component. + * @param z The number to add to each z component. */ extern void __attribute__((overloadable)) rsMatrixLoadTranslate(rs_matrix4x4 *m, float x, float y, float z); /** - * Multiply two matrix (lhs, rhs) and place the result in m. + * Multiply two matrices. + * + * Sets \e m to the matrix product of <em>lhs * rhs</em>. * - * @param m - * @param lhs - * @param rhs + * To combine two 4x4 transformaton matrices, multiply the second transformation matrix + * by the first transformation matrix. E.g. to create a transformation matrix that applies + * the transformation \e s1 followed by \e s2, call + * </c>rsMatrixLoadMultiply(&combined, &s2, &s1)</c>. + * + * \warning Prior to version 21, storing the result back into right matrix is not supported and + * will result in undefined behavior. Use rsMatrixMulitply instead. E.g. instead of doing + * rsMatrixLoadMultiply (&m2r, &m2r, &m2l), use rsMatrixMultiply (&m2r, &m2l). + * rsMatrixLoadMultiply (&m2l, &m2r, &m2l) works as expected. + * + * @param m The matrix to set. + * @param lhs The left matrix of the product. + * @param rhs The right matrix of the product. */ extern void __attribute__((overloadable)) rsMatrixLoadMultiply(rs_matrix4x4 *m, const rs_matrix4x4 *lhs, const rs_matrix4x4 *rhs); @@ -176,10 +258,16 @@ extern void __attribute__((overloadable)) rsMatrixLoadMultiply(rs_matrix2x2 *m, const rs_matrix2x2 *lhs, const rs_matrix2x2 *rhs); /** - * Multiply the matrix m by rhs and place the result back into m. + * Multiply a matrix into another one. + * + * Sets \e m to the matrix product <em>m * rhs</em>. * - * @param m (lhs) - * @param rhs + * When combining two 4x4 transformation matrices using this function, the resulting + * matrix will correspond to performing the \e rhs transformation first followed by + * the original \e m transformation. + * + * @param m The left matrix of the product and the matrix to be set. + * @param rhs The right matrix of the product. */ extern void __attribute__((overloadable)) rsMatrixMultiply(rs_matrix4x4 *m, const rs_matrix4x4 *rhs); @@ -195,43 +283,73 @@ extern void __attribute__((overloadable)) rsMatrixMultiply(rs_matrix2x2 *m, const rs_matrix2x2 *rhs); /** - * Multiple matrix m with a rotation matrix + * Multiply the matrix \e m with a rotation matrix. + * + * This function modifies a transformation matrix to first do a rotation. + * The axis of rotation is the <em>(x, y, z)</em> vector. * - * @param m - * @param rot - * @param x - * @param y - * @param z + * To apply this combined transformation to a vector, multiply + * the vector by the created matrix using \ref rsMatrixMultiply. + * + * @param m The matrix to modify. + * @param rot How much rotation to do, in degrees. + * @param x The x component of the vector that is the axis of rotation. + * @param y The y component of the vector that is the axis of rotation. + * @param z The z component of the vector that is the axis of rotation. */ extern void __attribute__((overloadable)) rsMatrixRotate(rs_matrix4x4 *m, float rot, float x, float y, float z); /** - * Multiple matrix m with a scale matrix + * Multiply the matrix \e m with a scaling matrix. + * + * This function modifies a transformation matrix to first do a scaling. + * When scaling, each component of a vector is multiplied by a number. + * This number can be negative. * - * @param m - * @param x - * @param y - * @param z + * To apply this combined transformation to a vector, multiply + * the vector by the created matrix using \ref rsMatrixMultiply. + * + * @param m The matrix to modify. + * @param x The multiple to scale the x components by. + * @param y The multiple to scale the y components by. + * @param z The multiple to scale the z components by. */ extern void __attribute__((overloadable)) rsMatrixScale(rs_matrix4x4 *m, float x, float y, float z); /** - * Multiple matrix m with a translation matrix + * Multiply the matrix \e m with a translation matrix. + * + * This function modifies a transformation matrix to first + * do a translation. When translating, a number is added + * to each component of a vector. + * + * To apply this combined transformation to a vector, multiply + * the vector by the created matrix using \ref rsMatrixMultiply. * - * @param m - * @param x - * @param y - * @param z + * @param m The matrix to modify. + * @param x The number to add to each x component. + * @param y The number to add to each y component. + * @param z The number to add to each z component. */ extern void __attribute__((overloadable)) rsMatrixTranslate(rs_matrix4x4 *m, float x, float y, float z); /** - * Load an Ortho projection matrix constructed from the 6 planes + * Load an orthographic projection matrix. * - * @param m + * Constructs an orthographic projection matrix, transforming the box + * identified by the six clipping planes <em>left, right, bottom, top, + * near, far</em> into a unit cube with a corner at + * <em>(-1, -1, -1)</em> and the opposite at <em>(1, 1, 1)</em>. + * + * To apply this projection to a vector, multiply the vector by the + * created matrix using \ref rsMatrixMultiply. + * + * See https://en.wikipedia.org/wiki/Orthographic_projection . + * + * @param m The matrix to set. * @param left * @param right * @param bottom @@ -243,9 +361,16 @@ extern void __attribute__((overloadable)) rsMatrixLoadOrtho(rs_matrix4x4 *m, float left, float right, float bottom, float top, float near, float far); /** - * Load an Frustum projection matrix constructed from the 6 planes + * Load a frustum projection matrix. + * + * Constructs a frustum projection matrix, transforming the box + * identified by the six clipping planes <em>left, right, bottom, top, + * near, far</em>. * - * @param m + * To apply this projection to a vector, multiply the vector by the + * created matrix using \ref rsMatrixMultiply. + * + * @param m The matrix to set. * @param left * @param right * @param bottom @@ -257,21 +382,36 @@ extern void __attribute__((overloadable)) rsMatrixLoadFrustum(rs_matrix4x4 *m, float left, float right, float bottom, float top, float near, float far); /** - * Load an perspective projection matrix constructed from the 6 planes + * Load a perspective projection matrix. + * + * Constructs a perspective projection matrix, assuming a symmetrical field of view. + * + * To apply this projection to a vector, multiply the vector by the + * created matrix using \ref rsMatrixMultiply. * - * @param m + * @param m The matrix to set. * @param fovy Field of view, in degrees along the Y axis. * @param aspect Ratio of x / y. - * @param near - * @param far + * @param near The near clipping plane. + * @param far The far clipping plane. */ extern void __attribute__((overloadable)) rsMatrixLoadPerspective(rs_matrix4x4* m, float fovy, float aspect, float near, float far); #if !defined(RS_VERSION) || (RS_VERSION < 14) /** - * Multiply a vector by a matrix and return the result vector. - * API version 10-13 + * Multiply a vector by a matrix. + * + * Returns the post-multiplication of the vector by the matrix, ie. <em>m * in</em>. + * + * When multiplying a \e float3 to a \e rs_matrix4x4, the vector is expanded with (1). + * + * When multiplying a \e float2 to a \e rs_matrix4x4, the vector is expanded with (0, 1). + * + * When multiplying a \e float2 to a \e rs_matrix3x3, the vector is expanded with (0). + * + * This function is available in API version 10-13. Starting with API 14, + * the function takes a const matrix as the first argument. */ _RS_RUNTIME float4 __attribute__((overloadable)) rsMatrixMultiply(rs_matrix4x4 *m, float4 in); @@ -307,8 +447,17 @@ _RS_RUNTIME float2 __attribute__((overloadable)) rsMatrixMultiply(rs_matrix2x2 *m, float2 in); #else /** - * Multiply a vector by a matrix and return the result vector. - * API version 14+ + * Multiply a vector by a matrix. + * + * Returns the post-multiplication of the vector of the matrix, i.e. <em>m * in</em>. + * + * When multiplying a \e float3 to a \e rs_matrix4x4, the vector is expanded with (1). + * + * When multiplying a \e float2 to a \e rs_matrix4x4, the vector is expanded with (0, 1). + * + * When multiplying a \e float2 to a \e rs_matrix3x3, the vector is expanded with (0). + * + * This function is available starting with API version 14. */ _RS_RUNTIME float4 __attribute__((overloadable)) rsMatrixMultiply(const rs_matrix4x4 *m, float4 in); @@ -346,23 +495,28 @@ rsMatrixMultiply(const rs_matrix2x2 *m, float2 in); /** - * Returns true if the matrix was successfully inversed + * Inverts a matrix in place. + * + * Returns true if the matrix was successfully inverted. * - * @param m + * @param m The matrix to invert. */ extern bool __attribute__((overloadable)) rsMatrixInverse(rs_matrix4x4 *m); /** - * Returns true if the matrix was successfully inversed and transposed. + * Inverts and transpose a matrix in place. + * + * The matrix is first inverted then transposed. + * Returns true if the matrix was successfully inverted. * - * @param m + * @param m The matrix to modify. */ extern bool __attribute__((overloadable)) rsMatrixInverseTranspose(rs_matrix4x4 *m); /** - * Transpose the matrix m. + * Transpose the matrix m in place. * - * @param m + * @param m The matrix to transpose. */ extern void __attribute__((overloadable)) rsMatrixTranspose(rs_matrix4x4 *m); /** |