计算：RenderScript Runtime API参考：简介

一、概论

RenderScript是一个高性能的运行时，可以在本机级别提供计算操作。 RenderScript代码在运行时在设备上编译，以允许平台独立性。

本参考文档介绍了RenderScript运行时API，您可以使用它来编写C99中的RenderScript代码。 自动为你包含RenderScript计算头文件。

要使用RenderScript，您需要使用此处记录的RenderScript运行时API以及RenderScript的Android框架API。 有关Android框架API的文档，请参阅android.renderscript软件包参考。

有关如何使用RenderScript开发以及运行时和Android框架API如何交互的更多信息，请参阅RenderScript开发人员指南和RenderScript示例。

二、数值类型

1、标量

RenderScript支持以下标量数值类型：

RenderScript支持长度为2,3和4.的固定大小向量。使用通用类型名称后跟2,3或4.声明向量。 float4，int3，double2，ulong4。

 8 bits16 bits32 bits64 bitsInteger:char, int8_tshort, int16_tint32_tlong, long long, int64_tUnsigned integer:uchar, uint8_tushort, uint16_tuint, uint32_tulong, uint64_tFloating point: halffloatdouble

2、矢量

RenderScript支持长度为2,3和4.的固定大小向量。使用通用类型名称后跟2,3或4.声明向量。 float4，int3，double2，ulong4。

要创建矢量文字，请使用矢量类型，后跟大括号之间的值，例如。 （float3）{1.0f，2.0f，3.0f}。

可以使用不同的命名样式来访问向量的条目。

可以通过使用点跟随变量名称来访问单个条目：

1、字母x，y，z和w，

2、字母r，g，b和a，

3、字母s或S，后跟零索引。

例如，使用int4 myVar; 以下是等效的：

myVar.x == myVar.r == myVar.s0 == myVar.S0myVar.y == myVar.g == myVar.s1 == myVar.S1myVar.z == myVar.b == myVar.s2 == myVar.S2myVar.w == myVar.a == myVar.s3 == myVar.S3

可以通过使用多个字母或索引的连接的标识符一次访问向量的多个条目。 结果向量的大小等于命名的条目数。

通过上面的例子，可以使用myVar.yz，myVar.gb，myVar.s12和myVar.S12访问中间的两个条目。

条目不必是连续的或按照递增的顺序。 条目甚至可以重复，只要我们不试图分配它。 您也不能混合命名样式。

以下是可以做什么或不能做的例子：

float4 v4;float3 v3;float2 v2;v2 = v4.xx; // Validv3 = v4.zxw; // Validv3 = v4.bba; // Validv3 = v4.s032; // Validv3.s120 = v4.S233; // Validv4.yz = v3.rg; // Validv4.yzx = v3.rg; // Invalid: mismatched sizesv4.yzz = v3; // Invalid: z appears twice in an assignmentv3 = v3.xas0; // Invalid: can't mix xyzw with rgba nor s0...v3 = v4.s034; // Invalid: the digit can only be 0, 1, 2, or 3

3、矩阵和四元数

RenderScript支持大小为2x2,3x3和4x4的固定尺寸的浮点矩阵。 这些类型命名为rs_matrix2x2，rs_matrix3x3和rs_matrix4x4。 有关操作列表，请参阅矩阵函数。

四元数也被rs四元数支持。 有关操作列表，请参见四元数函数。

Typeschar2Two 8 bit signed integerschar3Three 8 bit signed integerschar4Four 8 bit signed integersdouble2Two 64 bit floatsdouble3Three 64 bit floatsdouble4Four 64 bit floatsfloat2Two 32 bit floatsfloat3Three 32 bit floatsfloat4Four 32 bit floatshalf16 bit floating point valuehalf2Two 16 bit floatshalf3Three 16 bit floatshalf4Four 16 bit floatsint16_t16 bit signed integerint2Two 32 bit signed integersint3Three 32 bit signed integersint32_t32 bit signed integerint4Four 32 bit signed integersint64_t64 bit signed integerint8_t8 bit signed integerlong2Two 64 bit signed integerslong3Three 64 bit signed integerslong4Four 64 bit signed integersrs_matrix2x22x2 matrix of 32 bit floatsrs_matrix3x33x3 matrix of 32 bit floatsrs_matrix4x44x4 matrix of 32 bit floatsrs_quaternionQuaternionshort2Two 16 bit signed integersshort3Three 16 bit signed integersshort4Four 16 bit signed integerssize_tUnsigned size typessize_tSigned size typeuchar8 bit unsigned integeruchar2Two 8 bit unsigned integersuchar3Three 8 bit unsigned integersuchar4Four 8 bit unsigned integersuint32 bit unsigned integeruint16_t16 bit unsigned integeruint2Two 32 bit unsigned integersuint3Three 32 bit unsigned integersuint32_t32 bit unsigned integeruint4Four 32 bit unsigned integersuint64_t64 bit unsigned integeruint8_t8 bit unsigned integerulong64 bit unsigned integerulong2Two 64 bit unsigned integersulong3Three 64 bit unsigned integersulong4Four 64 bit unsigned integersushort16 bit unsigned integerushort2Two 16 bit unsigned integersushort3Three 16 bit unsigned integersushort4Four 16 bit unsigned integers

三、对象类型

以下类型用于操作RenderScript对象，如分配，采样器，元素和脚本。 大多数这些对象是使用Java RenderScript API创建的。

Typesrs_allocationHandle to an allocationrs_allocation_cubemap_faceEnum for selecting cube map facesrs_allocation_usage_typeBitfield to specify how an allocation is usedrs_data_kindElement data kindrs_data_typeElement basic data typers_elementHandle to an elementrs_samplerHandle to a Samplerrs_sampler_valueSampler wrap T valuers_scriptHandle to a Scriptrs_typeHandle to a Type

四、转换函数

以下功能将数字矢量类型转换为另一种，或从一种颜色表示转换为另一种。

FunctionsconvertConvert numerical vectorsrsPackColorTo8888Create a uchar4 RGBA from floatsrsUnpackColor8888Create a float4 RGBA from uchar4rsYuvToRGBAConvert a YUV value to RGBA

五、数学常数和函数

下面的数学函数可以应用于标量和向量。 当应用于向量时，返回的值是应用于输入的每个条目的函数的向量。

例如：

float3 a, b;// The following call sets// a.x to sin(b.x),// a.y to sin(b.y), and// a.z to sin(b.z).a = sin(b);

参见vector（）函数，如distance（）和length（），将输入解释为n维空间中的单个向量。

32位浮点数学运算的精度受编译指示rs_fp_relaxed和rs_fp_full的影响。 在rs_fp_relaxed下，可能会将低于正常值的值刷新为零，并可以向零舍入。 相比之下，rs_fp_full需要对正常值进行正确处理，即小于1.17549435e-38f。 rs_fp_rull也需要一轮到最接近的连线。

通过使用常用数学函数的变体可以实现不同的精度/速度权衡。 名称以

1、native_：可能具有较低精度的定制硬件实现。 另外，亚正态值可以被刷新为零，可以使用向零舍入，并且可以不正确地处理NaN和无穷大输入。

2、half_：可以使用16位浮点进行内部计算。 另外，可以将次正规值刷新为零，并且可以使用向零舍入。

常量M_1_PI1 / pi, as a 32 bit floatM_2_PI2 / pi, as a 32 bit floatM_2_SQRTPI2 / sqrt(pi), as a 32 bit floatM_Ee, as a 32 bit floatM_LN10log_e(10), as a 32 bit floatM_LN2log_e(2), as a 32 bit floatM_LOG10Elog_10(e), as a 32 bit floatM_LOG2Elog_2(e), as a 32 bit floatM_PIpi, as a 32 bit floatM_PI_2pi / 2, as a 32 bit floatM_PI_4pi / 4, as a 32 bit floatM_SQRT1_21 / sqrt(2), as a 32 bit floatM_SQRT2sqrt(2), as a 32 bit float

函数absAbsolute value of an integeracosInverse cosineacoshInverse hyperbolic cosineacospiInverse cosine divided by piasinInverse sineasinhInverse hyperbolic sineasinpiInverse sine divided by piatanInverse tangentatan2Inverse tangent of a ratioatan2piInverse tangent of a ratio, divided by piatanhInverse hyperbolic tangentatanpiInverse tangent divided by picbrtCube rootceilSmallest integer not less than a valueclampRestrain a value to a rangeclzNumber of leading 0 bitscopysignCopies the sign of a number to anothercosCosinecoshHypebolic cosinecospiCosine of a number multiplied by pidegreesConverts radians into degreeserfMathematical error functionerfcMathematical complementary error functionexpe raised to a numberexp1010 raised to a numberexp22 raised to a numberexpm1e raised to a number minus onefabsAbsolute value of a floatfdimPositive difference between two valuesfloorSmallest integer not greater than a valuefmaMultiply and addfmaxMaximum of two floatsfminMinimum of two floatsfmodModulofractPositive fractional partfrexpBinary mantissa and exponenthalf_recipReciprocal computed to 16 bit precisionhalf_rsqrtReciprocal of a square root computed to 16 bit precisionhalf_sqrtSquare root computed to 16 bit precisionhypotHypotenuseilogbBase two exponentldexpCreates a floating point from mantissa and exponentlgammaNatural logarithm of the gamma functionlogNatural logarithmlog10Base 10 logarithmlog1pNatural logarithm of a value plus 1log2Base 2 logarithmlogbBase two exponentmadMultiply and addmaxMaximumminMinimummixMixes two valuesmodfIntegral and fractional componentsnanNot a Numbernative_acosApproximate inverse cosinenative_acoshApproximate inverse hyperbolic cosinenative_acospiApproximate inverse cosine divided by pinative_asinApproximate inverse sinenative_asinhApproximate inverse hyperbolic sinenative_asinpiApproximate inverse sine divided by pinative_atanApproximate inverse tangentnative_atan2Approximate inverse tangent of a rationative_atan2piApproximate inverse tangent of a ratio, divided by pinative_atanhApproximate inverse hyperbolic tangentnative_atanpiApproximate inverse tangent divided by pinative_cbrtApproximate cube rootnative_cosApproximate cosinenative_coshApproximate hypebolic cosinenative_cospiApproximate cosine of a number multiplied by pinative_divideApproximate divisionnative_expApproximate e raised to a numbernative_exp10Approximate 10 raised to a numbernative_exp2Approximate 2 raised to a numbernative_expm1近似e上升到数字减1native_hypot近似斜边native_log近似自然对数native_log10近似基数10对数native_log1p值的近似自然对数加1native_log2近似基数2对数native_powr近似积极的基数升至指数native_recip近似倒数native_rootn近似第n个根native_rsqrt平方根的近似倒数native_sin近似正弦native_sincos大概正弦和余弦native_sinh近似双曲正弦native_sinpi一个数字的近似正弦乘以pinative_sqrt近似平方根native_tan近似切线native_tanh近似双曲正切native_tanpi一个数字的近似正切乘以pinextafter下一个浮点数pow基数提升到指数pown基数提升为整数指数powr正的基数上升到指数radians将度数转换为弧度remainder剩余部门remquo一个除法的余数和商数rintRound to evenrootn第N根round从零开始rsRand伪随机数rsqrt平方根的倒数sign一个价值的标志sin正弦sincos正弦和余弦sinh双曲正弦sinpi正弦数乘以pisqrt平方根step如果小于0，则为0，否则为0tan切线tanh双曲正切tanpi一个数字的相切乘以pitgamma伽玛功能trunc截断一个浮点

六、矢量数学函数

这些函数将输入参数解释为n维空间中向量的表示。

32位浮点数学运算的精度受编译指示rs_fp_relaxed和rs_fp_full的影响。 有关详细信息，请参见数学常数和函数。

通过使用常用数学函数的变体可以实现不同的精度/速度权衡。 名称以

1、native_：可能具有较低精度的定制硬件实现。 另外，亚正态值可以被刷新为零，可以使用向零舍入，并且可以不正确地处理NaN和无穷大输入。

2、fast_：可以使用16位浮点进行内部计算。 另外，可以将次正规值刷新为零，并且可以使用向零舍入。

Functionscross两个向量的交叉乘积distance两点之间的距离dot两个向量的点积fast_distance两点之间的近似距离fast_length矢量的近似长度fast_normalize近似归一化矢量length一个向量的长度native_distance两点之间的近似距离native_length矢量的近似长度native_normalize大概归一化一个向量normalize归一化矢量

七、矩阵函数

这些函数可以让您处理2×2,3×3和4×4级的方阵。 它们对于图形转换特别有用，并且与OpenGL兼容。

我们对行和列使用基于零的索引。 例如。 （3，3）找到rs_matrix4x4的最后一个元素。

RenderScript使用列主要矩阵和基于列的向量。 通过后向量来完成向量的变换，例如 （matrix * vector），由rsMatrixMultiply（）提供。

为了创建一次执行两个变换的变换矩阵，乘以两个源矩阵，第一个变换作为正确的参数。 例如。 创建一个转换矩阵，该矩阵应用s1后跟s2，调用rsMatrixLoadMultiply（＆combined，＆s2，＆s1）。 这来自s2 *（s1 * v），它是（s2 * s1）* v。

我们有两种风格的函数来创建转换矩阵：rsMatrixLoadTransformation和rsMatrixTransformation。 前一种风格只是将变换矩阵存储在第一个参数中。 后者修改了一个预先存在的转换矩阵，以便首先发生新的变换。 例如。 如果在已经进行缩放的矩阵上调用rsMatrixTranslate（），则应用于向量的矩阵将首先进行转换，然后进行缩放。

函数rsExtractFrustumPlanes计算平头锥体水平面rsIsSphereInFrustum检查球体是否在平截头体水平面内rsMatrixGet获得一个元素rsMatrixInverse将矩阵反转到位rsMatrixInverseTranspose反转并将矩阵转置到位rsMatrixLoad加载或复制矩阵rsMatrixLoadFrustum加载平截头体投影矩阵rsMatrixLoadIdentity加载标识矩阵rsMatrixLoadMultiply乘以两个矩阵rsMatrixLoadOrtho加载正投影矩阵rsMatrixLoadPerspective加载透视投影矩阵rsMatrixLoadRotate加载旋转矩阵rsMatrixLoadScale加载缩放矩阵rsMatrixLoadTranslate加载一个翻译矩阵rsMatrixMultiply通过矢量或另一个矩阵乘以一个矩阵rsMatrixRotate对转换矩阵应用旋转rsMatrixScale应用缩放到转换矩阵rsMatrixSet设置一个元素rsMatrixTranslate将转换应用于转换矩阵rsMatrixTranspose转置矩阵位置

八、四元函数

以下函数操纵四元数。

函数rsQuaternionAdd添加两个四元数rsQuaternionConjugate共轭四元数rsQuaternionDot两个四元数的点积rsQuaternionGetMatrixUnit从四元数得到旋转矩阵rsQuaternionLoadRotate创建一个旋转四元数rsQuaternionLoadRotateUnit表示围绕任意单位向量的旋转的四元数rsQuaternionMultiply将四元数乘以标量或其他四元数rsQuaternionNormalize归一化四元数rsQuaternionSet创建四元数rsQuaternionSlerp两个四元数之间的球面线性插值

九、原子更新函数

要更新多个线程之间共享的值，请使用以下功能。 它们确保值被原子更新，即存储器读取，更新和存储器写入以正确的顺序完成。

这些功能比其非原子等价物要慢，因此只有在需要同步时才使用它们。

请注意，在RenderScript中，尽管您没有明确创建它们，您的代码可能会在单独的线程中运行。 RenderScript运行时将经常将多个线程中的一个内核的执行拆分。 更新全局变量应该用原子函数完成。 如果可能，修改您的算法以避免它们完全相同。

函数rsAtomicAdd线程安全添加rsAtomicAnd线程安全按位和rsAtomicCas线程安全比较和设置rsAtomicDec线程安全递减rsAtomicInc线程安全增量rsAtomicMax线程安全最大值rsAtomicMin线程安全最小rsAtomicOr线程安全按位或rsAtomicSub线程安全减法rsAtomicXor线程安全按位排序或

十、时间函数和类型

以下功能可用于说明当前时钟时间和当前系统正常运行时间。 不建议在内核中调用这些函数。

类型rs_time_t自1970.1.1以来的秒数rs_tm日期和时间结构

函数rsGetDt自上次电话以来的经过时间rsLocaltime转换到当地时间rsTime自1970.1.1以来的秒数rsUptimeMillis系统正常运行时间（以毫秒为单位）rsUptimeNanos系统正常运行时间，以纳秒为单位

十一、分配数据访问功能

以下函数可用于获取和设置构成分配的单元格。

1、使用rs GetElementAt *和SetTlement函数访问各个单元格。

2、可以使用rsAllocationCopy *和rsAllocationV *函数复制多个单元格。

3、要通过采样器获取值，请使用rsSample。

rsGetElementAt和rsSetElement *函数有点不明确。 他们没有获取或设置元素，类似于数据类型; 他们得到或设置单元格。 将它们视为rsGetCellAt和rsSetCellAt。

函数rsAllocationCopy1DRange在分配之间复制连续的单元格rsAllocationCopy2DRange在分配之间复制单元格的矩形区域rsAllocationVLoadX从标量分配中获取向量rsAllocationVStoreX将向量存储到标量的分配中rsGetElementAt从分配中返回一个单元格rsGetElementAtYuv_uchar_U获取分配YUV的U分量rsGetElementAtYuv_uchar_V获取分配YUV的V分量rsGetElementAtYuv_uchar_Y获取Y分配的Y分量rsSample从纹理分配中抽取一个值rsSetElementAt设置一个分配单元格

十二、对象特征功能

以下功能可用于查询分配，元素或采样器对象的特性。 这些对象是从Java创建的。 您无法从脚本创建它们。

1、分配

分配是用于向RenderScript内核传递数据的主要方法。

它们是可用于存储位图，纹理，任意数据点等的单元格的结构化集合。

单元格的这个集合可能具有许多维度（X，Y，Z，Array0，Array1，Array2，Array3），面（用于立方体）和细节级别（用于mipmap）。

有关创建分配的详细信息，请参阅android.renderscript.Allocation。

2、元素

术语“元素”在RenderScript中有点模糊，作为分配单元格的类型信息和该类型的实例化。 例如：

 1）、rs_element是类型规范的句柄，

 2）、在诸如rsGetElementAt（）的函数中，“元素”表示类型的实例化，即分配的单元格。

以下函数可以查询类型规格的特征。

元素可以指定C中所发现的简单数据类型，例如。 一个整数，float或boolean。 它还可以指定一个RenderScript对象的句柄。 有关基本类型的列表，请参阅rs_data_type。

元素可以指定基本类型的固定大小向量（大小为2,3或4）版本。 元素可以组合成复杂的元素，创建相当于C结构定义。

元素也可以有一种，这是用于解释像素数据的语义信息。 见rs_data_kind。

当创建公共元素的分配时，您可以简单地使用许多预定义元素之一，如F32_2。

要创建复杂的元素，请使用Element.Builder Java类。

3、取样

采样器对象定义如何将内存中的结构读取为分配。 参见android.renderscript.S。

函数rsAllocationGetDimFacesPresence of more than one facersAllocationGetDimLODPresence of levels of detail（存在细节级别）rsAllocationGetDimXX维度的尺寸rsAllocationGetDimYY维度的尺寸rsAllocationGetDimZZ维度的尺寸rsAllocationGetElement获取描述分配单元格的对象rsClearObject释放一个对象rsElementGetBytesSize元素的大小rsElementGetDataKind元素的种类rsElementGetDataType元素的数据类型rsElementGetSubElement复杂元素的子元素rsElementGetSubElementArraySize复数元素的子元素的数组大小rsElementGetSubElementCount子元素数量rsElementGetSubElementName子元素的名称rsElementGetSubElementNameLength子元素名称的长度rsElementGetSubElementOffsetBytes实例子元素的偏移量rsElementGetVectorSize元素的矢量大小rsIsObject检查一个空的句柄rsSamplerGetAnisotropy取样器的各向异性rsSamplerGetMagnification取样器放大值rsSamplerGetMinification取样器最小化值rsSamplerGetWrapS采样器包裹S值rsSamplerGetWrapT采样器包裹T值

十三、内核调用函数和类型

rsForEach（）函数可用于调用脚本的根内核。

其他功能用于获取执行内核调用的特性，如维度和当前索引。 这些函数以rs_kernel_context为参数。

类型rs_for_each_strategy_t建议单元格处理顺序rs_kernel_context处理内核调用上下文rs_script_call_t单元格迭代信息

函数rsForEach调用脚本的根内核rsGetArray0指定内核上下文的Array0维度中的索引rsGetArray1指定内核上下文的Array1维度中的索引rsGetArray2指定内核上下文的Array2维度中的索引rsGetArray3指定内核上下文的Array3维度中的索引rsGetDimArray0指定内核上下文的Array0维的大小rsGetDimArray1指定内核上下文的Array1维的大小rsGetDimArray2指定内核上下文的Array2维度的大小rsGetDimArray3指定内核上下文的Array3维度的大小rsGetDimHasFaces针对指定的内核上下文存在多个面rsGetDimLod指定内核上下文的详细级别数rsGetDimX指定内核上下文的X维的大小rsGetDimY指定内核上下文的Y维的大小rsGetDimZ指定内核上下文的Z维的大小rsGetFace面向指定内核上下文的坐标rsGetLod指定内核上下文的“细节级别”维度中的索引

十四、输入/输出功能

这些功能用于：

1、发送信息到Java客户端，和

2、发送处理后的分配或接收下一个分配进行处理。

函数rsAllocationIoReceive从队列中接收新内容rsAllocationIoSend发送新的内容到队列rsSendToClient向客户端发送消息，不堵塞rsSendToClientBlocking发送消息给客户端，阻塞

十五、调试功能

以下功能旨在在应用程序开发过程中使用。 它们不应用于运输应用程序。

函数rsDebug记录消息和值

十六、图形功能和类型

RenderScript的图形子系统在API级别23被删除。