From 46e5a036100abf2465378871d69e24f2829194eb Mon Sep 17 00:00:00 2001 From: Stephen Hines Date: Fri, 26 Aug 2011 19:03:16 -0700 Subject: Updated time/type docs for Renderscript. Change-Id: Idb51c64271c4f2b4705ea932c715683003eff4cc --- libs/rs/scriptc/rs_time.rsh | 81 +++++++++++++++++++++++++++++++++------- libs/rs/scriptc/rs_types.rsh | 88 ++++++++++++++++++++++---------------------- 2 files changed, 110 insertions(+), 59 deletions(-) (limited to 'libs/rs') diff --git a/libs/rs/scriptc/rs_time.rsh b/libs/rs/scriptc/rs_time.rsh index f8f297d..60e3dee 100644 --- a/libs/rs/scriptc/rs_time.rsh +++ b/libs/rs/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/libs/rs/scriptc/rs_types.rsh b/libs/rs/scriptc/rs_types.rsh index 875beb9..5d5df60 100644 --- a/libs/rs/scriptc/rs_types.rsh +++ b/libs/rs/scriptc/rs_types.rsh @@ -89,7 +89,7 @@ typedef uint16_t ushort; */ 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 uint32_t size_t; 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 @@ typedef struct { const int* const p; } __attribute__((packed, aligned(4))) rs_fo /** * 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 @@ typedef float4 rs_quaternion; /** * \brief Enum for selecting cube map faces - * - * Used todo-alexst */ typedef enum { RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X = 0, -- cgit v1.1