Vật thể ảo chiếu sáng thực tế trong cảnh
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Tìm hiểu cách sử dụng công cụ Dự kiến ánh sáng
trong ứng dụng của chính bạn.
Điều kiện tiên quyết
Đảm bảo rằng bạn hiểu rõ các khái niệm cơ bản về AR
và cách định cấu hình phiên ARCore trước khi tiếp tục.
Thiết lập tính năng Ước tính ánh sáng một lần cho mỗi phiên cho chế độ bạn muốn sử dụng.
Java
// Configure the session with the Lighting Estimation API in ENVIRONMENTAL_HDR mode.
Config config = session.getConfig();
config.setLightEstimationMode(LightEstimationMode.ENVIRONMENTAL_HDR);
session.configure(config);
// Configure the session with the Lighting Estimation API in AMBIENT_INTENSITY mode.
Config config = session.getConfig();
config.setLightEstimationMode(LightEstimationMode.AMBIENT_INTENSITY);
session.configure(config);
// Configure the session with the Lighting Estimation API turned off.
Config config = session.getConfig();
config.setLightEstimationMode(LightEstimationMode.DISABLED);
session.configure(config);
Kotlin
// Configure the session with the Lighting Estimation API in ENVIRONMENTAL_HDR mode.
Config config = session.config
config.lightEstimationMode = LightEstimationMode.ENVIRONMENTAL_HDR
session.configure(config)
// Configure the session with the Lighting Estimation API in AMBIENT_INTENSITY mode.
Config config = session.config
config.lightEstimationMode = LightEstimationMode.AMBIENT_INTENSITY
session.configure(config)
// Configure the session with the Lighting Estimation API turned off.
Config config = session.config
config.lightEstimationMode = LightEstimationMode.DISABLED
session.configure(config)
Để định cấu hình chế độ ENVIRONMENTAL_HDR
, hãy lấy thông tin ước tính về ánh sáng cho mỗi khung hình,
sau đó nhận các thành phần ánh sáng HDR môi trường mà bạn muốn sử dụng.
Java
void update() {
// Get the current frame.
Frame frame = session.update();
// Get the light estimate for the current frame.
LightEstimate lightEstimate = frame.getLightEstimate();
// Get intensity and direction of the main directional light from the current light estimate.
float[] intensity = lightEstimate.getEnvironmentalHdrMainLightIntensity(); // note - currently only out param.
float[] direction = lightEstimate.getEnvironmentalHdrMainLightDirection();
app.setDirectionalLightValues(intensity, direction); // app-specific code.
// Get ambient lighting as spherical harmonics coefficients.
float[] harmonics = lightEstimate.getEnvironmentalHdrAmbientSphericalHarmonics();
app.setAmbientSphericalHarmonicsLightValues(harmonics); // app-specific code.
// Get HDR environmental lighting as a cubemap in linear color space.
Image[] lightmaps = lightEstimate.acquireEnvironmentalHdrCubeMap();
for (int i = 0; i < lightmaps.length /*should be 6*/; ++i) {
app.uploadToTexture(i, lightmaps[i]); // app-specific code.
}
}
Kotlin
fun update() {
// Get the current frame.
val frame = session.update()
// Get the light estimate for the current frame.
val lightEstimate = frame.lightEstimate
// Get intensity and direction of the main directional light from the current light estimate.
val intensity = lightEstimate.environmentalHdrMainLightIntensity
val direction = lightEstimate.environmentalHdrMainLightDirection
app.setDirectionalLightValues(intensity, direction) // app-specific code.
// Get ambient lighting as spherical harmonics coefficients.
val harmonics = lightEstimate.environmentalHdrAmbientSphericalHarmonics
app.ambientSphericalHarmonicsLightValues = harmonics // app-specific code.
// Get HDR environmental lighting as a cubemap in linear color space.
val lightMaps = lightEstimate.acquireEnvironmentalHdrCubeMap();
for ((index, lightMap) in lightMaps.withIndex()) { // 6 maps total.
app.uploadToTexture(index, lightMap); // app-specific code.
}
}
Nếu bạn định sử dụng thành phần chỉnh màu của AMBIENT_INTENSITY
hãy tránh phân bổ chỉnh màu trên mỗi khung hình bằng cách sử dụng lại phân bổ được chia sẻ.
Java
// Avoid allocation on every frame.
float[] colorCorrection = new float[4];
Kotlin
val colorCorrection = floatArrayOf(0.0f, 0.0f, 0.0f, 0.0f)
Nhận thông tin ước tính về ánh sáng cho mỗi khung hình, sau đó lấy các thành phần cường độ môi trường xung quanh mà bạn muốn sử dụng.
Java
void update() {
// Get the current frame.
Frame frame = session.update();
// Get the light estimate for the current frame.
LightEstimate lightEstimate = frame.getLightEstimate();
// Get the pixel intensity of AMBIENT_INTENSITY mode.
float pixelIntensity = lightEstimate.getPixelIntensity();
// Read the pixel color correction of AMBIENT_INTENSITY mode into colorCorrection.
lightEstimate.getColorCorrection(colorCorrection, 0);
}
Kotlin
fun update() {
// Get the current frame.
val frame = session.update()
// Get the light estimate for the current frame.
val lightEstimate = frame.lightEstimate
// Get the pixel intensity of AMBIENT_INTENSITY mode.
val pixelIntensity = lightEstimate.pixelIntensity
// Read the pixel color correction of AMBIENT_INTENSITY mode into colorCorrection.
lightEstimate.getColorCorrection(colorCorrection, 0)
}
Đảm bảo bảo tồn năng lượng bằng API HDR môi trường
Bảo toàn năng lượng là nguyên tắc mà ánh sáng phản chiếu từ một bề mặt sẽ
mãnh liệt hơn trước khi va chạm. Quy tắc này được thực thi trong quá trình kết xuất dựa trên thực tế, nhưng thường bị bỏ qua trong quy trình kết xuất cũ được dùng trong trò chơi điện tử và ứng dụng di động.
Nếu bạn đang sử dụng quy trình kết xuất hình ảnh dựa trên thực tế với Environmental HDR
ước tính ánh sáng, chỉ cần đảm bảo rằng bạn sử dụng các vật liệu dựa trên vật lý trong
vật thể ảo.
Tuy nhiên, nếu không sử dụng quy trình dựa trên thực tế, bạn có một số lựa chọn:
Giải pháp lý tưởng nhất cho vấn đề này là chuyển sang một đường ống thực tế.
Tuy nhiên, nếu không thể thực hiện được cách đó, giải pháp hay là tăng gấp đôi
giá trị suất phản chiếu từ một vật liệu phi vật lý bằng cách bảo toàn năng lượng
. Điều này đảm bảo ít nhất mô hình tô bóng BRDF
có thể chuyển hoá thành cơ thể. Mỗi BRDF có một yếu tố khác nhau --
ví dụ: đối với phản xạ khuếch tán, giá trị này là 1/Pi.
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-07-26 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-07-26 UTC."],[[["\u003cp\u003eThe Lighting Estimation API in ARCore lets you illuminate virtual objects with realistic lighting based on the real-world environment, enhancing their integration into the scene.\u003c/p\u003e\n"],["\u003cp\u003eBefore using the API, ensure familiarity with fundamental AR concepts and session configuration.\u003c/p\u003e\n"],["\u003cp\u003eChoose between \u003ccode\u003eENVIRONMENTAL_HDR\u003c/code\u003e and \u003ccode\u003eAMBIENT_INTENSITY\u003c/code\u003e modes when configuring lighting estimation, or disable it entirely using \u003ccode\u003eDISABLED\u003c/code\u003e mode.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eENVIRONMENTAL_HDR\u003c/code\u003e mode provides detailed environmental lighting information for advanced rendering, including main directional light, ambient spherical harmonics, and a HDR cubemap.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eAMBIENT_INTENSITY\u003c/code\u003e mode offers a simpler approach by providing pixel intensity and color correction values, suitable for basic lighting adjustments.\u003c/p\u003e\n"]]],["This content explains how to configure and use the Lighting Estimation API in ARCore apps. Key actions include: configuring the session with `ENVIRONMENTAL_HDR`, `AMBIENT_INTENSITY`, or `DISABLED` modes using Java or Kotlin. For `ENVIRONMENTAL_HDR`, retrieve light estimates, including intensity, direction, spherical harmonics, and cubemaps. For `AMBIENT_INTENSITY`, obtain pixel intensity and color correction. Lastly, using physically based material ensures energy conservation in the lighting model.\n"],null,["# Realistically light virtual objects in a scene\n\nLearn how to use [Lighting Estimation](/ar/develop/java/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/java/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### Java\n\n // Configure the session with the Lighting Estimation API in /ar/reference/java/com/google/ar/core/Config.LightEstimationMode#ENVIRONMENTAL_HDR mode.\n Config config = session.getConfig();\n config.setLightEstimationMode(LightEstimationMode.ENVIRONMENTAL_HDR);\n session.configure(config);\n\n // Configure the session with the Lighting Estimation API in /ar/reference/java/com/google/ar/core/Config.LightEstimationMode#AMBIENT_INTENSITY mode.\n Config config = session.getConfig();\n config.setLightEstimationMode(LightEstimationMode.AMBIENT_INTENSITY);\n session.configure(config);\n\n // Configure the session with the Lighting Estimation API turned off.\n Config config = session.getConfig();\n config.setLightEstimationMode(LightEstimationMode.DISABLED);\n session.configure(config);\n\n### Kotlin\n\n // Configure the session with the Lighting Estimation API in /ar/reference/java/com/google/ar/core/Config.LightEstimationMode#ENVIRONMENTAL_HDR mode.\n Config config = session.config\n config.lightEstimationMode = LightEstimationMode.ENVIRONMENTAL_HDR\n session.configure(config)\n\n // Configure the session with the Lighting Estimation API in /ar/reference/java/com/google/ar/core/Config.LightEstimationMode#AMBIENT_INTENSITY mode.\n Config config = session.config\n config.lightEstimationMode = LightEstimationMode.AMBIENT_INTENSITY\n session.configure(config)\n\n // Configure the session with the Lighting Estimation API turned off.\n Config config = session.config\n config.lightEstimationMode = LightEstimationMode.DISABLED\n session.configure(config)\n\nConfigure `ENVIRONMENTAL_HDR` mode\n----------------------------------\n\nTo configure [ENVIRONMENTAL_HDR](/ar/reference/java/com/google/ar/core/Config.LightEstimationMode#ENVIRONMENTAL_HDR) mode, get the light estimate for each frame,\nthen get the environmental HDR lighting components you want to use. \n\n### Java\n\n void update() {\n // Get the current frame.\n Frame frame = session.update();\n\n // Get the light estimate for the current frame.\n LightEstimate lightEstimate = frame.getLightEstimate();\n\n // Get intensity and direction of the main directional light from the current light estimate.\n float[] intensity = lightEstimate.getEnvironmentalHdrMainLightIntensity(); // note - currently only out param.\n float[] direction = lightEstimate.getEnvironmentalHdrMainLightDirection();\n app.setDirectionalLightValues(intensity, direction); // app-specific code.\n\n // Get ambient lighting as spherical harmonics coefficients.\n float[] harmonics = lightEstimate.getEnvironmentalHdrAmbientSphericalHarmonics();\n app.setAmbientSphericalHarmonicsLightValues(harmonics); // app-specific code.\n\n // Get HDR environmental lighting as a cubemap in linear color space.\n Image[] lightmaps = lightEstimate.acquireEnvironmentalHdrCubeMap();\n for (int i = 0; i \u003c lightmaps.length /*should be 6*/; ++i) {\n app.uploadToTexture(i, lightmaps[i]); // app-specific code.\n }\n }\n\n### Kotlin\n\n fun update() {\n // Get the current frame.\n val frame = session.update()\n\n // Get the light estimate for the current frame.\n val lightEstimate = frame.lightEstimate\n\n // Get intensity and direction of the main directional light from the current light estimate.\n val intensity = lightEstimate.environmentalHdrMainLightIntensity\n val direction = lightEstimate.environmentalHdrMainLightDirection\n app.setDirectionalLightValues(intensity, direction) // app-specific code.\n\n // Get ambient lighting as spherical harmonics coefficients.\n val harmonics = lightEstimate.environmentalHdrAmbientSphericalHarmonics\n app.ambientSphericalHarmonicsLightValues = harmonics // app-specific code.\n\n // Get HDR environmental lighting as a cubemap in linear color space.\n val lightMaps = lightEstimate.acquireEnvironmentalHdrCubeMap();\n for ((index, lightMap) in lightMaps.withIndex()) { // 6 maps total.\n app.uploadToTexture(index, lightMap); // app-specific code.\n }\n }\n\nConfigure `AMBIENT_INTENSITY` mode\n----------------------------------\n\nIf you're planning to use the color correction component of [AMBIENT_INTENSITY](/ar/reference/java/com/google/ar/core/Config.LightEstimationMode#AMBIENT_INTENSITY)\nmode, first avoid allocation of color correction on every frame by reusing a shared allocation. \n\n### Java\n\n // Avoid allocation on every frame.\n float[] colorCorrection = new float[4];\n\n### Kotlin\n\n val colorCorrection = floatArrayOf(0.0f, 0.0f, 0.0f, 0.0f)\n\nGet the light estimate for each frame, and then get ambient intensity components\nyou want to use. \n\n### Java\n\n void update() {\n // Get the current frame.\n Frame frame = session.update();\n\n // Get the light estimate for the current frame.\n LightEstimate lightEstimate = frame.getLightEstimate();\n\n // Get the pixel intensity of AMBIENT_INTENSITY mode.\n float pixelIntensity = lightEstimate.getPixelIntensity();\n\n // Read the pixel color correction of AMBIENT_INTENSITY mode into colorCorrection.\n lightEstimate.getColorCorrection(colorCorrection, 0);\n }\n\n### Kotlin\n\n fun update() {\n // Get the current frame.\n val frame = session.update()\n\n // Get the light estimate for the current frame.\n val lightEstimate = frame.lightEstimate\n\n // Get the pixel intensity of AMBIENT_INTENSITY mode.\n val pixelIntensity = lightEstimate.pixelIntensity\n\n // Read the pixel color correction of AMBIENT_INTENSITY mode into colorCorrection.\n lightEstimate.getColorCorrection(colorCorrection, 0)\n }\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."]]