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 última modificación

2024-09-18

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Descripción general

Esta extensión permite que la aplicación solicite datos que representen la iluminación del entorno real alrededor de los auriculares. 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.

Cómo inspeccionar 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 la luz extendiendo XrSystemProperties con la estructura XrSystemLightEstimationPropertiesANDROID cuando se llama a xrGetSystemProperties.

Si el sistema no es compatible con la estimación de luz, mostrará XR_FALSE para supportsLightEstimation y XR_ERROR_FEATURE_UNSUPPORTED de xrCreateLightEstimatorANDROID.

Uso válido (implícito)

Crea un identificador de estimador ligero

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

El control XrLightEstimatorANDROID representa un estimador de luz. Este control se puede usar para acceder a la información de estimación de la 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 los 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 muestra puede usarse posteriormente en llamadas a la API. Si una aplicación quiere indicarle al entorno de ejecución que ya terminó de acceder a los datos de estimación de luz, debe destruir el controlador con xrDestroyLightEstimatorANDROID.

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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 control 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 cualquier recurso subyacente. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descripciones de los parámetros

Uso válido (implícito)

Seguridad de subprocesos

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

Códigos de retorno

Correcto

  • XR_SUCCESS

Error

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Accede a los datos de estimación de la luz

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

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

Descripciones de los parámetros

Uso válido (implícito)

Códigos de retorno

Correcto

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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 la 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 que se muestra y los armónicos esféricos.
  • time es el XrTime que describe el momento en el 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 luz. 

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

Descripciones de los miembros

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

Uso válido (implícito)

La estructura XrAmbientLightANDROID contiene datos de estimación de luz sobre la luz ambiental de 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 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 el color de la renderización corregida por gamma con estos valores por componente.

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

  • 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 y XrDirectionalLightANDROID.
  • state es el XrLightEstimateStateANDROID que representa el estado de la estimación de luz.
  • kind es el XrSphericalHarmonicsKindANDROID que solicita la aplicación.
  • coefficients es un array float bidimensional con dimensiones de 9 filas y 3 columnas. Las 3 columnas correspondientes a los canales de color rojo, verde y azul, respectivamente. Cada canal tiene 9 coeficientes armónicos esféricos.

Uso válido (implícito)

La estructura XrDirectionalLightANDROID contiene datos de estimación de 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 al entorno 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;

Las enumeraciones tienen los siguientes significados:

Enum

Descripción

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

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

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Los coeficientes de armónicos esféricos representan la función de brillo de la luz ambiental, incluida la contribución de la luz principal.

La enumeración XrLightEstimateStateANDROID identifica al entorno de ejecución el tipo de armónicos esféricos que solicita la aplicación. 

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

Las enumeraciones tienen los siguientes significados:

Enum

Descripción

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

La estimación de la luz es válida

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

La estimación de luz no es válida.

Código de ejemplo para la estimación de la 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
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));

Nuevos tipos de objetos

  • XrLightEstimator

La enumeración XrObjectType se extiende con lo siguiente:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

La enumeración XrStructureType se extiende 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

Enumeraciones nuevas

Nuevas estructuras

Funciones nuevas

Problemas

Historial de versiones

  • Revisión 1, 16/9/2024 (Cairn Overturf)
    • Descripción inicial de la extensión