diff options
53 files changed, 519 insertions, 504 deletions
diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java index e1b8c6c..362b586 100644 --- a/graphics/java/android/renderscript/Allocation.java +++ b/graphics/java/android/renderscript/Allocation.java @@ -31,46 +31,29 @@ import android.graphics.Canvas; import android.os.Trace; /** - * <p> - * Memory allocation class for renderscript. An allocation combines a - * {@link android.renderscript.Type} with the memory to provide storage for user data and objects. - * This implies that all memory in Renderscript is typed. - * </p> + * <p> This class provides the primary method through which data is passed to + * and from RenderScript kernels. An Allocation provides the backing store for + * a given {@link android.renderscript.Type}. </p> * - * <p>Allocations are the primary way data moves into and out of scripts. Memory is user - * synchronized and it's possible for allocations to exist in multiple memory spaces - * concurrently. Currently those spaces are:</p> - * <ul> - * <li>Script: accessable by RS scripts.</li> - * <li>Graphics Texture: accessable as a graphics texture.</li> - * <li>Graphics Vertex: accessable as graphical vertex data.</li> - * <li>Graphics Constants: Accessable as constants in user shaders</li> - * </ul> - * </p> - * <p> - * For example, when creating a allocation for a texture, the user can - * specify its memory spaces as both script and textures. This means that it can both - * be used as script binding and as a GPU texture for rendering. To maintain - * synchronization if a script modifies an allocation used by other targets it must - * call a synchronizing function to push the updates to the memory, otherwise the results - * are undefined. - * </p> - * <p>By default, Android system side updates are always applied to the script accessable - * memory. If this is not present, they are then applied to the various HW - * memory types. A {@link android.renderscript.Allocation#syncAll syncAll()} - * call is necessary after the script data is updated to - * keep the other memory spaces in sync.</p> + * <p>An Allocation also contains a set of usage flags that denote how the + * Allocation could be used. For example, an Allocation may have usage flags + * specifying that it can be used from a script as well as input to a {@link + * android.renderscript.Sampler}. A developer must synchronize across these + * different usages using {@link android.renderscript.Allocation#syncAll} in + * order to ensure that different users of the Allocation have a consistent view + * of memory. For example, in the case where an Allocation is used as the output + * of one kernel and as Sampler input in a later kernel, a developer must call + * {@link #syncAll syncAll(Allocation.USAGE_SCRIPT)} prior to launching the + * second kernel to ensure correctness. * - * <p>Allocation data is uploaded in one of two primary ways. For simple - * arrays there are copyFrom() functions that take an array from the control code and - * copy it to the slave memory store. Both type checked and unchecked copies are provided. - * The unchecked variants exist to allow apps to copy over arrays of structures from a - * control language that does not support structures.</p> + * <p>An Allocation can be populated with the {@link #copyFrom} routines. For + * more complex Element types, the {@link #copyFromUnchecked} methods can be + * used to copy from byte arrays or similar constructs.</p> * * <div class="special reference"> * <h3>Developer Guides</h3> - * <p>For more information about creating an application that uses Renderscript, read the - * <a href="{@docRoot}guide/topics/renderscript/index.html">Renderscript</a> developer guide.</p> + * <p>For more information about creating an application that uses RenderScript, read the + * <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer guide.</p> * </div> **/ public class Allocation extends BaseObj { @@ -98,97 +81,102 @@ public class Allocation extends BaseObj { new HashMap<Integer, Allocation>(); IoInputNotifier mBufferNotifier; - /** - * The usage of the allocation. These signal to renderscript - * where to place the allocation in memory. + * The usage of the Allocation. These signal to RenderScript where to place + * the Allocation in memory. * - * SCRIPT The allocation will be bound to and accessed by - * scripts. + */ + + /** + * The Allocation will be bound to and accessed by scripts. */ public static final int USAGE_SCRIPT = 0x0001; /** - * GRAPHICS_TEXTURE The allocation will be used as a texture - * source by one or more graphics programs. + * The Allocation will be used as a texture source by one or more graphics + * programs. * */ public static final int USAGE_GRAPHICS_TEXTURE = 0x0002; /** - * GRAPHICS_VERTEX The allocation will be used as a graphics - * mesh. + * The Allocation will be used as a graphics mesh. + * + * This was deprecated in API level 16. * */ public static final int USAGE_GRAPHICS_VERTEX = 0x0004; /** - * GRAPHICS_CONSTANTS The allocation will be used as the source - * of shader constants by one or more programs. + * The Allocation will be used as the source of shader constants by one or + * more programs. + * + * This was deprecated in API level 16. * */ public static final int USAGE_GRAPHICS_CONSTANTS = 0x0008; /** - * USAGE_GRAPHICS_RENDER_TARGET The allocation will be used as a - * target for offscreen rendering + * The Allocation will be used as a target for offscreen rendering + * + * This was deprecated in API level 16. * */ public static final int USAGE_GRAPHICS_RENDER_TARGET = 0x0010; /** - * USAGE_IO_INPUT The allocation will be used as SurfaceTexture - * consumer. This usage will cause the allocation to be created - * read only. + * The Allocation will be used as a {@link android.graphics.SurfaceTexture} + * consumer. This usage will cause the Allocation to be created as + * read-only. * */ public static final int USAGE_IO_INPUT = 0x0020; /** - * USAGE_IO_OUTPUT The allocation will be used as a - * SurfaceTexture producer. The dimensions and format of the - * SurfaceTexture will be forced to those of the allocation. + * The Allocation will be used as a {@link android.graphics.SurfaceTexture} + * producer. The dimensions and format of the {@link + * android.graphics.SurfaceTexture} will be forced to those of the + * Allocation. * */ public static final int USAGE_IO_OUTPUT = 0x0040; /** - * USAGE_SHARED The allocation's backing store will be inherited - * from another object (usually a Bitmap); calling appropriate - * copy methods will be significantly faster than if the entire - * allocation were copied every time. + * The Allocation's backing store will be inherited from another object + * (usually a {@link android.graphics.Bitmap}); copying to or from the + * original source Bitmap will cause a synchronization rather than a full + * copy. {@link #syncAll} may also be used to synchronize the Allocation + * and the source Bitmap. * - * This is set by default for allocations created with - * CreateFromBitmap(RenderScript, Bitmap) in API version 18 and - * higher. + * <p>This is set by default for allocations created with {@link + * #createFromBitmap} in API version 18 and higher.</p> * */ public static final int USAGE_SHARED = 0x0080; /** - * Controls mipmap behavior when using the bitmap creation and - * update functions. + * Controls mipmap behavior when using the bitmap creation and update + * functions. */ public enum MipmapControl { /** - * No mipmaps will be generated and the type generated from the - * incoming bitmap will not contain additional LODs. + * No mipmaps will be generated and the type generated from the incoming + * bitmap will not contain additional LODs. */ MIPMAP_NONE(0), /** - * A Full mipmap chain will be created in script memory. The - * type of the allocation will contain a full mipmap chain. On - * upload to graphics the full chain will be transfered. + * A full mipmap chain will be created in script memory. The Type of + * the Allocation will contain a full mipmap chain. On upload, the full + * chain will be transferred. */ MIPMAP_FULL(1), /** - * The type of the allocation will be the same as MIPMAP_NONE. - * It will not contain mipmaps. On upload to graphics the - * graphics copy of the allocation data will contain a full - * mipmap chain generated from the top level in script memory. + * The Type of the Allocation will be the same as MIPMAP_NONE. It will + * not contain mipmaps. On upload, the allocation data will contain a + * full mipmap chain generated from the top level in script memory. */ MIPMAP_ON_SYNC_TO_TEXTURE(2); @@ -208,10 +196,10 @@ public class Allocation extends BaseObj { /** - * Get the element of the type of the Allocation. + * Get the {@link android.renderscript.Element} of the {@link + * android.renderscript.Type} of the Allocation. * - * @return Element that describes the structure of data in the - * allocation + * @return Element * */ public Element getElement() { @@ -221,8 +209,7 @@ public class Allocation extends BaseObj { /** * Get the usage flags of the Allocation. * - * @return usage flags associated with the allocation. e.g. - * script, texture, etc. + * @return usage this Allocation's set of the USAGE_* flags OR'd together * */ public int getUsage() { @@ -351,7 +338,7 @@ public class Allocation extends BaseObj { } /** - * Get the type of the Allocation. + * Get the {@link android.renderscript.Type} of the Allocation. * * @return Type * @@ -361,8 +348,8 @@ public class Allocation extends BaseObj { } /** - * Propagate changes from one usage of the allocation to the - * remaining usages of the allocation. + * Propagate changes from one usage of the Allocation to the + * other usages of the Allocation. * */ public void syncAll(int srcLocation) { @@ -391,8 +378,10 @@ public class Allocation extends BaseObj { } /** - * Send a buffer to the output stream. The contents of the - * Allocation will be undefined after this operation. + * Send a buffer to the output stream. The contents of the Allocation will + * be undefined after this operation. This operation is only valid if {@link + * #USAGE_IO_OUTPUT} is set on the Allocation. + * * */ public void ioSend() { @@ -415,7 +404,8 @@ public class Allocation extends BaseObj { } /** - * Receive the latest input into the Allocation. + * Receive the latest input into the Allocation. This operation + * is only valid if {@link #USAGE_IO_INPUT} is set on the Allocation. * */ public void ioReceive() { @@ -430,7 +420,7 @@ public class Allocation extends BaseObj { } /** - * Copy an array of RS objects to the allocation. + * Copy an array of RS objects to the Allocation. * * @param d Source array. */ @@ -506,9 +496,9 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from an array. This variant is not type - * checked which allows an application to fill in structured - * data from an array. + * Copy into this Allocation from an array. This method does not guarantee + * that the Allocation is compatible with the input buffer; it copies memory + * without reinterpretation. * * @param d the source data array */ @@ -526,9 +516,9 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from an array. This variant is not type - * checked which allows an application to fill in structured - * data from an array. + * Copy into this Allocation from an array. This method does not guarantee + * that the Allocation is compatible with the input buffer; it copies memory + * without reinterpretation. * * @param d the source data array */ @@ -546,9 +536,9 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from an array. This variant is not type - * checked which allows an application to fill in structured - * data from an array. + * Copy into this Allocation from an array. This method does not guarantee + * that the Allocation is compatible with the input buffer; it copies memory + * without reinterpretation. * * @param d the source data array */ @@ -566,9 +556,9 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from an array. This variant is not type - * checked which allows an application to fill in structured - * data from an array. + * Copy into this Allocation from an array. This method does not guarantee + * that the Allocation is compatible with the input buffer; it copies memory + * without reinterpretation. * * @param d the source data array */ @@ -587,9 +577,9 @@ public class Allocation extends BaseObj { /** - * Copy an allocation from an array. This variant is type - * checked and will generate exceptions if the Allocation type - * is not a 32 bit integer type. + * Copy into this Allocation from an array. This variant is type checked + * and will generate exceptions if the Allocation's {@link + * android.renderscript.Element} is not a 32 bit integer type. * * @param d the source data array */ @@ -607,9 +597,9 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from an array. This variant is type - * checked and will generate exceptions if the Allocation type - * is not a 16 bit integer type. + * Copy into this Allocation from an array. This variant is type checked + * and will generate exceptions if the Allocation's {@link + * android.renderscript.Element} is not a 16 bit integer type. * * @param d the source data array */ @@ -627,9 +617,9 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from an array. This variant is type - * checked and will generate exceptions if the Allocation type - * is not a 8 bit integer type. + * Copy into this Allocation from an array. This variant is type checked + * and will generate exceptions if the Allocation's {@link + * android.renderscript.Element} is not an 8 bit integer type. * * @param d the source data array */ @@ -647,9 +637,9 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from an array. This variant is type - * checked and will generate exceptions if the Allocation type - * is not a 32 bit float type. + * Copy into this Allocation from an array. This variant is type checked + * and will generate exceptions if the Allocation's {@link + * android.renderscript.Element} is not a 32 bit float type. * * @param d the source data array */ @@ -667,8 +657,15 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from a bitmap. The height, width, and - * format of the bitmap must match the existing allocation. + * Copy into an Allocation from a {@link android.graphics.Bitmap}. The + * height, width, and format of the bitmap must match the existing + * allocation. + * + * <p>If the {@link android.graphics.Bitmap} is the same as the {@link + * android.graphics.Bitmap} used to create the Allocation with {@link + * #createFromBitmap} and {@link #USAGE_SHARED} is set on the Allocation, + * this will synchronize the Allocation with the latest data from the {@link + * android.graphics.Bitmap}, potentially avoiding the actual copy.</p> * * @param b the source bitmap */ @@ -689,7 +686,7 @@ public class Allocation extends BaseObj { } /** - * Copy an allocation from an allocation. The types of both allocations + * Copy an Allocation from an Allocation. The types of both allocations * must be identical. * * @param a the source allocation @@ -705,8 +702,8 @@ public class Allocation extends BaseObj { } /** - * This is only intended to be used by auto-generate code reflected from the - * renderscript script files. + * This is only intended to be used by auto-generated code reflected from + * the RenderScript script files and should not be used by developers. * * @param xoff * @param fp @@ -725,8 +722,8 @@ public class Allocation extends BaseObj { } /** - * This is only intended to be used by auto-generate code reflected from the - * renderscript script files. + * This is only intended to be used by auto-generated code reflected from + * the RenderScript script files. * * @param xoff * @param component_number @@ -772,23 +769,22 @@ public class Allocation extends BaseObj { } /** - * Generate a mipmap chain. Requires the type of the allocation - * include mipmaps. + * Generate a mipmap chain. This is only valid if the Type of the Allocation + * includes mipmaps. * - * This function will generate a complete set of mipmaps from - * the top level lod and place them into the script memoryspace. + * <p>This function will generate a complete set of mipmaps from the top + * level LOD and place them into the script memory space.</p> * - * If the allocation is also using other memory spaces a - * followup sync will be required. + * <p>If the Allocation is also using other memory spaces, a call to {@link + * #syncAll syncAll(Allocation.USAGE_SCRIPT)} is required.</p> */ public void generateMipmaps() { mRS.nAllocationGenerateMipmaps(getID(mRS)); } /** - * Copy part of an allocation from an array. This variant is - * not type checked which allows an application to fill in - * structured data from an array. + * Copy an array into part of this Allocation. This method does not + * guarantee that the Allocation is compatible with the input buffer. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -803,9 +799,8 @@ public class Allocation extends BaseObj { } /** - * Copy part of an allocation from an array. This variant is - * not type checked which allows an application to fill in - * structured data from an array. + * Copy an array into part of this Allocation. This method does not + * guarantee that the Allocation is compatible with the input buffer. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -820,9 +815,8 @@ public class Allocation extends BaseObj { } /** - * Copy part of an allocation from an array. This variant is - * not type checked which allows an application to fill in - * structured data from an array. + * Copy an array into part of this Allocation. This method does not + * guarantee that the Allocation is compatible with the input buffer. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -837,9 +831,8 @@ public class Allocation extends BaseObj { } /** - * Copy part of an allocation from an array. This variant is - * not type checked which allows an application to fill in - * structured data from an array. + * Copy an array into part of this Allocation. This method does not + * guarantee that the Allocation is compatible with the input buffer. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -854,9 +847,9 @@ public class Allocation extends BaseObj { } /** - * Copy part of an allocation from an array. This variant is - * type checked and will generate exceptions if the Allocation - * type is not a 32 bit integer type. + * Copy an array into part of this Allocation. This variant is type checked + * and will generate exceptions if the Allocation type is not a 32 bit + * integer type. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -870,9 +863,9 @@ public class Allocation extends BaseObj { } /** - * Copy part of an allocation from an array. This variant is - * type checked and will generate exceptions if the Allocation - * type is not a 16 bit integer type. + * Copy an array into part of this Allocation. This variant is type checked + * and will generate exceptions if the Allocation type is not a 16 bit + * integer type. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -886,9 +879,9 @@ public class Allocation extends BaseObj { } /** - * Copy part of an allocation from an array. This variant is - * type checked and will generate exceptions if the Allocation - * type is not a 8 bit integer type. + * Copy an array into part of this Allocation. This variant is type checked + * and will generate exceptions if the Allocation type is not an 8 bit + * integer type. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -902,9 +895,9 @@ public class Allocation extends BaseObj { } /** - * Copy part of an allocation from an array. This variant is - * type checked and will generate exceptions if the Allocation - * type is not a 32 bit float type. + * Copy an array into part of this Allocation. This variant is type checked + * and will generate exceptions if the Allocation type is not a 32 bit float + * type. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -917,7 +910,7 @@ public class Allocation extends BaseObj { Trace.traceEnd(RenderScript.TRACE_TAG); } /** - * Copy part of an allocation from another allocation. + * Copy part of an Allocation into this Allocation. * * @param off The offset of the first element to be copied. * @param count The number of elements to be copied. @@ -987,14 +980,14 @@ public class Allocation extends BaseObj { } /** - * Copy a rectangular region from the array into the allocation. - * The incoming array is assumed to be tightly packed. + * Copy from an array into a rectangular region in this Allocation. The + * array is assumed to be tightly packed. * - * @param xoff X offset of the region to update - * @param yoff Y offset of the region to update - * @param w Width of the incoming region to update - * @param h Height of the incoming region to update - * @param data to be placed into the allocation + * @param xoff X offset of the region to update in this Allocation + * @param yoff Y offset of the region to update in this Allocation + * @param w Width of the region to update + * @param h Height of the region to update + * @param data to be placed into the Allocation */ public void copy2DRangeFrom(int xoff, int yoff, int w, int h, byte[] data) { Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom"); @@ -1003,6 +996,16 @@ public class Allocation extends BaseObj { Trace.traceEnd(RenderScript.TRACE_TAG); } + /** + * Copy from an array into a rectangular region in this Allocation. The + * array is assumed to be tightly packed. + * + * @param xoff X offset of the region to update in this Allocation + * @param yoff Y offset of the region to update in this Allocation + * @param w Width of the region to update + * @param h Height of the region to update + * @param data to be placed into the Allocation + */ public void copy2DRangeFrom(int xoff, int yoff, int w, int h, short[] data) { Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom"); validateIsInt16(); @@ -1010,6 +1013,16 @@ public class Allocation extends BaseObj { Trace.traceEnd(RenderScript.TRACE_TAG); } + /** + * Copy from an array into a rectangular region in this Allocation. The + * array is assumed to be tightly packed. + * + * @param xoff X offset of the region to update in this Allocation + * @param yoff Y offset of the region to update in this Allocation + * @param w Width of the region to update + * @param h Height of the region to update + * @param data to be placed into the Allocation + */ public void copy2DRangeFrom(int xoff, int yoff, int w, int h, int[] data) { Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom"); validateIsInt32(); @@ -1017,6 +1030,16 @@ public class Allocation extends BaseObj { Trace.traceEnd(RenderScript.TRACE_TAG); } + /** + * Copy from an array into a rectangular region in this Allocation. The + * array is assumed to be tightly packed. + * + * @param xoff X offset of the region to update in this Allocation + * @param yoff Y offset of the region to update in this Allocation + * @param w Width of the region to update + * @param h Height of the region to update + * @param data to be placed into the Allocation + */ public void copy2DRangeFrom(int xoff, int yoff, int w, int h, float[] data) { Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom"); validateIsFloat32(); @@ -1025,16 +1048,16 @@ public class Allocation extends BaseObj { } /** - * Copy a rectangular region into the allocation from another - * allocation. + * Copy a rectangular region from an Allocation into a rectangular region in + * this Allocation. * - * @param xoff X offset of the region to update. - * @param yoff Y offset of the region to update. - * @param w Width of the incoming region to update. - * @param h Height of the incoming region to update. - * @param data source allocation. - * @param dataXoff X offset in data of the region to update. - * @param dataYoff Y offset in data of the region to update. + * @param xoff X offset of the region in this Allocation + * @param yoff Y offset of the region in this Allocation + * @param w Width of the region to update. + * @param h Height of the region to update. + * @param data source Allocation. + * @param dataXoff X offset in source Allocation + * @param dataYoff Y offset in source Allocation */ public void copy2DRangeFrom(int xoff, int yoff, int w, int h, Allocation data, int dataXoff, int dataYoff) { @@ -1049,13 +1072,13 @@ public class Allocation extends BaseObj { } /** - * Copy a bitmap into an allocation. The height and width of - * the update will use the height and width of the incoming - * bitmap. + * Copy a {@link android.graphics.Bitmap} into an Allocation. The height + * and width of the update will use the height and width of the {@link + * android.graphics.Bitmap}. * - * @param xoff X offset of the region to update - * @param yoff Y offset of the region to update - * @param data the bitmap to be copied + * @param xoff X offset of the region to update in this Allocation + * @param yoff Y offset of the region to update in this Allocation + * @param data the Bitmap to be copied */ public void copy2DRangeFrom(int xoff, int yoff, Bitmap data) { Trace.traceBegin(RenderScript.TRACE_TAG, "copy2DRangeFrom"); @@ -1138,14 +1161,14 @@ public class Allocation extends BaseObj { /** * @hide * Copy a rectangular region from the array into the allocation. - * The incoming array is assumed to be tightly packed. - * - * @param xoff X offset of the region to update - * @param yoff Y offset of the region to update - * @param zoff Z offset of the region to update - * @param w Width of the incoming region to update - * @param h Height of the incoming region to update - * @param d Depth of the incoming region to update + * The array is assumed to be tightly packed. + * + * @param xoff X offset of the region to update in this Allocation + * @param yoff Y offset of the region to update in this Allocation + * @param zoff Z offset of the region to update in this Allocation + * @param w Width of the region to update + * @param h Height of the region to update + * @param d Depth of the region to update * @param data to be placed into the allocation */ public void copy3DRangeFrom(int xoff, int yoff, int zoff, int w, int h, int d, byte[] data) { @@ -1185,15 +1208,16 @@ public class Allocation extends BaseObj { * Copy a rectangular region into the allocation from another * allocation. * - * @param xoff X offset of the region to update. - * @param yoff Y offset of the region to update. - * @param w Width of the incoming region to update. - * @param h Height of the incoming region to update. - * @param d Depth of the incoming region to update. + * @param xoff X offset of the region to update in this Allocation + * @param yoff Y offset of the region to update in this Allocation + * @param zoff Z offset of the region to update in this Allocation + * @param w Width of the region to update. + * @param h Height of the region to update. + * @param d Depth of the region to update. * @param data source allocation. - * @param dataXoff X offset in data of the region to update. - * @param dataYoff Y offset in data of the region to update. - * @param dataZoff Z offset in data of the region to update + * @param dataXoff X offset of the region in the source Allocation + * @param dataYoff Y offset of the region in the source Allocation + * @param dataZoff Z offset of the region in the source Allocation */ public void copy3DRangeFrom(int xoff, int yoff, int zoff, int w, int h, int d, Allocation data, int dataXoff, int dataYoff, int dataZoff) { @@ -1206,8 +1230,8 @@ public class Allocation extends BaseObj { /** - * Copy from the Allocation into a Bitmap. The bitmap must - * match the dimensions of the Allocation. + * Copy from the Allocation into a {@link android.graphics.Bitmap}. The + * bitmap must match the dimensions of the Allocation. * * @param b The bitmap to be set from the Allocation. */ @@ -1221,9 +1245,9 @@ public class Allocation extends BaseObj { } /** - * Copy from the Allocation into a byte array. The array must - * be at least as large as the Allocation. The allocation must - * be of an 8 bit elemental type. + * Copy from the Allocation into a byte array. The array must be at least + * as large as the Allocation. The allocation must be of an 8 bit integer + * {@link android.renderscript.Element} type. * * @param d The array to be set from the Allocation. */ @@ -1236,9 +1260,9 @@ public class Allocation extends BaseObj { } /** - * Copy from the Allocation into a short array. The array must - * be at least as large as the Allocation. The allocation must - * be of an 16 bit elemental type. + * Copy from the Allocation into a short array. The array must be at least + * as large as the Allocation. The allocation must be of an 16 bit integer + * {@link android.renderscript.Element} type. * * @param d The array to be set from the Allocation. */ @@ -1251,9 +1275,9 @@ public class Allocation extends BaseObj { } /** - * Copy from the Allocation into a int array. The array must be - * at least as large as the Allocation. The allocation must be - * of an 32 bit elemental type. + * Copy from the Allocation into a int array. The array must be at least as + * large as the Allocation. The allocation must be of an 32 bit integer + * {@link android.renderscript.Element} type. * * @param d The array to be set from the Allocation. */ @@ -1266,9 +1290,9 @@ public class Allocation extends BaseObj { } /** - * Copy from the Allocation into a float array. The array must - * be at least as large as the Allocation. The allocation must - * be of an 32 bit float elemental type. + * Copy from the Allocation into a float array. The array must be at least + * as large as the Allocation. The allocation must be of an 32 bit float + * {@link android.renderscript.Element} type. * * @param d The array to be set from the Allocation. */ @@ -1281,20 +1305,19 @@ public class Allocation extends BaseObj { } /** - * Resize a 1D allocation. The contents of the allocation are - * preserved. If new elements are allocated objects are created - * with null contents and the new region is otherwise undefined. + * Resize a 1D allocation. The contents of the allocation are preserved. + * If new elements are allocated objects are created with null contents and + * the new region is otherwise undefined. * - * If the new region is smaller the references of any objects - * outside the new region will be released. + * <p>If the new region is smaller the references of any objects outside the + * new region will be released.</p> * - * A new type will be created with the new dimension. + * <p>A new type will be created with the new dimension.</p> * * @param dimX The new size of the allocation. * - * @deprecated Renderscript objects should be immutable once - * created. The replacement is to create a new allocation and copy the - * contents. + * @deprecated RenderScript objects should be immutable once created. The + * replacement is to create a new allocation and copy the contents. */ public synchronized void resize(int dimX) { if ((mType.getY() > 0)|| (mType.getZ() > 0) || mType.hasFaces() || mType.hasMipmaps()) { @@ -1318,11 +1341,13 @@ public class Allocation extends BaseObj { } /** + * Creates a new Allocation with the given {@link + * android.renderscript.Type}, mipmap flag, and usage flags. * - * @param type renderscript type describing data layout + * @param type RenderScript type describing data layout * @param mips specifies desired mipmap behaviour for the * allocation - * @param usage bit field specifying how the allocation is + * @param usage bit field specifying how the Allocation is * utilized */ static public Allocation createTyped(RenderScript rs, Type type, MipmapControl mips, int usage) { @@ -1340,8 +1365,8 @@ public class Allocation extends BaseObj { } /** - * Creates a renderscript allocation with the size specified by - * the type and no mipmaps generated by default + * Creates an Allocation with the size specified by the type and no mipmaps + * generated by default * * @param rs Context to which the allocation will belong. * @param type renderscript type describing data layout @@ -1355,12 +1380,11 @@ public class Allocation extends BaseObj { } /** - * Creates a renderscript allocation for use by the script with - * the size specified by the type and no mipmaps generated by - * default + * Creates an Allocation for use by scripts with a given {@link + * android.renderscript.Type} and no mipmaps * - * @param rs Context to which the allocation will belong. - * @param type renderscript type describing data layout + * @param rs Context to which the Allocation will belong. + * @param type RenderScript Type describing data layout * * @return allocation */ @@ -1369,13 +1393,12 @@ public class Allocation extends BaseObj { } /** - * Creates a renderscript allocation with a specified number of - * given elements + * Creates an Allocation with a specified number of given elements * - * @param rs Context to which the allocation will belong. - * @param e describes what each element of an allocation is - * @param count specifies the number of element in the allocation - * @param usage bit field specifying how the allocation is + * @param rs Context to which the Allocation will belong. + * @param e Element to use in the Allocation + * @param count the number of Elements in the Allocation + * @param usage bit field specifying how the Allocation is * utilized * * @return allocation @@ -1397,12 +1420,11 @@ public class Allocation extends BaseObj { } /** - * Creates a renderscript allocation with a specified number of - * given elements + * Creates an Allocation with a specified number of given elements * - * @param rs Context to which the allocation will belong. - * @param e describes what each element of an allocation is - * @param count specifies the number of element in the allocation + * @param rs Context to which the Allocation will belong. + * @param e Element to use in the Allocation + * @param count the number of Elements in the Allocation * * @return allocation */ @@ -1438,16 +1460,16 @@ public class Allocation extends BaseObj { } /** - * Creates a renderscript allocation from a bitmap + * Creates an Allocation from a {@link android.graphics.Bitmap}. * * @param rs Context to which the allocation will belong. - * @param b bitmap source for the allocation data + * @param b Bitmap source for the allocation data * @param mips specifies desired mipmap behaviour for the * allocation * @param usage bit field specifying how the allocation is * utilized * - * @return renderscript allocation containing bitmap data + * @return Allocation containing bitmap data * */ static public Allocation createFromBitmap(RenderScript rs, Bitmap b, @@ -1494,9 +1516,9 @@ public class Allocation extends BaseObj { } /** - * For allocations used with io operations, returns the handle - * onto a raw buffer that is being managed by the screen - * compositor. + * Returns the handle to a raw buffer that is being managed by the screen + * compositor. This operation is only valid for Allocations with {@link + * #USAGE_IO_INPUT}. * * @return Surface object associated with allocation * @@ -1516,7 +1538,8 @@ public class Allocation extends BaseObj { } /** - * Associate a surface for io output with this allocation + * Associate a {@link android.view.Surface} with this Allocation. This + * operation is only valid for Allocations with {@link #USAGE_IO_OUTPUT}. * * @param sur Surface to associate with allocation */ @@ -1530,16 +1553,17 @@ public class Allocation extends BaseObj { } /** - * Creates a RenderScript allocation from a bitmap. + * Creates an Allocation from a {@link android.graphics.Bitmap}. * - * With target API version 18 or greater, this allocation will be - * created with USAGE_SHARED. With target API version 17 or lower, - * this allocation will be created with USAGE_GRAPHICS_TEXTURE. + * <p>With target API version 18 or greater, this Allocation will be created + * with {@link #USAGE_SHARED}, {@link #USAGE_SCRIPT}, and {@link + * #USAGE_GRAPHICS_TEXTURE}. With target API version 17 or lower, this + * Allocation will be created with {@link #USAGE_GRAPHICS_TEXTURE}.</p> * * @param rs Context to which the allocation will belong. * @param b bitmap source for the allocation data * - * @return renderscript allocation containing bitmap data + * @return Allocation containing bitmap data * */ static public Allocation createFromBitmap(RenderScript rs, Bitmap b) { @@ -1552,12 +1576,13 @@ public class Allocation extends BaseObj { } /** - * Creates a cubemap allocation from a bitmap containing the - * horizontal list of cube faces. Each individual face must be - * the same size and power of 2 + * Creates a cubemap Allocation from a {@link android.graphics.Bitmap} + * containing the horizontal list of cube faces. Each face must be a square, + * have the same size as all other faces, and have a width that is a power + * of 2. * * @param rs Context to which the allocation will belong. - * @param b bitmap with cubemap faces layed out in the following + * @param b Bitmap with cubemap faces layed out in the following * format: right, left, top, bottom, front, back * @param mips specifies desired mipmap behaviour for the cubemap * @param usage bit field specifying how the cubemap is utilized @@ -1600,10 +1625,10 @@ public class Allocation extends BaseObj { } /** - * Creates a non-mipmapped cubemap allocation for use as a - * graphics texture from a bitmap containing the horizontal list - * of cube faces. Each individual face must be the same size and - * power of 2 + * Creates a non-mipmapped cubemap Allocation for use as a graphics texture + * from a {@link android.graphics.Bitmap} containing the horizontal list of + * cube faces. Each face must be a square, have the same size as all other + * faces, and have a width that is a power of 2. * * @param rs Context to which the allocation will belong. * @param b bitmap with cubemap faces layed out in the following @@ -1619,9 +1644,9 @@ public class Allocation extends BaseObj { } /** - * Creates a cubemap allocation from 6 bitmaps containing - * the cube faces. All the faces must be the same size and - * power of 2 + * Creates a cubemap Allocation from 6 {@link android.graphics.Bitmap} + * objects containing the cube faces. Each face must be a square, have the + * same size as all other faces, and have a width that is a power of 2. * * @param rs Context to which the allocation will belong. * @param xpos cubemap face in the positive x direction @@ -1686,10 +1711,10 @@ public class Allocation extends BaseObj { } /** - * Creates a non-mipmapped cubemap allocation for use as a - * graphics texture from 6 bitmaps containing - * the cube faces. All the faces must be the same size and - * power of 2 + * Creates a non-mipmapped cubemap Allocation for use as a sampler input + * from 6 {@link android.graphics.Bitmap} objects containing the cube + * faces. Each face must be a square, have the same size as all other faces, + * and have a width that is a power of 2. * * @param rs Context to which the allocation will belong. * @param xpos cubemap face in the positive x direction @@ -1715,8 +1740,8 @@ public class Allocation extends BaseObj { } /** - * Creates a renderscript allocation from the bitmap referenced - * by resource id + * Creates an Allocation from the Bitmap referenced + * by resource ID. * * @param rs Context to which the allocation will belong. * @param res application resources @@ -1726,7 +1751,7 @@ public class Allocation extends BaseObj { * @param usage bit field specifying how the allocation is * utilized * - * @return renderscript allocation containing resource data + * @return Allocation containing resource data * */ static public Allocation createFromBitmapResource(RenderScript rs, @@ -1746,18 +1771,19 @@ public class Allocation extends BaseObj { } /** - * Creates a non-mipmapped renderscript allocation to use as a - * graphics texture from the bitmap referenced by resource id + * Creates a non-mipmapped Allocation to use as a graphics texture from the + * {@link android.graphics.Bitmap} referenced by resource ID. * - * With target API version 18 or greater, this allocation will be - * created with USAGE_SHARED. With target API version 17 or lower, - * this allocation will be created with USAGE_GRAPHICS_TEXTURE. + * <p>With target API version 18 or greater, this allocation will be created + * with {@link #USAGE_SCRIPT} and {@link #USAGE_GRAPHICS_TEXTURE}. With + * target API version 17 or lower, this allocation will be created with + * {@link #USAGE_GRAPHICS_TEXTURE}.</p> * * @param rs Context to which the allocation will belong. * @param res application resources * @param id resource id to load the data from * - * @return renderscript allocation containing resource data + * @return Allocation containing resource data * */ static public Allocation createFromBitmapResource(RenderScript rs, @@ -1774,8 +1800,7 @@ public class Allocation extends BaseObj { } /** - * Creates a renderscript allocation containing string data - * encoded in UTF-8 format + * Creates an Allocation containing string data encoded in UTF-8 format. * * @param rs Context to which the allocation will belong. * @param str string to create the allocation from @@ -1802,11 +1827,10 @@ public class Allocation extends BaseObj { /** * @hide * - * Interface to handle notification when new buffers are - * available via USAGE_IO_INPUT. An application will receive - * one notification when a buffer is available. Additional - * buffers will not trigger new notifications until a buffer is - * processed. + * Interface to handle notification when new buffers are available via + * {@link #USAGE_IO_INPUT}. An application will receive one notification + * when a buffer is available. Additional buffers will not trigger new + * notifications until a buffer is processed. */ public interface IoInputNotifier { public void onBufferAvailable(Allocation a); @@ -1815,7 +1839,7 @@ public class Allocation extends BaseObj { /** * @hide * - * Set a notification handler for USAGE_IO_INPUT + * Set a notification handler for {@link #USAGE_IO_INPUT}. * * @param callback instance of the IoInputNotifier class to be called * when buffer arrive. @@ -1839,4 +1863,3 @@ public class Allocation extends BaseObj { } - diff --git a/graphics/java/android/renderscript/AllocationAdapter.java b/graphics/java/android/renderscript/AllocationAdapter.java index 85d86e5..a6645bb 100644 --- a/graphics/java/android/renderscript/AllocationAdapter.java +++ b/graphics/java/android/renderscript/AllocationAdapter.java @@ -22,6 +22,7 @@ import android.graphics.BitmapFactory; import android.util.TypedValue; /** + * Only intended for use by generated reflected code. * **/ public class AllocationAdapter extends Allocation { diff --git a/graphics/java/android/renderscript/BaseObj.java b/graphics/java/android/renderscript/BaseObj.java index f464f9b..e17d79a 100644 --- a/graphics/java/android/renderscript/BaseObj.java +++ b/graphics/java/android/renderscript/BaseObj.java @@ -19,9 +19,9 @@ package android.renderscript; 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 { @@ -75,8 +75,7 @@ public class BaseObj { /** * setName assigns a name to an object. This object can later be looked up - * by this name. This name will also be retained if the object is written - * to an A3D file. + * by this name. * * @param name The name to assign to the object. */ @@ -125,10 +124,9 @@ public class BaseObj { } /** - * 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/graphics/java/android/renderscript/Byte2.java b/graphics/java/android/renderscript/Byte2.java index 7df5f2e..cf34f3a 100644 --- a/graphics/java/android/renderscript/Byte2.java +++ b/graphics/java/android/renderscript/Byte2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Byte3.java b/graphics/java/android/renderscript/Byte3.java index 02a01c1..266e94d 100644 --- a/graphics/java/android/renderscript/Byte3.java +++ b/graphics/java/android/renderscript/Byte3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Byte4.java b/graphics/java/android/renderscript/Byte4.java index a55a696..68c8f52 100644 --- a/graphics/java/android/renderscript/Byte4.java +++ b/graphics/java/android/renderscript/Byte4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Double2.java b/graphics/java/android/renderscript/Double2.java index 9f4f328..29fd515 100644 --- a/graphics/java/android/renderscript/Double2.java +++ b/graphics/java/android/renderscript/Double2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Double3.java b/graphics/java/android/renderscript/Double3.java index eb55142..818952e 100644 --- a/graphics/java/android/renderscript/Double3.java +++ b/graphics/java/android/renderscript/Double3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Double4.java b/graphics/java/android/renderscript/Double4.java index 4755a76..7775ab7 100644 --- a/graphics/java/android/renderscript/Double4.java +++ b/graphics/java/android/renderscript/Double4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Element.java b/graphics/java/android/renderscript/Element.java index f6c07d1..3838c61 100644 --- a/graphics/java/android/renderscript/Element.java +++ b/graphics/java/android/renderscript/Element.java @@ -20,31 +20,37 @@ import java.lang.reflect.Field; 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/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 Element extends BaseObj { diff --git a/graphics/java/android/renderscript/FieldPacker.java b/graphics/java/android/renderscript/FieldPacker.java index 730d973..fed97d6 100644 --- a/graphics/java/android/renderscript/FieldPacker.java +++ b/graphics/java/android/renderscript/FieldPacker.java @@ -21,7 +21,7 @@ import java.util.BitSet; /** * 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 diff --git a/graphics/java/android/renderscript/FileA3D.java b/graphics/java/android/renderscript/FileA3D.java index 8b0222a..e41f02d 100644 --- a/graphics/java/android/renderscript/FileA3D.java +++ b/graphics/java/android/renderscript/FileA3D.java @@ -30,9 +30,9 @@ import android.util.TypedValue; /** * @hide * @deprecated in API 16 - * FileA3D allows users to load Renderscript objects from files + * FileA3D allows users to load RenderScript objects from files * or resources stored on disk. It could be used to load items - * such as 3D geometry data converted to a Renderscript format from + * such as 3D geometry data converted to a RenderScript format from * content creation tools. Currently only meshes are supported * in FileA3D. * @@ -56,7 +56,7 @@ public class FileA3D extends BaseObj { UNKNOWN (0), /** * @deprecated in API 16 - * Renderscript Mesh object + * RenderScript Mesh object **/ MESH (1); @@ -72,7 +72,7 @@ public class FileA3D extends BaseObj { /** * @deprecated in API 16 - * IndexEntry contains information about one of the Renderscript + * IndexEntry contains information about one of the RenderScript * objects inside the file's index. It could be used to query the * object's type and also name and load the object itself if * necessary. diff --git a/graphics/java/android/renderscript/Float2.java b/graphics/java/android/renderscript/Float2.java index 1d4ce36..0f730fe 100644 --- a/graphics/java/android/renderscript/Float2.java +++ b/graphics/java/android/renderscript/Float2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Float3.java b/graphics/java/android/renderscript/Float3.java index ffd1135..749865f 100644 --- a/graphics/java/android/renderscript/Float3.java +++ b/graphics/java/android/renderscript/Float3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Float4.java b/graphics/java/android/renderscript/Float4.java index c7cc3ae..7ddf6aa 100644 --- a/graphics/java/android/renderscript/Float4.java +++ b/graphics/java/android/renderscript/Float4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Font.java b/graphics/java/android/renderscript/Font.java index 1a8d5bf..0375d2b 100644 --- a/graphics/java/android/renderscript/Font.java +++ b/graphics/java/android/renderscript/Font.java @@ -39,7 +39,7 @@ import android.util.TypedValue; * faces, and different font sizes. During creation, the Android system quieries device's screen DPI to * ensure proper sizing across multiple device configurations.</p> * <p>Fonts are rendered using screen-space positions and no state setup beyond binding a - * font to the Renderscript is required. A note of caution on performance, though the state changes + * font to the RenderScript is required. A note of caution on performance, though the state changes * are transparent to the user, they do happen internally, and it is more efficient to * render large batches of text in sequence. It is also more efficient to render multiple * characters at once instead of one by one to improve draw call batching.</p> diff --git a/graphics/java/android/renderscript/Int2.java b/graphics/java/android/renderscript/Int2.java index 434af21..71b5dd5 100644 --- a/graphics/java/android/renderscript/Int2.java +++ b/graphics/java/android/renderscript/Int2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Int3.java b/graphics/java/android/renderscript/Int3.java index 333ccf8..719c908 100644 --- a/graphics/java/android/renderscript/Int3.java +++ b/graphics/java/android/renderscript/Int3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Int4.java b/graphics/java/android/renderscript/Int4.java index 8734c95..eefb349 100644 --- a/graphics/java/android/renderscript/Int4.java +++ b/graphics/java/android/renderscript/Int4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Long2.java b/graphics/java/android/renderscript/Long2.java index 95ea18c..bd8382d 100644 --- a/graphics/java/android/renderscript/Long2.java +++ b/graphics/java/android/renderscript/Long2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Long3.java b/graphics/java/android/renderscript/Long3.java index 96ee885..3e94942 100644 --- a/graphics/java/android/renderscript/Long3.java +++ b/graphics/java/android/renderscript/Long3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Long4.java b/graphics/java/android/renderscript/Long4.java index 50e664c..00fb7e6 100644 --- a/graphics/java/android/renderscript/Long4.java +++ b/graphics/java/android/renderscript/Long4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Matrix2f.java b/graphics/java/android/renderscript/Matrix2f.java index 39abd4f..d3621fa 100644 --- a/graphics/java/android/renderscript/Matrix2f.java +++ b/graphics/java/android/renderscript/Matrix2f.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Matrix3f.java b/graphics/java/android/renderscript/Matrix3f.java index 5e9a7ca..8c3c330 100644 --- a/graphics/java/android/renderscript/Matrix3f.java +++ b/graphics/java/android/renderscript/Matrix3f.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Matrix4f.java b/graphics/java/android/renderscript/Matrix4f.java index 4600424..cd18e30 100644 --- a/graphics/java/android/renderscript/Matrix4f.java +++ b/graphics/java/android/renderscript/Matrix4f.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java index d0d383d..bca4aa3 100644 --- a/graphics/java/android/renderscript/Mesh.java +++ b/graphics/java/android/renderscript/Mesh.java @@ -24,7 +24,7 @@ import android.util.Log; * @hide * @deprecated in API 16 * <p>This class is a container for geometric data displayed with - * Renderscript. Internally, a mesh is a collection of allocations that + * RenderScript. Internally, a mesh is a collection of allocations that * represent vertex data (positions, normals, texture * coordinates) and index data such as triangles and lines. </p> * <p> @@ -32,7 +32,7 @@ import android.util.Log; * allocation that is provided separately, as multiple allocation * objects, or done as a combination of both. When a * vertex channel name matches an input in the vertex program, - * Renderscript automatically connects the two together. + * RenderScript automatically connects the two together. * </p> * <p> * Parts of the mesh can be rendered with either explicit diff --git a/graphics/java/android/renderscript/Program.java b/graphics/java/android/renderscript/Program.java index 9bd103e..bc2ca35 100644 --- a/graphics/java/android/renderscript/Program.java +++ b/graphics/java/android/renderscript/Program.java @@ -276,7 +276,7 @@ public class Program extends BaseObj { try { mShader = new String(str, 0, strLength, "UTF-8"); } catch (UnsupportedEncodingException e) { - Log.e("Renderscript shader creation", "Could not decode shader string"); + Log.e("RenderScript shader creation", "Could not decode shader string"); } return this; diff --git a/graphics/java/android/renderscript/ProgramFragment.java b/graphics/java/android/renderscript/ProgramFragment.java index dd0f9f5..b9ba3fd 100644 --- a/graphics/java/android/renderscript/ProgramFragment.java +++ b/graphics/java/android/renderscript/ProgramFragment.java @@ -23,7 +23,7 @@ import android.util.Log; /** * @hide * @deprecated in API 16 - * <p>The Renderscript fragment program, also known as fragment shader is responsible + * <p>The RenderScript fragment program, also known as fragment shader is responsible * for manipulating pixel data in a user defined way. It's constructed from a GLSL * shader string containing the program body, textures inputs, and a Type object * that describes the constants used by the program. Similar to the vertex programs, diff --git a/graphics/java/android/renderscript/ProgramVertex.java b/graphics/java/android/renderscript/ProgramVertex.java index 50e32f6..1c5a191 100644 --- a/graphics/java/android/renderscript/ProgramVertex.java +++ b/graphics/java/android/renderscript/ProgramVertex.java @@ -16,9 +16,9 @@ /** * @hide - * <p>The Renderscript vertex program, also known as a vertex shader, describes a stage in + * <p>The RenderScript vertex program, also known as a vertex shader, describes a stage in * the graphics pipeline responsible for manipulating geometric data in a user-defined way. - * The object is constructed by providing the Renderscript system with the following data:</p> + * The object is constructed by providing the RenderScript system with the following data:</p> * <ul> * <li>Element describing its varying inputs or attributes</li> * <li>GLSL shader string that defines the body of the program</li> @@ -28,7 +28,7 @@ * <p>Once the program is created, you bind it to the graphics context, RenderScriptGL, and it will be used for * all subsequent draw calls until you bind a new program. If the program has constant inputs, * the user needs to bind an allocation containing those inputs. The allocation's type must match - * the one provided during creation. The Renderscript library then does all the necessary plumbing + * the one provided during creation. The RenderScript library then does all the necessary plumbing * to send those constants to the graphics hardware. Varying inputs to the shader, such as position, normal, * and texture coordinates are matched by name between the input Element and the Mesh object being drawn. * The signatures don't have to be exact or in any strict order. As long as the input name in the shader diff --git a/graphics/java/android/renderscript/RSDriverException.java b/graphics/java/android/renderscript/RSDriverException.java index ce85b53..9e6507f 100644 --- a/graphics/java/android/renderscript/RSDriverException.java +++ b/graphics/java/android/renderscript/RSDriverException.java @@ -19,7 +19,7 @@ package android.renderscript; /** * Base class for all exceptions thrown by the Android - * Renderscript + * RenderScript */ public class RSDriverException extends RSRuntimeException { public RSDriverException(String string) { diff --git a/graphics/java/android/renderscript/RSIllegalArgumentException.java b/graphics/java/android/renderscript/RSIllegalArgumentException.java index 954c0e8..5c68594 100644 --- a/graphics/java/android/renderscript/RSIllegalArgumentException.java +++ b/graphics/java/android/renderscript/RSIllegalArgumentException.java @@ -19,7 +19,7 @@ package android.renderscript; /** * Base class for all exceptions thrown by the Android - * Renderscript + * RenderScript */ public class RSIllegalArgumentException extends RSRuntimeException { public RSIllegalArgumentException(String string) { diff --git a/graphics/java/android/renderscript/RSInvalidStateException.java b/graphics/java/android/renderscript/RSInvalidStateException.java index 691aeba..c881898 100644 --- a/graphics/java/android/renderscript/RSInvalidStateException.java +++ b/graphics/java/android/renderscript/RSInvalidStateException.java @@ -19,7 +19,7 @@ package android.renderscript; /** * Base class for all exceptions thrown by the Android - * Renderscript + * RenderScript */ public class RSInvalidStateException extends RSRuntimeException { public RSInvalidStateException(String string) { diff --git a/graphics/java/android/renderscript/RSRuntimeException.java b/graphics/java/android/renderscript/RSRuntimeException.java index 5a16478..b4b629e 100644 --- a/graphics/java/android/renderscript/RSRuntimeException.java +++ b/graphics/java/android/renderscript/RSRuntimeException.java @@ -19,7 +19,7 @@ package android.renderscript; /** * Base class for all exceptions thrown by the Android - * Renderscript + * RenderScript */ public class RSRuntimeException extends java.lang.RuntimeException { diff --git a/graphics/java/android/renderscript/RSSurfaceView.java b/graphics/java/android/renderscript/RSSurfaceView.java index 3c6c720..308d97a 100644 --- a/graphics/java/android/renderscript/RSSurfaceView.java +++ b/graphics/java/android/renderscript/RSSurfaceView.java @@ -36,8 +36,8 @@ import android.view.SurfaceView; * * <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 RSSurfaceView extends SurfaceView implements SurfaceHolder.Callback { diff --git a/graphics/java/android/renderscript/RenderScript.java b/graphics/java/android/renderscript/RenderScript.java index 8071073..4de4766 100644 --- a/graphics/java/android/renderscript/RenderScript.java +++ b/graphics/java/android/renderscript/RenderScript.java @@ -33,15 +33,14 @@ import android.os.SystemProperties; import android.os.Trace; /** - * 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 { @@ -912,11 +911,14 @@ public class RenderScript { // /** - * 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 { @@ -927,9 +929,10 @@ public class RenderScript { } } /** - * 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; @@ -953,9 +956,9 @@ public class RenderScript { } /** - * 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 { @@ -968,7 +971,7 @@ public class RenderScript { /** * 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. * */ @@ -982,10 +985,9 @@ public class RenderScript { } /** - * 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)), @@ -1052,7 +1054,7 @@ public class RenderScript { } 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) { @@ -1137,7 +1139,7 @@ public class RenderScript { } /** - * Create a basic RenderScript context. + * Create a RenderScript context. * * @hide * @param ctx The context. @@ -1163,7 +1165,7 @@ public class RenderScript { } /** - * Create a basic RenderScript context. + * Create a RenderScript context. * * @param ctx The context. * @return RenderScript @@ -1173,7 +1175,7 @@ public class RenderScript { } /** - * Create a basic RenderScript context. + * Create a RenderScript context. * * * @param ctx The context. @@ -1196,8 +1198,8 @@ public class RenderScript { } /** - * 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() { @@ -1205,8 +1207,9 @@ public class RenderScript { } /** - * 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/graphics/java/android/renderscript/RenderScriptGL.java b/graphics/java/android/renderscript/RenderScriptGL.java index 52034b1..bac9c68 100644 --- a/graphics/java/android/renderscript/RenderScriptGL.java +++ b/graphics/java/android/renderscript/RenderScriptGL.java @@ -31,7 +31,7 @@ import android.view.SurfaceView; /** * @hide * @deprecated in API 16 - * The Graphics derivitive of Renderscript. Extends the basic context to add a + * The Graphics derivitive of RenderScript. Extends the basic context to add a * root script which is the display window for graphical output. When the * system needs to update the display the currently bound root script will be * called. This script is expected to issue the rendering commands to repaint @@ -39,8 +39,8 @@ import android.view.SurfaceView; * * <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 RenderScriptGL extends RenderScript { diff --git a/graphics/java/android/renderscript/Sampler.java b/graphics/java/android/renderscript/Sampler.java index 057e9b5..623055f 100644 --- a/graphics/java/android/renderscript/Sampler.java +++ b/graphics/java/android/renderscript/Sampler.java @@ -28,9 +28,14 @@ import android.graphics.Bitmap; 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 { @@ -275,9 +280,8 @@ public class Sampler extends BaseObj { } /** - * 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/graphics/java/android/renderscript/Script.java b/graphics/java/android/renderscript/Script.java index f0579ca..0026e0e 100644 --- a/graphics/java/android/renderscript/Script.java +++ b/graphics/java/android/renderscript/Script.java @@ -19,7 +19,8 @@ package android.renderscript; import android.util.SparseArray; /** - * + * The parent class for all executable scripts. This should not be used by + * applications. **/ public class Script extends BaseObj { @@ -46,14 +47,6 @@ public class Script extends BaseObj { private final SparseArray<KernelID> mKIDs = new SparseArray<KernelID>(); /** * Only to be used by generated reflected classes. - * - * - * @param slot - * @param sig - * @param ein - * @param eout - * - * @return KernelID */ protected KernelID createKernelID(int slot, int sig, Element ein, Element eout) { KernelID k = mKIDs.get(slot); @@ -92,11 +85,6 @@ public class Script extends BaseObj { private final SparseArray<FieldID> mFIDs = new SparseArray(); /** * Only to be used by generated reflected classes. - * - * @param slot - * @param e - * - * @return FieldID */ protected FieldID createFieldID(int slot, Element e) { FieldID f = mFIDs.get(slot); @@ -118,7 +106,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param slot */ protected void invoke(int slot) { mRS.nScriptInvoke(getID(mRS), slot); @@ -127,8 +114,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param slot - * @param v */ protected void invoke(int slot, FieldPacker v) { if (v != null) { @@ -141,10 +126,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param slot - * @param ain - * @param aout - * @param v */ protected void forEach(int slot, Allocation ain, Allocation aout, FieldPacker v) { if (ain == null && aout == null) { @@ -169,11 +150,6 @@ public class Script extends BaseObj { /** * 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 (ain == null && aout == null) { @@ -208,8 +184,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param va - * @param slot */ public void bindAllocation(Allocation va, int slot) { mRS.validate(); @@ -223,8 +197,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param v */ public void setVar(int index, float v) { mRS.nScriptSetVarF(getID(mRS), index, v); @@ -236,8 +208,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param v */ public void setVar(int index, double v) { mRS.nScriptSetVarD(getID(mRS), index, v); @@ -249,8 +219,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param v */ public void setVar(int index, int v) { mRS.nScriptSetVarI(getID(mRS), index, v); @@ -263,8 +231,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param v */ public void setVar(int index, long v) { mRS.nScriptSetVarJ(getID(mRS), index, v); @@ -277,8 +243,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param v */ public void setVar(int index, boolean v) { mRS.nScriptSetVarI(getID(mRS), index, v ? 1 : 0); @@ -290,8 +254,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param o */ public void setVar(int index, BaseObj o) { mRS.nScriptSetVarObj(getID(mRS), index, (o == null) ? 0 : o.getID(mRS)); @@ -300,8 +262,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param v */ public void setVar(int index, FieldPacker v) { mRS.nScriptSetVarV(getID(mRS), index, v.getData()); @@ -310,10 +270,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param v - * @param e - * @param dims */ public void setVar(int index, FieldPacker v, Element e, int[] dims) { mRS.nScriptSetVarVE(getID(mRS), index, v.getData(), e.getID(mRS), dims); @@ -322,8 +278,6 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. * - * @param index - * @param v */ public void getVarV(int index, FieldPacker v) { mRS.nScriptGetVarV(getID(mRS), index, v.getData()); @@ -338,6 +292,10 @@ public class Script extends BaseObj { } } + /** + * Only intended for use by generated reflected code. + * + */ public static class Builder { RenderScript mRS; diff --git a/graphics/java/android/renderscript/ScriptC.java b/graphics/java/android/renderscript/ScriptC.java index 6975534..b0a5759 100644 --- a/graphics/java/android/renderscript/ScriptC.java +++ b/graphics/java/android/renderscript/ScriptC.java @@ -30,7 +30,8 @@ import java.lang.reflect.Field; 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/graphics/java/android/renderscript/ScriptGroup.java b/graphics/java/android/renderscript/ScriptGroup.java index 7afdb39..1416641 100644 --- a/graphics/java/android/renderscript/ScriptGroup.java +++ b/graphics/java/android/renderscript/ScriptGroup.java @@ -20,24 +20,26 @@ import java.lang.reflect.Method; 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 final class ScriptGroup extends BaseObj { @@ -93,8 +95,8 @@ public final class ScriptGroup extends BaseObj { /** * 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 @@ public final class ScriptGroup extends BaseObj { /** * 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 @@ public final class ScriptGroup extends BaseObj { /** * 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 @@ public final class ScriptGroup extends BaseObj { /** - * 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 kernels to be used by the ScriptGroup should be added. * <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. + * 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> - * 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. + * 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 the connections are made a call to create will + * Once all connections are made, a call to {@link #create} will * return the ScriptGroup object. * */ @@ -166,10 +173,10 @@ public final class ScriptGroup extends BaseObj { private int mKernelCount; /** - * 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) { mRS = rs; diff --git a/graphics/java/android/renderscript/ScriptIntrinsic3DLUT.java b/graphics/java/android/renderscript/ScriptIntrinsic3DLUT.java index 86f37d8..34540a1 100644 --- a/graphics/java/android/renderscript/ScriptIntrinsic3DLUT.java +++ b/graphics/java/android/renderscript/ScriptIntrinsic3DLUT.java @@ -40,7 +40,7 @@ public final class ScriptIntrinsic3DLUT extends ScriptIntrinsic { * * 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 +55,13 @@ public final class ScriptIntrinsic3DLUT extends ScriptIntrinsic { 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/graphics/java/android/renderscript/ScriptIntrinsicBlend.java b/graphics/java/android/renderscript/ScriptIntrinsicBlend.java index 65c69c0..0e05bc8 100644 --- a/graphics/java/android/renderscript/ScriptIntrinsicBlend.java +++ b/graphics/java/android/renderscript/ScriptIntrinsicBlend.java @@ -18,8 +18,7 @@ package android.renderscript; /** - * 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 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * 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 */ @@ -53,7 +51,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * dst = {0, 0, 0, 0} + * Sets dst = {0, 0, 0, 0} * * @param ain The source buffer * @param aout The destination buffer @@ -73,7 +71,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { /** - * dst = src + * Sets dst = src * * @param ain The source buffer * @param aout The destination buffer @@ -92,8 +90,9 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * dst = dst - * This is a NOP + * Sets dst = dst + * + * This is a NOP. * * @param ain The source buffer * @param aout The destination buffer @@ -112,7 +111,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * 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 @@ -131,7 +130,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * 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 @@ -150,7 +149,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * dst = src * dst.a + * Sets dst = src * dst.a * * @param ain The source buffer * @param aout The destination buffer @@ -169,7 +168,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * dst = dst * src.a + * Sets dst = dst * src.a * * @param ain The source buffer * @param aout The destination buffer @@ -188,7 +187,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * dst = src * (1.0 - dst.a) + * Sets dst = src * (1.0 - dst.a) * * @param ain The source buffer * @param aout The destination buffer @@ -207,7 +206,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * dst = dst * (1.0 - src.a) + * Sets dst = dst * (1.0 - src.a) * * @param ain The source buffer * @param aout The destination buffer @@ -266,7 +265,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * 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 @@ -295,7 +294,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } */ /** - * dst = src * dst + * Sets dst = src * dst * * @param ain The source buffer * @param aout The destination buffer @@ -391,7 +390,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } */ /** - * dst = min(src + dst, 1.0) + * Sets dst = min(src + dst, 1.0) * * @param ain The source buffer * @param aout The destination buffer @@ -410,7 +409,7 @@ public class ScriptIntrinsicBlend extends ScriptIntrinsic { } /** - * 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/graphics/java/android/renderscript/ScriptIntrinsicBlur.java b/graphics/java/android/renderscript/ScriptIntrinsicBlur.java index 2848f64..aaf5ffc 100644 --- a/graphics/java/android/renderscript/ScriptIntrinsicBlur.java +++ b/graphics/java/android/renderscript/ScriptIntrinsicBlur.java @@ -40,7 +40,7 @@ public final class ScriptIntrinsicBlur extends ScriptIntrinsic { * * 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 diff --git a/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java b/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java index f7e844e..77b9385 100644 --- a/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java +++ b/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java @@ -41,7 +41,7 @@ public final class ScriptIntrinsicColorMatrix extends ScriptIntrinsic { * * 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/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java b/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java index d54df96..c9c54b2 100644 --- a/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java +++ b/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java @@ -41,7 +41,7 @@ public final class ScriptIntrinsicConvolve3x3 extends ScriptIntrinsic { * <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/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java b/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java index 1f52e3f..c6e1e39 100644 --- a/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java +++ b/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java @@ -42,7 +42,7 @@ public final class ScriptIntrinsicConvolve5x5 extends ScriptIntrinsic { * <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/graphics/java/android/renderscript/ScriptIntrinsicLUT.java b/graphics/java/android/renderscript/ScriptIntrinsicLUT.java index f5ca261..0f7ab38 100644 --- a/graphics/java/android/renderscript/ScriptIntrinsicLUT.java +++ b/graphics/java/android/renderscript/ScriptIntrinsicLUT.java @@ -47,7 +47,7 @@ public final class ScriptIntrinsicLUT extends ScriptIntrinsic { * * 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/graphics/java/android/renderscript/ScriptIntrinsicYuvToRGB.java b/graphics/java/android/renderscript/ScriptIntrinsicYuvToRGB.java index dc8a5aa..9b5de9b 100644 --- a/graphics/java/android/renderscript/ScriptIntrinsicYuvToRGB.java +++ b/graphics/java/android/renderscript/ScriptIntrinsicYuvToRGB.java @@ -36,7 +36,7 @@ public final class ScriptIntrinsicYuvToRGB extends ScriptIntrinsic { * * 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/graphics/java/android/renderscript/Short2.java b/graphics/java/android/renderscript/Short2.java index 617f1f5..7c6027f 100644 --- a/graphics/java/android/renderscript/Short2.java +++ b/graphics/java/android/renderscript/Short2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Short3.java b/graphics/java/android/renderscript/Short3.java index b9ca49b..49de05e 100644 --- a/graphics/java/android/renderscript/Short3.java +++ b/graphics/java/android/renderscript/Short3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Short4.java b/graphics/java/android/renderscript/Short4.java index d5f2db5..a7807a4 100644 --- a/graphics/java/android/renderscript/Short4.java +++ b/graphics/java/android/renderscript/Short4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * 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/graphics/java/android/renderscript/Type.java b/graphics/java/android/renderscript/Type.java index a5e24ce..ef08c29 100644 --- a/graphics/java/android/renderscript/Type.java +++ b/graphics/java/android/renderscript/Type.java @@ -23,24 +23,29 @@ import android.graphics.ImageFormat; 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/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 Type extends BaseObj { @@ -277,11 +282,9 @@ public class Type extends BaseObj { } /** - * Set the YUV layout for a Type. This controls how the memory is - * interpreted. Generally and application should not need to call this - * function and it would be set by the Camera. + * Set the YUV layout for a Type. * - * 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) { @@ -299,7 +302,7 @@ public class Type extends BaseObj { /** - * Validate structure and create a new type. + * Validate structure and create a new Type. * * @return Type */ diff --git a/graphics/java/android/renderscript/package.html b/graphics/java/android/renderscript/package.html index eb178c1..a844956 100644 --- a/graphics/java/android/renderscript/package.html +++ b/graphics/java/android/renderscript/package.html @@ -2,6 +2,11 @@ <BODY> <p>RenderScript provides support for high-performance computation across heterogeneous processors.</p> +<p>This package is for the latest native version of RenderScript included on +Android devices. Developers interested in running RenderScript on any Android +device running {@link android.os.Build.VERSION_CODES#GINGERBREAD} or newer +should see the {@link android.support.v8.renderscript} package. + <p>For more information, see the <a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer guide.</p> {@more} |