Updated time/type docs for Renderscript.
Change-Id: Idb51c64271c4f2b4705ea932c715683003eff4cc
diff --git a/scriptc/rs_time.rsh b/scriptc/rs_time.rsh
index f8f297d..60e3dee 100644
--- a/scriptc/rs_time.rsh
+++ b/scriptc/rs_time.rsh
@@ -15,43 +15,96 @@
*/
/** @file rs_time.rsh
- * \brief Time routines
+ * \brief Renderscript time routines
*
- *
+ * This file contains Renderscript functions relating to time and date
+ * manipulation.
*/
#ifndef __RS_TIME_RSH__
#define __RS_TIME_RSH__
+/**
+ * Calendar time interpreted as seconds elapsed since the Epoch (00:00:00 on
+ * January 1, 1970, Coordinated Universal Time (UTC)).
+ */
typedef int rs_time_t;
+/**
+ * Data structure for broken-down time components.
+ *
+ * tm_sec - Seconds after the minute. This ranges from 0 to 59, but possibly
+ * up to 60 for leap seconds.
+ * tm_min - Minutes after the hour. This ranges from 0 to 59.
+ * tm_hour - Hours past midnight. This ranges from 0 to 23.
+ * tm_mday - Day of the month. This ranges from 1 to 31.
+ * tm_mon - Months since January. This ranges from 0 to 11.
+ * tm_year - Years since 1900.
+ * tm_wday - Days since Sunday. This ranges from 0 to 6.
+ * tm_yday - Days since January 1. This ranges from 0 to 365.
+ * tm_isdst - Flag to indicate whether daylight saving time is in effect. The
+ * value is positive if it is in effect, zero if it is not, and
+ * negative if the information is not available.
+ */
typedef struct {
- int tm_sec;
- int tm_min;
- int tm_hour;
- int tm_mday;
- int tm_mon;
- int tm_year;
- int tm_wday;
- int tm_yday;
- int tm_isdst;
+ int tm_sec; ///< seconds
+ int tm_min; ///< minutes
+ int tm_hour; ///< hours
+ int tm_mday; ///< day of the month
+ int tm_mon; ///< month
+ int tm_year; ///< year
+ int tm_wday; ///< day of the week
+ int tm_yday; ///< day of the year
+ int tm_isdst; ///< daylight savings time
} rs_tm;
+/**
+ * Returns the number of seconds since the Epoch (00:00:00 UTC, January 1,
+ * 1970). If @p timer is non-NULL, the result is also stored in the memory
+ * pointed to by this variable. If an error occurs, a value of -1 is returned.
+ *
+ * @param timer Location to also store the returned calendar time.
+ *
+ * @return Seconds since the Epoch.
+ */
extern rs_time_t __attribute__((overloadable))
rsTime(rs_time_t *timer);
+/**
+ * Converts the time specified by @p timer into broken-down time and stores it
+ * in @p local. This function also returns a pointer to @p local. If @p local
+ * is NULL, this function does nothing and returns NULL.
+ *
+ * @param local Broken-down time.
+ * @param timer Input time as calendar time.
+ *
+ * @return Pointer to broken-down time (same as input @p local).
+ */
extern rs_tm * __attribute__((overloadable))
rsLocaltime(rs_tm *local, const rs_time_t *timer);
-// Return the current system clock in milliseconds
+/**
+ * Returns the current system clock (uptime) in milliseconds.
+ *
+ * @return Uptime in milliseconds.
+ */
extern int64_t __attribute__((overloadable))
rsUptimeMillis(void);
-// Return the current system clock in nanoseconds
+/**
+ * Returns the current system clock (uptime) in nanoseconds.
+ *
+ * @return Uptime in nanoseconds.
+ */
extern int64_t __attribute__((overloadable))
rsUptimeNanos(void);
-// Return the time in seconds since function was last called in this script.
+/**
+ * Returns the time in seconds since this function was last called in this
+ * script.
+ *
+ * @return Time in seconds.
+ */
extern float __attribute__((overloadable))
rsGetDt(void);
diff --git a/scriptc/rs_types.rsh b/scriptc/rs_types.rsh
index 875beb9..5d5df60 100644
--- a/scriptc/rs_types.rsh
+++ b/scriptc/rs_types.rsh
@@ -89,7 +89,7 @@
*/
typedef uint32_t uint;
/**
- * Typedef for unsigned char (use for 64-bit unsigned integers)
+ * Typedef for unsigned long (use for 64-bit unsigned integers)
*/
typedef uint64_t ulong;
/**
@@ -102,67 +102,67 @@
typedef int32_t ssize_t;
/**
- * \brief Opaque handle to a RenderScript element.
+ * \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.
+ * \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.
+ * \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.
+ * \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.
+ * \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.
+ * \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.
+ * \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.
+ * \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.
+ * \brief Opaque handle to a Renderscript ProgramRaster object.
*
- * See: android.renderscript.Sampler
+ * See: android.renderscript.ProgramRaster
*/
typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_program_raster;
/**
- * \brief Opaque handle to a RenderScript ProgramStore object.
+ * \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.
+ * \brief Opaque handle to a Renderscript font object.
*
* See: android.renderscript.Font
*/
@@ -170,163 +170,163 @@
/**
* Vector version of the basic float type.
- * Provides two float fields packed into a single 64bit field with 64 bit
+ * Provides two float fields packed into a single 64 bit 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.
+ * into a single 128 bit 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
+ * Provides four float fields packed into a single 128 bit field with 128 bit
* 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.
+ * into a single 128 bit field with 128 bit 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.
+ * into a single 256 bit field with 256 bit 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.
+ * into a single 256 bit field with 256 bit 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.
+ * into a single 16 bit field with 16 bit 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.
+ * into a single 32 bit field with 32 bit 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.
+ * into a single 32 bit field with 32 bit 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.
+ * into a single 32 bit field with 32 bit 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.
+ * into a single 64 bit field with 64 bit 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.
+ * into a single 64 bit field with 64 bit 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.
+ * single 64 bit field with 64 bit 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.
+ * a single 128 bit field with 128 bit 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.
+ * a single 128 bit field with 128 bit 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.
+ * a single 128 bit field with 128 bit 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.
+ * into a single 256 bit field with 256 bit 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.
+ * into a single 256 bit field with 256 bit 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.
+ * single 16 bit field with 16 bit 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.
+ * a single 32 bit field with 32 bit 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.
+ * a single 32 bit field with 32 bit 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.
+ * a single 32 bit field with 32 bit 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.
+ * into a single 64 bit field with 64 bit 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.
+ * into a single 64 bit field with 64 bit 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.
+ * single 64 bit field with 64 bit 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.
+ * single 128 bit field with 128 bit 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.
+ * single 128 bit field with 128 bit 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.
+ * single 128 bit field with 128 bit 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.
+ * a single 256 bit field with 256 bit 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.
+ * a single 256 bit field with 256 bit alignment.
*/
typedef long long4 __attribute__((ext_vector_type(4)));
@@ -369,8 +369,6 @@
/**
* \brief Enum for selecting cube map faces
- *
- * Used todo-alexst
*/
typedef enum {
RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X = 0,