Merge remote-tracking branch 'origin/5.7' into 5.8

Conflicts:
	src/input/backend/updateaxisactionjob.cpp
	src/render/renderstates/qalphacoverage.cpp
	src/render/renderstates/qclipplane.cpp
	src/render/renderstates/qdithering.cpp
	src/render/renderstates/qseamlesscubemap.cpp
	src/render/renderstates/qstenciltest.cpp

Change-Id: I5b279d30bbbb06af5e8ee9fc47e9794b78a567f5

4 files changed, 110 insertions, 50 deletions

diff --git a/src/render/framegraph/qdispatchcompute.cpp b/src/render/framegraph/qdispatchcompute.cpp
index abb4d7bdb..ca656c114 100644
--- a/src/render/framegraph/qdispatchcompute.cpp
+++ b/src/render/framegraph/qdispatchcompute.cpp
@@ -44,12 +44,18 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DRender {
 /*!
-  \class Qt3DRender::QDispatchCompute
-  \inmodule Qt3DRender
-  \since 5.7
-  \ingroup framegraph
+    \class Qt3DRender::QDispatchCompute
+    \inmodule Qt3DRender
+    \since 5.7
+    \ingroup framegraph
+    \brief FrameGraph node to issue work for the compute shader on GPU
 
-  \brief Allows a glDispatchCompute call to be issued to do work in a compute shader on the GPU.
+    A Qt3DRender::QDispatchCompute allows work to be issued for the compute shader to
+    run on the GPU. The workGroupX, workGroupY and workGroupZ properties specify the work group
+    sizes for the compute shader invocation. QComputeCommand components need to be added
+    to entities to instruct Qt3D to select the materials and geometry from the entities
+    for the compute invocation. The work group sizes for the shader invocation will be
+    the maximum of the work group sizes specified in QDispatchCompute and QComputeCommand.
 
  */
 
@@ -59,11 +65,33 @@ namespace Qt3DRender {
     \instantiates Qt3DRender::QDispatchCompute
     \inherits FrameGraphNode
     \since 5.7
-    \qmlabstract Allows a glDispatchCompute call to be issued to do work in a compute shader on the GPU.
+    \brief FrameGraph node to issue work for the compute shader on GPU
+
+    A DispatchCompute allows work to be issued for the compute shader to run on the GPU.
+    The workGroupX, workGroupY and workGroupZ properties specify the work group sizes for
+    the compute shader invocation. ComputeCommand components need to be added
+    to entities to instruct Qt3D to select the materials and geometry from the entities
+    for the compute invocation. The work group sizes for the shader invocation will be
+    the maximum of the work group sizes specified in DispatchCompute and ComputeCommand.
 */
 
 /*!
-  The constructor creates an instance with the specified \a parent.
+    \qmlproperty int DispatchCompute::workGroupX
+    Specifies X workgroup size.
+ */
+
+/*!
+    \qmlproperty int DispatchCompute::workGroupY
+    Specifies Y workgroup size.
+ */
+
+/*!
+    \qmlproperty int DispatchCompute::workGroupZ
+    Specifies Z workgroup size.
+ */
+
+/*!
+    The constructor creates an instance with the specified \a parent.
  */
 QDispatchCompute::QDispatchCompute(Qt3DCore::QNode *parent)
     : QFrameGraphNode(*new QDispatchComputePrivate(), parent)
diff --git a/src/render/framegraph/qframegraphnode.cpp b/src/render/framegraph/qframegraphnode.cpp
index c60c859ac..36a9f737a 100644
--- a/src/render/framegraph/qframegraphnode.cpp
+++ b/src/render/framegraph/qframegraphnode.cpp
@@ -56,8 +56,10 @@ QFrameGraphNodePrivate::QFrameGraphNodePrivate()
 
     \brief Base class of all FrameGraph configuration nodes.
 
-    This is an abstract class so it cannot be instanced directly
-    but rather through one of its subclasses.
+    This class is rarely instanced directly since it doesn't provide
+    any frame graph specific behavior, although it can be convenient
+    to use for grouping other nodes together in dynamic frame graphs.
+    The actual behavior comes from the subclasses.
 
     The subclasses are:
     \table
@@ -112,8 +114,10 @@ QFrameGraphNodePrivate::QFrameGraphNodePrivate()
     \since 5.5
     \brief Base class of all FrameGraph configuration nodes.
 
-    This is an abstract class so it cannot be instanced directly
-    but rather through one of its subclasses.
+    This class is rarely instanced directly since it doesn't provide
+    any frame graph specific behavior, although it can be convenient
+    to use for grouping other nodes together in dynamic frame graphs.
+    The actual behavior comes from the subclasses.
 
     The subclasses are:
     \table
diff --git a/src/render/framegraph/qfrustumculling.cpp b/src/render/framegraph/qfrustumculling.cpp
index 5ba96926e..1d95892b3 100644
--- a/src/render/framegraph/qfrustumculling.cpp
+++ b/src/render/framegraph/qfrustumculling.cpp
@@ -43,13 +43,20 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DRender {
 /*!
-  \class Qt3DRender::QFrustumCulling
-  \inmodule Qt3DRender
-  \since 5.7
-  \ingroup framegraph
+    \class Qt3DRender::QFrustumCulling
+    \inmodule Qt3DRender
+    \since 5.7
+    \ingroup framegraph
+    \brief Enable frustum culling for the FrameGraph
+
+    A QFrustumCulling class enables frustum culling of the drawable entities based on
+    the camera view and QGeometry bounds of the entities. If QFrustumCulling is present in
+    the FrameGraph, only the entities whose QGeometry bounds intersect with the camera
+    frustum, i.e. the view of the camera, are drawn. If QFrustumCulling is not present,
+    all drawable entities will be drawn. The camera is selected by a QCameraSelector
+    frame graph node in the current hierarchy. Frustum culling can save a lot of GPU
+    processing time when the rendered scene is complex.
 
-  \brief If present, only tries to draw entities that are in the view of the camera.
-    The camera is selected by a QCameraSelector frame graph node in the current hierarchy.
     \sa QCameraSelector
  */
 
@@ -59,13 +66,21 @@ namespace Qt3DRender {
     \instantiates Qt3DRender::QFrustumCulling
     \inherits FrameGraphNode
     \since 5.7
-    \qmlabstract If present, only tries to draw entities that are in the view of the camera.
-    The camera is selected by a CameraSelector frame graph node in the current hierarchy
+    \brief Enable frustum culling for the FrameGraph
+
+    A FrustumCulling type enables frustum culling of the drawable entities based on
+    the camera view and Geometry bounds of the entities. If FrustumCulling is present in
+    the FrameGraph, only the entities whose Geometry bounds intersect with the camera
+    frustum, i.e. the view of the camera, are drawn. If FrustumCulling is not present,
+    all drawable entities will be drawn. The camera is selected by a CameraSelector
+    frame graph node in the current hierarchy. Frustum culling can save a lot of GPU
+    processing time when the rendered scene is complex.
+
     \sa CameraSelector
 */
 
 /*!
-  The constructor creates an instance with the specified \a parent.
+    The constructor creates an instance with the specified \a parent.
  */
 QFrustumCulling::QFrustumCulling(Qt3DCore::QNode *parent)
     : QFrameGraphNode(parent)
diff --git a/src/render/framegraph/qrendertargetselector.cpp b/src/render/framegraph/qrendertargetselector.cpp
index a413bbf56..f129d6e1e 100644
--- a/src/render/framegraph/qrendertargetselector.cpp
+++ b/src/render/framegraph/qrendertargetselector.cpp
@@ -49,23 +49,38 @@ using namespace Qt3DCore;
 
 namespace Qt3DRender {
 /*!
- * \class Qt3DRender::QRenderTargetSelector
- * \inmodule Qt3DRender
- * \brief Provides a way of specifying a render target
- * \since 5.7
- *
- * \inherits Qt3DRender::QFrameGraphNode
- *
+    \class Qt3DRender::QRenderTargetSelector
+    \inmodule Qt3DRender
+    \since 5.7
+    \brief Provides a way of specifying a render target
+
+    A Qt3DRender::QRenderTargetSelector is used to select active Qt3DRender::QRenderTarget
+    for the FrameGraph. When QRenderTargetSelector is present in the FrameGraph,
+    the rendering is directed into QTexture objects or draw buffers instead of the surface
+    specified in the Qt3DRender::QRenderSurfaceSelector. A render buffer is automatically
+    generated for an attachment point if drawBuffers contain attachment point that any
+    output in the QRenderTarget do not specify. If the drawBuffers is empty,
+    the renderer will default to using all the outputs in QRenderTarget.
  */
 
 /*!
- * \qmltype RenderTargetSelector
- * \inqmlmodule Qt3D.Render
- * \since 5.7
- * \ingroup
- * \instantiates Qt3DRender::QRenderTargetSelector
- * \brief RenderTargetSelector
- *
+    \qmltype RenderTargetSelector
+    \inqmlmodule Qt3D.Render
+    \since 5.7
+    \instantiates Qt3DRender::QRenderTargetSelector
+    \inherits FrameGraphNode
+    \brief Provides a way of specifying a render target
+
+    A RenderTargetSelector is used to select active RenderTarget
+    for the FrameGraph. When RenderTargetSelector is present in the FrameGraph,
+    the rendering is directed into Texture objects or draw buffers instead of the surface
+    specified in the RenderSurfaceSelector.
+ */
+/*!
+    \qmlproperty list<variant> RenderTargetSelector::drawBuffers
+    Holds the list of draw buffers enabled for the RenderTarget.
+
+    \sa Qt3DRender::QRenderTargetOutput::AttachmentPoint
  */
 
 QRenderTargetSelectorPrivate::QRenderTargetSelectorPrivate()
@@ -75,7 +90,7 @@ QRenderTargetSelectorPrivate::QRenderTargetSelectorPrivate()
 }
 
 /*!
- * Constructs QRenderTargetSelector with given \a parent.
+    Constructs QRenderTargetSelector with given \a parent.
  */
 QRenderTargetSelector::QRenderTargetSelector(QNode *parent)
     : QFrameGraphNode(*new QRenderTargetSelectorPrivate, parent)
@@ -88,13 +103,13 @@ QRenderTargetSelector::~QRenderTargetSelector()
 }
 
 /*!
- *  \property QRenderTargetSelector::target
- *  Specifies the target to be rendered
+    \property QRenderTargetSelector::target
+    Holds the current render target
  */
 
-/*! \qmlproperty QWindow Qt3D.Render::RenderTargetSelector::target
- *
- * the target to be rendered
+/*! \qmlproperty RenderTarget Qt3D.Render::RenderTargetSelector::target
+
+    Holds the current render target
  */
 void QRenderTargetSelector::setTarget(QRenderTarget *target)
 {
@@ -124,15 +139,13 @@ QRenderTarget *QRenderTargetSelector::target() const
 }
 
 /*!
- * \internal
- * Sets the draw buffers \a buffers to be used. The draw buffers should be
- * matching the Qt3DRender::QRenderTargetOutput::RenderAttachmentType
- * defined in the attachments of the Qt3DRender::QRenderTarget associated to the
- * Qt3DRender::QRenderTargetSelector instance.
- *
- * \note At render time, if no draw buffer has been specified, the renderer will
- * default to using all the attachments' draw buffers.
- *
+    Sets the draw \a buffers to be used. The draw buffers should be
+    matching the Qt3DRender::QRenderTargetOutput::AttachmentPoint
+    defined in the attachments of the Qt3DRender::QRenderTarget associated to the
+    Qt3DRender::QRenderTargetSelector instance.
+
+    \note At render time, if no draw buffer has been specified, the renderer will
+    default to using all the attachments' draw buffers.
  */
 void QRenderTargetSelector::setOutputs(const QVector<QRenderTargetOutput::AttachmentPoint> &buffers)
 {
@@ -150,7 +163,7 @@ void QRenderTargetSelector::setOutputs(const QVector<QRenderTargetOutput::Attach
 }
 
 /*!
- * Returns the list of draw buffers for the current Qt3DRender::QRenderTargetSelector instance.
+    \return the list of draw buffers for the current Qt3DRender::QRenderTargetSelector instance.
  */
 QVector<QRenderTargetOutput::AttachmentPoint> QRenderTargetSelector::outputs() const
 {