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
diff --git a/api/current.txt b/api/current.txt
index a896ecb..0f93390 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -16895,7 +16895,7 @@
}
public class Matrix {
- ctor public Matrix();
+ ctor public deprecated Matrix();
method public static void frustumM(float[], int, float, float, float, float, float, float);
method public static boolean invertM(float[], int, float[], int);
method public static float length(float, float, float);
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 @@
/**
* 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 @@
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 @@
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 @@
/**
* 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 @@
/**
* 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 @@
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
/**
* 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 @@
}
/**
- * 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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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