Merge "Add docs to rs_types.rsh"

2 files changed, 484 insertions, 34 deletions

diff --git a/libs/rs/scriptc/rs_math.rsh b/libs/rs/scriptc/rs_math.rsh
index 1d36cc6..e44c051 100644
--- a/libs/rs/scriptc/rs_math.rsh
+++ b/libs/rs/scriptc/rs_math.rsh
@@ -1,32 +1,70 @@
+/** @file rs_math.rsh
+ *  \brief todo-jsams
+ *
+ *  todo-jsams
+ *
+ */
 #ifndef __RS_MATH_RSH__
 #define __RS_MATH_RSH__
 
+
+
 /**
- * Copy reference to the specified object.
- *
- * @param dst
- * @param src
+ * \overload
  */
 extern void __attribute__((overloadable))
     rsSetObject(rs_element *dst, rs_element src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_type *dst, rs_type src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_allocation *dst, rs_allocation src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_sampler *dst, rs_sampler src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_script *dst, rs_script src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_mesh *dst, rs_mesh src);
+/**
+ * Copy reference to the specified object.
+ *
+ * @param dst
+ * @param src
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_program_fragment *dst, rs_program_fragment src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_program_vertex *dst, rs_program_vertex src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_program_raster *dst, rs_program_raster src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_program_store *dst, rs_program_store src);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSetObject(rs_font *dst, rs_font src);
 
@@ -37,53 +75,114 @@ extern void __attribute__((overloadable))
  */
 extern void __attribute__((overloadable))
     rsClearObject(rs_element *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_type *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_allocation *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_sampler *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_script *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_mesh *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_program_fragment *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_program_vertex *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_program_raster *dst);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsClearObject(rs_program_store *dst);
+/**
+ * \overload
+ */
 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
+ * \overload
  */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_element);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_type);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_allocation);
+/**
+ * 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_sampler);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_script);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_mesh);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_program_fragment);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_program_vertex);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_program_raster);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_program_store);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsIsObject(rs_font);
 
@@ -188,46 +287,82 @@ extern void __attribute__((overloadable))
                             uint32_t srcMip,
                             rs_allocation_cubemap_face srcFace);
 
-// Extract a single element from an allocation.
+
+/**
+ * Extract a single element from an allocation.
+ */
 extern const void * __attribute__((overloadable))
     rsGetElementAt(rs_allocation, uint32_t x);
+/**
+ * \overload
+ */
 extern const void * __attribute__((overloadable))
     rsGetElementAt(rs_allocation, uint32_t x, uint32_t y);
+/**
+ * \overload
+ */
 extern const void * __attribute__((overloadable))
     rsGetElementAt(rs_allocation, uint32_t x, uint32_t y, uint32_t z);
 
-// Return a random value between 0 (or min_value) and max_malue.
+/**
+ * Return a random value between 0 (or min_value) and max_malue.
+ */
 extern int __attribute__((overloadable))
     rsRand(int max_value);
+/**
+ * \overload
+ */
 extern int __attribute__((overloadable))
     rsRand(int min_value, int max_value);
+/**
+ * \overload
+ */
 extern float __attribute__((overloadable))
     rsRand(float max_value);
+/**
+ * \overload
+ */
 extern float __attribute__((overloadable))
     rsRand(float min_value, float max_value);
 
-// return the fractional part of a float
-// min(v - ((int)floor(v)), 0x1.fffffep-1f);
+/**
+ * Returns the fractional part of a float
+ */
 extern float __attribute__((overloadable))
     rsFrac(float);
 
-// Send a message back to the client.  Will not block and returns true
-// if the message was sendable and false if the fifo was full.
-// A message ID is required.  Data payload is optional.
+/**
+ * Send a message back to the client.  Will not block and returns true
+ * if the message was sendable and false if the fifo was full.
+ * A message ID is required.  Data payload is optional.
+ */
 extern bool __attribute__((overloadable))
     rsSendToClient(int cmdID);
+/**
+ * \overload
+ */
 extern bool __attribute__((overloadable))
     rsSendToClient(int cmdID, const void *data, uint len);
-
-// Send a message back to the client, blocking until the message is queued.
-// A message ID is required.  Data payload is optional.
+/**
+ * Send a message back to the client, blocking until the message is queued.
+ * A message ID is required.  Data payload is optional.
+ */
 extern void __attribute__((overloadable))
     rsSendToClientBlocking(int cmdID);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsSendToClientBlocking(int cmdID, const void *data, uint len);
 
 
-// Script to Script
+/**
+ * Launch order hint for rsForEach calls.  This provides a hint to the system to
+ * determine in which order the root function of the target is called with each
+ * cell of the allocation.
+ *
+ * This is a hint and implementations may not obey the order.
+ */
 enum rs_for_each_strategy {
     RS_FOR_EACH_STRATEGY_SERIAL,
     RS_FOR_EACH_STRATEGY_DONT_CARE,
@@ -237,6 +372,11 @@ enum rs_for_each_strategy {
     RS_FOR_EACH_STRATEGY_TILE_LARGE
 };
 
+
+/**
+ * Structure to provide extra information to a rsForEach call.  Primarly used to
+ * restrict the call to a subset of cells in the allocation.
+ */
 typedef struct rs_script_call {
     enum rs_for_each_strategy strategy;
     uint32_t xStart;
@@ -249,26 +389,67 @@ typedef struct rs_script_call {
     uint32_t arrayEnd;
 } rs_script_call_t;
 
+/**
+ * Make a script to script call to launch work. One of the input or output is
+ * required to be a valid object. The input and output must be of the same
+ * dimensions.
+ * API 10-13
+ *
+ * @param script The target script to call
+ * @param input The allocation to source data from
+ * @param output the allocation to write date into
+ * @param usrData The user definied params to pass to the root script.  May be
+ *                NULL.
+ * @param sc Extra control infomation used to select a sub-region of the
+ *           allocation to be processed or suggest a walking strategy.  May be
+ *           NULL.
+ *
+ *  */
 #if !defined(RS_VERSION) || (RS_VERSION < 14)
 extern void __attribute__((overloadable))
-    rsForEach(rs_script script, rs_allocation input,
+    rsForEach(rs_script script script, rs_allocation input,
               rs_allocation output, const void * usrData,
-              const rs_script_call_t *);
-
+              const rs_script_call_t *sc);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsForEach(rs_script script, rs_allocation input,
               rs_allocation output, const void * usrData);
 #else
-extern void __attribute__((overloadable))
-    rsForEach(rs_script script, rs_allocation input, rs_allocation output);
 
+/**
+ * Make a script to script call to launch work. One of the input or output is
+ * required to be a valid object. The input and output must be of the same
+ * dimensions.
+ * API 14+
+ *
+ * @param script The target script to call
+ * @param input The allocation to source data from
+ * @param output the allocation to write date into
+ * @param usrData The user definied params to pass to the root script.  May be
+ *                NULL.
+ * @param usrDataLen The size of the userData structure.  This will be used to
+ *                   perform a shallow copy of the data if necessary.
+ * @param sc Extra control infomation used to select a sub-region of the
+ *           allocation to be processed or suggest a walking strategy.  May be
+ *           NULL.
+ *
+ */
 extern void __attribute__((overloadable))
     rsForEach(rs_script script, rs_allocation input, rs_allocation output,
-              const void * usrData, size_t usrDataLen);
-
+              const void * usrData, size_t usrDataLen, const rs_script_call_t *);
+/**
+ * \overload
+ */
 extern void __attribute__((overloadable))
     rsForEach(rs_script script, rs_allocation input, rs_allocation output,
-              const void * usrData, size_t usrDataLen, const rs_script_call_t *);
+              const void * usrData, size_t usrDataLen);
+/**
+ * \overload
+ */
+extern void __attribute__((overloadable))
+    rsForEach(rs_script script, rs_allocation input, rs_allocation output);
 #endif
 
 
diff --git a/libs/rs/scriptc/rs_types.rsh b/libs/rs/scriptc/rs_types.rsh
index 121e013..9a79f5e 100644
--- a/libs/rs/scriptc/rs_types.rsh
+++ b/libs/rs/scriptc/rs_types.rsh
@@ -1,98 +1,361 @@
+/** @file rs_time.rsh
+ *
+ *  Define the standard Renderscript types
+ *
+ *  Integers
+ *  8 bit: char, int8_t
+ *  16 bit: short, int16_t
+ *  32 bit: int, in32_t
+ *  64 bit: long, long long, int64_t
+ *
+ *  Unsigned Integers
+ *  8 bit: uchar, uint8_t
+ *  16 bit: ushort, uint16_t
+ *  32 bit: uint, uint32_t
+ *  64 bit: ulong, uint64_t
+ *
+ *  Floating point
+ *  32 bit: float
+ *  64 bit: double
+ *
+ *  Vectors of length 2, 3, and 4 are supported for all the types above.
+ *
+ */
+
 #ifndef __RS_TYPES_RSH__
 #define __RS_TYPES_RSH__
 
 #define M_PI        3.14159265358979323846264338327950288f   /* pi */
 
 #include "stdbool.h"
+/**
+ * 8 bit integer type
+ */
 typedef char int8_t;
+/**
+ * 16 bit integer type
+ */
 typedef short int16_t;
+/**
+ * 32 bit integer type
+ */
 typedef int int32_t;
+/**
+ * 64 bit integer type
+ */
 typedef long long int64_t;
-
+/**
+ * 8 bit unsigned integer type
+ */
 typedef unsigned char uint8_t;
+/**
+ * 16 bit unsigned integer type
+ */
 typedef unsigned short uint16_t;
+/**
+ * 32 bit unsigned integer type
+ */
 typedef unsigned int uint32_t;
+/**
+ * 64 bit unsigned integer type
+ */
 typedef unsigned long long uint64_t;
-
+/**
+ * 8 bit unsigned integer type
+ */
 typedef uint8_t uchar;
+/**
+ * 16 bit unsigned integer type
+ */
 typedef uint16_t ushort;
+/**
+ * 32 bit unsigned integer type
+ */
 typedef uint32_t uint;
+/**
+ * Typedef for unsigned char (use for 64-bit unsigned integers)
+ */
 typedef uint64_t ulong;
-
+/**
+ * Typedef for unsigned int
+ */
 typedef uint32_t size_t;
+/**
+ * Typedef for int (use for 32-bit integers)
+ */
 typedef int32_t ssize_t;
 
+/**
+ * \brief Opaque handle to a RenderScript element.
+ *
+ * See: android.renderscript.Element
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_element;
+/**
+ * \brief Opaque handle to a RenderScript type.
+ *
+ * See: android.renderscript.Type
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_type;
+/**
+ * \brief Opaque handle to a RenderScript allocation.
+ *
+ * See: android.renderscript.Allocation
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_allocation;
+/**
+ * \brief Opaque handle to a RenderScript sampler object.
+ *
+ * See: android.renderscript.Sampler
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_sampler;
+/**
+ * \brief Opaque handle to a RenderScript script object.
+ *
+ * See: android.renderscript.ScriptC
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_script;
+/**
+ * \brief Opaque handle to a RenderScript mesh object.
+ *
+ * See: android.renderscript.Mesh
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_mesh;
+/**
+ * \brief Opaque handle to a RenderScript ProgramFragment object.
+ *
+ * See: android.renderscript.ProgramFragment
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_program_fragment;
+/**
+ * \brief Opaque handle to a RenderScript ProgramVertex object.
+ *
+ * See: android.renderscript.ProgramVertex
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_program_vertex;
+/**
+ * \brief Opaque handle to a RenderScript sampler object.
+ *
+ * See: android.renderscript.Sampler
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_program_raster;
+/**
+ * \brief Opaque handle to a RenderScript ProgramStore object.
+ *
+ * See: android.renderscript.ProgramStore
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_program_store;
+/**
+ * \brief Opaque handle to a RenderScript font object.
+ *
+ * See: android.renderscript.Font
+ */
 typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_font;
 
-
+/**
+ * Vector version of the basic float type.
+ * Provides two float fields packed into a single 64bit field with 64 bit
+ * alignment.
+ */
 typedef float float2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic float type. Provides three float fields packed
+ * into a single 128bit field with 128 bit alignment.
+ */
 typedef float float3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic float type.
+ * Provides four float fields packed into a single 128bit field with 128bit
+ * alignment.
+ */
 typedef float float4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic double type. Provides two double fields packed
+ * into a single 128bit field with 128bit alignment.
+ */
 typedef double double2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic double type. Provides three double fields packed
+ * into a single 256bit field with 256bit alignment.
+ */
 typedef double double3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic double type. Provides four double fields packed
+ * into a single 256bit field with 256bit alignment.
+ */
 typedef double double4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic uchar type. Provides two uchar fields packed
+ * into a single 16bit field with 16bit alignment.
+ */
 typedef uchar uchar2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic uchar type. Provides three uchar fields packed
+ * into a single 32bit field with 32bit alignment.
+ */
 typedef uchar uchar3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic uchar type. Provides four uchar fields packed
+ * into a single 32bit field with 32bit alignment.
+ */
 typedef uchar uchar4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic ushort type. Provides two ushort fields packed
+ * into a single 32bit field with 32bit alignment.
+ */
 typedef ushort ushort2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic ushort type. Provides three ushort fields packed
+ * into a single 64bit field with 64bit alignment.
+ */
 typedef ushort ushort3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic ushort type. Provides four ushort fields packed
+ * into a single 64bit field with 64bit alignment.
+ */
 typedef ushort ushort4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic uint type. Provides two uint fields packed into a
+ * single 64bit field with 64bit alignment.
+ */
 typedef uint uint2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic uint type. Provides three uint fields packed into
+ * a single 128bit field with 128bit alignment.
+ */
 typedef uint uint3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic uint type. Provides four uint fields packed into
+ * a single 128bit field with 128bit alignment.
+ */
 typedef uint uint4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic ulong type. Provides two ulong fields packed into
+ * a single 128bit field with 128bit alignment.
+ */
 typedef ulong ulong2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic ulong type. Provides three ulong fields packed
+ * into a single 256bit field with 256bit alignment.
+ */
 typedef ulong ulong3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic ulong type. Provides four ulong fields packed
+ * into a single 256bit field with 256bit alignment.
+ */
 typedef ulong ulong4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic char type. Provides two char fields packed into a
+ * single 16bit field with 16bit alignment.
+ */
 typedef char char2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic char type. Provides three char fields packed into
+ * a single 32bit field with 32bit alignment.
+ */
 typedef char char3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic char type. Provides four char fields packed into
+ * a single 32bit field with 32bit alignment.
+ */
 typedef char char4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic short type. Provides two short fields packed into
+ * a single 32bit field with 32bit alignment.
+ */
 typedef short short2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic short type. Provides three short fields packed
+ * into a single 64bit field with 64bit alignment.
+ */
 typedef short short3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic short type. Provides four short fields packed
+ * into a single 64bit field with 64bit alignment.
+ */
 typedef short short4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic int type. Provides two int fields packed into a
+ * single 64bit field with 64bit alignment.
+ */
 typedef int int2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic int type. Provides three int fields packed into a
+ * single 128bit field with 128bit alignment.
+ */
 typedef int int3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic int type. Provides two four fields packed into a
+ * single 128bit field with 128bit alignment.
+ */
 typedef int int4 __attribute__((ext_vector_type(4)));
 
+/**
+ * Vector version of the basic long type. Provides two long fields packed into a
+ * single 128bit field with 128bit alignment.
+ */
 typedef long long2 __attribute__((ext_vector_type(2)));
+/**
+ * Vector version of the basic long type. Provides three long fields packed into
+ * a single 256bit field with 256bit alignment.
+ */
 typedef long long3 __attribute__((ext_vector_type(3)));
+/**
+ * Vector version of the basic long type. Provides four long fields packed into
+ * a single 256bit field with 256bit alignment.
+ */
 typedef long long4 __attribute__((ext_vector_type(4)));
 
+/**
+ * \brief 4x4 float matrix
+ *
+ * Native holder for RS matrix.  Elements are stored in the array at the
+ * location [row*4 + col]
+ */
 typedef struct {
     float m[16];
 } rs_matrix4x4;
-
+/**
+ * \brief 3x3 float matrix
+ *
+ * Native holder for RS matrix.  Elements are stored in the array at the
+ * location [row*3 + col]
+ */
 typedef struct {
     float m[9];
 } rs_matrix3x3;
-
+/**
+ * \brief 2x2 float matrix
+ *
+ * Native holder for RS matrix.  Elements are stored in the array at the
+ * location [row*2 + col]
+ */
 typedef struct {
     float m[4];
 } rs_matrix2x2;
 
+/**
+ * quaternion type for use with the quaternion functions
+ */
 typedef float4 rs_quaternion;
 
 #define RS_PACKED __attribute__((packed, aligned(4)))
-
 #define NULL ((const void *)0)
 
+
+/**
+ * \brief Enum for selecting cube map faces
+ *
+ * Used todo-alexst
+ */
 typedef enum {
     RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X = 0,
     RS_ALLOCATION_CUBEMAP_FACE_NEGATIVE_X = 1,
@@ -102,6 +365,12 @@ typedef enum {
     RS_ALLOCATION_CUBEMAP_FACE_NEGATIVE_Z = 5
 } rs_allocation_cubemap_face;
 
+/**
+ * \brief Bitfield to specify the usage types for an allocation.
+ *
+ * These values are ORed together to specify which usages or memory spaces are
+ * relevant to an allocation or an operation on an allocation.
+ */
 typedef enum {
     RS_ALLOCATION_USAGE_SCRIPT = 0x0001,
     RS_ALLOCATION_USAGE_GRAPHICS_TEXTURE = 0x0002,