// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example wiggly
    \examplecategory {Graphics}
    \meta tags {qqem, effects, quickcontrols}
    \title Wiggly
    \ingroup quickeffectmaker-examples
    \brief Demonstrates how to use an effect created with the Qt Quick Effect Maker (QQEM).

    \e {Wiggly} demonstrates how to use a shader effect, created
    with the Qt Quick Effect Maker (QQEM), in your Qt Quick application. A
    simple Qt Quick user interface allows changing the wiggly text and the wave size,
    as well as applying the electric cloud effect.

    \image wiggly-example.png
           {Wiggly text reading HELLO WORLD with rainbow gradient and wave effect}

    \include examples-run.qdocinc

    \section1 Application basics

    Most of the example is contained and set up in the \e main.qml file. First, create
    an item which is used as the source for the effect.

    \snippet wiggly/main.qml sourceitem

    The item is a \l Rectangle with a \l Text element inside. The size of the rectangle
    depends on the number of characters in the text to make it fit nicely into the
    application window. The important lines here are \e {layer.enabled: true} that creates
    the offscreen texture for the effect and \e {visible: false}
    that hides this element as the effect will replace its content. If the item is
    visible, it looks like this without the wiggly effect:

    \image wiggly-sourceitem.png {Label displaying the text WIGGLY}

    Next, create the settings toolbar used for controlling the effect.

    \image wiggly-settings.png
           {Settings toolbar with text field, two sliders, and toggle switch}

    \snippet wiggly/main.qml settings

    These components use the \l {Qt Quick Controls}, stacked inside a \l Row element.
    The first one is a \l TextField, which you can use to change the wiggly text. Then
    there are separate \l Slider elements, to control the wave size in X and Y
    coordinates. The last control is a \l Switch, to enable the electric clouds effect.

    \snippet wiggly/main.qml wigglyeffect

    This WigglyEffect is applied to the \c sourceItem defined earlier. Code sets
    \c timeRunning to true to animate the effect. Finally, it connects some shader effect
    properties to the controlling components.

    You can also look at the \c {WigglyEffect.qml} file for details of the effect. But
    that file is created by the QQEM tool, so you should not usually modify it manually.
    Instead, use the Qt Quick Effect Maker as instructed in the next section.

    \section1 Modifying the effect in QQEM

    As mentioned above, the \e {WigglyEffect} has been created using the Qt Quick
    Effect Maker. For more information about QQEM installation, see the
    \l {Installing Qt Quick Effect Maker} documentation.

    To modify the effects:

    \list 1
        \li Open the effect project file (qep) in the QQEM tool.
        \li Modify the effect nodes, properties or the shader code and see the live preview.
        \li When ready, export the modified effect into your application.
    \endlist

    When the \c {WigglyEffect/WigglyEffect.qep} project is opened in QQEM, you should see
    something like this:

    \image wiggly-qqem.png
           {Qt Quick Effect Maker with node view on left and shader code on right}

    On the left side, you can see the \uicontrol {Node view} with different nodes of this effect.
    The top-right view is \uicontrol {Property view}, with properties (API) of the effect.
    The bottom-right corner shows \uicontrol {Live view} of the effect, with the currently
    selected preview source item. To see the live preview with the actual content, add the
    image of the \c {sourceItem} to the sources list in \uicontrol Edit > \uicontrol Preferences
    and select it from the preview toolbar popup list.

    To modify the shader code for the wiggly effect, double-click the \e Wiggly node or select
    it and switch from \uicontrol DESIGN mode to \uicontrol CODE mode. Then select the
    \uicontrol VERT tab to see the vertex shader, where most of the effect code is:

    \badcode
    @mesh 63, 1
    out vec3 wigglyColor;

    float rainbowColor(float phase) {
        return abs(sin(texCoord.x * 2.0 + iTime + phase));
    }

    @main
    {
        float wave = sin(vertCoord.x * 0.01 + iTime * 3.0);
        vertCoord.x += wigglyAmountX * wave;
        vertCoord.y += wigglyAmountY * wave;
        const float tau = 6.28318530718;
        wigglyColor.r = rainbowColor(0.0);
        wigglyColor.g = rainbowColor(1.0/3.0 * tau);
        wigglyColor.b = rainbowColor(2.0/3.0 * tau);
        float shadowAmount = (wigglyAmountX + wigglyAmountY) * wave;
        wigglyColor.rgb += shadowAmount * wigglyShadows * 0.01;
    }
    \endcode

    The first line sets up the ShaderEffect mesh grid size. This is needed, as by
    default there are vertices only in the corners and the wiggly effect requires more
    moving vertices. Then, set the vertex shader to output \c wigglyColor variable,
    which will be later used in the fragment shader for applying some shadow. Next,
    introduce a function called \c rainbowColor, which returns the color of a single
    channel at the phase.

    Inside the main method, code first sets the \c vertCoord to move the vertex positions
    in a sin wave. The next lines set the red, green, and blue channels of the wiggly
    rainbow. The last two lines then apply some shadowing following the wave.

    Next, select the \uicontrol FRAG tab to see the fragment shader code:

    \badcode
    @main
    {
        fragColor.rgb *= wigglyColor * fragColor.a;
    }
    \endcode

    The fragment shader is very simple and only multiplies the current source
    color with the \c wigglyColor received from the vertex shader.

    More of the processing could have been done on the fragment shader side, but having
    the code on the vertex shader generally is more performant due to the number of
    vertices being notably lower than the number of fragments (pixels). Some tools,
    like the \l{http://www.shadertoy.com}{Shadertoy}, only allow writing a fragment
    shader. But as Qt Quick and QQEM also support custom vertex shaders, you should
    try to take advantage of them.

    When you modify these shaders, the output of the \uicontrol {Live view} changes
    instantly. To get the modified shader into use in the example application,
    select \uicontrol File > \uicontrol Export from the menu.

    You can now play more with the QQEM features. For example, add new nodes, change
    or add new properties, utilize these properties in the shader code, and so on.
    Here is an example of what the effect looks like with \c LedScreen node added
    to the beginning of the node graph:

    \image wiggly-ledscreen.png
           {Wiggly text with LED screen effect showing colorful dot pattern}

*/
