LightEstimate

Holds information about the estimated lighting of the real scene.

Summary

Enumerations

ArLightEstimateState{
  AR_LIGHT_ESTIMATE_STATE_NOT_VALID = 0,
  AR_LIGHT_ESTIMATE_STATE_VALID = 1
}
enum
Tracks the validity of a light estimate.

Typedefs

ArLightEstimate typedef
struct ArLightEstimate_
An estimate of the real-world lighting (value type).

Functions

ArLightEstimate_create(const ArSession *session, ArLightEstimate **out_light_estimate)
void
Allocates a light estimate object.
ArLightEstimate_destroy(ArLightEstimate *light_estimate)
void
Releases the provided light estimate object.
ArLightEstimate_getColorCorrection(const ArSession *session, const ArLightEstimate *light_estimate, float *out_color_correction_4)
void
Gets the color correction values that are uploaded to the fragment shader.
ArLightEstimate_getPixelIntensity(const ArSession *session, const ArLightEstimate *light_estimate, float *out_pixel_intensity)
void
Retrieves the pixel intensity, in gamma space, of the current camera view.
ArLightEstimate_getState(const ArSession *session, const ArLightEstimate *light_estimate, ArLightEstimateState *out_light_estimate_state)
void
Retrieves the validity state of a light estimate.

Enumerations

ArLightEstimateState

 ArLightEstimateState

Tracks the validity of a light estimate.

Properties
AR_LIGHT_ESTIMATE_STATE_NOT_VALID

The light estimate is not valid this frame and should not be used for rendering.

AR_LIGHT_ESTIMATE_STATE_VALID

The light estimate is valid this frame.

Typedefs

ArLightEstimate

struct ArLightEstimate_ ArLightEstimate

An estimate of the real-world lighting (value type).

Allocate with ArLightEstimate_create()
Populate with ArFrame_getLightEstimate()
Release with ArLightEstimate_destroy()

Functions

ArLightEstimate_create

void ArLightEstimate_create(
  const ArSession *session,
  ArLightEstimate **out_light_estimate
)

Allocates a light estimate object.

ArLightEstimate_destroy

void ArLightEstimate_destroy(
  ArLightEstimate *light_estimate
)

Releases the provided light estimate 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.

out_color_correction_4 components are:

  • [0] Red channel scale factor.
  • [1] Green channel scale factor.
  • [2] Blue channel scale factor.
  • [3] Pixel intensity. This is the same value as the one return from ArLightEstimate_getPixelIntensity().

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 space. If rendering in gamma space, component-wise multiply them 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 component-wise multiply against the final calculated color after rendering.

ArLightEstimate_getPixelIntensity

void ArLightEstimate_getPixelIntensity(
  const ArSession *session,
  const ArLightEstimate *light_estimate,
  float *out_pixel_intensity
)

Retrieves the pixel intensity, in gamma space, of the current camera view.

Values are in the range (0.0, 1.0), with zero being black and one being white. If rendering in gamma space, divide this value by 0.466, which is middle gray in gamma 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 a light estimate.

If the resulting value of *out_light_estimate_state is not AR_LIGHT_ESTIMATE_STATE_VALID, the estimate should not be used for rendering.

Send feedback about...