1 /****************************************************************************
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
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.
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.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
43 \page qt-embedded-opengl.html
45 \title Qt for Embedded Linux and OpenGL
46 \ingroup qt-embedded-linux
48 \section1 Introduction
50 \l {http://www.opengl.org}{OpenGL} is an industry standard API for
51 2D/3D graphics. It provides a powerful, low-level interface between
52 software and acceleration hardware, and it is operating system and
53 window system independent.
55 \l {http://www.khronos.org/opengles}{OpenGL ES} is a subset
56 of the \l {http://www.opengl.org}{OpenGL} standard.
57 Because it is meant for use in embedded systems, it has a smaller,
60 For reference, Nokia provides a plugin which integrates \l
61 {http://www.khronos.org/opengles}{OpenGL ES} with Qt for Embedded Linux,
62 but Qt for Embedded Linux can be adapted to a wide range of OpenGL
65 There are three ways to use OpenGL with Qt for Embedded Linux:
67 \o Perform OpenGL 3D graphics operations in applications;
68 \o Accelerate normal 2D painting operations;
69 \o Implement window compositing and special effects.
72 Qt for Embedded Linux is shipped with a reference integration example
73 that demonstrates all three uses.
75 \section2 Using OpenGL 3D Graphics in Applications
77 The \l {QtOpenGL module} offers classes that make it easy to draw 3D
78 graphics in GUI applications. The module API is cross-platform, so it
79 is also available on Windows, X11, and Mac OS X.
81 To use OpenGL-enabled widgets in a Qt for Embedded Linux application,
82 all that is required is to subclass the QGLWidget and draw into instances of
83 the subclass with standard OpenGL functions.
85 \section2 Using OpenGL to Accelerate Normal 2D Painting
87 Qt provides QOpenGLPaintEngine, a subclass of QPaintEngine that
88 translates QPainter operations into OpenGL calls. This specialized
89 paint engine can be used to improve 2D rendering performance on
90 appropriate hardware. It can also overlay controls and decorations
91 onto 3D scenes drawn using OpenGL.
93 \section2 Using OpenGL to Implement Window Compositing and Effects
95 Qt for Embedded Linux includes a complete windowing system, which implements
96 real transparency. The windowing system can be accelerated using
97 OpenGL to implement top level window compositing. This makes it easy
98 to add 3D effects to applications, for instance when windows are
99 minimized or maximized.
101 \section1 Acceleration Architecture
103 The diagram below shows the Qt for Embedded Linux painting architecture.
105 \image qt-embedded-opengl3.png
107 A client process widget uses a paint engine to draw into a window
108 surface. The server then combines the window surfaces and displays the
109 composition on the screen. This architecture lets you
110 control the steps of the painting process by subclassing.
112 Subclassing QPaintEngine allows you to implement the QPainter API
113 using accelerated hardware. Subclassing QWindowSurface lets you
114 decide the properties of the space your widgets will draw themselves
115 into, as well as which paint engine they should use to draw themselves
116 into that space. Subclassing QScreen lets you control the creation of
117 window surfaces and lets you decide how to implement window
118 compositing. Using subclassing, your implementation work is minimized
119 since you can reuse base class functionality you don't need to change.
121 The elements of an accelerated Qt for Embedded Linux system are shown in the
124 \image qt-embedded-opengl1.png
126 The applications, using the Qt API, do not depend on the presence of
127 the acceleration plugin. The plugin uses the graphics hardware to
128 accelerate painting primitives. Any operations not accelerated by the
129 plugin are done in software by the software paint engine.
131 To integrate an OpenGL implementation into Qt for Embedded Linux for a
132 particular platform, you use the same mechanisms you would use for
133 writing any other accelerated driver. Base classes, e.g., QGLScreen
134 and QWSGLWindowSurface, are provided to minimize the need for
135 reimplementing common functionality.
137 \section1 The Reference Integration
139 The \l{OpenGL for Embedded Systems Example} is the reference implementation
140 for integrating OpenGL ES and \l{http://www.khronos.org/egl/}{EGL} with
141 the graphics acceleration architecture of Qt for Embedded Linux.
142 (\l{http://www.khronos.org/egl/}{EGL} is a library that binds OpenGL ES to
143 native windowing systems.)
145 The diagram below shows how OpenGL ES is used within the acceleration architecture:
147 \image qt-embedded-opengl2.png
149 The example implements a screen driver plugin that demonstrates all
150 three uses of OpenGL in Qt for Embedded Linux: 2D graphics acceleration, 3D
151 graphics operations using the \l {QtOpenGL module}, and top-level
152 window compositing and special effects. The applications still do
153 not talk directly to the accelerated plugin.
155 For 2D graphics, applications use the normal Qt painting API. The example accelerates 2D
156 painting by using the QOpenGLPaintEngine, which is included in the \l {QtOpenGL module}.
158 For 3D graphics applications use the OpenGL API directly, together with the functionality
159 in the Qt OpenGL support classes. The example supports this by creating a
160 QWSGLWindowSurface whenever a QGLWidget is instantiated.
162 All access to the display is done through OpenGL. The example subclasses
163 QWSGLWindowSurface implementation and uses the \l
164 {http://oss.sgi.com/projects/ogl-sample/registry/EXT/framebuffer_object.txt}
165 {OpenGL Framebuffer Object extension} to draw windows into an offscreen buffer. This
166 lets the example use OpenGL to implement top level window compositing of opaque and
167 semi-transparent windows, and to provide a 3D animated transition effect as each new
170 The specific OpenGL library being used by the example restricts all
171 OpenGL operations to occur in a single process. Hence the example
172 creates instances of QWSGLWindowSurface only in the server process.
173 Other processes then perform 2D graphics by creating instances
174 of the standard QWindowSurface classes for client processes. The
175 standard window surface performs software-based rendering into a
176 shared memory segment. The server then transfers the contents of this
177 shared memory into an OpenGL texture before they are drawn onto the
178 screen during window compositing.
182 \section1 Future Directions
184 \section2 API Improvements
186 Nokia is now working on enhancing the API for integrating OpenGL
187 with Qt for Embedded Linux. The current design plan includes the following
192 \o Provide convenience classes, e.g., QEGLScreen and
193 QWSEGLWindowSurface, which implement common uses of the EGL
194 API. These classes will simplify implementing an OpenGL ES
197 \o Extend the screen driver API to provide more control over window
198 properties and animations, and provide a software-based integration
199 to enable testing on the desktop.
201 \o Improve performance as opportunities arise.
205 \section2 OpenVG Support
207 \l {http://www.khronos.org/openvg} {OpenVG} is a dedicated API for 2D
208 graphics on mobile devices. It is therefore more likely to be a better
209 alternative for 2D acceleration than OpenGL. Until recently, no
210 OpenVG-capable hardware has been available, so Nokia has not yet
211 included an OpenVG solution in Qt for Embedded Linux.
213 However, Nokia has done a feasibility study, implementing an
214 OpenVG paint engine on top of a software OpenVG implementation.
215 Assuming availability of the appropriate hardware, this OpenVG paint
216 engine can easily be completed and integrated using the existing
217 acceleration architecture. Since OpenVG shares the same EGL layer as
218 OpenGL ES, the work already done on the OpenGL integration can be
221 Related technologies included in the \l
222 {http://www.khronos.org/openkode} {OpenKODE} API set will also be