From e083a4ccd8ca7f890b4ee43057305e4a272256d6 Mon Sep 17 00:00:00 2001 From: Miikka Heikkinen Date: Wed, 19 Feb 2014 10:53:01 +0200 Subject: Document the rendering changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I100a516f6f5d8047b88f6d81cd8794979211df20 Reviewed-by: Miikka Heikkinen Reviewed-by: Tomi Korpipää --- examples/datavisualization/qmlbars/main.cpp | 5 -- examples/datavisualization/qmlcustominput/main.cpp | 5 -- examples/datavisualization/qmllegend/main.cpp | 5 -- examples/datavisualization/qmlmultigraph/main.cpp | 5 -- .../qmloscilloscope/doc/src/qmloscilloscope.qdoc | 16 +++++ .../datavisualization/qmloscilloscope/main.cpp | 7 ++- .../qmloscilloscope/qml/qmloscilloscope/main.qml | 3 + .../qmlscatter/doc/src/qmlscatter.qdoc | 10 --- examples/datavisualization/qmlscatter/main.cpp | 9 --- examples/datavisualization/qmlsurface/main.cpp | 5 -- .../datavisualization/qmlsurfacelayers/main.cpp | 2 +- ...tdatavisualization-qml-abstractdeclarative.qdoc | 72 ++++++++++++---------- .../doc/src/qtdatavisualization-qml-bars3d.qdoc | 5 -- .../doc/src/qtdatavisualization-qml-scatter3d.qdoc | 5 -- .../doc/src/qtdatavisualization-qml-surface3d.qdoc | 5 -- .../doc/src/qtdatavisualization.qdoc | 24 +++++--- tests/qmlcamera/main.cpp | 5 -- tests/qmldynamicdata/main.cpp | 5 -- 18 files changed, 83 insertions(+), 110 deletions(-) diff --git a/examples/datavisualization/qmlbars/main.cpp b/examples/datavisualization/qmlbars/main.cpp index a42218ae..966d068a 100644 --- a/examples/datavisualization/qmlbars/main.cpp +++ b/examples/datavisualization/qmlbars/main.cpp @@ -16,8 +16,6 @@ ** ****************************************************************************/ -#include - #include #include #include @@ -29,9 +27,6 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing - viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); - // The following are needed to make examples run without having to install the module // in desktop environments. #ifdef Q_OS_WIN diff --git a/examples/datavisualization/qmlcustominput/main.cpp b/examples/datavisualization/qmlcustominput/main.cpp index 08cbf26d..d4658d41 100644 --- a/examples/datavisualization/qmlcustominput/main.cpp +++ b/examples/datavisualization/qmlcustominput/main.cpp @@ -16,8 +16,6 @@ ** ****************************************************************************/ -#include - #include #include #include @@ -29,9 +27,6 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing - viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); - // The following are needed to make examples run without having to install the module // in desktop environments. #ifdef Q_OS_WIN diff --git a/examples/datavisualization/qmllegend/main.cpp b/examples/datavisualization/qmllegend/main.cpp index a3bc1590..62016770 100644 --- a/examples/datavisualization/qmllegend/main.cpp +++ b/examples/datavisualization/qmllegend/main.cpp @@ -16,8 +16,6 @@ ** ****************************************************************************/ -#include - #include #include #include @@ -29,9 +27,6 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing - viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); - // The following are needed to make examples run without having to install the module // in desktop environments. #ifdef Q_OS_WIN diff --git a/examples/datavisualization/qmlmultigraph/main.cpp b/examples/datavisualization/qmlmultigraph/main.cpp index 270e5274..ef53d5ec 100644 --- a/examples/datavisualization/qmlmultigraph/main.cpp +++ b/examples/datavisualization/qmlmultigraph/main.cpp @@ -16,8 +16,6 @@ ** ****************************************************************************/ -#include - #include #include #include @@ -29,9 +27,6 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing - viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); - // The following are needed to make examples run without having to install the module // in desktop environments. #ifdef Q_OS_WIN diff --git a/examples/datavisualization/qmloscilloscope/doc/src/qmloscilloscope.qdoc b/examples/datavisualization/qmloscilloscope/doc/src/qmloscilloscope.qdoc index e5a84b86..c574950b 100644 --- a/examples/datavisualization/qmloscilloscope/doc/src/qmloscilloscope.qdoc +++ b/examples/datavisualization/qmloscilloscope/doc/src/qmloscilloscope.qdoc @@ -107,4 +107,20 @@ DataSource at requested intervals. The label update is also triggered on each cycle: \snippet qmloscilloscope/qml/qmloscilloscope/main.qml 3 + + \section1 Enabling direct rendering + + Since this application potentially deals with a lot of rapidly changing data, we use direct + rendering mode for performance. To enable antialiasing in this mode the surface format of the application + window needs to be changed, as the default format used by QQuickView doesn't support antialiasing. + We use the utility function provided by Qt Data Visualization to change the surface format + in \c main.cpp: + + \snippet qmloscilloscope/main.cpp 1 + \dots 0 + \snippet qmloscilloscope/main.cpp 2 + + On the QML side, direct rendering mode is enabled via \l{AbstractGraph3D::renderingMode}{renderingMode} property: + + \snippet qmloscilloscope/qml/qmloscilloscope/main.qml 5 */ diff --git a/examples/datavisualization/qmloscilloscope/main.cpp b/examples/datavisualization/qmloscilloscope/main.cpp index 3e99c4a0..9ee46e21 100644 --- a/examples/datavisualization/qmloscilloscope/main.cpp +++ b/examples/datavisualization/qmloscilloscope/main.cpp @@ -17,7 +17,10 @@ ****************************************************************************/ #include "datasource.h" + +//! [2] #include +//! [2] #include #include @@ -31,8 +34,10 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing + // Enable antialiasing in direct rendering mode + //! [1] viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); + //! [1] // The following are needed to make examples run without having to install the module // in desktop environments. diff --git a/examples/datavisualization/qmloscilloscope/qml/qmloscilloscope/main.qml b/examples/datavisualization/qmloscilloscope/qml/qmloscilloscope/main.qml index 6034109b..eeaeab40 100644 --- a/examples/datavisualization/qmloscilloscope/qml/qmloscilloscope/main.qml +++ b/examples/datavisualization/qmloscilloscope/qml/qmloscilloscope/main.qml @@ -49,6 +49,9 @@ Item { height: dataView.height shadowQuality: AbstractGraph3D.ShadowQualityNone selectionMode: AbstractGraph3D.SelectionSlice | AbstractGraph3D.SelectionItemAndRow + //! [5] + renderingMode: AbstractGraph3D.RenderDirectToBackground + //! [5] axisX.labelFormat: "%d ms" axisY.labelFormat: "%d W" diff --git a/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc b/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc index ec11970f..177cf7c1 100644 --- a/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc +++ b/examples/datavisualization/qmlscatter/doc/src/qmlscatter.qdoc @@ -35,16 +35,6 @@ Before diving into the QML code, let's take a look at the application \c main.cpp. - Anti-aliasing for Qt Data Visualization graphs in Qt Quick 2 is not supported by default due - to technological limitations. To enable anti-aliasing, a custom surface format must be set to - the QQuickWindow we are using to show the application in the application \c main.cpp: - - \snippet qmlscatter/main.cpp 1 - \dots 0 - \snippet qmlscatter/main.cpp 0 - - This will make the graphs nicer to look at. - This application implements a 'Quit' button in the UI, so we want to connect the QQmlEngine::quit() signal to our application's QWindow::close() slot: diff --git a/examples/datavisualization/qmlscatter/main.cpp b/examples/datavisualization/qmlscatter/main.cpp index 425becd5..11684c84 100644 --- a/examples/datavisualization/qmlscatter/main.cpp +++ b/examples/datavisualization/qmlscatter/main.cpp @@ -16,10 +16,6 @@ ** ****************************************************************************/ -//! [1] -#include -//! [1] - #include #include #include @@ -31,11 +27,6 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing - //! [0] - viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); - //! [0] - // The following are needed to make examples run without having to install the module // in desktop environments. #ifdef Q_OS_WIN diff --git a/examples/datavisualization/qmlsurface/main.cpp b/examples/datavisualization/qmlsurface/main.cpp index 348533bb..71d79a2b 100644 --- a/examples/datavisualization/qmlsurface/main.cpp +++ b/examples/datavisualization/qmlsurface/main.cpp @@ -16,8 +16,6 @@ ** ****************************************************************************/ -#include - #include #include #include @@ -29,9 +27,6 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing - viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); - // The following are needed to make examples run without having to install the module // in desktop environments. #ifdef Q_OS_WIN diff --git a/examples/datavisualization/qmlsurfacelayers/main.cpp b/examples/datavisualization/qmlsurfacelayers/main.cpp index fc7393e6..eb895dd1 100644 --- a/examples/datavisualization/qmlsurfacelayers/main.cpp +++ b/examples/datavisualization/qmlsurfacelayers/main.cpp @@ -29,7 +29,7 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing + // Enable antialiasing in direct rendering mode viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); // The following are needed to make examples run without having to install the module diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc index 076af455..5b251768 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc @@ -28,12 +28,6 @@ Note that this type is uncreatable, but contains properties that are shared between the 3D visualizations. - \note QML doesn't support the type of anti-aliasing used by Qt Data Visualization graphs - by default. Setting the \c antialiasing property doesn't affect graphs. To enable - anti-aliasing for graphs, a custom surface format must be set up for the QQuickView - before showing it. You can use the convenience function - \c{QtDataVisualization::qDefaultSurfaceFormat()} to create the custom surface format object. - For AbstractGraph3D enums, see \l QAbstract3DGraph::SelectionFlag and \l QAbstract3DGraph::ShadowQuality @@ -68,7 +62,7 @@ /*! \qmlproperty AbstractGraph3D.RenderingMode AbstractGraph3D::renderingMode - Defaults to RenderDirectToBackground. + Defaults to \c{RenderIndirect}. \table \header @@ -76,38 +70,52 @@ \li Description \row \li RenderDirectToBackground - \li Indicates that the graph should also clear the whole window before - rendering the graph, including the areas outside the graph. - Since the graphs in this rendering mode are drawn first under other QML items, the - regular QML window clearing before rendering is suppressed when there are any graphs - in the window; the graphs handle the clearing themselves instead. - If you have any other items besides graphs that do similar - custom drawing under other QML items, you need to set this property to RenderDirectToBackground_NoClear - on all graphs drawn to same window with the other custom items, or it is likely that the - other custom items do not render properly. If the graphics hardware and current configuration - supports antialiasing that will be used to provide a higher quality rendering with good performance. - See \c {QtDataVisualization::qDefaultSurfaceFormat}. + \li Indicates the graph will be rendered directly on the window background. + This mode also clears the whole window before rendering the graph, including the areas + outside the graph. + Since the graphs in this rendering mode are drawn on the window background under other QML + items, the regular QML window clearing before rendering is suppressed. The graphs handle the clearing + themselves instead. + If the surface format of the window supports antialiasing, it will be used (see + \c {QtDataVisualization::qDefaultSurfaceFormat()}). + This rendering mode offers the best performance at the expense of non-standard QML behavior. For example, + the graphs do not obey the Z ordering of QML items and the opacity value has no effect on them. \row \li RenderDirectToBackground_NoClear - \li Indicates the graph will not clear the whole window before rendering - the graph. The graphs in this renderind mode are drawn first under other QML items. - If the graphics hardware and current configuration supports antialiasing that will be - used to provide a higher quality rendering with good performance. - See \c {QtDataVisualization::qDefaultSurfaceFormat}. + \li Similar to RenderDirectToBackground mode, except that the graph will not clear the whole + window before rendering the graph. This mode is better for windows where you have other custom items + besides the graphs that also draw on the window background. In that case you need to either take care + of the window clearing yourself or ensure that all areas of the window are fully covered with opaque + items. + If one graph in the window uses either of the direct rendering modes, then all other graphs in the + same window also drawn in direct modes should use the exact same direct rendering mode. + Otherwise some graphs may not show up, depending on the drawing order of the graphs. \row - \li RenderIndirect_NoAA + \li RenderIndirect \li Indicates the graph will be first rendered to an offscreen surface that - is then drawn during normal QML item rendering to the correct Z order. No antialiasing - post processing is done on the graph, meaning the quality will be lower but performance - should be better. + is then drawn during normal QML item rendering. The rendered image is + antialiased using multisampling method if it is supported in the current environment and the + msaaSamples property value is greater than zero. + This rendering mode offers good quality and normal QML item behavior at the expense of performance. \endtable - \note If one graph in the window uses either RenderDirectToBackground or RenderDirectToBackground_NoClear, then all - other graphs in the window drawn in direct mode should use the same rendering mode in that window. - Otherwise some graphs may not show. + \note Antialiasing is not supported in OpenGL ES2 environments in any rendering mode. + + \note Setting the \c antialiasing property of the graphs doesn't do anything. However, it is + set by the graph itself if the current rendering mode uses antialiasing. - \note If window clearing before rendering is suppressed, any areas of the window not fully - covered with opaque items may not draw properly. + \sa msaaSamples + */ + +/*! + \qmlproperty int AbstractGraph3D::msaaSamples + The number of samples used in multisample antialiasing when renderingMode is \c RenderIndirect. + When renderingMode is \c RenderDirectToBackground or \c RenderDirectToBackground_NoClear, this + property value is read-only and returns the number of samples specified by the window surface + format. + Defaults to 4. + + \sa renderingMode */ /*! diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc index 443cebf6..6ee51742 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc @@ -36,11 +36,6 @@ * * See \l{Qt Quick 2 Bars Example} for more thorough usage example. * - * \note Qt Data Visualization graphs are rendered behind any other QML elements on screen, including - * the parent elements of the graph. To make the whole graph show, ensure that no other element - * draws anything over the area the graph occupies. For example, having a non-transparent \c Rectangle - * item as the parent of a graph causes the graph to be hidden. - * * \sa Bar3DSeries, ItemModelBarDataProxy, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes} */ diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc index 76f68af4..4ea7888c 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc @@ -36,11 +36,6 @@ See \l{Qt Quick 2 Scatter Example} for more thorough usage example. - \note Qt Data Visualization graphs are rendered behind any other QML elements on screen, including - the parent elements of the graph. To make the whole graph show, ensure that no other element - draws anything over the area the graph occupies. For example, having a non-transparent \c Rectangle - item as the parent of a graph causes the graph to be hidden. - \sa Scatter3DSeries, ScatterDataProxy, Bars3D, Surface3D, {Qt Data Visualization C++ Classes} */ diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc index 576496b9..23a9a004 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc @@ -36,11 +36,6 @@ See \l{Qt Quick 2 Surface Example} for more thorough usage example. - \note Qt Data Visualization graphs are rendered behind any other QML elements on screen, including - the parent elements of the graph. To make the whole graph show, ensure that no other element - draws anything over the area the graph occupies. For example, having a non-transparent \c Rectangle - item as the parent of a graph causes the graph to be hidden. - \sa Surface3DSeries, ItemModelSurfaceDataProxy, Bars3D, Scatter3D, {Qt Data Visualization C++ Classes} */ diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc index c85b9dbb..e68a1086 100644 --- a/src/datavisualization/doc/src/qtdatavisualization.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc @@ -301,24 +301,34 @@ * \fn QSurfaceFormat QtDataVisualization::qDefaultSurfaceFormat(bool antialias = true) * \relates QAbstract3DGraph * - * Anti-aliasing is turned on by default on C++ and turned off on QML, except in OpenGL ES2 - * environments, where anti-aliasing is not supported by Qt Data Visualization. - * This convenience function can be used to construct a suitable surface format for use by + * This convenience function can be used to create a custom surface format suitable for use by * Qt Data Visualization graphs. - * The \a{antialias} parameter specifies whether or not anti-aliasing is activated. + * + * The \a antialias parameter specifies whether or not antialiasing is activated. + * * Give the surface format returned by this function to the graph constructor (C++) or set * it as the window format for QQuickView (QML) before calling show on it. * - * For example, disable anti-aliasing on C++ application: + * For example, disable antialiasing on C++ application: * * \code + * #include + * + * // ... + * * Q3DBars *graph = new Q3DBars(QtDataVisualization::qDefaultSurfaceFormat(false)); * \endcode * - * For example, enable anti-aliasing on QML application: + * For example, enable antialiasing for direct rendering modes on QML application: * * \code - * QtQuick2ApplicationViewer viewer; + * #include + * + * // ... + * + * QQuickView viewer; * viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); * \endcode + * + * \note Antialiasing is not supported in OpenGL ES2 environments. */ diff --git a/tests/qmlcamera/main.cpp b/tests/qmlcamera/main.cpp index 0a8d9817..040eaed3 100644 --- a/tests/qmlcamera/main.cpp +++ b/tests/qmlcamera/main.cpp @@ -16,8 +16,6 @@ ** ****************************************************************************/ -#include - #include #include #include @@ -29,9 +27,6 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing - viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); - // The following are needed to make examples run without having to install the module // in desktop environments. #ifdef Q_OS_WIN diff --git a/tests/qmldynamicdata/main.cpp b/tests/qmldynamicdata/main.cpp index d87a2db5..fa3ea866 100644 --- a/tests/qmldynamicdata/main.cpp +++ b/tests/qmldynamicdata/main.cpp @@ -16,8 +16,6 @@ ** ****************************************************************************/ -#include - #include #include #include @@ -29,9 +27,6 @@ int main(int argc, char *argv[]) QQuickView viewer; - // Enable antialiasing - viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat()); - // The following are needed to make examples run without having to install the module // in desktop environments. #ifdef Q_OS_WIN -- cgit v1.2.3