Documentation

Change-Id: Idb5f87f9d2c0f7fb4677b1b45c232502d66b4668

2 files changed, 332 insertions, 14 deletions

diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java
index 6b309e1..b15121a 100644
--- a/graphics/java/android/renderscript/Allocation.java
+++ b/graphics/java/android/renderscript/Allocation.java
@@ -479,26 +479,67 @@ public class Allocation extends BaseObj {
         mBitmapOptions.inScaled = false;
     }
 
-    static public Allocation createTyped(RenderScript rs, Type type, MipmapControl mc, int usage) {
+    /**
+     *
+     * @param type renderscript type describing data layout
+     * @param mips specifies desired mipmap behaviour for the
+     *             allocation
+     * @param usage bit field specifying how the allocation is
+     *              utilized
+     */
+    static public Allocation createTyped(RenderScript rs, Type type, MipmapControl mips, int usage) {
         rs.validate();
         if (type.getID() == 0) {
             throw new RSInvalidStateException("Bad Type");
         }
-        int id = rs.nAllocationCreateTyped(type.getID(), mc.mID, usage);
+        int id = rs.nAllocationCreateTyped(type.getID(), mips.mID, usage);
         if (id == 0) {
             throw new RSRuntimeException("Allocation creation failed.");
         }
         return new Allocation(id, rs, type, usage);
     }
 
+    /**
+     * Creates a renderscript allocation with the size specified by
+     * the type and no mipmaps generated by default
+     *
+     * @param rs
+     * @param type renderscript type describing data layout
+     * @param usage bit field specifying how the allocation is
+     *              utilized
+     *
+     * @return allocation
+     */
     static public Allocation createTyped(RenderScript rs, Type type, int usage) {
         return createTyped(rs, type, MipmapControl.MIPMAP_NONE, usage);
     }
 
+    /**
+     * Creates a renderscript allocation for use by the script with
+     * the size specified by the type and no mipmaps generated by
+     * default
+     *
+     * @param rs
+     * @param type renderscript type describing data layout
+     *
+     * @return allocation
+     */
     static public Allocation createTyped(RenderScript rs, Type type) {
         return createTyped(rs, type, MipmapControl.MIPMAP_NONE, USAGE_SCRIPT);
     }
 
+    /**
+     * Creates a renderscript allocation with a specified number of
+     * given elements
+     *
+     * @param rs
+     * @param e describes what each element of an allocation is
+     * @param count specifies the number of element in the allocation
+     * @param usage bit field specifying how the allocation is
+     *              utilized
+     *
+     * @return allocation
+     */
     static public Allocation createSized(RenderScript rs, Element e,
                                          int count, int usage) {
         rs.validate();
@@ -513,6 +554,16 @@ public class Allocation extends BaseObj {
         return new Allocation(id, rs, t, usage);
     }
 
+    /**
+     * Creates a renderscript allocation with a specified number of
+     * given elements
+     *
+     * @param rs
+     * @param e describes what each element of an allocation is
+     * @param count specifies the number of element in the allocation
+     *
+     * @return allocation
+     */
     static public Allocation createSized(RenderScript rs, Element e, int count) {
         return createSized(rs, e, count, USAGE_SCRIPT);
     }
@@ -544,6 +595,19 @@ public class Allocation extends BaseObj {
         return tb.create();
     }
 
+    /**
+     * Creates a renderscript allocation from a bitmap
+     *
+     * @param rs
+     * @param b bitmap source for the allocation data
+     * @param mips specifies desired mipmap behaviour for the
+     *             allocation
+     * @param usage bit field specifying how the allocation is
+     *              utilized
+     *
+     * @return renderscript allocation containing bitmap data
+     *
+     */
     static public Allocation createFromBitmap(RenderScript rs, Bitmap b,
                                               MipmapControl mips,
                                               int usage) {
@@ -557,23 +621,35 @@ public class Allocation extends BaseObj {
         return new Allocation(id, rs, t, usage);
     }
 
+    /**
+     * Creates a non-mipmapped renderscript allocation to use as a
+     * graphics texture
+     *
+     * @param rs
+     * @param b bitmap source for the allocation data
+     *
+     * @return renderscript allocation containing bitmap data
+     *
+     */
     static public Allocation createFromBitmap(RenderScript rs, Bitmap b) {
         return createFromBitmap(rs, b, MipmapControl.MIPMAP_NONE,
                                 USAGE_GRAPHICS_TEXTURE);
     }
 
     /**
-    * Creates a cubemap allocation from a bitmap containing the
-    * horizontal list of cube faces. Each individual face must be
-    * the same size and power of 2
-    *
-    * @param rs
-    * @param b bitmap with cubemap faces layed out in the following
-    *          format: right, left, top, bottom, front, back
-    * @param mips specifies desired mipmap behaviour for the cubemap
-    * @param usage bitfield specifying how the cubemap is utilized
-    *
-    **/
+     * Creates a cubemap allocation from a bitmap containing the
+     * horizontal list of cube faces. Each individual face must be
+     * the same size and power of 2
+     *
+     * @param rs
+     * @param b bitmap with cubemap faces layed out in the following
+     *          format: right, left, top, bottom, front, back
+     * @param mips specifies desired mipmap behaviour for the cubemap
+     * @param usage bit field specifying how the cubemap is utilized
+     *
+     * @return allocation containing cubemap data
+     *
+     */
     static public Allocation createCubemapFromBitmap(RenderScript rs, Bitmap b,
                                                      MipmapControl mips,
                                                      int usage) {
@@ -608,12 +684,43 @@ public class Allocation extends BaseObj {
         return new Allocation(id, rs, t, usage);
     }
 
+    /**
+     * Creates a non-mipmapped cubemap allocation for use as a
+     * graphics texture from a bitmap containing the horizontal list
+     * of cube faces. Each individual face must be the same size and
+     * power of 2
+     *
+     * @param rs
+     * @param b bitmap with cubemap faces layed out in the following
+     *          format: right, left, top, bottom, front, back
+     *
+     * @return allocation containing cubemap data
+     *
+     */
     static public Allocation createCubemapFromBitmap(RenderScript rs,
                                                      Bitmap b) {
         return createCubemapFromBitmap(rs, b, MipmapControl.MIPMAP_NONE,
                                        USAGE_GRAPHICS_TEXTURE);
     }
 
+    /**
+     * Creates a cubemap allocation from 6 bitmaps containing
+     * the cube faces. All the faces must be the same size and
+     * power of 2
+     *
+     * @param rs
+     * @param xpos cubemap face in the positive x direction
+     * @param xneg cubemap face in the negative x direction
+     * @param ypos cubemap face in the positive y direction
+     * @param yneg cubemap face in the negative y direction
+     * @param zpos cubemap face in the positive z direction
+     * @param zneg cubemap face in the negative z direction
+     * @param mips specifies desired mipmap behaviour for the cubemap
+     * @param usage bit field specifying how the cubemap is utilized
+     *
+     * @return allocation containing cubemap data
+     *
+     */
     static public Allocation createCubemapFromCubeFaces(RenderScript rs,
                                                         Bitmap xpos,
                                                         Bitmap xneg,
@@ -663,6 +770,23 @@ public class Allocation extends BaseObj {
         return cubemap;
     }
 
+    /**
+     * Creates a non-mipmapped cubemap allocation for use as a
+     * graphics texture from 6 bitmaps containing
+     * the cube faces. All the faces must be the same size and
+     * power of 2
+     *
+     * @param rs
+     * @param xpos cubemap face in the positive x direction
+     * @param xneg cubemap face in the negative x direction
+     * @param ypos cubemap face in the positive y direction
+     * @param yneg cubemap face in the negative y direction
+     * @param zpos cubemap face in the positive z direction
+     * @param zneg cubemap face in the negative z direction
+     *
+     * @return allocation containing cubemap data
+     *
+     */
     static public Allocation createCubemapFromCubeFaces(RenderScript rs,
                                                         Bitmap xpos,
                                                         Bitmap xneg,
@@ -675,6 +799,21 @@ public class Allocation extends BaseObj {
                                           USAGE_GRAPHICS_TEXTURE);
     }
 
+    /**
+     * Creates a renderscript allocation from the bitmap referenced
+     * by resource id
+     *
+     * @param rs
+     * @param res application resources
+     * @param id resource id to load the data from
+     * @param mips specifies desired mipmap behaviour for the
+     *             allocation
+     * @param usage bit field specifying how the allocation is
+     *              utilized
+     *
+     * @return renderscript allocation containing resource data
+     *
+     */
     static public Allocation createFromBitmapResource(RenderScript rs,
                                                       Resources res,
                                                       int id,
@@ -688,6 +827,17 @@ public class Allocation extends BaseObj {
         return alloc;
     }
 
+    /**
+     * Creates a non-mipmapped renderscript allocation to use as a
+     * graphics texture from the bitmap referenced by resource id
+     *
+     * @param rs
+     * @param res application resources
+     * @param id resource id to load the data from
+     *
+     * @return renderscript allocation containing resource data
+     *
+     */
     static public Allocation createFromBitmapResource(RenderScript rs,
                                                       Resources res,
                                                       int id) {
@@ -696,6 +846,16 @@ public class Allocation extends BaseObj {
                                         USAGE_GRAPHICS_TEXTURE);
     }
 
+    /**
+     * Creates a renderscript allocation containing string data
+     * encoded in UTF-8 format
+     *
+     * @param rs
+     * @param str string to create the allocation from
+     * @param usage bit field specifying how the allocaiton is
+     *              utilized
+     *
+     */
     static public Allocation createFromString(RenderScript rs,
                                               String str,
                                               int usage) {
diff --git a/graphics/java/android/renderscript/ProgramStore.java b/graphics/java/android/renderscript/ProgramStore.java
index 0e2227e..d79900e 100644
--- a/graphics/java/android/renderscript/ProgramStore.java
+++ b/graphics/java/android/renderscript/ProgramStore.java
@@ -22,16 +22,61 @@ import android.util.Log;
 
 
 /**
+ * ProgarmStore contains a set of parameters that control how
+ * the graphics hardware handles writes to the framebuffer.
+ *
+ * It could be used to:
+ *   - enable/diable depth testing
+ *   - specify wheather depth writes are performed
+ *   - setup various blending modes for use in effects like
+ *     transparency
+ *   - define write masks for color components written into the
+ *     framebuffer
  *
  **/
 public class ProgramStore extends BaseObj {
+    /**
+    * Specifies the function used to determine whether a fragment
+    * will be drawn during the depth testing stage in the rendering
+    * pipeline by comparing its value with that already in the depth
+    * buffer. DepthFunc is only valid when depth buffer is present
+    * and depth testing is enabled
+    */
     public enum DepthFunc {
+
+        /**
+        * Always drawn
+        */
         ALWAYS (0),
+        /**
+        * Drawn if the incoming depth value is less than that in the
+        * depth buffer
+        */
         LESS (1),
+        /**
+        * Drawn if the incoming depth value is less or equal to that in
+        * the depth buffer
+        */
         LESS_OR_EQUAL (2),
+        /**
+        * Drawn if the incoming depth value is greater than that in the
+        * depth buffer
+        */
         GREATER (3),
+        /**
+        * Drawn if the incoming depth value is greater or equal to that
+        * in the depth buffer
+        */
         GREATER_OR_EQUAL (4),
+        /**
+        * Drawn if the incoming depth value is equal to that in the
+        * depth buffer
+        */
         EQUAL (5),
+        /**
+        * Drawn if the incoming depth value is not equal to that in the
+        * depth buffer
+        */
         NOT_EQUAL (6);
 
         int mID;
@@ -40,6 +85,14 @@ public class ProgramStore extends BaseObj {
         }
     }
 
+    /**
+    * Specifies the functions used to combine incoming pixels with
+    * those already in the frame buffer.
+    *
+    * BlendSrcFunc describes how the coefficient used to scale the
+    * source pixels during the blending operation is computed
+    *
+    */
     public enum BlendSrcFunc {
         ZERO (0),
         ONE (1),
@@ -57,6 +110,15 @@ public class ProgramStore extends BaseObj {
         }
     }
 
+    /**
+    * Specifies the functions used to combine incoming pixels with
+    * those already in the frame buffer.
+    *
+    * BlendDstFunc describes how the coefficient used to scale the
+    * pixels already in the framebuffer is computed during the
+    * blending operation
+    *
+    */
     public enum BlendDstFunc {
         ZERO (0),
         ONE (1),
@@ -78,6 +140,17 @@ public class ProgramStore extends BaseObj {
         super(id, rs);
     }
 
+    /**
+    * Returns a pre-defined program store object with the following
+    * characteristics:
+    *  - incoming pixels are drawn if their depth value is less than
+    *    the stored value in the depth buffer. If the pixel is
+    *    drawn, its value is also stored in the depth buffer
+    *  - incoming pixels override the value stored in the color
+    *    buffer if it passes the depth test
+    *
+    *  @param rs
+    **/
     public static ProgramStore BLEND_NONE_DEPTH_TEST(RenderScript rs) {
         if(rs.mProgramStore_BLEND_NONE_DEPTH_TEST == null) {
             ProgramStore.Builder builder = new ProgramStore.Builder(rs);
@@ -89,6 +162,16 @@ public class ProgramStore extends BaseObj {
         }
         return rs.mProgramStore_BLEND_NONE_DEPTH_TEST;
     }
+    /**
+    * Returns a pre-defined program store object with the following
+    * characteristics:
+    *  - incoming pixels always pass the depth test and their value
+    *    is not stored in the depth buffer
+    *  - incoming pixels override the value stored in the color
+    *    buffer
+    *
+    *  @param rs
+    **/
     public static ProgramStore BLEND_NONE_DEPTH_NONE(RenderScript rs) {
         if(rs.mProgramStore_BLEND_NONE_DEPTH_NO_DEPTH == null) {
             ProgramStore.Builder builder = new ProgramStore.Builder(rs);
@@ -100,7 +183,19 @@ public class ProgramStore extends BaseObj {
         }
         return rs.mProgramStore_BLEND_NONE_DEPTH_NO_DEPTH;
     }
-
+    /**
+    * Returns a pre-defined program store object with the following
+    * characteristics:
+    *  - incoming pixels are drawn if their depth value is less than
+    *    the stored value in the depth buffer. If the pixel is
+    *    drawn, its value is also stored in the depth buffer
+    *  - if the incoming (Source) pixel passes depth test, its value
+    *    is combined with the stored color (Dest) using the
+    *    following formula
+    *  Final.RGB = Source.RGB * Source.A + Dest.RGB * (1 - Source.A)
+    *
+    *  @param rs
+    **/
     public static ProgramStore BLEND_ALPHA_DEPTH_TEST(RenderScript rs) {
         if(rs.mProgramStore_BLEND_ALPHA_DEPTH_TEST == null) {
             ProgramStore.Builder builder = new ProgramStore.Builder(rs);
@@ -112,6 +207,17 @@ public class ProgramStore extends BaseObj {
         }
         return rs.mProgramStore_BLEND_ALPHA_DEPTH_TEST;
     }
+    /**
+    * Returns a pre-defined program store object with the following
+    * characteristics:
+    *  - incoming pixels always pass the depth test and their value
+    *    is not stored in the depth buffer
+    *  - incoming pixel's value is combined with the stored color
+    *    (Dest) using the following formula
+    *  Final.RGB = Source.RGB * Source.A + Dest.RGB * (1 - Source.A)
+    *
+    *  @param rs
+    **/
     public static ProgramStore BLEND_ALPHA_DEPTH_NONE(RenderScript rs) {
         if(rs.mProgramStore_BLEND_ALPHA_DEPTH_NO_DEPTH == null) {
             ProgramStore.Builder builder = new ProgramStore.Builder(rs);
@@ -124,6 +230,11 @@ public class ProgramStore extends BaseObj {
         return rs.mProgramStore_BLEND_ALPHA_DEPTH_NO_DEPTH;
     }
 
+    /**
+    * Builder class for ProgramStore object. If the builder is left
+    * empty, the equivalent of BLEND_NONE_DEPTH_NONE would be
+    * returned
+    */
     public static class Builder {
         RenderScript mRS;
         DepthFunc mDepthFunc;
@@ -148,16 +259,41 @@ public class ProgramStore extends BaseObj {
             mBlendDst = BlendDstFunc.ZERO;
         }
 
+        /**
+        * Specifies the depth testing behavior
+        *
+        * @param func function used for depth testing
+        *
+        * @return this
+        */
         public Builder setDepthFunc(DepthFunc func) {
             mDepthFunc = func;
             return this;
         }
 
+        /**
+        * Enables writes into the depth buffer
+        *
+        * @param enable specifies whether depth writes are
+        *         enabled or disabled
+        *
+        * @return this
+        */
         public Builder setDepthMaskEnabled(boolean enable) {
             mDepthMask = enable;
             return this;
         }
 
+        /**
+        * Enables writes into the color buffer
+        *
+        * @param r specifies whether red channel is written
+        * @param g specifies whether green channel is written
+        * @param b specifies whether blue channel is written
+        * @param a specifies whether alpha channel is written
+        *
+        * @return this
+        */
         public Builder setColorMaskEnabled(boolean r, boolean g, boolean b, boolean a) {
             mColorMaskR = r;
             mColorMaskG = g;
@@ -166,12 +302,31 @@ public class ProgramStore extends BaseObj {
             return this;
         }
 
+        /**
+        * Specifies how incoming pixels are combined with the pixels
+        * stored in the framebuffer
+        *
+        * @param src specifies how the source blending factor is
+        *            computed
+        * @param dst specifies how the destination blending factor is
+        *            computed
+        *
+        * @return this
+        */
         public Builder setBlendFunc(BlendSrcFunc src, BlendDstFunc dst) {
             mBlendSrc = src;
             mBlendDst = dst;
             return this;
         }
 
+        /**
+        * Enables dithering
+        *
+        * @param enable specifies whether dithering is enabled or
+        *               disabled
+        *
+        * @return this
+        */
         public Builder setDitherEnabled(boolean enable) {
             mDither = enable;
             return this;
@@ -192,6 +347,9 @@ public class ProgramStore extends BaseObj {
             return new ProgramStore(id, rs);
         }
 
+        /**
+        * Creates a program store from the current state of the builder
+        */
         public ProgramStore create() {
             mRS.validate();
             return internalCreate(mRS, this);