doc/src/qtopiacore-opengl.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   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
  14 ** this package.
  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 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43 \page qt-embedded-opengl.html
  44
  45 \title Qt for Embedded Linux and OpenGL
  46 \ingroup qt-embedded-linux
  47
  48 \section1 Introduction
  49
  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.
  54
  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,
  58 more constrained API.
  59
  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
  63 versions.
  64
  65 There are three ways to use OpenGL with Qt for Embedded Linux:
  66 \list
  67   \o Perform OpenGL 3D graphics operations in applications;
  68   \o Accelerate normal 2D painting operations;
  69   \o Implement window compositing and special effects.
  70 \endlist
  71
  72 Qt for Embedded Linux is shipped with a reference integration example
  73 that demonstrates all three uses.
  74
  75 \section2 Using OpenGL 3D Graphics in Applications
  76
  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.
  80
  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.
  84
  85 \section2 Using OpenGL to Accelerate Normal 2D Painting
  86
  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.
  92
  93 \section2 Using OpenGL to Implement Window Compositing and Effects
  94
  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.
 100
 101 \section1 Acceleration Architecture
 102
 103 The diagram below shows the Qt for Embedded Linux painting architecture.
 104
 105 \image qt-embedded-opengl3.png
 106
 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.
 111
 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.
 120
 121 The elements of an accelerated Qt for Embedded Linux system are shown in the
 122 diagram below.
 123
 124 \image qt-embedded-opengl1.png
 125
 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.
 130
 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.
 136
 137 \section1 The Reference Integration
 138
 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.)
 144
 145 The diagram below shows how OpenGL ES is used within the acceleration architecture:
 146
 147 \image qt-embedded-opengl2.png
 148
 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.
 154
 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}.
 157
 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.
 161
 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
 168 window is shown.
 169
 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.
 179
 180 \omit
 181
 182 \section1 Future Directions
 183
 184 \section2 API Improvements
 185
 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
 188 features:
 189
 190 \list
 191
 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
 195   integration.
 196
 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.
 200
 201   \o Improve performance as opportunities arise.
 202
 203 \endlist
 204
 205 \section2 OpenVG Support
 206
 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.
 212
 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
 219 reused.
 220
 221 Related technologies included in the \l
 222 {http://www.khronos.org/openkode} {OpenKODE} API set will also be
 223 considered.
 224
 225 \endomit
 226
 227 */