Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Minor fixes to android.opengl.Matrix

Browse Source 
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
This commit is contained in:
Andy McFadden
2013-06-21 14:43:19 -07:00
parent e36b93575f
commit 043d13ad4b
2 changed files with 69 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
api/current.txt
View File

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

108
opengl/java/android/opengl/Matrix.java
View File

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