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

1 files changed, 68 insertions, 40 deletions

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.
- *
+ * <p>
  * Matrices are 4 x 4 column-vector matrices stored in column-major
  * order:
  * <pre>
  *  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]
- * </pre>
+ *  m[offset +  3] m[offset +  7] m[offset + 11] m[offset + 15]</pre>
  *
- * Vectors are 4 row x 1 column column-vectors stored in order:
+ * Vectors are 4 x 1 column vectors stored in order:
  * <pre>
  * v[offset + 0]
  * v[offset + 1]
  * v[offset + 2]
- * v[offset + 3]
- * </pre>
- *
+ * v[offset + 3]</pre>
  */
 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.
-     *
+     * <p>
      * 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
+     * <p>
      * 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.
+     * <p>
+     * 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.
+     * <p>
+     * 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.
+     * <p>
+     * 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.
+     * <p>
+     * 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).
+     * <p>
+     * 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).
+     * <p>
+     * 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