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

2025-01-17

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

Salar Khan, Google

Scott Chung, 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 e a rotação do cubemap 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 o cubo de iluminação do ambiente, luz ambiente, harmônicos esféricos e a luz direcional primária, os aplicativos podem encadear instâncias das seguintes estruturas: XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID, respectivamente, em XrLightEstimateANDROID::next.

Uso válido (implícito)

A estrutura XrEnvironmentLightingCubemapANDROID contém dados de estimativa de luz em um formato de cubomap sobre a iluminação do ambiente da cena. 

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

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, XrAmbientLightANDROID e XrDirectionalLightANDROID.
  • state é o XrLightEstimateStateANDROID que representa o estado da estimativa de luz.
  • cubemapRightImage é um float* que representa o buffer R32G32B32_SFLOAT do lado direito do cubomap. Este é HDR, então os valores flutuantes podem ser maiores que 1,0.
  • cubemapLeftImage é um float* que representa o buffer R32G32B32_SFLOAT do lado esquerdo do mapa de cubos. Este é HDR, então os valores flutuantes podem ser maiores que 1,0.
  • cubemapTopImage é um float* que representa o buffer R32G32B32_SFLOAT do lado de cima do cubomap. Este é o HDR, então os valores flutuantes podem ser maiores que 1,0.
  • cubemapBottomImage é um float* que representa o buffer R32G32B32_SFLOAT do lado de baixo do cubomap. Este é HDR, então os valores flutuantes podem ser maiores que 1,0.
  • cubemapFrontImage é um float* que representa o buffer R32G32B32_SFLOAT da frente do cubomap. Este é HDR, então os valores flutuantes podem ser maiores que 1,0.
  • resolution é um uint32_t que representa a largura e a altura da imagem de cada lado do cubo. Como esse é um HDR, os valores flutuantes podem ser maiores que 1,0.
  • rotation é um XrQuaternionf que representa a rotação do mapa de cubos.
  • centerExposureTime é um XrTime que representa o momento em que o mapa de cubos foi capturado. Útil para interpolação entre mapas de cubo.

Uso válido (implícito)

  • A extensão XR_ANDROID_light_estimation precisa ser ativada antes de usar XrEnvironmentLightingCubemapANDROID.
  • type precisa ser XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
  • state precisa ser um valor válido de XrLightEstimateStateANDROID
  • cubemapRightImage precisa ser um ponteiro para um valor de ponto flutuante válido
  • cubemapLeftImage precisa ser um ponteiro para um valor de ponto flutuante válido
  • cubemapTopImage precisa ser um ponteiro para um valor de ponto flutuante válido
  • cubemapBottomImage precisa ser um ponteiro para um valor de ponto flutuante válido
  • cubemapFrontImage precisa ser um ponteiro para um valor de ponto flutuante válido
  • cubemapBackImage precisa ser um ponteiro para um valor de ponto flutuante válido

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

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

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 radiância 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 radiância da luz 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,
};


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

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

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight,
  // lightingCubemap, 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
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

Novos tipos enumerados

Novas estruturas

Novas funções

Problemas

Histórico de versões

  • Revisão 2, 2025-01-17 (Salar Khan)
    • Adição de suporte a cubemap de iluminação do ambiente
  • Revisão 1, 2024-09-16 (Cairn Overturf)
    • Descrição inicial da extensão