Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 043d13ad authored by Andy McFadden's avatar Andy McFadden
Browse files

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
parent e36b9357

api/current.txt

+1 −1
Original line number Diff line number Diff line
@@ -16895,7 +16895,7 @@ package android.opengl { 
  }















  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);

























opengl/java/android/opengl/Matrix.java



+68
−40






























Original line number
Diff line number
Diff line








@@ -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,8 +308,9 @@ 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















     * @param left










@@ -358,8 +366,9 @@ 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










@@ -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