Fix: Allow StateSet to not contain any Qt3D::QRenderState

This offers a way to explicitly request every render states to be disabled.

Also updated the doc to be clear about how render states are defined.

Change-Id: I91af58dd3ede7ffd7fc9cc022c5e007104791151
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

4 files changed, 31 insertions, 6 deletions

diff --git a/src/render/backend/jobs/renderviewjobutils.cpp b/src/render/backend/jobs/renderviewjobutils.cpp
index d16d124a9..50ba5a0ab 100644
--- a/src/render/backend/jobs/renderviewjobutils.cpp
+++ b/src/render/backend/jobs/renderviewjobutils.cpp
@@ -344,9 +344,6 @@ void parametersFromMaterialEffectTechnique(ParameterInfoList *infoList,
 
 RenderStateSet *buildRenderStateSet(const QList<RenderState*> &states, QFrameAllocator *allocator)
 {
-    if (states.isEmpty())
-        return Q_NULLPTR;
-
     RenderStateSet *stateSet = allocator->allocate<RenderStateSet>();
 
     Q_FOREACH (RenderState *renderState, states) {
diff --git a/src/render/backend/renderview.cpp b/src/render/backend/renderview.cpp
index fce61d34f..71108d76a 100644
--- a/src/render/backend/renderview.cpp
+++ b/src/render/backend/renderview.cpp
@@ -420,9 +420,16 @@ void RenderView::buildRenderCommands(RenderEntity *node)
                     command->m_instancesCount = 0;
 
                     // TODO: Build the state set for a render pass only once per-pass. Not once per rendercommand and pass.
-                    command->m_stateSet = buildRenderStateSet(pass->renderStates(), m_allocator);
-                    if (command->m_stateSet != Q_NULLPTR)
+                    command->m_stateSet = Q_NULLPTR;
+                    command->m_changeCost = 0;
+                    // For RenderPass based states we use the globally set RenderState
+                    // if no renderstates are defined as part of the pass. That means:
+                    // RenderPass { renderStates: [] } will use the states defined by
+                    // StateSet in the FrameGraph
+                    if (!pass->renderStates().isEmpty()) {
+                        command->m_stateSet = buildRenderStateSet(pass->renderStates(), m_allocator);
                         command->m_changeCost = m_renderer->defaultRenderState()->changeCost(command->m_stateSet);
+                    }
                     setShaderAndUniforms(command, pass, globalParameter, *(node->worldTransform()));
                     buildSortingKey(command);
                     m_commands.append(command);
diff --git a/src/render/frontend/framegraph-components/qstateset.cpp b/src/render/frontend/framegraph-components/qstateset.cpp
index 166946ec5..11e8d54bc 100644
--- a/src/render/frontend/framegraph-components/qstateset.cpp
+++ b/src/render/frontend/framegraph-components/qstateset.cpp
@@ -57,7 +57,10 @@ QStateSetPrivate::QStateSetPrivate(QStateSet *qq)
  * branch.
  *
  * States set on a Qt3D::QStateSet are set globally, contrary to the per
- * Material states that can be set on a Qt3D::QRenderPass.
+ * Material states that can be set on a Qt3D::QRenderPass. By default an empty
+ * Qt3D::QStateSet will result in all render states being disabled when
+ * executed. Adding a Qt3D::QRenderState state explicitly enables that render
+ * state at runtime.
  *
  * \since 5.5
  *
@@ -89,6 +92,9 @@ void QStateSet::copy(const QNode *ref)
 
 /*!
  * Adds a new Qt3D::QRenderState \a state to the Qt3D::QStateSet instance.
+ *
+ * \note Not setting any Qt3D::QRenderState state on a Qt3D::QStateSet instance
+ * implies all the render states will be disabled at render time.
  */
 void QStateSet::addRenderState(QRenderState *state)
 {
diff --git a/src/render/frontend/qrenderpass.cpp b/src/render/frontend/qrenderpass.cpp
index 3c58b87b1..2aa9683a0 100644
--- a/src/render/frontend/qrenderpass.cpp
+++ b/src/render/frontend/qrenderpass.cpp
@@ -213,6 +213,14 @@ QList<QParameterMapping *> QRenderPass::bindings() const
     return d->m_bindings;
 }
 
+/*!
+ * Adds a Qt3D::QRenderState \a state to the rendering pass. That implies that
+ * when the pass is executed at render time, the globally set render state will
+ * be modifed by the states defined locally by the Qt3D::QRenderPass.
+ *
+ * \note not defining any Qt3D::QRenderState in a pass will result in the pass using
+ * the globally set render state for a given FrameGraph branch execution path.
+ */
 void QRenderPass::addRenderState(QRenderState *state)
 {
     Q_D(QRenderPass);
@@ -232,6 +240,9 @@ void QRenderPass::addRenderState(QRenderState *state)
     }
 }
 
+/*!
+ * Removes \a state from the Qt3D::QRenderPass local render state.
+ */
 void QRenderPass::removeRenderState(QRenderState *state)
 {
     Q_D(QRenderPass);
@@ -244,6 +255,10 @@ void QRenderPass::removeRenderState(QRenderState *state)
     d->m_renderStates.removeOne(state);
 }
 
+/*!
+ * Returns the list of Qt3D::QRenderState state objects making up the render
+ * state of the Qt3D::QRenderPass.
+ */
 QList<QRenderState *> QRenderPass::renderStates() const
 {
     Q_D(const QRenderPass);