Extensión XR_ANDROID_light_estimation de OpenXR

Cadena de nombre

XR_ANDROID_light_estimation

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

701

Revisión

1

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2025-01-17

Estado de la IP

No hay reclamos conocidos por IP.

Colaboradores

Jared Finder, Google

Cairn Overturf, de Google

Spencer Quin, de Google

Levana Chen, de Google

Nihav Jain, de Google

Salar Khan, de Google

Scott Chung, de Google

Descripción general

Esta extensión permite que la aplicación solicite datos que representan la iluminación del entorno del mundo real alrededor del visor. Esta información se puede usar cuando se renderizan objetos virtuales para iluminarlos en las mismas condiciones que la escena en la que se colocan.

Inspecciona la capacidad del sistema

Una aplicación puede inspeccionar si el sistema admite la estimación de luz encadenando una estructura XrSystemLightEstimationPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties. 

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

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.
  • supportsLightEstimation es un XrBool32 que indica si el sistema actual admite la estimación de luz.

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

Si el sistema no es capaz de admitir la estimación de luz, devolverá XR_FALSE para supportsLightEstimation y XR_ERROR_FEATURE_UNSUPPORTED de xrCreateLightEstimatorANDROID.

Uso válido (implícito)

Crea un identificador del estimador de luz

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

El identificador de XrLightEstimatorANDROID representa un estimador de luz. Este identificador se puede usar para acceder a la información de estimación de luz con otras funciones de esta extensión.

La función xrCreateLightEstimatorANDROID se define de la siguiente manera: 

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

Descripciones de parámetros

La aplicación puede usar la función xrCreateLightEstimatorANDROID para crear un estimador de luz.

El identificador del estimador de luz que se devuelve puede usarse posteriormente en llamadas a la API. Si una aplicación quiere indicarle al tiempo de ejecución que terminó de acceder a los datos de estimación de luz, debe destruir el identificador con xrDestroyLightEstimatorANDROID.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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

La estructura XrLightEstimatorCreateInfoANDROID describe la información para crear un identificador XrLightEstimatorANDROID. 

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrLightEstimatorCreateInfoANDROID;

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.

Uso válido (implícito)

La función xrDestroyLightEstimatorANDROID libera el estimator y todos los recursos subyacentes. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descripciones de parámetros

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a estimator y a cualquier identificador secundario debe sincronizarse de forma externa.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Cómo acceder a los datos de estimación de luz

La función xrGetLightEstimateANDROID se define de la siguiente manera: 

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

Descripciones de parámetros

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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

Un XrLightEstimateGetInfoANDROID describe la información necesaria para obtener datos de estimación de luz. 

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

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.
  • space es el XrSpace que define el espacio de referencia en el que se expresan la dirección de la luz y los armónicos esféricos, y la rotación del mapa cúbico devueltos.
  • time es el objeto XrTime que describe la hora en la que la aplicación desea consultar la estimación de luz.

Uso válido (implícito)

La estructura XrLightEstimateANDROID contiene datos de estimación de la luz. 

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

Descripciones de los miembros

Para obtener información sobre la estimación de luz del mapa de cubos de iluminación del entorno, la luz ambiental, los armónicos esféricos y la luz direccional principal, las aplicaciones pueden encadenar instancias de las siguientes estructuras, XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID y XrDirectionalLightANDROID, respectivamente, en XrLightEstimateANDROID::next.

Uso válido (implícito)

La estructura XrEnvironmentLightingCubemapANDROID contiene datos de estimación de la luz en formato de mapa de cubo sobre la iluminación del entorno de la escena. 

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;

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 XrSphericalHarmonicsANDROID, XrAmbientLightANDROID y XrDirectionalLightANDROID.
  • state es el XrLightEstimateStateANDROID que representa el estado de la estimación de luz.
  • cubemapRightImage es un float* que representa el búfer R32G32B32_SFLOAT del lado derecho del mapa de cubo. Ten en cuenta que se trata de HDR, por lo que los valores de punto flotante pueden ser mayores que 1.0.
  • cubemapLeftImage es un float* que representa el búfer R32G32B32_SFLOAT del lado izquierdo del mapa de cubo. Ten en cuenta que se trata de HDR, por lo que los valores de punto flotante pueden ser mayores que 1.0.
  • cubemapTopImage es un float* que representa el búfer R32G32B32_SFLOAT del lado superior del mapa de cubo. Ten en cuenta que se trata de HDR, por lo que los valores de punto flotante pueden ser mayores que 1.0.
  • cubemapBottomImage es un float* que representa el búfer R32G32B32_SFLOAT del lado inferior del mapa de cubo. Ten en cuenta que se trata de HDR, por lo que los valores de punto flotante pueden ser mayores que 1.0.
  • cubemapFrontImage es un float* que representa el búfer R32G32B32_SFLOAT del lado frontal del mapa de cubo. Ten en cuenta que se trata de HDR, por lo que los valores de punto flotante pueden ser mayores que 1.0.
  • resolution es un uint32_t que representa el ancho y la altura de la imagen de cada lado del mapa de cubo.
  • rotation es un XrQuaternionf que representa la rotación del mapa de cubo.
  • centerExposureTime es un objeto XrTime que representa la hora en la que se capturó el mapa de cubos. Es útil para la interpolación entre mapas de cubo.

Uso válido (implícito)

  • La extensión XR_ANDROID_light_estimation debe habilitarse antes de usar XrEnvironmentLightingCubemapANDROID.
  • type debe ser XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras
  • state debe ser un valor de XrLightEstimateStateANDROID válido
  • cubemapRightImage debe ser un puntero a un valor de número de punto flotante válido.
  • cubemapLeftImage debe ser un puntero a un valor de número de punto flotante válido.
  • cubemapTopImage debe ser un puntero a un valor de número de punto flotante válido.
  • cubemapBottomImage debe ser un puntero a un valor de número de punto flotante válido.
  • cubemapFrontImage debe ser un puntero a un valor de número de punto flotante válido.
  • cubemapBackImage debe ser un puntero a un valor de número de punto flotante válido.

La estructura XrAmbientLightANDROID contiene datos de estimación de la luz ambiente en la escena. 

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

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 XrSphericalHarmonicsANDROID, XrEnvironmentLightingCubemapANDROID y XrDirectionalLightANDROID.
  • state es el XrLightEstimateStateANDROID que representa el estado de la estimación de luz.
  • intensity es un XrVector3 que representa la intensidad de la luz ambiental. Cada componente del vector corresponde a los canales rojo, verde y azul.
  • colorCorrection es un XrVector3 con valores en el espacio gamma. Multiplica componente por componente el color de la renderización corregida por gamma con estos valores.

Uso válido (implícito)

La estructura XrSphericalHarmonicsANDROID contiene armónicos esféricos que representan la iluminación de la escena. 

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

Descripciones de los miembros

Uso válido (implícito)

La estructura XrDirectionalLightANDROID contiene datos de estimación de la luz. 

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

Descripciones de los miembros

Uso válido (implícito)

La enumeración XrSphericalHarmonicsKindANDROID identifica para el tiempo de ejecución qué tipo de armónicos esféricos solicita la aplicación. 

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1
} XrSphericalHarmonicsKindANDROID;

Los enums tienen los siguientes significados:

Enum

Descripción

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Los coeficientes armónicos esféricos representan la función de radiancia de la luz del entorno, incluida la contribución de la luz principal.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Los coeficientes armónicos esféricos representan la función de radiancia de la luz ambiental, sin incluir la contribución de la luz principal.

La enumeración XrLightEstimateStateANDROID identifica para el tiempo de ejecución qué tipo de armónicos esféricos solicita la aplicación. 

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

Los enums tienen los siguientes significados:

Enum

Descripción

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

La estimación de luz es válida

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

La estimación de luz no es válida

Ejemplo de código para la estimación de la luz

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

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

Nuevos tipos de objetos

  • XrLightEstimator

La enumeración XrObjectType se extiende con lo siguiente:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

Se extiende la enumeración XrStructureType con lo siguiente:

  • 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

Nuevas enumeraciones

Nuevas estructuras

Nuevas funciones

Problemas

Historial de versiones

  • Revisión 2, 2025-01-17 (Salar Khan)
    • Se agregó compatibilidad con el mapa de cubos de iluminación ambiental
  • Revisión 1, 2024-09-16 (Cairn Overturf)
    • Descripción inicial de la extensión

OpenXR™ y el logotipo de OpenXR son marcas comerciales propiedad de The Khronos Group Inc. y están registradas como marcas comerciales en China, la Unión Europea, Japón y el Reino Unido.