am 379641a7: am ea45ab6f: Merge "Improve RS documentation." into jb-mr2-dev

* commit '379641a7ef09e1d7fab34d3027c5809fb2bc21ad':
  Improve RS documentation.

1 files changed, 295 insertions, 272 deletions

diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java
index e1b8c6c92e86..362b58637606 100644
--- a/graphics/java/android/renderscript/Allocation.java
+++ b/graphics/java/android/renderscript/Allocation.java
@@ -31,46 +31,29 @@ import android.graphics.Canvas;
 import android.os.Trace;
 
 /**
- * <p>
- * 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>
+ * <p> This class provides the primary method through which data is passed to
+ * and from RenderScript kernels.  An Allocation provides the backing store for
+ * a given {@link android.renderscript.Type}.  </p>
  *
- * <p>Allocations are the primary way data moves into and out of scripts. Memory is user
- * synchronized and it's possible for allocations to exist in multiple memory spaces
- * concurrently. Currently those spaces are:</p>
- * <ul>
- * <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>
+ * <p>An Allocation also contains a set of usage flags that denote how the
+ * Allocation could be used. For example, an Allocation may have usage flags
+ * specifying that it can be used from a script as well as input to a {@link
+ * android.renderscript.Sampler}. A developer must synchronize across these
+ * different usages using {@link android.renderscript.Allocation#syncAll} in
+ * order to ensure that different users of the Allocation have a consistent view
+ * of memory. For example, in the case where an Allocation is used as the output
+ * of one kernel and as Sampler input in a later kernel, a developer must call
+ * {@link #syncAll syncAll(Allocation.USAGE_SCRIPT)} prior to launching the
+ * second kernel to ensure correctness.
  *
- * <p>Allocation data is uploaded in one of two primary ways. For simple
- * arrays there are copyFrom() functions that take an array from the control code and
- * copy it to the slave memory store. Both type checked and unchecked copies are provided.
- * The unchecked variants exist to allow apps to copy over arrays of structures from a
- * control language that does not support structures.</p>
+ * <p>An Allocation can be populated with the {@link #copyFrom} routines. For
+ * more complex Element types, the {@link #copyFromUnchecked} methods can be
+ * used to copy from byte arrays or similar constructs.</p>
  *
  * <div class="special reference">
  * <h3>Developer Guides</h3>
- * <p>For more information about creating an application that uses Renderscript, read the
- * <a href="{@docRoot}guide/topics/renderscript/index.html">Renderscript</a> developer guide.</p>
+ * <p>For more information about creating an application that uses RenderScript, read the
+ * <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer guide.</p>
  * </div>
  **/
 public class Allocation extends BaseObj {
@@ -98,97 +81,102 @@ public class Allocation extends BaseObj {
             new HashMap<Integer, Allocation>();
     IoInputNotifier mBufferNotifier;
 
-
     /**
-     * The usage of the allocation.  These signal to renderscript
-     * where to place the allocation in memory.
+     * The usage of the Allocation.  These signal to RenderScript where to place
+     * the Allocation in memory.
      *
-     * SCRIPT The allocation will be bound to and accessed by
-     * scripts.
+     */
+
+    /**
+     * The Allocation will be bound to and accessed by scripts.
      */
     public static final int USAGE_SCRIPT = 0x0001;
 
     /**
-     * GRAPHICS_TEXTURE The allocation will be used as a texture
-     * source by one or more graphics programs.
+     * The Allocation will be used as a texture source by one or more graphics
+     * programs.
      *
      */
     public static final int USAGE_GRAPHICS_TEXTURE = 0x0002;
 
     /**
-     * GRAPHICS_VERTEX The allocation will be used as a graphics
-     * mesh.
+     * The Allocation will be used as a graphics mesh.
+     *
+     * This was deprecated in API level 16.
      *
      */
     public static final int USAGE_GRAPHICS_VERTEX = 0x0004;
 
 
     /**
-     * GRAPHICS_CONSTANTS The allocation will be used as the source
-     * of shader constants by one or more programs.
+     * The Allocation will be used as the source of shader constants by one or
+     * more programs.
+     *
+     * This was deprecated in API level 16.
      *
      */
     public static final int USAGE_GRAPHICS_CONSTANTS = 0x0008;
 
     /**
-     * USAGE_GRAPHICS_RENDER_TARGET The allocation will be used as a
-     * target for offscreen rendering
+     * The Allocation will be used as a target for offscreen rendering
+     *
+     * This was deprecated in API level 16.
      *
      */
     public static final int USAGE_GRAPHICS_RENDER_TARGET = 0x0010;
 
     /**
-     * USAGE_IO_INPUT The allocation will be used as SurfaceTexture
-     * consumer.  This usage will cause the allocation to be created
-     * read only.
+     * The Allocation will be used as a {@link android.graphics.SurfaceTexture}
+     * consumer.  This usage will cause the Allocation to be created as
+     * read-only.
      *
      */
     public static final int USAGE_IO_INPUT = 0x0020;
 
     /**
-     * USAGE_IO_OUTPUT The allocation will be used as a
-     * SurfaceTexture producer.  The dimensions and format of the
-     * SurfaceTexture will be forced to those of the allocation.
+     * The Allocation will be used as a {@link android.graphics.SurfaceTexture}
+     * producer.  The dimensions and format of the {@link
+     * android.graphics.SurfaceTexture} will be forced to those of the
+     * Allocation.
      *
      */
     public static final int USAGE_IO_OUTPUT = 0x0040;
 
     /**
-     * USAGE_SHARED The allocation's backing store will be inherited
-     * from another object (usually a Bitmap); calling appropriate
-     * copy methods will be significantly faster than if the entire
-     * allocation were copied every time.
+     * The Allocation's backing store will be inherited from another object
+     * (usually a {@link android.graphics.Bitmap}); copying to or from the
+     * original source Bitmap will cause a synchronization rather than a full
+     * copy.  {@link #syncAll} may also be used to synchronize the Allocation
+     * and the source Bitmap.
      *
-     * This is set by default for allocations created with
-     * CreateFromBitmap(RenderScript, Bitmap) in API version 18 and
-     * higher.
+     * <p>This is set by default for allocations created with {@link
+     * #createFromBitmap} in API version 18 and higher.</p>
      *
      */
     public static final int USAGE_SHARED = 0x0080;
 
     /**
-     * Controls mipmap behavior when using the bitmap creation and
-     * update functions.
+     * Controls mipmap behavior when using the bitmap creation and update
+     * functions.
      */
     public enum MipmapControl {
         /**
-         * No mipmaps will be generated and the type generated from the
-         * incoming bitmap will not contain additional LODs.
+         * No mipmaps will be generated and the type generated from the incoming
+         * bitmap will not contain additional LODs.
          */
         MIPMAP_NONE(0),
 
         /**
-         * A Full mipmap chain will be created in script memory.  The
-         * type of the allocation will contain a full mipmap chain.  On
-         * upload to graphics the full chain will be transfered.
+         * A full mipmap chain will be created in script memory.  The Type of
+         * the Allocation will contain a full mipmap chain.  On upload, the full
+         * chain will be transferred.
          */
         MIPMAP_FULL(1),
 
         /**
-         * The type of the allocation will be the same as MIPMAP_NONE.
-         * It will not contain mipmaps.  On upload to graphics the
-         * graphics copy of the allocation data will contain a full
-         * mipmap chain generated from the top level in script memory.
+         * The Type of the Allocation will be the same as MIPMAP_NONE.  It will
+         * not contain mipmaps.  On upload, the allocation data will contain a
+         * full mipmap chain generated from the top level in script memory.
          */
         MIPMAP_ON_SYNC_TO_TEXTURE(2);
 
@@ -208,10 +196,10 @@ public class Allocation extends BaseObj {
 
 
    /**
-     * Get the element of the type of the Allocation.
+     * Get the {@link android.renderscript.Element} of the {@link
+     * android.renderscript.Type} of the Allocation.
      *
-     * @return Element that describes the structure of data in the
-     *         allocation
+     * @return Element
      *
      */
     public Element getElement() {
@@ -221,8 +209,7 @@ public class Allocation extends BaseObj {
     /**
      * Get the usage flags of the Allocation.
      *
-     * @return usage flags associated with the allocation. e.g.
-     *         script, texture, etc.
+     * @return usage this Allocation's set of the USAGE_* flags OR'd together
      *
      */
     public int getUsage() {
@@ -351,7 +338,7 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Get the type of the Allocation.
+     * Get the {@link android.renderscript.Type} of the Allocation.
      *
      * @return Type
      *
@@ -361,8 +348,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Propagate changes from one usage of the allocation to the
-     * remaining usages of the allocation.
+     * Propagate changes from one usage of the Allocation to the
+     * other usages of the Allocation.
      *
      */
     public void syncAll(int srcLocation) {
@@ -391,8 +378,10 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Send a buffer to the output stream.  The contents of the
-     * Allocation will be undefined after this operation.
+     * Send a buffer to the output stream.  The contents of the Allocation will
+     * be undefined after this operation. This operation is only valid if {@link
+     * #USAGE_IO_OUTPUT} is set on the Allocation.
+     *
      *
      */
     public void ioSend() {
@@ -415,7 +404,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Receive the latest input into the Allocation.
+     * Receive the latest input into the Allocation. This operation
+     * is only valid if {@link #USAGE_IO_INPUT} is set on the Allocation.
      *
      */
     public void ioReceive() {
@@ -430,7 +420,7 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an array of RS objects to the allocation.
+     * Copy an array of RS objects to the Allocation.
      *
      * @param d Source array.
      */
@@ -506,9 +496,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is not type
-     * checked which allows an application to fill in structured
-     * data from an array.
+     * Copy into this Allocation from an array. This method does not guarantee
+     * that the Allocation is compatible with the input buffer; it copies memory
+     * without reinterpretation.
      *
      * @param d the source data array
      */
@@ -526,9 +516,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is not type
-     * checked which allows an application to fill in structured
-     * data from an array.
+     * Copy into this Allocation from an array. This method does not guarantee
+     * that the Allocation is compatible with the input buffer; it copies memory
+     * without reinterpretation.
      *
      * @param d the source data array
      */
@@ -546,9 +536,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is not type
-     * checked which allows an application to fill in structured
-     * data from an array.
+     * Copy into this Allocation from an array. This method does not guarantee
+     * that the Allocation is compatible with the input buffer; it copies memory
+     * without reinterpretation.
      *
      * @param d the source data array
      */
@@ -566,9 +556,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is not type
-     * checked which allows an application to fill in structured
-     * data from an array.
+     * Copy into this Allocation from an array. This method does not guarantee
+     * that the Allocation is compatible with the input buffer; it copies memory
+     * without reinterpretation.
      *
      * @param d the source data array
      */
@@ -587,9 +577,9 @@ public class Allocation extends BaseObj {
 
 
     /**
-     * Copy an allocation from an array.  This variant is type
-     * checked and will generate exceptions if the Allocation type
-     * is not a 32 bit integer type.
+     * Copy into this Allocation from an array.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.renderscript.Element} is not a 32 bit integer type.
      *
      * @param d the source data array
      */
@@ -607,9 +597,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is type
-     * checked and will generate exceptions if the Allocation type
-     * is not a 16 bit integer type.
+     * Copy into this Allocation from an array.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.renderscript.Element} is not a 16 bit integer type.
      *
      * @param d the source data array
      */
@@ -627,9 +617,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is type
-     * checked and will generate exceptions if the Allocation type
-     * is not a 8 bit integer type.
+     * Copy into this Allocation from an array.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.renderscript.Element} is not an 8 bit integer type.
      *
      * @param d the source data array
      */
@@ -647,9 +637,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an array.  This variant is type
-     * checked and will generate exceptions if the Allocation type
-     * is not a 32 bit float type.
+     * Copy into this Allocation from an array.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.renderscript.Element} is not a 32 bit float type.
      *
      * @param d the source data array
      */
@@ -667,8 +657,15 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from a bitmap.  The height, width, and
-     * format of the bitmap must match the existing allocation.
+     * Copy into an Allocation from a {@link android.graphics.Bitmap}.  The
+     * height, width, and format of the bitmap must match the existing
+     * allocation.
+     *
+     * <p>If the {@link android.graphics.Bitmap} is the same as the {@link
+     * android.graphics.Bitmap} used to create the Allocation with {@link
+     * #createFromBitmap} and {@link #USAGE_SHARED} is set on the Allocation,
+     * this will synchronize the Allocation with the latest data from the {@link
+     * android.graphics.Bitmap}, potentially avoiding the actual copy.</p>
      *
      * @param b the source bitmap
      */
@@ -689,7 +686,7 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an allocation from an allocation.  The types of both allocations
+     * Copy an Allocation from an Allocation.  The types of both allocations
      * must be identical.
      *
      * @param a the source allocation
@@ -705,8 +702,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * This is only intended to be used by auto-generate code reflected from the
-     * renderscript script files.
+     * This is only intended to be used by auto-generated code reflected from
+     * the RenderScript script files and should not be used by developers.
      *
      * @param xoff
      * @param fp
@@ -725,8 +722,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * This is only intended to be used by auto-generate code reflected from the
-     * renderscript script files.
+     * This is only intended to be used by auto-generated code reflected from
+     * the RenderScript script files.
      *
      * @param xoff
      * @param component_number
@@ -772,23 +769,22 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Generate a mipmap chain.  Requires the type of the allocation
-     * include mipmaps.
+     * Generate a mipmap chain. This is only valid if the Type of the Allocation
+     * includes mipmaps.
      *
-     * This function will generate a complete set of mipmaps from
-     * the top level lod and place them into the script memoryspace.
+     * <p>This function will generate a complete set of mipmaps from the top
+     * level LOD and place them into the script memory space.</p>
      *
-     * If the allocation is also using other memory spaces a
-     * followup sync will be required.
+     * <p>If the Allocation is also using other memory spaces, a call to {@link
+     * #syncAll syncAll(Allocation.USAGE_SCRIPT)} is required.</p>
      */
     public void generateMipmaps() {
         mRS.nAllocationGenerateMipmaps(getID(mRS));
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * not type checked which allows an application to fill in
-     * structured data from an array.
+     * Copy an array into part of this Allocation.  This method does not
+     * guarantee that the Allocation is compatible with the input buffer.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -803,9 +799,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * not type checked which allows an application to fill in
-     * structured data from an array.
+     * Copy an array into part of this Allocation.  This method does not
+     * guarantee that the Allocation is compatible with the input buffer.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -820,9 +815,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * not type checked which allows an application to fill in
-     * structured data from an array.
+     * Copy an array into part of this Allocation.  This method does not
+     * guarantee that the Allocation is compatible with the input buffer.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -837,9 +831,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * not type checked which allows an application to fill in
-     * structured data from an array.
+     * Copy an array into part of this Allocation.  This method does not
+     * guarantee that the Allocation is compatible with the input buffer.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -854,9 +847,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * type checked and will generate exceptions if the Allocation
-     * type is not a 32 bit integer type.
+     * Copy an array into part of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation type is not a 32 bit
+     * integer type.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -870,9 +863,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * type checked and will generate exceptions if the Allocation
-     * type is not a 16 bit integer type.
+     * Copy an array into part of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation type is not a 16 bit
+     * integer type.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -886,9 +879,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * type checked and will generate exceptions if the Allocation
-     * type is not a 8 bit integer type.
+     * Copy an array into part of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation type is not an 8 bit
+     * integer type.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -902,9 +895,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of an allocation from an array.  This variant is
-     * type checked and will generate exceptions if the Allocation
-     * type is not a 32 bit float type.
+     * Copy an array into part of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation type is not a 32 bit float
+     * type.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -917,7 +910,7 @@ public class Allocation extends BaseObj {
         Trace.traceEnd(RenderScript.TRACE_TAG);
     }
      /**
-     * Copy part of an allocation from another allocation.
+     * Copy part of an Allocation into this Allocation.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
@@ -987,14 +980,14 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy a rectangular region from the array into the allocation.
-     * The incoming array is assumed to be tightly packed.
+     * Copy from an array into a rectangular region in this Allocation.  The
+     * array is assumed to be tightly packed.
      *
-     * @param xoff X offset of the region to update
-     * @param yoff Y offset of the region to update
-     * @param w Width of the incoming region to update
-     * @param h Height of the incoming region to update
-     * @param data to be placed into the allocation
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param data to be placed into the Allocation
      */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h, byte[] data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
@@ -1003,6 +996,16 @@ public class Allocation extends BaseObj {
         Trace.traceEnd(RenderScript.TRACE_TAG);
     }
 
+    /**
+     * Copy from an array into a rectangular region in this Allocation.  The
+     * array is assumed to be tightly packed.
+     *
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param data to be placed into the Allocation
+     */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h, short[] data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
         validateIsInt16();
@@ -1010,6 +1013,16 @@ public class Allocation extends BaseObj {
         Trace.traceEnd(RenderScript.TRACE_TAG);
     }
 
+    /**
+     * Copy from an array into a rectangular region in this Allocation.  The
+     * array is assumed to be tightly packed.
+     *
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param data to be placed into the Allocation
+     */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h, int[] data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
         validateIsInt32();
@@ -1017,6 +1030,16 @@ public class Allocation extends BaseObj {
         Trace.traceEnd(RenderScript.TRACE_TAG);
     }
 
+    /**
+     * Copy from an array into a rectangular region in this Allocation.  The
+     * array is assumed to be tightly packed.
+     *
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param data to be placed into the Allocation
+     */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h, float[] data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
         validateIsFloat32();
@@ -1025,16 +1048,16 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy a rectangular region into the allocation from another
-     * allocation.
+     * Copy a rectangular region from an Allocation into a rectangular region in
+     * this Allocation.
      *
-     * @param xoff X offset of the region to update.
-     * @param yoff Y offset of the region to update.
-     * @param w Width of the incoming region to update.
-     * @param h Height of the incoming region to update.
-     * @param data source allocation.
-     * @param dataXoff X offset in data of the region to update.
-     * @param dataYoff Y offset in data of the region to update.
+     * @param xoff X offset of the region in this Allocation
+     * @param yoff Y offset of the region in this Allocation
+     * @param w Width of the region to update.
+     * @param h Height of the region to update.
+     * @param data source Allocation.
+     * @param dataXoff X offset in source Allocation
+     * @param dataYoff Y offset in source Allocation
      */
     public void copy2DRangeFrom(int xoff, int yoff, int w, int h,
                                 Allocation data, int dataXoff, int dataYoff) {
@@ -1049,13 +1072,13 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy a bitmap into an allocation.  The height and width of
-     * the update will use the height and width of the incoming
-     * bitmap.
+     * Copy a {@link android.graphics.Bitmap} into an Allocation.  The height
+     * and width of the update will use the height and width of the {@link
+     * android.graphics.Bitmap}.
      *
-     * @param xoff X offset of the region to update
-     * @param yoff Y offset of the region to update
-     * @param data the bitmap to be copied
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param data the Bitmap to be copied
      */
     public void copy2DRangeFrom(int xoff, int yoff, Bitmap data) {
         Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom");
@@ -1138,14 +1161,14 @@ public class Allocation extends BaseObj {
     /**
      * @hide
      * Copy a rectangular region from the array into the allocation.
-     * The incoming array is assumed to be tightly packed.
-     *
-     * @param xoff X offset of the region to update
-     * @param yoff Y offset of the region to update
-     * @param zoff Z offset of the region to update
-     * @param w Width of the incoming region to update
-     * @param h Height of the incoming region to update
-     * @param d Depth of the incoming region to update
+     * The array is assumed to be tightly packed.
+     *
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param zoff Z offset of the region to update in this Allocation
+     * @param w Width of the region to update
+     * @param h Height of the region to update
+     * @param d Depth of the region to update
      * @param data to be placed into the allocation
      */
     public void copy3DRangeFrom(int xoff, int yoff, int zoff, int w, int h, int d, byte[] data) {
@@ -1185,15 +1208,16 @@ public class Allocation extends BaseObj {
      * Copy a rectangular region into the allocation from another
      * allocation.
      *
-     * @param xoff X offset of the region to update.
-     * @param yoff Y offset of the region to update.
-     * @param w Width of the incoming region to update.
-     * @param h Height of the incoming region to update.
-     * @param d Depth of the incoming region to update.
+     * @param xoff X offset of the region to update in this Allocation
+     * @param yoff Y offset of the region to update in this Allocation
+     * @param zoff Z offset of the region to update in this Allocation
+     * @param w Width of the region to update.
+     * @param h Height of the region to update.
+     * @param d Depth of the region to update.
      * @param data source allocation.
-     * @param dataXoff X offset in data of the region to update.
-     * @param dataYoff Y offset in data of the region to update.
-     * @param dataZoff Z offset in data of the region to update
+     * @param dataXoff X offset of the region in the source Allocation
+     * @param dataYoff Y offset of the region in the source Allocation
+     * @param dataZoff Z offset of the region in the source Allocation
      */
     public void copy3DRangeFrom(int xoff, int yoff, int zoff, int w, int h, int d,
                                 Allocation data, int dataXoff, int dataYoff, int dataZoff) {
@@ -1206,8 +1230,8 @@ public class Allocation extends BaseObj {
 
 
     /**
-     * Copy from the Allocation into a Bitmap.  The bitmap must
-     * match the dimensions of the Allocation.
+     * Copy from the Allocation into a {@link android.graphics.Bitmap}.  The
+     * bitmap must match the dimensions of the Allocation.
      *
      * @param b The bitmap to be set from the Allocation.
      */
@@ -1221,9 +1245,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into a byte array.  The array must
-     * be at least as large as the Allocation.  The allocation must
-     * be of an 8 bit elemental type.
+     * Copy from the Allocation into a byte array.  The array must be at least
+     * as large as the Allocation.  The allocation must be of an 8 bit integer
+     * {@link android.renderscript.Element} type.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1236,9 +1260,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into a short array.  The array must
-     * be at least as large as the Allocation.  The allocation must
-     * be of an 16 bit elemental type.
+     * Copy from the Allocation into a short array.  The array must be at least
+     * as large as the Allocation.  The allocation must be of an 16 bit integer
+     * {@link android.renderscript.Element} type.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1251,9 +1275,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into a int array.  The array must be
-     * at least as large as the Allocation.  The allocation must be
-     * of an 32 bit elemental type.
+     * Copy from the Allocation into a int array.  The array must be at least as
+     * large as the Allocation.  The allocation must be of an 32 bit integer
+     * {@link android.renderscript.Element} type.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1266,9 +1290,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into a float array.  The array must
-     * be at least as large as the Allocation.  The allocation must
-     * be of an 32 bit float elemental type.
+     * Copy from the Allocation into a float array.  The array must be at least
+     * as large as the Allocation.  The allocation must be of an 32 bit float
+     * {@link android.renderscript.Element} type.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1281,20 +1305,19 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Resize a 1D allocation.  The contents of the allocation are
-     * preserved.  If new elements are allocated objects are created
-     * with null contents and the new region is otherwise undefined.
+     * Resize a 1D allocation.  The contents of the allocation are preserved.
+     * If new elements are allocated objects are created with null contents and
+     * the new region is otherwise undefined.
      *
-     * If the new region is smaller the references of any objects
-     * outside the new region will be released.
+     * <p>If the new region is smaller the references of any objects outside the
+     * new region will be released.</p>
      *
-     * A new type will be created with the new dimension.
+     * <p>A new type will be created with the new dimension.</p>
      *
      * @param dimX The new size of the allocation.
      *
-     * @deprecated Renderscript objects should be immutable once
-     * created.  The replacement is to create a new allocation and copy the
-     * contents.
+     * @deprecated RenderScript objects should be immutable once created.  The
+     * replacement is to create a new allocation and copy the contents.
      */
     public synchronized void resize(int dimX) {
         if ((mType.getY() > 0)|| (mType.getZ() > 0) || mType.hasFaces() || mType.hasMipmaps()) {
@@ -1318,11 +1341,13 @@ public class Allocation extends BaseObj {
     }
 
     /**
+     * Creates a new Allocation with the given {@link
+     * android.renderscript.Type}, mipmap flag, and usage flags.
      *
-     * @param type renderscript type describing data layout
+     * @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
+     * @param usage bit field specifying how the Allocation is
      *              utilized
      */
     static public Allocation createTyped(RenderScript rs, Type type, MipmapControl mips, int usage) {
@@ -1340,8 +1365,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation with the size specified by
-     * the type and no mipmaps generated by default
+     * Creates an Allocation with the size specified by the type and no mipmaps
+     * generated by default
      *
      * @param rs Context to which the allocation will belong.
      * @param type renderscript type describing data layout
@@ -1355,12 +1380,11 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation for use by the script with
-     * the size specified by the type and no mipmaps generated by
-     * default
+     * Creates an Allocation for use by scripts with a given {@link
+     * android.renderscript.Type} and no mipmaps
      *
-     * @param rs Context to which the allocation will belong.
-     * @param type renderscript type describing data layout
+     * @param rs Context to which the Allocation will belong.
+     * @param type RenderScript Type describing data layout
      *
      * @return allocation
      */
@@ -1369,13 +1393,12 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation with a specified number of
-     * given elements
+     * Creates an Allocation with a specified number of given elements
      *
-     * @param rs Context to which the allocation will belong.
-     * @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
+     * @param rs Context to which the Allocation will belong.
+     * @param e Element to use in the Allocation
+     * @param count the number of Elements in the Allocation
+     * @param usage bit field specifying how the Allocation is
      *              utilized
      *
      * @return allocation
@@ -1397,12 +1420,11 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation with a specified number of
-     * given elements
+     * Creates an Allocation with a specified number of given elements
      *
-     * @param rs Context to which the allocation will belong.
-     * @param e describes what each element of an allocation is
-     * @param count specifies the number of element in the allocation
+     * @param rs Context to which the Allocation will belong.
+     * @param e Element to use in the Allocation
+     * @param count the number of Elements in the Allocation
      *
      * @return allocation
      */
@@ -1438,16 +1460,16 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation from a bitmap
+     * Creates an Allocation from a {@link android.graphics.Bitmap}.
      *
      * @param rs Context to which the allocation will belong.
-     * @param b bitmap source for the allocation data
+     * @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
+     * @return Allocation containing bitmap data
      *
      */
     static public Allocation createFromBitmap(RenderScript rs, Bitmap b,
@@ -1494,9 +1516,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * For allocations used with io operations, returns the handle
-     * onto a raw buffer that is being managed by the screen
-     * compositor.
+     * Returns the handle to a raw buffer that is being managed by the screen
+     * compositor. This operation is only valid for Allocations with {@link
+     * #USAGE_IO_INPUT}.
      *
      * @return Surface object associated with allocation
      *
@@ -1516,7 +1538,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Associate a surface for io output with this allocation
+     * Associate a {@link android.view.Surface} with this Allocation. This
+     * operation is only valid for Allocations with {@link #USAGE_IO_OUTPUT}.
      *
      * @param sur Surface to associate with allocation
      */
@@ -1530,16 +1553,17 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a RenderScript allocation from a bitmap.
+     * Creates an Allocation from a {@link android.graphics.Bitmap}.
      *
-     * With target API version 18 or greater, this allocation will be
-     * created with USAGE_SHARED. With target API version 17 or lower,
-     * this allocation will be created with USAGE_GRAPHICS_TEXTURE.
+     * <p>With target API version 18 or greater, this Allocation will be created
+     * with {@link #USAGE_SHARED}, {@link #USAGE_SCRIPT}, and {@link
+     * #USAGE_GRAPHICS_TEXTURE}. With target API version 17 or lower, this
+     * Allocation will be created with {@link #USAGE_GRAPHICS_TEXTURE}.</p>
      *
      * @param rs Context to which the allocation will belong.
      * @param b bitmap source for the allocation data
      *
-     * @return renderscript allocation containing bitmap data
+     * @return Allocation containing bitmap data
      *
      */
     static public Allocation createFromBitmap(RenderScript rs, Bitmap b) {
@@ -1552,12 +1576,13 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * 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
+     * Creates a cubemap Allocation from a {@link android.graphics.Bitmap}
+     * containing the horizontal list of cube faces. Each face must be a square,
+     * have the same size as all other faces, and have a width that is a power
+     * of 2.
      *
      * @param rs Context to which the allocation will belong.
-     * @param b bitmap with cubemap faces layed out in the following
+     * @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
@@ -1600,10 +1625,10 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * 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
+     * Creates a non-mipmapped cubemap Allocation for use as a graphics texture
+     * from a {@link android.graphics.Bitmap} containing the horizontal list of
+     * cube faces. Each face must be a square, have the same size as all other
+     * faces, and have a width that is a power of 2.
      *
      * @param rs Context to which the allocation will belong.
      * @param b bitmap with cubemap faces layed out in the following
@@ -1619,9 +1644,9 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a cubemap allocation from 6 bitmaps containing
-     * the cube faces. All the faces must be the same size and
-     * power of 2
+     * Creates a cubemap Allocation from 6 {@link android.graphics.Bitmap}
+     * objects containing the cube faces. Each face must be a square, have the
+     * same size as all other faces, and have a width that is a power of 2.
      *
      * @param rs Context to which the allocation will belong.
      * @param xpos cubemap face in the positive x direction
@@ -1686,10 +1711,10 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * 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
+     * Creates a non-mipmapped cubemap Allocation for use as a sampler input
+     * from 6 {@link android.graphics.Bitmap} objects containing the cube
+     * faces. Each face must be a square, have the same size as all other faces,
+     * and have a width that is a power of 2.
      *
      * @param rs Context to which the allocation will belong.
      * @param xpos cubemap face in the positive x direction
@@ -1715,8 +1740,8 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation from the bitmap referenced
-     * by resource id
+     * Creates an Allocation from the Bitmap referenced
+     * by resource ID.
      *
      * @param rs Context to which the allocation will belong.
      * @param res application resources
@@ -1726,7 +1751,7 @@ public class Allocation extends BaseObj {
      * @param usage bit field specifying how the allocation is
      *              utilized
      *
-     * @return renderscript allocation containing resource data
+     * @return Allocation containing resource data
      *
      */
     static public Allocation createFromBitmapResource(RenderScript rs,
@@ -1746,18 +1771,19 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a non-mipmapped renderscript allocation to use as a
-     * graphics texture from the bitmap referenced by resource id
+     * Creates a non-mipmapped Allocation to use as a graphics texture from the
+     * {@link android.graphics.Bitmap} referenced by resource ID.
      *
-     * With target API version 18 or greater, this allocation will be
-     * created with USAGE_SHARED. With target API version 17 or lower,
-     * this allocation will be created with USAGE_GRAPHICS_TEXTURE.
+     * <p>With target API version 18 or greater, this allocation will be created
+     * with {@link #USAGE_SCRIPT} and {@link #USAGE_GRAPHICS_TEXTURE}. With
+     * target API version 17 or lower, this allocation will be created with
+     * {@link #USAGE_GRAPHICS_TEXTURE}.</p>
      *
      * @param rs Context to which the allocation will belong.
      * @param res application resources
      * @param id resource id to load the data from
      *
-     * @return renderscript allocation containing resource data
+     * @return Allocation containing resource data
      *
      */
     static public Allocation createFromBitmapResource(RenderScript rs,
@@ -1774,8 +1800,7 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Creates a renderscript allocation containing string data
-     * encoded in UTF-8 format
+     * Creates an Allocation containing string data encoded in UTF-8 format.
      *
      * @param rs Context to which the allocation will belong.
      * @param str string to create the allocation from
@@ -1802,11 +1827,10 @@ public class Allocation extends BaseObj {
     /**
      * @hide
      *
-     * Interface to handle notification when new buffers are
-     * available via USAGE_IO_INPUT.  An application will receive
-     * one notification when a buffer is available.  Additional
-     * buffers will not trigger new notifications until a buffer is
-     * processed.
+     * Interface to handle notification when new buffers are available via
+     * {@link #USAGE_IO_INPUT}. An application will receive one notification
+     * when a buffer is available. Additional buffers will not trigger new
+     * notifications until a buffer is processed.
      */
     public interface IoInputNotifier {
         public void onBufferAvailable(Allocation a);
@@ -1815,7 +1839,7 @@ public class Allocation extends BaseObj {
     /**
      * @hide
      *
-     * Set a notification handler for USAGE_IO_INPUT
+     * Set a notification handler for {@link #USAGE_IO_INPUT}.
      *
      * @param callback instance of the IoInputNotifier class to be called
      *                 when buffer arrive.
@@ -1839,4 +1863,3 @@ public class Allocation extends BaseObj {
 
 }
 
-