Improve the documentation of the RenderScript API.
Only the explanations should be changing.
Change-Id: I889b366e3be44f5ac7f44a199e4b9a47353665e2
diff --git a/scriptc/rs_allocation_data.rsh b/scriptc/rs_allocation_data.rsh
index 12d62a0..928b649 100644
--- a/scriptc/rs_allocation_data.rsh
+++ b/scriptc/rs_allocation_data.rsh
@@ -17,33 +17,47 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_allocation_data.rsh: Allocation routines
+ * rs_allocation_data.rsh: Allocation Data Access Functions
*
- * TODO Adjust documentation.
+ * The functions below can be used to get and set the cells that comprise
+ * an allocation.
*
- * Functions that can be used to query the characteristics of an allocation,
- * to set and get elements of the allocation.
+ * - Individual cells are accessed using the rsGetElementAt* and
+ * rsSetElementAt functions.
+ * - Multiple cells can be copied using the rsAllocationCopy* and
+ * rsAllocationV* functions.
+ * - For getting values through a sampler, use rsSample.
+ *
+ * The rsGetElementAt and rsSetElement* functions are somewhat misnamed.
+ * They don't get or set elements, which are akin to data types; they get
+ * or set cells. Think of them as rsGetCellAt and and rsSetCellAt.
*/
#ifndef RENDERSCRIPT_RS_ALLOCATION_DATA_RSH
#define RENDERSCRIPT_RS_ALLOCATION_DATA_RSH
/*
- * rsAllocationCopy1DRange: Copy consecutive values between allocations
+ * rsAllocationCopy1DRange: Copy consecutive cells between allocations
*
- * Copies part of an allocation into another allocation.
+ * Copies the specified number of cells from one allocation to another.
*
* The two allocations must be different. Using this function to copy whithin
* the same allocation yields undefined results.
*
+ * The function does not validate whether the offset plus count exceeds the size
+ * of either allocation. Be careful!
+ *
+ * This function should only be called between 1D allocations. Calling it
+ * on other allocations is undefined.
+ *
* Parameters:
- * dstAlloc: Allocation to copy data into.
- * dstOff: The offset of the first element to be copied in the destination allocation.
- * dstMip: Mip level in the destination allocation.
- * count: The number of elements to be copied.
- * srcAlloc: The source data allocation.
- * srcOff: The offset of the first element in data to be copied in the source allocation.
- * srcMip: Mip level in the source allocation.
+ * dstAlloc: Allocation to copy cells into.
+ * dstOff: Offset in the destination of the first cell to be copied into.
+ * dstMip: Mip level in the destination allocation. 0 if mip mapping is not used.
+ * count: Number of cells to be copied.
+ * srcAlloc: Source allocation.
+ * srcOff: Offset in the source of the first cell to be copied.
+ * srcMip: Mip level in the source allocation. 0 if mip mapping is not used.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern void __attribute__((overloadable))
@@ -52,26 +66,33 @@
#endif
/*
- * rsAllocationCopy2DRange: Copy a rectangular region between allocations
+ * rsAllocationCopy2DRange: Copy a rectangular region of cells between allocations
*
- * Copy a rectangular region into the allocation from another allocation.
+ * Copies a rectangular region of cells from one allocation to another.
+ * (width * heigth) cells are copied.
*
* The two allocations must be different. Using this function to copy whithin
* the same allocation yields undefined results.
*
+ * The function does not validate whether the the source or destination region
+ * exceeds the size of its respective allocation. Be careful!
+ *
+ * This function should only be called between 2D allocations. Calling it
+ * on other allocations is undefined.
+ *
* Parameters:
- * dstAlloc: Allocation to copy data into.
- * dstXoff: X offset of the region to update in the destination allocation.
- * dstYoff: Y offset of the region to update in the destination allocation.
- * dstMip: Mip level in the destination allocation.
- * dstFace: Cubemap face of the destination allocation, ignored for allocations that aren't cubemaps.
+ * dstAlloc: Allocation to copy cells into.
+ * dstXoff: X offset in the destination of the region to be set.
+ * dstYoff: Y offset in the destination of the region to be set.
+ * dstMip: Mip level in the destination allocation. 0 if mip mapping is not used.
+ * dstFace: Cubemap face of the destination allocation. Ignored for allocations that aren't cubemaps.
* width: Width of the incoming region to update.
* height: Height of the incoming region to update.
- * srcAlloc: The source data allocation.
- * srcXoff: X offset in data of the source allocation.
- * srcYoff: Y offset in data of the source allocation.
- * srcMip: Mip level in the source allocation.
- * srcFace: Cubemap face of the source allocation, ignored for allocations that aren't cubemaps.
+ * srcAlloc: Source allocation.
+ * srcXoff: X offset in the source.
+ * srcYoff: Y offset in the source.
+ * srcMip: Mip level in the source allocation. 0 if mip mapping is not used.
+ * srcFace: Cubemap face of the source allocation. Ignored for allocations that aren't cubemaps.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern void __attribute__((overloadable))
@@ -82,7 +103,34 @@
#endif
/*
- * Get a single element from an allocation.
+ * rsAllocationVLoadX: Get a vector from an allocation of scalars
+ *
+ * This function returns a vector composed of successive cells of the allocation.
+ * It assumes that the allocation contains scalars.
+ *
+ * The "X" in the name indicates that successive values are extracted by
+ * increasing the X index. There are currently no functions to get successive
+ * values incrementing other dimensions. Use multiple calls to rsGetElementAt()
+ * instead.
+ *
+ * For example, when calling rsAllocationVLoadX_int4(a, 20, 30),
+ * an int4 composed of a[20, 30], a[21, 30], a[22, 30], and a[23, 30] is returned.
+ *
+ * When retrieving from a three dimensional allocations, use the x, y, z
+ * variant. Similarly, use the x, y variant for two dimensional
+ * allocations and x for the mono dimensional allocations.
+ *
+ * For efficiency, this function does not validate the inputs. Trying to
+ * wrap the X index, exceeding the size of the allocation, or using indexes
+ * incompatible with the dimensionality of the allocation yields undefined results.
+ *
+ * See also rsAllocationVStoreX().
+ *
+ * Parameters:
+ * a: Allocation to get the data from.
+ * x: X offset in the allocation of the first cell to be copied from.
+ * y: Y offset in the allocation of the first cell to be copied from.
+ * z: Z offset in the allocation of the first cell to be copied from.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 22))
extern float2 __attribute__((overloadable))
@@ -535,7 +583,35 @@
#endif
/*
- * Set a single element of an allocation.
+ * rsAllocationVStoreX: Store a vector into an allocation of scalars
+ *
+ * This function stores the entries of a vector into successive cells of an
+ * allocation. It assumes that the allocation contains scalars.
+ *
+ * The "X" in the name indicates that successive values are stored by
+ * increasing the X index. There are currently no functions to store successive
+ * values incrementing other dimensions. Use multiple calls to rsSetElementAt()
+ * instead.
+ *
+ * For example, when calling rsAllocationVStoreX_int3(a, v, 20, 30),
+ * v.x is stored at a[20, 30], v.y at a[21, 30], and v.z at a[22, 30].
+ *
+ * When storing into a three dimensional allocations, use the x, y, z
+ * variant. Similarly, use the x, y variant for two dimensional
+ * allocations and x for the mono dimensional allocations.
+ *
+ * For efficiency, this function does not validate the inputs. Trying to
+ * wrap the X index, exceeding the size of the allocation, or using indexes
+ * incompatible with the dimensionality of the allocation yiels undefined results.
+ *
+ * See also rsAllocationVLoadX().
+ *
+ * Parameters:
+ * a: Allocation to store the data into.
+ * val: Value to be stored.
+ * x: X offset in the allocation of the first cell to be copied into.
+ * y: Y offset in the allocation of the first cell to be copied into.
+ * z: Z offset in the allocation of the first cell to be copied into.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 22))
extern void __attribute__((overloadable))
@@ -988,9 +1064,18 @@
#endif
/*
- * rsGetElementAt: Get an element
+ * rsGetElementAt: Return a cell from an allocation
*
- * Extract a single element from an allocation.
+ * This function extracts a single cell from an allocation.
+ *
+ * When retrieving from a three dimensional allocations, use the x, y, z
+ * variant. Similarly, use the x, y variant for two dimensional
+ * allocations and x for the mono dimensional allocations.
+ *
+ * This function has two styles. One returns the address of the value using a
+ * void*, the other returns the actual value, e.g. rsGetElementAt() vs.
+ * rsGetElementAt_int4(). For primitive types, always use the latter as it is
+ * more efficient.
*/
extern const void* __attribute__((overloadable))
rsGetElementAt(rs_allocation a, uint32_t x);
@@ -2442,9 +2527,15 @@
#endif
/*
- * Extract a single element from an allocation.
+ * rsGetElementAtYuv_uchar_U: Get the U component of an allocation of YUVs
*
- * Coordinates are in the dimensions of the Y plane
+ * Extracts the U component of a single YUV value from a 2D allocation of YUVs.
+ *
+ * Inside an allocation, Y, U, and V components may be stored if different planes
+ * and at different resolutions. The x, y coordinates provided here are in the
+ * dimensions of the Y plane.
+ *
+ * See rsGetElementAtYuv_uchar_Y().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 18))
extern uchar __attribute__((overloadable))
@@ -2452,9 +2543,15 @@
#endif
/*
- * Extract a single element from an allocation.
+ * rsGetElementAtYuv_uchar_V: Get the V component of an allocation of YUVs
*
- * Coordinates are in the dimensions of the Y plane
+ * Extracts the V component of a single YUV value from a 2D allocation of YUVs.
+ *
+ * Inside an allocation, Y, U, and V components may be stored if different planes
+ * and at different resolutions. The x, y coordinates provided here are in the
+ * dimensions of the Y plane.
+ *
+ * See rsGetElementAtYuv_uchar_Y().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 18))
extern uchar __attribute__((overloadable))
@@ -2462,7 +2559,15 @@
#endif
/*
- * Extract a single element from an allocation.
+ * rsGetElementAtYuv_uchar_Y: Get the Y component of an allocation of YUVs
+ *
+ * Extracts the Y component of a single YUV value from a 2D allocation of YUVs.
+ *
+ * Inside an allocation, Y, U, and V components may be stored if different planes
+ * and at different resolutions. The x, y coordinates provided here are in the
+ * dimensions of the Y plane.
+ *
+ * See rsGetElementAtYuv_uchar_U() and rsGetElementAtYuv_uchar_V().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 18))
extern uchar __attribute__((overloadable))
@@ -2470,16 +2575,20 @@
#endif
/*
- * Fetch allocation in a way described by the sampler
+ * rsSample: Sample a value from a texture allocation
*
- * If your allocation is 1D, use the variant with float for location.
- * For 2D, use the float2 variant.
+ * Fetches a value from a texture allocation in a way described by the sampler.
+ *
+ * If your allocation is 1D, use the variant with float for location. For 2D,
+ * use the float2 variant.
+ *
+ * See android.renderscript.Sampler for more details.
*
* Parameters:
- * a: allocation to sample from
- * s: sampler state
- * location: location to sample from
- * lod: mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used
+ * a: Allocation to sample from.
+ * s: Sampler state.
+ * location: Location to sample from.
+ * lod: Mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern float4 __attribute__((overloadable))
@@ -2502,9 +2611,20 @@
#endif
/*
- * rsSetElementAt: Set an element
+ * rsSetElementAt: Set a cell of an allocation
*
- * Set single element of an allocation.
+ * This function stores a value into a single cell of an allocation.
+ *
+ * When storing into a three dimensional allocations, use the x, y, z
+ * variant. Similarly, use the x, y variant for two dimensional
+ * allocations and x for the mono dimensional allocations.
+ *
+ * This function has two styles. One passes the value to be stored using
+ * a void*, the other has the actual value as an argument, e.g. rsSetElementAt()
+ * vs. rsSetElementAt_int4(). For primitive types, always use the latter as it is
+ * more efficient.
+ *
+ * See also rsGetElementAt().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 18))
extern void __attribute__((overloadable))