XR_KHR_extended_struct_name_lengths

Nazwa ciągu znaków

XR_KHR_extended_struct_name_lengths

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer rozszerzenia

149

Wersja

2

Stan ratyfikacji

Zatwierdzone

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2025-12-04

Stan IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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

Przegląd

To rozszerzenie zwiększa maksymalne rozmiary nazw struktur i udostępnia nową funkcję umożliwiającą dostęp do tych nowych rozszerzonych nazw.

Funkcja xrStructureTypeToString2KHR umożliwia pobieranie nazw ciągów znaków elementów wyliczeniowych typu struktury o długościach przekraczających pierwotny limit 63 bajtów (64 bajty z uwzględnieniem znaku końca ciągu). Funkcja xrStructureTypeToString2KHR zwraca nazwy ciągów znaków dla elementów wyliczeniowych typu struktury o długości do 255 bajtów (256 bajtów z uwzględnieniem znaku końca ciągu). Aplikacja może używać funkcji xrStructureTypeToString2KHR jako zamiennika funkcji xrStructureTypeToString , ponieważ działa ona ze wszystkimi elementami wyliczeniowymi typu struktury niezależnie od długości nazwy ciągu znaków.

Pobieranie ciągów znaków elementów wyliczeniowych typu struktury

Jeśli do pobierania nazw ciągów znaków elementów wyliczeniowych typu struktury o długości nazwy przekraczającej 63 bajty używana jest oryginalna funkcja xrStructureTypeToString, jej działanie jest wyjaśnione w ten sposób. Funkcja xrStructureTypeToString musi wypełnić bufor prawidłową nazwą, z tym że ciąg znaków musi zostać obcięty na granicy punktu kodowego, aby zmieścić się w dostępnym buforze. Oznacza to, że zwracany ciąg znaków musi być zawsze prawidłowym ciągiem znaków UTF-8.

Funkcja xrStructureTypeToString2KHR jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • instance to uchwyt instancji, o której ciąg znaków ma zostać poproszony.
  • value to wartość XrStructureType, która ma zostać przekształcona w ciąg znaków.
  • buffer to bufor, w którym zostanie zwrócony ciąg znaków.

Zwraca nazwę podanej wartości XrStructureType, kopiując prawidłowy ciąg znaków UTF-8 zakończony znakiem końca ciągu do parametru buffer .

We wszystkich przypadkach zwracany ciąg znaków musi być jednym z tych ciągów:

Wartości wyjściowe ciągu znaków typu struktury

  • Literał zdefiniowany dla podanej wartości liczbowej w specyfikacji podstawowej lub rozszerzeniu. (np. wartość XR_TYPE_INSTANCE_CREATE_INFO powoduje zwrócenie ciągu znaków XR_TYPE_INSTANCE_CREATE_INFO )
  • XR_UNKNOWN_STRUCTURE_TYPE_ połączony z numerem typu struktury wyrażonym jako liczba dziesiętna.

W przypadku elementów wyliczeniowych typu struktury, których nazwy mieszczą się w pierwotnym limicie rozmiaru 63 bajtów, xrStructureTypeToString2KHR musi zwracać ten sam ciąg znaków co xrStructureTypeToString , aż do znaku końca ciągu.

Prawidłowe użycie (niejawne)

  • Przed wywołaniem funkcji xrStructureTypeToString2KHR musi być włączone rozszerzenie XR_KHR_extended_struct_name_lengths.
  • instance musi być prawidłowym uchwytem XrInstance.
  • value musi być prawidłową wartością XrStructureType.
  • buffer musi być tablicą znaków o długości XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Kody powrotu

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_VALIDATION_FAILURE

Element wyliczeniowy XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR określa rozmiar bufora przekazywanego do funkcji xrStructureTypeToString2KHR .

#define XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 256

Nowe polecenia

Nowe stałe wyliczeniowe

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Historia wersji

  • Wersja 1, 29 lutego 2024 r. (Matthew Langille)

    • Początkowy opis rozszerzenia

  • Wersja 2, 4 grudnia 2025 r. (Kenny Vercaemer)

    • Poprawka specyfikacji długości nazwy struktury