XR_KHR_extended_struct_name_lengths

Name String

XR_KHR_extended_struct_name_lengths

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

149

Revision

2

Ratifizierungsstatus

Ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

OpenXR 1.0

Datum der letzten Änderung

2025-12-04

IP-Status

Keine bekannten IP-Ansprüche.

Mitwirkende

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

Übersicht

Diese Erweiterung erhöht die maximale Größe von Strukturbezeichnungen und bietet eine neue Funktion für den Zugriff auf diese neuen, längeren Bezeichnungen.

xrStructureTypeToString2KHR ermöglicht das Abrufen der Stringbezeichnungen von Strukturtyp-Enumeranten mit einer Länge, die das ursprüngliche Limit von 63 Byte (64 Byte einschließlich des Null-Terminators) überschreitet. xrStructureTypeToString2KHR gibt Namensstrings für Strukturtyp-Enumeranten mit einer Länge von bis zu 255 Byte (256 Byte einschließlich des Null-Terminators) zurück. Eine Anwendung kann xrStructureTypeToString2KHR als direkten Ersatz für xrStructureTypeToString verwenden , da es mit allen Strukturtyp-Enumeranten funktioniert, unabhängig von der Länge des Stringnamens.

Strings für Strukturtyp-Enumeranten abrufen

Wenn das ursprüngliche xrStructureTypeToString verwendet wird, um Stringbezeichnungen für Strukturtyp-Enumeranten mit einer Länge von mehr als 63 Byte abzurufen, wird das Verhalten wie folgt erläutert. xrStructureTypeToString muss den Puffer mit dem korrekten Namen füllen, wobei der String jedoch an einer Codepoint-Grenze abgeschnitten werden muss , damit er in den verfügbaren Puffer passt. Das heißt, der zurückgegebene String muss immer gültiges UTF-8 sein.

Die Funktion xrStructureTypeToString2KHR ist wie folgt definiert:

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

Parameterbeschreibungen

  • instance ist das Handle der Instanz, für die der String angefordert wird.
  • value ist der XrStructureType-Wert, der in einen String umgewandelt werden soll.
  • buffer ist der Puffer, der zum Zurückgeben des Strings verwendet wird.

Gibt den Namen des angegebenen XrStructureType-Werts zurück, indem ein gültiger, mit Null beendeter UTF-8-String in buffer kopiert wird .

In allen Fällen muss der zurückgegebene String einer der folgenden sein:

String-Ausgabewerte für Strukturtypen

  • Der Literalstring, der für den angegebenen numerischen Wert in der Kernspezifikation oder Erweiterung definiert ist. Beispiel: Der Wert von XR_TYPE_INSTANCE_CREATE_INFO führt zum String XR_TYPE_INSTANCE_CREATE_INFO.
  • XR_UNKNOWN_STRUCTURE_TYPE_ verkettet mit der Strukturtypnummer als Dezimalzahl.

Für Strukturtyp-Enumeranten, deren Namen innerhalb des ursprünglichen Größenlimits von 63 Byte liegen, xrStructureTypeToString2KHR muss denselben resultierenden String wie xrStructureTypeToString zurückgeben, bis zum Null-Terminator.

Gültige Verwendung (implizit)

  • Die XR_KHR_extended_struct_name_lengths Erweiterung muss aktiviert sein, bevor xrStructureTypeToString2KHR aufgerufen wird.
  • instance muss ein gültiges XrInstance-Handle sein.
  • value muss ein gültiger XrStructureType-Wert sein
  • buffer muss ein Zeichenarray der Länge XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR sein.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_VALIDATION_FAILURE

Die XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR Enumerante definiert die Größe des Puffers, der an xrStructureTypeToString2KHR übergeben wird .

#define XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 256

Neue Befehle

Neue Enum-Konstanten

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Versionsverlauf

  • Revision 1, 29.02.2024 (Matthew Langille)

    • Erste Beschreibung der Erweiterung

  • Revision 2, 04.12.2025 (Kenny Vercaemer)

    • Spezifikation der Länge des Strukturbezeichnungsnamens korrigieren