XR_KHR_extended_struct_name_lengths

Stringa del nome

XR_KHR_extended_struct_name_lengths

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

149

Revisione

2

Stato di ratifica

Ratificato

Dipendenze di estensione e versione

OpenXR 1.0

Data dell'ultima modifica

2025-12-04

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

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

Panoramica

Questa estensione estende le dimensioni massime dei nomi delle struct e fornisce una nuova funzione per accedere a questi nuovi nomi estesi.

xrStructureTypeToString2KHR viene fornita per consentire il recupero dei nomi delle stringhe degli enumeranti del tipo di struttura con lunghezze che superano il limite originale di 63 byte (64 byte incluso il terminatore null). xrStructureTypeToString2KHR restituisce stringhe di nomi per gli enumeranti del tipo di struttura fino a 255 byte di lunghezza (256 byte incluso il terminatore null). Un'applicazione può utilizzare xrStructureTypeToString2KHR come sostituzione diretta di xrStructureTypeToString , poiché funziona con tutti gli enumeranti del tipo di struttura, indipendentemente dalla lunghezza del nome della stringa.

Recupero delle stringhe degli enumeranti del tipo di struttura

Se l'xrStructureTypeToString originale viene utilizzato per recuperare i nomi delle stringhe per gli enumeranti del tipo di struttura con lunghezze dei nomi superiori a 63 byte, il suo comportamento viene chiarito come segue. xrStructureTypeToString deve popolare il buffer con il nome corretto, tranne per il fatto che la stringa deve essere troncata al limite di un punto di codice per rientrare nel buffer disponibile. Ovvero, la stringa restituita deve essere sempre UTF-8 valida.

La funzione xrStructureTypeToString2KHR è definita come segue:

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

Descrizioni dei parametri

  • instance è l'handle dell'istanza a cui chiedere la stringa.
  • value è il valore XrStructureType da trasformare in una stringa.
  • buffer è il buffer che verrà utilizzato per restituire la stringa.

Restituisce il nome del valore XrStructureType fornito copiando una stringa UTF-8 valida con terminazione null in buffer .

In tutti i casi, la stringa restituita deve essere una delle seguenti:

Valori di output della stringa del tipo di struttura

  • La stringa letterale definita per il valore numerico fornito nella specifica principale o nell'estensione. (ad es. il valore di XR_TYPE_INSTANCE_CREATE_INFO genera la stringa XR_TYPE_INSTANCE_CREATE_INFO )
  • XR_UNKNOWN_STRUCTURE_TYPE_ concatenato con il numero del tipo di struttura espresso come numero decimale.

Per gli enumeranti del tipo di struttura i cui nomi rientrano nel limite di dimensione originale di 63 byte, xrStructureTypeToString2KHR deve restituire la stessa stringa risultante di xrStructureTypeToString , fino al terminatore null.

Utilizzo valido (implicito)

  • L'estensione XR_KHR_extended_struct_name_lengths deve essere abilitata prima di chiamare xrStructureTypeToString2KHR
  • instance deve essere un handle XrInstance valido
  • value deve essere un valore XrStructureType valido
  • buffer deve essere un array di caratteri di lunghezza XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Codici restituiti

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_VALIDATION_FAILURE

L'enumerante XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR definisce la dimensione del buffer passato a xrStructureTypeToString2KHR .

#define XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 256

Nuovi comandi

Nuove costanti enum

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Cronologia delle versioni

  • Revisione 1, 29/02/2024 (Matthew Langille)

    • Descrizione iniziale dell'estensione

  • Revisione 2, 04/12/2025 (Kenny Vercaemer)

    • Correggi la specifica della lunghezza del nome della struttura