XR_KHR_extended_struct_name_lengths

Name String

XR_KHR_extended_struct_name_lengths

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

149

リビジョン

2

Ratification Status（批准ステータス）

批准

拡張機能とバージョンの依存関係

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 バイト）の構造体型列挙子の名前文字列を返します。アプリケーションは、文字列名の長さに関係なく、すべての構造体型列挙子で動作するため、xrStructureTypeToString のドロップイン代替として xrStructureTypeToString2KHR を使用できます。

構造体型の列挙文字列の取得

元の 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_ と、10 進数で表される構造体型の番号が連結されます。

名前が元のサイズ制限の 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）

    • 構造名の長さの指定を修正