Merge "clean up and add javadocs" into honeycomb

graphics/java/android/renderscript/Allocation.java

@@ -26,19 +26,41 @@ import android.util.Log;
 import android.util.TypedValue;
 
 /**
- * Memory allocation class for renderscript.  An allocation combines a Type with
+ * <p>
- * memory to provide storage for user data and objects.
+ * Memory allocation class for renderscript.  An allocation combines a
+ * {@link android.renderscript.Type} with the memory to provide storage for user data and objects.
+ * This implies that all memory in Renderscript is typed.
+ * </p>
  *
- * Allocations may exist in one or more memory spaces.  Currently those are
+ * <p>Allocations are the primary way data moves into and out of scripts. Memory is user
- * Script: accessable by RS scripts.
+ * synchronized and it's possible for allocations to exist in multiple memory spaces
- * Graphics Texture: accessable as a graphics texture.
+ * concurrently. Currently those spaces are:</p>
- * Graphics Vertex: accessable as graphical vertex data.
+ * <ul>
- * Graphics Constants: Accessable as constants in user shaders
+ * <li>Script: accessable by RS scripts.</li>
+ * <li>Graphics Texture: accessable as a graphics texture.</li>
+ * <li>Graphics Vertex: accessable as graphical vertex data.</li>
+ * <li>Graphics Constants: Accessable as constants in user shaders</li>
+ * </ul>
+ * </p>
+ * <p>
+ * For example, when creating a allocation for a texture, the user can
+ * specify its memory spaces as both script and textures. This means that it can both
+ * be used as script binding and as a GPU texture for rendering. To maintain
+ * synchronization if a script modifies an allocation used by other targets it must
+ * call a synchronizing function to push the updates to the memory, otherwise the results
+ * are undefined.
+ * </p>
+ * <p>By default, Android system side updates are always applied to the script accessable
+ * memory. If this is not present, they are then applied to the various HW
+ * memory types.  A {@link android.renderscript.Allocation#syncAll syncAll()}
+ * call is necessary after the script data is updated to
+ * keep the other memory spaces in sync.</p>
  *
- * By default java side updates are always applied to the script accessable
+ * <p>Allocation data is uploaded in one of two primary ways. For simple
- * memory.  If this is not present they are then applied to the various HW
+ * arrays there are copyFrom() functions that take an array from the control code and
- * memory types.  A syncAll call is necessary after the script data is update to
+ * copy it to the slave memory store. Both type checked and unchecked copies are provided.
- * keep the other memory spaces in sync.
+ * The unchecked variants exist to allow apps to copy over arrays of structures from a
+ * control language that does not support structures.</p>
  *
  **/
 public class Allocation extends BaseObj {

graphics/java/android/renderscript/Byte2.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs byte2 type back to java applications.
+ * Class for exposing the native Renderscript byte2 type back to the Android system.
  *
  **/
 public class Byte2 {

graphics/java/android/renderscript/Byte3.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs byte3 type back to java applications.
+ * Class for exposing the native Renderscript byte3 type back to the Android system.
  *
  **/
 public class Byte3 {

graphics/java/android/renderscript/Byte4.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs byte4 type back to java applications.
+ * Class for exposing the native Renderscript byte4 type back to the Android system.
  *
  **/
 public class Byte4 {

graphics/java/android/renderscript/Element.java

@@ -20,25 +20,26 @@ import java.lang.reflect.Field;
 import android.util.Log;
 
 /**
- * Element is the basic data type of RenderScript.  An element can be of 2
+ * <p>The most basic data type. An element represents one cell of a memory allocation.
- * forms.  Basic elements contain a single component of data.  This can be of
+ * Element is the basic data type of Renderscript. An element can be of two forms: Basic elements or Complex forms. 
- * any of the legal RS types.  Examples of basic element types.
+ * Examples of basic elements are:</p>
- * Single float value
+ * <ul>
- * 4 element float vector
+ *  <li>Single float value</li>
- * single RGB-565 color
+ *  <li>4 element float vector</li>
- * single unsigned int 16
+ *  <li>single RGB-565 color</li>
- *
+ *  <li>single unsigned int 16</li>
- * Complex elements will contain a list of sub-elements and names.  This in
+ * </ul>
- * effect represents a structure of data.  The fields can be accessed by name
+ * <p>Complex elements contain a list of sub-elements and names that 
- * from a script or shader.  The memory layout is defined and ordered.  Data
+ * represents a structure of data. The fields can be accessed by name
- * alignment is determinied by the most basic primitive type.  i.e. a float4
+ * 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.
+ * with each component aligned as necessary. No re-ordering will be done.</p>
  *
- * The primary source of elements will be from scripts.  A script that exports a
+ * <p>The primary source of elements are from scripts. A script that exports a
- * bind point for a data structure will generate a RS element to represent the
+ * bind point for a data structure generates a Renderscript element to represent the
- * data exported by the script.
+ * data exported by the script. The other common source of elements is from bitmap formats.</p>
  **/
 public class Element extends BaseObj {
     int mSize;

graphics/java/android/renderscript/FieldPacker.java

@@ -18,8 +18,8 @@ package android.renderscript;
 
 
 /**
- * Utility class for packing arguments and structures from java objects to rs
+ * Utility class for packing arguments and structures from Android system objects to
- * objects.
+ * Renderscript objects.
  *
  **/
 public class FieldPacker {

graphics/java/android/renderscript/FileA3D.java

@@ -28,9 +28,9 @@ import android.util.Log;
 import android.util.TypedValue;
 
 /**
- * FileA3D allows users to load renderscript objects from files
+ * FileA3D allows users to load Renderscript objects from files
  * or resources stored on disk. It could be used to load items
- * such as 3d geometry data converted a renderscript format from
+ * such as 3D geometry data converted to a Renderscript format from
  * content creation tools. Currently only meshes are supported
  * in FileA3D.
  *
@@ -66,9 +66,9 @@ public class FileA3D extends BaseObj {
     }
 
     /**
-    * IndexEntry contains information about one of the renderscript
+    * IndexEntry contains information about one of the Renderscript
     * objects inside the file's index. It could be used to query the
-    * object's type and name and load the object itself if
+    * object's type and also name and load the object itself if
     * necessary.
     */
     public static class IndexEntry {

graphics/java/android/renderscript/Float2.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs float2 type back to java applications.
+ * Class for exposing the native Renderscript float2 type back to the Android system.
  *
  **/
 public class Float2 {

graphics/java/android/renderscript/Float3.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs float3 type back to java applications.
+ * Class for exposing the native Renderscript float2 type back to the Android system.
  *
  **/
 public class Float3 {

graphics/java/android/renderscript/Float4.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs float4 type back to java applications.
+ * Class for exposing the native Renderscript float2 type back to the Android system.
  *
  **/
 public class Float4 {

graphics/java/android/renderscript/Font.java

@@ -30,7 +30,20 @@ import android.util.Log;
 import android.util.TypedValue;
 
 /**
- *
+ * <p>This class gives users a simple way to draw hardware accelerated text. 
+ * Internally, the glyphs are rendered using the Freetype library and an internal cache of
+ * rendered glyph bitmaps is maintained. Each font object represents a combination of a typeface,
+ * and point size. You can create multiple font objects to represent styles such as bold or italic text,
+ * faces, and different font sizes. During creation, the Android system quieries device's screen DPI to
+ * ensure proper sizing across multiple device configurations.</p>
+ * <p>Fonts are rendered using screen-space positions and no state setup beyond binding a
+ * font to the Renderscript is required. A note of caution on performance, though the state changes
+ * are transparent to the user, they do happen internally, and it is more efficient to
+ * render large batches of text in sequence. It is also more efficient to render multiple
+ * characters at once instead of one by one to improve draw call batching.</p>
+ * <p>Font color and transparency are not part of the font object and you can freely modify
+ * them in the script to suit the user's rendering needs. Font colors work as a state machine. 
+ * Every new call to draw text uses the last color set in the script.</p>
  **/
 public class Font extends BaseObj {
 

graphics/java/android/renderscript/Int2.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs int2 type back to java applications.
+ * Class for exposing the native Renderscript int2 type back to the Android system.
  *
  **/
 public class Int2 {

graphics/java/android/renderscript/Int3.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs int3 type back to java applications.
+ * Class for exposing the native Renderscript int3 type back to the Android system.
  *
  **/
 public class Int3 {

graphics/java/android/renderscript/Int4.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs int4 type back to java applications.
+ * Class for exposing the native Renderscript int4 type back to the Android system.
  *
  **/
 public class Int4 {

graphics/java/android/renderscript/Long2.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- *
+ * Class for exposing the native Renderscript long2 type back to the Android system.
  **/
 public class Long2 {
     public Long2() {

graphics/java/android/renderscript/Long3.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- *
+ * Class for exposing the native Renderscript long3 type back to the Android system.
  **/
 public class Long3 {
     public Long3() {

graphics/java/android/renderscript/Long4.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- *
+ * Class for exposing the native Renderscript long4 type back to the Android system.
  **/
 public class Long4 {
     public Long4() {

graphics/java/android/renderscript/Matrix2f.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs_matrix2x2 type back to java applications.
+ * Class for exposing the native Renderscript rs_matrix2x2 type back to the Android system.
  *
  **/
 public class Matrix2f {

graphics/java/android/renderscript/Matrix3f.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs_matrix3x3 type back to java applications.
+ * Class for exposing the native Renderscript rs_matrix3x3 type back to the Android system.
  *
  **/
 public class Matrix3f {

graphics/java/android/renderscript/Matrix4f.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs_matrix4x4 type back to java applications.
+ * Class for exposing the native Renderscript rs_matrix4x4 type back to the Android system.
  *
  **/
 public class Matrix4f {

graphics/java/android/renderscript/Mesh.java

@@ -22,22 +22,21 @@ import android.util.Config;
 import android.util.Log;
 
 /**
- * Mesh class is a container for geometric data displayed in
+ * <p>This class is a container for geometric data displayed with
- * renderscript.
+ * Renderscript. Internally, a mesh is a collection of allocations that
- *
- * Internally, mesh is a collection of allocations that
  * represent vertex data (positions, normals, texture
- * coordinates) and index data such as triangles and lines.
+ * coordinates) and index data such as triangles and lines. </p>
- *
+ * <p>
- * Vertex data could either be interlieved within one
+ * Vertex data could either be interleaved within one
- * allocation, provided separately as multiple allocation
+ * allocation that is provided separately, as multiple allocation
- * objects or done as a combination of the above. When a
+ * objects, or done as a combination of both. When a
  * vertex channel name matches an input in the vertex program,
- * renderscript will automatically connect the two together.
+ * Renderscript automatically connects the two together.
- *
+ * </p>
- *  Parts of the mesh could be rendered with either explicit
+ * <p>
+ *  Parts of the mesh can be rendered with either explicit
  *  index sets or primitive types.
- *
+ * </p>
  **/
 public class Mesh extends BaseObj {
 
@@ -170,9 +169,9 @@ public class Mesh extends BaseObj {
     }
 
     /**
-    * Mesh builder object. It starts empty and requires the user to
+    * Mesh builder object. It starts empty and requires you to
     * add the types necessary to create vertex and index
-    * allocations
+    * allocations.
     *
     */
     public static class Builder {

graphics/java/android/renderscript/ProgramFragment.java

@@ -22,9 +22,19 @@ import android.util.Log;
 
 
 /**
- * ProgramFragment, also know as a fragment shader, describes a
+ * <p>The Renderscript fragment program, also known as fragment shader is responsible
- * stage in the graphics pipeline responsible for manipulating
+ * for manipulating pixel data in a user defined way. It's constructed from a GLSL
- * pixel data in a user-defined way.
+ * shader string containing the program body, textures inputs, and a Type object
+ * that describes the constants used by the program. Similar to the vertex programs,
+ * when an allocation with constant input values is bound to the shader, its values
+ * are sent to the graphics program automatically.</p>
+ * <p> The values inside the allocation are not explicitly tracked. If they change between two draw
+ * calls using the same program object, the runtime needs to be notified of that
+ * change by calling rsgAllocationSyncAll so it could send the new values to hardware.
+ * Communication between the vertex and fragment programs is handled internally in the
+ * GLSL code. For example, if the fragment program is expecting a varying input called
+ * varTex0, the GLSL code inside the program vertex must provide it.
+ * </p>
  *
  **/
 public class ProgramFragment extends Program {

graphics/java/android/renderscript/ProgramFragmentFixedFunction.java

@@ -22,13 +22,11 @@ import android.util.Log;
 
 
 /**
- * ProgramFragmentFixedFunction is a helper class that provides
+ * <p>ProgramFragmentFixedFunction is a helper class that provides
  * a way to make a simple fragment shader without writing any
- * GLSL code.
+ * GLSL code. This class allows for display of constant color, interpolated
- *
+ * color from the vertex shader, or combinations of the both
- * This class allows for display of constant color, interpolated
+ * blended with results of up to two texture lookups.</p
- * color from vertex shader, or combinations of the above
- * blended with results of up to two texture lookups.
  *
  **/
 public class ProgramFragmentFixedFunction extends ProgramFragment {

graphics/java/android/renderscript/ProgramRaster.java

@@ -22,7 +22,8 @@ import android.util.Log;
 
 
 /**
- *
+ * Program raster is primarily used to specify whether point sprites are enabled and to control
+ * the culling mode. By default, back faces are culled.
  **/
 public class ProgramRaster extends BaseObj {
 

graphics/java/android/renderscript/ProgramStore.java

@@ -22,16 +22,17 @@ import android.util.Log;
 
 
 /**
- * ProgarmStore contains a set of parameters that control how
+ * <p>ProgramStore contains a set of parameters that control how
  * the graphics hardware handles writes to the framebuffer.
- *
+ * It could be used to:</p>
- * It could be used to:
+ * <ul>
- *   - enable/diable depth testing
+ *   <li>enable/disable depth testing</li>
- *   - specify wheather depth writes are performed
+ *   <li>specify wheather depth writes are performed</li>
- *   - setup various blending modes for use in effects like
+ *   <li>setup various blending modes for use in effects like
- *     transparency
+ *     transparency</li>
- *   - define write masks for color components written into the
+ *   <li>define write masks for color components written into the
- *     framebuffer
+ *     framebuffer</li>
+ *  </ul>
  *
  **/
 public class ProgramStore extends BaseObj {

graphics/java/android/renderscript/ProgramVertex.java

@@ -14,6 +14,27 @@
  * limitations under the License.
  */
 
+ /**
+ * <p>The Renderscript vertex program, also known as a vertex shader, describes a stage in
+ * the graphics pipeline responsible for manipulating geometric data in a user-defined way.
+ * The object is constructed by providing the Renderscript system with the following data:</p>
+ * <ul>
+ *   <li>Element describing its varying inputs or attributes</li>
+ *   <li>GLSL shader string that defines the body of the program</li>
+ *   <li>a Type that describes the layout of an Allocation containing constant or uniform inputs</li>
+ * </ul>
+ *
+ * <p>Once the program is created, you bind it to the graphics context, RenderScriptGL, and it will be used for
+ * all subsequent draw calls until you bind a new program. If the program has constant inputs,
+ * the user needs to bind an allocation containing those inputs. The allocation's type must match
+ * the one provided during creation. The Renderscript library then does all the necessary plumbing
+ * to send those constants to the graphics hardware. Varying inputs to the shader, such as position, normal,
+ * and texture coordinates are matched by name between the input Element and the Mesh object being drawn.
+ * The signatures don't have to be exact or in any strict order. As long as the input name in the shader
+ * matches a channel name and size available on the mesh, the runtime takes care of connecting the
+ * two. Unlike OpenGL, there is no need to link the vertex and fragment programs.</p>
+ *
+ **/
 package android.renderscript;
 
 

graphics/java/android/renderscript/RSSurfaceView.java

@@ -30,7 +30,7 @@ import android.view.SurfaceHolder;
 import android.view.SurfaceView;
 
 /**
- *
+ * The Surface View for a graphics renderscript (RenderScriptGL) to draw on. 
  */
 public class RSSurfaceView extends SurfaceView implements SurfaceHolder.Callback {
     private SurfaceHolder mSurfaceHolder;

graphics/java/android/renderscript/Sampler.java

@@ -29,8 +29,8 @@ import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
 
 /**
- * Sampler object which defines how data is extracted from textures.  Samplers
+ * Sampler object which defines how data is extracted from textures. Samplers
- * are attached to Program objects (currently only fragment) when those objects
+ * are attached to Program objects (currently only ProgramFragment) when those objects
  * need to access texture data.
  **/
 public class Sampler extends BaseObj {

graphics/java/android/renderscript/Short2.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs short2 type back to java applications.
+ * Class for exposing the native Renderscript Short2 type back to the Android system.
  *
  **/
 public class Short2 {

graphics/java/android/renderscript/Short3.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs short3 type back to java applications.
+ * Class for exposing the native Renderscript short3 type back to the Android system.
  *
  **/
 public class Short3 {

graphics/java/android/renderscript/Short4.java

@@ -21,7 +21,7 @@ import android.util.Log;
 
 
 /**
- * Class for exposing the rs short4 type back to java applications.
+ * Class for exposing the native Renderscript short4 type back to the Android system.
  *
  **/
 public class Short4 {

graphics/java/android/renderscript/Type.java

@@ -21,19 +21,19 @@ import java.lang.reflect.Field;
 import android.util.Log;
 
 /**
- * Type is an allocation template.  It consists of an Element and one or more
+ * <p>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
+ * dimensions. It describes only the layout of memory but does not allocate any
- * storage for the data thus described.
+ * storage for the data that is described.</p>
  *
- * A Type consists of several dimensions.  Those are X, Y, Z, LOD (level of
+ * <p>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.
+ * x=10, y=0 would be considered 1 dimensional.</p>
  *
- * The LOD and Faces dimensions are booleans to indicate present or not present.
+ * <p>The LOD and Faces dimensions are booleans to indicate present or not present.</p>
  *
  **/
 public class Type extends BaseObj {

graphics/java/android/renderscript/package.html

@@ -0,0 +1,85 @@
+<HTML>
+<BODY>
+<p>The Renderscript rendering and computational APIs offer a low-level, high performance means of
+carrying out mathematical calculations and 3D graphics rendering. An example of Renderscript in
+applications include the 3D carousel view that is present in Android 3.0 applications such as the
+Books and YouTube applications. This API is intended for developers who are comfortable working with
+native code and want to maximize their performance critical applications.</p>
+
+<p>Renderscript adopts a control and slave architecture where the low-level native code is controlled by the
+higher level Android system that runs in the virtual machine (VM). The VM code handles resource
+allocation and lifecycle management of the Renderscript enabled application and calls the Renderscript
+code through high level entry points. The Android build tools generate these entry points through reflection on
+the native Renderscript code, which you write in C (C99 standard). The Renderscript code
+does the intensive computation and returns the result back to the Android VM.</p>
+
+<p>You can find the Renderscript native
+APIs in the <code>&lt;sdk_root&gt;/platforms/android-3.0/renderscript</code> directory. 
+The Android system APIs are broken into a few main groups:</p>
+
+<h4>Core</h4>
+<p>These classes are used internally by the system for memory allocation. They are used by the classes that
+are generated by the build tools:</p>
+<ul>
+  <li>Allocation</li>
+  <li>Element</li>
+  <li>Type</li>
+  <li>Script</li>
+</ul>
+
+
+<h4>Data Types</h4>
+<p>These data types are used by the classes that are generated
+by the build tools. They are the reflected counterparts of the native data types that
+are defined by the native Renderscript APIs and used by your Renderscript code. The
+classes include:</p>
+<ul>
+  <li>Byte2, Byte3, and Byte4</li>
+  <li>Float2, Float3, Float4</li>
+  <li>Int2, Int3, Int4</li>
+  <li>Long2, Long3, Long4</li>  
+  <li>Matrix2f, Matrix3f, Matrix4f</li>
+  <li>Short2, Short3, Short4</li>
+</ul>
+
+<p>For example, if you declared the following struct in your .rs Renderscript file:</p>
+
+<pre>struct Hello { float3 position; rs_matrix4x4 transform; }</pre>
+
+<p>The build tools generate a class through reflection that looks like the following:</p>
+<pre>
+class Hello {
+    static public class Item {
+        Float4 position;
+        Matrix4f transform;
+    }
+Element createElement(RenderScript rs) {
+        Element.Builder eb = new Element.Builder(rs);
+        eb.add(Element.F32_3(rs), "position");
+        eb.add(Element.MATRIX_4X4(rs), "transform");
+        return eb.create();
+    }
+}
+</pre>
+
+<h4>Graphics</h4>
+<p>These classes are specific to graphics Renderscripts and support a typical rendering
+pipeline.</p>
+<ul>
+<li>Mesh</li>
+<li>ProgramFragment</li>
+<li>ProgramRaster</li>
+<li>ProgramStore</li>
+<li>ProgramVertex</li>
+<li>RSSurfaceView</li>
+<li>Sampler</li>
+</ul>
+
+</p>
+<p>
+For information on how to create an application that uses Renderscript, and also the
+see <a href="../../../guide/topics/graphics/renderscript.html">3D with
+Renderscript</a> dev guide. 
+</p>
+</BODY>
+</HTML>