RenderScript 对象特性函数

概览

以下函数可用于查询 Allocation、Element 或 Sampler 对象的特性。这些对象是从 Java 创建的。您无法从脚本中创建它们。

Allocations（分配）

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

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

此单元格集合可以具有许多维度（X、Y、Z、Array0、Array1、Array2、Array3）、面（用于立方体贴图）和细节级别（用于 mipmapping）。

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

Elements（元素）

在 RenderScript 中，“元素”这个术语有点含糊不清，既指 Allocation 单元格的类型信息，也指该类型的实例化。例如，

  • rs_element 是类型规范的句柄，而
  • 在 rsGetElementAt() 等函数中，“element”指类型的实例化，即 Allocation 的一个单元格。

以下函数允许您查询类型规范的特性。

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

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

元素还可以具有 kind，这是一种用于解释像素数据的语义信息。请参阅 rs_data_kind。

创建常见元素的 Allocation 时，您可以直接使用许多预定义元素之一，例如 F32_2。

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

Samplers（采样器）

Sampler 对象定义了 Allocation 如何在内核中被读取为结构。请参阅 android.renderscript.S。

摘要

函数
rsAllocationGetDimFaces 是否存在多个面
rsAllocationGetDimLOD 是否存在细节级别
rsAllocationGetDimX X 维度的大小
rsAllocationGetDimY Y 维度的大小
rsAllocationGetDimZ Z 维度的大小
rsAllocationGetElement 获取描述 Allocation 单元格的对象
rsClearObject 释放对象
rsElementGetBytesSize Element 的大小
rsElementGetDataKind Element 的 kind
rsElementGetDataType Element 的数据类型
rsElementGetSubElement 复杂元素的子元素
rsElementGetSubElementArraySize 复杂元素的子元素的数组大小
rsElementGetSubElementCount 子元素的数量
rsElementGetSubElementName 子元素的名称
rsElementGetSubElementNameLength 子元素名称的长度
rsElementGetSubElementOffsetBytes 实例化子元素的偏移量
rsElementGetVectorSize Element 的矢量大小
rsIsObject 检查空句柄
rsSamplerGetAnisotropy Sampler 的各向异性值
rsSamplerGetMagnification Sampler 放大值
rsSamplerGetMinification Sampler 缩小值
rsSamplerGetWrapS Sampler S 环绕值
rsSamplerGetWrapT Sampler 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。

查询 Allocation 是否存在多个细节级别。这对于 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 的维度少于两个，则返回 0。

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

rsAllocationGetDimZ : Z 维度的大小

uint32_t rsAllocationGetDimZ(rs_allocation a);
返回值
Allocation 的 Z 维度。

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

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

rsAllocationGetElement : 获取描述 Allocation 单元格的对象

rs_element rsAllocationGetElement(rs_allocation a);
参数
a要获取数据的 Allocation。
返回值
描述 Allocation 布局的 Element。

获取描述 Allocation 单元格的类型、kind 和其他特性的 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 : Element 的大小

uint32_t rsElementGetBytesSize(rs_element e); 添加于 API 级别 16

返回此 Element 实例化时占用的字节大小。

rsElementGetDataKind : Element 的 kind

rs_data_kind rsElementGetDataKind(rs_element e); 添加于 API 级别 16

返回 Element 的数据 kind。这用于解释像素数据。

请参阅 rs_data_kind。

rsElementGetDataType : Element 的数据类型

rs_data_type rsElementGetDataType(rs_element e); 添加于 API 级别 16

返回 Element 的基本数据类型。这可以是类似于 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* 函数探索此复杂 Element。

rsElementGetSubElement : 复杂元素的子元素

rs_element rsElementGetSubElement(rs_element e, uint32_t index); 添加于 API 级别 16
参数
e要查询的 Element。
index要返回的子元素的索引。
返回值
给定索引处的子元素。

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

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

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

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

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

rsElementGetSubElementCount : 子元素的数量

uint32_t rsElementGetSubElementCount(rs_element e); 添加于 API 级别 16
参数
e要获取数据的 Element。
返回值
子元素的数量。

元素可以是简单的，例如 int 或 float，也可以是具有多个子元素的结构。此函数对于简单元素返回零，对于复杂元素返回子元素的数量。

rsElementGetSubElementName : 子元素的名称

uint32_t rsElementGetSubElementName(rs_element e, uint32_t index, char* name, uint32_t nameLength); 添加于 API 级别 16
参数
e要获取数据的 Element。
index子元素的索引。
name用于存储名称的数组地址。
nameLength提供的名称数组的长度。
返回值
复制的字符数，不包括 null 终止符。

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

rsElementGetSubElementNameLength : 子元素名称的长度

uint32_t rsElementGetSubElementNameLength(rs_element e, uint32_t index); 添加于 API 级别 16
参数
e要获取数据的 Element。
index子元素的索引。
返回值
子元素名称的长度，包括 null 终止符。

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

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

uint32_t rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index); 添加于 API 级别 16
参数
e要获取数据的 Element。
index子元素的索引。
返回值
字节偏移量。

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

例如，如果 Element 描述一个 32 位浮点数后跟一个 32 位整数，则第一个返回的偏移量将是 0，第二个返回的偏移量将是 4。

rsElementGetVectorSize : Element 的矢量大小

uint32_t rsElementGetVectorSize(rs_element e); 添加于 API 级别 16
参数
e要获取数据的 Element。
返回值
元素矢量的长度。

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

rsGetAllocation : 返回给定指针的 Allocation

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() 返回的 Element，或查看是否已在句柄上调用了 rsClearObject()。

rsSamplerGetAnisotropy : Sampler 的各向异性值

float rsSamplerGetAnisotropy(rs_sampler s); 添加于 API 级别 16

获取 Sampler 的各向异性值。

请参阅 android.renderscript.S。

rsSamplerGetMagnification : Sampler 放大值

rs_sampler_value rsSamplerGetMagnification(rs_sampler s); 添加于 API 级别 16

获取 Sampler 的放大值。

请参阅 android.renderscript.S。

rsSamplerGetMinification : Sampler 缩小值

rs_sampler_value rsSamplerGetMinification(rs_sampler s); 添加于 API 级别 16

获取 Sampler 的缩小值。

请参阅 android.renderscript.S。

rsSamplerGetWrapS : Sampler S 环绕值

rs_sampler_value rsSamplerGetWrapS(rs_sampler s); 添加于 API 级别 16

获取 Sampler 的 S 环绕值。

请参阅 android.renderscript.S。

rsSamplerGetWrapT : Sampler T 环绕值

rs_sampler_value rsSamplerGetWrapT(rs_sampler s); 添加于 API 级别 16

获取 Sampler 的 T 环绕值。

请参阅 android.renderscript.S。