Merge "[RenderScript] Update RenderScript support lib documentation." into nyc-dev

am: 1628eba4ea

* commit '1628eba4eae8b2acac0688a07343263f883a938e':
  [RenderScript] Update RenderScript support lib documentation.

Change-Id: Id0d6bd3fcbcfc85b8a1d79036b9dcdb92dacdfb2

2 files changed, 893 insertions, 125 deletions

diff --git a/support/java/src/android/support/v8/renderscript/Allocation.java b/support/java/src/android/support/v8/renderscript/Allocation.java
index 21a68a42..a2a648f8 100644
--- a/support/java/src/android/support/v8/renderscript/Allocation.java
+++ b/support/java/src/android/support/v8/renderscript/Allocation.java
@@ -16,19 +16,15 @@
 
 package android.support.v8.renderscript;
 
-import java.io.IOException;
-import java.io.InputStream;
-import java.util.concurrent.locks.ReentrantReadWriteLock;
 import java.nio.ByteBuffer;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
 
 import android.content.res.Resources;
-import android.content.res.AssetManager;
 import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
 import android.graphics.Canvas;
-import android.view.Surface;
 import android.util.Log;
-import android.util.TypedValue;
+import android.view.Surface;
 
 /**
  * <p> This class provides the primary method through which data is passed to
@@ -269,13 +265,50 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Enable/Disable AutoPadding for Vec3 Elements.
+     * Specifies the mapping between the Allocation's cells and an array's elements
+     * when data is copied from the Allocation to the array, or vice-versa.
+     *
+     * Only applies to an Allocation whose Element is a vector of length 3 (such as
+     * {@link Element#U8_3} or {@link Element#RGB_888}). Enabling this feature may make
+     * copying data from the Allocation to an array or vice-versa less efficient.
+     *
+     * <p> Vec3 Element cells are stored in an Allocation as Vec4 Element cells with
+     * the same {@link android.support.v8.renderscript.Element.DataType}, with the fourth vector
+     * component treated as padding. When this feature is enabled, only the data components,
+     * i.e. the first 3 vector components of each cell, will be mapped between the array
+     * and the Allocation. When disabled, explicit mapping of the padding components
+     * is required, as described in the following example.
+     *
+     * <p> For example, when copying an integer array to an Allocation of two {@link
+     * Element#I32_3} cells using {@link #copyFrom(int[])}:
+     * <p> When disabled:
+     *     The array must have at least 8 integers, with the first 4 integers copied
+     *     to the first cell of the Allocation, and the next 4 integers copied to
+     *     the second cell. The 4th and 8th integers are mapped as the padding components.
      *
-     * <p> Vec3 Elements, such as {@link Element#U8_3} are treated as Vec4 Elements
-     * with the fourth vector element used as padding. Enabling the AutoPadding feature
-     * will automatically add/remove the padding when you copy to/from an Allocation
-     * with a Vec3 Element.
-     * <p> By default: Disabled.
+     * <p> When enabled:
+     *     The array just needs to have at least 6 integers, with the first 3 integers
+     *     copied to the the first cell as data components, and the next 3 copied to
+     *     the second cell. There is no mapping for the padding components.
+     *
+     * <p> Similarly, when copying a byte array to an Allocation of two {@link
+     * Element#I32_3} cells, using {@link #copyFromUnchecked(int[])}:
+     * <p> When disabled:
+     *     The array must have at least 32 bytes, with the first 16 bytes copied
+     *     to the first cell of the Allocation, and the next 16 bytes copied to
+     *     the second cell. The 13th-16th and 29th-32nd bytes are mapped as padding
+     *     components.
+     *
+     * <p> When enabled:
+     *     The array just needs to have at least 24 bytes, with the first 12 bytes copied
+     *     to the first cell of the Allocation, and the next 12 bytes copied to
+     *     the second cell. There is no mapping for the padding components.
+     *
+     * <p> Similar to copying data to an Allocation from an array, when copying data from an
+     * Allocation to an array, the padding components for Vec3 Element cells will not be
+     * copied/mapped to the array if AutoPadding is enabled.
+     *
+     * <p> Default: Disabled.
      *
      * @param useAutoPadding True: enable AutoPadding; False: disable AutoPadding
      *
@@ -476,11 +509,19 @@ public class Allocation extends BaseObj {
     public void ioSendOutput() {
         ioSend();
     }
-
     /**
      * @hide
-     * Get the ByteBuffer pointing to the raw data associated with Allocation.
-     * Note: The ByteBuffer will be Read-Only for devices before Lollopop (API 21).
+     * Gets or creates a ByteBuffer that contains the raw data of the current Allocation.
+     * <p> If the Allocation is created with USAGE_IO_INPUT, the returned ByteBuffer
+     * would contain the up-to-date data as READ ONLY.
+     * For a 2D or 3D Allocation, the raw data maybe padded so that each row of
+     * the Allocation has certain alignment. The size of each row including padding,
+     * called stride, can be queried using the {@link #getStride()} method.
+     *
+     * Note: Operating on the ByteBuffer of a destroyed Allocation will triger errors.
+     *       The ByteBuffer will be Read-Only for devices before Lollopop (API 21).
+     *
+     * @return ByteBuffer The ByteBuffer associated with raw data pointer of the Allocation.
      */
     public ByteBuffer getByteBuffer() {
         int xBytesSize = mType.getX() * mType.getElement().getBytesSize();
@@ -514,7 +555,14 @@ public class Allocation extends BaseObj {
 
     /**
      * @hide
-     * Get the Stride of raw data associated with this 2D Allocation.
+     * Gets the stride of the Allocation.
+     * For a 2D or 3D Allocation, the raw data maybe padded so that each row of
+     * the Allocation has certain alignment. The size of each row including such
+     * padding is called stride.
+     *
+     * @return the stride. For 1D Allocation, the stride will be the number of
+     *         bytes of this Allocation. For 2D and 3D Allocations, the stride
+     *         will be the stride in X dimension measuring in bytes.
      */
     public long getStride() {
         if (mByteBufferStride ==0) {
@@ -640,7 +688,21 @@ public class Allocation extends BaseObj {
      * that the Allocation is compatible with the input buffer; it copies memory
      * without reinterpretation.
      *
-     * @param array The source data array
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
+     *
+     * @param array The source array
      */
     public void copyFromUnchecked(Object array) {
         copyFromUnchecked(array, validateObjectIsPrimitiveArray(array, false),
@@ -652,7 +714,21 @@ public class Allocation extends BaseObj {
      * that the Allocation is compatible with the input buffer; it copies memory
      * without reinterpretation.
      *
-     * @param d the source data array
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
+     *
+     * @param d the source array
      */
     public void copyFromUnchecked(int[] d) {
         copyFromUnchecked(d, Element.DataType.SIGNED_32, d.length);
@@ -663,7 +739,21 @@ public class Allocation extends BaseObj {
      * that the Allocation is compatible with the input buffer; it copies memory
      * without reinterpretation.
      *
-     * @param d the source data array
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
+     *
+     * @param d the source array
      */
     public void copyFromUnchecked(short[] d) {
         copyFromUnchecked(d, Element.DataType.SIGNED_16, d.length);
@@ -674,7 +764,21 @@ public class Allocation extends BaseObj {
      * that the Allocation is compatible with the input buffer; it copies memory
      * without reinterpretation.
      *
-     * @param d the source data array
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
+     *
+     * @param d the source array
      */
     public void copyFromUnchecked(byte[] d) {
         copyFromUnchecked(d, Element.DataType.SIGNED_8, d.length);
@@ -685,7 +789,21 @@ public class Allocation extends BaseObj {
      * that the Allocation is compatible with the input buffer; it copies memory
      * without reinterpretation.
      *
-     * @param d the source data array
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
+     *
+     * @param d the source array
      */
     public void copyFromUnchecked(float[] d) {
         copyFromUnchecked(d, Element.DataType.FLOAT_32, d.length);
@@ -695,10 +813,24 @@ public class Allocation extends BaseObj {
     /**
      * Copy into this Allocation from an array.  This variant is type checked
      * and will generate exceptions if the Allocation's {@link
-     * android.renderscript.Element} does not match the array's
+     * android.support.v8.renderscript.Element} does not match the array's
      * primitive type.
      *
-     * @param array The source data array
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
+     *
+     * @param array The source array
      */
     public void copyFrom(Object array) {
         copyFromUnchecked(array, validateObjectIsPrimitiveArray(array, true),
@@ -708,9 +840,24 @@ public class Allocation extends BaseObj {
     /**
      * Copy into this Allocation from an array.  This variant is type checked
      * and will generate exceptions if the Allocation's {@link
-     * android.support.v8.renderscript.Element} is not a 32 bit integer type.
+     * android.support.v8.renderscript.Element} is not a 32 bit integer nor a vector of 32 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
      *
-     * @param d the source data array
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
+     *
+     * @param d the source array
      */
     public void copyFrom(int[] d) {
         validateIsInt32();
@@ -720,9 +867,24 @@ public class Allocation extends BaseObj {
     /**
      * Copy into this Allocation from an array.  This variant is type checked
      * and will generate exceptions if the Allocation's {@link
-     * android.support.v8.renderscript.Element} is not a 16 bit integer type.
+     * android.support.v8.renderscript.Element} is not a 16 bit integer nor a vector of 16 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
      *
-     * @param d the source data array
+     * @param d the source array
      */
     public void copyFrom(short[] d) {
         validateIsInt16();
@@ -732,9 +894,24 @@ public class Allocation extends BaseObj {
     /**
      * Copy into this Allocation from an array.  This variant is type checked
      * and will generate exceptions if the Allocation's {@link
-     * android.support.v8.renderscript.Element} is not an 8 bit integer type.
+     * android.support.v8.renderscript.Element} is not an 8 bit integer nor a vector of 8 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
      *
-     * @param d the source data array
+     * @param d the source array
      */
     public void copyFrom(byte[] d) {
         validateIsInt8();
@@ -744,9 +921,24 @@ public class Allocation extends BaseObj {
     /**
      * Copy into this Allocation from an array.  This variant is type checked
      * and will generate exceptions if the Allocation's {@link
-     * android.support.v8.renderscript.Element} is not a 32 bit float type.
+     * android.support.v8.renderscript.Element} is neither a 32 bit float nor a vector of
+     * 32 bit floats {@link android.support.v8.renderscript.Element.DataType}.
      *
-     * @param d the source data array
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
+     *
+     * @param d the source array
      */
     public void copyFrom(float[] d) {
         validateIsFloat32();
@@ -940,12 +1132,26 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an array into part of this Allocation.  This method does not
+     * Copy an array into a 1D region of this Allocation.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param array The source data array
+     * @param array The source array
      */
     public void copy1DRangeFromUnchecked(int off, int count, Object array) {
         copy1DRangeFromUnchecked(off, count, array,
@@ -954,48 +1160,104 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy an array into part of this Allocation.  This method does not
+     * Copy an array into a 1D region of this Allocation.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeFromUnchecked(int off, int count, int[] d) {
         copy1DRangeFromUnchecked(off, count, (Object)d, Element.DataType.SIGNED_32, d.length);
     }
 
     /**
-     * Copy an array into part of this Allocation.  This method does not
+     * Copy an array into a 1D region of this Allocation.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeFromUnchecked(int off, int count, short[] d) {
         copy1DRangeFromUnchecked(off, count, (Object)d, Element.DataType.SIGNED_16, d.length);
     }
 
     /**
-     * Copy an array into part of this Allocation.  This method does not
+     * Copy an array into a 1D region of this Allocation.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeFromUnchecked(int off, int count, byte[] d) {
         copy1DRangeFromUnchecked(off, count, (Object)d, Element.DataType.SIGNED_8, d.length);
     }
 
     /**
-     * Copy an array into part of this Allocation.  This method does not
+     * Copy an array into a 1D region of this Allocation.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeFromUnchecked(int off, int count, float[] d) {
         copy1DRangeFromUnchecked(off, count, (Object)d, Element.DataType.FLOAT_32, d.length);
@@ -1003,13 +1265,28 @@ public class Allocation extends BaseObj {
 
 
     /**
-     * Copy an array into part of this Allocation.  This variant is type checked
-     * and will generate exceptions if the Allocation type does not
-     * match the component type of the array passed in.
+     * Copy an array into a 1D region of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} does not match the component type
+     * of the array passed in.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param array The source data array.
+     * @param array The source array.
      */
     public void copy1DRangeFrom(int off, int count, Object array) {
         copy1DRangeFromUnchecked(off, count, array,
@@ -1018,13 +1295,28 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * 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.
+     * Copy an array into a 1D region of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is not an 32 bit integer nor a vector of 32 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeFrom(int off, int count, int[] d) {
         validateIsInt32();
@@ -1032,13 +1324,28 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * 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.
+     * Copy an array into a 1D region of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is not an 16 bit integer nor a vector of 16 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeFrom(int off, int count, short[] d) {
         validateIsInt16();
@@ -1046,13 +1353,28 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * 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.
+     * Copy an array into a 1D region of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is not an 8 bit integer nor a vector of 8 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeFrom(int off, int count, byte[] d) {
         validateIsInt8();
@@ -1060,13 +1382,28 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * 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.
+     * Copy an array into a 1D region of this Allocation.  This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is neither a 32 bit float nor a vector of
+     * 32 bit floats {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array.
+     * @param d the source array.
      */
     public void copy1DRangeFrom(int off, int count, float[] d) {
         validateIsFloat32();
@@ -1132,7 +1469,23 @@ public class Allocation extends BaseObj {
 
     /**
      * Copy from an array into a rectangular region in this Allocation.  The
-     * array is assumed to be tightly packed.
+     * array is assumed to be tightly packed. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} does not match the input data type.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to update in this Allocation
      * @param yoff Y offset of the region to update in this Allocation
@@ -1148,7 +1501,24 @@ public class Allocation extends BaseObj {
 
     /**
      * Copy from an array into a rectangular region in this Allocation.  The
-     * array is assumed to be tightly packed.
+     * array is assumed to be tightly packed. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is not an 8 bit integer nor a vector of 8 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to update in this Allocation
      * @param yoff Y offset of the region to update in this Allocation
@@ -1164,7 +1534,24 @@ public class Allocation extends BaseObj {
 
     /**
      * Copy from an array into a rectangular region in this Allocation.  The
-     * array is assumed to be tightly packed.
+     * array is assumed to be tightly packed. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is not a 16 bit integer nor a vector of 16 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to update in this Allocation
      * @param yoff Y offset of the region to update in this Allocation
@@ -1180,7 +1567,24 @@ public class Allocation extends BaseObj {
 
     /**
      * Copy from an array into a rectangular region in this Allocation.  The
-     * array is assumed to be tightly packed.
+     * array is assumed to be tightly packed. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is not a 32 bit integer nor a vector of 32 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to update in this Allocation
      * @param yoff Y offset of the region to update in this Allocation
@@ -1196,7 +1600,24 @@ public class Allocation extends BaseObj {
 
     /**
      * Copy from an array into a rectangular region in this Allocation.  The
-     * array is assumed to be tightly packed.
+     * array is assumed to be tightly packed. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is neither a 32 bit float nor a vector of
+     * 32 bit floats {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to update in this Allocation
      * @param yoff Y offset of the region to update in this Allocation
@@ -1272,7 +1693,13 @@ public class Allocation extends BaseObj {
         }
     }
 
-
+    /**
+     * Copy a rectangular region from the array into the allocation.
+     * The array is assumed to be tightly packed.
+     *
+     * The data type of the array is not required to be the same as
+     * the element data type.
+     */
     private void copy3DRangeFromUnchecked(int xoff, int yoff, int zoff, int w, int h, int d,
                                           Object array, Element.DataType dt, int arrayLen) {
         mRS.validate();
@@ -1298,8 +1725,24 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy a rectangular region from the array into the allocation.
-     * The array is assumed to be tightly packed.
+     * Copy from an array into a 3D region in this Allocation.  The
+     * array is assumed to be tightly packed. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} does not match the input data type.
+     *
+     * <p> The size of the region is: w * h * d * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to update in this Allocation
      * @param yoff Y offset of the region to update in this Allocation
@@ -1374,10 +1817,23 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from the Allocation into an array.  The array must be at
-     * least as large as the Allocation.  The
-     * {@link android.renderscript.Element} must match the component
-     * type of the array passed in.
+     * Copy from the Allocation into an array. The method is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} does not match the input data type.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells will be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
      *
      * @param array The array to be set from the Allocation.
      */
@@ -1387,9 +1843,24 @@ 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 integer
-     * {@link android.support.v8.renderscript.Element} type.
+     * Copy from the Allocation into a byte array. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is neither an 8 bit integer nor a vector of 8 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells will be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1399,9 +1870,24 @@ 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 integer
-     * {@link android.support.v8.renderscript.Element} type.
+     * Copy from the Allocation into a short array. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is not a 16 bit integer nor a vector of 16 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells will be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1411,9 +1897,24 @@ 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 integer
-     * {@link android.support.v8.renderscript.Element} type.
+     * Copy from the Allocation into a int array. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is not a 32 bit integer nor a vector of 32 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells will be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1423,9 +1924,24 @@ 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
-     * {@link android.support.v8.renderscript.Element} type.
+     * Copy from the Allocation into a float array. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is neither a 32 bit float nor a vector of
+     * 32 bit floats {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the Allocation {@link
+     * #getBytesSize getBytesSize()}.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells will be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the Allocation {@link #getBytesSize getBytesSize()}. The padding bytes for
+     * the cells must not be part of the array.
      *
      * @param d The array to be set from the Allocation.
      */
@@ -1443,7 +1959,7 @@ public class Allocation extends BaseObj {
      * @param yoff
      * @param zoff
      * @param component_number
-     * @param array
+     * @param fp
      */
     /*
     public void copyToFieldPacker(int xoff, int yoff, int zoff, int component_number, FieldPacker fp) {
@@ -1462,7 +1978,7 @@ public class Allocation extends BaseObj {
         }
 
         final byte[] data = fp.getData();
-        int data_length = fp.getPos();
+        int data_length = data.length;
         int eSize = mType.mElement.mElements[component_number].getBytesSize();
         eSize *= mType.mElement.mArraySizes[component_number];
 
@@ -1490,12 +2006,26 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
+     * Copy a 1D region of this Allocation into an array.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param array The dest data array
+     * @param array The dest array
      */
     public void copy1DRangeToUnchecked(int off, int count, Object array) {
         copy1DRangeToUnchecked(off, count, array,
@@ -1504,48 +2034,104 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
+     * Copy a 1D region of this Allocation into an array.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeToUnchecked(int off, int count, int[] d) {
         copy1DRangeToUnchecked(off, count, (Object)d, Element.DataType.SIGNED_32, d.length);
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
+     * Copy a 1D region of this Allocation into an array.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeToUnchecked(int off, int count, short[] d) {
         copy1DRangeToUnchecked(off, count, (Object)d, Element.DataType.SIGNED_16, d.length);
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
+     * Copy a 1D region of this Allocation into an array.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeToUnchecked(int off, int count, byte[] d) {
         copy1DRangeToUnchecked(off, count, (Object)d, Element.DataType.SIGNED_8, d.length);
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
+     * Copy a 1D region of this Allocation into an array.  This method does not
      * guarantee that the Allocation is compatible with the input buffer.
      *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
+     *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeToUnchecked(int off, int count, float[] d) {
         copy1DRangeToUnchecked(off, count, (Object)d, Element.DataType.FLOAT_32, d.length);
@@ -1553,13 +2139,28 @@ public class Allocation extends BaseObj {
 
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
-     * and will generate exceptions if the Allocation type does not
-     * match the component type of the array passed in.
+     * Copy a 1D region of this Allocation into an array.  This method is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} does not match the component type
+     * of the array passed in.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param array The source data array.
+     * @param array The source array.
      */
     public void copy1DRangeTo(int off, int count, Object array) {
         copy1DRangeToUnchecked(off, count, array,
@@ -1568,13 +2169,28 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
-     * and will generate exceptions if the Allocation type is not a 32 bit
-     * integer type.
+     * Copy a 1D region of this Allocation into an array. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is neither a 32 bit integer nor a vector of 32 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeTo(int off, int count, int[] d) {
         validateIsInt32();
@@ -1582,13 +2198,28 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
-     * and will generate exceptions if the Allocation type is not a 16 bit
-     * integer type.
+     * Copy a 1D region of this Allocation into an array. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is neither a 16 bit integer nor a vector of 16 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeTo(int off, int count, short[] d) {
         validateIsInt16();
@@ -1596,13 +2227,28 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
-     * and will generate exceptions if the Allocation type is not an 8 bit
-     * integer type.
+     * Copy a 1D region of this Allocation into an array. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is neither an 8 bit integer nor a vector of 8 bit
+     * integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array
+     * @param d the source array
      */
     public void copy1DRangeTo(int off, int count, byte[] d) {
         validateIsInt8();
@@ -1610,13 +2256,28 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy part of this Allocation into an array.  This method does not
-     * and will generate exceptions if the Allocation type is not a 32 bit float
-     * type.
+     * Copy a 1D region of this Allocation into an array. This variant is type checked
+     * and will generate exceptions if the Allocation's {@link
+     * android.support.v8.renderscript.Element} is neither a 32 bit float nor a vector of
+     * 32 bit floats {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: count * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param off The offset of the first element to be copied.
      * @param count The number of elements to be copied.
-     * @param d the source data array.
+     * @param d the source array.
      */
     public void copy1DRangeTo(int off, int count, float[] d) {
         validateIsFloat32();
@@ -1648,7 +2309,24 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from a rectangular region in this Allocation into an array.
+     * Copy from a rectangular region in this Allocation into an array. This
+     * method is type checked and will generate exceptions if the Allocation's
+     * {@link android.support.v8.renderscript.Element} does not match the component type
+     * of the array passed in.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to copy in this Allocation
      * @param yoff Y offset of the region to copy in this Allocation
@@ -1663,7 +2341,24 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from a rectangular region in this Allocation into an array.
+     * Copy from a rectangular region in this Allocation into an array. This
+     * variant is type checked and will generate exceptions if the Allocation's
+     * {@link android.support.v8.renderscript.Element} is neither an 8 bit integer nor a vector
+     * of 8 bit integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to copy in this Allocation
      * @param yoff Y offset of the region to copy in this Allocation
@@ -1678,7 +2373,24 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from a rectangular region in this Allocation into an array.
+     * Copy from a rectangular region in this Allocation into an array. This
+     * variant is type checked and will generate exceptions if the Allocation's
+     * {@link android.support.v8.renderscript.Element} is neither a 16 bit integer nor a vector
+     * of 16 bit integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to copy in this Allocation
      * @param yoff Y offset of the region to copy in this Allocation
@@ -1693,7 +2405,24 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from a rectangular region in this Allocation into an array.
+     * Copy from a rectangular region in this Allocation into an array. This
+     * variant is type checked and will generate exceptions if the Allocation's
+     * {@link android.support.v8.renderscript.Element} is neither a 32 bit integer nor a vector
+     * of 32 bit integers {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to copy in this Allocation
      * @param yoff Y offset of the region to copy in this Allocation
@@ -1708,7 +2437,24 @@ public class Allocation extends BaseObj {
     }
 
     /**
-     * Copy from a rectangular region in this Allocation into an array.
+     * Copy from a rectangular region in this Allocation into an array. This
+     * variant is type checked and will generate exceptions if the Allocation's
+     * {@link android.support.v8.renderscript.Element} is neither a 32 bit float nor a vector
+     * of 32 bit floats {@link android.support.v8.renderscript.Element.DataType}.
+     *
+     * <p> The size of the region is: w * h * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to copy in this Allocation
      * @param yoff Y offset of the region to copy in this Allocation
@@ -1724,8 +2470,12 @@ public class Allocation extends BaseObj {
 
 
     /**
-     * @hide
+     * Copy from a 3D region in this Allocation into an array. This method does
+     * not guarantee that the Allocation is compatible with the input buffer.
+     * The array is assumed to be tightly packed.
      *
+     * The data type of the array is not required to be the same as
+     * the element data type.
      */
     /*
     private void copy3DRangeToUnchecked(int xoff, int yoff, int zoff, int w, int h, int d,
@@ -1754,7 +2504,24 @@ public class Allocation extends BaseObj {
 
     /**
      * @hide
-     * Copy from a rectangular region in this Allocation into an array.
+     * Copy from a 3D region in this Allocation into an array. This
+     * method is type checked and will generate exceptions if the Allocation's
+     * {@link android.support.v8.renderscript.Element} does not match the component type
+     * of the array passed in.
+     *
+     * <p> The size of the region is: w * h * d * {@link #getElement}.{@link
+     * Element#getBytesSize}.
+     *
+     * <p> If the Allocation does not have Vec3 Elements, then the size of the
+     * array in bytes must be at least the size of the region.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is disabled, then the size of the array in bytes must be at least the size
+     * of the region. The padding bytes for the cells must be part of the array.
+     *
+     * <p> If the Allocation has Vec3 Elements and {@link #setAutoPadding AutoPadding}
+     * is enabled, then the size of the array in bytes must be at least 3/4 the size
+     * of the region. The padding bytes for the cells must not be part of the array.
      *
      * @param xoff X offset of the region to copy in this Allocation
      * @param yoff Y offset of the region to copy in this Allocation
diff --git a/support/java/src/android/support/v8/renderscript/ScriptIntrinsicBlur.java b/support/java/src/android/support/v8/renderscript/ScriptIntrinsicBlur.java
index e577d674..e1a134a2 100644
--- a/support/java/src/android/support/v8/renderscript/ScriptIntrinsicBlur.java
+++ b/support/java/src/android/support/v8/renderscript/ScriptIntrinsicBlur.java
@@ -40,7 +40,8 @@ public class ScriptIntrinsicBlur extends ScriptIntrinsic {
      * Create an intrinsic for applying a blur to an allocation. The
      * default radius is 5.0.
      *
-     * Supported elements types are {@link Element#U8_4}
+     * Supported elements types are {@link Element#U8},
+     * {@link Element#U8_4}.
      *
      * @param rs The RenderScript context
      * @param e Element type for inputs and outputs