Revision control
++ // Copyright (C) 2026 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \title Qt Graphs 2D Rendering Backends
++ \page qtgraphs-backends-2D.html
++ \brief Comparison of the two rendering backends available for 2D graphs.
++
++ Qt Graphs for 2D can draw a \l GraphsView with either of two rendering
++ backends:
++
++ \list
++ \li The \b {high-quality} backend, which draws with
++ \l {Qt Quick Shapes}. This is the default.
++ \li The \b {high-performance} backend, which draws with
++ \l {Qt Canvas Painter}. This backend is available only if you
++ enable it when you build the Qt Graphs module.
++ \endlist
++
++ Both backends produce the same graphs from the same API. They differ only
++ in how they draw them.
++
++ \note \l {Building with a Backend}{The build} determines which backends
++ are available. Each graph then picks one of them
++ \l {Selecting the Backend at Run Time}{at run time}.
++
++ \section1 High-Quality Backend
++
++ The high-quality backend draws each series with \l {Qt Quick Shapes},
++ using \l{QtQuick.Shapes::Shape::preferredRendererType}{Shape.CurveRenderer},
++ which keeps strokes and curved edges smooth at any scale. The shapes become
++ part of the scene graph, so the graph is rendered without an intermediate
++ render target.
++
++ \section1 High-Performance Backend
++
++ The high-performance backend draws the whole graph with
++ \l {Qt Canvas Painter}. All of the 2D renderers paint into a single
++ \l QCanvasPainterItem, a \l QQuickRhiItem that renders into an offscreen
++ color buffer sized to the item, so the graph is one scene graph item no
++ matter how many series it contains, and it is resampled rather than
++ redrawn if the item is scaled by a transformation.
++
++ \section1 Choosing a Backend
++
++ The high-quality backend is the default, and is the right choice unless
++ there is a specific reason to change.
++
++ Neither backend redraws a graph that does not change, so for a graph that
++ is drawn once and then left alone, the choice only affects visual quality.
++ The difference in rendering cost shows up when the data, the axis ranges,
++ or the size of the graph keep changing, because that is when the
++ high-quality backend has to rebuild its shape geometry.
++
++ The choice does not affect \l ScatterSeries. Neither backend draws its
++ points. They are Qt Quick items, created from the component set as
++ \l {XYSeries::pointDelegate}{pointDelegate}, or from a built-in marker
++ when the series sets none. The other XY series draw their points the
++ same way when they set a delegate. Their lines and areas still go
++ through the backend.
++
++ Consider the high-performance backend when:
++
++ \list
++ \li The graph contains a large number of series, or series with a
++ large number of points.
++ \li The data is updated continuously, for example from a live sensor
++ feed, so the shape geometry would have to be rebuilt on every
++ frame.
++ \li The application runs on hardware where the number of scene graph
++ nodes and draw calls is the limiting factor.
++ \endlist
++
++ Stay with the high-quality backend when:
++
++ \list
++ \li The graph is scaled, rotated, or otherwise transformed by its
++ parent items, or is rendered into a
++ \l {QtQuick::Item::layer.enabled}{layer} that is scaled.
++ \li Visual fidelity of strokes and curves matters more than the cost
++ of drawing them.
++ \li You don't want to add a dependency on the
++ \l {Qt Canvas Painter} module.
++ \endlist
++
++ \section1 Building with a Backend
++
++ The following table describes the two configure features that control the
++ backends.
++
++ \table
++ \header
++ \li Feature
++ \li Default
++ \li Requires
++ \row
++ \li \c graphs-2d-high-quality-backend
++ \li \c ON
++ \li Nothing beyond the normal Qt Graphs dependencies.
++ \row
++ \li \c graphs-2d-high-performance-backend
++ \li \c OFF
++ \li The \l {Qt Canvas Painter} module (\c qtcanvaspainter).
++ \endtable
++
++ You can enable the high-performance backend only if Qt Canvas Painter is
++ available. If you request the feature in a build without that module,
++ configure fails with an error.
++
++ To enable the high-performance backend when configuring Qt:
++
++ \badcode
++ ./configure -feature-graphs-2d-high-performance-backend
++ \endcode
++
++ To do the same with CMake:
++
++ \badcode
++ cmake -DFEATURE_graphs_2d_high_performance_backend=ON <source>
++ \endcode
++
++ To disable the high-quality backend, pass
++ \c{-no-feature-graphs-2d-high-quality-backend} to \c configure, or
++ \c{-DFEATURE_graphs_2d_high_quality_backend=OFF} to CMake.
++
++ The \c {Qt Graphs 2D} section of the configure summary lists the resulting
++ state as \c {High Quality} and \c {High Performance}.
++
++ The two features are independent, and you can enable both. A graph then
++ chooses between them
++ \l {Selecting the Backend at Run Time}{at run time}.
++
++ Axes, grids, \l BarSeries, \l ScatterSeries, and the delegates of
++ \l CustomSeries do not go through either backend, so Qt Graphs draws
++ them even in a build that has neither. \l AreaSeries, \l LineSeries,
++ \l PieSeries, and \l SplineSeries do need one, and configuring a build
++ that has those graph types but no backend fails with an error. To build
++ the backend-less variant, disable those graph types as well:
++
++ \badcode
++ ./configure -no-feature-graphs-2d-high-quality-backend \
++ -no-feature-graphs-2d-area \
++ -no-feature-graphs-2d-donut-pie \
++ -no-feature-graphs-2d-line \
++ -no-feature-graphs-2d-spline
++ \endcode
++
++ \l {Qt Graphs Configure Options} describes how to enable only the graph
++ types that you need.
++
++ \section1 Selecting the Backend at Run Time
++
++ The high-performance backend is off by default. Unless Qt Graphs was built
++ with it enabled, there is nothing to select between, and the graph is
++ always drawn with Qt Quick Shapes.
++
++ In a build that has both backends, each \l GraphsView selects its backend
++ with the \l {GraphsView::useCanvasPainter} property:
++
++ \qml
++ GraphsView {
++ anchors.fill: parent
++
++ // Draw this graph with the high-performance backend.
++ useCanvasPainter: true
++
++ LineSeries {
++ XYPoint { x: 0; y: 0 }
++ XYPoint { x: 1; y: 1 }
++ }
++ }
++ \endqml
++
++ The property defaults to \c false when the high-quality backend is
++ available, and to \c true when the build has only the high-performance
++ backend. In a build without the high-performance backend, setting the
++ property to \c true has no effect and produces no warning.
++
++ \section1 Extending the Backends
++
++ A \l CustomSeries draws itself with its
++ \l {CustomSeries::delegate}{delegate} component, which works regardless of
++ which backend draws the rest of the graph.
++
++ A custom series can also paint with \l QCanvasPainter, by passing a
++ \l QCustomSeriesCanvasRenderer subclass to
++ \l {QCustomSeries::setCustomSeriesPainter()}. That method only exists in a
++ build that has the high-performance backend, and the painter is only used
++ while that backend is drawing the graph.
++
++ \sa {Qt Graphs Configure Options}, {Qt Graphs Overview for 2D},
++ GraphsView, {Qt Canvas Painter}
++ */