Extensão OpenXR XR_ANDROID_light_estimation

String de nome

XR_ANDROID_light_estimation

Tipo de extensão

Extensão da instância

Número de ramal 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

Não há reivindicações de IP conhecidas.

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 da cena em que são colocados.

Inspecionar a capacidade do sistema

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

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

Descrições de membros

  • 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 OpenXR principal ou nesta extensão.
  • supportsLightEstimation é um XrBool32 que indica se o sistema atual é compatível com a estimativa de iluminação.

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

Se o sistema não for capaz de oferecer suporte à estimativa de iluminação, ele vai retornar XR_FALSE para supportsLightEstimation e XR_ERROR_FEATURE_UNSUPPORTED de xrCreateLightEstimatorANDROID.

Uso válido (implícito)

Criar um handle do estimador de luz

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

O identificador XrLightEstimatorANDROID representa um estimador de luz. Esse identificador pode ser usado para acessar informações de estimativa de luz 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 for compatível com a estimativa de iluminação.
  • xrCreateLightEstimatorANDROID vai retornar XR_ERROR_PERMISSION_INSUFFICIENT se as permissões necessárias não tiverem sido concedidas ao aplicativo de chamada.

O identificador do estimador de luz retornado pode ser usado posteriormente em chamadas de API. Se um aplicativo quiser indicar ao tempo de execução que terminou de acessar dados de estimativa de iluminação, 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 de membros

  • 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 OpenXR principal 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)

Concorrência segura

  • 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 iluminação

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 iluminação. 

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

Descrições de membros

  • 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 as rotações de harmônicos esféricos e cubemap são expressas.
  • time é o XrTime que descreve o momento em que o aplicativo quer consultar a estimativa de iluminação.

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 de membros

Para receber informações de estimativa de luz para o cubemap 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 cubo de mapa 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 de membros

  • 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 cubemap. Como é HDR, os valores de ponto flutuante podem ser maiores que 1,0.
  • cubemapLeftImage é um float* que representa o buffer R32G32B32_SFLOAT do lado esquerdo do cubemap. Como é HDR, os valores de ponto flutuante podem ser maiores que 1,0.
  • cubemapTopImage é um float* que representa o buffer R32G32B32_SFLOAT da parte superior do cubemap. Como é HDR, os valores de ponto flutuante podem ser maiores que 1,0.
  • cubemapBottomImage é um float* que representa o buffer R32G32B32_SFLOAT da parte de baixo do cubemap. Como é HDR, os valores de ponto flutuante podem ser maiores que 1,0.
  • cubemapFrontImage é um float* que representa o buffer R32G32B32_SFLOAT da parte da frente do cubemap. Como é HDR, os valores de ponto flutuante podem ser maiores que 1,0.
  • resolution é um uint32_t que representa a largura e a altura da imagem de cada lado do cubo.
  • rotation é um XrQuaternionf que representa a rotação do cubemap.
  • centerExposureTime é um XrTime que representa o momento em que o cubo foi capturado. Útil para interpolação entre cubemaps.

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 XrLightEstimateStateANDROID válido
  • 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 de membros

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 de membros

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 de membros

Uso válido (implícito)

A enumeração XrSphericalHarmonicsKindANDROID identifica para o tempo de execução qual 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 enums têm os seguintes significados:

Enum

Descrição

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Os coeficientes harmônicos esféricos representam a função de radiância da luz do ambiente, incluindo 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, excluindo a contribuição da luz principal.

A enumeração XrLightEstimateStateANDROID identifica para o tempo de execução qual 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 enums têm os seguintes significados:

Enum

Descrição

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

A estimativa de iluminação é válida

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

A estimativa de iluminação é inválida

Exemplo de código para estimativa de iluminação

O exemplo de código a seguir demonstra como extrair todas as quantidades possíveis de estimativa de luz do tempo 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 objetos

  • XrLightEstimator

A enumeração XrObjectType é estendida com:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

A enumeração XrStructureType é estendida 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 enums

Novas estruturas

Novas funções

Problemas

Histórico de versões

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

OpenXR™ e o logotipo OpenXR são marcas registradas de propriedade da Khronos Group Inc. e estão registradas como marcas comerciais na China, na União Europeia, no Japão e no Reino Unido.