Doc: Add best practice section for shader codeqds/v4.7

Based mainly on https://intranet.qt.io/display/QTPO/Approaches+to+coding

Task-number: QDS-14525
Change-Id: I587c6e8fe450618a7ac9950e9e6fdb7cf7c185aa
Reviewed-by: Ali Kianian <[email protected]>
Reviewed-by: Miikka Heikkinen <[email protected]>
Reviewed-by: Johanna Vanhatapio <[email protected]>

3 files changed, 154 insertions, 0 deletions

diff --git a/doc/qtdesignstudio/images/timeRunning_property.webp b/doc/qtdesignstudio/images/timeRunning_property.webp
new file mode 100644
index 00000000000..92cdf33101e
--- /dev/null
+++ b/doc/qtdesignstudio/images/timeRunning_property.webp
diff --git a/doc/qtdesignstudio/src/best practices/best-practices-shader-code.qdoc b/doc/qtdesignstudio/src/best practices/best-practices-shader-code.qdoc
new file mode 100644
index 00000000000..abbc5691bb3
--- /dev/null
+++ b/doc/qtdesignstudio/src/best practices/best-practices-shader-code.qdoc
@@ -0,0 +1,153 @@
+// Copyright (C) 2025 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page best-practices-shader-code.html
+
+    \title Working with shader code in Effect Composer
+
+    This page contains tips, tricks, and best practices for working with shader code in the
+    \uicontrol {Effect Composer} view.
+
+    To get started with the the \uicontrol {Effect Composer} view, see \l{Effect Composer}.
+
+    \section1 Shader code structure
+
+    The shader code structure for shaders of individual nodes in \QDS is as follows:
+    \list
+      \li The \c main function content should be listed below the \c @main tag.
+      \li Other functions should be listed above the \c @main tag.
+    \endlist
+
+    \note The main shader code structure is different from the code structure of indivudal nodes.
+    The main shader has a \c{@nodes} tag instead of a \c{@main} tag to indicate where the
+    node specific main function content goes.
+
+    \section2 Example shader code
+
+    In this example, you can see a comparison of shader code that works in
+    \l{http:www.shadertoy.com}{ShaderToy} and shader code in \QDS:
+
+    Shadertoy
+    \code
+      vec3 waveEffect(vec2 uv, float time) {
+        float wave = sin(uv.x * 10.0 + time) * 0.1;
+        return vec3(uv.y + wave, uv.y + wave, 1.0);
+      }
+
+      void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+        vec2 uv = fragCoord / iResolution.xy;
+        vec3 color = waveEffect(uv, iTime);
+        fragColor = vec4(color, 1.0);
+      }
+    \endcode
+
+    \QDS
+    \code
+      vec3 waveEffect(vec2 uv, float time) {
+        float wave = sin(uv.x * 10.0 + time) * 0.1;
+        return vec3(uv.y + wave, uv.y + wave, 1.0);
+      }
+
+      @main
+      {
+        vec2 uv = fragCoord / iResolution.xy;
+        vec3 color = waveEffect(uv, iTime);
+        fragColor = vec4(color, 1.0);
+      }
+    \endcode
+
+    \section1 Built-in uniforms
+
+    In \QDS, you can use uniforms for shaders you build and also use custom shaders.
+
+    \section2 Inputs and outputs
+
+    \table
+      \header
+          \li Type
+          \li Name
+          \li Description
+      \row
+          \li vec4
+          \li fragColor
+          \li Fragment shader's output for the color. The format is RGBA and is multiplied
+          by default with the item opacity (qt_opacity).
+      \row
+          \li vec2
+          \li texCoord
+          \li Normalized position of the fragment (0.0 - 1.0).
+      \row
+          \li vec2
+          \li fragCoord
+          \li Position of the fragment in pixels (0.0 - iResolution.xy).
+      \row
+          \li vec2
+          \li vertCoord
+          \li Position of the vertex in pixels (0.0 - iResolution.xy). Modify this in the vertex
+          shader to move the vertices.
+      \row
+          \li vec3
+          \li iResolution
+          \li Size of the source item or image in pixels. The z parameter is always 1.0.
+      \row
+          \li float
+          \li iTime
+          \li Animated time in seconds.
+      \row
+          \li int
+          \li iFrame
+          \li Animated frame number.
+      \row
+          \li sampler2D
+          \li iSource
+          \li Texture sampler of the source item or image.
+    \endtable
+
+    \section2 External resources
+
+    If you copy shader code from external resources, consider the following:
+
+    \section3 ShaderToy
+
+    ShaderToy is using the same naming as \QDS for uniforms.
+
+    \section3 The Book of Shaders
+
+    If you use shader code from \l{https://thebookofshaders.com/}{The Book of Shaders}, you need
+    to rename the uniforms.
+
+    Example uniforms.
+
+    \table
+      \header
+        \li The Book of Shaders uniforms
+        \li In \QDS, rename to this
+      \row
+        \li \c {uniform vec2 u_resolution;}
+        \li \c {iResolution}
+      \row
+        \li \c {uniform float u_time;}
+        \li \c {iTime}
+    \endtable
+
+    \section1 Controlling animations with iTime
+
+    If you are using \c iTime in your shader code, you can start and sop the animation with the
+    \c timeRunning property in \QDS.
+
+    If you set \c timeRunning to false, you can freeze the effect to a specific point in the
+    elapsed time of the animation by setting a value for the \c animatedTime property.
+
+    You can control these settings either from the \uicontrol Properties view or from code.
+
+    \image timeRunning_property.webp
+
+    \code
+        NorthernLights {
+            id: northernLights
+            animatedTime: 1
+            timeRunning: false
+        }
+    \endcode
+*/
diff --git a/doc/qtdesignstudio/src/best-practices.qdoc b/doc/qtdesignstudio/src/best-practices.qdoc
index 345a055d3f2..aa01a765c27 100644
--- a/doc/qtdesignstudio/src/best-practices.qdoc
+++ b/doc/qtdesignstudio/src/best-practices.qdoc
@@ -12,6 +12,7 @@
 
     \list
       \li \l {Creating the glow and the bloom effects}
+      \li \l {Working with shader code in Effect Composer}
     \endlist
 
     \section1 Performance