Android NDK开发详解RenderScript之RenderScript 对象特征函数

概览

以下函数可用于查询 Allocation、Element 或 Sampler 对象的特性。这些对象是通过 Java 创建的。但不能通过脚本创建它们。

分配：
分配是用于将数据传递到 RenderScript 内核以及从 RenderScript 内核传递数据的主要方法。

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

这个单元格集合可能具有许多维度（X、Y、Z、Array0、Array1、Array2、Array3）、面（如果是立方体贴图）和细节级别（如果是 mipmap）。

如需详细了解如何创建 Allocation，请参阅 android.renderscript.Allocation。

元素：
“元素”这一术语在 RenderScript 中有些不明确，既用作 Allocation 单元格的类型信息，又是该类型的实例化。例如：

rs_element 是类型规范的句柄，而
在 rsGetElementAt() 等函数中，“元素”表示类型的（即 Allocation 的单元格）的实例化。
通过以下函数，您可以查询类型特异的特征。

元素可以指定 C 中的简单数据类型，例如整数、浮点数或布尔值。它还可以指定 RenderScript 对象的句柄。如需查看基本类型的列表，请参阅 rs_data_type。

元素可以指定基本类型的固定大小矢量（大小为 2、3 或 4）。元素可以组合成复杂的元素，创建等效的 C 结构定义。

元素还可以有一个类型，该类型是用于解读像素数据的语义信息。请参阅 rs_data_Kind。

创建常见元素的 Allocation 时，只需使用诸多预定义 Element 中的一个，如 F32_2。

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

采样器：
采样器对象定义了如何将分配作为内核中的结构进行读取。请参阅 android.renderscript.S。

摘要

函数
rsAllocationGetDimFaces 出现多张面孔
rsAllocationGetDimLOD 呈现出细节级别
rsAllocationGetDimX X 维度的尺寸
rsAllocationGetDimY Y 维度的尺寸
rsAllocationGetDimZ Z 维度的尺寸
rsAllocationGetElement 获取描述 Allocation 的单元的对象
rsClearObject 释放对象
rsElementGetBytesSize 元素大小
rsElementGetDataKind 元素种类
rsElementGetDataType 元素的数据类型
rsElementGetSubElement 复杂元素的子元素
rsElementGetSubElementArraySize 复杂元素中子元素的数组大小
rsElementGetSubElementCount 子元素的数量
rsElementGetSubElementName 子元素的名称
rsElementGetSubElementNameLength 子元素名称的长度
rsElementGetSubElementOffsetBytes 实例化的子元素的偏移量
rsElementGetVectorSize 元素的矢量大小
rsIsObject 检查标识名是否为空
rsSamplerGetAnisotropy 采样器的各向异性
rsSamplerGetMagnification 采样器放大值
rsSamplerGetMinification 采样器缩减值
rsSamplerGetWrapS 采样器封装 S 值
rsSamplerGetWrapT 采样器封装 T 值
已弃用的函数
rsGetAllocation 已弃用。返回指定指针的 Allocation

函数

rsAllocationGetDimFaces ：出现多张面孔
uint32_t rsAllocationGetDimFaces(rs_allocation a);

返回
如果存在多个人脸，则返回 1，否则返回 0。

如果 Allocation 为立方体贴图，且有多个面，则此函数会返回 1。在所有其他情况下，返回 0。

使用 rsGetDimHasFaces() 可获取当前正在运行的内核的维度。

rsAllocationGetDimLOD ：显示详细程度信息
uint32_t rsAllocationGetDimLOD(rs_allocation a);

返回
如果存在多个 LOD，则返回 1，否则返回 0。

针对存在多个详情级别的情况查询分配。这对于 mipmap 非常有用。

使用 rsGetDimLod() 可获取当前正在运行的内核的维度。

rsAllocationGetDimX ：X 维度的大小
uint32_t rsAllocationGetDimX(rs_allocation a);

返回
Allocation 的 X 维度。

返回 Allocation 的 X 维度的大小。

使用 rsGetDimX() 可获取当前正在运行的内核的维度。

rsAllocationGetDimY ：Y 维度的大小
uint32_t rsAllocationGetDimY(rs_allocation a);

返回
分配对应的 Y 维度。

返回 Allocation 的 Y 维度的大小。如果 Allocation 的维度少于两个，则返回 0。

使用 rsGetDimY() 可获取当前正在运行的内核的维度。

rsAllocationGetDimZ ：Z 维度的大小
uint32_t rsAllocationGetDimZ(rs_allocation a);

返回
Allocation 的 Z 维度。

返回 Allocation 的 Z 维度的大小。如果 Allocation 的维度少于 3 个，则返回 0。

使用 rsGetDimZ() 获取当前正在运行的内核的维度。

rsAllocationGetElement ：获取用于描述 Allocation 的单元的对象
rs_element rsAllocationGetElement(rs_allocation a);

参数
一个	要从其中获取数据的分配。
返回
描述 Allocation 布局的元素。

获取描述 Allocation 单元格的类型、种类和其他特性的 Element 对象。请参阅下面的 rsElement* 函数。

rsClearObject ：释放对象
void rsClearObject(rs_allocation* dst);
void rsClearObject(rs_element* dst);
void rsClearObject(rs_font* dst); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
void rsClearObject(rs_mesh* dst); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
void rsClearObject(rs_program_fragment* dst); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
void rsClearObject(rs_program_raster* dst); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
void rsClearObject(rs_program_store* dst); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
void rsClearObject(rs_program_vertex* dst); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
void rsClearObject(rs_sampler* dst);
void rsClearObject(rs_script* dst);
void rsClearObject(rs_type* dst);
告知运行时此句柄将不再用于访问相关对象。如果这是该对象的最后一个句柄，则可能会恢复资源。

调用此函数后，*dst 将设置为空句柄。请参阅 rsIsObject()。

rsElementGetBytesSize ：元素的大小

uint32_t rsElementGetBytesSize(rs_element e);	在 API 级别 16 中引入

返回此元素的实例化将占用的大小（以字节为单位）。

rsElementGetDataKind ：元素的种类
rs_data_Kind rsElementGetDataKind(rs_element e); 在 API 级别 16 中引入
返回元素的数据类型。此属性用于解读像素数据。

请参阅 rs_data_Kind。

rsElementGetDataType ：元素的数据类型

rs_data_type rsElementGetDataType(rs_element e);	在 API 级别 16 中引入

返回元素的基本数据类型。可以是类似于 C/C++ 的类型（例如 RS_TYPE_UNSIGNED_8）、句柄（例如 RS_TYPE_ALLOCATION 和 RS_TYPE_ELEMENT），也可以是更复杂的数值类型（例如 RS_TYPE_UNSIGNED_5_6_5 和 RS_TYPE_MATRIX_4X4）。 请参阅 rs_data_type。

如果元素描述的是向量，则此函数会返回其中某个项的数据类型。 使用 rsElementGetVectorSize 获取矢量的大小。

如果元素描述的是结构，则返回 RS_TYPE_NONE。使用 rsElementGetSub* 函数探索这个复杂的元素。

rsElementGetSubElement ：复杂元素的子元素

rs_element rsElementGetSubElement(rs_element e, uint32_t 索引);	在 API 级别 16 中引入
参数

e	要查询的元素。
index	要返回的子元素的索引。
返回
指定索引处的子元素。

对于表示结构的 Element，此函数会返回指定索引处的子元素。

如果元素不是结构或者索引大于或等于子元素的数量，则返回无效句柄。

rsElementGetSubElementArraySize ：复杂 Element 的子元素的数组大小

uint32_t rsElementGetSubElementArraySize(rs_element e, uint32_t index);	在 API 级别 16 中引入

参数
e	要查询的元素。
index	子元素的索引。
返回
子元素的数组大小。

对于复杂元素，子元素可以是静态大小的数组。此函数返回索引处子元素的数组大小。这种子元素的重复方式不同于固定大小的向量。

rsElementGetSubElementCount ：子元素的数量

uint32_t rsElementGetSubElementCount(rs_element e);	在 API 级别 16 中引入

参数
e	用于从中获取数据的元素。
返回
子元素的数量。

元素可以是简单的元素（如整数或浮点数），也可以是具有多个子元素的结构。对于简单元素，此函数返回 0；对于复杂元素，此函数返回子元素的数量。

rsElementGetSubElementName ：子元素的名称

uint32_t rsElementGetSubElementName(rs_element e, uint32_t index, char* name, uint32_t nameLength);	在 API 级别 16 中引入

参数
e	用于从中获取数据的元素。
index	子元素的索引。
name	将名称存储到的数组的地址。
名称长度	提供的名称数组的长度。
返回
已复制的字符数（不包括 null 终止符）。

对于复杂元素，此函数会返回指定索引处的子元素的名称。

rsElementGetSubElementNameLength ：子元素的名称长度

uint32_t rsElementGetSubElementNameLength(rs_element e, uint32_t 索引);	在 API 级别 16 中引入

参数
e	用于从中获取数据的元素。
index	子元素的索引。
返回
子元素名称的长度（包括 null 终止符）。

对于复杂元素，此函数会返回指定索引处子元素的名称的长度。

rsElementGetSubElementOffsetBytes ：实例化的子元素的偏移量

uint32_t rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index);	在 API 级别 16 中引入

参数
e	用于从中获取数据的元素。
index	子元素的索引。
返回
偏移量（以字节为单位）。

此函数返回指定子元素在 Element 实例化中的相对位置。

例如，如果元素描述一个 32 位浮点数，后跟一个 32 位整数，则第一个的偏移返回值为 0，第二个的值为 4。

rsElementGetVectorSize ：元素的矢量大小
uint32_t rsElementGetVectorSize(rs_element e); 在 API 级别 16 中引入

参数
e	用于从中获取数据的元素。
返回
元素矢量的长度。

返回元素的矢量大小。如果 Element 不表示矢量，则返回 1。

rsGetAllocation ：返回指定指针的分配

rs_allocation rsGetAllocation(const void* p);	
已弃用。此函数已废弃，并将在未来的 SDK 版本中移除。

返回指定指针的 Allocation。指针应指向有效的分配范围。如果指针并非来自有效的 Allocation，则结果未定义。

rsIsObject ：检查是否为空句柄
bool rsIsObject(rs_allocation v);
bool rsIsObject(rs_element v);
bool rsIsObject(rs_font v); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
bool rsIsObject(rs_mesh v); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
bool rsIsObject(rs_program_fragment v); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
bool rsIsObject(rs_program_raster v); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
bool rsIsObject(rs_program_store v); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
bool rsIsObject(rs_program_vertex v); 针对 32 位进行编译时。从 API 级别 23 及更高级别中移除
bool rsIsObject(rs_sampler v);
bool rsIsObject(rs_script v);
bool rsIsObject(rs_type v);
如果该句柄包含非 null 引用，则返回 true。

此函数不会验证句柄中使用的内部指针是否指向实际的有效对象；它只检查是否存在 null。

此函数可用于检查 rsElementGetSubElement() 返回的元素，或查看是否已对句柄调用 rsClearObject()。

rsSamplerGetAnisotropy ：采样器的各向异性

float rsSamplerGetAnisotropy(rs_sampler s);	在 API 级别 16 中引入

获取采样器的各向异性。

请参阅 android.renderscript.S。

rsSamplerGetMagnification ：采样器放大率值

rs_sampler_value rsSamplerGetMagnification(rs_sampler s);	在 API 级别 16 中引入

获取采样器的放大率值。

请参阅 android.renderscript.S。

rsSamplerGetMinification ：采样器缩减值

rs_sampler_value rsSamplerGetMinification(rs_sampler s);	在 API 级别 16 中引入

获取采样器的缩减值。

请参阅 android.renderscript.S。

rsSamplerGetWrapS ：Sampler wrap S 值

rs_sampler_value rsSamplerGetWrapS(rs_sampler s);	在 API 级别 16 中引入

获取采样器的封装 S 值。

请参阅 android.renderscript.S。

rsSamplerGetWrapT ：Sampler wrap T 值

rs_sampler_value rsSamplerGetWrapT(rs_sampler s);	在 API 级别 16 中引入

获取采样器的封装 T 值。

请参阅 android.renderscript.S。

本页面上的内容和代码示例受内容许可部分所述许可的限制。Java 和 OpenJDK 是 Oracle 和/或其关联公司的注册商标。

最后更新时间 (UTC)：2023-10-18。