From ec0d3353b16741c69681577eb43ccfea435eb4ba Mon Sep 17 00:00:00 2001 From: Alex Sakhartchouk Date: Mon, 17 Jan 2011 15:23:22 -0800 Subject: More docs Change-Id: I3dfea7d83bf8525efda59cef6fafa854b5aa9fe3 --- graphics/java/android/renderscript/FileA3D.java | 30 ++++- graphics/java/android/renderscript/Matrix2f.java | 78 +++++++++++ graphics/java/android/renderscript/Matrix3f.java | 131 ++++++++++++++++++ graphics/java/android/renderscript/Matrix4f.java | 163 ++++++++++++++++++++++- graphics/java/android/renderscript/Mesh.java | 21 +++ 5 files changed, 414 insertions(+), 9 deletions(-) (limited to 'graphics/java') diff --git a/graphics/java/android/renderscript/FileA3D.java b/graphics/java/android/renderscript/FileA3D.java index fe3971a..79ee997 100644 --- a/graphics/java/android/renderscript/FileA3D.java +++ b/graphics/java/android/renderscript/FileA3D.java @@ -46,7 +46,13 @@ public class FileA3D extends BaseObj { **/ public enum EntryType { + /** + * Unknown or or invalid object, nothing will be loaded + **/ UNKNOWN (0), + /** + * Renderscript Mesh object + **/ MESH (1); int mID; @@ -74,14 +80,20 @@ public class FileA3D extends BaseObj { BaseObj mLoadedObj; /** + * Returns the name of a renderscript object the index entry + * describes + * * @return name of a renderscript object the index entry - * describes + * describes + * */ public String getName() { return mName; } /** + * Returns the type of a renderscript object the index entry + * describes * @return type of a renderscript object the index entry * describes */ @@ -90,7 +102,8 @@ public class FileA3D extends BaseObj { } /** - * @return renderscript object described by the entry + * Used to load the object described by the index entry + * @return base renderscript object described by the entry */ public BaseObj getObject() { mRS.validate(); @@ -99,6 +112,9 @@ public class FileA3D extends BaseObj { } /** + * Used to load the mesh described by the index entry, object + * described by the index entry must be a renderscript mesh + * * @return renderscript mesh object described by the entry */ public Mesh getMesh() { @@ -166,7 +182,9 @@ public class FileA3D extends BaseObj { } /** - * @return the numberof objects stored inside a FileA3D + * Returns the number of objects stored inside the a3d file + * + * @return the number of objects stored inside the a3d file */ public int getIndexEntryCount() { if(mFileEntries == null) { @@ -180,6 +198,8 @@ public class FileA3D extends BaseObj { * FileA3D * * @param index number of the entry from the list to return + * + * @return entry in the a3d file described by the index */ public IndexEntry getIndexEntry(int index) { if(getIndexEntryCount() == 0 || index < 0 || index >= mFileEntries.length) { @@ -195,6 +215,7 @@ public class FileA3D extends BaseObj { * @param mgr asset manager used to load asset * @param path location of the file to load * + * @return a3d file containing renderscript objects */ static public FileA3D createFromAsset(RenderScript rs, AssetManager mgr, String path) { rs.validate(); @@ -214,6 +235,7 @@ public class FileA3D extends BaseObj { * @param rs Context to which the object will belong. * @param path location of the file to load * + * @return a3d file containing renderscript objects */ static public FileA3D createFromFile(RenderScript rs, String path) { int fileId = rs.nFileA3DCreateFromFile(path); @@ -232,6 +254,7 @@ public class FileA3D extends BaseObj { * @param rs Context to which the object will belong. * @param path location of the file to load * + * @return a3d file containing renderscript objects */ static public FileA3D createFromFile(RenderScript rs, File path) { return createFromFile(rs, path.getAbsolutePath()); @@ -244,6 +267,7 @@ public class FileA3D extends BaseObj { * @param res resource manager used for loading * @param id resource to create FileA3D from * + * @return a3d file containing renderscript objects */ static public FileA3D createFromResource(RenderScript rs, Resources res, int id) { diff --git a/graphics/java/android/renderscript/Matrix2f.java b/graphics/java/android/renderscript/Matrix2f.java index 2fffe8c..c9a0ea8 100644 --- a/graphics/java/android/renderscript/Matrix2f.java +++ b/graphics/java/android/renderscript/Matrix2f.java @@ -26,28 +26,61 @@ import android.util.Log; **/ public class Matrix2f { + /** + * Creates a new identity 2x2 matrix + */ public Matrix2f() { mMat = new float[4]; loadIdentity(); } + /** + * Creates a new matrix and sets its values from the given + * parameter + * + * @param dataArray values to set the matrix to, must be 4 + * floats long + */ public Matrix2f(float[] dataArray) { mMat = new float[2]; System.arraycopy(dataArray, 0, mMat, 0, mMat.length); } + /** + * Return a reference to the internal array representing matrix + * values. Modifying this array will also change the matrix + * + * @return internal array representing the matrix + */ public float[] getArray() { return mMat; } + /** + * Returns the value for a given row and column + * + * @param i row of the value to return + * @param j column of the value to return + * + * @return value in the ith row and jth column + */ public float get(int i, int j) { return mMat[i*2 + j]; } + /** + * Sets the value for a given row and column + * + * @param i row of the value to set + * @param j column of the value to set + */ public void set(int i, int j, float v) { mMat[i*2 + j] = v; } + /** + * Sets the matrix values to identity + */ public void loadIdentity() { mMat[0] = 1; mMat[1] = 0; @@ -56,10 +89,20 @@ public class Matrix2f { mMat[3] = 1; } + /** + * Sets the values of the matrix to those of the parameter + * + * @param src matrix to load the values from + */ public void load(Matrix2f src) { System.arraycopy(src.getArray(), 0, mMat, 0, mMat.length); } + /** + * Sets current values to be a rotation matrix of given angle + * + * @param rot rotation angle + */ public void loadRotate(float rot) { float c, s; rot *= (float)(java.lang.Math.PI / 180.0f); @@ -71,11 +114,25 @@ public class Matrix2f { mMat[3] = c; } + /** + * Sets current values to be a scale matrix of given dimensions + * + * @param x scale component x + * @param y scale component y + */ public void loadScale(float x, float y) { loadIdentity(); mMat[0] = x; mMat[3] = y; } + + /** + * Sets current values to be the result of multiplying two given + * matrices + * + * @param lhs left hand side matrix + * @param rhs right hand side matrix + */ public void loadMultiply(Matrix2f lhs, Matrix2f rhs) { for (int i=0 ; i<2 ; i++) { float ri0 = 0; @@ -90,21 +147,42 @@ public class Matrix2f { } } + /** + * Post-multiplies the current matrix by a given parameter + * + * @param rhs right hand side to multiply by + */ public void multiply(Matrix2f rhs) { Matrix2f tmp = new Matrix2f(); tmp.loadMultiply(this, rhs); load(tmp); } + /** + * Modifies the current matrix by post-multiplying it with a + * rotation matrix of given angle + * + * @param rot angle of rotation + */ public void rotate(float rot) { Matrix2f tmp = new Matrix2f(); tmp.loadRotate(rot); multiply(tmp); } + /** + * Modifies the current matrix by post-multiplying it with a + * scale matrix of given dimensions + * + * @param x scale component x + * @param y scale component y + */ public void scale(float x, float y) { Matrix2f tmp = new Matrix2f(); tmp.loadScale(x, y); multiply(tmp); } + /** + * Sets the current matrix to its transpose + */ public void transpose() { float temp = mMat[1]; mMat[1] = mMat[2]; diff --git a/graphics/java/android/renderscript/Matrix3f.java b/graphics/java/android/renderscript/Matrix3f.java index e4c5e00..2ec8c62 100644 --- a/graphics/java/android/renderscript/Matrix3f.java +++ b/graphics/java/android/renderscript/Matrix3f.java @@ -26,28 +26,61 @@ import android.util.Log; **/ public class Matrix3f { + /** + * Creates a new identity 3x3 matrix + */ public Matrix3f() { mMat = new float[9]; loadIdentity(); } + /** + * Creates a new matrix and sets its values from the given + * parameter + * + * @param dataArray values to set the matrix to, must be 9 + * floats long + */ public Matrix3f(float[] dataArray) { mMat = new float[9]; System.arraycopy(dataArray, 0, mMat, 0, mMat.length); } + /** + * Return a reference to the internal array representing matrix + * values. Modifying this array will also change the matrix + * + * @return internal array representing the matrix + */ public float[] getArray() { return mMat; } + /** + * Returns the value for a given row and column + * + * @param i row of the value to return + * @param j column of the value to return + * + * @return value in the ith row and jth column + */ public float get(int i, int j) { return mMat[i*3 + j]; } + /** + * Sets the value for a given row and column + * + * @param i row of the value to set + * @param j column of the value to set + */ public void set(int i, int j, float v) { mMat[i*3 + j] = v; } + /** + * Sets the matrix values to identity + */ public void loadIdentity() { mMat[0] = 1; mMat[1] = 0; @@ -62,10 +95,24 @@ public class Matrix3f { mMat[8] = 1; } + /** + * Sets the values of the matrix to those of the parameter + * + * @param src matrix to load the values from + */ public void load(Matrix3f src) { System.arraycopy(src.getArray(), 0, mMat, 0, mMat.length); } + /** + * Sets current values to be a rotation matrix of certain angle + * about a given axis + * + * @param rot angle of rotation + * @param x rotation axis x + * @param y rotation axis y + * @param z rotation axis z + */ public void loadRotate(float rot, float x, float y, float z) { float c, s; rot *= (float)(java.lang.Math.PI / 180.0f); @@ -97,7 +144,13 @@ public class Matrix3f { mMat[8] = z*z*nc + c; } + /** + * Makes the upper 2x2 a rotation matrix of the given angle + * + * @param rot rotation angle + */ public void loadRotate(float rot) { + loadIdentity(); float c, s; rot *= (float)(java.lang.Math.PI / 180.0f); c = (float)java.lang.Math.cos(rot); @@ -108,12 +161,25 @@ public class Matrix3f { mMat[4] = c; } + /** + * Makes the upper 2x2 a scale matrix of given dimensions + * + * @param x scale component x + * @param y scale component y + */ public void loadScale(float x, float y) { loadIdentity(); mMat[0] = x; mMat[4] = y; } + /** + * Sets current values to be a scale matrix of given dimensions + * + * @param x scale component x + * @param y scale component y + * @param z scale component z + */ public void loadScale(float x, float y, float z) { loadIdentity(); mMat[0] = x; @@ -121,12 +187,26 @@ public class Matrix3f { mMat[8] = z; } + /** + * Sets current values to be a translation matrix of given + * dimensions + * + * @param x translation component x + * @param y translation component y + */ public void loadTranslate(float x, float y) { loadIdentity(); mMat[6] = x; mMat[7] = y; } + /** + * Sets current values to be the result of multiplying two given + * matrices + * + * @param lhs left hand side matrix + * @param rhs right hand side matrix + */ public void loadMultiply(Matrix3f lhs, Matrix3f rhs) { for (int i=0 ; i<3 ; i++) { float ri0 = 0; @@ -144,36 +224,87 @@ public class Matrix3f { } } + /** + * Post-multiplies the current matrix by a given parameter + * + * @param rhs right hand side to multiply by + */ public void multiply(Matrix3f rhs) { Matrix3f tmp = new Matrix3f(); tmp.loadMultiply(this, rhs); load(tmp); } + + /** + * Modifies the current matrix by post-multiplying it with a + * rotation matrix of certain angle about a given axis + * + * @param rot angle of rotation + * @param x rotation axis x + * @param y rotation axis y + * @param z rotation axis z + */ public void rotate(float rot, float x, float y, float z) { Matrix3f tmp = new Matrix3f(); tmp.loadRotate(rot, x, y, z); multiply(tmp); } + + /** + * Modifies the upper 2x2 of the current matrix by + * post-multiplying it with a rotation matrix of given angle + * + * @param rot angle of rotation + */ public void rotate(float rot) { Matrix3f tmp = new Matrix3f(); tmp.loadRotate(rot); multiply(tmp); } + + /** + * Modifies the upper 2x2 of the current matrix by + * post-multiplying it with a scale matrix of given dimensions + * + * @param x scale component x + * @param y scale component y + */ public void scale(float x, float y) { Matrix3f tmp = new Matrix3f(); tmp.loadScale(x, y); multiply(tmp); } + + /** + * Modifies the current matrix by post-multiplying it with a + * scale matrix of given dimensions + * + * @param x scale component x + * @param y scale component y + * @param z scale component z + */ public void scale(float x, float y, float z) { Matrix3f tmp = new Matrix3f(); tmp.loadScale(x, y, z); multiply(tmp); } + + /** + * Modifies the current matrix by post-multiplying it with a + * translation matrix of given dimensions + * + * @param x translation component x + * @param y translation component y + */ public void translate(float x, float y) { Matrix3f tmp = new Matrix3f(); tmp.loadTranslate(x, y); multiply(tmp); } + + /** + * Sets the current matrix to its transpose + */ public void transpose() { for(int i = 0; i < 2; ++i) { for(int j = i + 1; j < 3; ++j) { diff --git a/graphics/java/android/renderscript/Matrix4f.java b/graphics/java/android/renderscript/Matrix4f.java index ec07cd5..2afd72e 100644 --- a/graphics/java/android/renderscript/Matrix4f.java +++ b/graphics/java/android/renderscript/Matrix4f.java @@ -26,28 +26,61 @@ import android.util.Log; **/ public class Matrix4f { + /** + * Creates a new identity 4x4 matrix + */ public Matrix4f() { mMat = new float[16]; loadIdentity(); } + /** + * Creates a new matrix and sets its values from the given + * parameter + * + * @param dataArray values to set the matrix to, must be 16 + * floats long + */ public Matrix4f(float[] dataArray) { mMat = new float[16]; System.arraycopy(dataArray, 0, mMat, 0, mMat.length); } + /** + * Return a reference to the internal array representing matrix + * values. Modifying this array will also change the matrix + * + * @return internal array representing the matrix + */ public float[] getArray() { return mMat; } + /** + * Returns the value for a given row and column + * + * @param i row of the value to return + * @param j column of the value to return + * + * @return value in the ith row and jth column + */ public float get(int i, int j) { return mMat[i*4 + j]; } + /** + * Sets the value for a given row and column + * + * @param i row of the value to set + * @param j column of the value to set + */ public void set(int i, int j, float v) { mMat[i*4 + j] = v; } + /** + * Sets the matrix values to identity + */ public void loadIdentity() { mMat[0] = 1; mMat[1] = 0; @@ -70,10 +103,24 @@ public class Matrix4f { mMat[15] = 1; } + /** + * Sets the values of the matrix to those of the parameter + * + * @param src matrix to load the values from + */ public void load(Matrix4f src) { System.arraycopy(src.getArray(), 0, mMat, 0, mMat.length); } + /** + * Sets current values to be a rotation matrix of certain angle + * about a given axis + * + * @param rot angle of rotation + * @param x rotation axis x + * @param y rotation axis y + * @param z rotation axis z + */ public void loadRotate(float rot, float x, float y, float z) { float c, s; mMat[3] = 0; @@ -112,6 +159,13 @@ public class Matrix4f { mMat[10] = z*z*nc + c; } + /** + * Sets current values to be a scale matrix of given dimensions + * + * @param x scale component x + * @param y scale component y + * @param z scale component z + */ public void loadScale(float x, float y, float z) { loadIdentity(); mMat[0] = x; @@ -119,6 +173,14 @@ public class Matrix4f { mMat[10] = z; } + /** + * Sets current values to be a translation matrix of given + * dimensions + * + * @param x translation component x + * @param y translation component y + * @param z translation component z + */ public void loadTranslate(float x, float y, float z) { loadIdentity(); mMat[12] = x; @@ -126,6 +188,13 @@ public class Matrix4f { mMat[14] = z; } + /** + * Sets current values to be the result of multiplying two given + * matrices + * + * @param lhs left hand side matrix + * @param rhs right hand side matrix + */ public void loadMultiply(Matrix4f lhs, Matrix4f rhs) { for (int i=0 ; i<4 ; i++) { float ri0 = 0; @@ -146,6 +215,16 @@ public class Matrix4f { } } + /** + * Set current values to be an orthographic projection matrix + * + * @param l location of the left vertical clipping plane + * @param r location of the right vertical clipping plane + * @param b location of the bottom horizontal clipping plane + * @param t location of the top horizontal clipping plane + * @param n location of the near clipping plane + * @param f location of the far clipping plane + */ public void loadOrtho(float l, float r, float b, float t, float n, float f) { loadIdentity(); mMat[0] = 2 / (r - l); @@ -156,10 +235,31 @@ public class Matrix4f { mMat[14]= -(f + n) / (f - n); } + /** + * Set current values to be an orthographic projection matrix + * with the right and bottom clipping planes set to the given + * values. Left and top clipping planes are set to 0. Near and + * far are set to -1, 1 respectively + * + * @param w location of the right vertical clipping plane + * @param h location of the bottom horizontal clipping plane + * + */ public void loadOrthoWindow(int w, int h) { loadOrtho(0,w, h,0, -1,1); } + /** + * Sets current values to be a perspective projection matrix + * + * @param l location of the left vertical clipping plane + * @param r location of the right vertical clipping plane + * @param b location of the bottom horizontal clipping plane + * @param t location of the top horizontal clipping plane + * @param n location of the near clipping plane, must be positive + * @param f location of the far clipping plane, must be positive + * + */ public void loadFrustum(float l, float r, float b, float t, float n, float f) { loadIdentity(); mMat[0] = 2 * n / (r - l); @@ -172,6 +272,14 @@ public class Matrix4f { mMat[15]= 0; } + /** + * Sets current values to be a perspective projection matrix + * + * @param fovy vertical field of view angle in degrees + * @param aspect aspect ratio of the screen + * @param near near cliping plane, must be positive + * @param far far clipping plane, must be positive + */ public void loadPerspective(float fovy, float aspect, float near, float far) { float top = near * (float)Math.tan((float) (fovy * Math.PI / 360.0f)); float bottom = -top; @@ -180,6 +288,14 @@ public class Matrix4f { loadFrustum(left, right, bottom, top, near, far); } + /** + * Helper function to set the current values to a perspective + * projection matrix with aspect ratio defined by the parameters + * and (near, far), (bottom, top) mapping to (-1, 1) at z = 0 + * + * @param w screen width + * @param h screen height + */ public void loadProjectionNormalized(int w, int h) { // range -1,1 in the narrow axis at z = 0. Matrix4f m1 = new Matrix4f(); @@ -205,22 +321,53 @@ public class Matrix4f { load(m1); } - + /** + * Post-multiplies the current matrix by a given parameter + * + * @param rhs right hand side to multiply by + */ public void multiply(Matrix4f rhs) { Matrix4f tmp = new Matrix4f(); tmp.loadMultiply(this, rhs); load(tmp); } + /** + * Modifies the current matrix by post-multiplying it with a + * rotation matrix of certain angle about a given axis + * + * @param rot angle of rotation + * @param x rotation axis x + * @param y rotation axis y + * @param z rotation axis z + */ public void rotate(float rot, float x, float y, float z) { Matrix4f tmp = new Matrix4f(); tmp.loadRotate(rot, x, y, z); multiply(tmp); } + + /** + * Modifies the current matrix by post-multiplying it with a + * scale matrix of given dimensions + * + * @param x scale component x + * @param y scale component y + * @param z scale component z + */ public void scale(float x, float y, float z) { Matrix4f tmp = new Matrix4f(); tmp.loadScale(x, y, z); multiply(tmp); } + + /** + * Modifies the current matrix by post-multiplying it with a + * translation matrix of given dimensions + * + * @param x translation component x + * @param y translation component y + * @param z translation component z + */ public void translate(float x, float y, float z) { Matrix4f tmp = new Matrix4f(); tmp.loadTranslate(x, y, z); @@ -245,6 +392,9 @@ public class Matrix4f { return cofactor; } + /** + * Sets the current matrix to its inverse + */ public boolean inverse() { Matrix4f result = new Matrix4f(); @@ -271,6 +421,9 @@ public class Matrix4f { return true; } + /** + * Sets the current matrix to its inverse transpose + */ public boolean inverseTranspose() { Matrix4f result = new Matrix4f(); @@ -296,6 +449,9 @@ public class Matrix4f { return true; } + /** + * Sets the current matrix to its transpose + */ public void transpose() { for(int i = 0; i < 3; ++i) { for(int j = i + 1; j < 4; ++j) { @@ -308,8 +464,3 @@ public class Matrix4f { final float[] mMat; } - - - - - diff --git a/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java index fcf8178..43e0496 100644 --- a/graphics/java/android/renderscript/Mesh.java +++ b/graphics/java/android/renderscript/Mesh.java @@ -46,11 +46,32 @@ public class Mesh extends BaseObj { * **/ public enum Primitive { + /** + * Vertex data will be rendered as a series of points + */ POINT (0), + /** + * Vertex pairs will be rendered as lines + */ LINE (1), + /** + * Vertex data will be rendered as a connected line strip + */ LINE_STRIP (2), + /** + * Vertices will be rendered as individual triangles + */ TRIANGLE (3), + /** + * Vertices will be rendered as a connected triangle strip + * defined by the first three vertices with each additional + * triangle defined by a new vertex + */ TRIANGLE_STRIP (4), + /** + * Vertices will be rendered as a sequence of triangles that all + * share first vertex as the origin + */ TRIANGLE_FAN (5); int mID; -- cgit v1.1