Update RS support library docs.
Bug: 8570568
Change-Id: Ie80c8edc9fbcfbda047912c1228ebb5807d7c488
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Allocation.java b/v8/renderscript/java/src/android/support/v8/renderscript/Allocation.java
index 31bfe72..be2d812 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Allocation.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Allocation.java
@@ -28,46 +28,29 @@
import android.util.TypedValue;
/**
- * <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/graphics/renderscript.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 {
@@ -92,75 +75,76 @@
int mCurrentDimZ;
int mCurrentCount;
+ /**
+ * 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;
/**
- * 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);
@@ -180,10 +164,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() {
@@ -193,8 +177,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() {
@@ -304,7 +287,7 @@
}
/**
- * Get the type of the Allocation.
+ * Get the {@link android.renderscript.Type} of the Allocation.
*
* @return Type
*
@@ -314,8 +297,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) {
@@ -331,8 +314,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() {
@@ -353,7 +338,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() {
@@ -366,7 +352,7 @@
}
/**
- * Copy an array of RS objects to the allocation.
+ * Copy an array of RS objects to the Allocation.
*
* @param d Source array.
*/
@@ -440,9 +426,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
*/
@@ -457,9 +443,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
*/
@@ -474,9 +460,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
*/
@@ -491,9 +477,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
*/
@@ -509,9 +495,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
*/
@@ -527,9 +513,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
*/
@@ -545,9 +531,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
*/
@@ -563,9 +549,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
*/
@@ -581,8 +567,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
*/
@@ -601,7 +594,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
@@ -616,8 +609,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
@@ -636,8 +629,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
@@ -683,23 +676,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.
@@ -711,9 +703,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.
@@ -725,9 +716,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.
@@ -739,9 +729,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.
@@ -754,9 +743,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.
@@ -768,9 +757,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.
@@ -782,9 +771,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.
@@ -796,9 +785,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.
@@ -810,7 +799,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.
@@ -872,46 +861,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) {
@@ -924,13 +943,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();
@@ -1011,14 +1030,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) {
@@ -1058,15 +1077,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) {
@@ -1079,8 +1099,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.
*/
@@ -1092,9 +1112,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.
*/
@@ -1105,9 +1125,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.
*/
@@ -1118,9 +1138,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.
*/
@@ -1131,9 +1151,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.
*/
@@ -1151,11 +1171,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) {
@@ -1175,8 +1197,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
@@ -1190,12 +1212,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
*/
@@ -1204,13 +1225,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
@@ -1234,12 +1254,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
*/
@@ -1275,16 +1294,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,
@@ -1333,15 +1352,15 @@
}
/**
- * Creates a RenderScript allocation from a bitmap.
+ * Creates an Allocation from a {@link android.graphics.Bitmap}.
*
- * This allocation will be created with MIPMAP_NONE and
- * USAGE_SHARED | USAGE_SCRIPT.
+ * <p>This Allocation will be created with {@link #USAGE_SHARED}, and
+ * {@link #USAGE_SCRIPT}.</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) {
@@ -1350,12 +1369,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
@@ -1398,10 +1418,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
@@ -1417,9 +1437,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
@@ -1487,10 +1507,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
@@ -1516,8 +1536,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
@@ -1527,7 +1547,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,
@@ -1537,6 +1557,9 @@
int usage) {
rs.validate();
+ if ((usage & (USAGE_SHARED | USAGE_IO_INPUT | USAGE_IO_OUTPUT)) != 0) {
+ throw new RSIllegalArgumentException("Unsupported usage specified.");
+ }
Bitmap b = BitmapFactory.decodeResource(res, id);
Allocation alloc = createFromBitmap(rs, b, mips, usage);
b.recycle();
@@ -1544,14 +1567,17 @@
}
/**
- * 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.
+ *
+ * <p>This allocation will be created with {@link #USAGE_SCRIPT} and
+ * {@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,
@@ -1559,12 +1585,11 @@
int id) {
return createFromBitmapResource(rs, res, id,
MipmapControl.MIPMAP_NONE,
- USAGE_SHARED | USAGE_SCRIPT);
+ USAGE_SCRIPT | USAGE_GRAPHICS_TEXTURE);
}
/**
- * 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
@@ -1589,4 +1614,3 @@
}
}
-
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/BaseObj.java b/v8/renderscript/java/src/android/support/v8/renderscript/BaseObj.java
index 2c97b08..b9ed367 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/BaseObj.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/BaseObj.java
@@ -19,9 +19,9 @@
import android.util.Log;
/**
- * BaseObj is the base class for interfacing with native renderscript objects.
- * It primarly contains code for tracking the native object ID and forcably
- * disconecting the object from the native allocation for early cleanup.
+ * BaseObj is the base class for all RenderScript objects owned by a RS context.
+ * It is responsible for lifetime management and resource tracking. This class
+ * should not be used by a user application.
*
**/
public class BaseObj {
@@ -97,10 +97,9 @@
}
/**
- * destroy disconnects the object from the native object effectively
- * rendering this java object dead. The primary use is to force immediate
- * cleanup of resources when it is believed the GC will not respond quickly
- * enough.
+ * Frees any native resources associated with this object. The
+ * primary use is to force immediate cleanup of resources when it is
+ * believed the GC will not respond quickly enough.
*/
synchronized public void destroy() {
if(mDestroyed) {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Byte2.java b/v8/renderscript/java/src/android/support/v8/renderscript/Byte2.java
index 1f3a801..ed1eb9a 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Byte2.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Byte2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript byte2 type back to the Android system.
+ * Class for exposing the native RenderScript byte2 type back to the Android system.
*
**/
public class Byte2 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Byte3.java b/v8/renderscript/java/src/android/support/v8/renderscript/Byte3.java
index 84ea3fc..4ed6af6 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Byte3.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Byte3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript byte3 type back to the Android system.
+ * Class for exposing the native RenderScript byte3 type back to the Android system.
*
**/
public class Byte3 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Byte4.java b/v8/renderscript/java/src/android/support/v8/renderscript/Byte4.java
index 2ccb225..715a718 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Byte4.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Byte4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript byte4 type back to the Android system.
+ * Class for exposing the native RenderScript byte4 type back to the Android system.
*
**/
public class Byte4 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Double2.java b/v8/renderscript/java/src/android/support/v8/renderscript/Double2.java
index 5052d19..cd73363 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Double2.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Double2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript double2 type back
+ * Class for exposing the native RenderScript double2 type back
* to the Android system.
*
**/
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Double3.java b/v8/renderscript/java/src/android/support/v8/renderscript/Double3.java
index b930316..38a46a6 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Double3.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Double3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript double3 type back
+ * Class for exposing the native RenderScript double3 type back
* to the Android system.
*
**/
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Double4.java b/v8/renderscript/java/src/android/support/v8/renderscript/Double4.java
index fd15bfe..6de0fa8 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Double4.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Double4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript double4 type back
+ * Class for exposing the native RenderScript double4 type back
* to the Android system.
*
**/
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Element.java b/v8/renderscript/java/src/android/support/v8/renderscript/Element.java
index cffb706..b776f8f 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Element.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Element.java
@@ -21,31 +21,37 @@
import android.util.Log;
/**
- * <p>The most basic data type. An element represents one cell of a memory allocation.
- * Element is the basic data type of Renderscript. An element can be of two forms: Basic elements or Complex forms.
- * Examples of basic elements are:</p>
- * <ul>
- * <li>Single float value</li>
- * <li>4 element float vector</li>
- * <li>single RGB-565 color</li>
- * <li>single unsigned int 16</li>
- * </ul>
- * <p>Complex elements contain a list of sub-elements and names that
- * represents a structure of data. The fields can be accessed by name
- * from a script or shader. The memory layout is defined and ordered. Data
- * alignment is determined by the most basic primitive type. i.e. a float4
- * vector will be aligned to sizeof(float) and not sizeof(float4). The
- * ordering of elements in memory will be the order in which they were added
- * with each component aligned as necessary. No re-ordering will be done.</p>
+ * <p>An Element represents one item within an {@link
+ * android.renderscript.Allocation}. An Element is roughly equivalent to a C
+ * type in a RenderScript kernel. Elements may be basic or complex. Some basic
+ * elements are</p> <ul> <li>A single float value (equivalent to a float in a
+ * kernel)</li> <li>A four-element float vector (equivalent to a float4 in a
+ * kernel)</li> <li>An unsigned 32-bit integer (equivalent to an unsigned int in
+ * a kernel)</li> <li>A single signed 8-bit integer (equivalent to a char in a
+ * kernel)</li> </ul> <p>A complex element is roughly equivalent to a C struct
+ * and contains a number of basic or complex Elements. From Java code, a complex
+ * element contains a list of sub-elements and names that represents a
+ * particular data structure. Structs used in RS scripts are available to Java
+ * code by using the {@code ScriptField_structname} class that is reflected from
+ * a particular script.</p>
*
- * <p>The primary source of elements are from scripts. A script that exports a
- * bind point for a data structure generates a Renderscript element to represent the
- * data exported by the script. The other common source of elements is from bitmap formats.</p>
+ * <p>Basic Elements are comprised of a {@link
+ * android.renderscript.Element.DataType} and a {@link
+ * android.renderscript.Element.DataKind}. The DataType encodes C type
+ * information of an Element, while the DataKind encodes how that Element should
+ * be interpreted by a {@link android.renderscript.Sampler}. Note that {@link
+ * android.renderscript.Allocation} objects with DataKind {@link
+ * android.renderscript.Element.DataKind#USER} cannot be used as input for a
+ * {@link android.renderscript.Sampler}. In general, {@link
+ * android.renderscript.Allocation} objects that are intended for use with a
+ * {@link android.renderscript.Sampler} should use bitmap-derived Elements such
+ * as {@link android.renderscript.Element#RGBA_8888} or {@link
+ * android.renderscript#Element.A_8}.</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/graphics/renderscript.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 Element extends BaseObj {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/FieldPacker.java b/v8/renderscript/java/src/android/support/v8/renderscript/FieldPacker.java
index 3934af2..9dbf8cc 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/FieldPacker.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/FieldPacker.java
@@ -20,7 +20,11 @@
/**
* Utility class for packing arguments and structures from Android system objects to
- * Renderscript objects.
+ * RenderScript objects.
+ *
+ * This class is only intended to be used to support the
+ * reflected code generated by the RS tool chain. It should not
+ * be called directly.
*
**/
public class FieldPacker {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Float2.java b/v8/renderscript/java/src/android/support/v8/renderscript/Float2.java
index 9bb29ae..edbc5aa 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Float2.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Float2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript float2 type back to the Android system.
+ * Class for exposing the native RenderScript float2 type back to the Android system.
*
**/
public class Float2 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Float3.java b/v8/renderscript/java/src/android/support/v8/renderscript/Float3.java
index 9dc2882..90162a1 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Float3.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Float3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript float2 type back to the Android system.
+ * Class for exposing the native RenderScript float2 type back to the Android system.
*
**/
public class Float3 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Float4.java b/v8/renderscript/java/src/android/support/v8/renderscript/Float4.java
index 604b563..d0dc568 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Float4.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Float4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript float2 type back to the Android system.
+ * Class for exposing the native RenderScript float2 type back to the Android system.
*
**/
public class Float4 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Int2.java b/v8/renderscript/java/src/android/support/v8/renderscript/Int2.java
index 2619a2d..e5d04b8 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Int2.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Int2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript int2 type back to the Android system.
+ * Class for exposing the native RenderScript int2 type back to the Android system.
*
**/
public class Int2 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Int3.java b/v8/renderscript/java/src/android/support/v8/renderscript/Int3.java
index 71af5d2..12f59e8 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Int3.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Int3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript int3 type back to the Android system.
+ * Class for exposing the native RenderScript int3 type back to the Android system.
*
**/
public class Int3 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Int4.java b/v8/renderscript/java/src/android/support/v8/renderscript/Int4.java
index aff218f..bb49fb1 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Int4.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Int4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript int4 type back to the Android system.
+ * Class for exposing the native RenderScript int4 type back to the Android system.
*
**/
public class Int4 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Long2.java b/v8/renderscript/java/src/android/support/v8/renderscript/Long2.java
index aa0dd21..b3c95f2 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Long2.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Long2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript long2 type back to the Android system.
+ * Class for exposing the native RenderScript long2 type back to the Android system.
**/
public class Long2 {
public Long2() {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Long3.java b/v8/renderscript/java/src/android/support/v8/renderscript/Long3.java
index bc9d63b..6ce0f83 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Long3.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Long3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript long3 type back to the Android system.
+ * Class for exposing the native RenderScript long3 type back to the Android system.
**/
public class Long3 {
public Long3() {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Long4.java b/v8/renderscript/java/src/android/support/v8/renderscript/Long4.java
index 9ce51e8..d44a321 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Long4.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Long4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript long4 type back to the Android system.
+ * Class for exposing the native RenderScript long4 type back to the Android system.
**/
public class Long4 {
public Long4() {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Matrix2f.java b/v8/renderscript/java/src/android/support/v8/renderscript/Matrix2f.java
index 75f0d22..9a8b5bf 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Matrix2f.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Matrix2f.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript rs_matrix2x2 type back to the Android system.
+ * Class for exposing the native RenderScript rs_matrix2x2 type back to the Android system.
*
**/
public class Matrix2f {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Matrix3f.java b/v8/renderscript/java/src/android/support/v8/renderscript/Matrix3f.java
index fb9542a..4528543 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Matrix3f.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Matrix3f.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript rs_matrix3x3 type back to the Android system.
+ * Class for exposing the native RenderScript rs_matrix3x3 type back to the Android system.
*
**/
public class Matrix3f {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Matrix4f.java b/v8/renderscript/java/src/android/support/v8/renderscript/Matrix4f.java
index a9891da..b9e5636 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Matrix4f.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Matrix4f.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript rs_matrix4x4 type back to the Android system.
+ * Class for exposing the native RenderScript rs_matrix4x4 type back to the Android system.
*
**/
public class Matrix4f {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/RSDriverException.java b/v8/renderscript/java/src/android/support/v8/renderscript/RSDriverException.java
index 57d14eb..d4ae341 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/RSDriverException.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/RSDriverException.java
@@ -19,7 +19,7 @@
/**
* Base class for all exceptions thrown by the Android
- * Renderscript
+ * RenderScript
*/
public class RSDriverException extends RSRuntimeException {
public RSDriverException(String string) {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/RSIllegalArgumentException.java b/v8/renderscript/java/src/android/support/v8/renderscript/RSIllegalArgumentException.java
index fcda626..378a49c 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/RSIllegalArgumentException.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/RSIllegalArgumentException.java
@@ -19,7 +19,7 @@
/**
* Base class for all exceptions thrown by the Android
- * Renderscript
+ * RenderScript
*/
public class RSIllegalArgumentException extends RSRuntimeException {
public RSIllegalArgumentException(String string) {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/RSInvalidStateException.java b/v8/renderscript/java/src/android/support/v8/renderscript/RSInvalidStateException.java
index eed218d..a5676a3 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/RSInvalidStateException.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/RSInvalidStateException.java
@@ -19,7 +19,7 @@
/**
* Base class for all exceptions thrown by the Android
- * Renderscript
+ * RenderScript
*/
public class RSInvalidStateException extends RSRuntimeException {
public RSInvalidStateException(String string) {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/RSRuntimeException.java b/v8/renderscript/java/src/android/support/v8/renderscript/RSRuntimeException.java
index 9721fa3..ec83365 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/RSRuntimeException.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/RSRuntimeException.java
@@ -19,7 +19,7 @@
/**
* Base class for all exceptions thrown by the Android
- * Renderscript
+ * RenderScript
*/
public class RSRuntimeException
extends java.lang.RuntimeException {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/RenderScript.java b/v8/renderscript/java/src/android/support/v8/renderscript/RenderScript.java
index 750b6f4..6b49285 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/RenderScript.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/RenderScript.java
@@ -32,15 +32,14 @@
import android.os.SystemProperties;
/**
- * Renderscript base master class. An instance of this class creates native
- * worker threads for processing commands from this object. This base class
- * does not provide any extended capabilities beyond simple data processing.
- * For extended capabilities use derived classes such as RenderScriptGL.
+ * This class provides access to a RenderScript context, which controls RenderScript
+ * initialization, resource management, and teardown. An instance of the RenderScript
+ * class must be created before any other RS objects can be created.
*
* <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 RenderScript {
@@ -91,9 +90,29 @@
f.mkdirs();
}
+ /**
+ * ContextType specifies the specific type of context to be created.
+ *
+ */
public enum ContextType {
+ /**
+ * NORMAL context, this is the default and what shipping apps should
+ * use.
+ */
NORMAL (0),
+
+ /**
+ * DEBUG context, perform extra runtime checks to validate the
+ * kernels and APIs are being used as intended. Get and SetElementAt
+ * will be bounds checked in this mode.
+ */
DEBUG (1),
+
+ /**
+ * PROFILE context, Intended to be used once the first time an
+ * application is run on a new device. This mode allows the runtime to
+ * do additional testing and performance tuning.
+ */
PROFILE (2);
int mID;
@@ -629,11 +648,14 @@
//
/**
- * Base class application should derive from for handling RS messages
- * coming from their scripts. When a script calls sendToClient the data
- * fields will be filled in and then the run method called by a message
- * handling thread. This will occur some time after sendToClient completes
- * in the script.
+ * The base class from which an application should derive in order
+ * to receive RS messages from scripts. When a script calls {@code
+ * rsSendToClient}, the data fields will be filled, and the run
+ * method will be called on a separate thread. This will occur
+ * some time after {@code rsSendToClient} completes in the script,
+ * as {@code rsSendToClient} is asynchronous. Message handlers are
+ * not guaranteed to have completed when {@link
+ * android.renderscript.RenderScript#finish} returns.
*
*/
public static class RSMessageHandler implements Runnable {
@@ -644,9 +666,10 @@
}
}
/**
- * If an application is expecting messages it should set this field to an
- * instance of RSMessage. This instance will receive all the user messages
- * sent from sendToClient by scripts from this context.
+ * If an application is expecting messages, it should set this
+ * field to an instance of {@link RSMessageHandler}. This
+ * instance will receive all the user messages sent from {@code
+ * sendToClient} by scripts from this context.
*
*/
RSMessageHandler mMessageCallback = null;
@@ -672,6 +695,9 @@
}
/**
+ * Place a message into the message queue to be sent back to the message
+ * handler once all previous commands have been executed.
+ *
* @hide
*
* @param id
@@ -682,9 +708,9 @@
}
/**
- * Runtime error base class. An application should derive from this class
- * if it wishes to install an error handler. When errors occur at runtime
- * the fields in this class will be filled and the run method called.
+ * The runtime error handler base class. An application should derive from this class
+ * if it wishes to install an error handler. When errors occur at runtime,
+ * the fields in this class will be filled, and the run method will be called.
*
*/
public static class RSErrorHandler implements Runnable {
@@ -697,7 +723,7 @@
/**
* Application Error handler. All runtime errors will be dispatched to the
* instance of RSAsyncError set here. If this field is null a
- * RSRuntimeException will instead be thrown with details about the error.
+ * {@link RSRuntimeException} will instead be thrown with details about the error.
* This will cause program termaination.
*
*/
@@ -723,10 +749,9 @@
}
/**
- * RenderScript worker threads priority enumeration. The default value is
- * NORMAL. Applications wishing to do background processing such as
- * wallpapers should set their priority to LOW to avoid starving forground
- * processes.
+ * RenderScript worker thread priority enumeration. The default value is
+ * NORMAL. Applications wishing to do background processing should set
+ * their priority to LOW to avoid starving forground processes.
*/
public enum Priority {
LOW (Process.THREAD_PRIORITY_BACKGROUND + (5 * Process.THREAD_PRIORITY_LESS_FAVORABLE)),
@@ -791,7 +816,7 @@
}
if (mRS.nContextGetUserMessage(mRS.mContext, rbuf) !=
RS_MESSAGE_TO_CLIENT_USER) {
- throw new RSDriverException("Error processing message from Renderscript.");
+ throw new RSDriverException("Error processing message from RenderScript.");
}
if(mRS.mMessageCallback != null) {
@@ -860,7 +885,7 @@
}
/**
- * Create a basic RenderScript context.
+ * Create a RenderScript context.
*
* @hide
* @param ctx The context.
@@ -901,7 +926,7 @@
}
/**
- * Create a basic RenderScript context.
+ * Create a RenderScript context.
*
* @param ctx The context.
* @return RenderScript
@@ -911,11 +936,12 @@
}
/**
- * Create a basic RenderScript context.
+ * Create a RenderScript context.
*
* @hide
*
* @param ctx The context.
+ * @param ct The type of context to be created.
* @return RenderScript
*/
public static RenderScript create(Context ctx, ContextType ct) {
@@ -934,8 +960,8 @@
}
/**
- * Wait for any commands in the fifo between the java bindings and native to
- * be processed.
+ * Wait for any pending asynchronous opeations (such as copies to a RS
+ * allocation or RS script executions) to complete.
*
*/
public void finish() {
@@ -943,8 +969,9 @@
}
/**
- * Destroy this renderscript context. Once this function is called its no
- * longer legal to use this or any objects created by this context.
+ * Destroys this RenderScript context. Once this function is called,
+ * using this context or any objects belonging to this context is
+ * illegal.
*
*/
public void destroy() {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Sampler.java b/v8/renderscript/java/src/android/support/v8/renderscript/Sampler.java
index 13ccc03..30236eb 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Sampler.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Sampler.java
@@ -28,9 +28,14 @@
import android.graphics.BitmapFactory;
/**
- * Sampler object which defines how data is extracted from textures. Samplers
- * are attached to Program objects (currently only ProgramFragment) when those objects
- * need to access texture data.
+ * Sampler object that defines how Allocations can be read as textures within a
+ * kernel. Samplers are used in conjunction with the {@code rsSample} runtime
+ * function to return values from normalized coordinates.
+ *
+ * Any Allocation used with a Sampler must have been created with {@link
+ * android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE}; using a Sampler on
+ * an {@link android.renderscript.Allocation} that was not created with {@link
+ * android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE} is undefined.
**/
public class Sampler extends BaseObj {
public enum Value {
@@ -255,9 +260,8 @@
}
/**
- * Builder for creating non-standard samplers. Usefull if mix and match of
- * wrap modes is necesary or if anisotropic filtering is desired.
- *
+ * Builder for creating non-standard samplers. This is only necessary if
+ * a Sampler with different min and mag modes is desired.
*/
public static class Builder {
RenderScript mRS;
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Script.java b/v8/renderscript/java/src/android/support/v8/renderscript/Script.java
index 596c387..8ac9171 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Script.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Script.java
@@ -19,7 +19,8 @@
import android.util.SparseArray;
/**
- *
+ * The parent class for all executable scripts. This should not be used by
+ * applications.
**/
public class Script extends BaseObj {
ScriptCThunker mT;
@@ -248,6 +249,15 @@
mRS.nScriptForEach(getID(mRS), slot, in_id, out_id, params);
}
+ /**
+ * Only intended for use by generated reflected code.
+ *
+ * @param slot
+ * @param ain
+ * @param aout
+ * @param v
+ * @param sc
+ */
protected void forEach(int slot, Allocation ain, Allocation aout, FieldPacker v, LaunchOptions sc) {
if (mT != null) {
mT.thunkForEach(slot, ain, aout, v, sc);
@@ -404,6 +414,10 @@
mRS.nScriptSetVarVE(getID(mRS), index, v.getData(), e.getID(mRS), dims);
}
+ /**
+ * Only intended for use by generated reflected code.
+ *
+ */
public static class Builder {
RenderScript mRS;
@@ -413,6 +427,10 @@
}
+ /**
+ * Only intended for use by generated reflected code.
+ *
+ */
public static class FieldBase {
protected Element mElement;
protected Allocation mAllocation;
@@ -445,16 +463,29 @@
}
}
+
+ /**
+ * Class used to specify clipping for a kernel launch.
+ *
+ */
public static final class LaunchOptions {
- protected int xstart = 0;
- protected int ystart = 0;
- protected int xend = 0;
- protected int yend = 0;
- protected int zstart = 0;
- protected int zend = 0;
+ private int xstart = 0;
+ private int ystart = 0;
+ private int xend = 0;
+ private int yend = 0;
+ private int zstart = 0;
+ private int zend = 0;
+ private int strategy;
- protected int strategy;
-
+ /**
+ * Set the X range. If the end value is set to 0 the X dimension is not
+ * clipped.
+ *
+ * @param xstartArg Must be >= 0
+ * @param xendArg Must be >= xstartArg
+ *
+ * @return LaunchOptions
+ */
public LaunchOptions setX(int xstartArg, int xendArg) {
if (xstartArg < 0 || xendArg <= xstartArg) {
throw new RSIllegalArgumentException("Invalid dimensions");
@@ -464,6 +495,15 @@
return this;
}
+ /**
+ * Set the Y range. If the end value is set to 0 the Y dimension is not
+ * clipped.
+ *
+ * @param ystartArg Must be >= 0
+ * @param yendArg Must be >= ystartArg
+ *
+ * @return LaunchOptions
+ */
public LaunchOptions setY(int ystartArg, int yendArg) {
if (ystartArg < 0 || yendArg <= ystartArg) {
throw new RSIllegalArgumentException("Invalid dimensions");
@@ -473,6 +513,15 @@
return this;
}
+ /**
+ * Set the Z range. If the end value is set to 0 the Z dimension is not
+ * clipped.
+ *
+ * @param zstartArg Must be >= 0
+ * @param zendArg Must be >= zstartArg
+ *
+ * @return LaunchOptions
+ */
public LaunchOptions setZ(int zstartArg, int zendArg) {
if (zstartArg < 0 || zendArg <= zstartArg) {
throw new RSIllegalArgumentException("Invalid dimensions");
@@ -483,21 +532,51 @@
}
+ /**
+ * Returns the current X start
+ *
+ * @return int current value
+ */
public int getXStart() {
return xstart;
}
+ /**
+ * Returns the current X end
+ *
+ * @return int current value
+ */
public int getXEnd() {
return xend;
}
+ /**
+ * Returns the current Y start
+ *
+ * @return int current value
+ */
public int getYStart() {
return ystart;
}
+ /**
+ * Returns the current Y end
+ *
+ * @return int current value
+ */
public int getYEnd() {
return yend;
}
+ /**
+ * Returns the current Z start
+ *
+ * @return int current value
+ */
public int getZStart() {
return zstart;
}
+ /**
+ * Returns the current Z end
+ *
+ * @return int current value
+ */
public int getZEnd() {
return zend;
}
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptC.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptC.java
index 2daeb8f..7b01154 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptC.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptC.java
@@ -30,7 +30,8 @@
import java.lang.reflect.Modifier;
/**
- *
+ * The superclass for all user-defined scripts. This is only
+ * intended to be used by the generated derived classes.
**/
public class ScriptC extends Script {
private static final String TAG = "ScriptC";
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptGroup.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptGroup.java
index 1d63708..c8ae482 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptGroup.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptGroup.java
@@ -20,24 +20,26 @@
import java.util.ArrayList;
/**
- * ScriptGroup creates a groups of scripts which are executed
- * together based upon upon one execution call as if they were
- * all part of a single script. The scripts may be connected
- * internally or to an external allocation. For the internal
- * connections the intermediate results are not observable after
- * the execution of the script.
+ * ScriptGroup creates a group of kernels that are executed
+ * together with one execution call as if they were a single kernel.
+ * The kernels may be connected internally or to an external allocation.
+ * The intermediate results for internal connections are not observable
+ * after the execution of the script.
* <p>
- * The external connections are grouped into inputs and outputs.
+ * External connections are grouped into inputs and outputs.
* All outputs are produced by a script kernel and placed into a
- * user supplied allocation. Inputs are similar but supply the
- * input of a kernal. Inputs bounds to a script are set directly
- * upon the script.
+ * user-supplied allocation. Inputs provide the input of a kernel.
+ * Inputs bound to script globals are set directly upon the script.
* <p>
* A ScriptGroup must contain at least one kernel. A ScriptGroup
* must contain only a single directed acyclic graph (DAG) of
* script kernels and connections. Attempting to create a
* ScriptGroup with multiple DAGs or attempting to create
* a cycle within a ScriptGroup will throw an exception.
+ * <p>
+ * Currently, all kernels in a ScriptGroup must be from separate
+ * Script objects. Attempting to use multiple kernels from the same
+ * Script object will result in an {@link android.renderscript.RSInvalidStateException}.
*
**/
public class ScriptGroup extends BaseObj {
@@ -93,8 +95,8 @@
/**
* Sets an input of the ScriptGroup. This specifies an
- * Allocation to be used for the kernels which require a kernel
- * input and that input is provided external to the group.
+ * Allocation to be used for kernels that require an input
+ * Allocation provided from outside of the ScriptGroup.
*
* @param s The ID of the kernel where the allocation should be
* connected.
@@ -113,8 +115,8 @@
/**
* Sets an output of the ScriptGroup. This specifies an
- * Allocation to be used for the kernels which require a kernel
- * output and that output is provided external to the group.
+ * Allocation to be used for the kernels that require an output
+ * Allocation visible after the ScriptGroup is executed.
*
* @param s The ID of the kernel where the allocation should be
* connected.
@@ -133,8 +135,8 @@
/**
* Execute the ScriptGroup. This will run all the kernels in
- * the script. The state of the connecting lines will not be
- * observable after this operation.
+ * the ScriptGroup. No internal connection results will be visible
+ * after execution of the ScriptGroup.
*/
public void execute() {
mRS.nScriptGroupExecute(getID(mRS));
@@ -142,20 +144,25 @@
/**
- * Create a ScriptGroup. There are two steps to creating a
- * ScriptGoup.
+ * Helper class to build a ScriptGroup. A ScriptGroup is
+ * created in two steps.
* <p>
- * First all the Kernels to be used by the group should be
- * added. Once this is done the kernels should be connected.
- * Kernels cannot be added once a connection has been made.
+ * First, all kernels to be used by the ScriptGroup should be added.
* <p>
- * Second, add connections. There are two forms of connections.
- * Kernel to Kernel and Kernel to Field. Kernel to Kernel is
- * higher performance and should be used where possible. The
- * line of connections cannot form a loop. If a loop is detected
- * an exception is thrown.
+ * Second, add connections between kernels. There are two types
+ * of connections: kernel to kernel and kernel to field.
+ * Kernel to kernel allows a kernel's output to be passed to
+ * another kernel as input. Kernel to field allows the output of
+ * one kernel to be bound as a script global. Kernel to kernel is
+ * higher performance and should be used where possible.
* <p>
- * Once all the connections are made a call to create will
+ * A ScriptGroup must contain a single directed acyclic graph (DAG); it
+ * cannot contain cycles. Currently, all kernels used in a ScriptGroup
+ * must come from different Script objects. Additionally, all kernels
+ * in a ScriptGroup must have at least one input, output, or internal
+ * connection.
+ * <p>
+ * Once all connections are made, a call to {@link #create} will
* return the ScriptGroup object.
*
*/
@@ -168,10 +175,10 @@
private ScriptGroupThunker.Builder mT;
/**
- * Create a builder for generating a ScriptGroup.
+ * Create a Builder for generating a ScriptGroup.
*
*
- * @param rs The Renderscript context.
+ * @param rs The RenderScript context.
*/
public Builder(RenderScript rs) {
if (rs.isNative) {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsic3DLUT.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsic3DLUT.java
index bcf1313..d8a7dcc 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsic3DLUT.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsic3DLUT.java
@@ -20,6 +20,11 @@
/**
*
+ * Intrinsic for converting RGB to RGBA by using a 3D lookup table. The
+ * incoming r,g,b values are use as normalized x,y,z coordinates into a 3D
+ * allocation. The 8 nearest values are sampled and linearly interpolated. The
+ * result is placed in the output.
+ *
* @hide
**/
public class ScriptIntrinsic3DLUT extends ScriptIntrinsic {
@@ -36,7 +41,7 @@
*
* The defaults tables are identity.
*
- * @param rs The Renderscript context
+ * @param rs The RenderScript context
* @param e Element type for intputs and outputs
*
* @return ScriptIntrinsic3DLUT
@@ -55,6 +60,13 @@
return new ScriptIntrinsic3DLUT(id, rs, e);
}
+ /**
+ * Sets the {@link android.renderscript.Allocation} to be used as the lookup table.
+ *
+ * The lookup table must use the same {@link android.renderscript.Element} as the intrinsic.
+ *
+ */
+
public void setLUT(Allocation lut) {
final Type t = lut.getType();
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicBlend.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicBlend.java
index db45a19..0e9b4da 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicBlend.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicBlend.java
@@ -18,8 +18,7 @@
/**
- * Intrinsic kernels for blending two buffers. Each blend function is a separate
- * kernel to make it easy to change between blend modes.
+ * Intrinsic kernels for blending two {@link android.renderscript.Allocation} objects.
**/
public class ScriptIntrinsicBlend extends ScriptIntrinsic {
ScriptIntrinsicBlend(int id, RenderScript rs) {
@@ -27,11 +26,10 @@
}
/**
- * Supported elements types are uchar4
+ * Supported elements types are {@link Element#U8_4}
*
- *
- * @param rs
- * @param e
+ * @param rs The RenderScript context
+ * @param e Element type for inputs and outputs
*
* @return ScriptIntrinsicBlend
*/
@@ -57,7 +55,7 @@
}
/**
- * dst = {0, 0, 0, 0}
+ * Sets dst = {0, 0, 0, 0}
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -77,7 +75,7 @@
/**
- * dst = src
+ * Sets dst = src
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -96,8 +94,9 @@
}
/**
- * dst = dst
- * This is a NOP
+ * Sets dst = dst
+ *
+ * This is a NOP.
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -116,7 +115,7 @@
}
/**
- * dst = src + dst * (1.0 - src.a)
+ * Sets dst = src + dst * (1.0 - src.a)
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -135,7 +134,7 @@
}
/**
- * dst = dst + src * (1.0 - dst.a)
+ * Sets dst = dst + src * (1.0 - dst.a)
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -154,7 +153,7 @@
}
/**
- * dst = src * dst.a
+ * Sets dst = src * dst.a
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -173,7 +172,7 @@
}
/**
- * dst = dst * src.a
+ * Sets dst = dst * src.a
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -192,7 +191,7 @@
}
/**
- * dst = src * (1.0 - dst.a)
+ * Sets dst = src * (1.0 - dst.a)
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -211,7 +210,7 @@
}
/**
- * dst = dst * (1.0 - src.a)
+ * Sets dst = dst * (1.0 - src.a)
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -270,7 +269,7 @@
}
/**
- * dst = {src.r ^ dst.r, src.g ^ dst.g, src.b ^ dst.b, src.a ^ dst.a}
+ * Sets dst = {src.r ^ dst.r, src.g ^ dst.g, src.b ^ dst.b, src.a ^ dst.a}
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -299,7 +298,7 @@
}
*/
/**
- * dst = src * dst
+ * Sets dst = src * dst
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -395,7 +394,7 @@
}
*/
/**
- * dst = min(src + dst, 1.0)
+ * Sets dst = min(src + dst, 1.0)
*
* @param ain The source buffer
* @param aout The destination buffer
@@ -414,7 +413,7 @@
}
/**
- * dst = max(dst - src, 0.0)
+ * Sets dst = max(dst - src, 0.0)
*
* @param ain The source buffer
* @param aout The destination buffer
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicBlur.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicBlur.java
index 302b8e8..b2b74cb 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicBlur.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicBlur.java
@@ -40,7 +40,7 @@
*
* Supported elements types are {@link Element#U8_4}
*
- * @param rs The Renderscript context
+ * @param rs The RenderScript context
* @param e Element type for inputs and outputs
*
* @return ScriptIntrinsicBlur
@@ -50,7 +50,7 @@
RenderScriptThunker rst = (RenderScriptThunker) rs;
return ScriptIntrinsicBlurThunker.create(rs, e);
}
- if ((e != Element.U8_4(rs)) && e != (Element.U8(rs))) {
+ if ((!e.isCompatible(Element.U8_4(rs))) && (!e.isCompatible(Element.U8(rs)))) {
throw new RSIllegalArgumentException("Unsuported element type.");
}
int id = rs.nScriptIntrinsicCreate(5, e.getID(rs));
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicColorMatrix.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicColorMatrix.java
index 9337303..f80d4ac 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicColorMatrix.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicColorMatrix.java
@@ -41,7 +41,7 @@
*
* Supported elements types are {@link Element#U8_4}
*
- * @param rs The Renderscript context
+ * @param rs The RenderScript context
* @param e Element type for intputs and outputs
*
* @return ScriptIntrinsicColorMatrix
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicConvolve3x3.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicConvolve3x3.java
index f3f8686..c902917 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicConvolve3x3.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicConvolve3x3.java
@@ -41,7 +41,7 @@
* <p> [ 0, 0, 0 ]
* </code>
*
- * @param rs The Renderscript context
+ * @param rs The RenderScript context
* @param e Element type for intputs and outputs
*
* @return ScriptIntrinsicConvolve3x3
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicConvolve5x5.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicConvolve5x5.java
index bb64090..a651c0f 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicConvolve5x5.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicConvolve5x5.java
@@ -42,7 +42,7 @@
* <p> [ 0, 0, 0, 0, 0 ]
* </code>
*
- * @param rs The Renderscript context
+ * @param rs The RenderScript context
* @param e Element type for intputs and outputs
*
* @return ScriptIntrinsicConvolve5x5
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicLUT.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicLUT.java
index 0445a65..1c0c819 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicLUT.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicLUT.java
@@ -39,7 +39,7 @@
*
* The defaults tables are identity.
*
- * @param rs The Renderscript context
+ * @param rs The RenderScript context
* @param e Element type for intputs and outputs
*
* @return ScriptIntrinsicLUT
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicYuvToRGB.java b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicYuvToRGB.java
index 7bd19c8..70e43ba 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicYuvToRGB.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/ScriptIntrinsicYuvToRGB.java
@@ -36,7 +36,7 @@
*
* Supported elements types are {@link Element#U8_4}
*
- * @param rs The Renderscript context
+ * @param rs The RenderScript context
* @param e Element type for output
*
* @return ScriptIntrinsicYuvToRGB
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Short2.java b/v8/renderscript/java/src/android/support/v8/renderscript/Short2.java
index 4100c95..365b319 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Short2.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Short2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript Short2 type back to the Android system.
+ * Class for exposing the native RenderScript Short2 type back to the Android system.
*
**/
public class Short2 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Short3.java b/v8/renderscript/java/src/android/support/v8/renderscript/Short3.java
index 275c146..abf8196 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Short3.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Short3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript short3 type back to the Android system.
+ * Class for exposing the native RenderScript short3 type back to the Android system.
*
**/
public class Short3 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Short4.java b/v8/renderscript/java/src/android/support/v8/renderscript/Short4.java
index d0480f8..d2108e4 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Short4.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Short4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the native Renderscript short4 type back to the Android system.
+ * Class for exposing the native RenderScript short4 type back to the Android system.
*
**/
public class Short4 {
diff --git a/v8/renderscript/java/src/android/support/v8/renderscript/Type.java b/v8/renderscript/java/src/android/support/v8/renderscript/Type.java
index ed29954..95ff6b1 100644
--- a/v8/renderscript/java/src/android/support/v8/renderscript/Type.java
+++ b/v8/renderscript/java/src/android/support/v8/renderscript/Type.java
@@ -23,24 +23,29 @@
import android.util.Log;
/**
- * <p>Type is an allocation template. It consists of an Element and one or more
- * dimensions. It describes only the layout of memory but does not allocate any
- * storage for the data that is described.</p>
+ * <p>A Type describes the {@link android.renderscript.Element} and dimensions used for an {@link
+ * android.renderscript.Allocation} or a parallel operation. Types are created through {@link
+ * android.renderscript.Type.Builder}.</p>
*
- * <p>A Type consists of several dimensions. Those are X, Y, Z, LOD (level of
- * detail), Faces (faces of a cube map). The X,Y,Z dimensions can be assigned
- * any positive integral value within the constraints of available memory. A
- * single dimension allocation would have an X dimension of greater than zero
- * while the Y and Z dimensions would be zero to indicate not present. In this
- * regard an allocation of x=10, y=1 would be considered 2 dimensionsal while
- * x=10, y=0 would be considered 1 dimensional.</p>
+ * <p>A Type always includes an {@link android.renderscript.Element} and an X
+ * dimension. A Type may be multidimensional, up to three dimensions. A nonzero
+ * value in the Y or Z dimensions indicates that the dimension is present. Note
+ * that a Type with only a given X dimension and a Type with the same X
+ * dimension but Y = 1 are not equivalent.</p>
*
- * <p>The LOD and Faces dimensions are booleans to indicate present or not present.</p>
+ * <p>A Type also supports inclusion of level of detail (LOD) or cube map
+ * faces. LOD and cube map faces are booleans to indicate present or not
+ * present. </p>
+ *
+ * <p>A Type also supports YUV format information to support an {@link
+ * android.renderscript.Allocation} in a YUV format. The YUV formats supported
+ * are {@link android.graphics.ImageFormat#YV12} and {@link
+ * android.graphics.ImageFormat#NV21}.</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/graphics/renderscript.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 Type extends BaseObj {
@@ -104,6 +109,17 @@
}
/**
+ * Get the YUV format
+ *
+ * @hide
+ *
+ * @return int
+ */
+ public int getYuv() {
+ return mDimYuv;
+ }
+
+ /**
* Return if the Type has a mipmap chain.
*
* @return boolean
@@ -122,13 +138,6 @@
}
/**
- * @hide
- */
- public int getYuv() {
- return mDimYuv;
- }
-
- /**
* Return the total number of accessable cells in the Type.
*
* @return int
@@ -247,9 +256,11 @@
}
/**
+ * Set the YUV layout for a Type.
+ *
* @hide
*
- * only NV21, YV12. Enums from ImageFormat
+ * @param yuvFormat {@link android.graphics.ImageFormat#YV12} or {@link android.graphics.ImageFormat#NV21}
*/
public Builder setYuvFormat(int yuvFormat) {
switch (yuvFormat) {
@@ -267,7 +278,7 @@
/**
- * Validate structure and create a new type.
+ * Validate structure and create a new Type.
*
* @return Type
*/
