Create fire particle tutorial

- Rewrite the obsolete fire particle example to a tutorial and move it to
  the tutorial section
- Add links to particle system tutorials to the particle page
- Small related fixes

Task-number: QDS-6459
Change-Id: If637c9eeabd176af4ee9acdb7f2027e365a6b59a
Reviewed-by: Tanja Remes <tanja.remes@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: <github-actions-qt-creator@cristianadam.eu>

8 files changed, 237 insertions, 140 deletions

diff --git a/doc/qtdesignstudio/examples/doc/FireParticles.qdoc b/doc/qtdesignstudio/examples/doc/FireParticles.qdoc
new file mode 100644
index 0000000000..9d0b489de3
--- /dev/null
+++ b/doc/qtdesignstudio/examples/doc/FireParticles.qdoc
@@ -0,0 +1,227 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Design Studio documentation.
+**
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+/*!
+    \page fire-particle-effect.html
+    \ingroup gstutorials
+    \sa Particles
+
+    \title Particle System: Fire Effect
+    \brief Illustrates how to create a fire effect with the \QDS
+    particle system.
+
+    \image fire-particles.png
+
+    The \e{Fire Effect} tutorial illustrates how you can add a fire effect to
+    your scene using the \QDS particle system.
+
+    In this tutorial, you create a project from the beginning. You can download
+    the completed project from
+    \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/fire-particles}
+    {here}.
+
+    This tutorial requires that you know the basics of \QDS, see
+    \l{Getting Started}.
+
+    \section1 Tutorial Assets
+
+    You need the following assets to complete this tutorial:
+    \list
+      \li \e fire-sprites.png
+      \li \e fire-color-table.png
+    \endlist
+
+    You can download the assets from
+    \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/fire-particles/FireParticles/content/images}
+    {here}.
+
+    \section1 Creating a Fire Effect
+
+    \section2 Creating a Project
+
+    To create a new project:
+
+    \list 1
+      \li Open \QDS.
+      \li On the \uicontrol {Welcome Screen}, select \uicontrol
+      {Create Project}.
+      \li In the \uicontrol Presets section, select \uicontrol General >
+      \uicontrol {3D}.
+      \li In the \uicontrol Details section, set the name to \e FireParticles
+      and select the folder where you want to save the project.
+      \li Select \uicontrol {Create}.
+    \endlist
+
+    Next, remove unwanted default components from the project:
+
+    \list 1
+      \li In \uicontrol {Navigator}, select \e Text and select the \key Delete
+      key.
+      \li In the same way, delete \e {cubeModel}.
+    \endlist
+
+    For a better visual effect, set the background color to black:
+
+    \list
+      \li In \uicontrol {Navigator}, select \e Rectangle and in
+      \uicontrol {Properties}, set \uicontrol {Fill Color} to #000000.
+    \endlist
+
+
+    \section2 Adding a Particle System to Your Scene
+
+    To add a particle system, you first need to import the QtQuick3D.Particles3D
+    module to your project:
+
+    \list 1
+      \li In the \uicontrol Components view, select \inlineimage icons/plus.png
+      .
+      \li Find QtQuick3D.Particles3D, and select it to add it to your project.
+    \endlist
+
+    In this project, you use an animated sprite to simulate a fire. For
+    this, use the Animated Sprite particle system template:
+
+    \list
+      \li From \uicontrol Components >
+      \uicontrol{Qt Quick 3D Particle System Templates} drag an
+      \uicontrol {Animated Sprite} component to \uicontrol{3D Editor}. You can
+      also drag it to \e scene in \uicontrol {Navigator}.
+    \endlist
+
+    \image fire-particles-navigator.png
+
+    You now have the particle system in place. To preview it, select
+    \key Alt + \key{P}. You can also preview the particle system in
+    \uicontrol {3D Editor} by using the \l {Particle Editor} tools.
+
+    \section2 Adding Sprites and Sprite Animations
+
+    First, import the sprite to use for the fire:
+
+    \list 1
+      \li In \uicontrol {Assets}, select \inlineimage icons/plus.png
+      .
+      \li Select \e {fire-sprites.png}.
+    \endlist
+
+    \image fire-particles-assets.png
+
+    Next, add the sprite to the particle system and create the animation:
+
+    \list 1
+      \li From \uicontrol{Assets}, drag \e {fire-sprites.png} to
+      \e animatedTexture in \uicontrol {Navigator}.
+      \li In \uicontrol{Navigator}, select \e{animatedSequence} and in
+      \uicontrol {Properties}, set:
+        \list
+          \li \uicontrol{Frame Count} to 3.
+          There are 3 sprites in \e {fire-sprites.png} so you want to
+          divide the image into 3 different sprites for this animation.
+          \li \uicontrol Interpolate to true. This makes the animation between
+          the sprites smooth.
+          \li \uicontrol{Random Start} to true.
+          This sets the animation for each particle to start from any of the
+          3 sprites, creating some randomness to the effect.
+        \endlist
+    \endlist
+
+    \image fire-particles-sprite-sequence.png
+
+    To add color to the sprites, use a \e{color table}. With a color table, you
+    change the color of a single sprite during its life span. In this
+    project, you use a gradient color table ranging from yellow to dark orange.
+    This results in the sprites being yellow when they are emitted and dark
+    orange at the end of the life span.
+
+    To set the color table:
+    \list 1
+      \li Import \e{fire-color-table.png} to your project.
+      \li From \uicontrol{Components}, drag a \uicontrol Texture to
+      \e animatedSpriteParticle in \uicontrol{Navigator}.
+      \li Rename the texture to \e {fireColorTable}.
+      \li In \uicontrol {Navigator}, select \e {fireColorTable} and  in
+      \uicontrol {Properties}, set \uicontrol Source to
+      \e{fire-color-table.png}.
+      \li In \uicontrol {Navigator}, select \e {animatedSpriteParticle} and:
+        \list
+          \li Ensure that \uicontrol Sprite is set to \e {animatedTexture}.
+          \li Set \uicontrol {Particle Scale} to 5.
+          \li Set \uicontrol {Color Table} to \e{fireColorTable}.
+        \endlist
+    \endlist
+
+    \image fire-particles-sprite-textures.png
+
+    \section2 Adjusting the Particle Emitter
+
+    The next step is to adjust the particle emitter properties:
+
+    \list 1
+      \li In \uicontrol{Navigator}, select \e animatedSpriteEmitter and in
+      \uicontrol {Properties}, set:
+      \list
+        \li \uicontrol {Emit Rate} to 300.
+        \li \uicontrol {Life Span} to 2500.
+        \li \uicontrol {Life Span Variation} to 100.
+        \li \uicontrol {Particle End Scale} to 1,50.
+      \endlist
+      This sets the emitter to emit 300 particles per second. The life span of
+      each particle is ranging from 2.4 to 2.6 seconds. The size of each
+      particle is increasing slightly throughout its life span.
+      \li In \uicontrol{Navigator}, select \e animatedSpriteParticle and in
+      \uicontrol {Properties}, set:
+      \list
+        \li \uicontrol {Blend Mode} to Screen.
+        \li \uicontrol {Max Amount} to 1000.
+        \li \uicontrol {Color Variation} > \uicontrol W to 0,50. This adds
+        randomness to the opacity of the sprites.
+      \endlist
+      \li In \uicontrol{Navigator}, select \e animatedSpriteDirection and in
+      \uicontrol {Properties}, set:
+      \list
+        \li \uicontrol Direction > \uicontrol Y to 20.
+        \li \uicontrol {Direction Variation} > \uicontrol X to 3.
+        \li \uicontrol {Direction Variation} > \uicontrol Y to 10.
+      \endlist
+      This makes the particles go straight up with a small amount of randomness
+      to the direction.
+    \endlist
+
+    \section1 Previewing
+
+    Now, the fire effect is done. Before you preview it, adjust the camera:
+    \list 1
+      \li In \uicontrol {Navigator}, select \e sceneCamera and in
+      \uicontrol {Properties}, set:
+      \list
+        \li \uicontrol {Field of View} to 20.
+        \li \uicontrol {Translation} > \uicontrol Y to 35.
+      \endlist
+    \endlist
+
+    Now, preview the fire effect by selecting \key Alt + \key{P}.
+
+*/
diff --git a/doc/qtdesignstudio/examples/doc/images/fire-particles-assets.png b/doc/qtdesignstudio/examples/doc/images/fire-particles-assets.png
new file mode 100644
index 0000000000..a820fd9819
--- /dev/null
+++ b/doc/qtdesignstudio/examples/doc/images/fire-particles-assets.png
diff --git a/doc/qtdesignstudio/examples/doc/images/fire-particles-navigator.png b/doc/qtdesignstudio/examples/doc/images/fire-particles-navigator.png
new file mode 100644
index 0000000000..759cca9990
--- /dev/null
+++ b/doc/qtdesignstudio/examples/doc/images/fire-particles-navigator.png
diff --git a/doc/qtdesignstudio/examples/doc/images/fire-particles-sprite-sequence.png b/doc/qtdesignstudio/examples/doc/images/fire-particles-sprite-sequence.png
new file mode 100644
index 0000000000..c2ef2156bf
--- /dev/null
+++ b/doc/qtdesignstudio/examples/doc/images/fire-particles-sprite-sequence.png
diff --git a/doc/qtdesignstudio/examples/doc/images/fire-particles-sprite-textures.png b/doc/qtdesignstudio/examples/doc/images/fire-particles-sprite-textures.png
new file mode 100644
index 0000000000..e719b7ef29
--- /dev/null
+++ b/doc/qtdesignstudio/examples/doc/images/fire-particles-sprite-textures.png
diff --git a/doc/qtdesignstudio/examples/doc/images/fire-particles.png b/doc/qtdesignstudio/examples/doc/images/fire-particles.png
new file mode 100644
index 0000000000..c0ea560828
--- /dev/null
+++ b/doc/qtdesignstudio/examples/doc/images/fire-particles.png
diff --git a/doc/qtdesignstudio/examples/doc/rainSnowParticles.qdoc b/doc/qtdesignstudio/examples/doc/rainSnowParticles.qdoc
index 6b50449f07..2ab7fe2182 100644
--- a/doc/qtdesignstudio/examples/doc/rainSnowParticles.qdoc
+++ b/doc/qtdesignstudio/examples/doc/rainSnowParticles.qdoc
@@ -26,8 +26,9 @@
 /*!
     \page rain-snow-particle-effect.html
     \ingroup gstutorials
+    \sa Particles
 
-    \title Rain and Snow Effect
+    \title Particle System: Rain and Snow Effect
     \brief Illustrates how to create a rain and snow effect with the \QDS
     particle system.
 
diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-particles.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-particles.qdoc
index 6f768c6bd2..12638642ff 100644
--- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-particles.qdoc
+++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-particles.qdoc
@@ -29,7 +29,6 @@
     \page studio-3d-particles.html
     \previouspage studio-3d-loader-3d.html
     \nextpage studio-3d-particle-system.html
-
     \title Particles
 
     A \e {particle system} enables you to use sprites, 3D models, or images to
@@ -96,144 +95,7 @@
             particle instance in \uicontrol Navigator.
     \endlist
 
-    Add instances of other components according to your use case. The following
-    section describes how to modify particle system component property values by
-    using the simulation of fire as an example.
-
-    \section1 Example: Fire
-
-    \image studio-3d-particles-fire.gif "Fire simulated by using particles"
-
-    In this section, we explore using particle system components and modifying
-    their property values, such as particle source images and their color, life
-    span, and fading effects, to simulate fire.
-
-    You can download the completed project from
-    \l {https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/FireParticles}{here}.
-
-    We will need the following \l{Assets}{assets}:
-
-    \list
-        \li Two images of flames: \e flame_01.png and \e flame_03.png
-        \li An image of smoke: \e smoke_01.png
-    \endlist
-
-    \image studio-3d-particles-fire-assets.png "The assets in Assets"
-
-    We will also need instances of the following components:
-
-    \list
-        \li \l {Particle System} (one instance)
-        \li \l {Sprite Particle} (four instances)
-        \li \l {Emitter} (four instances)
-        \li \l {Vector Direction} (four instances)
-        \li \l {Textures}{Texture} (four instances)
-    \endlist
-
-    We start by creating a \l{Creating a Project}{Qt Quick 3D Application}
-    project and adding the assets to it. We then follow the instructions above
-    to add the \uicontrol {Particle System} component instance, which provides
-    us with our first \uicontrol Emitter, \uicontrol {Sprite Particle}, and
-    \uicontrol {Vector Direction} instances.
-
-    We add a \uicontrol Texture component instance with \e flame_01.png as the
-    source, and then add the texture as the sprite to use for the sprite
-    particle. We now have all the component instances we need for our first
-    emitter. To keep all the component instances together, we drag-and-drop the
-    sprite particle instance to the emitter instance in \uicontrol Navigator.
-
-    \image studio-3d-particles-fire-emitter1.png "First emitter in fire example in Navigator"
-
-    We need more than one particle to realistically simulate a fire, so we will
-    add three more emitter instances to the particle system. We can copy-paste
-    the first instance in \uicontrol Navigator, and just modify two of the
-    texture instances to use \e flame_03.png as the source and one of them to
-    use \e smoke_01.png as the source. We use three different flame particles
-    to be able to layer them and to hide the fact that two of them actually use
-    the same texture.
-
-    \image studio-3d-particles-fire-components.png "Fire particle system component instances in Navigator"
-
-    We can now start playing with the particle system component properties to
-    achieve the artistic effect that we want. To see how the changes in property
-    values affect the simulation, we will open the live preview by selecting
-    \inlineimage icons/live_preview.png
-    on the main toolbar (or by pressing \key {Alt+P}).
-
-    First, we will specify property values for the \uicontrol {Particle System}
-    component. We want to spawn some particles before the simulation starts, so
-    that the fire will be roaring at start. To achieve this, we set the value of
-    \uicontrol Properties > \uicontrol {Particle System} >
-    \uicontrol {Start Time} to \e 2000 milliseconds. We will
-    use the default values for the other properties.
-
-    \image studio-3d-particles-fire-properties-particle-system.png "Particle System properties"
-
-    Then, we will specify how individual particles are spawned. We set the
-    value of \uicontrol Properties > \uicontrol {Particle Emitter} >
-    \uicontrol {Emit rate} to \e 40.00 for the flame particles and \e 20.00
-    for the smoke particle, because we want to have more flames than smoke.
-
-    \image studio-3d-particles-fire-properties-particle-emitter.png "Particle Emitter properties"
-
-    To increase the visibility of the smoke at the top, we set the value of
-    \uicontrol {Life span} to \e 1200 milliseconds for the smoke particles
-    and \e 900, \e 1000, and \e 600 milliseconds for the flame particles.
-    Further, we set \uicontrol {Life span variation} to \e 100, \e 200, and
-    \e 300 for the flame particles to have some of them expire sooner than
-    others.
-
-    To scale the particles during their lifespan, we set
-    \uicontrol {Particle scale} to \e 2.00 for all particles and
-    \uicontrol {Particle end scale} to \e 5.00 for the flame
-    particles and to \e 6.00 for the smoke particles.
-
-    We can now modify the appearance of the particles by selecting the
-    \e spriteParticle in \uicontrol Navigator and then setting their color in
-    \uicontrol Properties > \uicontrol Particle. We select transparent yellow,
-    orange, and transparent gray in \uicontrol Color and set values for
-    \uicontrol {Color variation} to use slightly different colors for the
-    individual particles.
-
-    We can also try changing the \uicontrol{Blend Mode} for the particle to get
-    a more realistic fire effect.
-
-    \image studio-3d-particles-fire-properties-particle.png "Particle properties"
-
-    We set \uicontrol {Fade in effect} and \uicontrol {Fade out effect} values
-    to \uicontrol FadeOpacity to change particle opacity between 0 and 1 over
-    the time specified in milliseconds in \uicontrol {Fade in duration} and
-    \uicontrol {Fade out duration}. Fading duration is calculated into the
-    particle lifespan, and therefore the smoke particles are actually never
-    fully visible with our settings.
-
-    To specify that the particle texture should always be aligned face towards
-    the screen, we enable \uicontrol Properties > \uicontrol {Sprite Particle} >
-    \uicontrol Billboard for all the particle component instances.
-
-    \image studio-3d-particles-fire-properties-sprite-particle.png "Sprite Particle properties"
-
-    In \uicontrol{Particle Rotation}, we also need to set \uicontrol Rotation
-    and \uicontrol{Velocity Variation} for all emitters to 0.
-
-    \image studio-3d-particles-fire-properties-rotation.png "Emitter rotation properties"
-
-    Finally, we will specify the direction in which the particles move by
-    modifying the property values of the \uicontrol {Vector Direction} component
-    instances in \uicontrol Properties > \uicontrol {Particle Vector Direction}.
-
-    In \uicontrol Direction, we set \uicontrol Y to \e 100.00 to make particles
-    move \e up, and \uicontrol Z to \e -100.00 to make them move in the
-    direction opposite to the target vector. We set the \uicontrol Direction
-    value to \e -50.00 for one of the flame particles and to \e -80.00 for the
-    smoke particle.
-
-    \image studio-3d-particles-fire-properties-vector-direction.png "Vector Direction properties"
-
-    We set the \uicontrol {Direction Variation} values for the different
-    vector direction instances to \e 10.00, \e 8.00, and \e 12.00 to make some
-    flames spread wider than others. You can try different values until you
-    get the effect you want.
+    Add instances of other components according to your use case.
 
     \section1 Performance Considerations
 
@@ -344,6 +206,13 @@
         \li Wander
         \li Applies random wave curves to particles.
     \endtable
+
+    \section1 Particle System Tutorials
+
+    \list
+      \li \l{Particle System: Fire Effect}
+      \li \l{Particle System: Rain and Snow Effect}
+    \endlist
 */
 
 /*!