XR_KHR_extended_struct_name_lengths

Chaîne de nom

XR_KHR_extended_struct_name_lengths

Type d'extension

Extension d'instance

Numéro d'extension enregistré

149

Révision

2

État de ratification

Ratifié

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2025-12-04

État de la propriété intellectuelle

Aucune revendication de propriété intellectuelle connue.

Participants

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

Présentation

Cette extension augmente la taille maximale des noms de structure et fournit une nouvelle fonction pour accéder à ces nouveaux noms étendus.

xrStructureTypeToString2KHR permet de récupérer les noms de chaîne des énumérants de type de structure dont la longueur dépasse la limite d'origine de 63 octets (64 octets, y compris le terminateur nul). xrStructureTypeToString2KHR renvoie des chaînes de nom pour les énumérants de type de structure d'une longueur maximale de 255 octets (256 octets, y compris le terminateur nul). Une application peut utiliser xrStructureTypeToString2KHR comme remplacement direct de xrStructureTypeToString , car elle fonctionne avec tous les énumérants de type de structure, quelle que soit la longueur du nom de la chaîne.

Récupérer des chaînes d'énumérants de type de structure

Si la fonction xrStructureTypeToString d'origine est utilisée pour récupérer des noms de chaîne pour des énumérants de type de structure dont la longueur dépasse 63 octets, son comportement est clarifié comme suit. xrStructureTypeToString doit remplir la mémoire tampon avec le nom correct, sauf que la chaîne doit être tronquée à une limite de point de code pour s'adapter à la mémoire tampon disponible. Autrement dit, la chaîne renvoyée doit toujours être un encodage UTF-8 valide.

La fonction xrStructureTypeToString2KHR est définie comme suit :

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

Description des paramètres

  • instance est le descripteur de l'instance pour laquelle demander la chaîne.
  • value est la valeur XrStructureType à convertir en chaîne.
  • buffer est la mémoire tampon qui sera utilisée pour renvoyer la chaîne.

Renvoie le nom de la valeur XrStructureType fournie en copiant une chaîne UTF-8 valide terminée par un caractère nul dans buffer .

Dans tous les cas, la chaîne renvoyée doit être l'une des suivantes :

Valeurs de sortie de la chaîne de type de structure

  • La chaîne littérale définie pour la valeur numérique fournie dans la spécification ou l'extension principale. (Par exemple, la valeur de XR_TYPE_INSTANCE_CREATE_INFO génère la chaîne XR_TYPE_INSTANCE_CREATE_INFO.)
  • XR_UNKNOWN_STRUCTURE_TYPE_ concaténé avec le numéro de type de structure exprimé sous forme de nombre décimal.

Pour les énumérants de type de structure dont les noms respectent la limite de taille d'origine de 63 octets, xrStructureTypeToString2KHR doit renvoyer la même chaîne résultante que xrStructureTypeToString , jusqu'au terminateur nul.

Utilisation valide (implicite)

  • L'extension XR_KHR_extended_struct_name_lengths doit être activée avant d'appeler xrStructureTypeToString2KHR.
  • instance doit être un descripteur XrInstance valide.
  • value doit être une valeur XrStructureType valide.
  • buffer doit être un tableau de caractères de longueur XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_VALIDATION_FAILURE

L'énumérant XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR définit la taille de la mémoire tampon transmise à xrStructureTypeToString2KHR .

#define XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 256

Nouvelles commandes

Nouvelles constantes d'énumération

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

L'historique des versions

  • Révision 1, 29/02/2024 (Matthew Langille)

    • Description initiale de l'extension

  • Révision 2, 04/12/2025 (Kenny Vercaemer)

    • Corriger la spécification de la longueur du nom de la structure