Document RS element and type and add validity checking to type creation.

Change-Id: Ic96c0199e27785b3eabde2c6e95ed514915328e9

2 files changed, 224 insertions, 1 deletions

diff --git a/graphics/java/android/renderscript/Element.java b/graphics/java/android/renderscript/Element.java
index 8907cd2..4b007f2 100644
--- a/graphics/java/android/renderscript/Element.java
+++ b/graphics/java/android/renderscript/Element.java
@@ -22,6 +22,25 @@ import android.util.Log;
 /**
  * @hide
  *
+ * Element is the basic data type of RenderScript.  An element can be of 2
+ * forms.  Basic elements contain a single component of data.  This can be of
+ * any of the legal RS types.  Examples of basic element types.
+ * Single float value
+ * 4 element float vector
+ * single RGB-565 color
+ * single unsigned int 16
+ *
+ * Complex elements will contain a list of sub-elements and names.  This in
+ * effect represents a structure of data.  The fields can be accessed by name
+ * from a script or shader.  The memory layout is defined and ordered.  Data
+ * alignment is determinied by the most basic primitive type.  i.e. a float4
+ * vector will be alligned to sizeof(float) and not sizeof(float4).  The
+ * ordering of elements in memory will be the order in which they were added
+ * with each component aligned as necessary. No re-ordering will be done.
+ *
+ * The primary source of elements will be from scripts.  A script that exports a
+ * bind point for a data structure will generate a RS element to represent the
+ * data exported by the script.
  **/
 public class Element extends BaseObj {
     int mSize;
@@ -36,6 +55,21 @@ public class Element extends BaseObj {
 
     int getSizeBytes() {return mSize;}
 
+
+    /**
+     * DataType represents the basic type information for a basic element.  The
+     * naming convention follows.  For numeric types its FLOAT, SIGNED, UNSIGNED
+     * followed by the _BITS where BITS is the size of the data.  BOOLEAN is a
+     * true / false (1,0) represented in an 8 bit container.  The UNSIGNED
+     * variants with multiple bit definitions are for packed graphical data
+     * formats and represents vectors with per vector member sizes which are
+     * treated as a single unit for packing and alignment purposes.
+     *
+     * MATRIX the three matrix types contain FLOAT_32 elements and are treated
+     * as 32 bits for alignment purposes.
+     *
+     * RS_* objects.  32 bit opaque handles.
+     */
     public enum DataType {
         //FLOAT_16 (1, 2),
         FLOAT_32 (2, 4),
@@ -78,6 +112,12 @@ public class Element extends BaseObj {
         }
     }
 
+    /**
+     * The special interpretation of the data if required.  This is primarly
+     * useful for graphical data.  USER indicates no special interpretation is
+     * expected.  PIXEL is used in conjunction with the standard data types for
+     * representing texture formats.
+     */
     public enum DataKind {
         USER (0),
 
@@ -93,6 +133,12 @@ public class Element extends BaseObj {
         }
     }
 
+    /**
+     * Return if a element is too complex for use as a data source for a Mesh or
+     * a Program.
+     *
+     * @return boolean
+     */
     public boolean isComplex() {
         if (mElements == null) {
             return false;
@@ -105,6 +151,13 @@ public class Element extends BaseObj {
         return false;
     }
 
+    /**
+     * Utility function for returning an Element containing a single Boolean.
+     *
+     * @param rs Context to which the element will belong.
+     *
+     * @return Element
+     */
     public static Element BOOLEAN(RenderScript rs) {
         if(rs.mElement_BOOLEAN == null) {
             rs.mElement_BOOLEAN = createUser(rs, DataType.BOOLEAN);
@@ -112,6 +165,13 @@ public class Element extends BaseObj {
         return rs.mElement_BOOLEAN;
     }
 
+    /**
+     * Utility function for returning an Element containing a single UNSIGNED_8.
+     *
+     * @param rs Context to which the element will belong.
+     *
+     * @return Element
+     */
     public static Element U8(RenderScript rs) {
         if(rs.mElement_U8 == null) {
             rs.mElement_U8 = createUser(rs, DataType.UNSIGNED_8);
@@ -119,6 +179,13 @@ public class Element extends BaseObj {
         return rs.mElement_U8;
     }
 
+    /**
+     * Utility function for returning an Element containing a single SIGNED_8.
+     *
+     * @param rs Context to which the element will belong.
+     *
+     * @return Element
+     */
     public static Element I8(RenderScript rs) {
         if(rs.mElement_I8 == null) {
             rs.mElement_I8 = createUser(rs, DataType.SIGNED_8);
@@ -414,7 +481,14 @@ public class Element extends BaseObj {
         super.destroy();
     }
 
-    /////////////////////////////////////////
+    /**
+     * Create a custom Element of the specified DataType.  The DataKind will be
+     * set to USER and the vector size to 1 indicating non-vector.
+     *
+     * @param rs The context associated with the new Element.
+     * @param dt The DataType for the new element.
+     * @return Element
+     */
     public static Element createUser(RenderScript rs, DataType dt) {
         DataKind dk = DataKind.USER;
         boolean norm = false;
@@ -423,6 +497,17 @@ public class Element extends BaseObj {
         return new Element(id, rs, dt, dk, norm, vecSize);
     }
 
+    /**
+     * Create a custom vector element of the specified DataType and vector size.
+     *  DataKind will be set to USER.
+     *
+     * @param rs The context associated with the new Element.
+     * @param dt The DataType for the new element.
+     * @param size Vector size for the new Element.  Range 2-4 inclusive
+     *             supported.
+     *
+     * @return Element
+     */
     public static Element createVector(RenderScript rs, DataType dt, int size) {
         if (size < 2 || size > 4) {
             throw new RSIllegalArgumentException("Vector size out of rance 2-4.");
@@ -433,6 +518,18 @@ public class Element extends BaseObj {
         return new Element(id, rs, dt, dk, norm, size);
     }
 
+    /**
+     * Create a new pixel Element type.  A matching DataType and DataKind must
+     * be provided.  The DataType and DataKind must contain the same number of
+     * components.  Vector size will be set to 1.
+     *
+     * @param rs The context associated with the new Element.
+     * @param dt The DataType for the new element.
+     * @param dk The DataKind to specify the mapping of each component in the
+     *           DataType.
+     *
+     * @return Element
+     */
     public static Element createPixel(RenderScript rs, DataType dt, DataKind dk) {
         if (!(dk == DataKind.PIXEL_L ||
               dk == DataKind.PIXEL_A ||
@@ -473,6 +570,12 @@ public class Element extends BaseObj {
         return new Element(id, rs, dt, dk, norm, size);
     }
 
+    /**
+     * Builder class for producing complex elements with matching field and name
+     * pairs.  The builder starts empty.  The order in which elements are added
+     * is retained for the layout in memory.
+     *
+     */
     public static class Builder {
         RenderScript mRS;
         Element[] mElements;
@@ -480,6 +583,11 @@ public class Element extends BaseObj {
         int[] mArraySizes;
         int mCount;
 
+        /**
+         * Create a builder object.
+         *
+         * @param rs
+         */
         public Builder(RenderScript rs) {
             mRS = rs;
             mCount = 0;
@@ -488,6 +596,13 @@ public class Element extends BaseObj {
             mArraySizes = new int[8];
         }
 
+        /**
+         * Add an array of elements to this element.
+         *
+         * @param element
+         * @param name
+         * @param arraySize
+         */
         public void add(Element element, String name, int arraySize) {
             if (arraySize < 1) {
                 throw new RSIllegalArgumentException("Array size cannot be less than 1.");
@@ -509,10 +624,22 @@ public class Element extends BaseObj {
             mCount++;
         }
 
+        /**
+         * Add a single element to this Element.
+         *
+         * @param element
+         * @param name
+         */
         public void add(Element element, String name) {
             add(element, name, 1);
         }
 
+        /**
+         * Create the element from this builder.
+         *
+         *
+         * @return Element
+         */
         public Element create() {
             mRS.validate();
             Element[] ein = new Element[mCount];
diff --git a/graphics/java/android/renderscript/Type.java b/graphics/java/android/renderscript/Type.java
index ad933b8..44aee63 100644
--- a/graphics/java/android/renderscript/Type.java
+++ b/graphics/java/android/renderscript/Type.java
@@ -23,6 +23,20 @@ import android.util.Log;
 /**
  * @hide
  *
+ * Type is an allocation template.  It consists of an Element and one or more
+ * dimensions.  It describes only the layout of memory but does not allocate and
+ * storage for the data thus described.
+ *
+ * A Type consists of several dimensions.  Those are X, Y, Z, LOD (level of
+ * detail), Faces (faces of a cube map).  The X,Y,Z dimensions can be assigned
+ * any positive integral value within the constraints of available memory.  A
+ * single dimension allocation would have an X dimension of greater than zero
+ * while the Y and Z dimensions would be zero to indicate not present.  In this
+ * regard an allocation of x=10, y=1 would be considered 2 dimensionsal while
+ * x=10, y=0 would be considered 1 dimensional.
+ *
+ * The LOD and Faces dimensions are booleans to indicate present or not present.
+ *
  **/
 public class Type extends BaseObj {
     int mDimX;
@@ -33,25 +47,65 @@ public class Type extends BaseObj {
     int mElementCount;
     Element mElement;
 
+    /**
+     * Return the element associated with this Type.
+     *
+     * @return Element
+     */
     public Element getElement() {
         return mElement;
     }
 
+    /**
+     * Return the value of the X dimension.
+     *
+     * @return int
+     */
     public int getX() {
         return mDimX;
     }
+
+    /**
+     * Return the value of the Y dimension or 0 for a 1D allocation.
+     *
+     * @return int
+     */
     public int getY() {
         return mDimY;
     }
+
+    /**
+     * Return the value of the Z dimension or 0 for a 1D or 2D allocation.
+     *
+     * @return int
+     */
     public int getZ() {
         return mDimZ;
     }
+
+    /**
+     * Return if the Type has a mipmap chain.
+     *
+     * @return boolean
+     */
     public boolean getLOD() {
         return mDimLOD;
     }
+
+    /**
+     * Return if the Type is a cube map.
+     *
+     * @return boolean
+     */
     public boolean getFaces() {
         return mDimFaces;
     }
+
+    /**
+     * Return the total number of accessable cells in the Type.
+     *
+     * @return int
+     */
     public int getElementCount() {
         return mElementCount;
     }
@@ -122,6 +176,10 @@ public class Type extends BaseObj {
         calcElementCount();
     }
 
+    /**
+     * Builder class for Type.
+     *
+     */
     public static class Builder {
         RenderScript mRS;
         Dimension[] mDimensions;
@@ -134,6 +192,12 @@ public class Type extends BaseObj {
             int mValue;
         }
 
+        /**
+         * Create a new builder object.
+         *
+         * @param rs
+         * @param e The element for the type to be created.
+         */
         public Builder(RenderScript rs, Element e) {
             if(e.getID() == 0) {
                 throw new RSIllegalArgumentException("Invalid element.");
@@ -145,6 +209,13 @@ public class Type extends BaseObj {
             mElement = e;
         }
 
+        /**
+         * Add a dimension to the Type.
+         *
+         *
+         * @param d
+         * @param value
+         */
         public void add(Dimension d, int value) {
             if(value < 1) {
                 throw new RSIllegalArgumentException("Values of less than 1 for Dimensions are not valid.");
@@ -163,6 +234,11 @@ public class Type extends BaseObj {
             mEntryCount++;
         }
 
+        /**
+         * Validate structure and create a new type.
+         *
+         * @return Type
+         */
         public Type create() {
             int dims[] = new int[mEntryCount];
             for (int ct=0; ct < mEntryCount; ct++) {
@@ -190,6 +266,26 @@ public class Type extends BaseObj {
                     t.mDimFaces = mDimensionValues[ct] != 0;
                 }
             }
+
+            if (t.mDimZ > 0) {
+                if ((t.mDimX < 1) || (t.mDimY < 1)) {
+                    throw new RSInvalidStateException("Both X and Y dimension required when Z is present.");
+                }
+                if (t.mDimFaces) {
+                    throw new RSInvalidStateException("Cube maps not supported with 3D types.");
+                }
+            }
+            if (t.mDimY > 0) {
+                if (t.mDimX < 1) {
+                    throw new RSInvalidStateException("X dimension required when Y is present.");
+                }
+            }
+            if (t.mDimFaces) {
+                if (t.mDimY < 1) {
+                    throw new RSInvalidStateException("Cube maps require 2D Types.");
+                }
+            }
+
             t.calcElementCount();
             return t;
         }