Merge remote-tracking branch 'origin/5.12' into 5.13

Change-Id: I7d7274866129a3c8a3ed3788680a46368120d20d

2 files changed, 51 insertions, 3 deletions

diff --git a/src/render/frontend/qcamera.cpp b/src/render/frontend/qcamera.cpp
index 29703878d..c2df23c6d 100644
--- a/src/render/frontend/qcamera.cpp
+++ b/src/render/frontend/qcamera.cpp
@@ -336,6 +336,18 @@ void QCameraPrivate::updateViewMatrixAndTransform(bool doEmit)
  * Holds the current projection matrix of the camera.
  */
 
+/*!
+ * \qmlproperty real Qt3D.Render::Camera::exposure
+ * Holds the current exposure of the camera.
+ *
+ * The default value is 0.0.
+ *
+ * The MetalRoughMaterial in Qt 3D Extras is currently the only provided
+ * material that makes use of camera exposure. Negative values will cause
+ * the material to be darker, and positive values will cause it to be lighter.
+ *
+ * Custom materials may choose to interpret the value differently.
+ */
 
 /*!
  * \qmlproperty vector3d Qt3D.Render::Camera::position
@@ -469,6 +481,14 @@ void QCameraPrivate::updateViewMatrixAndTransform(bool doEmit)
 /*!
  * \property QCamera::exposure
  * Holds the current exposure of the camera.
+ *
+ * The default value is 0.0.
+ *
+ * The MetalRoughMaterial in Qt 3D Extras is currently the only provided
+ * material that makes use of camera exposure. Negative values will cause
+ * the material to be darker, and positive values will cause it to be lighter.
+ *
+ * Custom materials may choose to interpret the value differently.
  */
 
 /*!
diff --git a/src/render/lights/qenvironmentlight.cpp b/src/render/lights/qenvironmentlight.cpp
index b3dac56ff..86ef04f95 100644
--- a/src/render/lights/qenvironmentlight.cpp
+++ b/src/render/lights/qenvironmentlight.cpp
@@ -55,7 +55,21 @@ namespace Qt3DRender
  * \since 5.9
  *
  * EnvironmentLight uses cubemaps to implement image-based lighting (IBL), a technique
- * often used in conjunction with physically-based rendering (PBR).
+ * often used in conjunction with physically-based rendering (PBR). The cubemaps are
+ * typically expected be based on high dynamic range (HDR) images, with a suitable
+ * OpenGL format (such as RGBA16F) that can handle the increased range of values.
+ *
+ * There are a variety of tools that can be used to produce the cubemaps needed by
+ * EnvironmentLight. Some examples include
+ *
+ * \list
+ * \li \l {https://github.com/dariomanesku/cmftStudio}{cmftStudio}
+ * \li \l {https://github.com/derkreature/IBLBaker}{IBLBaker}
+ * \li \l {https://www.knaldtech.com/lys/}{Lys}
+ * \endlist
+ *
+ * \l {https://hdrihaven.com/hdris/}{HDRI Haven} provides many CC0-licensed HDR images
+ * that can be used as source material for the above tools.
  */
 
 QEnvironmentLightPrivate::QEnvironmentLightPrivate()
@@ -101,8 +115,22 @@ Qt3DCore::QNodeCreatedChangeBasePtr QEnvironmentLight::createNodeCreationChange(
     \brief Encapsulate an environment light object in a Qt 3D scene.
     \since 5.9
 
-    EnvironmentLight uses cubemaps to implement image-based lighting (IBL), a technique
-    often used in conjunction with physically-based rendering (PBR).
+    QEnvironmentLight uses cubemaps to implement image-based lighting (IBL), a technique
+    often used in conjunction with physically-based rendering (PBR). The cubemaps are
+    typically expected be based on high dynamic range (HDR) images, with a suitable
+    OpenGL format (such as RGBA16F) that can handle the increased range of values.
+
+    There are a variety of tools that can be used to produce the cubemaps needed by
+    QEnvironmentLight. Some examples include
+
+    \list
+    \li \l {https://github.com/dariomanesku/cmftStudio}{cmftStudio}
+    \li \l {https://github.com/derkreature/IBLBaker}{IBLBaker}
+    \li \l {https://www.knaldtech.com/lys/}{Lys}
+    \endlist
+
+    \l {https://hdrihaven.com/hdris/}{HDRI Haven} provides many CC0-licensed HDR images
+    that can be used as source material for the above tools.
 */
 
 QEnvironmentLight::QEnvironmentLight(Qt3DCore::QNode *parent)