XR_KHR_extended_struct_name_lengths

名稱字串

XR_KHR_extended_struct_name_lengths

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

149

修訂版本

2

批准狀態

批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2025-12-04

IP 狀態

沒有已知的智慧財產權聲明。

著作人

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

總覽

這項擴充功能會擴充結構體名稱大小上限，並提供新函式來存取這些新擴充名稱。

xrStructureTypeToString2KHR 可用於擷取結構型別列舉值的字串名稱，長度超過原始限制 63 個位元組 (包括空值終止符為 64 個位元組)。xrStructureTypeToString2KHR 會傳回結構型別列舉值的名稱字串，長度最多為 255 個位元組 (包括空值終止符為 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 是用來傳回字串的緩衝區。

將有效的空值終止 UTF-8 字串複製到 buffer 中，即可傳回所提供 XrStructureType 值的名稱。

在所有情況下，傳回的字串必須是下列其中一個值：

結構類型字串輸出值

  • 在核心規格或擴充功能中，為提供的數值定義的常值字串。(例如，XR_TYPE_INSTANCE_CREATE_INFO 的值會產生字串「XR_TYPE_INSTANCE_CREATE_INFO」)
  • XR_UNKNOWN_STRUCTURE_TYPE_，並以十進位數字表示結構類型編號。

如果結構體類型列舉值的名稱符合 63 個位元組的原始大小限制，則 xrStructureTypeToString2KHR 必須傳回與 xrStructureTypeToString 相同的結果字串，直到空值終止符為止。

有效使用 (隱含)

  • 呼叫 xrStructureTypeToString2KHR 前，XR_KHR_extended_struct_name_lengths 擴充功能必須啟用
  • 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-02-29 (Matthew Langille)

    • 擴充功能初始說明

  • 修訂版本 2，2025-12-04 (Kenny Vercaemer)

    • 修正住家結構體名稱長度規格