source: trunk/doc/src/howtos/openvg.qdoc@ 603

Last change on this file since 603 was 561, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.1 sources.

  • Property svn:eol-style set to native
File size: 13.3 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \page openvg.html
44 \title OpenVG Rendering in Qt
45 \since 4.6
46 \ingroup best-practices
47
48 \brief Efficient rendering on embedded devices with OpenVG
49
50 OpenVG is a standard API from the
51 \l{http://www.khronos.org/openvg}{Khronos Group} for accelerated
52 2D vector graphics that is appearing in an increasing number of
53 embedded devices. The QtOpenVG plugin provides support for OpenVG
54 painting.
55
56 OpenVG is optimized for 2D vector operations, and closely matches
57 the functionality in QPainter. It can therefore be an excellent
58 substitute for the default raster-based QPaintEngine on hardware
59 that supports OpenVG.
60
61 \tableofcontents
62
63 \section1 Building Qt with OpenVG support
64
65 OpenVG support can be enabled by passing the \c{-openvg} option
66 to configure. It is assumed that the following qmake variables
67 are set to appropriate values in the qmake.conf file for your
68 platform:
69
70 \list
71 \o QMAKE_INCDIR_OPENVG
72 \o QMAKE_LIBDIR_OPENVG
73 \o QMAKE_LIBS_OPENVG
74 \endlist
75
76 Most OpenVG implementations are based on EGL, so the following
77 variables may also need to be set:
78
79 \list
80 \o QMAKE_INCDIR_EGL
81 \o QMAKE_LIBDIR_EGL
82 \o QMAKE_LIBS_EGL
83 \endlist
84
85 See \l{qmake Variable Reference} for more information on these variables.
86
87 Two kinds of OpenVG engines are currently supported: EGL based,
88 and engines built on top of OpenGL such as
89 \l{http://sourceforge.net/projects/shivavg}{ShivaVG}.
90 EGL based engines are preferred.
91
92 It is assumed that the EGL implementation has some way to turn a
93 QWidget::winId() into an EGL rendering surface with
94 \c{eglCreateWindowSurface()}. If this is not the case, then
95 modifications may be needed to the code under \c{src/gui/egl} and
96 \c{src/plugins/graphicssystems/openvg} to accomodate the EGL
97 implementation.
98
99 The ShivaVG graphics system under \c{src/plugins/graphicssystems/shivavg}
100 is an example of how to integrate a non-EGL implementation of
101 OpenVG into Qt. It is currently only supported with Qt/X11
102 and being an example only, the resulting screen output may not
103 be as good as with other OpenVG engines.
104
105 \section1 Using the OpenVG graphics system
106
107 Once the graphics system plugin has been built and installed,
108 applications can be run as follows to use the plugin:
109
110 \code
111 app -graphicssystem OpenVG
112 \endcode
113
114 If ShivaVG is being used, then substitute \c ShivaVG instead of
115 \c OpenVG in the line above.
116
117 If the plugin fails to load, try setting the \c QT_DEBUG_PLUGINS
118 environment variable to 1 and try again. Usually the plugin
119 cannot be loaded because Qt cannot locate it in the directory
120 \c{plugins/graphicssystems} within the Qt installation, or the
121 dynamic library path does not include the directory containing
122 the system's \c libOpenVG.so library.
123
124 \section1 Supported features
125
126 \section2 Context modes
127
128 The default configuration is "single-context" mode, where a single
129 EGLContext object is used for all drawing, regardless of the surface.
130 Multiple EGLSurfaces are created, one for each window surface or pixmap.
131 eglMakeCurrent() is called with the same EGLContext every time, but a
132 different EGLSurface.
133
134 Single-context mode is necessary for QPixmapData to be implemented in
135 terms of a VGImage. If single-context mode is not enabled, then QPixmapData
136 will use the fallback QRasterPixmapData implementation, which is less
137 efficient performance-wise.
138
139 Single-context mode can be disabled with the QVG_NO_SINGLE_CONTEXT define
140 if the OpenVG engine does not support one context with multiple surfaces.
141
142 \section2 Transformation matrices
143
144 All affine and projective transformation matrices are supported.
145
146 QVGPaintEngine will use the engine to accelerate affine transformation
147 matrices only. When a projective transformation matrix is used,
148 QVGPaintEngine will transform the coordinates before passing them
149 to the engine. This will probably incur a performance penalty.
150
151 Pixmaps and images are always transformed by the engine, because
152 OpenVG specifies that projective transformations must work for images.
153
154 It is recommended that client applications should avoid using projective
155 transformations for non-image elements in performance critical code.
156
157 \section2 Composition modes