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 <laszlo.agocs@qt.io>

10 files changed, 190 insertions, 1 deletions

diff --git a/examples/quick/CMakeLists.txt b/examples/quick/CMakeLists.txt
index 7194f13ac9..d9cdeb617f 100644
--- a/examples/quick/CMakeLists.txt
+++ b/examples/quick/CMakeLists.txt
@@ -29,6 +29,7 @@ qt_internal_add_example(window)
 add_subdirectory(particles)
 qt_internal_add_example(delegatechooser)
 qt_internal_add_example(shapes)
+qt_internal_add_example(itemvariablerefreshrate)
 if(QT_FEATURE_opengl OR QT_FEATURE_opengles2 OR QT_FEATURE_opengles3)
     add_subdirectory(rendercontrol)
 endif()
diff --git a/examples/quick/itemvariablerefreshrate/CMakeLists.txt b/examples/quick/itemvariablerefreshrate/CMakeLists.txt
new file mode 100644
index 0000000000..b8cab61909
--- /dev/null
+++ b/examples/quick/itemvariablerefreshrate/CMakeLists.txt
@@ -0,0 +1,48 @@
+# Copyright (C) 2022 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.16)
+project(itemvariablerefreshrate LANGUAGES CXX)
+
+set(CMAKE_AUTOMOC ON)
+
+if(NOT DEFINED INSTALL_EXAMPLESDIR)
+    set(INSTALL_EXAMPLESDIR "examples")
+endif()
+
+set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/quick/itemvariablerefreshrate")
+
+find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Quick)
+
+qt_add_executable(itemvariablerefreshrateexample
+    main.cpp
+)
+
+set_target_properties(itemvariablerefreshrateexample PROPERTIES
+    MACOSX_BUNDLE TRUE
+    WIN32_EXECUTABLE TRUE
+)
+
+
+target_link_libraries(itemvariablerefreshrateexample PUBLIC
+    Qt::Core
+    Qt::Gui
+    Qt::Qml
+    Qt::Quick
+)
+
+qt_add_qml_module(itemvariablerefreshrateexample
+    URI itemvariablerefreshrate
+    VERSION 1.0
+    AUTO_RESOURCE_PREFIX
+    QML_FILES
+        "itemvariablerefreshrate.qml"
+    RESOURCES
+        "content/qt_logo.png"
+)
+
+install(TARGETS itemvariablerefreshrateexample
+    RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
+    BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
+    LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
+)
diff --git a/examples/quick/itemvariablerefreshrate/content/qt_logo.png b/examples/quick/itemvariablerefreshrate/content/qt_logo.png
new file mode 100644
index 0000000000..30c621c9c6
--- /dev/null
+++ b/examples/quick/itemvariablerefreshrate/content/qt_logo.png
diff --git a/examples/quick/itemvariablerefreshrate/doc/images/qml-itemvariablerefreshrate-example.png b/examples/quick/itemvariablerefreshrate/doc/images/qml-itemvariablerefreshrate-example.png
new file mode 100644
index 0000000000..592baa3a4a
--- /dev/null
+++ b/examples/quick/itemvariablerefreshrate/doc/images/qml-itemvariablerefreshrate-example.png
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.
+*/
diff --git a/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.pro b/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.pro
new file mode 100644
index 0000000000..7981d2492f
--- /dev/null
+++ b/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.pro
@@ -0,0 +1,8 @@
+TEMPLATE = app
+
+QT += quick qml
+SOURCES += main.cpp
+RESOURCES += itemvariablerefreshrate.qrc
+
+target.path = $$[QT_INSTALL_EXAMPLES]/quick/itemvariablerefreshrate
+INSTALLS += target
diff --git a/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.qml b/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.qml
new file mode 100644
index 0000000000..2ef0cb4326
--- /dev/null
+++ b/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.qml
@@ -0,0 +1,85 @@
+// Copyright (C) 2021 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+import QtQuick
+import QtQuick.Controls
+
+Rectangle {
+    id: root
+    width: 640
+    height: 480
+    visible: true
+
+    //! [frameAnimation]
+    FrameAnimation {
+      id: frameAnimation
+      property real fps: smoothFrameTime > 0 ? (1.0 / smoothFrameTime) : 0
+      running: true
+    }
+    //! [frameAnimation]
+
+
+    //! [item]
+    Item {
+        id: qt_logo
+        width: 230
+        height: 230
+        anchors.fill: parent
+        anchors.topMargin: 125
+        layer.enabled: true
+        layer.live: slider.value > 0 && frameAnimation.currentFrame % slider.value == 0
+        //! [item]
+
+        Rectangle {
+            id: rectangle
+            anchors.fill: parent
+            color: "black"
+            Image {
+                anchors.fill: parent
+                source: "content/qt_logo.png"
+            }
+
+            // one second is one full rotation
+            RotationAnimation on rotation {
+                loops: Animation.Infinite
+                duration: 1000
+                from: 0
+                to: 360
+            }
+        }
+    }
+
+    Column {
+        anchors.top: root.top
+        anchors.left: root.left
+        anchors.margins: 10
+
+        Label {
+            text: "FPS: " + frameAnimation.fps.toFixed(0)
+            font.pixelSize: 20
+            font.italic: true
+        }
+
+        Label {
+            text: "Rect rotation (degrees): " + rectangle.rotation.toFixed(0)
+            font.pixelSize: 20
+            font.italic: true
+        }
+
+        Row {
+            Label {
+                text: qsTr("Draw every " + slider.value.toFixed(0) + " frame")
+                font.pixelSize: 20
+                font.italic: true
+            }
+
+            Slider {
+                id: slider
+                from: 0
+                value: 1
+                to: 10
+                stepSize: 1
+            }
+        }
+    }
+}
diff --git a/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.qrc b/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.qrc
new file mode 100644
index 0000000000..c50b0da872
--- /dev/null
+++ b/examples/quick/itemvariablerefreshrate/itemvariablerefreshrate.qrc
@@ -0,0 +1,6 @@
+<RCC>
+    <qresource prefix="/qt/qml/itemvariablerefreshrate">
+        <file>itemvariablerefreshrate.qml</file>
+        <file>content/qt_logo.png</file>
+    </qresource>
+</RCC>
diff --git a/examples/quick/itemvariablerefreshrate/main.cpp b/examples/quick/itemvariablerefreshrate/main.cpp
new file mode 100644
index 0000000000..078b9b4358
--- /dev/null
+++ b/examples/quick/itemvariablerefreshrate/main.cpp
@@ -0,0 +1,4 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+#include "../shared/shared.h"
+DECLARATIVE_EXAMPLE_MAIN(itemvariablerefreshrate/itemvariablerefreshrate)
diff --git a/examples/quick/quick.pro b/examples/quick/quick.pro
index df65ea8e17..2003b1c03b 100644
--- a/examples/quick/quick.pro
+++ b/examples/quick/quick.pro
@@ -26,7 +26,8 @@ SUBDIRS =   quick-accessibility \
             window \
             particles \
             delegatechooser \
-            shapes
+            shapes \
+            itemvariablerefreshrate
 
 #OpenGL Support Required
 qtConfig(opengl(es1|es2)?) {