Improve RS documentation.
bug 8570568
Change-Id: I465fcc8ec3e2cc892dc3cb0067aacf5224338102
diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java
index 8ba09e0..b460a4d 100644
--- a/graphics/java/android/renderscript/Allocation.java
+++ b/graphics/java/android/renderscript/Allocation.java
@@ -30,46 +30,29 @@
import android.graphics.Canvas;
/**
- * <p>
- * Memory allocation class for renderscript. An allocation combines a
- * {@link android.renderscript.Type} with the memory to provide storage for user data and objects.
- * This implies that all memory in Renderscript is typed.
- * </p>
+ * <p> This class provides the primary method through which data is passed to
+ * and from RenderScript kernels. An Allocation provides the backing store for
+ * a given {@link android.renderscript.Type}. </p>
*
- * <p>Allocations are the primary way data moves into and out of scripts. Memory is user
- * synchronized and it's possible for allocations to exist in multiple memory spaces
- * concurrently. Currently those spaces are:</p>
- * <ul>
- * <li>Script: accessable by RS scripts.</li>
- * <li>Graphics Texture: accessable as a graphics texture.</li>
- * <li>Graphics Vertex: accessable as graphical vertex data.</li>
- * <li>Graphics Constants: Accessable as constants in user shaders</li>
- * </ul>
- * </p>
- * <p>
- * For example, when creating a allocation for a texture, the user can
- * specify its memory spaces as both script and textures. This means that it can both
- * be used as script binding and as a GPU texture for rendering. To maintain
- * synchronization if a script modifies an allocation used by other targets it must
- * call a synchronizing function to push the updates to the memory, otherwise the results
- * are undefined.
- * </p>
- * <p>By default, Android system side updates are always applied to the script accessable
- * memory. If this is not present, they are then applied to the various HW
- * memory types. A {@link android.renderscript.Allocation#syncAll syncAll()}
- * call is necessary after the script data is updated to
- * keep the other memory spaces in sync.</p>
+ * <p>An Allocation also contains a set of usage flags that denote how the
+ * Allocation could be used. For example, an Allocation may have usage flags
+ * specifying that it can be used from a script as well as input to a {@link
+ * android.renderscript.Sampler}. A developer must synchronize across these
+ * different usages using {@link android.renderscript.Allocation#syncAll} in
+ * order to ensure that different users of the Allocation have a consistent view
+ * of memory. For example, in the case where an Allocation is used as the output
+ * of one kernel and as Sampler input in a later kernel, a developer must call
+ * {@link #syncAll syncAll(Allocation.USAGE_SCRIPT)} prior to launching the
+ * second kernel to ensure correctness.
*
- * <p>Allocation data is uploaded in one of two primary ways. For simple
- * arrays there are copyFrom() functions that take an array from the control code and
- * copy it to the slave memory store. Both type checked and unchecked copies are provided.
- * The unchecked variants exist to allow apps to copy over arrays of structures from a
- * control language that does not support structures.</p>
+ * <p>An Allocation can be populated with the {@link #copyFrom} routines. For
+ * more complex Element types, the {@link #copyFromUnchecked} methods can be
+ * used to copy from byte arrays or similar constructs.</p>
*
* <div class="special reference">
* <h3>Developer Guides</h3>
- * <p>For more information about creating an application that uses Renderscript, read the
- * <a href="{@docRoot}guide/topics/renderscript/index.html">Renderscript</a> developer guide.</p>
+ * <p>For more information about creating an application that uses RenderScript, read the
+ * <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer guide.</p>
* </div>
**/
public class Allocation extends BaseObj {
@@ -97,97 +80,102 @@
new HashMap<Integer, Allocation>();
IoInputNotifier mBufferNotifier;
+ /**
+ * The usage of the Allocation. These signal to RenderScript where to place
+ * the Allocation in memory.
+ *
+ */
/**
- * The usage of the allocation. These signal to renderscript
- * where to place the allocation in memory.
- *
- * SCRIPT The allocation will be bound to and accessed by
- * scripts.
+ * The Allocation will be bound to and accessed by scripts.
*/
public static final int USAGE_SCRIPT = 0x0001;
/**
- * GRAPHICS_TEXTURE The allocation will be used as a texture
- * source by one or more graphics programs.
+ * The Allocation will be used as a texture source by one or more graphics
+ * programs.
*
*/
public static final int USAGE_GRAPHICS_TEXTURE = 0x0002;
/**
- * GRAPHICS_VERTEX The allocation will be used as a graphics
- * mesh.
+ * The Allocation will be used as a graphics mesh.
+ *
+ * This was deprecated in API level 16.
*
*/
public static final int USAGE_GRAPHICS_VERTEX = 0x0004;
/**
- * GRAPHICS_CONSTANTS The allocation will be used as the source
- * of shader constants by one or more programs.
+ * The Allocation will be used as the source of shader constants by one or
+ * more programs.
+ *
+ * This was deprecated in API level 16.
*
*/
public static final int USAGE_GRAPHICS_CONSTANTS = 0x0008;
/**
- * USAGE_GRAPHICS_RENDER_TARGET The allocation will be used as a
- * target for offscreen rendering
+ * The Allocation will be used as a target for offscreen rendering
+ *
+ * This was deprecated in API level 16.
*
*/
public static final int USAGE_GRAPHICS_RENDER_TARGET = 0x0010;
/**
- * USAGE_IO_INPUT The allocation will be used as SurfaceTexture
- * consumer. This usage will cause the allocation to be created
- * read only.
+ * The Allocation will be used as a {@link android.graphics.SurfaceTexture}
+ * consumer. This usage will cause the Allocation to be created as
+ * read-only.
*
*/
public static final int USAGE_IO_INPUT = 0x0020;
/**
- * USAGE_IO_OUTPUT The allocation will be used as a
- * SurfaceTexture producer. The dimensions and format of the
- * SurfaceTexture will be forced to those of the allocation.
+ * The Allocation will be used as a {@link android.graphics.SurfaceTexture}
+ * producer. The dimensions and format of the {@link
+ * android.graphics.SurfaceTexture} will be forced to those of the
+ * Allocation.
*
*/
public static final int USAGE_IO_OUTPUT = 0x0040;
/**
- * USAGE_SHARED The allocation's backing store will be inherited
- * from another object (usually a Bitmap); calling appropriate
- * copy methods will be significantly faster than if the entire
- * allocation were copied every time.
+ * The Allocation's backing store will be inherited from another object
+ * (usually a {@link android.graphics.Bitmap}); copying to or from the
+ * original source Bitmap will cause a synchronization rather than a full
+ * copy. {@link #syncAll} may also be used to synchronize the Allocation
+ * and the source Bitmap.
*
- * This is set by default for allocations created with
- * CreateFromBitmap(RenderScript, Bitmap) in API version 18 and
- * higher.
+ * <p>This is set by default for allocations created with {@link
+ * #createFromBitmap} in API version 18 and higher.</p>
*
*/
public static final int USAGE_SHARED = 0x0080;
/**
- * Controls mipmap behavior when using the bitmap creation and
- * update functions.
+ * Controls mipmap behavior when using the bitmap creation and update
+ * functions.
*/
public enum MipmapControl {
/**
- * No mipmaps will be generated and the type generated from the
- * incoming bitmap will not contain additional LODs.
+ * No mipmaps will be generated and the type generated from the incoming
+ * bitmap will not contain additional LODs.
*/
MIPMAP_NONE(0),
/**
- * A Full mipmap chain will be created in script memory. The
- * type of the allocation will contain a full mipmap chain. On
- * upload to graphics the full chain will be transfered.
+ * A full mipmap chain will be created in script memory. The Type of
+ * the Allocation will contain a full mipmap chain. On upload, the full
+ * chain will be transferred.
*/
MIPMAP_FULL(1),
/**
- * The type of the allocation will be the same as MIPMAP_NONE.
- * It will not contain mipmaps. On upload to graphics the
- * graphics copy of the allocation data will contain a full
- * mipmap chain generated from the top level in script memory.
+ * The Type of the Allocation will be the same as MIPMAP_NONE. It will
+ * not contain mipmaps. On upload, the allocation data will contain a
+ * full mipmap chain generated from the top level in script memory.
*/
MIPMAP_ON_SYNC_TO_TEXTURE(2);
@@ -207,10 +195,10 @@
/**
- * Get the element of the type of the Allocation.
+ * Get the {@link android.renderscript.Element} of the {@link
+ * android.renderscript.Type} of the Allocation.
*
- * @return Element that describes the structure of data in the
- * allocation
+ * @return Element
*
*/
public Element getElement() {
@@ -220,8 +208,7 @@
/**
* Get the usage flags of the Allocation.
*
- * @return usage flags associated with the allocation. e.g.
- * script, texture, etc.
+ * @return usage this Allocation's set of the USAGE_* flags OR'd together
*
*/
public int getUsage() {
@@ -350,7 +337,7 @@
}
/**
- * Get the type of the Allocation.
+ * Get the {@link android.renderscript.Type} of the Allocation.
*
* @return Type
*
@@ -360,8 +347,8 @@
}
/**
- * Propagate changes from one usage of the allocation to the
- * remaining usages of the allocation.
+ * Propagate changes from one usage of the Allocation to the
+ * other usages of the Allocation.
*
*/
public void syncAll(int srcLocation) {
@@ -388,8 +375,10 @@
}
/**
- * Send a buffer to the output stream. The contents of the
- * Allocation will be undefined after this operation.
+ * Send a buffer to the output stream. The contents of the Allocation will
+ * be undefined after this operation. This operation is only valid if {@link
+ * #USAGE_IO_OUTPUT} is set on the Allocation.
+ *
*
*/
public void ioSend() {
@@ -410,7 +399,8 @@
}
/**
- * Receive the latest input into the Allocation.
+ * Receive the latest input into the Allocation. This operation
+ * is only valid if {@link #USAGE_IO_INPUT} is set on the Allocation.
*
*/
public void ioReceive() {
@@ -423,7 +413,7 @@
}
/**
- * Copy an array of RS objects to the allocation.
+ * Copy an array of RS objects to the Allocation.
*
* @param d Source array.
*/
@@ -497,9 +487,9 @@
}
/**
- * Copy an allocation from an array. This variant is not type
- * checked which allows an application to fill in structured
- * data from an array.
+ * Copy into this Allocation from an array. This method does not guarantee
+ * that the Allocation is compatible with the input buffer; it copies memory
+ * without reinterpretation.
*
* @param d the source data array
*/
@@ -514,9 +504,9 @@
}
}
/**
- * Copy an allocation from an array. This variant is not type
- * checked which allows an application to fill in structured
- * data from an array.
+ * Copy into this Allocation from an array. This method does not guarantee
+ * that the Allocation is compatible with the input buffer; it copies memory
+ * without reinterpretation.
*
* @param d the source data array
*/
@@ -531,9 +521,9 @@
}
}
/**
- * Copy an allocation from an array. This variant is not type
- * checked which allows an application to fill in structured
- * data from an array.
+ * Copy into this Allocation from an array. This method does not guarantee
+ * that the Allocation is compatible with the input buffer; it copies memory
+ * without reinterpretation.
*
* @param d the source data array
*/
@@ -548,9 +538,9 @@
}
}
/**
- * Copy an allocation from an array. This variant is not type
- * checked which allows an application to fill in structured
- * data from an array.
+ * Copy into this Allocation from an array. This method does not guarantee
+ * that the Allocation is compatible with the input buffer; it copies memory
+ * without reinterpretation.
*
* @param d the source data array
*/
@@ -566,9 +556,9 @@
}
/**
- * Copy an allocation from an array. This variant is type
- * checked and will generate exceptions if the Allocation type
- * is not a 32 bit integer type.
+ * Copy into this Allocation from an array. This variant is type checked
+ * and will generate exceptions if the Allocation's {@link
+ * android.renderscript.Element} is not a 32 bit integer type.
*
* @param d the source data array
*/
@@ -584,9 +574,9 @@
}
/**
- * Copy an allocation from an array. This variant is type
- * checked and will generate exceptions if the Allocation type
- * is not a 16 bit integer type.
+ * Copy into this Allocation from an array. This variant is type checked
+ * and will generate exceptions if the Allocation's {@link
+ * android.renderscript.Element} is not a 16 bit integer type.
*
* @param d the source data array
*/
@@ -602,9 +592,9 @@
}
/**
- * Copy an allocation from an array. This variant is type
- * checked and will generate exceptions if the Allocation type
- * is not a 8 bit integer type.
+ * Copy into this Allocation from an array. This variant is type checked
+ * and will generate exceptions if the Allocation's {@link
+ * android.renderscript.Element} is not an 8 bit integer type.
*
* @param d the source data array
*/
@@ -620,9 +610,9 @@
}
/**
- * Copy an allocation from an array. This variant is type
- * checked and will generate exceptions if the Allocation type
- * is not a 32 bit float type.
+ * Copy into this Allocation from an array. This variant is type checked
+ * and will generate exceptions if the Allocation's {@link
+ * android.renderscript.Element} is not a 32 bit float type.
*
* @param d the source data array
*/
@@ -638,8 +628,15 @@
}
/**
- * Copy an allocation from a bitmap. The height, width, and
- * format of the bitmap must match the existing allocation.
+ * Copy into an Allocation from a {@link android.graphics.Bitmap}. The
+ * height, width, and format of the bitmap must match the existing
+ * allocation.
+ *
+ * <p>If the {@link android.graphics.Bitmap} is the same as the {@link
+ * android.graphics.Bitmap} used to create the Allocation with {@link
+ * #createFromBitmap} and {@link #USAGE_SHARED} is set on the Allocation,
+ * this will synchronize the Allocation with the latest data from the {@link
+ * android.graphics.Bitmap}, potentially avoiding the actual copy.</p>
*
* @param b the source bitmap
*/
@@ -658,7 +655,7 @@
}
/**
- * Copy an allocation from an allocation. The types of both allocations
+ * Copy an Allocation from an Allocation. The types of both allocations
* must be identical.
*
* @param a the source allocation
@@ -673,8 +670,8 @@
/**
- * This is only intended to be used by auto-generate code reflected from the
- * renderscript script files.
+ * This is only intended to be used by auto-generated code reflected from
+ * the RenderScript script files and should not be used by developers.
*
* @param xoff
* @param fp
@@ -693,8 +690,8 @@
}
/**
- * This is only intended to be used by auto-generate code reflected from the
- * renderscript script files.
+ * This is only intended to be used by auto-generated code reflected from
+ * the RenderScript script files.
*
* @param xoff
* @param component_number
@@ -740,23 +737,22 @@
}
/**
- * Generate a mipmap chain. Requires the type of the allocation
- * include mipmaps.
+ * Generate a mipmap chain. This is only valid if the Type of the Allocation
+ * includes mipmaps.
*
- * This function will generate a complete set of mipmaps from
- * the top level lod and place them into the script memoryspace.
+ * <p>This function will generate a complete set of mipmaps from the top
+ * level LOD and place them into the script memory space.</p>
*
- * If the allocation is also using other memory spaces a
- * followup sync will be required.
+ * <p>If the Allocation is also using other memory spaces, a call to {@link
+ * #syncAll syncAll(Allocation.USAGE_SCRIPT)} is required.</p>
*/
public void generateMipmaps() {
mRS.nAllocationGenerateMipmaps(getID(mRS));
}
/**
- * Copy part of an allocation from an array. This variant is
- * not type checked which allows an application to fill in
- * structured data from an array.
+ * Copy an array into part of this Allocation. This method does not
+ * guarantee that the Allocation is compatible with the input buffer.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -768,9 +764,8 @@
mRS.nAllocationData1D(getIDSafe(), off, mSelectedLOD, count, d, dataSize);
}
/**
- * Copy part of an allocation from an array. This variant is
- * not type checked which allows an application to fill in
- * structured data from an array.
+ * Copy an array into part of this Allocation. This method does not
+ * guarantee that the Allocation is compatible with the input buffer.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -782,9 +777,8 @@
mRS.nAllocationData1D(getIDSafe(), off, mSelectedLOD, count, d, dataSize);
}
/**
- * Copy part of an allocation from an array. This variant is
- * not type checked which allows an application to fill in
- * structured data from an array.
+ * Copy an array into part of this Allocation. This method does not
+ * guarantee that the Allocation is compatible with the input buffer.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -796,9 +790,8 @@
mRS.nAllocationData1D(getIDSafe(), off, mSelectedLOD, count, d, dataSize);
}
/**
- * Copy part of an allocation from an array. This variant is
- * not type checked which allows an application to fill in
- * structured data from an array.
+ * Copy an array into part of this Allocation. This method does not
+ * guarantee that the Allocation is compatible with the input buffer.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -811,9 +804,9 @@
}
/**
- * Copy part of an allocation from an array. This variant is
- * type checked and will generate exceptions if the Allocation
- * type is not a 32 bit integer type.
+ * Copy an array into part of this Allocation. This variant is type checked
+ * and will generate exceptions if the Allocation type is not a 32 bit
+ * integer type.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -825,9 +818,9 @@
}
/**
- * Copy part of an allocation from an array. This variant is
- * type checked and will generate exceptions if the Allocation
- * type is not a 16 bit integer type.
+ * Copy an array into part of this Allocation. This variant is type checked
+ * and will generate exceptions if the Allocation type is not a 16 bit
+ * integer type.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -839,9 +832,9 @@
}
/**
- * Copy part of an allocation from an array. This variant is
- * type checked and will generate exceptions if the Allocation
- * type is not a 8 bit integer type.
+ * Copy an array into part of this Allocation. This variant is type checked
+ * and will generate exceptions if the Allocation type is not an 8 bit
+ * integer type.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -853,9 +846,9 @@
}
/**
- * Copy part of an allocation from an array. This variant is
- * type checked and will generate exceptions if the Allocation
- * type is not a 32 bit float type.
+ * Copy an array into part of this Allocation. This variant is type checked
+ * and will generate exceptions if the Allocation type is not a 32 bit float
+ * type.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -867,7 +860,7 @@
}
/**
- * Copy part of an allocation from another allocation.
+ * Copy part of an Allocation into this Allocation.
*
* @param off The offset of the first element to be copied.
* @param count The number of elements to be copied.
@@ -929,46 +922,76 @@
/**
- * Copy a rectangular region from the array into the allocation.
- * The incoming array is assumed to be tightly packed.
+ * Copy from an array into a rectangular region in this Allocation. The
+ * array is assumed to be tightly packed.
*
- * @param xoff X offset of the region to update
- * @param yoff Y offset of the region to update
- * @param w Width of the incoming region to update
- * @param h Height of the incoming region to update
- * @param data to be placed into the allocation
+ * @param xoff X offset of the region to update in this Allocation
+ * @param yoff Y offset of the region to update in this Allocation
+ * @param w Width of the region to update
+ * @param h Height of the region to update
+ * @param data to be placed into the Allocation
*/
public void copy2DRangeFrom(int xoff, int yoff, int w, int h, byte[] data) {
validateIsInt8();
copy2DRangeFromUnchecked(xoff, yoff, w, h, data);
}
+ /**
+ * Copy from an array into a rectangular region in this Allocation. The
+ * array is assumed to be tightly packed.
+ *
+ * @param xoff X offset of the region to update in this Allocation
+ * @param yoff Y offset of the region to update in this Allocation
+ * @param w Width of the region to update
+ * @param h Height of the region to update
+ * @param data to be placed into the Allocation
+ */
public void copy2DRangeFrom(int xoff, int yoff, int w, int h, short[] data) {
validateIsInt16();
copy2DRangeFromUnchecked(xoff, yoff, w, h, data);
}
+ /**
+ * Copy from an array into a rectangular region in this Allocation. The
+ * array is assumed to be tightly packed.
+ *
+ * @param xoff X offset of the region to update in this Allocation
+ * @param yoff Y offset of the region to update in this Allocation
+ * @param w Width of the region to update
+ * @param h Height of the region to update
+ * @param data to be placed into the Allocation
+ */
public void copy2DRangeFrom(int xoff, int yoff, int w, int h, int[] data) {
validateIsInt32();
copy2DRangeFromUnchecked(xoff, yoff, w, h, data);
}
+ /**
+ * Copy from an array into a rectangular region in this Allocation. The
+ * array is assumed to be tightly packed.
+ *
+ * @param xoff X offset of the region to update in this Allocation
+ * @param yoff Y offset of the region to update in this Allocation
+ * @param w Width of the region to update
+ * @param h Height of the region to update
+ * @param data to be placed into the Allocation
+ */
public void copy2DRangeFrom(int xoff, int yoff, int w, int h, float[] data) {
validateIsFloat32();
copy2DRangeFromUnchecked(xoff, yoff, w, h, data);
}
/**
- * Copy a rectangular region into the allocation from another
- * allocation.
+ * Copy a rectangular region from an Allocation into a rectangular region in
+ * this Allocation.
*
- * @param xoff X offset of the region to update.
- * @param yoff Y offset of the region to update.
- * @param w Width of the incoming region to update.
- * @param h Height of the incoming region to update.
- * @param data source allocation.
- * @param dataXoff X offset in data of the region to update.
- * @param dataYoff Y offset in data of the region to update.
+ * @param xoff X offset of the region in this Allocation
+ * @param yoff Y offset of the region in this Allocation
+ * @param w Width of the region to update.
+ * @param h Height of the region to update.
+ * @param data source Allocation.
+ * @param dataXoff X offset in source Allocation
+ * @param dataYoff Y offset in source Allocation
*/
public void copy2DRangeFrom(int xoff, int yoff, int w, int h,
Allocation data, int dataXoff, int dataYoff) {
@@ -981,13 +1004,13 @@
}
/**
- * Copy a bitmap into an allocation. The height and width of
- * the update will use the height and width of the incoming
- * bitmap.
+ * Copy a {@link android.graphics.Bitmap} into an Allocation. The height
+ * and width of the update will use the height and width of the {@link
+ * android.graphics.Bitmap}.
*
- * @param xoff X offset of the region to update
- * @param yoff Y offset of the region to update
- * @param data the bitmap to be copied
+ * @param xoff X offset of the region to update in this Allocation
+ * @param yoff Y offset of the region to update in this Allocation
+ * @param data the Bitmap to be copied
*/
public void copy2DRangeFrom(int xoff, int yoff, Bitmap data) {
mRS.validate();
@@ -1068,14 +1091,14 @@
/**
* @hide
* Copy a rectangular region from the array into the allocation.
- * The incoming array is assumed to be tightly packed.
+ * The array is assumed to be tightly packed.
*
- * @param xoff X offset of the region to update
- * @param yoff Y offset of the region to update
- * @param zoff Z offset of the region to update
- * @param w Width of the incoming region to update
- * @param h Height of the incoming region to update
- * @param d Depth of the incoming region to update
+ * @param xoff X offset of the region to update in this Allocation
+ * @param yoff Y offset of the region to update in this Allocation
+ * @param zoff Z offset of the region to update in this Allocation
+ * @param w Width of the region to update
+ * @param h Height of the region to update
+ * @param d Depth of the region to update
* @param data to be placed into the allocation
*/
public void copy3DRangeFrom(int xoff, int yoff, int zoff, int w, int h, int d, byte[] data) {
@@ -1115,15 +1138,16 @@
* Copy a rectangular region into the allocation from another
* allocation.
*
- * @param xoff X offset of the region to update.
- * @param yoff Y offset of the region to update.
- * @param w Width of the incoming region to update.
- * @param h Height of the incoming region to update.
- * @param d Depth of the incoming region to update.
+ * @param xoff X offset of the region to update in this Allocation
+ * @param yoff Y offset of the region to update in this Allocation
+ * @param zoff Z offset of the region to update in this Allocation
+ * @param w Width of the region to update.
+ * @param h Height of the region to update.
+ * @param d Depth of the region to update.
* @param data source allocation.
- * @param dataXoff X offset in data of the region to update.
- * @param dataYoff Y offset in data of the region to update.
- * @param dataZoff Z offset in data of the region to update
+ * @param dataXoff X offset of the region in the source Allocation
+ * @param dataYoff Y offset of the region in the source Allocation
+ * @param dataZoff Z offset of the region in the source Allocation
*/
public void copy3DRangeFrom(int xoff, int yoff, int zoff, int w, int h, int d,
Allocation data, int dataXoff, int dataYoff, int dataZoff) {
@@ -1136,8 +1160,8 @@
/**
- * Copy from the Allocation into a Bitmap. The bitmap must
- * match the dimensions of the Allocation.
+ * Copy from the Allocation into a {@link android.graphics.Bitmap}. The
+ * bitmap must match the dimensions of the Allocation.
*
* @param b The bitmap to be set from the Allocation.
*/
@@ -1149,9 +1173,9 @@
}
/**
- * Copy from the Allocation into a byte array. The array must
- * be at least as large as the Allocation. The allocation must
- * be of an 8 bit elemental type.
+ * Copy from the Allocation into a byte array. The array must be at least
+ * as large as the Allocation. The allocation must be of an 8 bit integer
+ * {@link android.renderscript.Element} type.
*
* @param d The array to be set from the Allocation.
*/
@@ -1162,9 +1186,9 @@
}
/**
- * Copy from the Allocation into a short array. The array must
- * be at least as large as the Allocation. The allocation must
- * be of an 16 bit elemental type.
+ * Copy from the Allocation into a short array. The array must be at least
+ * as large as the Allocation. The allocation must be of an 16 bit integer
+ * {@link android.renderscript.Element} type.
*
* @param d The array to be set from the Allocation.
*/
@@ -1175,9 +1199,9 @@
}
/**
- * Copy from the Allocation into a int array. The array must be
- * at least as large as the Allocation. The allocation must be
- * of an 32 bit elemental type.
+ * Copy from the Allocation into a int array. The array must be at least as
+ * large as the Allocation. The allocation must be of an 32 bit integer
+ * {@link android.renderscript.Element} type.
*
* @param d The array to be set from the Allocation.
*/
@@ -1188,9 +1212,9 @@
}
/**
- * Copy from the Allocation into a float array. The array must
- * be at least as large as the Allocation. The allocation must
- * be of an 32 bit float elemental type.
+ * Copy from the Allocation into a float array. The array must be at least
+ * as large as the Allocation. The allocation must be of an 32 bit float
+ * {@link android.renderscript.Element} type.
*
* @param d The array to be set from the Allocation.
*/
@@ -1201,20 +1225,19 @@
}
/**
- * Resize a 1D allocation. The contents of the allocation are
- * preserved. If new elements are allocated objects are created
- * with null contents and the new region is otherwise undefined.
+ * Resize a 1D allocation. The contents of the allocation are preserved.
+ * If new elements are allocated objects are created with null contents and
+ * the new region is otherwise undefined.
*
- * If the new region is smaller the references of any objects
- * outside the new region will be released.
+ * <p>If the new region is smaller the references of any objects outside the
+ * new region will be released.</p>
*
- * A new type will be created with the new dimension.
+ * <p>A new type will be created with the new dimension.</p>
*
* @param dimX The new size of the allocation.
*
- * @deprecated Renderscript objects should be immutable once
- * created. The replacement is to create a new allocation and copy the
- * contents.
+ * @deprecated RenderScript objects should be immutable once created. The
+ * replacement is to create a new allocation and copy the contents.
*/
public synchronized void resize(int dimX) {
if ((mType.getY() > 0)|| (mType.getZ() > 0) || mType.hasFaces() || mType.hasMipmaps()) {
@@ -1238,11 +1261,13 @@
}
/**
+ * Creates a new Allocation with the given {@link
+ * android.renderscript.Type}, mipmap flag, and usage flags.
*
- * @param type renderscript type describing data layout
+ * @param type RenderScript type describing data layout
* @param mips specifies desired mipmap behaviour for the
* allocation
- * @param usage bit field specifying how the allocation is
+ * @param usage bit field specifying how the Allocation is
* utilized
*/
static public Allocation createTyped(RenderScript rs, Type type, MipmapControl mips, int usage) {
@@ -1258,8 +1283,8 @@
}
/**
- * Creates a renderscript allocation with the size specified by
- * the type and no mipmaps generated by default
+ * Creates an Allocation with the size specified by the type and no mipmaps
+ * generated by default
*
* @param rs Context to which the allocation will belong.
* @param type renderscript type describing data layout
@@ -1273,12 +1298,11 @@
}
/**
- * Creates a renderscript allocation for use by the script with
- * the size specified by the type and no mipmaps generated by
- * default
+ * Creates an Allocation for use by scripts with a given {@link
+ * android.renderscript.Type} and no mipmaps
*
- * @param rs Context to which the allocation will belong.
- * @param type renderscript type describing data layout
+ * @param rs Context to which the Allocation will belong.
+ * @param type RenderScript Type describing data layout
*
* @return allocation
*/
@@ -1287,13 +1311,12 @@
}
/**
- * Creates a renderscript allocation with a specified number of
- * given elements
+ * Creates an Allocation with a specified number of given elements
*
- * @param rs Context to which the allocation will belong.
- * @param e describes what each element of an allocation is
- * @param count specifies the number of element in the allocation
- * @param usage bit field specifying how the allocation is
+ * @param rs Context to which the Allocation will belong.
+ * @param e Element to use in the Allocation
+ * @param count the number of Elements in the Allocation
+ * @param usage bit field specifying how the Allocation is
* utilized
*
* @return allocation
@@ -1313,12 +1336,11 @@
}
/**
- * Creates a renderscript allocation with a specified number of
- * given elements
+ * Creates an Allocation with a specified number of given elements
*
- * @param rs Context to which the allocation will belong.
- * @param e describes what each element of an allocation is
- * @param count specifies the number of element in the allocation
+ * @param rs Context to which the Allocation will belong.
+ * @param e Element to use in the Allocation
+ * @param count the number of Elements in the Allocation
*
* @return allocation
*/
@@ -1354,16 +1376,16 @@
}
/**
- * Creates a renderscript allocation from a bitmap
+ * Creates an Allocation from a {@link android.graphics.Bitmap}.
*
* @param rs Context to which the allocation will belong.
- * @param b bitmap source for the allocation data
+ * @param b Bitmap source for the allocation data
* @param mips specifies desired mipmap behaviour for the
* allocation
* @param usage bit field specifying how the allocation is
* utilized
*
- * @return renderscript allocation containing bitmap data
+ * @return Allocation containing bitmap data
*
*/
static public Allocation createFromBitmap(RenderScript rs, Bitmap b,
@@ -1408,9 +1430,9 @@
}
/**
- * For allocations used with io operations, returns the handle
- * onto a raw buffer that is being managed by the screen
- * compositor.
+ * Returns the handle to a raw buffer that is being managed by the screen
+ * compositor. This operation is only valid for Allocations with {@link
+ * #USAGE_IO_INPUT}.
*
* @return Surface object associated with allocation
*
@@ -1430,7 +1452,8 @@
}
/**
- * Associate a surface for io output with this allocation
+ * Associate a {@link android.view.Surface} with this Allocation. This
+ * operation is only valid for Allocations with {@link #USAGE_IO_OUTPUT}.
*
* @param sur Surface to associate with allocation
*/
@@ -1444,16 +1467,17 @@
}
/**
- * Creates a RenderScript allocation from a bitmap.
+ * Creates an Allocation from a {@link android.graphics.Bitmap}.
*
- * With target API version 18 or greater, this allocation will be
- * created with USAGE_SHARED. With target API version 17 or lower,
- * this allocation will be created with USAGE_GRAPHICS_TEXTURE.
+ * <p>With target API version 18 or greater, this Allocation will be created
+ * with {@link #USAGE_SHARED}, {@link #USAGE_SCRIPT}, and {@link
+ * #USAGE_GRAPHICS_TEXTURE}. With target API version 17 or lower, this
+ * Allocation will be created with {@link #USAGE_GRAPHICS_TEXTURE}.</p>
*
* @param rs Context to which the allocation will belong.
* @param b bitmap source for the allocation data
*
- * @return renderscript allocation containing bitmap data
+ * @return Allocation containing bitmap data
*
*/
static public Allocation createFromBitmap(RenderScript rs, Bitmap b) {
@@ -1466,12 +1490,13 @@
}
/**
- * Creates a cubemap allocation from a bitmap containing the
- * horizontal list of cube faces. Each individual face must be
- * the same size and power of 2
+ * Creates a cubemap Allocation from a {@link android.graphics.Bitmap}
+ * containing the horizontal list of cube faces. Each face must be a square,
+ * have the same size as all other faces, and have a width that is a power
+ * of 2.
*
* @param rs Context to which the allocation will belong.
- * @param b bitmap with cubemap faces layed out in the following
+ * @param b Bitmap with cubemap faces layed out in the following
* format: right, left, top, bottom, front, back
* @param mips specifies desired mipmap behaviour for the cubemap
* @param usage bit field specifying how the cubemap is utilized
@@ -1514,10 +1539,10 @@
}
/**
- * Creates a non-mipmapped cubemap allocation for use as a
- * graphics texture from a bitmap containing the horizontal list
- * of cube faces. Each individual face must be the same size and
- * power of 2
+ * Creates a non-mipmapped cubemap Allocation for use as a graphics texture
+ * from a {@link android.graphics.Bitmap} containing the horizontal list of
+ * cube faces. Each face must be a square, have the same size as all other
+ * faces, and have a width that is a power of 2.
*
* @param rs Context to which the allocation will belong.
* @param b bitmap with cubemap faces layed out in the following
@@ -1533,9 +1558,9 @@
}
/**
- * Creates a cubemap allocation from 6 bitmaps containing
- * the cube faces. All the faces must be the same size and
- * power of 2
+ * Creates a cubemap Allocation from 6 {@link android.graphics.Bitmap}
+ * objects containing the cube faces. Each face must be a square, have the
+ * same size as all other faces, and have a width that is a power of 2.
*
* @param rs Context to which the allocation will belong.
* @param xpos cubemap face in the positive x direction
@@ -1600,10 +1625,10 @@
}
/**
- * Creates a non-mipmapped cubemap allocation for use as a
- * graphics texture from 6 bitmaps containing
- * the cube faces. All the faces must be the same size and
- * power of 2
+ * Creates a non-mipmapped cubemap Allocation for use as a sampler input
+ * from 6 {@link android.graphics.Bitmap} objects containing the cube
+ * faces. Each face must be a square, have the same size as all other faces,
+ * and have a width that is a power of 2.
*
* @param rs Context to which the allocation will belong.
* @param xpos cubemap face in the positive x direction
@@ -1629,8 +1654,8 @@
}
/**
- * Creates a renderscript allocation from the bitmap referenced
- * by resource id
+ * Creates an Allocation from the Bitmap referenced
+ * by resource ID.
*
* @param rs Context to which the allocation will belong.
* @param res application resources
@@ -1640,7 +1665,7 @@
* @param usage bit field specifying how the allocation is
* utilized
*
- * @return renderscript allocation containing resource data
+ * @return Allocation containing resource data
*
*/
static public Allocation createFromBitmapResource(RenderScript rs,
@@ -1660,18 +1685,19 @@
}
/**
- * Creates a non-mipmapped renderscript allocation to use as a
- * graphics texture from the bitmap referenced by resource id
+ * Creates a non-mipmapped Allocation to use as a graphics texture from the
+ * {@link android.graphics.Bitmap} referenced by resource ID.
*
- * With target API version 18 or greater, this allocation will be
- * created with USAGE_SHARED. With target API version 17 or lower,
- * this allocation will be created with USAGE_GRAPHICS_TEXTURE.
+ * <p>With target API version 18 or greater, this allocation will be created
+ * with {@link #USAGE_SCRIPT} and {@link #USAGE_GRAPHICS_TEXTURE}. With
+ * target API version 17 or lower, this allocation will be created with
+ * {@link #USAGE_GRAPHICS_TEXTURE}.</p>
*
* @param rs Context to which the allocation will belong.
* @param res application resources
* @param id resource id to load the data from
*
- * @return renderscript allocation containing resource data
+ * @return Allocation containing resource data
*
*/
static public Allocation createFromBitmapResource(RenderScript rs,
@@ -1688,8 +1714,7 @@
}
/**
- * Creates a renderscript allocation containing string data
- * encoded in UTF-8 format
+ * Creates an Allocation containing string data encoded in UTF-8 format.
*
* @param rs Context to which the allocation will belong.
* @param str string to create the allocation from
@@ -1716,11 +1741,10 @@
/**
* @hide
*
- * Interface to handle notification when new buffers are
- * available via USAGE_IO_INPUT. An application will receive
- * one notification when a buffer is available. Additional
- * buffers will not trigger new notifications until a buffer is
- * processed.
+ * Interface to handle notification when new buffers are available via
+ * {@link #USAGE_IO_INPUT}. An application will receive one notification
+ * when a buffer is available. Additional buffers will not trigger new
+ * notifications until a buffer is processed.
*/
public interface IoInputNotifier {
public void onBufferAvailable(Allocation a);
@@ -1729,7 +1753,7 @@
/**
* @hide
*
- * Set a notification handler for USAGE_IO_INPUT
+ * Set a notification handler for {@link #USAGE_IO_INPUT}.
*
* @param callback instance of the IoInputNotifier class to be called
* when buffer arrive.
@@ -1753,4 +1777,3 @@
}
-