RenderScript 对象特征函数

概览

以下函数可用于查询 Allocation、Element 或 Sampler 对象的特性。这些对象是通过 Java 创建的。而无法通过脚本创建。

分配:

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

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

该单元格集合可能具有多个维度(X、Y、Z、Array0、Array1、Array2、Array3)、面(对于立方体贴图)和细节级别(对于 mipmapping)。

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

元素:

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

  • rs_element 是类型规范的句柄,
  • rsGetElementAt() 等函数中,“元素”表示类型的实例化,即 Allocation 的单元格。

您可以利用以下函数查询类型规范的特性。

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

元素可以指定基本类型的固定大小矢量(大小为 2、3 或 4)。您可以将元素归为一组复杂的 Element,从而创建等效的 C 结构定义。

元素还可以有一个种类,这是用于解释像素数据的语义信息。请参阅 rs_data_Kind

创建公共元素的 Allocation 时,只需使用众多预定义 Element 中的一个,如 F32_2

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

采样器:

采样器对象定义了如何将 Allocation 作为内核中的结构进行读取。请参阅 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);
返回
Allocation 的 Y 维度。

返回 Allocation 的 Y 维度的大小。如果 Allocation 的维度少于 2 个,则返回 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 单元格的类型、种类和其他特性的 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 中引入

返回此 Element 的实例化将占用的大小(以字节为单位)。

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

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

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

rsElementGetSubElement :复杂元素的子元素

rs_element rsElementGetSubElement(rs_element e, uint32_t index); API 级别 16 中引入
参数
e要查询的元素。
index要返回的子元素的索引。
返回
指定索引处的子元素。

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

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

rsElementGetSubElementArraySize :复杂元素的子元素的数组大小

uint32_t rsElementGetSubElementArraySize(rs_element e, uint32_t index); API 级别 16 中引入
参数
e要查询的元素。
index子元素的索引。
返回
子元素的数组大小。

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

rsElementGetSubElementCount :子元素的数量

uint32_t rsElementGetSubElementCount(rs_element e); API 级别 16 中引入
参数
e要从其中获取数据的元素。
返回
子元素的数量。

元素可以很简单(如 int 或 float),也可以包含多个子元素。对于简单元素,此函数返回零;对于复杂元素,此函数返回子元素的数量。

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 index); 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 :采样器封装 S 值

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

获取采样器的封装 S 值。

请参阅 android.renderscript.S

rsSamplerGetWrapT :采样器封装 T 值

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

获取采样器的封装 T 值。

请参阅 android.renderscript.S