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
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
é umXrBool32
, 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)
- A extensão XR_ANDROID_light_estimation precisa ser ativada antes de usar XrSystemLightEstimationPropertiesANDROID.
type
precisa serXR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID
next
precisa serNULL
ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.
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
session
é a XrSession que cria o estimador de luz.createInfo
é um ponteiro para uma estrutura XrLightEstimatorCreateInfoANDROID que contém parâmetros a serem usados para criar o estimador de luz.outHandle
é um ponteiro para um identificador em que o XrLightEstimatorANDROID criado é retornado.
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)
- A extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de chamar xrCreateLightEstimatorANDROID. session
precisa ser um identificador XrSession válidocreateInfo
precisa ser um ponteiro para uma estrutura XrLightEstimatorCreateInfoANDROID.outHandle
precisa ser um ponteiro para um identificador XrLightEstimatorANDROID.
Códigos de retorno
XR_SUCCESS
XR_SESSION_LOSS_PENDING
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 extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de usar XrLightEstimatorCreateInfoANDROID. type
precisa serXR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
next
precisa serNULL
ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.
A função xrDestroyLightEstimatorANDROID libera o estimator
e todos os
recursos subjacentes.
XrResult xrDestroyLightEstimatorANDROID(
XrLightEstimatorANDROID estimator);
Descrições dos parâmetros
estimator
é um XrLightEstimatorANDROID criado anteriormente por xrCreateLightEstimatorANDROID.
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de chamar xrDestroyLightEstimatorANDROID. estimator
precisa ser um identificador XrLightEstimatorANDROID válido.
Segurança da linha de execução
- O acesso a
estimator
e a qualquer identificador filho precisa ser sincronizado externamente.
Códigos de retorno
XR_SUCCESS
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
estimator
: identificador de um XrLightEstimatorANDROID criado anteriormente comxrCreateLightEstimatorANDROID
.input
: ponteiro para uma estrutura XrLightEstimateGetInfoANDROID.output
: ponteiro para uma estrutura XrLightEstimateANDROID.
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de chamar xrGetLightEstimateANDROID. estimator
precisa ser um identificador XrLightEstimatorANDROID válido.input
precisa ser um ponteiro para uma estrutura XrLightEstimateGetInfoANDROID válida.output
precisa ser um ponteiro para uma estrutura XrLightEstimateANDROID
Códigos de retorno
XR_SUCCESS
XR_SESSION_LOSS_PENDING
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
é oXrTime
que descreve o horário em que o aplicativo quer consultar a estimativa de luz.
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de usar XrLightEstimateGetInfoANDROID. type
precisa serXR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
next
precisa serNULL
ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.space
precisa ser um identificador XrSpace válido.
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
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, XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID.state
é o XrLightEstimateStateANDROID que representa o estado da estimativa de luz.lastUpdatedTime
é oXrTime
que representa quando a estimativa foi calculada pela última vez.
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 extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de usar XrLightEstimateANDROID. type
precisa serXR_TYPE_LIGHT_ESTIMATE_ANDROID
next
precisa serNULL
ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas. Consulte também: XrAmbientLightANDROID, XrDirectionalLightANDROID e XrSphericalHarmonicsANDROID.state
precisa ser um valor válido de XrLightEstimateStateANDROID
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
é umXrVector3
que representa a intensidade da luz ambiente. Cada componente do vetor corresponde aos canais vermelho, verde e azul.colorCorrection
é umXrVector3
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 extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de usar XrAmbientLightANDROID. type
precisa serXR_TYPE_AMBIENT_LIGHT_ANDROID
next
precisa serNULL
ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.state
precisa ser um valor válido de XrLightEstimateStateANDROID
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 matrizfloat
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 extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de usar XrSphericalHarmonicsANDROID. type
precisa serXR_TYPE_SPHERICAL_HARMONICS_ANDROID
next
precisa serNULL
ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.state
precisa ser um valor válido de XrLightEstimateStateANDROIDkind
precisa ser um valor válido de XrSphericalHarmonicsKindANDROID
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
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, XrSphericalHarmonicsANDROID e XrDirectionalLightANDROID.state
é o XrLightEstimateStateANDROID que representa o estado da estimativa de luz.intensity
é umXrVector3
que representa a intensidade da luz direcional. Cada componente do vetor corresponde aos canais vermelho, verde e azul.direction
é umXrVector3
que representa a direção da luz.
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation
precisa ser ativada antes de usar XrDirectionalLightANDROID. type
precisa serXR_TYPE_DIRECTIONAL_LIGHT_ANDROID
next
precisa serNULL
ou um ponteiro válido para a próxima estrutura em uma cadeia de estrutura.state
precisa ser um valor válido de XrLightEstimateStateANDROID
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 |
|
Os coeficientes harmônicos esféricos representam a função de brilho da luz ambiente, excluindo a contribuição da luz principal. |
|
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 |
|
A estimativa de luz é válida |
|
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
- XrLightEstimatorCreateInfoANDROID
- XrLightEstimateGetInfoANDROID
- XrLightEstimateANDROID
- XrDirectionalLightANDROID
- XrSphericalHarmonicsANDROID
- XrAmbientLightANDROID
- XrSystemLightEstimationPropertiesANDROID
Novas funções
Problemas
Histórico de versões
- Revisão 1, 2024-09-16 (Cairn Overturf)
- Descrição inicial da extensão