Allow any Item to act as a viewport for any of its children

The children that have the ItemObservesViewport flag set will have
transformChanged() called whenever any parent moves, and can use
clipRect() to avoid creating SG nodes that fall outside the viewport.
So now the viewport can be narrower than the whole QQuickWindow; but the
fallback is the window.

It was always unclear why we had both boundingRect() and clipRect(),
returning the same rectangular areas.  Now clipRect() can actually be
used for a rough pre-clipping, to limit the amount of vertex data going
into the scene graph, which can save a lot of memory in some cases.

setClip() sets the ItemIsViewport flag, for the sake of making it easy
to do viewporting without writing C++; but it's well known that
scissoring has a performance impact, so we recommend that users who
are writing C++ anyway can set the flags in C++ rather than in QML.

In case there are nested items with both flags ItemIsViewport and
ItemObservesViewport, calling clipRect() on something inside the
innermost viewport is recursive: we intersect all the viewports,
going up the hierarchy to the window. So it's possible for the
innermost item to be clipped down to a small "iris" where all the
viewports are letting "light" pass through.

[ChangeLog][QtQuick][QQuickItem] QQuickItem::clipRect() now provides
the region visible in the viewport, and can be used to limit SG node
vertices as an optimization in custom items, at the cost of having
updatePaintNode() called more often. See docs about the new
ItemObservesViewport and ItemIsViewport flags.

Fixes: QTBUG-37364
Task-number: QTBUG-60491
Task-number: QTBUG-65741
Task-number: QTBUG-77521
Task-number: QTBUG-90734
Change-Id: I71a26c2dab4e991d7fb0f6679f1aa0c34e7a14ee
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>

1 files changed, 20 insertions, 0 deletions

diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
index faec8df7e4..735efdf8e0 100644
--- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
@@ -692,6 +692,26 @@ with multiple windows.
   like a TextArea, this is fine. One should, however, use clip on
   smaller items with caution as it prevents batching. This includes
   button label, text field or list delegate and table cells.
+  Clipping a Flickable (or item view) can often be avoided by arranging
+  the UI so that opaque items cover areas around the Flickable, and
+  otherwise relying on the window edges to clip everything else.
+
+  Setting Item::clip to \c true also sets the \l QQuickItem::ItemIsViewport
+  flag; child items with the \l QQuickItem::ItemObservesViewport flag may
+  use the viewport for a rough pre-clipping step: e.g. \l Text omits
+  lines of text that are completely outside the viewport. Omitting scene
+  graph nodes or limiting the \l {QSGGeometry::vertexCount()}{vertices}
+  is an optimization, which can be achieved by setting the
+  \l {QQuickItem::flags()}{flags} in C++ rather than setting
+  \l Item::clip in QML.
+
+  When implementing QQuickItem::updatePaintNode() in a custom item,
+  if it can render a lot of details over a large geometric area,
+  you should think about whether it's efficient to limit the graphics
+  to the viewport; if so, you can set the \l ItemObservesViewport flag
+  and read the currently exposed area from QQuickItem::clipRect().
+  One consequence is that updatePaintNode() will be called more often
+  (typically once per frame whenever content is moving in the viewport).
 
   \section2 Vertex Buffers