XR_KHR_extended_struct_name_lengths

名称字符串

XR_KHR_extended_struct_name_lengths

扩展程序类型

实例扩展程序

已注册的扩展程序编号

149

修订版本

2

批准状态

已批准

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2025-12-04

IP 状态

没有已知的 IP 权利主张。

创作贡献者

Matthew Langille，Meta Platforms
Andreas Selvik，Meta Platforms
Rylie Pavlik，Collabora, Ltd.

概览

此扩展程序扩展了结构体名称的最大大小，并提供了一个新函数来访问这些新的扩展名称。

xrStructureTypeToString2KHR 用于检索结构类型枚举数的字符串名称，这些名称的长度超过了原始限制 63 字节（包括 null 终止符为 64 字节）。xrStructureTypeToString2KHR 返回的结构类型枚举数的名称字符串长度上限为 255 字节（包括 null 终止符为 256 字节）。应用可以 使用 xrStructureTypeToString2KHR 作为 xrStructureTypeToString 的直接替代项，因为它适用于所有结构类型枚举数，无论字符串名称长度如何。

检索结构类型枚举数字符串

如果使用原始 xrStructureTypeToString 检索名称长度超过 63 字节的结构类型枚举数的字符串名称，则其行为说明如下。xrStructureTypeToString 必须 使用正确的名称填充缓冲区，但字符串必须 在代码点边界处截断，以适应可用缓冲区。也就是说，返回的字符串必须 始终是有效的 UTF-8。

xrStructureTypeToString2KHR 函数定义如下：

XrResult xrStructureTypeToString2KHR(
    XrInstance                                  instance,
    XrStructureType                             value,
    char                                        buffer[XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR]);

参数说明

  • instance 是要请求字符串的实例的句柄。
  • value 是要转换为字符串的 XrStructureType 值。
  • buffer 是将用于返回字符串的缓冲区。

通过将有效的以 null 终止的 UTF-8 字符串复制到 buffer 中，返回所提供的 XrStructureType 值的名称。

在所有情况下，返回的字符串必须 是以下其中一项：

结构类型字符串输出值

  • 在核心规范或扩展程序中为所提供的数值定义的字面量字符串。（例如，XR_TYPE_INSTANCE_CREATE_INFO 的值会生成字符串 XR_TYPE_INSTANCE_CREATE_INFO）
  • XR_UNKNOWN_STRUCTURE_TYPE_ 与以十进制数表示的结构类型编号连接。

对于名称符合原始大小限制 63 字节的结构类型枚举数，xrStructureTypeToString2KHR 必须 返回与 xrStructureTypeToString 相同的结果字符串，直至 null 终止符。

有效用法（隐式）

  • 必须先启用 XR_KHR_extended_struct_name_lengths 扩展程序，然后才能调用 xrStructureTypeToString2KHR
  • instance 必须 是有效的 XrInstance 句柄
  • value 必须 是有效的 XrStructureType 值
  • buffer 必须 是长度为 XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 的字符数组

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_VALIDATION_FAILURE

XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 枚举数定义了传递给 xrStructureTypeToString2KHR 的缓冲区的大小。

#define XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 256

新增命令

新枚举常量

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

版本历史记录

  • 修订版本 1，2024 年 2 月 29 日 (Matthew Langille)

    • 初始扩展程序说明

  • 修订版本 2，2025 年 12 月 4 日 (Kenny Vercaemer)

    • 修复结构名称长度规范