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

Last change on this file since 846 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

  • Property svn:eol-style set to native
File size: 13.5 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 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:FDL$
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 a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \page openvg.html
30 \title OpenVG Rendering in Qt
31 \since 4.6
32 \ingroup best-practices
33 \ingroup technology-apis
34
35
36 \brief Efficient rendering on embedded devices with OpenVG
37
38 OpenVG is a standard API from the
39 \l{http://www.khronos.org/openvg}{Khronos Group} for accelerated
40 2D vector graphics that is appearing in an increasing number of
41 embedded devices. The QtOpenVG plugin provides support for OpenVG
42 painting.
43
44 OpenVG is optimized for 2D vector operations, and closely matches
45 the functionality in QPainter. It can therefore be an excellent
46 substitute for the default raster-based QPaintEngine on hardware
47 that supports OpenVG.
48
49 \tableofcontents
50
51 \section1 Building Qt with OpenVG support
52
53 OpenVG support can be enabled by passing the \c{-openvg} option
54 to configure. It is assumed that the following qmake variables
55 are set to appropriate values in the qmake.conf file for your
56 platform:
57
58 \list
59 \o QMAKE_INCDIR_OPENVG
60 \o QMAKE_LIBDIR_OPENVG
61 \o QMAKE_LIBS_OPENVG
62 \endlist
63
64 Most OpenVG implementations are based on EGL, so the following
65 variables may also need to be set:
66
67 \list
68 \o QMAKE_INCDIR_EGL
69 \o QMAKE_LIBDIR_EGL
70 \o QMAKE_LIBS_EGL
71 \endlist
72
73 See \l{qmake Variable Reference} for more information on these variables.
74
75 Two kinds of OpenVG engines are currently supported: EGL based,
76 and engines built on top of OpenGL such as
77 \l{http://sourceforge.net/projects/shivavg}{ShivaVG}.
78 EGL based engines are preferred.
79
80 It is assumed that the EGL implementation has some way to turn a
81 QWidget::winId() into an EGL rendering surface with
82 \c{eglCreateWindowSurface()}. If this is not the case, then
83 modifications may be needed to the code under \c{src/gui/egl} and
84 \c{src/plugins/graphicssystems/openvg} to accomodate the EGL
85 implementation.
86
87 The ShivaVG graphics system under \c{src/plugins/graphicssystems/shivavg}
88 is an example of how to integrate a non-EGL implementation of
89 OpenVG into Qt. It is currently only supported with Qt/X11
90 and being an example only, the resulting screen output may not
91 be as good as with other OpenVG engines.
92
93 \section1 Using the OpenVG graphics system
94
95 Once the graphics system plugin has been built and installed,
96 applications can be run as follows to use the plugin:
97
98 \code
99 app -graphicssystem OpenVG
100 \endcode
101
102 If ShivaVG is being used, then substitute \c ShivaVG instead of
103 \c OpenVG in the line above.
104
105 If the plugin fails to load, try setting the \c QT_DEBUG_PLUGINS
106 environment variable to 1 and try again. Usually the plugin
107 cannot be loaded because Qt cannot locate it in the directory
108 \c{plugins/graphicssystems} within the Qt installation, or the
109 dynamic library path does not include the directory containing
110 the system's \c libOpenVG.so library.
111
112 \section1 Supported features
113
114 \section2 Context modes
115
116 The default configuration is "single-context" mode, where a single
117 EGLContext object is used for all drawing, regardless of the surface.
118 Multiple EGLSurfaces are created, one for each window surface or pixmap.
119 eglMakeCurrent() is called with the same EGLContext every time, but a
120 different EGLSurface.
121
122 Single-context mode is necessary for QPixmapData to be implemented in
123 terms of a VGImage. If single-context mode is not enabled, then QPixmapData
124 will use the fallback QRasterPixmapData implementation, which is less
125 efficient performance-wise.
126
127 Single-context mode can be disabled with the QVG_NO_SINGLE_CONTEXT define
128 if the OpenVG engine does not support one context with multiple surfaces.
129
130 \section2 Transformation matrices
131
132 All affine and projective transformation matrices are supported.
133
134 QVGPaintEngine will use the engine to accelerate affine transformation
135 matrices only. When a projective transformation matrix is used,
136 QVGPaintEngine will transform the coordinates before passing them
137 to the engine. This will probably incur a performance penalty.
138
139 Pixmaps and images are always transformed by the engine, because
140 OpenVG specifies that projective transformations must work for images.
141
142 It is recommended that client applications should avoid using projective
143 transformations for non-image elements in performance critical code.
144
145 \section2 Composition modes
146
147 The following composition modes are supported:
148
149 \list
150 \o QPainter::CompositionMode_SourceOver
151 \o QPainter::CompositionMode_DestinationOver
152 \o QPainter::CompositionMode_Source
153 \o QPainter::CompositionMode_SourceIn
154 \o QPainter::CompositionMode_DestinationIn
155 \o QPainter::CompositionMode_Plus
156 \o QPainter::CompositionMode_Multiply
157 \o QPainter::CompositionMode_Screen
158 \o QPainter::CompositionMode_Darken
159 \o QPainter::CompositionMode_Lighten
160 \endlist
161
162 The other members of QPainter::CompositionMode are not supported
163 unless the \c{VG_KHR_advanced_blending} extension is present,
164 in which case the following additional modes are supported:
165
166 \list
167 \o QPainter::CompositionMode_Overlay
168 \o QPainter::CompositionMode_ColorDodge
169 \o QPainter::CompositionMode_ColorBurn
170 \o QPainter::CompositionMode_HardLight
171 \o QPainter::CompositionMode_SoftLight
172 \o QPainter::CompositionMode_Difference
173 \o QPainter::CompositionMode_Exclusion
174 \o QPainter::CompositionMode_SourceOut
175 \o QPainter::CompositionMode_DestinationOut
176 \o QPainter::CompositionMode_SourceAtop
177 \o QPainter::CompositionMode_DestinationAtop
178 \o QPainter::CompositionMode_Xor
179 \endlist
180
181 Any attempt to set an unsupported mode will result in
182 the actual mode being set to QPainter::CompositionMode_SourceOver.
183 Client applications should avoid using unsupported modes.
184
185 \section2 Pens and brushes
186
187 All pen styles are supported, including cosmetic pens.
188
189 All brush styles are supported except for conical gradients, which are
190 not supported by OpenVG 1.1. Conical gradients will be converted into a
191 solid color brush corresponding to the first color in the gradient's
192 color ramp.
193
194 Affine matrices are supported for brush transforms, but not projective
195 matrices.
196
197 \section2 Rectangles, lines, and points
198
199 Rectangles, lines, and rounded rectangles use cached VGPath objects
200 to try to accelerate drawing operations. vgModifyPathCoords() is used
201 to modify the co-ordinates in the cached VGPath object each time
202 fillRect(), drawRects(), drawLines(), or drawRoundedRect() is called.
203
204 If the engine does not implement vgModifyPathCoords() properly, then the
205 QVG_NO_MODIFY_PATH define can be set to disable path caching. This will
206 incur a performance penalty.
207
208 Points are implemented as lines from the point to itself. The cached
209 line drawing VGPath object is used when drawing points.
210
211 \section2 Polygons and Ellipses
212
213 Polygon and ellipse drawing creates a new VGPath object every time
214 drawPolygon() or drawEllipse() is called. If the client application is
215 making heavy use of these functions, the constant creation and destruction
216 of VGPath objects could have an impact on performance.
217
218 If a projective transformation is active, ellipses are converted into
219 cubic curves prior to transformation, which may further impact performance.
220
221 Client applications should avoid polygon and ellipse drawing in performance
222 critical code if possible.
223
224 \section2 Other Objects
225
226 Most other objects (arcs, pies, etc) use drawPath(), which takes a
227 QPainterPath argument. The default implementation in QPainterEngineEx
228 converts the QPainterPath into a QVectorPath and then calls draw(),
229 which in turn converts the QVectorPath into a VGPath for drawing.
230
231 To reduce the overhead, we have overridden drawPath() in QVGPaintEngine
232 to convert QPainterPath's directly into VGPath's. This should help improve
233 performance compared to the default implementation.
234
235 Client applications should try to avoid these types of objects in
236 performance critical code because of the QPainterPath to VGPath
237 conversion cost.
238
239 \section2 Clipping
240
241 Clipping with QRect, QRectF, and QRegion objects is supported on all
242 OpenVG engines with vgMask() if the transformation matrix is the identity
243 or a simple origin translation.
244
245 Clipping with an arbitrary QPainterPath, or setting the clip region when
246 the transformation matrix is simple, is supported only if the OpenVG engine
247 has the vgRenderToMask() function (OpenVG 1.1 and higher).
248
249 The QVG_NO_RENDER_TO_MASK define will disable the use of vgRenderToMask().
250
251 The QVG_SCISSOR_CLIP define will disable clipping with vgMask() or
252 vgRenderToMask() and instead use the scissor rectangle list to perform
253 clipping. Clipping with an arbitrary QPainterPath will need to convert
254 the path into a series of rectangles. If the number of rectangles
255 exceeds VG_MAX_SCISSOR_RECTS, then the results will not be exact.
256
257 The QVG_SCISSOR_CLIP define should only be used if the OpenVG engine
258 does not support vgMask() or vgRenderToMask().
259
260 \section2 Opacity
261
262 Opacity is supported for all drawing operations. Solid color pens,
263 solid color brushes, gradient brushes, and image drawing with drawPixmap()
264 and drawImage() will probably have the best performance compared to
265 other kinds of pens and brushes.
266
267 \section2 Text Drawing
268
269 If OpenVG 1.1 is used, the paint engine will use VG fonts to cache glyphs
270 while drawing. If the engine does not support VG fonts correctly,
271 QVG_NO_DRAW_GLYPHS can be defined to disable this mode. Text drawing
272 performance will suffer if VG fonts are not used.
273
274 By default, image-based glyphs are used. If QVG_NO_IMAGE_GLYPHS is defined,
275 then path-based glyphs will be used instead. QVG_NO_IMAGE_GLYPHS is ignored
276 if QVG_NO_DRAW_GLYPHS is defined.
277
278 If path-based glyphs are used, then the OpenVG engine will need to
279 support hinting to render text with good results. Image-based glyphs
280 avoids the need for hinting and will usually give better results than
281 path-based glyphs.
282
283 \section2 Pixmaps
284
285 In single-context mode, pixmaps will be implemented using VGImage
286 unless QVG_NO_PIXMAP_DATA is defined.
287
288 QVGPixmapData will convert QImage's into VGImage's when the application
289 calls drawPixmap(), and the pixmap will be kept in VGImage form for the
290 lifetime of the QVGPixmapData object. When the application tries to paint
291 into a QPixmap with QPainter, the data will be converted back into a
292 QImage and the raster paint engine will be used to render into the QImage.
293
294 This arrangement optimizes for the case of drawing the same static pixmap
295 over and over (e.g. for icons), but does not optimize the case of drawing
296 into pixmaps.
297
298 Bitmaps must use QRasterPixmapData. They are not accelerated with
299 VGImage at present.
300
301 \section2 Pixmap filters
302
303 Convolution, colorize, drop shadow, and blur filters are accelerated
304 using OpenVG operations.
305
306 \section2 Scrolling
307
308 By default, accelerated scrolling is not enabled because the impact on
309 performance is very much tied to the hardware platform. To enable
310 accelerated scrolling, you should ensure that QVG_BUFFER_SCROLLING is
311 defined when compiling the QtOpenVG module.
312
313 You should only enable this feature if vgCopyPixels() is known to be
314 efficient on your hardware platform.
315
316 \section1 Known issues
317
318 Performance of copying the contents of an OpenVG-rendered window to the
319 screen needs platform-specific work in the QVGWindowSurface class.
320
321 Clipping with arbitrary non-rectangular paths only works on engines
322 that support vgRenderToMask(). Simple rectangular paths are supported
323 on all engines that correctly implement vgMask().
324
325 The paint engine is not yet thread-safe, so it is not recommended for
326 use in threaded Qt applications that draw from multiple threads.
327 Drawing should be limited to the main GUI thread.
328
329 Performance of projective matrices for non-image drawing is not as good
330 as for affine matrices.
331
332 QPixmap's are implemented as VGImage objects so that they can be quickly
333 rendered with drawPixmap(). Rendering into a QPixmap using QPainter
334 will use the default Qt raster paint engine on a QImage copy of the
335 QPixmap, and will not be accelerated. This issue may be addressed in
336 a future version of the engine.
337
338 ShivaVG support is highly experimental and limited to Qt/X11. It is
339 provided as an example of how to integrate a non-EGL engine.
340*/
Note: See TracBrowser for help on using the repository browser.