Merge "Adding comments to the renderscript program classes." into honeycomb

6 files changed, 466 insertions, 1 deletions

diff --git a/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java
index 59e3dd9..b77fe7d 100644
--- a/graphics/java/android/renderscript/Mesh.java
+++ b/graphics/java/android/renderscript/Mesh.java
@@ -23,10 +23,29 @@ import android.util.Log;
 
 /**
  * @hide
+ * Mesh class is a container for geometric data displayed in
+ * renderscript.
+ *
+ * Internally, mesh is a collection of allocations that
+ * represent vertex data (positions, normals, texture
+ * coordinates) and index data such as triangles and lines.
+ *
+ * Vertex data could either be interlieved within one
+ * allocation, provided separately as multiple allocation
+ * objects or done as a combination of the above. When a
+ * vertex channel name matches an input in the vertex program,
+ * renderscript will automatically connect the two together.
+ *
+ *  Parts of the mesh could be rendered with either explicit
+ *  index sets or primitive types.
  *
  **/
 public class Mesh extends BaseObj {
 
+    /**
+    * Describes the way mesh vertex data is interpreted when rendering
+    *
+    **/
     public enum Primitive {
         POINT (0),
         LINE (1),
@@ -49,25 +68,50 @@ public class Mesh extends BaseObj {
         super(id, rs);
     }
 
+    /**
+    * @return number of allocations containing vertex data
+    *
+    **/
     public int getVertexAllocationCount() {
         if(mVertexBuffers == null) {
             return 0;
         }
         return mVertexBuffers.length;
     }
+    /**
+    * @param slot index in the list of allocations to return
+    * @return vertex data allocation at the given index
+    *
+    **/
     public Allocation getVertexAllocation(int slot) {
         return mVertexBuffers[slot];
     }
 
+    /**
+    * @return number of primitives or index sets in the mesh
+    *
+    **/
     public int getPrimitiveCount() {
         if(mIndexBuffers == null) {
             return 0;
         }
         return mIndexBuffers.length;
     }
+
+    /**
+    * @param slot locaton within the list of index set allocation
+    * @return allocation containing primtive index data or null if
+    *         the index data is not specified explicitly
+    *
+    **/
     public Allocation getIndexSetAllocation(int slot) {
         return mIndexBuffers[slot];
     }
+    /**
+    * @param slot locaiton within the list of index set primitives
+    * @return index set primitive type
+    *
+    **/
     public Primitive getPrimitive(int slot) {
         return mPrimitives[slot];
     }
@@ -105,6 +149,12 @@ public class Mesh extends BaseObj {
         }
     }
 
+    /**
+    * Mesh builder object. It starts empty and requires the user to
+    * add the types necessary to create vertex and index
+    * allocations
+    *
+    */
     public static class Builder {
         RenderScript mRS;
         int mUsage;
@@ -121,6 +171,13 @@ public class Mesh extends BaseObj {
         Entry[] mVertexTypes;
         Vector mIndexTypes;
 
+        /**
+        * Creates builder object
+        * @param rs
+        * @param usage specifies how the mesh allocations are to be
+        *              handled, whether they need to be uploaded to a
+        *              buffer on the gpu, maintain a cpu copy, etc
+        */
         public Builder(RenderScript rs, int usage) {
             mRS = rs;
             mUsage = usage;
@@ -129,14 +186,29 @@ public class Mesh extends BaseObj {
             mIndexTypes = new Vector();
         }
 
+        /**
+        * @return internal index of the last vertex buffer type added to
+        *         builder
+        **/
         public int getCurrentVertexTypeIndex() {
             return mVertexTypeCount - 1;
         }
 
+        /**
+        * @return internal index of the last index set added to the
+        *         builder
+        **/
         public int getCurrentIndexSetIndex() {
             return mIndexTypes.size() - 1;
         }
 
+        /**
+        * Adds a vertex data type to the builder object
+        *
+        * @param r type of the vertex data allocation to be created
+        *
+        * @return this
+        **/
         public Builder addVertexType(Type t) throws IllegalStateException {
             if (mVertexTypeCount >= mVertexTypes.length) {
                 throw new IllegalStateException("Max vertex types exceeded.");
@@ -149,6 +221,14 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Adds a vertex data type to the builder object
+        *
+        * @param e element describing the vertex data layout
+        * @param size number of elements in the buffer
+        *
+        * @return this
+        **/
         public Builder addVertexType(Element e, int size) throws IllegalStateException {
             if (mVertexTypeCount >= mVertexTypes.length) {
                 throw new IllegalStateException("Max vertex types exceeded.");
@@ -162,6 +242,14 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Adds an index set data type to the builder object
+        *
+        * @param t type of the index set data, could be null
+        * @param p primitive type
+        *
+        * @return this
+        **/
         public Builder addIndexSetType(Type t, Primitive p) {
             Entry indexType = new Entry();
             indexType.t = t;
@@ -172,6 +260,13 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Adds an index set primitive type to the builder object
+        *
+        * @param p primitive type
+        *
+        * @return this
+        **/
         public Builder addIndexSetType(Primitive p) {
             Entry indexType = new Entry();
             indexType.t = null;
@@ -182,6 +277,15 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Adds an index set data type to the builder object
+        *
+        * @param e element describing the index set data layout
+        * @param size number of elements in the buffer
+        * @param p primitive type
+        *
+        * @return this
+        **/
         public Builder addIndexSetType(Element e, int size, Primitive p) {
             Entry indexType = new Entry();
             indexType.t = null;
@@ -237,6 +341,10 @@ public class Mesh extends BaseObj {
             return newMesh;
         }
 
+        /**
+        * Create a Mesh object from the current state of the builder
+        *
+        **/
         public Mesh create() {
             mRS.validate();
             Mesh sm = internalCreate(mRS, this);
@@ -244,6 +352,12 @@ public class Mesh extends BaseObj {
         }
     }
 
+    /**
+    * Mesh builder object. It starts empty and requires the user to
+    * add all the vertex and index allocations that comprise the
+    * mesh
+    *
+    */
     public static class AllocationBuilder {
         RenderScript mRS;
 
@@ -264,14 +378,30 @@ public class Mesh extends BaseObj {
             mIndexTypes = new Vector();
         }
 
+        /**
+        * @return internal index of the last vertex buffer type added to
+        *         builder
+        **/
         public int getCurrentVertexTypeIndex() {
             return mVertexTypeCount - 1;
         }
 
+        /**
+        * @return internal index of the last index set added to the
+        *         builder
+        **/
         public int getCurrentIndexSetIndex() {
             return mIndexTypes.size() - 1;
         }
 
+        /**
+        * Adds an allocation containing vertex buffer data to the
+        * builder
+        *
+        * @param a vertex data allocation
+        *
+        * @return this
+        **/
         public AllocationBuilder addVertexAllocation(Allocation a) throws IllegalStateException {
             if (mVertexTypeCount >= mVertexTypes.length) {
                 throw new IllegalStateException("Max vertex types exceeded.");
@@ -283,6 +413,15 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Adds an allocation containing index buffer data and index type
+        * to the builder
+        *
+        * @param a index set data allocation, could be null
+        * @param p index set primitive type
+        *
+        * @return this
+        **/
         public AllocationBuilder addIndexSetAllocation(Allocation a, Primitive p) {
             Entry indexType = new Entry();
             indexType.a = a;
@@ -291,6 +430,13 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Adds an index set type to the builder
+        *
+        * @param p index set primitive type
+        *
+        * @return this
+        **/
         public AllocationBuilder addIndexSetType(Primitive p) {
             Entry indexType = new Entry();
             indexType.a = null;
@@ -325,6 +471,10 @@ public class Mesh extends BaseObj {
             return newMesh;
         }
 
+        /**
+        * Create a Mesh object from the current state of the builder
+        *
+        **/
         public Mesh create() {
             mRS.validate();
             Mesh sm = internalCreate(mRS, this);
@@ -332,7 +482,11 @@ public class Mesh extends BaseObj {
         }
     }
 
-
+    /**
+    * Builder that allows creation of a mesh object point by point
+    * and triangle by triangle
+    *
+    **/
     public static class TriangleMeshBuilder {
         float mVtxData[];
         int mVtxCount;
@@ -358,6 +512,15 @@ public class Mesh extends BaseObj {
         public static final int NORMAL = 0x0002;
         public static final int TEXTURE_0 = 0x0100;
 
+        /**
+        * @param rs
+        * @param vtxSize specifies whether the vertex is a float2 or
+        *                float3
+        * @param flags bitfield that is a combination of COLOR, NORMAL,
+        *              and TEXTURE_0 that specifies what vertex data
+        *              channels are present in the mesh
+        *
+        **/
         public TriangleMeshBuilder(RenderScript rs, int vtxSize, int flags) {
             mRS = rs;
             mVtxCount = 0;
@@ -401,6 +564,15 @@ public class Mesh extends BaseObj {
             }
         }
 
+        /**
+        * Adds a float2 vertex to the mesh
+        *
+        * @param x position x
+        * @param y position y
+        *
+        * @return this
+        *
+        **/
         public TriangleMeshBuilder addVertex(float x, float y) {
             if (mVtxSize != 2) {
                 throw new IllegalStateException("add mistmatch with declared components.");
@@ -412,6 +584,16 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Adds a float3 vertex to the mesh
+        *
+        * @param x position x
+        * @param y position y
+        * @param z position z
+        *
+        * @return this
+        *
+        **/
         public TriangleMeshBuilder addVertex(float x, float y, float z) {
             if (mVtxSize != 3) {
                 throw new IllegalStateException("add mistmatch with declared components.");
@@ -424,6 +606,14 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Sets the texture coordinate for the last added vertex
+        *
+        * @param s texture coordinate s
+        * @param t texture coordinate t
+        *
+        * @return this
+        **/
         public TriangleMeshBuilder setTexture(float s, float t) {
             if ((mFlags & TEXTURE_0) == 0) {
                 throw new IllegalStateException("add mistmatch with declared components.");
@@ -433,6 +623,15 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Sets the normal vector for the last added vertex
+        *
+        * @param x normal vector x
+        * @param y normal vector y
+        * @param z normal vector z
+        *
+        * @return this
+        **/
         public TriangleMeshBuilder setNormal(float x, float y, float z) {
             if ((mFlags & NORMAL) == 0) {
                 throw new IllegalStateException("add mistmatch with declared components.");
@@ -443,6 +642,16 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Sets the color for the last added vertex
+        *
+        * @param r red component
+        * @param g green component
+        * @param b blue component
+        * @param a alpha component
+        *
+        * @return this
+        **/
         public TriangleMeshBuilder setColor(float r, float g, float b, float a) {
             if ((mFlags & COLOR) == 0) {
                 throw new IllegalStateException("add mistmatch with declared components.");
@@ -454,6 +663,15 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Adds a new triangle to the mesh builder
+        *
+        * @param idx1 index of the first vertex in the triangle
+        * @param idx2 index of the second vertex in the triangle
+        * @param idx3 index of the third vertex in the triangle
+        *
+        * @return this
+        **/
         public TriangleMeshBuilder addTriangle(int idx1, int idx2, int idx3) {
             if((idx1 >= mVtxCount) || (idx1 < 0) ||
                (idx2 >= mVtxCount) || (idx2 < 0) ||
@@ -471,6 +689,20 @@ public class Mesh extends BaseObj {
             return this;
         }
 
+        /**
+        * Creates the mesh object from the current state of the builder
+        *
+        * @param uploadToBufferObject specifies whether the vertex data
+        *                             is to be uploaded into the buffer
+        *                             object indicating that it's likely
+        *                             not going to be modified and
+        *                             rendered many times.
+        *                             Alternatively, it indicates the
+        *                             mesh data will be updated
+        *                             frequently and remain in script
+        *                             accessible memory
+        *
+        **/
         public Mesh create(boolean uploadToBufferObject) {
             Element.Builder b = new Element.Builder(mRS);
             int floatCount = mVtxSize;
diff --git a/graphics/java/android/renderscript/Program.java b/graphics/java/android/renderscript/Program.java
index b07ae7d..fdd138c 100644
--- a/graphics/java/android/renderscript/Program.java
+++ b/graphics/java/android/renderscript/Program.java
@@ -28,6 +28,9 @@ import android.util.Log;
 
 /**
  *
+ * Program is a base class for all the objects that modify
+ * various stages of the graphics pipeline
+ *
  **/
 public class Program extends BaseObj {
     public static final int MAX_INPUT = 8;
@@ -35,6 +38,12 @@ public class Program extends BaseObj {
     public static final int MAX_CONSTANT = 8;
     public static final int MAX_TEXTURE = 8;
 
+    /**
+     *
+     * TextureType specifies what textures are attached to Program
+     * objects
+     *
+     **/
     public enum TextureType {
         TEXTURE_2D (0),
         TEXTURE_CUBE (1);
@@ -68,6 +77,14 @@ public class Program extends BaseObj {
         super(id, rs);
     }
 
+    /**
+     * Binds a constant buffer to be used as uniform inputs to the
+     * program
+     *
+     * @param a allocation containing uniform data
+     * @param slot index within the program's list of constant
+     *             buffer allocations
+     */
     public void bindConstants(Allocation a, int slot) {
         if (slot < 0 || slot >= mConstants.length) {
             throw new IllegalArgumentException("Slot ID out of range.");
@@ -80,6 +97,13 @@ public class Program extends BaseObj {
         mRS.nProgramBindConstants(getID(), slot, id);
     }
 
+    /**
+     * Binds a texture to be used in the program
+     *
+     * @param va allocation containing texture data
+     * @param slot index within the program's list of textures
+     *
+     */
     public void bindTexture(Allocation va, int slot)
         throws IllegalArgumentException {
         mRS.validate();
@@ -95,6 +119,15 @@ public class Program extends BaseObj {
         mRS.nProgramBindTexture(getID(), slot, id);
     }
 
+    /**
+     * Binds an object that describes how a texture at the
+     * corresponding location is sampled
+     *
+     * @param vs sampler for a corresponding texture
+     * @param slot index within the program's list of textures to
+     *             use the sampler on
+     *
+     */
     public void bindSampler(Sampler vs, int slot)
         throws IllegalArgumentException {
         mRS.validate();
@@ -133,11 +166,25 @@ public class Program extends BaseObj {
             mTextureTypes = new TextureType[MAX_TEXTURE];
         }
 
+        /**
+         * Sets the GLSL shader code to be used in the program
+         *
+         * @param s GLSL shader string
+         * @return  self
+         */
         public BaseProgramBuilder setShader(String s) {
             mShader = s;
             return this;
         }
 
+        /**
+         * Sets the GLSL shader code to be used in the program
+         *
+         * @param resources application resources
+         * @param resourceID id of the file containing GLSL shader code
+         *
+         * @return  self
+         */
         public BaseProgramBuilder setShader(Resources resources, int resourceID) {
             byte[] str;
             int strLength;
@@ -176,14 +223,29 @@ public class Program extends BaseObj {
             return this;
         }
 
+        /**
+         * Queries the index of the last added constant buffer type
+         *
+         */
         public int getCurrentConstantIndex() {
             return mConstantCount - 1;
         }
 
+        /**
+         * Queries the index of the last added texture type
+         *
+         */
         public int getCurrentTextureIndex() {
             return mTextureCount - 1;
         }
 
+        /**
+         * Adds constant (uniform) inputs to the program
+         *
+         * @param t Type that describes the layout of the Allocation
+         *          object to be used as constant inputs to the Program
+         * @return  self
+         */
         public BaseProgramBuilder addConstant(Type t) throws IllegalStateException {
             // Should check for consistant and non-conflicting names...
             if(mConstantCount >= MAX_CONSTANT) {
@@ -197,6 +259,13 @@ public class Program extends BaseObj {
             return this;
         }
 
+        /**
+         * Adds a texture input to the Program
+         *
+         * @param texType describes that the texture to append it (2D,
+         *                Cubemap, etc.)
+         * @return  self
+         */
         public BaseProgramBuilder addTexture(TextureType texType) throws IllegalArgumentException {
             if(mTextureCount >= MAX_TEXTURE) {
                 throw new IllegalArgumentException("Max texture count exceeded.");
diff --git a/graphics/java/android/renderscript/ProgramFragment.java b/graphics/java/android/renderscript/ProgramFragment.java
index 7f12661..14c0c01 100644
--- a/graphics/java/android/renderscript/ProgramFragment.java
+++ b/graphics/java/android/renderscript/ProgramFragment.java
@@ -22,6 +22,9 @@ import android.util.Log;
 
 
 /**
+ * ProgramFragment, also know as a fragment shader, describes a
+ * stage in the graphics pipeline responsible for manipulating
+ * pixel data in a user-defined way.
  *
  **/
 public class ProgramFragment extends Program {
@@ -30,10 +33,20 @@ public class ProgramFragment extends Program {
     }
 
     public static class Builder extends BaseProgramBuilder {
+        /**
+         * Create a builder object.
+         *
+         * @param rs
+         */
         public Builder(RenderScript rs) {
             super(rs);
         }
 
+        /**
+         * Creates ProgramFragment from the current state of the builder
+         *
+         * @return  ProgramFragment
+         */
         public ProgramFragment create() {
             mRS.validate();
             int[] tmp = new int[(mInputCount + mOutputCount + mConstantCount + mTextureCount) * 2];
diff --git a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
index f0040c6..663bc9f 100644
--- a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
+++ b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
@@ -22,6 +22,13 @@ import android.util.Log;
 
 
 /**
+ * ProgramFragmentFixedFunction is a helper class that provides
+ * a way to make a simple fragment shader without writing any
+ * GLSL code.
+ *
+ * This class allows for display of constant color, interpolated
+ * color from vertex shader, or combinations of the above
+ * blended with results of up to two texture lookups.
  *
  **/
 public class ProgramFragmentFixedFunction extends ProgramFragment {
@@ -34,6 +41,12 @@ public class ProgramFragmentFixedFunction extends ProgramFragment {
             super(rs);
         }
 
+        /**
+         * Creates ProgramFragmentFixedFunction from the current state
+         * of the builder
+         *
+         * @return  ProgramFragmentFixedFunction
+         */
         public ProgramFragmentFixedFunction create() {
             mRS.validate();
             int[] tmp = new int[(mInputCount + mOutputCount + mConstantCount + mTextureCount) * 2];
@@ -71,6 +84,11 @@ public class ProgramFragmentFixedFunction extends ProgramFragment {
         String mShader;
         RenderScript mRS;
 
+        /**
+         * EnvMode describes how textures are combined with the existing
+         * color in the fixed function fragment shader
+         *
+         **/
         public enum EnvMode {
             REPLACE (1),
             MODULATE (2),
@@ -82,6 +100,11 @@ public class ProgramFragmentFixedFunction extends ProgramFragment {
             }
         }
 
+        /**
+         * Format describes the pixel format of textures in the fixed
+         * function fragment shader and how they are sampled
+         *
+         **/
         public enum Format {
             ALPHA (1),
             LUMINANCE_ALPHA (2),
@@ -168,12 +191,30 @@ public class ProgramFragmentFixedFunction extends ProgramFragment {
             mShader += "}\n";
         }
 
+        /**
+         * Creates a builder for fixed function fragment program
+         *
+         * @param rs
+         */
         public Builder(RenderScript rs) {
             mRS = rs;
             mSlots = new Slot[MAX_TEXTURE];
             mPointSpriteEnable = false;
         }
 
+        /**
+         * Adds a texture to be fetched as part of the fixed function
+         * fragment program
+         *
+         * @param env specifies how the texture is combined with the
+         *            current color
+         * @param fmt specifies the format of the texture and how its
+         *            components will be used to combine with the
+         *            current color
+         * @param slot index of the texture to apply the operations on
+         *
+         * @return this
+         */
         public Builder setTexture(EnvMode env, Format fmt, int slot)
             throws IllegalArgumentException {
             if((slot < 0) || (slot >= MAX_TEXTURE)) {
@@ -183,16 +224,34 @@ public class ProgramFragmentFixedFunction extends ProgramFragment {
             return this;
         }
 
+        /**
+         * Specifies whether the texture coordinate passed from the
+         * vertex program is replaced with an openGL internal point
+         * sprite texture coordinate
+         *
+         **/
         public Builder setPointSpriteTexCoordinateReplacement(boolean enable) {
             mPointSpriteEnable = enable;
             return this;
         }
 
+        /**
+         * Specifies whether the varying color passed from the vertex
+         * program or the constant color set on the fragment program is
+         * used in the final color calculation in the fixed function
+         * fragment shader
+         *
+         **/
         public Builder setVaryingColor(boolean enable) {
             mVaryingColorEnable = enable;
             return this;
         }
 
+        /**
+        * Creates the fixed function fragment program from the current
+        * state of the builder.
+        *
+        */
         public ProgramFragmentFixedFunction create() {
             InternalBuilder sb = new InternalBuilder(mRS);
             mNumTextures = 0;
diff --git a/graphics/java/android/renderscript/ProgramVertex.java b/graphics/java/android/renderscript/ProgramVertex.java
index 13800ff..7ba8b82 100644
--- a/graphics/java/android/renderscript/ProgramVertex.java
+++ b/graphics/java/android/renderscript/ProgramVertex.java
@@ -23,6 +23,9 @@ import android.util.Log;
 
 
 /**
+ * ProgramVertex, also know as a vertex shader, describes a
+ * stage in the graphics pipeline responsible for manipulating
+ * geometric data in a user-defined way.
  *
  **/
 public class ProgramVertex extends Program {
@@ -31,11 +34,31 @@ public class ProgramVertex extends Program {
         super(id, rs);
     }
 
+    /**
+    * Builder class for creating ProgramVertex objects.
+    * The builder starts empty and the user must minimally provide
+    * the GLSL shader code, and the varying inputs. Constant, or
+    * uniform parameters to the shader may optionally be provided as
+    * well.
+    *
+    **/
     public static class Builder extends BaseProgramBuilder {
+        /**
+         * Create a builder object.
+         *
+         * @param rs
+         */
         public Builder(RenderScript rs) {
             super(rs);
         }
 
+        /**
+         * Add varying inputs to the program
+         *
+         * @param e element describing the layout of the varying input
+         *          structure
+         * @return  self
+         */
         public Builder addInput(Element e) throws IllegalStateException {
             // Should check for consistant and non-conflicting names...
             if(mInputCount >= MAX_INPUT) {
@@ -48,6 +71,11 @@ public class ProgramVertex extends Program {
             return this;
         }
 
+        /**
+         * Creates ProgramVertex from the current state of the builder
+         *
+         * @return  ProgramVertex
+         */
         public ProgramVertex create() {
             mRS.validate();
             int[] tmp = new int[(mInputCount + mOutputCount + mConstantCount + mTextureCount) * 2];
diff --git a/graphics/java/android/renderscript/ProgramVertexFixedFunction.java b/graphics/java/android/renderscript/ProgramVertexFixedFunction.java
index 1b69efe..b9537c7 100644
--- a/graphics/java/android/renderscript/ProgramVertexFixedFunction.java
+++ b/graphics/java/android/renderscript/ProgramVertexFixedFunction.java
@@ -23,6 +23,9 @@ import android.util.Log;
 
 
 /**
+ * ProgramVertexFixedFunction is a helper class that provides a
+ * simple way to create a fixed function emulation vertex shader
+ * without writing any GLSL code.
  *
  **/
 public class ProgramVertexFixedFunction extends ProgramVertex {
@@ -31,6 +34,12 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
         super(id, rs);
     }
 
+    /**
+     * Binds the constant buffer containing fixed function emulation
+     * matrices
+     *
+     * @param va allocation containing fixed function matrices
+     */
     public void bindConstants(Constants va) {
         mRS.validate();
         bindConstants(va.getAllocation(), 0);
@@ -53,6 +62,12 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
             return this;
         }
 
+        /**
+         * Creates ProgramVertexFixedFunction from the current state of
+         * the builder
+         *
+         * @return  ProgramVertexFixedFunction
+         */
         public ProgramVertexFixedFunction create() {
             mRS.validate();
             int[] tmp = new int[(mInputCount + mOutputCount + mConstantCount + mTextureCount) * 2];
@@ -87,10 +102,20 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
         String mShader;
         RenderScript mRS;
 
+        /**
+         * Creates a builder for fixed function vertex program
+         *
+         * @param rs
+         */
         public Builder(RenderScript rs) {
             mRS = rs;
         }
 
+        /**
+         * Specifies whether texture matrix calculations are to be added
+         * to the shader
+         *
+         */
         public Builder setTextureMatrixEnable(boolean enable) {
             mTextureMatrixEnable = enable;
             return this;
@@ -126,6 +151,12 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
             mShader += "}\n";
         }
 
+        /**
+         * Creates ProgramVertexFixedFunction from the current state of
+         * the builder
+         *
+         * @return Fixed function emulation ProgramVertex
+         */
         public ProgramVertexFixedFunction create() {
             buildShaderString();
 
@@ -144,6 +175,11 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
         }
     }
 
+    /**
+     * Helper class to store modelview, projection and texture
+     * matrices for ProgramVertexFixedFunction
+     *
+     */
     public static class Constants {
         static final int MODELVIEW_OFFSET = 0;
         static final int PROJECTION_OFFSET = 16;
@@ -159,6 +195,11 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
         }
         private FieldPacker mIOBuffer;
 
+        /**
+        * Creates buffer to store fixed function emulation matrices
+        *
+        * @param rs
+        **/
         public Constants(RenderScript rs) {
             Type constInputType = ProgramVertexFixedFunction.Builder.getConstantInputType(rs);
             mAlloc = Allocation.createTyped(rs, constInputType);
@@ -173,6 +214,11 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
             setTexture(new Matrix4f());
         }
 
+        /**
+        * Forces deallocation of memory backing the contant matrices.
+        * Normally, this is unnecessary and will be garbage collected
+        *
+        */
         public void destroy() {
             mAlloc.destroy();
             mAlloc = null;
@@ -186,16 +232,34 @@ public class ProgramVertexFixedFunction extends ProgramVertex {
             mAlloc.copyFrom(mIOBuffer.getData());
         }
 
+        /**
+        * Sets the modelview matrix in the fixed function matrix buffer
+        *
+        * @param m modelview matrix
+        */
         public void setModelview(Matrix4f m) {
             mModel.load(m);
             addToBuffer(MODELVIEW_OFFSET*4, m);
         }
 
+        /**
+        * Sets the projection matrix in the fixed function matrix buffer
+        *
+        * @param m projection matrix
+        */
         public void setProjection(Matrix4f m) {
             mProjection.load(m);
             addToBuffer(PROJECTION_OFFSET*4, m);
         }
 
+        /**
+        * Sets the texture matrix in the fixed function matrix buffer.
+        * Texture matrix must be enabled in the
+        * ProgramVertexFixedFunction builder for the shader to utilize
+        * it.
+        *
+        * @param m modelview matrix
+        */
         public void setTexture(Matrix4f m) {
             mTexture.load(m);
             addToBuffer(TEXTURE_OFFSET*4, m);