diff options
Diffstat (limited to 'doc/src/qtopenvg.qdoc')
| -rw-r--r-- | doc/src/qtopenvg.qdoc | 324 |
1 files changed, 0 insertions, 324 deletions
diff --git a/doc/src/qtopenvg.qdoc b/doc/src/qtopenvg.qdoc deleted file mode 100644 index 9f0df5815..000000000 --- a/doc/src/qtopenvg.qdoc +++ /dev/null @@ -1,324 +0,0 @@ -/**************************************************************************** -** -** 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://qt.nokia.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. - */ |