| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page topics-graphics.html |
| \title Graphics |
| \brief Qt's graphics features |
| |
| Graphics in Qt 5 is primarily done either through the imperative QPainter API, |
| or through Qt’s declarative UI language, Qt Quick, and its scene graph back-end. |
| Qt 5's graphics capabilities also includes support for printing, as well as the |
| loading and saving of various image formats. |
| |
| |
| |
| \section1 2D Graphics with QPainter |
| |
| QPainter provides API for drawing vector graphics, text and images |
| onto different surfaces, or QPaintDevice instances, such as QImage, |
| QOpenGLPaintDevice, QWidget, and QPrinter. The actual drawing happens |
| in the QPaintDevice's QPaintEngine. The software rasterizer and the |
| OpenGL (ES) 2.0 back-ends are the two most important QPaintEngine |
| implementations. The raster paint engine is Qt’s software rasterizer, |
| and is used when drawing on a QImage or QWidget. Its strength over the |
| OpenGL paint engine is its high quality when antialiasing is enabled, |
| and a complete feature set. |
| |
| \sa {Paint System} |
| |
| \list |
| |
| \li \l {Paint System}{Paint System} - Overview over the QPainter |
| classes and architecture. |
| |
| \li \l {Coordinate System}{Coordinate System} - Explains how |
| QPainter's coordinate system works. |
| |
| \li \l {Drawing and Filling}{Drawing and Filling} - Explains how |
| QPainter performs filling and outlining of vector shapes. |
| |
| \endlist |
| |
| The most important rendering targets for QPainter are: |
| |
| \list |
| |
| \li \l {QImage}{QImage} - A hardware-independent image representation |
| with direct pixel access. QPainter will use the software |
| rasterizer to draw to QImage instances. |
| |
| \li \l {QPixmap}{QPixmap} - A image representation suited for display |
| on screen. QPainter will primarily use the software rasterizer to |
| draw to QPixmap instances. |
| |
| \li \l {QOpenGLPaintDevice}{QOpenGLPaintDevice} - A paint device to |
| render to the current OpenGL (ES) 2.0 context. QPainter will use |
| hardware accellerated OpenGL calls to draw to QOpenGLPaintDevice |
| instances. |
| |
| \li \l {QBackingStore}{QBackingStore} - A backbuffer for top-level |
| windows. QPainter will primarily use the software rasterizer to |
| draw to QBackingStore instances. |
| |
| \li \l {QWidget}{QWidget} - A baseclass for pre-Qt Quick user |
| interface classes. QPainter will render widgets using a |
| QBackingStore. |
| |
| \li \l {QOpenGLWidget}{QOpenGLWidget} - A painter can also be |
| opened on a QOpenGLWidget. This is provided as a convenience, since |
| technically this is no different than using QOpenGLPaintDevice. |
| |
| \endlist |
| |
| QPainter and related classes are part of the \l {Qt GUI} module. |
| |
| |
| |
| \section1 OpenGL and 3D |
| |
| OpenGL is the most widely adopted graphics API for hardware accelerated and 3D |
| graphics, implemented on all desktop platforms and almost every mobile and |
| embedded platform. The Qt library contains a number of classes that help users |
| integrate graphics driven by OpenGL or other graphics API calls into their |
| applications, as well as add-on modules for displaying 3D content. |
| |
| \list |
| |
| \li \l {qtgui-index.html#opengl-and-opengl-es-integration}{OpenGL |
| in Qt GUI} - An overview of how OpenGL integrates with the \l{Qt GUI} |
| module. |
| |
| \li \l {QOpenGLWidget}{QOpenGLWidget} is a widget that allows adding OpenGL |
| scenes into QWidget-based user interfaces. |
| |
| \li \l {Mixing Scene Graph and the native graphics API}{OpenGL and Qt Quick 2.0} |
| - How to integrate application-provided graphics commands |
| (OpenGL, Vulkan, Direct3D, etc.) into a Qt Quick scene graph. |
| |
| \li \l {http://www.khronos.org/opengl}{www.khronos.org/opengl} - |
| The official OpenGL pages. |
| |
| \li \l {Qt Quick 3D} - An add-on module that provides a high-level API for |
| creating 3D content or UIs based on Qt Quick. |
| |
| \li \l {Qt 3D} - An add-on module that provides functionality for near-realtime |
| simulation systems with support for 2D and 3D rendering, in both Qt C++ and |
| Qt Quick applications. |
| |
| \endlist |
| |
| Prior to Qt 5.0, OpenGL support in Qt was handled by the \l {Qt OpenGL} |
| module. This module is still present, but new code should aim to use |
| the new classes in the \l {Qt GUI} module. The classes are easily distinguisible |
| based on their names: Classes with the \c QGL prefix should not be used. Instead, |
| prefer the ones starting with \c QOpenGL. |
| |
| |
| |
| \section1 Qt Quick Scene Graph |
| |
| Qt Quick 2 introduces an OpenGL (ES) 2.0 scene graph for |
| rendering. It generally improves the performance of Qt Quick 2 |
| significantly compared to the QGraphicsView/QPainter-based approach |
| used in earlier versions. |
| |
| The scene graph is a graphical representation of the Item scene. It |
| can be thought of as a graphical deep copy, an independent structure |
| that contains enough information to render all the items. Once it has |
| been set up, it can be manipulated and rendered independently of the |
| state of the items. On many platforms, the scene graph will even be |
| rendered on a dedicated render thread while the GUI thread is |
| preparing the next frame's state. |
| |
| The scene graph is used when you import QtQuick 2.x in your QML |
| file, and use QQuickView to run it. |
| |
| \list |
| |
| \li \l {qtquick-visualcanvas-scenegraph.html}{Qt Quick Scene Graph} |
| - Overview of the Qt Quick Scene Graph architecture. |
| |
| \li \l {Scene Graph and Rendering} - Breakdown of the rendering of |
| each frame. |
| |
| \endlist |
| |
| Qt Quick can be mixed with raw OpenGL rendering by connecting to the |
| signals \l QQuickWindow::beforeRendering() or \l |
| QQuickWindow::afterRendering() which are emitted before and after the |
| Qt Quick scene graph is rendered, respectively. There signals are |
| emitted from the render thread (when applicable), and the connections |
| need to be direct. |
| |
| Qt Quick can also be rendered using \l{Qt Quick 2D Renderer}. This raster |
| paint engine enables rendering Qt Quick applications on platforms that |
| do not have OpenGL. |
| |
| \section1 Printing |
| |
| Qt supports printing both directly to actual printers, locally or on the |
| network, as well as producing PDF output. How to do printing with |
| Qt is described in detail on the \l {Qt Print Support} page. |
| |
| \section1 Images |
| |
| Qt supports convenient reading, writing, and manipulating of images through the |
| QImage class. In addition, for more fine grained control of how images are |
| loaded or saved, you can use the QImageReader and QImageWriter classes |
| respectively. To add support for additional image formats, outside of the ones |
| provided by Qt, you can create image format plugins by using QImageIOHandler |
| and QImageIOPlugin. |
| |
| See the \l {Reading and Writing Image Files} page for more information. |
| |
| */ |