Configure the API once per session with the appropriate mode
Configure Lighting Estimation once per session for the mode you want to use.
Environmental HDR
// Configure the session's lighting estimation mode for// AR_LIGHT_ESTIMATION_MODE_ENVIRONMENTAL_HDR.ArConfig*config=NULL;ArConfig_create(session,&config);ArSession_getConfig(session,config);ArConfig_setLightEstimationMode(session,config,AR_LIGHT_ESTIMATION_MODE_ENVIRONMENTAL_HDR);ArSession_configure(session,config);ArConfig_destroy(config);
Ambient Intensity
// Configure the session's lighting estimation mode for// AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY.ArConfig*config=NULL;ArConfig_create(session,&config);ArSession_getConfig(session,config);ArConfig_setLightEstimationMode(session,config,AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY);ArSession_configure(session,config);ArConfig_destroy(config);
Disabled
// Disable the session's lighting estimation mode.ArConfig*config=NULL;ArConfig_create(session,&config);ArSession_getConfig(session,config);ArConfig_setLightEstimationMode(session,config,AR_LIGHT_ESTIMATION_MODE_DISABLED);ArSession_configure(session,config);ArConfig_destroy(config);
Use values obtained from Lighting Estimation
To use values obtained from Lighting Estimation, get the light estimate for each frame.
// Get the current frame.ArFrame*ar_frame=NULL;if(ArSession_update(session,ar_frame)!=AR_SUCCESS){LOGE("ArSession_update error");return;}// Get the light estimate for the current frame.ArLightEstimate*ar_light_estimate=NULL;ArLightEstimate_create(session,&ar_light_estimate);ArFrame_getLightEstimate(session,ar_frame,ar_light_estimate);ArLightEstimateStatear_light_estimate_state;ArLightEstimate_getState(session,ar_light_estimate,&ar_light_estimate_state);// Check that the light estimate is valid before proceeding.if(ar_light_estimate_state!=AR_LIGHT_ESTIMATE_STATE_VALID){LOGE("ArLightEstimateState is not valid.");ArLightEstimate_destroy(ar_light_estimate);return;}
Then get the environmental HDR lighting components for the current configuration:
Environmental HDR
// Get intensity and direction of the main directional light from the current// light estimate.floatdirection[3];ArLightEstimate_getEnvironmentalHdrMainLightDirection(session,ar_light_estimate,direction);floatintensity[3];ArLightEstimate_getEnvironmentalHdrMainLightIntensity(session,ar_light_estimate,intensity);// Get ambient lighting as spherical harmonics coefficients.floatambient_spherical_harmonics[27];ArLightEstimate_getEnvironmentalHdrAmbientSphericalHarmonics(session,ar_light_estimate,ambient_spherical_harmonics);// Get HDR environmental lighting as a cubemap in linear color space.ArImageCubemapcubemap_textures;ArLightEstimate_acquireEnvironmentalHdrCubemap(session,ar_light_estimate,cubemap_textures);intwidth=-1;intheight=-1;int32_tformat=-1;for(inti=0;i < 6;++i){ArImage*image_ptr=cubemap_textures[i];// We can access the cubemap texture data through ArImage APIs.ArImage_getWidth(session,image_ptr,&width);ArImage_getHeight(session,image_ptr,&height);ArImage_getFormat(session,image_ptr,&format);// Acquired image must be released with ArImage_release once it is no// longer needed.ArImage_release(image_ptr);}ArLightEstimate_destroy(ar_light_estimate);
Ambient Intensity
// Get the pixel intensity of AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY mode.floatpixel_intensity;ArLightEstimate_getPixelIntensity(session,ar_light_estimate,&pixel_intensity);// Get the pixel color correction of// AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY mode.floatcolor_correction[4];ArLightEstimate_getColorCorrection(session,ar_light_estimate,color_correction);ArLightEstimate_destroy(ar_light_estimate);
Ensuring energy conservation with Environmental HDR APIs
Energy conservation is the principle that light reflected from a surface will
never be more intense than it was before it hit the surface. This rule is
enforced in physically-based rendering, but is usually omitted from legacy
rendering pipelines used in video games and mobile apps.
If you're using a physically-based rendering pipeline with Environmental HDR
light estimation, simply ensure physically-based materials are used in your
virtual objects.
If you aren't using a physically-based pipeline, however, you have a couple of
options:
The most ideal solution for this is to migrate to a physically-based pipeline.
If that isn't possible, however, a good workaround is to multiply the
albedo value from a non-physically-based material by an energy conservation
factor. This can make sure at least the BRDF shading model
can be converted into physically-based. Each BRDF has a different factor --
for example, for a diffuse reflection it is 1/Pi.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-10-31 UTC."],[[["\u003cp\u003eThis guide explains how to use Lighting Estimation in your ARCore apps to enhance realism by incorporating real-world lighting.\u003c/p\u003e\n"],["\u003cp\u003eBefore proceeding, ensure you have a foundational understanding of AR concepts and ARCore session configuration.\u003c/p\u003e\n"],["\u003cp\u003eChoose from three lighting estimation modes: Environmental HDR for detailed lighting information, Ambient Intensity for basic lighting, or Disabled if not needed, configuring it once per session.\u003c/p\u003e\n"],["\u003cp\u003eAccess lighting data by retrieving the light estimate for each frame, then extract relevant components like main light direction, intensity, ambient spherical harmonics, or pixel intensity and color correction depending on the chosen mode.\u003c/p\u003e\n"],["\u003cp\u003eWhen using Environmental HDR, consider energy conservation principles to ensure physically accurate lighting in your virtual objects, either by using a physically-based rendering pipeline or adjusting material properties accordingly.\u003c/p\u003e\n"]]],[],null,["# Realistically light virtual objects in a scene\n\nLearn how to use [Lighting Estimation](/ar/develop/c/light-estimation)\nin your own apps.\n\nPrerequisites\n-------------\n\nMake sure that you understand [fundamental AR concepts](/ar/develop/fundamentals)\nand how to [configure an ARCore session](/ar/develop/c/session-config) before proceeding.\n\nConfigure the API once per session with the appropriate mode\n------------------------------------------------------------\n\nConfigure Lighting Estimation once per session for the mode you want to use. \n\n### Environmental HDR\n\n\n```c\n// Configure the session's lighting estimation mode for\n// AR_LIGHT_ESTIMATION_MODE_ENVIRONMENTAL_HDR.\nArConfig* config = NULL;\nArConfig_create(session, &config);\nArSession_getConfig(session, config);\nArConfig_setLightEstimationMode(session, config,\n AR_LIGHT_ESTIMATION_MODE_ENVIRONMENTAL_HDR);\nArSession_configure(session, config);\nArConfig_destroy(config);\n```\n\n\u003cbr /\u003e\n\n### Ambient Intensity\n\n\n```c\n// Configure the session's lighting estimation mode for\n// AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY.\nArConfig* config = NULL;\nArConfig_create(session, &config);\nArSession_getConfig(session, config);\nArConfig_setLightEstimationMode(session, config,\n AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY);\nArSession_configure(session, config);\nArConfig_destroy(config);\n```\n\n\u003cbr /\u003e\n\n### Disabled\n\n\n```c\n// Disable the session's lighting estimation mode.\nArConfig* config = NULL;\nArConfig_create(session, &config);\nArSession_getConfig(session, config);\nArConfig_setLightEstimationMode(session, config,\n AR_LIGHT_ESTIMATION_MODE_DISABLED);\nArSession_configure(session, config);\nArConfig_destroy(config);\n```\n\n\u003cbr /\u003e\n\nUse values obtained from Lighting Estimation\n--------------------------------------------\n\nTo use values obtained from Lighting Estimation, get the light estimate for each frame. \n\n```c\n// Get the current frame.\nArFrame* ar_frame = NULL;\nif (ArSession_update(session, ar_frame) != AR_SUCCESS) {\n LOGE(\"ArSession_update error\");\n return;\n}\n\n// Get the light estimate for the current frame.\nArLightEstimate* ar_light_estimate = NULL;\nArLightEstimate_create(session, &ar_light_estimate);\nArFrame_getLightEstimate(session, ar_frame, ar_light_estimate);\n\nArLightEstimateState ar_light_estimate_state;\nArLightEstimate_getState(session, ar_light_estimate,\n &ar_light_estimate_state);\n\n// Check that the light estimate is valid before proceeding.\nif (ar_light_estimate_state != AR_LIGHT_ESTIMATE_STATE_VALID) {\n LOGE(\"ArLightEstimateState is not valid.\");\n ArLightEstimate_destroy(ar_light_estimate);\n return;\n}\n```\n\nThen get the environmental HDR lighting components for the current configuration: \n\n### Environmental HDR\n\n\n```c\n// Get intensity and direction of the main directional light from the current\n// light estimate.\nfloat direction[3];\nArLightEstimate_getEnvironmentalHdrMainLightDirection(\n session, ar_light_estimate, direction);\n\nfloat intensity[3];\nArLightEstimate_getEnvironmentalHdrMainLightIntensity(\n session, ar_light_estimate, intensity);\n\n// Get ambient lighting as spherical harmonics coefficients.\nfloat ambient_spherical_harmonics[27];\nArLightEstimate_getEnvironmentalHdrAmbientSphericalHarmonics(\n session, ar_light_estimate, ambient_spherical_harmonics);\n\n// Get HDR environmental lighting as a cubemap in linear color space.\nArImageCubemap cubemap_textures;\nArLightEstimate_acquireEnvironmentalHdrCubemap(session, ar_light_estimate,\n cubemap_textures);\nint width = -1;\nint height = -1;\nint32_t format = -1;\nfor (int i = 0; i \u003c 6; ++i) {\n ArImage* image_ptr = cubemap_textures[i];\n // We can access the cubemap texture data through ArImage APIs.\n ArImage_getWidth(session, image_ptr, &width);\n ArImage_getHeight(session, image_ptr, &height);\n ArImage_getFormat(session, image_ptr, &format);\n // Acquired image must be released with ArImage_release once it is no\n // longer needed.\n ArImage_release(image_ptr);\n}\nArLightEstimate_destroy(ar_light_estimate);\n```\n\n\u003cbr /\u003e\n\n### Ambient Intensity\n\n\n```c\n// Get the pixel intensity of AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY mode.\nfloat pixel_intensity;\nArLightEstimate_getPixelIntensity(session, ar_light_estimate,\n &pixel_intensity);\n\n// Get the pixel color correction of\n// AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY mode.\nfloat color_correction[4];\nArLightEstimate_getColorCorrection(session, ar_light_estimate,\n color_correction);\nArLightEstimate_destroy(ar_light_estimate);\n```\n\n\u003cbr /\u003e\n\nEnsuring *energy conservation* with Environmental HDR APIs\n----------------------------------------------------------\n\n*Energy conservation* is the principle that light reflected from a surface will\nnever be more intense than it was before it hit the surface. This rule is\nenforced in physically-based rendering, but is usually omitted from legacy\nrendering pipelines used in video games and mobile apps.\n\nIf you're using a physically-based rendering pipeline with Environmental HDR\nlight estimation, simply ensure physically-based materials are used in your\nvirtual objects.\n\nIf you aren't using a physically-based pipeline, however, you have a couple of\noptions:\n\n- The most ideal solution for this is to migrate to a physically-based pipeline.\n\n- If that isn't possible, however, a good workaround is to multiply the\n albedo value from a non-physically-based material by an energy conservation\n factor. This can make sure at least the [BRDF shading model](https://en.wikipedia.org/wiki/Bidirectional_reflectance_distribution_function)\n can be converted into physically-based. Each BRDF has a different factor --\n for example, for a diffuse reflection it is 1/Pi."]]