XR_KHR_extended_struct_name_lengths

String do nome

XR_KHR_extended_struct_name_lengths

Tipo de extensão

Extensão de instância

Número de extensão registrada

149

Revisão

2

Status de ratificação

Ratificado

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2025-12-04

Status de IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

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

Visão geral

Essa extensão aumenta os tamanhos máximos de nomes de struct e fornece uma nova função para acessar esses novos nomes estendidos.

xrStructureTypeToString2KHR é fornecido para permitir a recuperação dos nomes de string de enumeradores de tipo de estrutura com comprimentos que excedem o limite original de 63 bytes (64 bytes, incluindo o terminador nulo). xrStructureTypeToString2KHR retorna strings de nome para enumeradores de tipo de estrutura de até 255 bytes de comprimento (256 bytes, incluindo o terminador nulo). Um aplicativo pode usar xrStructureTypeToString2KHR como um substituto direto para xrStructureTypeToString , porque ele funciona com todos os enumeradores de tipo de estrutura, independentemente do comprimento do nome da string.

Como recuperar strings de enumeradores de tipo de estrutura

Se o xrStructureTypeToString original for usado para recuperar nomes de string para enumeradores de tipo de estrutura com comprimentos de nome superiores a 63 bytes, o comportamento será esclarecido da seguinte maneira. xrStructureTypeToString precisa preencher o buffer com o nome correto, exceto que a string precisa ser truncada em um limite de ponto de código para caber no buffer disponível. Ou seja, a string retornada precisa ser sempre UTF-8 válida.

A função xrStructureTypeToString2KHR é definida como:

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

Descrições dos parâmetros

  • instance é o identificador da instância para solicitar a string.
  • value é o valor de XrStructureType a ser transformado em uma string.
  • buffer é o buffer que será usado para retornar a string.

Retorna o nome do valor XrStructureType fornecido copiando uma string UTF-8 válida terminada em nulo para buffer .

Em todos os casos, a string retornada precisa ser uma das seguintes:

Valores de saída de string de tipo de estrutura

  • A string literal definida para o valor numérico fornecido na especificação ou extensão principal. Por exemplo, o valor de XR_TYPE_INSTANCE_CREATE_INFO resulta na string XR_TYPE_INSTANCE_CREATE_INFO.
  • XR_UNKNOWN_STRUCTURE_TYPE_ concatenado com o número do tipo de estrutura expresso como um número decimal.

Para enumeradores de tipo de estrutura cujos nomes se ajustam ao limite de tamanho original de 63 bytes, xrStructureTypeToString2KHR precisa retornar a mesma string resultante que xrStructureTypeToString , até o terminador nulo.

Uso válido (implícito)

  • A extensão XR_KHR_extended_struct_name_lengths precisa ser ativada antes de chamar xrStructureTypeToString2KHR.
  • instance precisa ser um identificador XrInstance válido.
  • value precisa ser um valor XrStructureType válido.
  • buffer precisa ser uma matriz de caracteres de comprimento XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_VALIDATION_FAILURE

O enumerador XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR define o tamanho do buffer transmitido para xrStructureTypeToString2KHR .

#define XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 256

Novos comandos

Novas constantes de tipo enumerado

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

Histórico de versões

  • Revisão 1, 29/02/2024 (Matthew Langille)

    • Descrição inicial da extensão

  • Revisão 2, 04/12/2025 (Kenny Vercaemer)

    • Corrigir a especificação do comprimento do nome da estrutura