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

/*!
\page topics-vectorimageformats.html
\title Vector Image Formats in Qt
\brief Details on Qt's support for vector image formats
\ingroup explanations-graphicsandmultimedia

Qt supports many standard file formats for loading graphical data, allowing applications to import
content produced in other tools.

This article focuses on vector images, and which considerations to take when producing vector
graphics content for use in a Qt application.

\note For general information on Qt's support for 2D graphics, see the
\l{2D Graphics in Qt}{2D Graphics in Qt documentation}.

\section1 File Format: SVG

SVG files can be loaded in two different ways in \l{Qt Quick}: Either as a software-rasterized image
using the \l{Image} component or using hardware-accelerated rendering with \l{VectorImage}
(including converting the file ahead of time using \l{svgtoqml}.)

In addition, \l{QSvgRenderer} provides general access to the software rasterizer. \l{QSvgWidget}
and \l{QGraphicsSvgItem} provide convenience APIs for integrating SVG content in \l{Qt Widgets}
applications.

As a baseline, Qt supports the static features of the SVG 1.2 Tiny profile. A detailed list of the
features supported by this profile is available in the
\l{https://www.w3.org/TR/SVGMobile12/}{SVG 1.2 Tiny specification}.

In addition, certain \l[QtSvg]{extended features} are supported.

Interactive features of SVG are not supported, but interaction can easily be implemented in either
\l{Qt Quick} or \l{Qt Widgets}. Some specific animation types are also supported, using either the
SMIL format or CSS keyframes.

Here follows a high-level list of supported and unsupported features to give an overview of what to
expect. Unsupported features will be ignored as far as it is possible, so that SVG files that depend
on unsupported features will still show, but they may have omissions or errors.

\table
\row
    \li \b{Transforms}
    \li \b{Supported}
\row
    \li Position
    \li 👍
\row
    \li Scale
    \li 👍
\row
    \li Rotation
    \li 👍
\row
    \li Skew
    \li 👍
\row
    \li \b{Shapes}
    \li \b{Supported}
\row
    \li Ellipse/circle
    \li 👍
\row
    \li Rectangle
    \li 👍
\row
    \li Polylines and polygons
    \li 👍
\row
    \li Bezier paths
    \li 👍
\row
    \li Markers
    \li 👍
\row
    \li Symbols
    \li 👍
\row
    \li \b{Shape renderable}
    \li \b{Supported}
\row
    \li Fill
    \li 👍
\row
    \li Stroke
    \li 👍
\row
    \li Linear gradient
    \li 👍
\row
    \li Radial gradient
    \li 👍
\row
    \li Conical gradient
    \li 👍
\row
    \li Patterns
    \li 👍
\row
    \li Gradient stroke
    \li 👍
\row
    \li Stroke caps
    \li 👍
\row
    \li Stroke joins
    \li 👍
\row
    \li Stroke styles (dashed, etc.)
    \li 👍
\row
    \li Cosmetic strokes
    \li 👍
\row
    \li \b{Text}
    \li \b{Supported}
\row
    \li Spans
    \li 👍
\row
    \li Glyphs
    \li 👍
\row
    \li \b{Post-processing effects}
    \li \b{Supported}
\row
    \li Masks
    \li 👍
\row
    \li \e{feColorMatrix}
    \li 👍
\row
    \li \e{feFlood}
    \li 👍
\row
    \li \e{feOffset}
    \li 👍
\row
    \li \e{feGaussianBlur}
    \li 👍
\row
    \li \e{feMerge}
    \li 👍
\row
    \li Remaining filters
    \li 🚫
\row
    \li \b{CSS animations}
    \li \b{Supported}
\row
    \li Colors
    \li 👍
\row
    \li Gradients
    \li 👍
\row
    \li Opacity
    \li 👍
\row
    \li Transforms
    \li 👍
\row
    \li \e{Offset-path}
    \li 👍
\row
    \li Motion paths
    \li 👍
\row
    \li Easing curves
    \li 👍
\row
    \li Remaining properties
    \li 🚫
\row
    \li \b{SMIL animations}
    \li \b{Supported}
\row
    \li \e{animateTransform}
    \li 👍
\row
    \li \e{animateColor}
    \li 👍
\row
    \li \e{animate}
    \li 🚫
\row
    \li \e{animateMotion}
    \li 🚫
\row
    \li \e{set}
    \li 🚫
\row
    \li \b{Other}
    \li \b{Supported}
\row
    \li Raster images
    \li 👍
\row
    \li \e{Use} element
    \li 👍
\row
    \li \e{Switch} element
    \li 👍
\row
    \li Clip paths
    \li 🚫
\row
    \li Multimedia
    \li 🚫
\row
    \li Scripting
    \li 🚫
\row
    \li Linking
    \li 🚫
\endtable

\section1 File Format: Lottie

Similarly to SVG, there are different ways of loading files in the Lottie format in Qt.

The LottieAnimation type loads an image and displays it using a software rasterizer, much
like QSvgRenderer does for SVG.

In addition, hardware accelerated rendering is possible using VectorImage and the \l{lottietoqml}
tool.

In order to use Lottie files with VectorImage, the \c vectorimageformats plugin included with the
\l{Qt Lottie Animation} module must be deployed together with the application. In addition,
the \l{QtQuick.VectorImage::VectorImage::assumeTrustedSource}{assumeTrustedSource} property of
the VectorImage must be set to \c true. Detailed control of the animation playback is available in
\l{LottieVectorImageController}.

The \l{lottietoqml} tool can be used to pre-convert Lottie source files to QML. An example of this
can be found in the \l{lottietoqml Example}.

The following is a list of the high-level features supported by the LottieAnimation type (software
rasterizer) and VectorImage (also including pre-converting files using \l{lottietoqml}.)

\table
\row
    \li \b{Transforms}
    \li \b{Supported}
\row
    \li Position
    \li 👍
\row
    \li Scale
    \li 👍
\row
    \li Rotation
    \li 👍
\row
    \li Skew
    \li 👍
\row
    \li Opacity
    \li 👍
\row
    \li Anchor point
    \li 👍
\row
    \li Auto orient
    \li 👍
\row
    \li \b{Shapes}
    \li \b{Supported}
\row
    \li Ellipse/circle
    \li 👍
\row
    \li Rectangle
    \li 👍
\row
    \li Rounded rectangle
    \li 👍
\row
    \li Polystar
    \li 👍
\row
    \li Bezier paths
    \li 👍
\row
    \li Trimmed paths
    \li 👍
\row
    \li \b{Shape renderable}
    \li \b{Supported}
\row
    \li Fill
    \li 👍
\row
    \li Stroke
    \li 👍
\row
    \li Linear gradient
    \li 👍
\row
    \li Radial gradient
    \li 👍
\row
    \li Gradient stroke
    \li 👍
\row
    \li Stroke caps
    \li 👍
\row
    \li Stroke joins
    \li 👍
\row
    \li Stroke styles (dashed, etc.)
    \li 👍
\row
    \li \b{Text}
    \li \b{Supported}
\row
    \li Fill
    \li 👍
\row
    \li Stroke
    \li 🚫
\row
    \li Fonts
    \li 👍
\row
    \li Glyphs
    \li 👍
\row
    \li \b{Post-processing effects}
    \li \b{Supported}
\row
    \li Alpha mattes
    \li 👍
\row
    \li Luminance mattes
    \li 👍
\row
    \li Layer effects
    \li 🚫
\row
    \li \b{Merged paths}
    \li \b{Supported}
\row
    \li Add
    \li 👍
\row
    \li Subtract
    \li 🚫
\row
    \li Intersect
    \li 🚫
\row
    \li \b{Masks}
    \li \b{Supported}
\row
    \li Mask path
    \li 👍
\row
    \li Union
    \li 👍
\row
    \li Additional operations
    \li 🚫
\row
    \li \b{Animations}
    \li \b{Supported}
\row
    \li Colors
    \li 👍
\row
    \li Gradients
    \li 👍
\row
    \li Opacity
    \li 👍
\row
    \li Transforms
    \li 👍
\row
    \li Path interpolation
    \li 👍
\row
    \li Trims
    \li 👍
\row
    \li Markers
    \li 🚫
\row
    \li Merged paths
    \li 🚫
\row
    \li Remaining properties
    \li 🚫
\row
    \li Easing curves
    \li 👍
\row
    \li Time stretch
    \li 👍
\row
    \li Time remap
    \li 👍
\row
    \li \b{Other}
    \li \b{Supported}
\row
    \li Raster images
    \li 👍
\row
    \li \e{Precomp} layers
    \li 👍
\row
    \li Expressions
    \li 🚫
\endtable

\section1 File Format: Font Files as a Vector Image Format

In addition to conventional format for vector graphics, like SVG, it is also possible to utilize
custom font files where vector graphics assets are stored as glyphs.

This has the advantage that simple illustrations can be inlined in text labels, with typographical
properties similar to text. This, in turn, that can make the alignment of the images with text
easier.

Using font files for this purpose can also be a convenient way to distribute large icon libraries,
as well as providing themes that can be replaced at run-time.

However, font use in Qt is optimized for producing text, so there are some considerations when using
icon fonts as an alternative to specialized vector image components like \l{VectorImage}.

First of all, color fonts will always be pre-rasterized at the specified pixel size. This means
that applying transforms to such text items will cause scaling artifacts. For illustrations that
require zooming for instance, using \l{VectorImage} is preferable.

Using the specialized components is also preferable for any animated vector image. While the
variable font format extension makes morphing animations possible, this is not the use the font
system in Qt is optimized for. Therefore, animating the variable axes of a font will be less
efficient than using another vector image format.

So for animated and/or multi-color vector images, using a format such as SVG should typically be
preferred. For single-color, static ones, using a font is an option with certain conveniences.

\note See also the \l{Icons in Qt Quick Controls}{standard icon support in Qt Quick Controls}.
*/
