Realistically light virtual objects in a scene

The Lighting Estimation API provides detailed data that lets you mimic various lighting cues when rendering virtual objects. ARCore supports three light estimation modes:

1. Disabled
2. Ambient Intensity mode
3. Environmental HDR mode

Prerequisites

Make sure that you understand fundamental AR concepts and how to configure an ARCore session before proceeding.

Enable Lighting Estimation

Follow these steps to enable lighting estimation in your app.

1. Set up an AR Foundation project or ARCore Extensions project.
2. In the Hierarchy tab, navigate to XR Session Origin > AR Camera.

1. Under the AR Camera Manager component, select Light Estimation.
2. In the Light Estimation drop-down menu, select the mode(s) you wish to use.

Enable Environmental HDR mode

Environmental HDR mode enables the following light estimation settings:

• Main Light Direction
• Main Light Intensity
• Ambient Spherical Harmonics

This mode is automatically enabled when the following criteria are met:

• Ambient Spherical Harmonics, Main Light Direction, and/or Main Light Intensity are selected in the Light Estimation mode provided by the AR Camera manager
• Environment probes are enabled in an AREnvironmentProbeManager
• A compatible camera configuration is selected

Enable Ambient Intensity mode

Basic light estimation is automatically enabled when Ambient Intensity mode is selected in the ARCameraManager component.

Ambient Intensity mode enables the following light estimation settings:

• Ambient Color
• Ambient Intensity

Use lighting information in your scene

Once you have obtained the correct lighting settings, you can light the virtual objects in your scene as if they were a part of the real world.

The ARCameraManager component can raise a frameReceived event that estimates frames’ lighting conditions when lighting estimation is enabled. Information from frameReceived events are stored in ARCameraFrameEventArgs structs as ARLightEstimationData.

Follow these steps to change a light’s parameters at runtime.

1. Create or modify the existing Directional Light in your scene.

2. Attach a new script to the Directional Light.

   // Sample Lighting Estimation script
   
   Light light;
   void Awake ()
   {
       light = GetComponent<Light>();
   }
   
   void OnEnable()
   {
       if (cameraManager != null)
           cameraManager.frameReceived += FrameChanged;
   }
   
   void OnDisable()
   {
       if (cameraManager != null)
           cameraManager.frameReceived -= FrameChanged;
   }
   
   void FrameChanged(ARCameraFrameEventArgs args)
   {
      // Modify `light` parameters using ARCameraFrameEventArgs.
   }
   

3. Modify this new script to detect changes in lighting. For examples of how to do this, check out Unity’s BasicLightEstimation.cs and HDRLightEstimation.cs scripts.

Use environment probes in your scene

Follow these steps to enable environment probes in your scene.

1. Enable automatic placement in your scene’s ARSessionOrigin.
2. Add an AREnvironmentProbeManager component to the ARSessionOrigin.