XR_ANDROID_light_estimation

String de nome

XR_ANDROID_light_estimation

Tipo de extensão

Extensão de instância

Número da extensão registrada

701

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

2025-03-13

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. O aplicativo pode usar essas informações para iluminar objetos virtuais nas mesmas condições da cena do mundo real em que eles estão inseridos.

Permissões

Os aplicativos Android precisam ter a permissão android.permission.SCENE_UNDERSTANDING_COARSE listada no manifesto, já que essa extensão expõe informações de iluminação sobre o ambiente. A permissão android.permission.SCENE_UNDERSTANDING_COARSE é considerada perigosa. O aplicativo precisa solicitar a permissão no momento da execução para usar estas funções:

(nível de proteção: perigoso)

Inspecionar a capacidade do sistema

A estrutura XrSystemLightEstimationPropertiesANDROID é definida da seguinte maneira:

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 à estimativa de iluminação estendendo o XrSystemProperties com a estrutura XrSystemLightEstimationPropertiesANDROID ao chamar xrGetSystemProperties .

Se e somente se um tempo de execução retornar XR_FALSE para supportsLightEstimation , o tempo de execução deverá retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateLightEstimatorANDROID .

Uso válido (implícito)

Criar um handle do estimador de luz

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Os dados de estimativa de iluminação são gerados pelo tempo de execução e compartilhados com o aplicativo usando o identificador XrLightEstimatorANDROID.

Esse identificador pode ser usado para acessar informações de estimativa de iluminação 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 usa a função xrCreateLightEstimatorANDROID para criar um estimador de luz.

  • O tempo de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED se o sistema não for compatível com a estimativa de iluminação.
  • O tempo de execução precisa retornar XR_ERROR_PERMISSION_INSUFFICIENT se as permissões necessárias não tiverem sido concedidas ao app que fez a chamada.

Se um aplicativo quiser indicar ao tempo de execução que terminou de acessar os 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_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

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

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const 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 é definida como:

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descrições dos parâmetros

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

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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrLightEstimateGetInfoANDROID é definida como:

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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 e os harmônicos esféricos retornados são expressos.
  • 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 cada struct de estimativa de iluminação, se o state for XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID, todos os outros campos na struct serão arbitrários, ou seja, os valores deles não serão definidos.

Para receber informações de estimativa de iluminação sobre luz ambiente, harmônicos esféricos e a luz direcional principal, os aplicativos podem encadear instâncias das seguintes estruturas, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID, respectivamente, para 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 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 incluem XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID .
  • state é o XrLightEstimateStateANDROID que representa o estado da estimativa de luz.
  • intensity é um XrVector3f que representa a intensidade da luz ambiente. Cada componente do vetor corresponde aos canais vermelho, verde e azul, respectivamente.

  • colorCorrection é um XrVector3f com valores no espaço gama. Se a renderização for no espaço de cores gama, multiplique-os por componentes em relação à cor final calculada após a renderização. Se a renderização for no espaço linear, primeiro converta os valores para o espaço linear elevando à potência 2, 2 e multiplique por componentes em relação à cor final calculada após a renderização.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. As estruturas válidas incluem XrAmbientLightANDROID e XrDirectionalLightANDROID .
  • state é o XrLightEstimateStateANDROID que representa o estado da estimativa de luz.
  • kind é o XrSphericalHarmonicsKindANDROID solicitado pelo aplicativo.
  • coefficients é uma matriz bidimensional float 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.

Os coefficients são usados em uma função especial que recebe uma direção como entrada e gera a cor da luz que vem dessa direção. Confira mais detalhes neste artigo .

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,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

Os valores de enumeração têm os seguintes significados:

Descrição da enumeraçã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 do ambiente, incluindo a contribuição da luz principal.

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 XrLightEstimateStateANDROID indica o estado da estimativa de luz retornada pelo ambiente de execução.

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

Os valores de enumeração têm os seguintes significados:

Descrição da enumeraçã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 iluminação do tempo de execução.

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

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

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

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de enumeração

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • Extensão de XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Extensão de XrStructureType :

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

Problemas

Histórico de versões

  • Revisão 1, 16/09/2024 (Cairn Overturf)

    • Descrição inicial da extensão