diff options
Diffstat (limited to 'doc/src/qtopenvg.qdoc')
| -rw-r--r-- | doc/src/qtopenvg.qdoc | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/doc/src/qtopenvg.qdoc b/doc/src/qtopenvg.qdoc new file mode 100644 index 0000000..38be288 --- /dev/null +++ b/doc/src/qtopenvg.qdoc @@ -0,0 +1,324 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtOpenVG + \title QtOpenVG Module + \since 4.6 + \contentspage Qt's Modules + \previouspage QtOpenGL + \nextpage QtScript + \ingroup modules + + \brief The QtOpenVG module provides support classes for OpenVG painting. + + \tableofcontents + + OpenVG is a standard API from the + \l{http://www.khronos.org/openvg}{Khronos Group} for accelerated + 2D vector graphics that is appearing in an increasing number of + embedded devices. + + OpenVG is optimized for 2D vector operations, and closely matches + the functionality in QPainter. It can therefore be an excellent + substitute for the default raster-based QPaintEngine on hardware + that supports OpenVG. + + \section1 Building Qt with OpenVG support + + OpenVG support can be enabled by passing the \c{-openvg} option + to configure. It is assumed that the following qmake variables + are set to appropriate values in the qmake.conf file for your + platform: + + \list + \o QMAKE_INCDIR_OPENVG + \o QMAKE_LIBDIR_OPENVG + \o QMAKE_LIBS_OPENVG + \endlist + + Most OpenVG implementations are based on EGL, so the following + variables may also need to be set: + + \list + \o QMAKE_INCDIR_EGL + \o QMAKE_LIBDIR_EGL + \o QMAKE_LIBS_EGL + \endlist + + See \l{qmake Variable Reference} for more information on these variables. + + Two kinds of OpenVG engines are currently supported: EGL based, + and engines built on top of OpenGL such as + \l{http://sourceforge.net/projects/shivavg}{ShivaVG}. + EGL based engines are preferred. + + It is assumed that the EGL implementation has some way to turn a + QWidget::winId() into an EGL rendering surface with + \c{eglCreateWindowSurface()}. If this is not the case, then + modifications may be needed to the code under \c{src/gui/egl} and + \c{src/plugins/graphicssystems/openvg} to accomodate the EGL + implementation. + + The ShivaVG graphics system under \c{src/plugins/graphicssystems/shivavg} + is an example of how to integrate a non-EGL implementation of + OpenVG into Qt. It is currently only supported with Qt/X11 + and being an example only, the resulting screen output may not + be as good as with other OpenVG engines. + + \section1 Using the OpenVG graphics system + + Once the graphics system plugin has been built and installed, + applications can be run as follows to use the plugin: + + \code + app -graphicssystem OpenVG + \endcode + + If ShivaVG is being used, then substitute \c ShivaVG instead of + \c OpenVG in the line above. + + If the plugin fails to load, try setting the \c QT_DEBUG_PLUGINS + environment variable to 1 and try again. Usually the plugin + cannot be loaded because Qt cannot locate it in the directory + \c{plugins/graphicssystems} within the Qt installation, or the + dynamic library path does not include the directory containing + the system's \c libOpenVG.so library. + + \section1 Supported features + + \section2 Context modes + + The default configuration is "single-context" mode, where a single + EGLContext object is used for all drawing, regardless of the surface. + Multiple EGLSurfaces are created, one for each window surface or pixmap. + eglMakeCurrent() is called with the same EGLContext every time, but a + different EGLSurface. + + Single-context mode is necessary for QPixmapData to be implemented in + terms of a VGImage. If single-context mode is not enabled, then QPixmapData + will use the fallback QRasterPixmapData implementation, which is less + efficient performance-wise. + + Single-context mode can be disabled with the QVG_NO_SINGLE_CONTEXT define + if the OpenVG engine does not support one context with multiple surfaces. + + \section2 Transformation matrices + + All affine and projective transformation matrices are supported. + + QVGPaintEngine will use the engine to accelerate affine transformation + matrices only. When a projective transformation matrix is used, + QVGPaintEngine will transform the coordinates before passing them + to the engine. This will probably incur a performance penalty. + + Pixmaps and images are always transformed by the engine, because + OpenVG specifies that projective transformations must work for images. + + It is recommended that client applications should avoid using projective + transformations for non-image elements in performance critical code. + + \section2 Composition modes + + The following composition modes are supported: + + \list + \o QPainter::CompositionMode_SourceOver + \o QPainter::CompositionMode_DestinationOver + \o QPainter::CompositionMode_Source + \o QPainter::CompositionMode_SourceIn + \o QPainter::CompositionMode_DestinationIn + \o QPainter::CompositionMode_Plus + \o QPainter::CompositionMode_Multiply + \o QPainter::CompositionMode_Screen + \o QPainter::CompositionMode_Darken + \o QPainter::CompositionMode_Lighten + \endlist + + The other members of QPainter::CompositionMode are not supported + because OpenVG 1.1 does not have an equivalent in its \c VGBlendMode + enumeration. Any attempt to set an unsupported mode will result in + the actual mode being set to QPainter::CompositionMode_SourceOver. + Client applications should avoid using unsupported modes. + + \section2 Pens and brushes + + All pen styles are supported, including cosmetic pens. + + All brush styles are supported except for conical gradients, which are + not supported by OpenVG 1.1. Conical gradients will be converted into a + solid color brush corresponding to the first color in the gradient's + color ramp. + + Affine matrices are supported for brush transforms, but not projective + matrices. + + \section2 Rectangles, lines, and points + + Rectangles and lines use cached VGPath objects to try to accelerate + drawing operations. vgModifyPathCoords() is used to modify the + co-ordinates in the cached VGPath object each time fillRect(), + drawRects(), or drawLines() is called. + + If the engine does not implement vgModifyPathCoords() properly, then the + QVG_NO_MODIFY_PATH define can be set to disable path caching. This will + incur a performance penalty. + + Points are implemented as lines from the point to itself. The cached + line drawing VGPath object is used when drawing points. + + \section2 Polygons and Ellipses + + Polygon and ellipse drawing creates a new VGPath object every time + drawPolygon() or drawEllipse() is called. If the client application is + making heavy use of these functions, the constant creation and destruction + of VGPath objects could have an impact on performance. + + If a projective transformation is active, ellipses are converted into + cubic curves prior to transformation, which may further impact performance. + + Client applications should avoid polygon and ellipse drawing in performance + critical code if possible. + + \section2 Other Objects + + Most other objects (arcs, pies, etc) use drawPath(), which takes a + QPainterPath argument. The default implementation in QPainterEngineEx + converts the QPainterPath into a QVectorPath and then calls draw(), + which in turn converts the QVectorPath into a VGPath for drawing. + + To reduce the overhead, we have overridden drawPath() in QVGPaintEngine + to convert QPainterPath's directly into VGPath's. This should help improve + performance compared to the default implementation. + + Client applications should try to avoid these types of objects in + performance critical code because of the QPainterPath to VGPath + conversion cost. + + \section2 Clipping + + Clipping with QRect, QRectF, and QRegion objects is supported on all + OpenVG engines with vgMask() if the transformation matrix is the identity + or a simple origin translation. + + Clipping with an arbitrary QPainterPath, or setting the clip region when + the transformation matrix is simple, is supported only if the OpenVG engine + has the vgRenderToMask() function (OpenVG 1.1 and higher). + + The QVG_NO_RENDER_TO_MASK define will disable the use of vgRenderToMask(). + + The QVG_SCISSOR_CLIP define will disable clipping with vgMask() or + vgRenderToMask() and instead use the scissor rectangle list to perform + clipping. Clipping with an arbitrary QPainterPath will not be supported. + The QVG_SCISSOR_CLIP define should only be used if the OpenVG engine + does not support vgMask() or vgRenderToMask(). + + \section2 Opacity + + Opacity is supported for all drawing operations. Solid color pens, + solid color brushes, gradient brushes, and image drawing with drawPixmap() + and drawImage() will probably have the best performance compared to + other kinds of pens and brushes. + + \section2 Text Drawing + + If OpenVG 1.1 is used, the paint engine will use VG fonts to cache glyphs + while drawing. If the engine does not support VG fonts correctly, + QVG_NO_DRAW_GLYPHS can be defined to disable this mode. Text drawing + performance will suffer if VG fonts are not used. + + By default, image-based glyphs are used. If QVG_NO_IMAGE_GLYPHS is defined, + then path-based glyphs will be used instead. QVG_NO_IMAGE_GLYPHS is ignored + if QVG_NO_DRAW_GLYPHS is defined. + + If path-based glyphs are used, then the OpenVG engine will need to + support hinting to render text with good results. Image-based glyphs + avoids the need for hinting and will usually give better results than + path-based glyphs. + + \section2 Pixmaps + + In single-context mode, pixmaps will be implemented using VGImage + unless QVG_NO_PIXMAP_DATA is defined. + + QVGPixmapData will convert QImage's into VGImage's when the application + calls drawPixmap(), and the pixmap will be kept in VGImage form for the + lifetime of the QVGPixmapData object. When the application tries to paint + into a QPixmap with QPainter, the data will be converted back into a + QImage and the raster paint engine will be used to render into the QImage. + + This arrangement optimizes for the case of drawing the same static pixmap + over and over (e.g. for icons), but does not optimize the case of drawing + into pixmaps. + + Bitmaps must use QRasterPixmapData. They are not accelerated with + VGImage at present. + + \section2 Pixmap filters + + Convolution, colorize, and drop shadow filters are accelerated using + OpenVG operations. + + \section1 Known issues + + Performance of copying the contents of an OpenVG-rendered window to the + screen needs platform-specific work in the QVGWindowSurface class. + + Clipping with arbitrary non-rectangular paths only works on engines + that support vgRenderToMask(). Simple rectangular paths are supported + on all engines that correctly implement vgMask(). + + The paint engine is not yet thread-safe, so it is not recommended for + use in threaded Qt applications that draw from multiple threads. + Drawing should be limited to the main GUI thread. + + Performance of projective matrices for non-image drawing is not as good + as for affine matrices. + + QPixmap's are implemented as VGImage objects so that they can be quickly + rendered with drawPixmap(). Rendering into a QPixmap using QPainter + will use the default Qt raster paint engine on a QImage copy of the + QPixmap, and will not be accelerated. This issue may be addressed in + a future version of the engine. + + ShivaVG support is highly experimental and limited to Qt/X11. It is + provided as an example of how to integrate a non-EGL engine. + */ |