Update documentation about copyTo and copyFrom.
Bug: 23159764
Bug: 26862970
- Add detailed description of AutoPadding
- Add comments to all the copy related APIs.
- Fix typos in the comments.
Change-Id: I2d045e0d90efd94f1407f88d3e35bcd42ea93fb9
(cherry picked from commit 3231e8e0220614f7b1628493da5f276f19faab7c)
diff --git a/rs/java/android/renderscript/Allocation.java b/rs/java/android/renderscript/Allocation.java
index 7619e79..4cd2354 100644
--- a/rs/java/android/renderscript/Allocation.java
+++ b/rs/java/android/renderscript/Allocation.java
@@ -297,13 +297,50 @@
}
/**
- * 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.
*
- * <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.
+ * 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.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> 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
*
@@ -665,12 +702,27 @@
}
}
+
/**
* 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 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) {
try {
@@ -687,7 +739,21 @@
* 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);
@@ -698,7 +764,21 @@
* 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);
@@ -709,7 +789,21 @@
* 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);
@@ -720,7 +814,21 @@
* 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);
@@ -733,7 +841,21 @@
* android.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) {
try {
@@ -748,9 +870,24 @@
/**
* 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.
+ * android.renderscript.Element} is not a 32 bit integer nor a vector of 32 bit
+ * integers {@link android.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(int[] d) {
validateIsInt32();
@@ -760,9 +897,24 @@
/**
* 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.
+ * android.renderscript.Element} is not a 16 bit integer nor a vector of 16 bit
+ * integers {@link android.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(short[] d) {
validateIsInt16OrFloat16();
@@ -772,9 +924,24 @@
/**
* 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.
+ * android.renderscript.Element} is not an 8 bit integer nor a vector of 8 bit
+ * integers {@link android.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(byte[] d) {
validateIsInt8();
@@ -784,9 +951,24 @@
/**
* 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.
+ * android.renderscript.Element} is neither a 32 bit float nor a vector of
+ * 32 bit floats {@link android.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();
@@ -972,13 +1154,28 @@
}
}
+
/**
- * 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,
@@ -987,62 +1184,132 @@
}
/**
- * 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);
}
-
/**
- * 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.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,
@@ -1051,13 +1318,28 @@
}
/**
- * 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.renderscript.Element} is not an 32 bit integer nor a vector of 32 bit
+ * integers {@link android.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();
@@ -1065,13 +1347,28 @@
}
/**
- * 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.renderscript.Element} is not an 16 bit integer nor a vector of 16 bit
+ * integers {@link android.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) {
validateIsInt16OrFloat16();
@@ -1079,13 +1376,28 @@
}
/**
- * 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.renderscript.Element} is not an 8 bit integer nor a vector of 8 bit
+ * integers {@link android.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();
@@ -1093,13 +1405,28 @@
}
/**
- * 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.renderscript.Element} is neither a 32 bit float nor a vector of
+ * 32 bit floats {@link android.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();
@@ -1172,7 +1499,23 @@
/**
* 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.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
@@ -1193,7 +1536,24 @@
/**
* 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.renderscript.Element} is not an 8 bit integer nor a vector of 8 bit
+ * integers {@link android.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
@@ -1209,7 +1569,24 @@
/**
* 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.renderscript.Element} is not a 16 bit integer nor a vector of 16 bit
+ * integers {@link android.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
@@ -1225,7 +1602,24 @@
/**
* 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.renderscript.Element} is not a 32 bit integer nor a vector of 32 bit
+ * integers {@link android.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
@@ -1241,7 +1635,24 @@
/**
* 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.renderscript.Element} is neither a 32 bit float nor a vector of
+ * 32 bit floats {@link android.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
@@ -1364,8 +1775,24 @@
}
/**
- * 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.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
@@ -1455,10 +1882,23 @@
}
/**
- * 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.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.
*/
@@ -1468,9 +1908,24 @@
}
/**
- * 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.
+ * Copy from the Allocation into a byte array. This variant is type checked
+ * and will generate exceptions if the Allocation's {@link
+ * android.renderscript.Element} is neither an 8 bit integer nor a vector of 8 bit
+ * integers {@link android.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.
*/
@@ -1480,9 +1935,24 @@
}
/**
- * 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.
+ * Copy from the Allocation into a short array. This variant is type checked
+ * and will generate exceptions if the Allocation's {@link
+ * android.renderscript.Element} is not a 16 bit integer nor a vector of 16 bit
+ * integers {@link android.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.
*/
@@ -1492,9 +1962,24 @@
}
/**
- * 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.
+ * Copy from the Allocation into a int array. This variant is type checked
+ * and will generate exceptions if the Allocation's {@link
+ * android.renderscript.Element} is not a 32 bit integer nor a vector of 32 bit
+ * integers {@link android.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.
*/
@@ -1504,9 +1989,24 @@
}
/**
- * 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.
+ * Copy from the Allocation into a float array. This variant is type checked
+ * and will generate exceptions if the Allocation's {@link
+ * android.renderscript.Element} is neither a 32 bit float nor a vector of
+ * 32 bit floats {@link android.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.
*/
@@ -1609,12 +2109,26 @@
}
/**
- * 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,
@@ -1623,62 +2137,132 @@
}
/**
- * 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);
}
-
/**
- * 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.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,
@@ -1687,13 +2271,28 @@
}
/**
- * 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.renderscript.Element} is neither a 32 bit integer nor a vector of 32 bit
+ * integers {@link android.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();
@@ -1701,13 +2300,28 @@
}
/**
- * 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.renderscript.Element} is neither a 16 bit integer nor a vector of 16 bit
+ * integers {@link android.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) {
validateIsInt16OrFloat16();
@@ -1715,13 +2329,28 @@
}
/**
- * 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.renderscript.Element} is neither an 8 bit integer nor a vector of 8 bit
+ * integers {@link android.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();
@@ -1729,13 +2358,28 @@
}
/**
- * 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.renderscript.Element} is neither a 32 bit float nor a vector of
+ * 32 bit floats {@link android.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();
@@ -1772,7 +2416,24 @@
}
/**
- * 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.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
@@ -1787,7 +2448,24 @@
}
/**
- * 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.renderscript.Element} is neither an 8 bit integer nor a vector
+ * of 8 bit integers {@link android.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
@@ -1802,7 +2480,24 @@
}
/**
- * 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.renderscript.Element} is neither a 16 bit integer nor a vector
+ * of 16 bit integers {@link android.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
@@ -1817,7 +2512,24 @@
}
/**
- * 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.renderscript.Element} is neither a 32 bit integer nor a vector
+ * of 32 bit integers {@link android.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
@@ -1832,7 +2544,24 @@
}
/**
- * 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.renderscript.Element} is neither a 32 bit float nor a vector
+ * of 32 bit floats {@link android.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
@@ -1848,7 +2577,8 @@
/**
- * Copy from a rectangular region in this Allocation into an array.
+ * 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
@@ -1883,7 +2613,24 @@
}
/*
- * 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.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
@@ -2094,7 +2841,7 @@
/**
* @hide
* Gets or creates a ByteBuffer that contains the raw data of the current Allocation.
- * If the Allocation is created with USAGE_IO_INPUT, the returned ByteBuffer
+ * <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,
@@ -2171,7 +2918,7 @@
* Creates a new Allocation with the given {@link
* android.renderscript.Allocation}. The same data layout of
* the input Allocation will be applied.
- * If the input allocation is of usage: USAGE_IO_INPUT, the created
+ * <p> If the input allocation is of usage: USAGE_IO_INPUT, the created
* Allocation will be sharing the same BufferQueue.
*
* @param rs Context to which the allocation will belong.
