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

6 files changed, 109 insertions, 1 deletions

diff --git a/src/extras/defaults/qskyboxentity.cpp b/src/extras/defaults/qskyboxentity.cpp
index 7de552b38..e82a30950 100644
--- a/src/extras/defaults/qskyboxentity.cpp
+++ b/src/extras/defaults/qskyboxentity.cpp
@@ -238,6 +238,30 @@ void QSkyboxEntityPrivate::reloadTexture()
  */
 
 /*!
+ * \qmltype SkyboxEntity
+ * \instantiates Qt3DExtras::QSkyboxEntity
+   \inqmlmodule Qt3D.Extras
+ *
+ * \brief SkyboxEntity is a convenience Entity subclass that can be used to
+ * insert a skybox in a 3D scene.
+ *
+ * By specifying a base name and an extension, SkyboxEntity will take care of
+ * building a TextureCubeMap to be rendered at runtime. The images in the
+ * source directory should match the pattern: \b base name + *
+ * "_posx|_posy|_posz|_negx|_negy|_negz" + extension
+ *
+ * By default the extension defaults to .png.
+ *
+ * Be sure to disable frustum culling in the FrameGraph through which the
+ * skybox rendering happens.
+ *
+ * \note Please note that you shouldn't try to render a skybox with an
+ * orthographic projection.
+ *
+ * \since 5.5
+ */
+
+/*!
  * Constructs a new Qt3DExtras::QSkyboxEntity object with \a parent as parent.
  */
 QSkyboxEntity::QSkyboxEntity(QNode *parent)
@@ -269,6 +293,11 @@ void QSkyboxEntity::setBaseName(const QString &baseName)
     Contains the base name of the Skybox.
 */
 /*!
+    \qmlproperty string QSkyboxEntity::baseName
+
+    Contains the base name of the Skybox.
+*/
+/*!
  * Returns the base name of the Skybox.
  */
 QString QSkyboxEntity::baseName() const
@@ -298,6 +327,15 @@ void QSkyboxEntity::setExtension(const QString &extension)
 
     The default value is: .png
 */
+
+/*!
+    \qmlproperty string QSkyboxEntity::extension
+
+    Contains the extension of the filename for the skybox image, including the
+    leading '.'.
+
+    The default value is: .png
+*/
 /*!
  * Returns the extension
  */
@@ -336,5 +374,12 @@ bool QSkyboxEntity::isGammaCorrectEnabled() const
     \property QSkyboxEntity::gammaCorrect
 
     A boolean indicating whether gamma correction is enabled.
+    \since 5.9
+*/
+/*!
+    \qmlproperty bool QSkyboxEntity::gammaCorrect
+
+    A boolean indicating whether gamma correction is enabled.
+    \since 5.9
 */
 QT_END_NAMESPACE
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.
 */
 
 /*!
diff --git a/src/render/materialsystem/shaderdata.cpp b/src/render/materialsystem/shaderdata.cpp
index de423c3c2..130333898 100644
--- a/src/render/materialsystem/shaderdata.cpp
+++ b/src/render/materialsystem/shaderdata.cpp
@@ -245,7 +245,7 @@ void ShaderData::sceneChangeEvent(const Qt3DCore::QSceneChangePtr &e)
         // Note we aren't notified about nested QShaderData in this call
         // only scalar / vec properties
         m_originalProperties.insert(propertyName, propertyValue);
-        BackendNode::markDirty(AbstractRenderer::AllDirty);
+        BackendNode::markDirty(AbstractRenderer::ParameterDirty);
     }
 
     BackendNode::sceneChangeEvent(e);