# ArLightEstimate

Holds information about the estimated lighting of the real scene.

## Summary

| ### Enumerations ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimatestate{ https://developers.google.com/ar/reference/c/group/ar-light-estimate#ar_light_estimate_state_not_valid = 0, https://developers.google.com/ar/reference/c/group/ar-light-estimate#ar_light_estimate_state_valid = 1 }` | enumTracks the validity of an `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` object. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` | typedef `struct ArLightEstimate_` An estimate of the real-world lighting ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_acquireenvironmentalhdrcubemap(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate, https://developers.google.com/ar/reference/c/group/ar-image#arimagecubemap out_textures_6)` | `void` Gets the 6 cubemap textures in OpenGL texture format based on the inferred Environmental HDR lighting. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_create(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate **out_light_estimate)` | `void` Allocates an `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` object. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_destroy(https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate)` | `void` Releases the provided `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` object. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_getcolorcorrection(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate, float *out_color_correction_4)` | `void` Gets the color correction values that are uploaded to the fragment shader. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_getenvironmentalhdrambientsphericalharmonics(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate, float *out_coefficients_27)` | `void` Gets the spherical harmonics coefficients for the ambient illumination based on the inferred Environmental HDR Lighting Estimation. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_getenvironmentalhdrmainlightdirection(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate, float *out_direction_3)` | `void` Returns the direction of the main directional light based on the inferred Environmental HDR Lighting Estimation. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_getenvironmentalhdrmainlightintensity(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate, float *out_intensity_3)` | `void` Returns the intensity of the main directional light based on the inferred Environmental HDR Lighting Estimation. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_getpixelintensity(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate, float *out_pixel_intensity)` | `void` Retrieves the pixel intensity, in gamma color space, of the current camera view. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_getstate(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate, https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimatestate *out_light_estimate_state)` | `void` Retrieves the validity state of an `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate`. |
| `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_gettimestamp(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate *light_estimate, int64_t *out_timestamp_ns)` | `void` Returns the timestamp of the given `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` in nanoseconds. |

## Enumerations

### ArLightEstimateState

```
 ArLightEstimateState
```
Tracks the validity of an `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` object.

| Properties ||
|---|---|
| `AR_LIGHT_ESTIMATE_STATE_NOT_VALID` | The `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` is not valid this frame and should not be used for rendering. |
| `AR_LIGHT_ESTIMATE_STATE_VALID` | The `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` is valid this frame. |

## Typedefs

### ArLightEstimate

```
struct ArLightEstimate_ ArLightEstimate
```
An estimate of the real-world lighting ([value type](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Create with: `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_create`
- Allocate with: `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_getlightestimate`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_destroy`

<br />

## Functions

### ArLightEstimate_acquireEnvironmentalHdrCubemap

```
void ArLightEstimate_acquireEnvironmentalHdrCubemap(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  ArImageCubemap out_textures_6
)
```
Gets the 6 cubemap textures in OpenGL texture format based on the inferred Environmental HDR lighting.


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `light_estimate` | The ArLightEstimate. | | `out_textures_6` | The fixed size array for 6 cubemap textures. `https://developers.google.com/ar/reference/c/group/ar-image#arimagecubemap` type has been created to facilitate representing the array of `https://developers.google.com/ar/reference/c/group/ar-image#arimage` pointers. out_textures_6 contains 6 images in `AIMAGE_FORMAT_RGBA_FP16` format for the HDR cubemap. The memory layout for the image data is identical to `GL_RGBA16F`. The pixel values are in linear color space. The order of the images corresponds to the cubemap order as follows: out_textures_6\[0\]: GL_TEXTURE_CUBE_MAP_POSITIVE_X out_textures_6\[1\]: GL_TEXTURE_CUBE_MAP_NEGATIVE_X out_textures_6\[2\]: GL_TEXTURE_CUBE_MAP_POSITIVE_Y out_textures_6\[3\]: GL_TEXTURE_CUBE_MAP_NEGATIVE_Y out_textures_6\[4\]: GL_TEXTURE_CUBE_MAP_POSITIVE_Z out_textures_6\[5\]: GL_TEXTURE_CUBE_MAP_NEGATIVE_Z If `https://developers.google.com/ar/reference/c/group/ar-config#ar_light_estimation_mode_environmental_hdr` mode is not set, all textures will be assigned with zero pixel values. All 6 acquired images must be released with `https://developers.google.com/ar/reference/c/group/ar-image#arimage_release` once they are no longer needed. | |

### ArLightEstimate_create

```
void ArLightEstimate_create(
  const ArSession *session,
  ArLightEstimate **out_light_estimate
)
```
Allocates an `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` object.

### ArLightEstimate_destroy

```
void ArLightEstimate_destroy(
  ArLightEstimate *light_estimate
)
```
Releases the provided `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` object.

### ArLightEstimate_getColorCorrection

```
void ArLightEstimate_getColorCorrection(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  float *out_color_correction_4
)
```
Gets the color correction values that are uploaded to the fragment shader.

Use the RGB scale factors (components 0-2) to match the color of the light in the scene. Use the pixel intensity (component 3) to match the intensity of the light in the scene. If `https://developers.google.com/ar/reference/c/group/ar-config#ar_light_estimation_mode_ambient_intensity` mode is not set, returns all zeros.

`out_color_correction_4` components are:

- `[0]` Red channel scale factor. This value is larger or equal to zero.
- `[1]` Green channel scale factor. This value is always 1.0 as the green channel is the reference baseline.
- `[2]` Blue channel scale factor. This value is larger or equal to zero.
- `[3]` Pixel intensity. This is the same value as the one return from `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_getpixelintensity`.

<br />

The RGB scale factors can be used independently from the pixel intensity value. They are put together for the convenience of only having to upload one float4 to the fragment shader.

The RGB scale factors are not intended to brighten nor dim the scene. They are only to shift the color of the virtual object towards the color of the light; not intensity of the light. The pixel intensity is used to match the intensity of the light in the scene.

Color correction values are reported in gamma color space. If rendering in gamma color space, multiply them component-wise against the final calculated color after rendering. If rendering in linear space, first convert the values to linear space by rising to the power 2.2. Then multiply component-wise against the final calculated color after rendering.

### ArLightEstimate_getEnvironmentalHdrAmbientSphericalHarmonics

```
void ArLightEstimate_getEnvironmentalHdrAmbientSphericalHarmonics(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  float *out_coefficients_27
)
```
Gets the spherical harmonics coefficients for the ambient illumination based on the inferred Environmental HDR Lighting Estimation.


| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `light_estimate` | The ArLightEstimate. | | `out_coefficients_27` | The output spherical harmonics coefficients for the ambient illumination. This array contains 9 sets of per-channel coefficients, or a total of 27 values of 32-bit floating point type. The coefficients are stored in a channel-major fashion e.g. \[r0, g0, b0, r1, g1, b1, ... , r8, g8, b8\]. If `https://developers.google.com/ar/reference/c/group/ar-config#ar_light_estimation_mode_environmental_hdr` mode is not set, returns zero for all 27 coefficients. | |

### ArLightEstimate_getEnvironmentalHdrMainLightDirection

```
void ArLightEstimate_getEnvironmentalHdrMainLightDirection(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  float *out_direction_3
)
```
Returns the direction of the main directional light based on the inferred Environmental HDR Lighting Estimation.

If `https://developers.google.com/ar/reference/c/group/ar-config#ar_light_estimation_mode_environmental_hdr` mode is not set, returns \[0.0, 1.0, 0.0\], representing a light shining straight down from above.

| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `light_estimate` | The ArLightEstimate. | | `out_direction_3` | Output lighting direction. This array stores the normalized output lighting direction as 3 floats \[x, y, z\]. | |

### ArLightEstimate_getEnvironmentalHdrMainLightIntensity

```
void ArLightEstimate_getEnvironmentalHdrMainLightIntensity(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  float *out_intensity_3
)
```
Returns the intensity of the main directional light based on the inferred Environmental HDR Lighting Estimation.

All return values are larger or equal to zero. If `https://developers.google.com/ar/reference/c/group/ar-config#ar_light_estimation_mode_environmental_hdr` mode is not set, returns zero for all elements of the array.

| Details ||
|---|---|
| Parameters | |---|---| | `session` | The ARCore session. | | `light_estimate` | The ArLightEstimate. | | `out_intensity_3` | Output lighting intensity. This array stores the output lighting intensity as 3 floats \[r, g, b\]. | |

### ArLightEstimate_getPixelIntensity

```
void ArLightEstimate_getPixelIntensity(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  float *out_pixel_intensity
)
```
Retrieves the pixel intensity, in gamma color space, of the current camera view.

Values are in the range \[0.0, 1.0\], with zero being black and one being white. If `https://developers.google.com/ar/reference/c/group/ar-config#ar_light_estimation_mode_ambient_intensity` mode is not set, returns zero.

If rendering in gamma color space, divide this value by 0.466, which is middle gray in gamma color space, and multiply against the final calculated color after rendering. If rendering in linear space, first convert this value to linear space by rising to the power 2.2. Normalize the result by dividing it by 0.18 which is middle gray in linear space. Then multiply by the final calculated color after rendering.

### ArLightEstimate_getState

```
void ArLightEstimate_getState(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  ArLightEstimateState *out_light_estimate_state
)
```
Retrieves the validity state of an `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate`.

If the resulting value of `*out_light_estimate_state` is not `https://developers.google.com/ar/reference/c/group/ar-light-estimate#ar_light_estimate_state_valid`, the estimate should not be used for rendering.

### ArLightEstimate_getTimestamp

```
void ArLightEstimate_getTimestamp(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  int64_t *out_timestamp_ns
)
```
Returns the timestamp of the given `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate` in nanoseconds.

ARCore returns a different timestamp when the underlying light estimate has changed. Conversely, the same timestamp is returned if the light estimate has not changed.

This timestamp uses the same time base as `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_gettimestamp`.