Add live property to QQuickItem layer

QQuickItemLayer now has a live property that can be set to determine if
its contents should change whenever the item updates. This enables
variable refresh rate for quick items.

[ChangeLog] Added live property to QQuickItem layer.

Fixes: QTBUG-77343
Change-Id: I8bf7e7af4cfed6deef2253d346bb0b72d0fef66e
Reviewed-by: Laszlo Agocs <[email protected]>

1 files changed, 36 insertions, 0 deletions

diff --git a/examples/quick/itemvariablerefreshrate/doc/src/itemvariablerefreshrate.qdoc b/examples/quick/itemvariablerefreshrate/doc/src/itemvariablerefreshrate.qdoc
new file mode 100644
index 0000000000..5be8cd36eb
--- /dev/null
+++ b/examples/quick/itemvariablerefreshrate/doc/src/itemvariablerefreshrate.qdoc
@@ -0,0 +1,36 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+/*!
+    \title Qt Quick Examples - Item Variable Refresh Rate
+    \example itemvariablerefreshrate
+    \image qml-itemvariablerefreshrate-example.png
+    \brief A Qt Quick example shows how to setup variable refresh rate for
+    specific parts of the UI.
+    \ingroup qtquickexamples
+
+    This example demonstrates using the live property of a \l{Item Layers} to get a
+    variable and independent refresh rate for Quick items. This can provide a significant
+    boost to performance if specific parts of a UI does not need to be re-rendered
+    every frame, but still require internal updates. Drawing parts that are static
+    most of the time or animations that does not have to run smoothly at all times
+    is a waste of resources. This property gives the user control over when the item
+    is drawn.
+
+    \note Using \l{Item Layers} may involve a performance penalty, depending on the size
+    of the layered item subtree, due to using separate render targets (textures),
+    which are then blended together in the main render pass.
+    Application designers should always evaluate the impact to ensure that the benefits
+    of using layers outweigh the potential disadvantages.
+
+    The example uses \l FrameAnimation to control how often the item is rendered.
+    Useful when you only want to e.g. every second frame.
+    Using something like a timer or other mechanics to toggle the flag is also valid.
+    \snippet itemvariablerefreshrate/itemvariablerefreshrate.qml frameAnimation
+    In the above snippet, the fps property is only there for visual demonstration purposes.
+
+    The item requires layer.enabled to be true, and then the item will
+    be rendered depending on the state of layer.live as shown in the below snippet.
+    \snippet itemvariablerefreshrate/itemvariablerefreshrate.qml item
+    Using modulo operator and a slider to set the value, we can dynamically change
+    how often the Qt logo is rendered.
+*/