From a00e6d8bf175034a9c6323b0177100978222d657 Mon Sep 17 00:00:00 2001 From: Jason Sams Date: Mon, 8 Aug 2011 14:31:25 -0700 Subject: Add docs to rs_types.rsh Change-Id: Id2352f325c3ef9564cc226c6c5df908df16bb26a --- libs/rs/scriptc/rs_math.rsh | 235 ++++++++++++++++++++++++++++++----- libs/rs/scriptc/rs_types.rsh | 283 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 484 insertions(+), 34 deletions(-) (limited to 'libs/rs') 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, -- cgit v1.1