1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6\title Using Image-Based Lighting
7\page quick3d-asset-conditioning-ibl
11Qt Quick 3D supports IBL (Image-Based Lighting) to illuminate scenes or individual materials.
13IBL is a lighting technique that allows scenes to be illuminated with images. This is especially
14useful when you want to create realistic lighting and reflections in indoor and outdoor scenes.
16You can use any image file for IBL, but it is recommended to use 360ยบ HDR (High Dynamic Range)
17images. HDR images have a much higher dynamic range than for example JPEG or PNG images. A higher
18dynamic range provides more realistic lighting through a great range of luminance levels from
19very bright to very dark.
21The following example demonstrates the lighting effect on an object using an HDR image vs a single
27 \li Smooth Dielectric material
28 \li Rough Dielectric material
29 \li Smooth Metallic material
30 \li Rough Metallic material
32 \li \b{Single directional light}
33 \li \image IBL-sphere-smooth-directional-light.png
34 \li \image IBL-sphere-rough-directional-light.png
35 \li \image IBL-sphere-metallic-smooth-directional-light.png
36 \li \image IBL-sphere-metallic-rough-directional-light.png
38 \li \b{Image-based light}
39 \li \image IBL-sphere-smooth-environment-light.png
40 \li \image IBL-sphere-rough-environment-light.png
41 \li \image IBL-sphere-metallic-smooth-environment-light.png
42 \li \image IBL-sphere-metallic-rough-environment-light.png
45\section1 Scene Lighting
47To illuminate a \l {SceneEnvironment}{scene} using an image you'll add the image as a \l Texture to
48the \l {SceneEnvironment::lightProbe}{lightProbe} property.
52 source: "maps/OpenfootageNET_garage-1024.hdr"
56Once you have selected an image, IBL is set up for your scene. All models in the scene are
57illuminated by the light probe by default.
59\note You can also combine IBL with any other light source to compliment the lighting effect on an
62Now that you have IBL set up for your scene, let us have a look at the different properties for
63the probe. In many cases the default values provide a satisfying result, but you can tweak the
64following property values depending on the image and desired result:
67 \li \l {SceneEnvironment::probeExposure}{Exposure}
68 The amount of light emitted by the light probe.
69 \li \l {SceneEnvironment::probeHorizon}{Horizon Cut-Off}
70 Increasing the value adds darkness (black) to the bottom half of the environment,
71 forcing the lighting to come predominantly from the top of the image
72 (and removing specific reflections from the lower half).
73 \li \l {SceneEnvironment::probeOrientation}{Orientation}
74 This property when defines the orientation of the light probe.
75 Orientation is defined in terms of euler angles in degrees over the
83 \li Dielectric material
85 \li \e{\b{Default settings}}
86 \li \image IBL-sphere-metallic-smooth-environment-light.png
87 \li \image IBL-sphere-smooth-environment-light.png
90 \li \image IBL-sphere-metallic-smooth-environment-light-exposure.png
91 \li \image IBL-sphere-smooth-environment-light-exposure.png
93 \li \e{\b{Horizon Cut-off}}
94 \li \image IBL-sphere-metallic-smooth-environment-light-horizon.png
95 \li \image IBL-sphere-smooth-environment-light-horizon.png
97 \li \e{\b{Orientation}}
98 \li \image IBL-sphere-metallic-smooth-environment-light-orientation.png
99 \li \image IBL-sphere-smooth-environment-light-orientation.png
102\section1 Material Lighting
104To use image-based lighting only on one material instead of a whole scene, or use a separate light
105probe for a model already illuminated by image-based lighting, set the image as the
106\l {Material::lightProbe}{light probe} for the material.
108Once you have followed the steps above, you have a separate light probe set for the material.
109This light probe overrides the scene light probe if there is one specified.
111\section1 Pre-generating IBL cubemap
113When IBL is used, a cubemap for the IBL image needs to be generated by the
114application. By default this happens during application startup and can be quite
115slow, especially on embedded and mobile devices. It is therefore possible to
116pre-generate this cubemap using \l {Balsam Asset Import Tool}{Balsam}. Simply
117run \l {Balsam Asset Import Tool}{Balsam} with the .hdr file as input and it
118will output a cubemap file with the same name as the input but with a ktx file
119extension. One can then reference this file in the lightProbe property's
120associated \l Texture, and Qt will then load the pregenerated cubemap without
121any costly processing at run time.
123\section2 Manual baking
125As an example, let's assume the application uses a .hdr image for its light
130 environment: SceneEnvironment {
131 backgroundMode: SceneEnvironment.SkyBox
132 lightProbe: Texture {
133 source: "environment.hdr"
135 probeOrientation: Qt.vector3d(0, -90, 0)
141This is fully functional, assuming environment.hdr is available at run
142time. However, loading the .hdr image involves expensive pre-processing. This
143can be avoided by running:
146 balsam environment.hdr
149The result is a new file \c{environment.ktx}. Shipping this instead of the .hdr file
150and changing the Texture source provides significantly faster loading times.
153 lightProbe: Texture {
154 source: "environment.ktx"
158\section2 Build time baking via CMake
160Manually running balsam on assets is not always ideal. Therefore, applications
161are recommended to rely on CMake to automatically perform the same task at
162application build time.
164This is done by using the qt6_add_lightprobe_images CMake function provided by
165the Quick3D component of the Qt6 package:
169 find_package(Qt6 COMPONENTS Quick3D)
171 qt6_add_lightprobe_images(application_target "ibl_assets"
179Replace \c application_target with the appropriate target. Here, there is no
180need to run balsam manually on environment.hdr anymore, and the .hdr file does
181not need to be shipped with the application. Rather, during the build balsam
182will be invoked automatically, and an environment.ktx will be added to the
183application resources at \c{:/ibl/environment.ktx}. The lightProbe's \l Texture
184needs to then reference this file.
187 lightProbe: Texture {
188 source: "qrc:/ibl/environment.ktx"
192\note Setting PREFIX so that the final name in the resource system has a path
193matching the .qml file's location allows using a relative source path instead of
194having to provide an absolute path with the qrc scheme.
196In addition to PREFIX, the keyword BASE is also available. The behavior follows
197that of qt6_add_resources. For example, the following leads to generating
198\c{:/ibl/maps/environment.ktx}:
201 qt6_add_lightprobe_images(application_target "ibl_assets"
207 "../data/shared/maps/environment.hdr"
211Like in qt6_add_shaders, the OUTPUTS keyword is available to allow specifying a
212completely custom name for the file in the resource system. For example, the
213following also generates \c{:/ibl/maps/environment.ktx}:
216 qt6_add_lightprobe_images(application_target "ibl_assets"
220 "../data/shared/maps/environment.hdr"
222 "maps/environment.ktx"
226\note For each entry in the FILES list, there must be a corresponding entry in