Clean up RS samples for SDK, bug 2943369

Fix bug 3403965 rsgSyncAll would not mark constants as changed
found by inspection.

Only rsAllocation.cpp affects on device bits.

Change-Id: I6b7ec0df87e42687b24384aaf54dc04976cb84f7

doc update

Change-Id: Id5841f08868557e086f185024470924ef202d19f

8 files changed, 377 insertions, 41 deletions

diff --git a/libs/rs/java/ModelViewer/src/com/android/modelviewer/scenegraph.rs b/libs/rs/java/ModelViewer/src/com/android/modelviewer/scenegraph.rs
index 3bee8d6..3679068 100644
--- a/libs/rs/java/ModelViewer/src/com/android/modelviewer/scenegraph.rs
+++ b/libs/rs/java/ModelViewer/src/com/android/modelviewer/scenegraph.rs
@@ -81,7 +81,7 @@ int root(int launchID) {
     rsgProgramVertexLoadModelMatrix(&robot2Ptr->globalMat);
     rsgDrawMesh(gTestMesh);
 
-    color(0.3f, 0.3f, 0.3f, 1.0f);
+    //color(0.3f, 0.3f, 0.3f, 1.0f);
     rsgDrawText("Renderscript transform test", 30, 695);
 
     rsgBindFont(gItalic);
diff --git a/libs/rs/java/Samples/src/com/android/samples/rslist.rs b/libs/rs/java/Samples/src/com/android/samples/rslist.rs
index 0baccb8..b79f4fc 100644
--- a/libs/rs/java/Samples/src/com/android/samples/rslist.rs
+++ b/libs/rs/java/Samples/src/com/android/samples/rslist.rs
@@ -44,7 +44,6 @@ int root(int launchID) {
 
     rsgFontColor(0.9f, 0.9f, 0.9f, 1.0f);
     rsgBindFont(gItalic);
-    color(0.2, 0.2, 0.2, 0);
 
     rs_allocation listAlloc;
     rsSetObject(&listAlloc, rsGetAllocation(gList));
diff --git a/libs/rs/java/Samples/src/com/android/samples/rsrenderstates.rs b/libs/rs/java/Samples/src/com/android/samples/rsrenderstates.rs
index a973167..42be4d8 100644
--- a/libs/rs/java/Samples/src/com/android/samples/rsrenderstates.rs
+++ b/libs/rs/java/Samples/src/com/android/samples/rsrenderstates.rs
@@ -407,7 +407,7 @@ static void setupCustomShaderLights() {
     gVSConstants->light1_Diffuse = 1.0f;
     gVSConstants->light1_Specular = 0.7f;
     gVSConstants->light1_CosinePower = 25.0f;
-    rsAllocationMarkDirty(rsGetAllocation(gVSConstants));
+    rsgAllocationSyncAll(rsGetAllocation(gVSConstants));
 
     gVSConstants2->light_Posision[0] = light0Pos;
     gVSConstants2->light_Diffuse[0] = 1.0f;
@@ -417,7 +417,7 @@ static void setupCustomShaderLights() {
     gVSConstants2->light_Diffuse[1] = 1.0f;
     gVSConstants2->light_Specular[1] = 0.7f;
     gVSConstants2->light_CosinePower[1] = 25.0f;
-    rsAllocationMarkDirty(rsGetAllocation(gVSConstants2));
+    rsgAllocationSyncAll(rsGetAllocation(gVSConstants2));
 
     // Update fragmetn shader constants
     // Set light 0 colors
@@ -426,14 +426,14 @@ static void setupCustomShaderLights() {
     // Set light 1 colors
     gFSConstants->light1_DiffuseColor = light1DiffCol;
     gFSConstants->light1_SpecularColor = light1SpecCol;
-    rsAllocationMarkDirty(rsGetAllocation(gFSConstants));
+    rsgAllocationSyncAll(rsGetAllocation(gFSConstants));
 
     gFSConstants2->light_DiffuseColor[0] = light0DiffCol;
     gFSConstants2->light_SpecularColor[0] = light0SpecCol;
     // Set light 1 colors
     gFSConstants2->light_DiffuseColor[1] = light1DiffCol;
     gFSConstants2->light_SpecularColor[1] = light1SpecCol;
-    rsAllocationMarkDirty(rsGetAllocation(gFSConstants2));
+    rsgAllocationSyncAll(rsGetAllocation(gFSConstants2));
 }
 
 static void displayCustomShaderSamples() {
diff --git a/libs/rs/java/tests/src/com/android/rs/test/rslist.rs b/libs/rs/java/tests/src/com/android/rs/test/rslist.rs
index f354a72..67c2b86 100644
--- a/libs/rs/java/tests/src/com/android/rs/test/rslist.rs
+++ b/libs/rs/java/tests/src/com/android/rs/test/rslist.rs
@@ -45,7 +45,6 @@ int root(int launchID) {
 
     rsgFontColor(0.9f, 0.9f, 0.9f, 1.0f);
     rsgBindFont(gFont);
-    color(0.2, 0.2, 0.2, 0);
 
     rs_allocation listAlloc;
     rsSetObject(&listAlloc, rsGetAllocation(gList));
diff --git a/libs/rs/rsAllocation.cpp b/libs/rs/rsAllocation.cpp
index 41c9fe2..c598f03 100644
--- a/libs/rs/rsAllocation.cpp
+++ b/libs/rs/rsAllocation.cpp
@@ -679,6 +679,7 @@ static void mip(const Adapter2D &out, const Adapter2D &in) {
 void rsi_AllocationSyncAll(Context *rsc, RsAllocation va, RsAllocationUsageType src) {
     Allocation *a = static_cast<Allocation *>(va);
     a->syncAll(rsc, src);
+    a->sendDirty();
 }
 
 void rsi_AllocationGenerateMipmaps(Context *rsc, RsAllocation va) {
diff --git a/libs/rs/scriptc/rs_core.rsh b/libs/rs/scriptc/rs_core.rsh
index e32d435..464e1d9 100644
--- a/libs/rs/scriptc/rs_core.rsh
+++ b/libs/rs/scriptc/rs_core.rsh
@@ -3,93 +3,227 @@
 
 #define _RS_RUNTIME extern
 
-// Debugging, print to the LOG a description string and a value.
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, float);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, float, float);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, float, float, float);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, float, float, float, float);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, double);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, const rs_matrix4x4 *);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, const rs_matrix3x3 *);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, const rs_matrix2x2 *);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, int);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, uint);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, long);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, unsigned long);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, long long);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, unsigned long long);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 extern void __attribute__((overloadable))
     rsDebug(const char *, const void *);
 #define RS_DEBUG(a) rsDebug(#a, a)
 #define RS_DEBUG_MARKER rsDebug(__FILE__, __LINE__)
 
+
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 _RS_RUNTIME void __attribute__((overloadable)) rsDebug(const char *s, float2 v);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 _RS_RUNTIME void __attribute__((overloadable)) rsDebug(const char *s, float3 v);
+/**
+ * Debug function.  Prints a string and value to the log.
+ */
 _RS_RUNTIME void __attribute__((overloadable)) rsDebug(const char *s, float4 v);
 
+
+/**
+ * Pack floating point (0-1) RGB values into a uchar4.  The alpha component is
+ * set to 255 (1.0).
+ *
+ * @param r
+ * @param g
+ * @param b
+ *
+ * @return uchar4
+ */
 _RS_RUNTIME uchar4 __attribute__((overloadable)) rsPackColorTo8888(float r, float g, float b);
 
+/**
+ * Pack floating point (0-1) RGBA values into a uchar4.
+ *
+ * @param r
+ * @param g
+ * @param b
+ * @param a
+ *
+ * @return uchar4
+ */
 _RS_RUNTIME uchar4 __attribute__((overloadable)) rsPackColorTo8888(float r, float g, float b, float a);
 
+/**
+ * Pack floating point (0-1) RGB values into a uchar4.  The alpha component is
+ * set to 255 (1.0).
+ *
+ * @param color
+ *
+ * @return uchar4
+ */
 _RS_RUNTIME uchar4 __attribute__((overloadable)) rsPackColorTo8888(float3 color);
 
+/**
+ * Pack floating point (0-1) RGBA values into a uchar4.
+ *
+ * @param color
+ *
+ * @return uchar4
+ */
 _RS_RUNTIME uchar4 __attribute__((overloadable)) rsPackColorTo8888(float4 color);
 
+/**
+ * Unpack a uchar4 color to float4.  The resulting float range will be (0-1).
+ *
+ * @param c
+ *
+ * @return float4
+ */
 _RS_RUNTIME float4 rsUnpackColor8888(uchar4 c);
 
-//extern uchar4 __attribute__((overloadable)) rsPackColorTo565(float r, float g, float b);
-//extern uchar4 __attribute__((overloadable)) rsPackColorTo565(float3);
-//extern float4 rsUnpackColor565(uchar4);
-
 
 /////////////////////////////////////////////////////
 // Matrix ops
 /////////////////////////////////////////////////////
 
+/**
+ * Set one element of a matrix.
+ *
+ * @param m The matrix to be set
+ * @param row
+ * @param col
+ * @param v
+ *
+ * @return void
+ */
 _RS_RUNTIME void __attribute__((overloadable))
 rsMatrixSet(rs_matrix4x4 *m, uint32_t row, uint32_t col, float v);
-
-_RS_RUNTIME float __attribute__((overloadable))
-rsMatrixGet(const rs_matrix4x4 *m, uint32_t row, uint32_t col);
-
 _RS_RUNTIME void __attribute__((overloadable))
 rsMatrixSet(rs_matrix3x3 *m, uint32_t row, uint32_t col, float v);
-
-_RS_RUNTIME float __attribute__((overloadable))
-rsMatrixGet(const rs_matrix3x3 *m, uint32_t row, uint32_t col);
-
 _RS_RUNTIME void __attribute__((overloadable))
 rsMatrixSet(rs_matrix2x2 *m, uint32_t row, uint32_t col, float v);
 
+/**
+ * Get one element of a matrix.
+ *
+ * @param m The matrix to read from
+ * @param row
+ * @param col
+ *
+ * @return float
+ */
+_RS_RUNTIME float __attribute__((overloadable))
+rsMatrixGet(const rs_matrix4x4 *m, uint32_t row, uint32_t col);
+_RS_RUNTIME float __attribute__((overloadable))
+rsMatrixGet(const rs_matrix3x3 *m, uint32_t row, uint32_t col);
 _RS_RUNTIME float __attribute__((overloadable))
 rsMatrixGet(const rs_matrix2x2 *m, uint32_t row, uint32_t col);
 
+/**
+ * Set the elements of a matrix to the identity matrix.
+ *
+ * @param m
+ */
 extern void __attribute__((overloadable)) rsMatrixLoadIdentity(rs_matrix4x4 *m);
 extern void __attribute__((overloadable)) rsMatrixLoadIdentity(rs_matrix3x3 *m);
 extern void __attribute__((overloadable)) rsMatrixLoadIdentity(rs_matrix2x2 *m);
+
+/**
+ * Set the elements of a matrix from an array of floats.
+ *
+ * @param m
+ */
 extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix4x4 *m, const float *v);
 extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix3x3 *m, const float *v);
 extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix2x2 *m, const float *v);
+
+/**
+ * Set the elements of a matrix from another matrix.
+ *
+ * @param m
+ */
 extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix4x4 *m, const rs_matrix4x4 *v);
 extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix4x4 *m, const rs_matrix3x3 *v);
 extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix4x4 *m, const rs_matrix2x2 *v);
 extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix3x3 *m, const rs_matrix3x3 *v);
 extern void __attribute__((overloadable)) rsMatrixLoad(rs_matrix2x2 *m, const rs_matrix2x2 *v);
 
+/**
+ * Load a rotation matrix.
+ *
+ * @param m
+ * @param rot
+ * @param x
+ * @param y
+ * @param z
+ */
 extern void __attribute__((overloadable))
 rsMatrixLoadRotate(rs_matrix4x4 *m, float rot, float x, float y, float z);
 
diff --git a/libs/rs/scriptc/rs_graphics.rsh b/libs/rs/scriptc/rs_graphics.rsh
index 3868f24..142e21a 100644
--- a/libs/rs/scriptc/rs_graphics.rsh
+++ b/libs/rs/scriptc/rs_graphics.rsh
@@ -1,21 +1,60 @@
 #ifndef __RS_GRAPHICS_RSH__
 #define __RS_GRAPHICS_RSH__
 
-// Bind a ProgramFragment to the RS context.
+
+/**
+ * Bind a new ProgramFragment to the rendering context.
+ *
+ * @param pf
+ */
 extern void __attribute__((overloadable))
-    rsgBindProgramFragment(rs_program_fragment);
+    rsgBindProgramFragment(rs_program_fragment pf);
+
+/**
+ * Bind a new ProgramStore to the rendering context.
+ *
+ * @param ps
+ */
 extern void __attribute__((overloadable))
-    rsgBindProgramStore(rs_program_store);
+    rsgBindProgramStore(rs_program_store ps);
+
+/**
+ * Bind a new ProgramVertex to the rendering context.
+ *
+ * @param pv
+ */
 extern void __attribute__((overloadable))
-    rsgBindProgramVertex(rs_program_vertex);
+    rsgBindProgramVertex(rs_program_vertex pv);
+
+/**
+ * Bind a new ProgramRaster to the rendering context.
+ *
+ * @param pr
+ */
 extern void __attribute__((overloadable))
-    rsgBindProgramRaster(rs_program_raster);
+    rsgBindProgramRaster(rs_program_raster pr);
 
+/**
+ * Bind a new Sampler object to a ProgramFragment.  The sampler will
+ * operate on the texture bound at the matching slot.
+ *
+ * @param slot
+ */
 extern void __attribute__((overloadable))
     rsgBindSampler(rs_program_fragment, uint slot, rs_sampler);
+
+/**
+ * Bind a new Allocation object to a ProgramFragment.  The
+ * Allocation must be a valid texture for the Program.  The sampling
+ * of the texture will be controled by the Sampler bound at the
+ * matching slot.
+ *
+ * @param slot
+ */
 extern void __attribute__((overloadable))
     rsgBindTexture(rs_program_fragment, uint slot, rs_allocation);
 
+
 extern void __attribute__((overloadable))
     rsgProgramVertexLoadProjectionMatrix(const rs_matrix4x4 *);
 extern void __attribute__((overloadable))
@@ -26,32 +65,134 @@ extern void __attribute__((overloadable))
 extern void __attribute__((overloadable))
     rsgProgramVertexGetProjectionMatrix(rs_matrix4x4 *);
 
+/**
+ * Set the constant color for a fixed function emulation program.
+ *
+ * @param pf
+ * @param r
+ * @param g
+ * @param b
+ * @param a
+ */
 extern void __attribute__((overloadable))
-    rsgProgramFragmentConstantColor(rs_program_fragment, float, float, float, float);
+    rsgProgramFragmentConstantColor(rs_program_fragment pf, float r, float g, float b, float a);
 
+/**
+ * Get the width of the current rendering surface.
+ *
+ * @return uint
+ */
 extern uint __attribute__((overloadable))
     rsgGetWidth(void);
+
+/**
+ * Get the height of the current rendering surface.
+ *
+ * @return uint
+ */
 extern uint __attribute__((overloadable))
     rsgGetHeight(void);
 
+
+/**
+ * Sync the contents of an allocation from its SCRIPT memory space to its HW
+ * memory spaces.
+ *
+ * @param alloc
+ */
 extern void __attribute__((overloadable))
-    rsgAllocationSyncAll(rs_allocation);
+    rsgAllocationSyncAll(rs_allocation alloc);
 
+/**
+ * Low performance utility function for drawing a simple rectangle.  Not
+ * intended for drawing large quantities of geometry.
+ *
+ * @param x1
+ * @param y1
+ * @param x2
+ * @param y2
+ * @param z
+ */
 extern void __attribute__((overloadable))
     rsgDrawRect(float x1, float y1, float x2, float y2, float z);
+
+/**
+ * Low performance utility function for drawing a simple quad.  Not intended for
+ * drawing large quantities of geometry.
+ *
+ * @param x1
+ * @param y1
+ * @param z1
+ * @param x2
+ * @param y2
+ * @param z2
+ * @param x3
+ * @param y3
+ * @param z3
+ * @param x4
+ * @param y4
+ * @param z4
+ */
 extern void __attribute__((overloadable))
     rsgDrawQuad(float x1, float y1, float z1,
                 float x2, float y2, float z2,
                 float x3, float y3, float z3,
                 float x4, float y4, float z4);
+
+
+/**
+ * Low performance utility function for drawing a textured quad.  Not intended
+ * for drawing large quantities of geometry.
+ *
+ * @param x1
+ * @param y1
+ * @param z1
+ * @param u1
+ * @param v1
+ * @param x2
+ * @param y2
+ * @param z2
+ * @param u2
+ * @param v2
+ * @param x3
+ * @param y3
+ * @param z3
+ * @param u3
+ * @param v3
+ * @param x4
+ * @param y4
+ * @param z4
+ * @param u4
+ * @param v4
+ */
 extern void __attribute__((overloadable))
     rsgDrawQuadTexCoords(float x1, float y1, float z1, float u1, float v1,
                          float x2, float y2, float z2, float u2, float v2,
                          float x3, float y3, float z3, float u3, float v3,
                          float x4, float y4, float z4, float u4, float v4);
+
+
+/**
+ * Low performance function for drawing rectangles in screenspace.  This
+ * function uses the default passthough ProgramVertex.  Any bound ProgramVertex
+ * is ignored.  This function has considerable overhead and should not be used
+ * for drawing in shipping applications.
+ *
+ * @param x
+ * @param y
+ * @param z
+ * @param w
+ * @param h
+ */
 extern void __attribute__((overloadable))
     rsgDrawSpriteScreenspace(float x, float y, float z, float w, float h);
 
+/**
+ * Draw a mesh of geometry using the current context state.  The whole mesh is
+ * rendered.
+ *
+ * @param ism
+ */
 extern void __attribute__((overloadable))
     rsgDrawMesh(rs_mesh ism);
 extern void __attribute__((overloadable))
@@ -59,10 +200,23 @@ extern void __attribute__((overloadable))
 extern void __attribute__((overloadable))
     rsgDrawMesh(rs_mesh ism, uint primitiveIndex, uint start, uint len);
 
+/**
+ * Clears the rendering surface to the specified color.
+ *
+ * @param r
+ * @param g
+ * @param b
+ * @param a
+ */
 extern void __attribute__((overloadable))
-    rsgClearColor(float, float, float, float);
+    rsgClearColor(float r, float g, float b, float a);
+
+/**
+ * Clears the depth suface to the specified value.
+ *
+ */
 extern void __attribute__((overloadable))
-    rsgClearDepth(float);
+    rsgClearDepth(float value);
 
 extern void __attribute__((overloadable))
     rsgDrawText(const char *, int x, int y);
@@ -94,12 +248,13 @@ rsgMeshComputeBoundingBox(rs_mesh mesh, float3 *bBoxMin, float3 *bBoxMax) {
     bBoxMax->z = z2;
 }
 
-///////////////////////////////////////////////////////
-// misc
 
-// Depricated
-extern void __attribute__((overloadable))
-    color(float, float, float, float);
+/**
+ * @hide
+ * Deprecated, do not use.
+ *
+ */
+extern void __attribute__((overloadable)) color(float, float, float, float);
 
 #endif
 
diff --git a/libs/rs/scriptc/rs_math.rsh b/libs/rs/scriptc/rs_math.rsh
index a74c0e0..e2719e0 100644
--- a/libs/rs/scriptc/rs_math.rsh
+++ b/libs/rs/scriptc/rs_math.rsh
@@ -1,6 +1,12 @@
 #ifndef __RS_MATH_RSH__
 #define __RS_MATH_RSH__
 
+/**
+ * Copy reference to the specified object.
+ *
+ * @param dst
+ * @param src
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_element *dst, rs_element src);
 extern void __attribute__((overloadable))
@@ -24,6 +30,11 @@ extern void __attribute__((overloadable))
 extern void __attribute__((overloadable))
     rsSetObject(rs_font *dst, rs_font src);
 
+/**
+ * Sets the object to NULL.
+ *
+ * @return bool
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_element *dst);
 extern void __attribute__((overloadable))
@@ -47,6 +58,12 @@ extern void __attribute__((overloadable))
 extern void __attribute__((overloadable))
     rsClearObject(rs_font *dst);
 
+/**
+ * Tests if the object is valid.  Returns true if the object is valid, false if
+ * it is NULL.
+ *
+ * @return bool
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_element);
 extern bool __attribute__((overloadable))
@@ -71,27 +88,58 @@ extern bool __attribute__((overloadable))
     rsIsObject(rs_font);
 
 
-
-// Allocations
-
-// Return the rs_allocation associated with a bound data
-// pointer.
+/**
+ * Returns the Allocation for a given pointer.  The pointer should point within
+ * a valid allocation.  The results are undefined if the pointer is not from a
+ * valid allocation.
+ */
 extern rs_allocation __attribute__((overloadable))
     rsGetAllocation(const void *);
 
-// Mark the allocation dirty and notify those using it
+/**
+ * Mark the contents of an allocation as dirty.  This forces any other scripts
+ * using the allocation to receive the updated
+ */
 extern void __attribute__((overloadable))
     rsAllocationMarkDirty(rs_allocation);
 
-// Return the dimensions associated with an allocation.
+/**
+ * Query the dimension of an allocation.
+ *
+ * @return uint32_t The X dimension of the allocation.
+ */
 extern uint32_t __attribute__((overloadable))
     rsAllocationGetDimX(rs_allocation);
+
+/**
+ * Query the dimension of an allocation.
+ *
+ * @return uint32_t The Y dimension of the allocation.
+ */
 extern uint32_t __attribute__((overloadable))
     rsAllocationGetDimY(rs_allocation);
+
+/**
+ * Query the dimension of an allocation.
+ *
+ * @return uint32_t The Z dimension of the allocation.
+ */
 extern uint32_t __attribute__((overloadable))
     rsAllocationGetDimZ(rs_allocation);
+
+/**
+ * Query an allocation for the presence of more than one LOD.
+ *
+ * @return uint32_t Returns 1 if more than one LOD is present, 0 otherwise.
+ */
 extern uint32_t __attribute__((overloadable))
     rsAllocationGetDimLOD(rs_allocation);
+
+/**
+ * Query an allocation for the presence of more than one face.
+ *
+ * @return uint32_t Returns 1 if more than one face is present, 0 otherwise.
+ */
 extern uint32_t __attribute__((overloadable))
     rsAllocationGetDimFaces(rs_allocation);