XR_ANDROID_global_passthrough_dimming

String de nome

XR_ANDROID_global_passthrough_dimming

Tipo de extensão

Extensão de instância

Número de ramal registrado

797

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2026-03-10

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

Brian Chen, Google
Kyle Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Visão geral

Com a introdução de dispositivos ópticos transparentes, é importante não apenas permitir que os aplicativos ajustem a escuridão do passthrough para oferecer a melhor combinação com o contexto do app ao usuário, mas também permitir que o sistema clareie o passthrough por motivos de segurança.

Essa extensão oferece duas funções para que os apps definam e recebam o nível de escurecimento atual, além de um evento para transmitir quando o nível de escurecimento mudar.

Inspecionar a capacidade do sistema

A estrutura XrSystemGlobalDimmingPropertiesANDROID é definida como:

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • supportsGlobalDimming é um XrBool32 que indica se o sistema atual é compatível com o escurecimento global.

Um aplicativo pode verificar se o sistema oferece suporte ao escurecimento global encadeando uma estrutura XrSystemGlobalDimmingPropertiesANDROID ao XrSystemProperties ao chamar xrGetSystemProperties .

Se o ambiente de execução retornar XR_FALSE para supportsGlobalDimming , ele precisará retornar XR_ERROR_FEATURE_UNSUPPORTED quando xrGetGlobalDimmingLevelANDROID for chamado.

Uso válido (implícito)

Enumerar os níveis de escurecimento global compatíveis

A estrutura xrEnumerateSupportedGlobalDimmingLevelsANDROID é definida como:

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

Descrições dos membros

  • instance é a instância de onde systemId foi recuperado.
  • systemId é o XrSystemId com os níveis compatíveis que serão enumerados.
  • supportedGlobalDimmingLevelCapacityInput é a capacidade da matriz supportedGlobalDimmingLevels ou 0 para indicar uma solicitação de recuperação da capacidade necessária.
  • supportedGlobalDimmingLevelCountOutput é um ponteiro para a contagem de supportedGlobalDimmingLevels gravados ou um ponteiro para a capacidade necessária caso supportedGlobalDimmingLevelCapacityInput seja insuficiente.
  • supportedGlobalDimmingLevels é um ponteiro para uma matriz de níveis compatíveis, mas pode ser NULL se supportedGlobalDimmingLevelCapacityInput for 0.

Se o supportedGlobalDimmingLevelCountOutput retornado for 0, todos os níveis de escurecimento global entre 0,0 e 1,0 serão aceitos.

xrEnumerateSupportedGlobalDimmingLevelsANDROID enumera os níveis de escurecimento global aceitos pelo XrSystemId . Os níveis com suporte não podem mudar durante o ciclo de vida da XrInstance . A lista de níveis retornada precisa ser classificada em ordem crescente.

Os ambientes de execução precisam sempre retornar conteúdos de buffer idênticos dessa enumeração para o systemId fornecido e durante a vida útil do instance .

Uso válido (implícito)

  • A extensão XR_ANDROID_global_passthrough_dimming precisa ser ativada antes de chamar xrEnumerateSupportedGlobalDimmingLevelsANDROID.
  • instance precisa ser um identificador XrInstance válido
  • supportedGlobalDimmingLevelCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se supportedGlobalDimmingLevelCapacityInput não for 0 , supportedGlobalDimmingLevels precisa ser um ponteiro para uma matriz de valores supportedGlobalDimmingLevelCapacityInput float

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_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Configurar o nível de escurecimento global

A estrutura XrGlobalDimmingFrameEndInfoANDROID é definida como:

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

Descrições dos parâmetros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • globalDimmingLevel é um valor entre 0,0 (transparente) e 1,0 (opaco). O ambiente de execução pode mapear esse valor para o nível de escurecimento global mais próximo com suporte. O aplicativo pode definir esse valor como -1,0 para indicar que o nível de escurecimento atual é o preferido.

O valor globalDimmingLevel especifica a porcentagem de luz bloqueada, em que 0,0 corresponde a 0% de bloqueio de luz e 1,0 corresponde a 100% de bloqueio de luz. A porcentagem de luz bloqueada pode ser representada em geral como:

100% - Light Transmittance%

A porcentagem de transmissão de luz, de acordo com a ISO 8980-3:2022 , pode ser medida como a proporção entre o fluxo radiante transmitido e o fluxo radiante incidente em comprimentos de onda de luz visível (380 nm a 780 nm).

O XrGlobalDimmingFrameEndInfoANDROID é uma estrutura que um aplicativo pode encadear em XrFrameEndInfo para solicitar um nível de escurecimento global preferencial.

O ambiente de execução precisa respeitar o nível de escurecimento solicitado se ele for diferente do atual.

O ambiente de execução terá controle do nível de escurecimento global e poderá desconsiderar o nível preferencial por motivos de segurança.

Uso válido (implícito)

A função xrGetGlobalDimmingLevelANDROID é definida como:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Descrições dos parâmetros

  • session é um identificador XrSession válido.
  • dimmingLevel é um ponteiro para o nível de escurecimento atual.

O dimmingLevel retornado precisa estar entre 0,0 e 1,0, em que 0,0 significa totalmente transparente e 1,0 significa totalmente escurecido.

Se o nível de escurecimento não tiver sido definido, o ambiente de execução precisará definir o nível de escurecimento como 0,0 quando o modo de passagem estiver ativado e 1,0 quando estiver desativado.

Uso válido (implícito)

  • A extensão XR_ANDROID_global_passthrough_dimming precisa ser ativada antes de chamar xrGetGlobalDimmingLevelANDROID.
  • session precisa ser um identificador XrSession válido
  • dimmingLevel precisa ser um ponteiro para um valor float

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Evento de mudança no nível de escurecimento

A estrutura XrEventDataGlobalDimmingLevelChangedANDROID é definida como:

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • session é um identificador XrSession válido.

O aplicativo pode recuperar esse evento usando xrPollEvent . Esse evento será enviado quando o nível de escurecimento for alterado por apps ou botões físicos nos dispositivos.

Esse evento não será enviado quando o app em foco mudar para outro.

O aplicativo precisa responder ao evento chamando xrGetGlobalDimmingLevelANDROID para receber o novo nível de escurecimento e atualizar XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel de acordo. Responder ao evento garante que o ambiente de execução será sinalizado quando o aplicativo mudar o nível de escurecimento preferencial.

Uso válido (implícito)

Exemplo de código

Verificar a capacidade do sistema e enumerar os níveis de escurecimento global compatíveis

O exemplo de código a seguir demonstra como verificar se o escurecimento global é compatível.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

Evento de mudança no nível de escurecimento da pesquisa

O exemplo de código a seguir demonstra como consultar o evento de mudança do nível de escurecimento.

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

Novos comandos

Novas estruturas

Novas constantes de tipo enumerado

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • Estendendo XrStructureType :

    • XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
    • XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
    • XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

Problemas

Histórico de versões

  • Revisão 1, 07/10/2025 (Brian Chen)

    • Descrição inicial da extensão.