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 | */
|
---|