XR_ANDROID_light_estimation_cubemap
String de nome
XR_ANDROID_light_estimation_cubemap
Tipo de extensão
Extensão de instância
Número de ramal registrado
722
Revisão
1
Status de ratificação
Não ratificado
Dependências de extensão e versão
XR_ANDROID_light_estimation
Data da última modificação
06/08/2025
Status do IP
Nenhuma reivindicação de PI conhecida.
Colaboradores
Salar Khan, Google
Scott Chung, Google
Jared Finder, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Jürgen Sturm, Google
Visão geral
Essa extensão se baseia na extensão básica XR_ANDROID_light_estimation. Ele adiciona suporte para receber estimativas de iluminação de cubemap, que fornecem estimativas mais detalhadas sobre a iluminação no ambiente físico.
Observação
O mecanismo para receber os dados de estimativa de luz é o mesmo da extensão básica, mas o XrCubemapLightEstimatorCreateInfoANDROID precisa ser encadeado ao XrLightEstimatorCreateInfoANDROID ao criar o identificador do estimador de luz.
Inspecionar a capacidade do sistema
typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;
Descrições dos membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.supportsCubemapLightEstimationé umXrBool32que indica se o sistema atual é compatível com a estimativa de luz do cubemap.
Um aplicativo pode inspecionar se o sistema é capaz de oferecer suporte à estimativa de luz do mapa de cubo estendendo XrSystemProperties com a estrutura XrSystemCubemapLightEstimationPropertiesANDROID ao chamar xrGetSystemProperties .
Se o ambiente de execução retornar XR_FALSE para supportsCubemapLightEstimation e XrCubemapLightEstimatorCreateInfoANDROID tiver sido encadeado a XrLightEstimatorCreateInfoANDROID , o ambiente de execução precisará retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateLightEstimatorANDROID .
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation_cubemapprecisa ser ativada antes de usar XrSystemCubemapLightEstimationPropertiesANDROID. -
typeprecisa serXR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
Como receber resoluções de cubemap compatíveis
XrResult xrEnumerateCubemapLightingResolutionsANDROID(
XrInstance instance,
XrSystemId systemId,
uint32_t resolutionCapacityInput,
uint32_t* resolutionCountOutput,
uint32_t* resolutions);
Descrições dos parâmetros
instanceé uma XrInstance criada anteriormente.systemIdé oXrSystemIdrecuperado anteriormente por xrGetSystem para receber as resoluções de cubemap compatíveis.resolutionCapacityInputé umuint32_tque indica o número máximo de elementos que podem ser armazenados na matrizresolutions.resolutionCountOutputé um ponteiro para umuint32_tdefinido pelo ambiente de execução que indica o número de elementos gravados na matrizresolutionspelo ambiente de execução.resolutionsé uma matriz deuint32_tque é preenchida pelo ambiente de execução com as resoluções de cubemap compatíveis.
A resolução de um cubemap indica a largura e a altura de cada face dele em pixels. Idioma de duas chamadas: o aplicativo pode escolher uma das resoluções compatíveis em XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution ao criar o identificador do estimador de luz. O aplicativo precisa alocar a quantidade adequada de memória para os membros do buffer de imagem de XrCubemapLightingDataANDROID com base na resolução escolhida e no formato de cor.
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation_cubemapprecisa ser ativada antes de chamar xrEnumerateCubemapLightingResolutionsANDROID. -
instanceprecisa ser um identificador XrInstance válido -
resolutionCountOutputprecisa ser um ponteiro para um valoruint32_t - Se
resolutionCapacityInputnão for0,resolutionsprecisa ser um ponteiro para uma matriz de valoresresolutionCapacityInputuint32_t
Códigos de retorno
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
Como receber formatos de cor de cubemap compatíveis
A enumeração XrCubemapLightingColorFormatANDROID identifica para o ambiente de execução o formato de cor da iluminação do mapa de cubo a ser usado.
typedef enum XrCubemapLightingColorFormatANDROID {
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID = 1,
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID = 2,
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID = 3,
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrCubemapLightingColorFormatANDROID;
Os tipos enumerados têm os seguintes significados:
Descrição do tipo enumerado
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID
Um formato de cor com três canais em que cada canal é um valor de ponto flutuante de 32 bits.
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID
Um formato de cor com quatro canais em que cada canal é um valor de ponto flutuante de 32 bits.
XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID
Um formato de cor com quatro canais em que cada canal é um valor de ponto flutuante de 16 bits.
XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
XrInstance instance,
XrSystemId systemId,
uint32_t colorFormatCapacityInput,
uint32_t* colorFormatCountOutput,
XrCubemapLightingColorFormatANDROID* colorFormats);
Descrições dos parâmetros
instanceé uma XrInstance criada anteriormente.systemIdé oXrSystemIdrecuperado anteriormente por xrGetSystem para receber as resoluções de cubemap compatíveis.colorFormatCapacityInputé umuint32_tque indica o número máximo de elementos que podem ser armazenados na matrizcolorFormats.colorFormatCountOutputé um ponteiro para umuint32_tdefinido pelo ambiente de execução que indica o número de elementos gravados na matrizcolorFormatspelo ambiente de execução.colorFormatsé uma matriz de XrCubemapLightingColorFormatANDROID que é preenchida pelo ambiente de execução com os formatos de cor de cubemap compatíveis.
Idioma de duas chamadas: o aplicativo pode usar um dos formatos de cor compatíveis em XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat ao criar o identificador do estimador de luz. O aplicativo precisa alocar a quantidade adequada de memória para os membros do buffer de imagem de XrCubemapLightingDataANDROID com base no formato de cor escolhido.
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation_cubemapprecisa ser ativada antes de chamar xrEnumerateCubemapLightingColorFormatsANDROID. -
instanceprecisa ser um identificador XrInstance válido -
colorFormatCountOutputprecisa ser um ponteiro para um valoruint32_t - Se
colorFormatCapacityInputnão for0,colorFormatsprecisa ser um ponteiro para uma matriz de valorescolorFormatCapacityInputXrCubemapLightingColorFormatANDROID
Códigos de retorno
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
Criar um handle para o estimador de luz do mapa de cubo
typedef struct XrCubemapLightEstimatorCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t cubemapResolution;
XrCubemapLightingColorFormatANDROID colorFormat;
XrBool32 reproject;
} XrCubemapLightEstimatorCreateInfoANDROID;
Descrições dos membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas.cubemapResolutioné umuint32_tque indica a resolução da iluminação do mapa de cubo a ser usada.colorFormaté um XrCubemapLightingColorFormatANDROID que indica o formato de cor dos dados de iluminação do mapa de cubo a serem usados.reprojecté umXrBool32que indica se a iluminação do mapa de cubo precisa ser reprojetada para o espaço base do aplicativo.
A estrutura XrCubemapLightEstimatorCreateInfoANDROID descreve as informações para criar um identificador XrLightEstimatorANDROID capaz de fornecer estimativas de iluminação de cubemap. O membro cubemapResolution de XrCubemapLightEstimatorCreateInfoANDROID precisa ser definido como uma das resoluções retornadas por xrEnumerateCubemapLightingResolutionsANDROID . O membro colorFormat de XrCubemapLightEstimatorCreateInfoANDROID precisa ser definido como um dos formatos de cor retornados por xrEnumerateCubemapLightingColorFormatsANDROID . Se o aplicativo não definir a resolução como uma das resoluções compatíveis ou o formato de cor como um dos formatos de cor compatíveis, o ambiente de execução precisará retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateLightEstimatorANDROID .
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation_cubemapprecisa ser ativada antes de usar XrCubemapLightEstimatorCreateInfoANDROID. -
typeprecisa serXR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas -
colorFormatprecisa ser um valor XrCubemapLightingColorFormatANDROID válido
Estimativas de luz do mapa de cubo
typedef struct XrCubemapLightingDataANDROID {
XrStructureType type;
void* next;
XrLightEstimateStateANDROID state;
uint32_t imageBufferSize;
uint8_t* imageBufferRight;
uint8_t* imageBufferLeft;
uint8_t* imageBufferTop;
uint8_t* imageBufferBottom;
uint8_t* imageBufferFront;
uint8_t* imageBufferBack;
XrQuaternionf rotation;
XrTime centerExposureTime;
} XrCubemapLightingDataANDROID;
Descrições dos membros
typeé o XrStructureType dessa estrutura.nextéNULLou 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.imageBufferSizeé umuint32_tque indica o tamanho em bytes de cada buffer de imagem de face no cubemap.imageBufferRighté um bufferuint8_tque contém a imagem da face direita do cubemap.imageBufferLefté um bufferuint8_tque contém a imagem da face esquerda do mapa de cubo.imageBufferTopé um bufferuint8_tque contém a imagem da face superior do mapa de cubo.imageBufferBottomé um bufferuint8_tque contém a imagem da face inferior do mapa de cubo.imageBufferFronté um bufferuint8_tque contém a imagem da face frontal do mapa de cubo.imageBufferBacké um bufferuint8_tque contém a imagem da face traseira do mapa de cubo.rotationé um XrQuaternionf que indica a rotação do mapa de cubo.centerExposureTimeé umXrTimeque indica o horário em que o cubemap foi capturado.
Essa estrutura pode ser encadeada ao XrLightEstimateANDROID . O ambiente de execução precisa preencher essa estrutura em xrGetLightEstimateANDROID somente se XrCubemapLightEstimatorCreateInfoANDROID tiver sido usado para criar o identificador do estimador de luz. O aplicativo precisa alocar a quantidade adequada de memória para os buffers de imagem, que depende dos valores definidos em XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution e XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat ao criar o identificador do estimador de luz. O aplicativo precisa definir XrCubemapLightingDataANDROID :: imageBufferSize como a capacidade de cada buffer de imagem de face em bytes. Se o aplicativo não estiver usando a estimativa de luz do cubemap ou se XrCubemapLightingDataANDROID :: imageBufferSize não for grande o suficiente para o ambiente de execução preencher os buffers de imagem, o ambiente de execução precisa definir XrCubemapLightingDataANDROID :: state como XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID .
Se o aplicativo definir XrCubemapLightEstimatorCreateInfoANDROID :: reproject como XR_TRUE ao criar o identificador do estimador de luz, o ambiente de execução precisará definir XrCubemapLightingDataANDROID :: rotation como a rotação de identidade e garantir que o mapa de cubo girado internamente seja reprojetado nas faces de um mapa de cubo de identidade no espaço base do aplicativo.
O layout do cubemap de iluminação é igual ao do OpenGL, conforme mostrado na imagem a seguir.
Figura 31. Layout do mapa de cubo.
Uso válido (implícito)
- A extensão
XR_ANDROID_light_estimation_cubemapprecisa ser ativada antes de usar XrCubemapLightingDataANDROID. -
typeprecisa serXR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas -
stateprecisa ser um valor XrLightEstimateStateANDROID válido -
imageBufferRightprecisa ser um ponteiro para uma matriz de valoresimageBufferSizeuint8_t -
imageBufferLeftprecisa ser um ponteiro para uma matriz de valoresimageBufferSizeuint8_t -
imageBufferTopprecisa ser um ponteiro para uma matriz de valoresimageBufferSizeuint8_t -
imageBufferBottomprecisa ser um ponteiro para uma matriz de valoresimageBufferSizeuint8_t -
imageBufferFrontprecisa ser um ponteiro para uma matriz de valoresimageBufferSizeuint8_t -
imageBufferBackprecisa ser um ponteiro para uma matriz de valoresimageBufferSizeuint8_t - O parâmetro
imageBufferSizeprecisa ser maior que0.
Exemplo de código para estimativa de iluminação
O exemplo de código a seguir demonstra como receber todas as quantidades possíveis de estimativa de luz do ambiente de execução
XrSession session; // Created at app startup
XrInstance instance; // Created at app startup
XrSpace appSpace; // Created previously.
XrSystemId systemId; // Retrieved previously by xrGetSystem
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingResolutionsANDROID xrEnumerateCubemapLightingResolutionsANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingColorFormatsANDROID xrEnumerateCubemapLightingColorFormatsANDROID; // Created previously.
XrSystemCubemapLightEstimationPropertiesANDROID props = {
.type = XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID};
XrSystemProperties base = {.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &props};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));
if (!props.supportsCubemapLightEstimation) {
// Cubemap light estimation is not supported
}
uint32_t cubemapResolution = 0;
std::vector<uint32_t> supportedCubemapResolutions;
uint32_t resolutionCount;
CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
instance, systemId, 0, &resolutionCount, nullptr));
supportedCubemapResolutions.resize(resolutionCount);
if (resolutionCount == 0) {
// No cubemap lighting supported
} else {
CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
instance, systemId, 0, &resolutionCount, supportedCubemapResolutions.data()));
cubemapResolution = supportedCubemapResolutions[0];
}
uint32_t pixelCount = cubemapResolution * cubemapResolution;
XrCubemapLightingColorFormatANDROID colorFormat;
std::vector<XrCubemapLightingColorFormatANDROID> supportedColorFormats;
uint32_t colorFormatCount;
CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
instance, systemId, 0, &colorFormatCount, nullptr));
supportedColorFormats.resize(colorFormatCount);
if (colorFormatCount == 0) {
// No supported color formats for cubemap lighting. Cannot use cubemap
// light estimation.
} else {
CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
instance, systemId, 0, &colorFormatCount, supportedColorFormats.data()));
colorFormat = supportedColorFormats[0];
}
uint32_t pixelSize = 0;
switch (colorFormat) {
case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID:
pixelSize = 3 * sizeof(float);
break;
case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID:
pixelSize = 4 * sizeof(float);
break;
case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID:
pixelSize = 4 * sizeof(uint16_t);
break;
default:
// Should not happen since the color format was validated previously.
break;
}
uint32_t perFaceImageBufferSize = pixelCount * pixelSize;
XrLightEstimatorANDROID estimator;
XrCubemapLightEstimatorCreateInfoANDROID cubemapCreateInfo = {
.type = XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
.cubemapResolution = cubemapResolution,
.colorFormat = colorFormat,
.reproject = XR_TRUE
};
XrLightEstimatorCreateInfoANDROID basicCreateInfo = {
.type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
.next = &cubemapCreateInfo};
CHK_XR(xrCreateLightEstimatorANDROID(session, &basicCreateInfo, &estimator));
std::vector<uint8_t> cubemapBuffer(perFaceImageBufferSize * 6); // 6 faces * perFaceImageBufferSize
// 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,
};
XrCubemapLightingDataANDROID cubemap = {
.type = XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID,
.next = nullptr,
.imageBufferSize = perFaceImageBufferSize,
.imageBufferRight = cubemapBuffer.data() + 0 * perFaceImageBufferSize,
.imageBufferLeft = cubemapBuffer.data() + 1 * perFaceImageBufferSize,
.imageBufferTop = cubemapBuffer.data() + 2 * perFaceImageBufferSize,
.imageBufferBottom = cubemapBuffer.data() + 3 * perFaceImageBufferSize,
.imageBufferFront = cubemapBuffer.data() + 4 * perFaceImageBufferSize,
.imageBufferBack = cubemapBuffer.data() + 5 * perFaceImageBufferSize,
};
XrDirectionalLightANDROID directionalLight = {
.type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
.next = &cubemap,
};
XrSphericalHarmonicsANDROID totalSh = {
.type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
.next = &directionalLight,
.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
};
XrSphericalHarmonicsANDROID ambientSh = {
.type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
.next = &totalSh,
.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
};
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 cubemap, directionalLight, totalSh, ambientSh, and
// ambientLight if each struct has a valid state field
if (cubemap.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
// use cubemap
if (cubemapCreateInfo.reproject == XR_TRUE) {
XrQuaternionf identityQuaternion = {0.0f, 0.0f, 0.0f, 1.0f};
assert(memcmp(&cubemap.rotation, &identityQuaternion, sizeof(XrQuaternionf)) == 0);
}
}
}
// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));
Novos comandos
Novas estruturas
Estendendo XrLightEstimateANDROID :
Estendendo XrLightEstimatorCreateInfoANDROID :
Estendendo XrSystemProperties :
Novos tipos enumerados
Novas constantes de tipo enumerado
XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAMEXR_ANDROID_light_estimation_cubemap_SPEC_VERSIONEstendendo XrStructureType :
XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROIDXR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROIDXR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID
Problemas
Histórico de versões
Revisão 1, 05/12/2025 (Salar Khan)
- Descrição inicial da extensão