Extensão OpenXR XR_ANDROID_light_estimation

String de nome

XR_ANDROID_light_estimation

Tipo de extensão

Extensão de instância

Número de extensão registrado

701

Revisão

1

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2024-09-18

Status do IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Visão geral

Essa extensão permite que o aplicativo solicite dados que representam a iluminação do ambiente real ao redor do headset. Essas informações podem ser usadas ao renderizar objetos virtuais para iluminá-los nas mesmas condições que a cena em que eles estão colocados.

Inspecionar o capability do sistema

Um aplicativo pode inspecionar se o sistema oferece suporte à estimativa de luz encadeando uma estrutura XrSystemLightEstimationPropertiesANDROID ao XrSystemProperties ao chamar xrGetSystemProperties.

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.
  • supportsLightEstimation é um XrBool32, indicando se o sistema atual oferece suporte à estimativa de luz.

Um aplicativo pode inspecionar se o sistema é capaz de oferecer suporte à estimativa de luz estendendo o XrSystemProperties com a estrutura XrSystemLightEstimationPropertiesANDROID ao chamar xrGetSystemProperties.

Se o sistema não for compatível com a estimativa de luz, ele retornará XR_FALSE para supportsLightEstimation e XR_ERROR_FEATURE_UNSUPPORTED de xrCreateLightEstimatorANDROID.

Uso válido (implícito)

Criar um identificador de estimativa leve

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

O identificador XrLightEstimatorANDROID representa um estimador de luz. Esse gerenciador pode ser usado para acessar informações de estimativa leve usando outras funções nesta extensão.

A função xrCreateLightEstimatorANDROID é definida como:

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

Descrições dos parâmetros

O aplicativo pode usar a função xrCreateLightEstimatorANDROID para criar um estimador de luz.

  • xrCreateLightEstimatorANDROID vai retornar XR_ERROR_FEATURE_UNSUPPORTED se o sistema não oferecer suporte à estimativa de luz.
  • xrCreateLightEstimatorANDROID vai retornar XR_ERROR_PERMISSION_INSUFFICIENT se as permissões necessárias não tiverem sido concedidas ao aplicativo de chamada.

O identificador de estimador de luz retornado pode ser usado posteriormente em chamadas de API. Se um aplicativo quiser indicar ao ambiente de execução que ele terminou de acessar dados de estimativa de luz, ele precisa destruir o identificador usando xrDestroyLightEstimatorANDROID.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_LIMIT_REACHED

A estrutura XrLightEstimatorCreateInfoANDROID descreve as informações para criar um identificador XrLightEstimatorANDROID.

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrLightEstimatorCreateInfoANDROID;

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no núcleo do OpenXR ou nesta extensão.

Uso válido (implícito)

A função xrDestroyLightEstimatorANDROID libera o estimator e todos os recursos subjacentes.

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descrições dos parâmetros

Uso válido (implícito)

Segurança da linha de execução

  • O acesso a estimator e a qualquer identificador filho precisa ser sincronizado externamente.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Acessar dados de estimativa de luz

A função xrGetLightEstimateANDROID é definida como:

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

Descrições dos parâmetros

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_TIME_INVALID

Um XrLightEstimateGetInfoANDROID descreve as informações necessárias para receber dados de estimativa de luz.

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • space é o XrSpace que define o espaço de referência em que a direção da luz retornada e os harmônicos esféricos são expressos.
  • time é o XrTime que descreve o horário em que o aplicativo quer consultar a estimativa de luz.

Uso válido (implícito)

A estrutura XrLightEstimateANDROID contém dados de estimativa de luz.

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

Descrições dos participantes

Para receber informações de estimativa de luz para luz ambiente, harmônicos esféricos e a luz direcional principal, os aplicativos podem encadenar instâncias das seguintes estruturas: XrAmbientLightANDROID, XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID, respectivamente, em XrLightEstimateANDROID::next.

Uso válido (implícito)

A estrutura XrAmbientLightANDROID contém dados de estimativa de luz sobre a luz ambiente na cena.

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. As estruturas válidas são XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID.
  • state é o XrLightEstimateStateANDROID que representa o estado da estimativa de luz.
  • intensity é um XrVector3 que representa a intensidade da luz ambiente. Cada componente do vetor corresponde aos canais vermelho, verde e azul.
  • colorCorrection é um XrVector3 com valores no espaço gamma. Componente por multiplica a cor da renderização corrigida por gama com esses valores.

Uso válido (implícito)

A estrutura XrSphericalHarmonicsANDROID contém harmônicos esféricos que representam a iluminação da cena.

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

Descrições dos participantes

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. As estruturas válidas são XrAmbientLightANDROID e XrDirectionalLightANDROID.
  • state é o XrLightEstimateStateANDROID que representa o estado da estimativa de luz.
  • kind é o XrSphericalHarmonicsKindANDROID solicitado pelo aplicativo.
  • coefficients é uma matriz float bidimensional com dimensões de 9 linhas e 3 colunas. As três colunas correspondentes aos canais de cores vermelho, verde e azul, respectivamente. Cada canal tem nove coeficientes harmônicos esféricos.

Uso válido (implícito)

A estrutura XrDirectionalLightANDROID contém dados de estimativa de luz.

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

Descrições dos participantes

Uso válido (implícito)

A enumeração XrSphericalHarmonicsKindANDROID identifica ao ambiente de execução que tipo de harmônicos esféricos o aplicativo está solicitando.

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1
} XrSphericalHarmonicsKindANDROID;

Os tipos enumerados têm os seguintes significados:

Tipo enumerado

Descrição

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Os coeficientes harmônicos esféricos representam a função de brilho da luz ambiente, excluindo a contribuição da luz principal.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Os coeficientes harmônicos esféricos representam a função de intensidade de luz do ambiente, incluindo a contribuição da luz principal.

A enumeração XrLightEstimateStateANDROID identifica para o ambiente de execução que tipo de harmônicos esféricos o aplicativo está solicitando.

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1
} XrLightEstimateStateANDROID;

Os tipos enumerados têm os seguintes significados:

Tipo enumerado

Descrição

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

A estimativa de luz é válida

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

A estimativa de luz é inválida

Exemplo de código para estimativa de luz

O exemplo de código abaixo demonstra como receber todas as quantidades possíveis de estimativa de luz do ambiente do ambiente de execução.

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.

XrLightEstimatorANDROID estimator;
XrLightEstimatorCreateInfoANDROID createInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID};
CHK_XR(xrCreateLightEstimatorANDROID(session, &createInfo, &estimator));

// Every frame
XrTime updateTime;  // Time used for the current frame's simulation update.

XrLightEstimateGetInfoANDROID info = {
    .type = XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID,
    .space = appSpace,
    .time = updateTime,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
};

XrSphericalHarmonicsANDROID totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
    .next = &directionalLight,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
    .next = &totalSh,
};

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &ambientSh,
};

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &ambientLight,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight if each
  // struct has a valid state field
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

Novos tipos de objeto

  • XrLightEstimator

A enumeração XrObjectType é estendida com:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

A enumeração XrStructureType foi ampliada com:

  • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_ANDROID
  • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
  • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
  • XR_TYPE_AMBIENT_LIGHT_ANDROID

Novos tipos enumerados

Novas estruturas

Novas funções

Problemas

Histórico de versões

  • Revisão 1, 2024-09-16 (Cairn Overturf)
    • Descrição inicial da extensão