Provide more detail in *Light documentation

Change-Id: I8d56836f1f075c7239b262454131062c10058026
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>

4 files changed, 63 insertions, 0 deletions

diff --git a/src/render/lights/qdirectionallight.cpp b/src/render/lights/qdirectionallight.cpp
index 14bdb2c38..9b6e580de 100644
--- a/src/render/lights/qdirectionallight.cpp
+++ b/src/render/lights/qdirectionallight.cpp
@@ -76,6 +76,9 @@ QDirectionalLightPrivate::QDirectionalLightPrivate()
   \since 5.7
   \brief Encapsulate a Directional Light object in a Qt 3D scene.
 
+  A directional light is a light source that behaves similar to sunlight.
+  The light from a directional light hits all objects from the same direction
+  and with the same intensity, regardless of where they are in the scene.
  */
 
 /*!
@@ -86,6 +89,9 @@ QDirectionalLightPrivate::QDirectionalLightPrivate()
     \since 5.7
     \brief Encapsulate a Directional Light object in a Qt 3D scene.
 
+    A directional light is a light source that behaves similar to sunlight.
+    The light from a directional light hits all objects from the same direction
+    and with the same intensity, regardless of where they are in the scene.
 */
 
 /*!
diff --git a/src/render/lights/qenvironmentlight.cpp b/src/render/lights/qenvironmentlight.cpp
index 866905fb6..b3dac56ff 100644
--- a/src/render/lights/qenvironmentlight.cpp
+++ b/src/render/lights/qenvironmentlight.cpp
@@ -53,6 +53,9 @@ namespace Qt3DRender
  * \instantiates Qt3DRender::QEnvironmentLight
  * \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).
  */
 
 QEnvironmentLightPrivate::QEnvironmentLightPrivate()
@@ -97,6 +100,9 @@ Qt3DCore::QNodeCreatedChangeBasePtr QEnvironmentLight::createNodeCreationChange(
     \inmodule Qt3DRender
     \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::QEnvironmentLight(Qt3DCore::QNode *parent)
diff --git a/src/render/lights/qpointlight.cpp b/src/render/lights/qpointlight.cpp
index 28dd265b8..2b042c91d 100644
--- a/src/render/lights/qpointlight.cpp
+++ b/src/render/lights/qpointlight.cpp
@@ -75,6 +75,19 @@ QPointLightPrivate::QPointLightPrivate()
   \since 5.5
     \brief Encapsulate a Point Light object in a Qt 3D scene.
 
+    A point light is a light source that emits light in all directions, from a single point.
+    Conceptually, this is similar to light given off by a standard light bulb.
+
+    A point light uses three attenuation factors to describe how the intensity of the light
+    decreases over distance. These factors are designed to be used together in calcuating total
+    attenuation. For the materials in Qt3D Extras the following formula is used, where distance
+    is the distance from the light to the surface being rendered:
+
+    \code
+    totalAttenuation = 1.0 / (constantAttenuation + (linearAttenuation * distance) + (quadraticAttenuation * distance * distance));
+    \endcode
+
+    Custom materials may choose to interpret these factors differently.
  */
 
 /*!
@@ -84,6 +97,20 @@ QPointLightPrivate::QPointLightPrivate()
     \inqmlmodule Qt3D.Render
     \since 5.5
     \brief Encapsulate a Point Light object in a Qt 3D scene.
+
+    A point light is a light source that emits light in all directions, from a single point.
+    Conceptually, this is similar to light given off by a standard light bulb.
+
+    A point light uses three attenuation factors to describe how the intensity of the light
+    decreases over distance. These factors are designed to be used together in calcuating total
+    attenuation. For the materials in Qt3D Extras the following formula is used, where distance
+    is the distance from the light to the surface being rendered:
+
+    \code
+    totalAttenuation = 1.0 / (constantAttenuation + (linearAttenuation * distance) + (quadraticAttenuation * distance * distance));
+    \endcode
+
+    Custom materials may choose to interpret these factors differently.
 */
 
 /*!
diff --git a/src/render/lights/qspotlight.cpp b/src/render/lights/qspotlight.cpp
index 81c18387b..c4deaf817 100644
--- a/src/render/lights/qspotlight.cpp
+++ b/src/render/lights/qspotlight.cpp
@@ -83,6 +83,18 @@ QSpotLightPrivate::QSpotLightPrivate()
   \since 5.5
   \brief Encapsulate a Spot Light object in a Qt 3D scene.
 
+    A spotlight is a light source that emits a cone of light in a particular direction.
+
+    A spotlight uses three attenuation factors to describe how the intensity of the light
+    decreases over distance. These factors are designed to be used together in calcuating total
+    attenuation. For the materials in Qt3D Extras the following formula is used, where distance
+    is the distance from the light to the surface being rendered:
+
+    \code
+    totalAttenuation = 1.0 / (constantAttenuation + (linearAttenuation * distance) + (quadraticAttenuation * distance * distance));
+    \endcode
+
+    Custom materials may choose to interpret these factors differently.
  */
 
 /*!
@@ -93,6 +105,18 @@ QSpotLightPrivate::QSpotLightPrivate()
     \since 5.5
     \brief Encapsulate a Spot Light object in a Qt 3D scene.
 
+    A spotlight is a light source that emits a cone of light in a particular direction.
+
+    A spotlight uses three attenuation factors to describe how the intensity of the light
+    decreases over distance. These factors are designed to be used together in calcuating total
+    attenuation. For the materials in Qt3D Extras the following formula is used, where distance
+    is the distance from the light to the surface being rendered:
+
+    \code
+    totalAttenuation = 1.0 / (constantAttenuation + (linearAttenuation * distance) + (quadraticAttenuation * distance * distance));
+    \endcode
+
+    Custom materials may choose to interpret these factors differently.
 */
 
 /*!