Merge remote-tracking branch 'origin/5.10' into dev

Change-Id: Ib51c8311ce78b2fec62dd0c09cb943a85a7d0b2b

3 files changed, 227 insertions, 7 deletions

diff --git a/src/render/framegraph/qblitframebuffer.cpp b/src/render/framegraph/qblitframebuffer.cpp
index 505bab96c..d5484b719 100644
--- a/src/render/framegraph/qblitframebuffer.cpp
+++ b/src/render/framegraph/qblitframebuffer.cpp
@@ -47,6 +47,99 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DRender {
 
+/*!
+    \class Qt3DRender::QBlitFramebuffer
+    \inmodule Qt3DRender
+    \since 5.10
+    \ingroup framegraph
+    \brief FrameGraph node to transfer a rectangle of pixel values from one
+    region of a render target to another.
+
+    This node inserts a \c glBlitFrameBuffer or an equivalent into the command
+    stream. This provides a more efficient method for copying rectangles
+    between textures or surface backbuffers wrapped by QRenderTarget than
+    drawing textured quads. It also supports scaling with the specified
+    interpolation method.
+
+    \note In practice the QBlitFramebuffer node will often be used in
+    combination with QNoDraw since a blit should not involve issuing draw calls
+    for any entities.
+ */
+
+/*!
+    \qmltype BlitFramebuffer
+    \inqmlmodule Qt3D.Render
+    \instantiates Qt3DRender::QBlitFramebuffer
+    \inherits FrameGraphNode
+    \since 5.10
+    \brief FrameGraph node to transfer a rectangle of pixel values from one
+    region of a render target to another.
+
+    This node inserts a \c glBlitFrameBuffer or an equivalent into the command
+    stream. This provides a more efficient method for copying rectangles
+    between textures or surface backbuffers wrapped by QRenderTarget than
+    drawing textured quads. It also supports scaling with the specified
+    interpolation method.
+
+    \note In practice the BlitFramebuffer node will often be used in
+    combination with NoDraw since a blit should not involve issuing draw calls
+    for any entities.
+*/
+
+/*!
+    \qmlproperty RenderTarget BlitFramebuffer::source
+
+    Specifies the source render target. When not set, the source is assumed to
+    be the default framebuffer (i.e. the backbuffer of the current surface), if
+    there is one.
+
+    \note the source and destination must not refer to the same render target.
+ */
+
+/*!
+    \qmlproperty RenderTarget BlitFramebuffer::destination
+
+    Specifies the destination render target. When not set, the destination is
+    assumed to be the default framebuffer (i.e. the backbuffer of the current
+    surface), if there is one.
+
+    \note the source and destination must not refer to the same render target.
+ */
+
+/*!
+    \qmlproperty Rect BlitFramebuffer::sourceRect
+
+    Specifies the source rectangle. The coordinates are assumed to follow the
+    normal Qt coordinate system, meaning Y runs from top to bottom.
+ */
+
+/*!
+    \qmlproperty Rect BlitFramebuffer::destinationRect
+
+    Specifies the destination rectangle. The coordinates are assumed to follow
+    the normal Qt coordinate system, meaning Y runs from top to bottom.
+ */
+
+/*!
+    \qmlproperty RenderTargetOutput.AttachmentPoint BlitFramebuffer::sourceAttachmentPoint
+
+    Specifies the source attachment point. Defaults to
+    RenderTargetOutput.AttachmentPoint.Color0.
+ */
+
+/*!
+    \qmlproperty RenderTargetOutput.AttachmentPoint BlitFramebuffer::destinationAttachmentPoint
+
+    Specifies the source attachment point. Defaults to
+    RenderTargetOutput.AttachmentPoint.Color0.
+ */
+
+/*!
+    \qmlproperty InterpolationMethod BlitFramebuffer::interpolationMethod
+
+    Specifies the interpolation applied if the image is stretched. Defaults to Linear.
+ */
+
 QBlitFramebufferPrivate::QBlitFramebufferPrivate()
     : QFrameGraphNodePrivate()
     , m_source(nullptr)
@@ -59,82 +152,168 @@ QBlitFramebufferPrivate::QBlitFramebufferPrivate()
 {
 }
 
+/*!
+  Constructs a new QBlitFramebuffer with the given \a parent.
+ */
 QBlitFramebuffer::QBlitFramebuffer(QNode *parent)
     : QFrameGraphNode(*new QBlitFramebufferPrivate, parent)
 {
 
 }
 
+/*!
+  \internal
+ */
 QBlitFramebuffer::QBlitFramebuffer(QBlitFramebufferPrivate &dd, QNode *parent)
     : QFrameGraphNode(dd, parent)
 {
 }
 
+/*!
+  Destructor.
+ */
 QBlitFramebuffer::~QBlitFramebuffer()
 {
 
 }
 
+/*!
+  \return the source render target.
+ */
 QRenderTarget *QBlitFramebuffer::source() const
 {
     Q_D(const QBlitFramebuffer);
     return d->m_source;
 }
 
+/*!
+  \return the destination render target.
+ */
 QRenderTarget *QBlitFramebuffer::destination() const
 {
     Q_D(const QBlitFramebuffer);
     return d->m_destination;
 }
 
+/*!
+  \return the source rectangle.
+ */
 QRectF QBlitFramebuffer::sourceRect() const
 {
     Q_D(const QBlitFramebuffer);
     return d->m_sourceRect;
 }
 
+/*!
+  \return the destination rectangle.
+ */
 QRectF QBlitFramebuffer::destinationRect() const
 {
     Q_D(const QBlitFramebuffer);
     return d->m_destinationRect;
 }
 
+/*!
+  \return the source attachment point.
+ */
 Qt3DRender::QRenderTargetOutput::AttachmentPoint QBlitFramebuffer::sourceAttachmentPoint() const
 {
     Q_D(const QBlitFramebuffer);
     return d->m_sourceAttachmentPoint;
 }
 
+/*!
+  \return the destination attachment point.
+ */
 QRenderTargetOutput::AttachmentPoint QBlitFramebuffer::destinationAttachmentPoint() const
 {
     Q_D(const QBlitFramebuffer);
     return d->m_destinationAttachmentPoint;
 }
 
+/*!
+  \return the interpolation method.
+ */
 QBlitFramebuffer::InterpolationMethod QBlitFramebuffer::interpolationMethod() const
 {
     Q_D(const QBlitFramebuffer);
     return d->m_interpolationMethod;
 }
 
+/*!
+    Sets the source render target. The default value is nullptr, in which
+    case the source is assumed to be be the default framebuffer (i.e. the
+    backbuffer of the current surface), if there is one.
+
+    \note the source and destination must not refer to the same render target.
+
+    \note As with other nodes, \a source gets automatically parented to the
+    QBlitFramebuffer instance when no parent has been set. The lifetime is also
+    tracked, meaning the source reverts to nullptr in case the currently set
+    \a source is destroyed.
+  */
 void QBlitFramebuffer::setSource(QRenderTarget *source)
 {
     Q_D(QBlitFramebuffer);
     if (d->m_source != source) {
+        if (d->m_source) {
+            // Remove bookkeeping connection
+            d->unregisterDestructionHelper(d->m_source);
+        }
+
         d->m_source = source;
+
+        if (d->m_source) {
+            // Ensures proper bookkeeping. Calls us back with nullptr in case the rt gets destroyed.
+            d->registerDestructionHelper(d->m_source, &QBlitFramebuffer::setSource, d->m_source);
+
+            if (!d->m_source->parent())
+                d->m_source->setParent(this);
+        }
+
         emit sourceChanged();
     }
 }
 
+/*!
+    Sets the destination render target. The default value is nullptr, in which
+    case the destination is assumed to be be the default framebuffer (i.e. the
+    backbuffer of the current surface), if there is one.
+
+    \note the source and destination must not refer to the same render target.
+
+    \note As with other nodes, \a destination gets automatically parented to the
+    QBlitFramebuffer instance when no parent has been set. The lifetime is also
+    tracked, meaning the destination reverts to nullptr in case the currently set
+    \a destination is destroyed.
+  */
 void QBlitFramebuffer::setDestination(QRenderTarget *destination)
 {
     Q_D(QBlitFramebuffer);
     if (d->m_destination != destination) {
+        if (d->m_destination) {
+            // Remove bookkeeping connection
+            d->unregisterDestructionHelper(d->m_destination);
+        }
+
         d->m_destination = destination;
+
+        if (d->m_destination) {
+            // Ensures proper bookkeeping. Calls us back with nullptr in case the rt gets destroyed.
+            d->registerDestructionHelper(d->m_destination, &QBlitFramebuffer::setDestination, d->m_destination);
+
+            if (!d->m_destination->parent())
+                d->m_destination->setParent(this);
+        }
+
         emit destinationChanged();
     }
 }
 
+/*!
+    Sets the source rectangle to \a inputRect. The coordinates are assumed to
+    follow the normal Qt coordinate system, meaning Y runs from top to bottom.
+ */
 void QBlitFramebuffer::setSourceRect(const QRectF &inputRect)
 {
     Q_D(QBlitFramebuffer);
@@ -144,6 +323,11 @@ void QBlitFramebuffer::setSourceRect(const QRectF &inputRect)
     }
 }
 
+/*!
+    Sets the destination rectangle to \a inputRect. The coordinates are assumed
+    to follow the normal Qt coordinate system, meaning Y runs from top to
+    bottom.
+ */
 void QBlitFramebuffer::setDestinationRect(const QRectF &outputRect)
 {
     Q_D(QBlitFramebuffer);
@@ -153,6 +337,10 @@ void QBlitFramebuffer::setDestinationRect(const QRectF &outputRect)
     }
 }
 
+/*!
+    Sets the \a sourceAttachmentPoint. Defaults to
+    Qt3DRender::QRenderTargetOutput::AttachmentPoint::Color0.
+ */
 void QBlitFramebuffer::setSourceAttachmentPoint(Qt3DRender::QRenderTargetOutput::AttachmentPoint sourceAttachmentPoint)
 {
     Q_D(QBlitFramebuffer);
@@ -162,6 +350,10 @@ void QBlitFramebuffer::setSourceAttachmentPoint(Qt3DRender::QRenderTargetOutput:
     }
 }
 
+/*!
+    Sets the \a destinationAttachmentPoint. Defaults to
+    Qt3DRender::QRenderTargetOutput::AttachmentPoint::Color0.
+ */
 void QBlitFramebuffer::setDestinationAttachmentPoint(QRenderTargetOutput::AttachmentPoint destinationAttachmentPoint)
 {
     Q_D(QBlitFramebuffer);
@@ -171,6 +363,10 @@ void QBlitFramebuffer::setDestinationAttachmentPoint(QRenderTargetOutput::Attach
     }
 }
 
+/*!
+    Sets the \a interpolationMethod that is applied if the image is stretched.
+    Defaults to Linear.
+  */
 void QBlitFramebuffer::setInterpolationMethod(QBlitFramebuffer::InterpolationMethod interpolationMethod)
 {
     Q_D(QBlitFramebuffer);
@@ -180,6 +376,9 @@ void QBlitFramebuffer::setInterpolationMethod(QBlitFramebuffer::InterpolationMet
     }
 }
 
+/*!
+    \internal
+ */
 Qt3DCore::QNodeCreatedChangeBasePtr QBlitFramebuffer::createNodeCreationChange() const
 {
     auto creationChange = QFrameGraphNodeCreatedChangePtr<QBlitFramebufferData>::create(this);
diff --git a/src/render/framegraph/qrendercapture.cpp b/src/render/framegraph/qrendercapture.cpp
index 66c518506..28bc41b91 100644
--- a/src/render/framegraph/qrendercapture.cpp
+++ b/src/render/framegraph/qrendercapture.cpp
@@ -149,6 +149,15 @@ namespace Qt3DRender {
  */
 
 /*!
+ * \qmlmethod RenderCaptureReply Qt3D.Render::RenderCapture::requestCapture(Rect rect)
+ *
+ * Used to request render capture from a specified \a rect. Only one render capture
+ * result is produced per requestCapture call even if the frame graph has multiple leaf nodes.
+ * The function returns a QRenderCaptureReply object, which receives the captured image
+ * when it is done. The user is responsible for deallocating the returned object.
+ */
+
+/*!
  * \internal
  */
 QRenderCaptureReplyPrivate::QRenderCaptureReplyPrivate()
@@ -311,7 +320,7 @@ QRenderCapture::QRenderCapture(Qt3DCore::QNode *parent)
  * The function returns a QRenderCaptureReply object, which receives the captured image
  * when it is done. The user is responsible for deallocating the returned object.
  */
-QRenderCaptureReply *QRenderCapture::requestCapture(int captureId, const QRect &rect)
+QRenderCaptureReply *QRenderCapture::requestCapture(int captureId)
 {
     Q_D(QRenderCapture);
     QRenderCaptureReply *reply = d->createReply(captureId);
@@ -322,7 +331,7 @@ QRenderCaptureReply *QRenderCapture::requestCapture(int captureId, const QRect &
 
     Qt3DCore::QPropertyUpdatedChangePtr change(new Qt3DCore::QPropertyUpdatedChange(id()));
     change->setPropertyName(QByteArrayLiteral("renderCaptureRequest"));
-    const QRenderCaptureRequest request = { captureId, rect };
+    const QRenderCaptureRequest request = { captureId, QRect() };
     change->setValue(QVariant::fromValue(request));
     d->notifyObservers(change);
 
@@ -330,8 +339,8 @@ QRenderCaptureReply *QRenderCapture::requestCapture(int captureId, const QRect &
 }
 
 /*!
- * Used to request render capture. Only one render capture result is produced per
- * requestCapture call even if the frame graph has multiple leaf nodes.
+ * Used to request render capture from a specified \a rect. Only one render capture result
+ * is produced per requestCapture call even if the frame graph has multiple leaf nodes.
  * The function returns a QRenderCaptureReply object, which receives the captured image
  * when it is done. The user is responsible for deallocating the returned object.
  */
@@ -357,6 +366,17 @@ QRenderCaptureReply *QRenderCapture::requestCapture(const QRect &rect)
 }
 
 /*!
+ * Used to request render capture. Only one render capture result is produced per
+ * requestCapture call even if the frame graph has multiple leaf nodes.
+ * The function returns a QRenderCaptureReply object, which receives the captured image
+ * when it is done. The user is responsible for deallocating the returned object.
+ */
+Qt3DRender::QRenderCaptureReply *QRenderCapture::requestCapture()
+{
+    return requestCapture(QRect());
+}
+
+/*!
  * \internal
  */
 void QRenderCapture::sceneChangeEvent(const Qt3DCore::QSceneChangePtr &change)
diff --git a/src/render/framegraph/qrendercapture.h b/src/render/framegraph/qrendercapture.h
index c0a4d4ab4..80eeabe64 100644
--- a/src/render/framegraph/qrendercapture.h
+++ b/src/render/framegraph/qrendercapture.h
@@ -84,9 +84,10 @@ class QT3DRENDERSHARED_EXPORT QRenderCapture : public QFrameGraphNode
 public:
     explicit QRenderCapture(Qt3DCore::QNode *parent = nullptr);
 
-    Q_INVOKABLE Q_DECL_DEPRECATED_X("Use the overload with no parameter")
-    Qt3DRender::QRenderCaptureReply *requestCapture(int captureId, const QRect &rect = QRect());
-    Q_REVISION(9) Q_INVOKABLE Qt3DRender::QRenderCaptureReply *requestCapture(const QRect &rect = QRect());
+    Q_INVOKABLE Q_DECL_DEPRECATED_X("Use the overload with no id parameter")
+    Qt3DRender::QRenderCaptureReply *requestCapture(int captureId);
+    Q_REVISION(9) Q_INVOKABLE Qt3DRender::QRenderCaptureReply *requestCapture();
+    Q_REVISION(10) Q_INVOKABLE Qt3DRender::QRenderCaptureReply *requestCapture(const QRect &rect);
 
 protected:
     void sceneChangeEvent(const Qt3DCore::QSceneChangePtr &change) override;