From 043d13ad4b67b57fa8ba1fa35f48ff5bcc0f0141 Mon Sep 17 00:00:00 2001 From: Andy McFadden Date: Fri, 21 Jun 2013 14:43:19 -0700 Subject: Minor fixes to android.opengl.Matrix This has a minor API change: deprecation of the nullary constructor. The class is entirely composed of static methods, and was written without a constructor, but the compiler dutifully generated a default implementation and the API tool slurped it up. The other changes are to the documentation: - Added warnings about the use of overlapping input and output on certain methods. - Fixed a few inaccuracies (e.g. transposeM() returns a transposed matrix, not an inverted matrix). - Tidied up the formatting. - Generally placated the consistency hobgoblins. Bug 8868762 Change-Id: Ie3f86b98c477d8dc82d9dcaa311959bd4d191359 --- opengl/java/android/opengl/Matrix.java | 108 +++++++++++++++++++++------------ 1 file changed, 68 insertions(+), 40 deletions(-) (limited to 'opengl') diff --git a/opengl/java/android/opengl/Matrix.java b/opengl/java/android/opengl/Matrix.java index 72128ac..ce3f57e 100644 --- a/opengl/java/android/opengl/Matrix.java +++ b/opengl/java/android/opengl/Matrix.java @@ -19,24 +19,21 @@ package android.opengl; /** * Matrix math utilities. These methods operate on OpenGL ES format * matrices and vectors stored in float arrays. - * + *

* Matrices are 4 x 4 column-vector matrices stored in column-major * order: * 

  *  m[offset +  0] m[offset +  4] m[offset +  8] m[offset + 12]
  *  m[offset +  1] m[offset +  5] m[offset +  9] m[offset + 13]
  *  m[offset +  2] m[offset +  6] m[offset + 10] m[offset + 14]
- *  m[offset +  3] m[offset +  7] m[offset + 11] m[offset + 15]
- *
+ * m[offset + 3] m[offset + 7] m[offset + 11] m[offset + 15] * - * Vectors are 4 row x 1 column column-vectors stored in order: + * Vectors are 4 x 1 column vectors stored in order: * 
  * v[offset + 0]
  * v[offset + 1]
  * v[offset + 2]
- * v[offset + 3]
- *
- * + * v[offset + 3] */ public class Matrix { @@ -44,12 +41,18 @@ public class Matrix { private final static float[] sTemp = new float[32]; /** - * Multiply two 4x4 matrices together and store the result in a third 4x4 + * @deprecated All methods are static, do not instantiate this class. + */ + @Deprecated + public Matrix() {} + + /** + * Multiplies two 4x4 matrices together and stores the result in a third 4x4 * matrix. In matrix notation: result = lhs x rhs. Due to the way * matrix multiplication works, the result matrix will have the same * effect as first multiplying by the rhs matrix, then multiplying by * the lhs matrix. This is the opposite of what you might expect. - * + *

* The same float array may be passed for result, lhs, and/or rhs. However, * the result element values are undefined if the result elements overlap * either the lhs or rhs elements. @@ -70,9 +73,9 @@ public class Matrix { float[] lhs, int lhsOffset, float[] rhs, int rhsOffset); /** - * Multiply a 4 element vector by a 4x4 matrix and store the result in a 4 - * element column vector. In matrix notation: result = lhs x rhs - * + * Multiplies a 4 element vector by a 4x4 matrix and stores the result in a + * 4-element column vector. In matrix notation: result = lhs x rhs + *

* The same float array may be passed for resultVec, lhsMat, and/or rhsVec. * However, the resultVec element values are undefined if the resultVec * elements overlap either the lhsMat or rhsVec elements. @@ -97,12 +100,14 @@ public class Matrix { /** * Transposes a 4 x 4 matrix. + *

+ * mTrans and m must not overlap. * - * @param mTrans the array that holds the output inverted matrix - * @param mTransOffset an offset into mInv where the inverted matrix is + * @param mTrans the array that holds the output transposed matrix + * @param mTransOffset an offset into mTrans where the transposed matrix is * stored. * @param m the input array - * @param mOffset an offset into m where the matrix is stored. + * @param mOffset an offset into m where the input matrix is stored. */ public static void transposeM(float[] mTrans, int mTransOffset, float[] m, int mOffset) { @@ -117,12 +122,14 @@ public class Matrix { /** * Inverts a 4 x 4 matrix. + *

+ * mInv and m must not overlap. * * @param mInv the array that holds the output inverted matrix * @param mInvOffset an offset into mInv where the inverted matrix is * stored. * @param m the input array - * @param mOffset an offset into m where the matrix is stored. + * @param mOffset an offset into m where the input matrix is stored. * @return true if the matrix could be inverted, false if it could not. */ public static boolean invertM(float[] mInv, int mInvOffset, float[] m, @@ -301,10 +308,11 @@ public class Matrix { /** - * Define a projection matrix in terms of six clip planes - * @param m the float array that holds the perspective matrix + * Defines a projection matrix in terms of six clip planes. + * + * @param m the float array that holds the output perspective matrix * @param offset the offset into float array m where the perspective - * matrix data is written + * matrix data is written * @param left * @param right * @param bottom @@ -358,11 +366,12 @@ public class Matrix { } /** - * Define a projection matrix in terms of a field of view angle, an - * aspect ratio, and z clip planes + * Defines a projection matrix in terms of a field of view angle, an + * aspect ratio, and z clip planes. + * * @param m the float array that holds the perspective matrix * @param offset the offset into float array m where the perspective - * matrix data is written + * matrix data is written * @param fovy field of view in y direction, in degrees * @param aspect width to height aspect ratio of the viewport * @param zNear @@ -395,7 +404,7 @@ public class Matrix { } /** - * Computes the length of a vector + * Computes the length of a vector. * * @param x x coordinate of a vector * @param y y coordinate of a vector @@ -408,6 +417,7 @@ public class Matrix { /** * Sets matrix m to the identity matrix. + * * @param sm returns the result * @param smOffset index into sm where the result matrix starts */ @@ -421,7 +431,10 @@ public class Matrix { } /** - * Scales matrix m by x, y, and z, putting the result in sm + * Scales matrix m by x, y, and z, putting the result in sm. + *

+ * m and sm must not overlap. + * * @param sm returns the result * @param smOffset index into sm where the result matrix starts * @param m source matrix @@ -444,7 +457,8 @@ public class Matrix { } /** - * Scales matrix m in place by sx, sy, and sz + * Scales matrix m in place by sx, sy, and sz. + * * @param m matrix to scale * @param mOffset index into m where the matrix starts * @param x scale factor x @@ -462,7 +476,10 @@ public class Matrix { } /** - * Translates matrix m by x, y, and z, putting the result in tm + * Translates matrix m by x, y, and z, putting the result in tm. + *

+ * m and tm must not overlap. + * * @param tm returns the result * @param tmOffset index into sm where the result matrix starts * @param m source matrix @@ -487,6 +504,7 @@ public class Matrix { /** * Translates matrix m by x, y, and z in place. + * * @param m matrix * @param mOffset index into m where the matrix starts * @param x translation factor x @@ -503,15 +521,18 @@ public class Matrix { } /** - * Rotates matrix m by angle a (in degrees) around the axis (x, y, z) + * Rotates matrix m by angle a (in degrees) around the axis (x, y, z). + *

+ * m and rm must not overlap. + * * @param rm returns the result * @param rmOffset index into rm where the result matrix starts * @param m source matrix * @param mOffset index into m where the source matrix starts * @param a angle to rotate in degrees - * @param x scale factor x - * @param y scale factor y - * @param z scale factor z + * @param x X axis component + * @param y Y axis component + * @param z Z axis component */ public static void rotateM(float[] rm, int rmOffset, float[] m, int mOffset, @@ -524,13 +545,14 @@ public class Matrix { /** * Rotates matrix m in place by angle a (in degrees) - * around the axis (x, y, z) + * around the axis (x, y, z). + * * @param m source matrix * @param mOffset index into m where the matrix starts * @param a angle to rotate in degrees - * @param x scale factor x - * @param y scale factor y - * @param z scale factor z + * @param x X axis component + * @param y Y axis component + * @param z Z axis component */ public static void rotateM(float[] m, int mOffset, float a, float x, float y, float z) { @@ -542,13 +564,18 @@ public class Matrix { } /** - * Rotates matrix m by angle a (in degrees) around the axis (x, y, z) + * Creates a matrix for rotation by angle a (in degrees) + * around the axis (x, y, z). + *

+ * An optimized path will be used for rotation about a major axis + * (e.g. x=1.0f y=0.0f z=0.0f). + * * @param rm returns the result * @param rmOffset index into rm where the result matrix starts * @param a angle to rotate in degrees - * @param x scale factor x - * @param y scale factor y - * @param z scale factor z + * @param x X axis component + * @param y Y axis component + * @param z Z axis component */ public static void setRotateM(float[] rm, int rmOffset, float a, float x, float y, float z) { @@ -608,7 +635,8 @@ public class Matrix { } /** - * Converts Euler angles to a rotation matrix + * Converts Euler angles to a rotation matrix. + * * @param rm returns the result * @param rmOffset index into rm where the result matrix starts * @param x angle of rotation, in degrees @@ -651,7 +679,7 @@ public class Matrix { } /** - * Define a viewing transformation in terms of an eye point, a center of + * Defines a viewing transformation in terms of an eye point, a center of * view, and an up vector. * * @param rm returns the result -- cgit v1.1