D3D12: Painter node

Only supports QImage backing.

As a bonus add some notes to the Context2D docs too.

Change-Id: I18457a1f766d2f136c6864ec06fe596668d5e726
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

2 files changed, 35 insertions, 18 deletions

diff --git a/src/quick/items/context2d/qquickcanvasitem.cpp b/src/quick/items/context2d/qquickcanvasitem.cpp
index 6603d8158d..f654261cb2 100644
--- a/src/quick/items/context2d/qquickcanvasitem.cpp
+++ b/src/quick/items/context2d/qquickcanvasitem.cpp
@@ -255,17 +255,18 @@ QQuickCanvasItemPrivate::~QQuickCanvasItemPrivate()
     The Canvas item supports two render targets: \c Canvas.Image and
     \c Canvas.FramebufferObject.
 
-    The \c Canvas.Image render target is a \a QImage object.  This render
-    target supports background thread rendering, allowing complex or long
-    running painting to be executed without blocking the UI.
+    The \c Canvas.Image render target is a \a QImage object. This render target
+    supports background thread rendering, allowing complex or long running
+    painting to be executed without blocking the UI. This is the only render
+    target that is supported by all Qt Quick backends.
 
     The Canvas.FramebufferObject render target utilizes OpenGL hardware
     acceleration rather than rendering into system memory, which in many cases
-    results in faster rendering. Canvas.FramebufferObject relies on the
-    OpenGL extensions \c GL_EXT_framebuffer_multisample and
-    \c GL_EXT_framebuffer_blit for antialiasing. It will also use more
-    graphics memory when rendering strategy is anything other than
-    Canvas.Cooperative.
+    results in faster rendering. Canvas.FramebufferObject relies on the OpenGL
+    extensions \c GL_EXT_framebuffer_multisample and \c GL_EXT_framebuffer_blit
+    for antialiasing. It will also use more graphics memory when rendering
+    strategy is anything other than Canvas.Cooperative. Framebuffer objects may
+    not be available with Qt Quick backends other than OpenGL.
 
     The default render target is Canvas.Image and the default renderStrategy is
     Canvas.Immediate.
@@ -300,7 +301,14 @@ QQuickCanvasItemPrivate::~QQuickCanvasItemPrivate()
     and can be used directly in \l {ShaderEffect}{ShaderEffects} and other
     classes that consume texture providers.
 
-    \sa Context2D
+    \note In general large canvases, frequent updates, and animation should be
+    avoided with the Canvas.Image render target. This is because with
+    accelerated graphics APIs each update will lead to a texture upload. Also,
+    if possible, prefer QQuickPaintedItem and implement drawing in C++ via
+    QPainter instead of the more expensive and likely less performing
+    JavaScript and Context2D approach.
+
+    \sa Context2D QQuickPaintedItem
 */
 
 QQuickCanvasItem::QQuickCanvasItem(QQuickItem *parent)
diff --git a/src/quick/items/qquickpainteditem.cpp b/src/quick/items/qquickpainteditem.cpp
index e4a20b9787..5813b4b115 100644
--- a/src/quick/items/qquickpainteditem.cpp
+++ b/src/quick/items/qquickpainteditem.cpp
@@ -63,13 +63,14 @@ public:
 
     \inmodule QtQuick
 
-    The QQuickPaintedItem makes it possible to use the QPainter API with the QML Scene Graph.
-    It sets up a textured rectangle in the Scene Graph and uses a QPainter to paint
-    onto the texture. The render target can be either a QImage or a QOpenGLFramebufferObject.
-    When the render target is a QImage, QPainter first renders into the image then
-    the content is uploaded to the texture.
-    When a QOpenGLFramebufferObject is used, QPainter paints directly onto the texture.
-    Call update() to trigger a repaint.
+    The QQuickPaintedItem makes it possible to use the QPainter API with the
+    QML Scene Graph. It sets up a textured rectangle in the Scene Graph and
+    uses a QPainter to paint onto the texture. The render target can be either
+    a QImage or, when OpenGL is in use, a QOpenGLFramebufferObject. When the
+    render target is a QImage, QPainter first renders into the image then the
+    content is uploaded to the texture. When a QOpenGLFramebufferObject is
+    used, QPainter paints directly onto the texture. Call update() to trigger a
+    repaint.
 
     To enable QPainter to do anti-aliased rendering, use setAntialiasing().
 
@@ -78,6 +79,10 @@ public:
     public function: paint(), which implements the actual painting. The
     painting will be inside the rectangle spanning from 0,0 to
     width(),height().
+
+    \note It important to understand the performance implications such items
+    can incur. See QQuickPaintedItem::RenderTarget and
+    QQuickPaintedItem::renderTarget.
 */
 
 /*!
@@ -172,8 +177,6 @@ QQuickPaintedItem::~QQuickPaintedItem()
     is processed by the QML Scene Graph when the next frame is rendered. The item will only be
     redrawn if it is visible.
 
-    Note that calling this function will trigger a repaint of the whole scene.
-
     \sa paint()
 */
 void QQuickPaintedItem::update(const QRect &rect)
@@ -499,6 +502,12 @@ void QQuickPaintedItem::setFillColor(const QColor &c)
     the QQuickPaintedItem::FramebufferObject render target if the item gets resized often.
 
     By default, the render target is QQuickPaintedItem::Image.
+
+    \note Some Qt Quick backends may not support all render target options. For
+    example, it is likely that non-OpenGL backends will lack support for
+    QQuickPaintedItem::FramebufferObject and
+    QQuickPaintedItem::InvertedYFramebufferObject. Requesting these will then
+    be ignored.
 */
 QQuickPaintedItem::RenderTarget QQuickPaintedItem::renderTarget() const
 {