// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
    \title Weather Forecast Example
    \example quickshapes/weatherforecast
    \image qml-weatherforecast-example.png
    \brief A Qt Quick Shapes example demonstrating different ways to uses shapes in an application.
    \ingroup qtquickexamples
    \examplecategory {Graphics}

    This example is designed to look like a weather forecast app for Europe. It demonstrates
    a few different ways the \l{QtQuick.Shapes} API might be useful in an application, and how
    different properties can affect the quality and performance of the rendering.

    All graphics in the example originated as \c .svg files which are converted to QML
    using the \l{svgtoqml} tool automatically at build time.

    \snippet quickshapes/weatherforecast/CMakeLists.txt svgtoqml

    The generated QML files can be used in the application code like any other.

    \section1 Different Types of Shapes

    The \l{QtQuick.Shapes} module provides APIs to render vector graphics in a Qt Quick
    application. This is an alternative to using a raster \l{Image} for 2D graphics and is useful
    if the target size of the image is not known up front. With an \l{Image}, the rasterized pixmap
    is precreated at a specific size and scaling the image will either add or subtract information.
    This will result in pixelation or blurring, depending on whether its \c smooth property is set.

    With \l{QtQuick.Shapes} the shapes are described mathematically, as a set of curves and line
    segments, and thus they can be scaled arbitrarily without introducing artifacts.

    \image qml-weatherforecast-example.png

    In the Weather Forecast example, there are three main uses of shapes:

    \list
    \li User interface icons, such as weather symbols and the cog wheel on the "Settings" button.
    \li The overview map of Europe.
    \li Country name labels visible when zooming into the map.
    \endlist

    \section2 User Interface Icons

    While using appropriately sized raster images for icons is usually preferred for performance
    reasons, it may be inconvenient if the same application is targeting many different screen
    sizes. In order for the icons to look crisp on all screens, you have to pregenerate a large
    set of different sizes. \l{QtQuick.Shapes} makes it possible for the application to do this
    adaptation at runtime, by including the icons as shapes and rendering them at a size appropriate
    for the current screen size.

    When running the Weather Forecast example on a desktop system, this can be seen by making the
    application window larger or smaller. The weather symbols adapt to the window size without
    reducing quality.

    In addition, animated effects, such as zooms, can be added without quality loss. This can be
    seen by hovering over the weather symbols.

    So for any use case where the target size is unknown, or the number of possibilities is so large
    that creating specific pixmaps for all would be impractical, using shapes for icons can be
    useful and worth the performance cost of rasterizing the shapes at runtime.

    \section2 Map of Europe

    The Weather Forecast example also uses a vectorized map of Europe. This makes it easy to
    create effects such as zooming into the map when we want to emphasize a specific country. In
    addition, since each country is a separate sub-shape, we can apply different fills and strokes
    to them independently.

    Click on the map to zoom into a country. The scale will be adjusted so that the country shape
    fills the window and the fill color will be slightly darker.

    \image zoomed.png

    \note The weather symbols on the zoomed map are the same assets as in the original view, but at
    a much larger size.

    \section2 Country Name Labels

    When zooming on a country, its name appears across the country shape. This label is also created
    with \l{QtQuick.Shapes}, by using the \l{PathText} component type which converts a string into
    renderable shape.

    This is not the typical way to create text labels in Qt Quick. For most purposes, using the
    \l{Text} element is the most efficient and convenient approach. However, there are certain
    visualization effects supported by \l{QtQuick.Shapes} which is not supported by the regular
    \l{Text} element. Fill gradients is one such effect.

    \snippet quickshapes/weatherforecast/main.qml textShape

    To illustrate this, the Weather Forecast example applies a subtle radial gradient to the opacity
    of the country labels, making them seem to blend into the map on the edges.

    \section1 Different Types of Renderers

    The Weather Forecast example illustrates multiple different use cases for \l{QtQuick.Shapes}.
    In addition, it can be used to see the upsides and downsides of the different renderers the
    module supports.

    Click on the cog wheel in the upper left corner to open a settings panel, where different
    approaches to rasterization can be selected.

    \image settings.png

    \l{QtQuick.Shapes} supports two different renderers, selectable using the
    \l{ QtQuick.Shapes::Shape::preferredRendererType}{preferredRendererType} property. The preferred
    renderer in the example is \c CurveRenderer. This supports hardware-accelerated curves and
    built-in antialiasing. It is not the default renderer in \l{QtQuick.Shapes}, but in the example
    it is automatically selected on startup.

    The default renderer in Qt Quick Shapes is the \c GeometryRenderer. This flattens the curves of
    the shape into very small straight lines and draws the shape as a polygon. Redrawing the shape
    is more efficient than with the \c CurveRenderer, but at certain scales, the fact that curves
    are approximated by lines will be visible.

    In addition, the \c GeometryRenderer does not support antialiasing, so you will typically want
    to enable multi-sampling when using it. This can be done by rendering the shapes into layers and
    enabling multi-sampling on these. Since we will render the shapes into off-screen buffers in
    this mode, it consumes additional graphics memory as well as an additional rendering pass for
    each shape.

    \snippet quickshapes/weatherforecast/main.qml msaa

    The settings panel also provides the option to use the \c GeometryRenderer together with 4x
    multi-sampling, so that the quality of this can be compared to the built-in antialiasing of
    the \c CurveRenderer.

    \include examples-run.qdocinc
*/
