XR_KHR_extended_struct_name_lengths

Cadena de nombre

XR_KHR_extended_struct_name_lengths

Tipo de extensión

Extensión de instancia

Número de extensión registrada

149

Revisión

2

Estado de ratificación

Ratificado

Dependencias de extensión y versión

OpenXR 1.0

Fecha de última modificación

2025-12-04

Estado de IP

No se conocen reclamos de IP.

Colaboradores

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

Descripción general

Esta extensión amplía los tamaños máximos de nombres de struct y proporciona una nueva función para acceder a estos nombres extendidos nuevos.

xrStructureTypeToString2KHR se proporciona para permitir la recuperación de los nombres de cadena de los enumeradores de tipo de estructura con longitudes que superan el límite original de 63 bytes (64 bytes, incluido el terminador nulo). xrStructureTypeToString2KHR muestra cadenas de nombres para enumeradores de tipo de estructura de hasta 255 bytes de longitud (256 bytes, incluido el terminador nulo). Una aplicación puede usar xrStructureTypeToString2KHR como reemplazo directo de xrStructureTypeToString , ya que funciona con todos los enumeradores de tipo de estructura, independientemente de la longitud del nombre de la cadena.

Cómo recuperar cadenas de enumeradores de tipo de estructura

Si se usa el xrStructureTypeToString original para recuperar nombres de cadena para enumeradores de tipo de estructura con longitudes de nombre superiores a 63 bytes, su comportamiento se aclara de la siguiente manera. xrStructureTypeToString debe propagar el búfer con el nombre correcto, excepto que la cadena debe truncarse en un límite de punto de código para ajustarse al búfer disponible. Es decir, la cadena que se muestra siempre debe ser UTF-8 válida.

La función xrStructureTypeToString2KHR se define de la siguiente manera:

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

Descripciones de parámetros

  • instance es el controlador de la instancia para solicitar la cadena.
  • value es el valor de XrStructureType que se convertirá en una cadena.
  • buffer es el búfer que se usará para mostrar la cadena.

Copia una cadena UTF-8 válida terminada en nulo en buffer y muestra el nombre del valor de XrStructureType proporcionado .

En todos los casos, la cadena que se muestra debe ser una de las siguientes:

Valores de salida de cadena de tipo de estructura

  • La cadena literal definida para el valor numérico proporcionado en la especificación o extensión principal (p.ej., el valor de XR_TYPE_INSTANCE_CREATE_INFO da como resultado la cadena XR_TYPE_INSTANCE_CREATE_INFO)
  • XR_UNKNOWN_STRUCTURE_TYPE_ concatenado con el número de tipo de estructura expresado como un número decimal

Para los enumeradores de tipo de estructura cuyos nombres se ajustan al límite de tamaño original de 63 bytes, xrStructureTypeToString2KHR debe mostrar la misma cadena resultante que xrStructureTypeToString , hasta el terminador nulo.

Uso válido (implícito)

  • La extensión XR_KHR_extended_struct_name_lengths debe habilitarse antes de llamar a xrStructureTypeToString2KHR.
  • instance debe ser un controlador XrInstance válido.
  • value debe ser un valor XrStructureType válido.
  • buffer debe ser un array de caracteres de longitud XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_VALIDATION_FAILURE

El enumerador XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR define el tamaño del búfer que se pasa a xrStructureTypeToString2KHR .

#define XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 256

Comandos nuevos

Nuevas constantes de enum

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Historial de versiones

  • Revisión 1, 29 de febrero de 2024 (Matthew Langille)

    • Descripción inicial de la extensión

  • Revisión 2, 4 de diciembre de 2025 (Kenny Vercaemer)

    • Corrige la especificación de longitud del nombre de la estructura