**Name String**

`XR_ANDROID_light_estimation`

**Extension Type**

Instance extension

**Registered Extension Number**

701

**Revision**

1

**Extension and Version Dependencies**

[OpenXR 1.0](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#versions-1.0)

**Last Modified Date**

2025-01-17

**IP Status**

No known IP claims.

**Contributors**

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Salar Khan, Google

Scott Chung, Google

## Overview

This extension allows the application to request data representing the lighting
of the real-world environment around the headset. This information can be used
when rendering virtual objects to light them under the same conditions as the
scene they're placed in.
| **Note:** The light estimation data is generated by the runtime and shared with the
| application using
| [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID).
| **Caution:**   
|
| **Permissions**
|
| Android applications **must** have the
| `android.permission.SCENE_UNDERSTANDING_COARSE` permission listed in their
| manifest as this extension exposes lighting information about the environment.
| The `android.permission.SCENE_UNDERSTANDING_COARSE` permission is considered a
| dangerous permission. The application **must**
| [request
| the permission at runtime](https://developer.android.com/training/permissions/requesting) to use these functions:
|
| - [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID)
|
| (protection level: dangerous)

## Inspect system capability

An application **can** inspect whether the system supports light estimation by
chaining an [XrSystemLightEstimationPropertiesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSystemLightEstimationPropertiesANDROID) structure to the
[XrSystemProperties](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSystemProperties) when calling [xrGetSystemProperties](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrGetSystemProperties).  

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

### Member Descriptions

- `type` is the [XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) of this structure.
- `next` is `NULL` or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `supportsLightEstimation` is an [`XrBool32`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrBool32), indicating if the current system supports light estimation.

An application **can** inspect whether the system is capable of supporting light
estimation by extending the [XrSystemProperties](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSystemProperties) with
[XrSystemLightEstimationPropertiesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSystemLightEstimationPropertiesANDROID) structure when calling
[xrGetSystemProperties](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrGetSystemProperties).

If the system is not capable of supporting light estimation, then it will return
`XR_FALSE` for `supportsLightEstimation`, and `XR_ERROR_FEATURE_UNSUPPORTED`
from [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID).

### Valid Usage (Implicit)

- The [XR_ANDROID_light_estimation](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to using [XrSystemLightEstimationPropertiesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSystemLightEstimationPropertiesANDROID)
- `type` **must** be `XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID`
- `next` **must** be `NULL` or a valid pointer to the [next structure in a
  structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)

## Create a light estimator handle

    XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

The [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID) handle represents a light estimator. This
handle **can** be used to access light estimation information using other
functions in this extension.

The [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID) function is defined as:  

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

### Parameter Descriptions

- `session` is the [XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession) that creates the light estimator.
- `createInfo` is a pointer to an [XrLightEstimatorCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorCreateInfoANDROID) structure containing parameters to be used to create the light estimator.
- `outHandle` is a pointer to a handle in which the created [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID) is returned.

The application **can** use [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID) function to
create a light estimator.

- [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID) will return `XR_ERROR_FEATURE_UNSUPPORTED` if the system does not support light estimation.
- [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID) will return `XR_ERROR_PERMISSION_INSUFFICIENT` if the required permissions have not been granted to the calling application.

The returned light estimator handle **may** be subsequently used in API calls.
If an application wants to indicate to the runtime that it is done accessing
light estimation data it **must** destroy the handle using
[xrDestroyLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrDestroyLightEstimatorANDROID).

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to calling [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID)
- `session` **must** be a valid [XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession) handle
- `createInfo` **must** be a pointer to an [XrLightEstimatorCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorCreateInfoANDROID) structure
- `outHandle` **must** be a pointer to an [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID) handle

Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `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`

The [XrLightEstimatorCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorCreateInfoANDROID) structure describes the information
to create an [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID) handle.  

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

### Member Descriptions

- `type` is the [XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) of this structure.
- `next` is `NULL` or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to using [XrLightEstimatorCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorCreateInfoANDROID)
- `type` **must** be `XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID`
- `next` **must** be `NULL` or a valid pointer to the [next structure in a
  structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)

[xrDestroyLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrDestroyLightEstimatorANDROID) function releases the `estimator` and any
underlying resources.  

    XrResult xrDestroyLightEstimatorANDROID(
        XrLightEstimatorANDROID                     estimator);

### Parameter Descriptions

- `estimator` is an [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID) previously created by [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID).

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to calling [xrDestroyLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrDestroyLightEstimatorANDROID)
- `estimator` **must** be a valid [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID) handle

### Thread Safety

- Access to `estimator`, and any child handles, **must** be externally synchronized

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_HANDLE_INVALID`

## Access light estimation data

The [xrGetLightEstimateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrGetLightEstimateANDROID) function is defined as:  

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

### Parameter Descriptions

- `estimator`: Handle to an [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID) previously created with `xrCreateLightEstimatorANDROID`.
- `input`: Pointer to an [XrLightEstimateGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateGetInfoANDROID) structure.
- `output`: Pointer to an [XrLightEstimateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateANDROID) structure.

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to calling [xrGetLightEstimateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrGetLightEstimateANDROID)
- `estimator` **must** be a valid [XrLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorANDROID) handle
- `input` **must** be a pointer to a valid [XrLightEstimateGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateGetInfoANDROID) structure
- `output` **must** be a pointer to an [XrLightEstimateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateANDROID) structure

### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `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`

A [XrLightEstimateGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateGetInfoANDROID) describes the information required to get
light estimation data.  

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

### Member Descriptions

- `type` is the [XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) of this structure.
- `next` is `NULL` or a pointer to the next structure in a structure chain.
- `space` is the [XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace) defining the reference space in which the returned light direction and spherical harmonics and cubemap rotation are expressed.
- `time` is the [`XrTime`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrTime) that describes the time at which the application wishes to query the light estimation.

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to using [XrLightEstimateGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateGetInfoANDROID)
- `type` **must** be `XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID`
- `next` **must** be `NULL` or a valid pointer to the [next structure in a
  structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `space` **must** be a valid [XrSpace](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSpace) handle

[XrLightEstimateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateANDROID) structure contains light estimation data.  

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

### Member Descriptions

- `type` is the [XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) of this structure.
- `next` is `NULL` or a pointer to the next structure in a structure chain. Valid structures are [XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID), [XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID), [XrEnvironmentLightingCubemapANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrEnvironmentLightingCubemapANDROID) and [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID).
- `state` is the [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) representing the state of the light estimate.
- `lastUpdatedTime` is the [`XrTime`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrTime) that represents when the estimate was last calculated.

To obtain light estimate information for the environment lighting cubemap, ambient
light, spherical harmonics, and
the primary directional light, applications **can** chain instances of the
following structures,
[XrEnvironmentLightingCubemapANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrEnvironmentLightingCubemapANDROID),
[XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID),
[XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID) and [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID)
respectively onto [XrLightEstimateANDROID::next](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateANDROID).

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to using [XrLightEstimateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateANDROID)
- `type` **must** be `XR_TYPE_LIGHT_ESTIMATE_ANDROID`
- `next` **must** be `NULL` or a valid pointer to the [next structure in a
  structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains). See also: [XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID), [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID), [XrEnvironmentLightingCubemapANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrEnvironmentLightingCubemapANDROID), [XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID)
- `state` **must** be a valid [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) value

The [XrEnvironmentLightingCubemapANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrEnvironmentLightingCubemapANDROID)
structure contains light estimation data in a cubemap format about the
environment lighting of the scene.  

    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;

### Member Descriptions

- `type` is the [XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) of this structure.
- `next` is `NULL` or a pointer to the next structure in a structure chain. Valid structures are [XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID), [XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID), and [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID).
- `state` is the [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) representing the state of the light estimate.
- `cubemapRightImage` is a `float*` representing the R32G32B32_SFLOAT buffer of the right side of the cubemap. Note this is HDR so float values can be greater than 1.0.
- `cubemapLeftImage` is a `float*` representing the R32G32B32_SFLOAT buffer of the left side of the cubemap. Note this is HDR so float values can be greater than 1.0.
- `cubemapTopImage` is a `float*` representing the R32G32B32_SFLOAT buffer of the top side of the cubemap. Note this is HDR so float values can be greater than 1.0.
- `cubemapBottomImage` is a `float*` representing the R32G32B32_SFLOAT buffer of the bottom side of the cubemap. Note this is HDR so float values can be greater than 1.0.
- `cubemapFrontImage` is a `float*` representing the R32G32B32_SFLOAT buffer of the front side of the cubemap. Note this is HDR so float values can be greater than 1.0.
- `resolution` is a `uint32_t` representing the width and height of the image of each side of the cubemap.
- `rotation` is a [XrQuaternionf](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrQuaternionf) representing the rotation of the cubemap.
- `centerExposureTime` is a `XrTime` representing the time the cubemap was captured. Useful for interpolation between cubemaps.

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to using [XrEnvironmentLightingCubemapANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrEnvironmentLightingCubemapANDROID)
- `type` **must** be `XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID`
- `next` **must** be `NULL` or a valid pointer to the [next structure in a
  structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `state` **must** be a valid [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) value
- `cubemapRightImage` **must** be a pointer to a valid float value
- `cubemapLeftImage` **must** be a pointer to a valid float value
- `cubemapTopImage` **must** be a pointer to a valid float value
- `cubemapBottomImage` **must** be a pointer to a valid float value
- `cubemapFrontImage` **must** be a pointer to a valid float value
- `cubemapBackImage` **must** be a pointer to a valid float value

[XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID) structure contains light estimation data about the
ambient light in the scene.  

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

### Member Descriptions

- `type` is the [XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) of this structure.
- `next` is `NULL` or a pointer to the next structure in a structure chain. Valid structures are [XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID), [XrEnvironmentLightingCubemapANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrEnvironmentLightingCubemapANDROID), and [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID).
- `state` is the [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) representing the state of the light estimate.
- `intensity` is a `XrVector3` representing the intensity of the ambient light. Each component of the vector corresponds to the red, green and blue channels.
- `colorCorrection` is a `XrVector3` with values in gamma space. Componentwise multiply the color of your gamma corrected render with these values.

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to using [XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID)
- `type` **must** be `XR_TYPE_AMBIENT_LIGHT_ANDROID`
- `next` **must** be `NULL` or a valid pointer to the [next structure in a
  structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `state` **must** be a valid [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) value

[XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID) structure contains spherical harmonics
representing the lighting of the scene.  

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

### Member Descriptions

- `type` is the [XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) of this structure.
- `next` is `NULL` or a pointer to the next structure in a structure chain. Valid structures are [XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID), [XrEnvironmentLightingCubemapANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrEnvironmentLightingCubemapANDROID), and [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID).
- `state` is the [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) representing the state of the light estimate.
- `kind` is the [XrSphericalHarmonicsKindANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsKindANDROID) requested by the application.
- `coefficients` is a two-dimensional `float` array with dimensions 9 rows and 3 columns. The 3 columns corresponding to color channels red, green and blue respectively. Each channel has 9 spherical harmonic coefficients.

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to using [XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID)
- `type` **must** be `XR_TYPE_SPHERICAL_HARMONICS_ANDROID`
- `next` **must** be `NULL` or a valid pointer to the [next structure in a
  structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `state` **must** be a valid [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) value
- `kind` **must** be a valid [XrSphericalHarmonicsKindANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsKindANDROID) value

[XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID) structure contains light estimation data.  

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

### Member Descriptions

- `type` is the [XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) of this structure.
- `next` is `NULL` or a pointer to the next structure in a structure chain. Valid structures are [XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID), [XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID) and [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID).
- `state` is the [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) representing the state of the light estimate.
- `intensity` is a `XrVector3` representing the intensity of the directional light. Each component of the vector corresponds to the red, green and blue channels.
- `direction` is a `XrVector3` representing the light direction.

### Valid Usage (Implicit)

- The [`XR_ANDROID_light_estimation`](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XR_ANDROID_light_estimation) extension **must** be enabled prior to using [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID)
- `type` **must** be `XR_TYPE_DIRECTIONAL_LIGHT_ANDROID`
- `next` **must** be `NULL` or a valid pointer to the [next structure in a
  structure chain](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-valid-usage-for-structure-pointer-chains)
- `state` **must** be a valid [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) value

The [XrSphericalHarmonicsKindANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsKindANDROID) enumeration identifies to the runtime,
what type of spherical harmonics the application is requesting.  

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

The enums have the following meanings:

|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| **Enum**                                      | **Description**                                                                                                                        |
| `XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID`   | The spherical harmonic coefficients represent the environment light radiance function, including the contribution from the main light. |
| `XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID` | The spherical harmonic coefficients represent the environment light radiance function, excluding the contribution from the main light. |

The [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID) enumeration identifies to the runtime,
what type of spherical harmonics the application is requesting.  

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

The enums have the following meanings:

|-------------------------------------------|-------------------------------|
| **Enum**                                  | **Description**               |
| `XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID`   | The light estimate is valid   |
| `XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID` | The light estimate is invalid |

## Example code for light estimation

The following example code demonstrates how to get all possible light estimation
quantities from the runtime.  

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

**New Object Types**

- `XrLightEstimator`

[XrObjectType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrObjectType) enumeration is extended with:

- `XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID`

[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType) enumeration is extended with:

- `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`

**New Enums**

- [XrSphericalHarmonicsKindANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsKindANDROID)
- [XrLightEstimateStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateStateANDROID)

**New Structures**

- [XrLightEstimatorCreateInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimatorCreateInfoANDROID)
- [XrLightEstimateGetInfoANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateGetInfoANDROID)
- [XrLightEstimateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrLightEstimateANDROID)
- [XrDirectionalLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrDirectionalLightANDROID)
- [XrSphericalHarmonicsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSphericalHarmonicsANDROID)
- [XrAmbientLightANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrAmbientLightANDROID)
- [XrSystemLightEstimationPropertiesANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrSystemLightEstimationPropertiesANDROID)
- [XrEnvironmentLightingCubemapANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#XrEnvironmentLightingCubemapANDROID)

**New Functions**

- [xrCreateLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrCreateLightEstimatorANDROID)
- [xrDestroyLightEstimatorANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrDestroyLightEstimatorANDROID)
- [xrGetLightEstimateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_light_estimation#xrGetLightEstimateANDROID)

**Issues**

**Version History**

- Revision 2, 2025-01-17 (Salar Khan)
  - Added environment lighting cubemap support
- Revision 1, 2024-09-16 (Cairn Overturf)
  - Initial extension description

*** ** * ** ***

OpenXR™ and the OpenXR logo are trademarks owned
by The Khronos Group Inc. and are registered as a trademark in China,
the European Union, Japan and the United Kingdom.