XR_ANDROID_light_estimation_cubemap

Name String

XR_ANDROID_light_estimation_cubemap

Tipo de extensión

Extensión de instancia

Número de extensión registrado

722

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

XR_ANDROID_light_estimation

Fecha de la última modificación

2025-08-06

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Salar Khan, Google
Scott Chung, Google
Jared Finder, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Jürgen Sturm, Google

Descripción general

Esta extensión se basa en la extensión básica XR_ANDROID_light_estimation. Agrega compatibilidad para obtener estimaciones de iluminación de mapas de cubos, lo que proporciona estimaciones más detalladas sobre la iluminación en el entorno físico.

Nota

El mecanismo para obtener los datos de estimación de luz es el mismo que el de la extensión básica, excepto que XrCubemapLightEstimatorCreateInfoANDROID debe encadenarse a XrLightEstimatorCreateInfoANDROID cuando se crea el controlador del estimador de luz.

Inspecciona la capacidad del sistema

typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • supportsCubemapLightEstimation es un XrBool32 que indica si el sistema actual admite la estimación de luz del mapa de cubos.

Una aplicación puede inspeccionar si el sistema es capaz de admitir la estimación de luz de mapa de cubo extendiendo XrSystemProperties con la estructura XrSystemCubemapLightEstimationPropertiesANDROID cuando se llama a xrGetSystemProperties .

Si el entorno de ejecución devuelve XR_FALSE para supportsCubemapLightEstimation y XrCubemapLightEstimatorCreateInfoANDROID se encadenó a XrLightEstimatorCreateInfoANDROID , el entorno de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED de xrCreateLightEstimatorANDROID .

Uso válido (implícito)

Obtén resoluciones de mapas de cubos compatibles

XrResult xrEnumerateCubemapLightingResolutionsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    uint32_t*                                   resolutions);

Descripciones de los parámetros

  • instance es una XrInstance creada anteriormente.
  • systemId es el XrSystemId que xrGetSystem recuperó anteriormente y para el que se obtendrán las resoluciones de mapa de cubo compatibles.
  • resolutionCapacityInput es un uint32_t que indica la cantidad máxima de elementos que se pueden almacenar en el array resolutions.
  • resolutionCountOutput es un puntero a un uint32_t que establece el entorno de ejecución y que indica la cantidad de elementos que el entorno de ejecución escribió en el array resolutions.
  • resolutions es un array de uint32_t que el entorno de ejecución propaga con las resoluciones de mapas de cubos compatibles.

La resolución de un mapa de cubo indica el ancho y la altura de cada cara del mapa de cubo en píxeles. Lenguaje de 2 llamadas Luego, la aplicación puede elegir usar una de las resoluciones admitidas en XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution cuando se crea el controlador del estimador de luz. La aplicación debe asignar la cantidad adecuada de memoria para los miembros del búfer de imágenes de XrCubemapLightingDataANDROID según la resolución elegida y el formato de color.

Uso válido (implícito)

  • La extensión XR_ANDROID_light_estimation_cubemap debe estar habilitada antes de llamar a xrEnumerateCubemapLightingResolutionsANDROID.
  • instance debe ser un controlador XrInstance válido.
  • resolutionCountOutput debe ser un puntero a un valor uint32_t
  • Si resolutionCapacityInput no es 0 , resolutions debe ser un puntero a un array de valores resolutionCapacityInput uint32_t

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Cómo obtener formatos de color de mapa de cubo compatibles

La enumeración XrCubemapLightingColorFormatANDROID identifica para el entorno de ejecución el formato de color de la iluminación del mapa de cubo que se usará.

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;

Las enumeraciones tienen los siguientes significados:

Descripción de enum

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID

Es un formato de color con 3 canales en el que cada canal es un valor de punto flotante de 32 bits.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID

Es un formato de color con 4 canales en el que cada canal es un valor de punto flotante de 32 bits.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID

Es un formato de color con 4 canales en el que cada canal es un valor de punto flotante de 16 bits.

XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    colorFormatCapacityInput,
    uint32_t*                                   colorFormatCountOutput,
    XrCubemapLightingColorFormatANDROID*        colorFormats);

Descripciones de los parámetros

  • instance es una XrInstance creada anteriormente.
  • systemId es el XrSystemId que xrGetSystem recuperó anteriormente y para el que se obtendrán las resoluciones de mapa de cubo compatibles.
  • colorFormatCapacityInput es un uint32_t que indica la cantidad máxima de elementos que se pueden almacenar en el array colorFormats.
  • colorFormatCountOutput es un puntero a un uint32_t que establece el entorno de ejecución y que indica la cantidad de elementos que el entorno de ejecución escribió en el array colorFormats.
  • colorFormats es un array de XrCubemapLightingColorFormatANDROID que el entorno de ejecución propaga con los formatos de color de mapa de cubo compatibles.

Lenguaje de 2 llamadas: Luego, la aplicación puede elegir usar uno de los formatos de color admitidos en XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat cuando se crea el controlador del estimador de luz. La aplicación debe asignar la cantidad adecuada de memoria para los miembros del búfer de imágenes de XrCubemapLightingDataANDROID según el formato de color elegido.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Crea un controlador de estimador de luz de mapa de cubo

typedef struct XrCubemapLightEstimatorCreateInfoANDROID {
    XrStructureType                        type;
    const void*                            next;
    uint32_t                               cubemapResolution;
    XrCubemapLightingColorFormatANDROID    colorFormat;
    XrBool32                               reproject;
} XrCubemapLightEstimatorCreateInfoANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
  • cubemapResolution es un uint32_t que indica la resolución de la iluminación del mapa de cubo que se usará.
  • colorFormat es un XrCubemapLightingColorFormatANDROID que indica el formato de color de los datos de iluminación del mapa de cubo que se usarán.
  • reproject es un XrBool32 que indica si la iluminación del mapa de cubo debe volver a proyectarse en el espacio base de la aplicación.

La estructura XrCubemapLightEstimatorCreateInfoANDROID describe la información para crear un controlador XrLightEstimatorANDROID que pueda proporcionar estimaciones de iluminación de mapas de cubos. El miembro XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution debe establecerse en una de las resoluciones que muestra xrEnumerateCubemapLightingResolutionsANDROID . El miembro XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat debe establecerse en uno de los formatos de color que muestra xrEnumerateCubemapLightingColorFormatsANDROID . Si la aplicación no establece la resolución en una de las resoluciones admitidas o el formato de color en uno de los formatos de color admitidos, el entorno de ejecución debe mostrar XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateLightEstimatorANDROID .

Uso válido (implícito)

Estimaciones de luz de mapas de cubos

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;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. Las estructuras válidas son XrAmbientLightANDROID, XrSphericalHarmonicsANDROID y XrDirectionalLightANDROID .
  • state es el XrLightEstimateStateANDROID que representa el estado de la estimación de luz.
  • imageBufferSize es un uint32_t que indica el tamaño en bytes de cada búfer de imagen de cara en el mapa cúbico.
  • imageBufferRight es un búfer uint8_t que contiene la imagen de la cara derecha del mapa de cubo.
  • imageBufferLeft es un búfer uint8_t que contiene la imagen de la cara izquierda del mapa de cubo.
  • imageBufferTop es un búfer uint8_t que contiene la imagen de la cara superior del mapa de cubo.
  • imageBufferBottom es un búfer uint8_t que contiene la imagen de la cara inferior del mapa de cubo.
  • imageBufferFront es un búfer uint8_t que contiene la imagen de la cara frontal del mapa de cubo.
  • imageBufferBack es un búfer uint8_t que contiene la imagen de la cara posterior del mapa de cubo.
  • rotation es un XrQuaternionf que indica la rotación del mapa de cubo.
  • centerExposureTime es un XrTime que indica la hora en que se capturó el mapa de cubo.

Esta estructura se puede encadenar a XrLightEstimateANDROID . El entorno de ejecución debe propagar esta estructura solo en xrGetLightEstimateANDROID si se usó XrCubemapLightEstimatorCreateInfoANDROID para crear el controlador del estimador de luz. La aplicación debe asignar la cantidad adecuada de memoria para los búferes de imagen, que depende de los valores establecidos en XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution y XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat cuando se crea el controlador del estimador de luz. La aplicación debe establecer XrCubemapLightingDataANDROID :: imageBufferSize en la capacidad de cada búfer de imagen de cara en bytes. Si la aplicación no usa la estimación de luz de mapa de cubo o si XrCubemapLightingDataANDROID :: imageBufferSize no es lo suficientemente grande como para que el entorno de ejecución complete los búferes de imagen, el entorno de ejecución debe establecer XrCubemapLightingDataANDROID :: state en XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID .

Si la aplicación estableció XrCubemapLightEstimatorCreateInfoANDROID :: reproject en XR_TRUE cuando creó el controlador del estimador de luz, el entorno de ejecución debe establecer XrCubemapLightingDataANDROID :: rotation en la rotación de identidad y asegurarse de que el mapa de cubo rotado interno se vuelva a proyectar en las caras de un mapa de cubo de identidad en el espacio base de la aplicación.

El diseño del mapa de cubo de iluminación es el mismo que el del mapa de cubo de OpenGL, como se muestra en la siguiente imagen.

Diseño de mapa de cubo de estimación de iluminación de XR ANDROID

Figura 31. Diseño de mapa de cubo.

Uso válido (implícito)

  • La extensión XR_ANDROID_light_estimation_cubemap debe estar habilitada antes de usar XrCubemapLightingDataANDROID.
  • type debe ser XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
  • next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras
  • state debe ser un valor XrLightEstimateStateANDROID válido.
  • imageBufferRight debe ser un puntero a un array de valores imageBufferSize uint8_t
  • imageBufferLeft debe ser un puntero a un array de valores imageBufferSize uint8_t
  • imageBufferTop debe ser un puntero a un array de valores imageBufferSize uint8_t
  • imageBufferBottom debe ser un puntero a un array de valores imageBufferSize uint8_t
  • imageBufferFront debe ser un puntero a un array de valores imageBufferSize uint8_t
  • imageBufferBack debe ser un puntero a un array de valores imageBufferSize uint8_t
  • El parámetro imageBufferSize debe ser mayor que 0.

Código de ejemplo para la estimación de luz

En el siguiente código de ejemplo, se muestra cómo obtener todas las cantidades posibles de estimación de luz del entorno de ejecución

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));

Comandos nuevos

Estructuras nuevas

Enums nuevas

Nuevas constantes de enum

  • XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAME
  • XR_ANDROID_light_estimation_cubemap_SPEC_VERSION

  • Extiende XrStructureType :

    • XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
    • XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Problemas

Historial de versiones

  • Revisión 1, 5 de diciembre de 2025 (Salar Khan)

    • Descripción inicial de la extensión