XR_ANDROID_light_estimation

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

Estado de ratificación

No se ratificó

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2025-03-13

Estado de la IP

No hay reclamos conocidos por IP.

Colaboradores

Jared Finder, Google
Cairn Overturf, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Salar Khan, Google
Scott Chung, 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. La aplicación puede usar esta información para iluminar objetos virtuales en las mismas condiciones que la escena del mundo real en la que se colocan.

Permisos

Las aplicaciones para Android deben tener el permiso android.permission.SCENE_UNDERSTANDING_COARSE incluido en su manifiesto, ya que esta extensión expone información de iluminación sobre el entorno. El permiso android.permission.SCENE_UNDERSTANDING_COARSE se considera un permiso peligroso. La aplicación debe solicitar el permiso durante el tiempo de ejecución para usar estas funciones:

(nivel de protección: peligroso)

Inspecciona la capacidad del sistema

La estructura XrSystemLightEstimationPropertiesANDROID se define de la siguiente manera:

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 llama a xrGetSystemProperties .

Si y solo si un tiempo de ejecución devuelve XR_FALSE para supportsLightEstimation , el tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateLightEstimatorANDROID .

Uso válido (implícito)

Crea un controlador del estimador de luz

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

El tiempo de ejecución genera los datos de estimación de luz y los comparte con la aplicación a través del controlador XrLightEstimatorANDROID.

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 los parámetros

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

  • El tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED si el sistema no admite la estimación de luz.
  • El tiempo de ejecución debe devolver XR_ERROR_PERMISSION_INSUFFICIENT si no se otorgaron los permisos necesarios a la app de llamada.

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 a través de xrDestroyLightEstimatorANDROID .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

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

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const 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 se define de la siguiente manera:

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Descripciones de los parámetros

La función xrDestroyLightEstimatorANDROID libera el estimator y cualquier recurso subyacente.

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 los 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrLightEstimateGetInfoANDROID se define de la siguiente manera:

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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 las armónicas esféricas devueltas.
  • 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 la luz:

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

Descripciones de los miembros

Para cada estructura de estimación de luz, si state es XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID, todos los demás campos de la estructura son arbitrarios, lo que significa que sus valores no están definidos.

Para obtener información sobre 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, a XrLightEstimateANDROID :: next .

Uso válido (implícito)

La estructura XrAmbientLightANDROID contiene datos de estimación de la luz sobre 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 incluyen XrSphericalHarmonicsANDROID y XrDirectionalLightANDROID .
  • state es el XrLightEstimateStateANDROID que representa el estado de la estimación de luz.
  • intensity es un XrVector3f que representa la intensidad de la luz ambiente. Cada componente del vector corresponde a los canales rojo, verde y azul, respectivamente.

  • colorCorrection es un XrVector3f con valores en el espacio gamma. Si se renderiza en el espacio de color gamma, multiplícalos componente por componente con el color final calculado después del renderizado. Si se renderiza en espacio lineal, primero convierte los valores al espacio lineal elevándolos a la potencia 2.2 y, luego, multiplica componente por componente con el color final calculado después del renderizado.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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 incluyen XrAmbientLightANDROID y XrDirectionalLightANDROID .
  • state es el XrLightEstimateStateANDROID que representa el estado de la estimación de luz.
  • kind es el XrSphericalHarmonicsKindANDROID que solicitó 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.

Los coefficients se deben usar en una función especial que toma una dirección como entrada y genera el color de la luz que proviene de esa dirección. En este informe, se incluyen más detalles .

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,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

Los valores de enumeración tienen los siguientes significados:

Descripción de la enumeración

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Los coeficientes armónicos esféricos representan la función de radiancia de la luz del entorno, sin incluir 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 del entorno, incluida la contribución de la luz principal.

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 XrLightEstimateStateANDROID indica el estado de la estimación de luz que devuelve el tiempo de ejecución.

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

Los valores de enumeración tienen los siguientes significados:

Descripción de la enumeració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 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.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &sphericalHarmonics,
};

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

Comandos nuevos

Nuevas estructuras

Nuevas enumeraciones

Nuevas constantes de enumeración

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • Extensión de XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Extensión de XrStructureType :

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Problemas

Historial de versiones

  • Revisión 1, 2024-09-16 (Cairn Overturf)

    • Descripción inicial de la extensión