Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-opengl-EmbLinux.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29 \page qt-embeddedLinux-opengl.html
30
31 \title Qt for Embedded Linux and OpenGL
32
33 \ingroup qt-embedded-linux
34
35 \input platforms/emb-opengl.qdocinc
36
37 \section1 Using OpenGL with Qt for Embedded Linux
38 Qt for Embedded Linux provides support for integrating OpenGL ES for
39 drawing into a QGLWidget. The current implementation supports OpenGL and 2D
40 painting within a QGLWidget. Using OpenGL to accelerate regular widgets and
41 compositing top-level windows with OpenGL are not currently supported.
42
43 \note OpenGL rendering only works with QGLWidget under QWS.  Regular
44 widgets cannot currently support it.
45
46 \section2 Configure
47
48 It is recommended that Qt for Embedded Linux is configured with the
49 \c{-DQT_QWS_CLIENTBLIT} and \c{-DQT_NO_QWS_CURSOR} options for optimum
50 performance.  OpenGL is rendered direct to the screen and these options
51 prevent Qt for Embedded Linux from trying to do its own non-OpenGL
52 compositing on the QGLWidget contents.
53
54 \section2 Using OpenGL to Implement Window Compositing and Effects
55
56 Compositing effects can be simulated by adjusting the opacity and other
57 parameters of the items within a QGraphicsView canvas on a QGLWidget
58 viewport.
59
60 While Qt for Embedded Linux does include a complete windowing system,
61 using OpenGL to composite regular window surfaces can be quite difficult.
62 Most of Qt for Embedded Linux assumes that the window surface is a plain
63 raster memory buffer, with QGLWidget being the sole exception.
64 The need to constantly re-upload the raster memory buffers into OpenGL
65 textures for compositing can have a significant impact on performance,
66 which is why we do not recommend implementing that form of compositing.
67 We intend to address this problem in future versions of Qt.
68
69 \section1 Integrating OpenGL/ES into Qt for Embedded Linux
70 \section2 Reference Integration
71 The reference integration for OpenGL into Qt for Embedded Linux is for the
72 PowerVR chipset from \l{http://www.imgtec.com/}{Imagination Technologies}.
73 It consists of two components: \c{pvreglscreen}, which provides the Qt for
74 Embedded Linux screen driver, and \c{QWSWSEGL}, which implements a plug-in
75 to the PowerVR EGL implementation to implement low-level OpenGL drawing
76 surfaces.
77
78 \section2 Integrating Other Chipsets
79 In this section, we discuss the essential features of the reference
80 integration that need to be provided for any other chipset integration.
81
82 The QtOpenGL module assumes that a QGLWidget can be represented
83 by an \c EGLNativeWindowType value in some underlying window system
84 implementation, and that \c{eglSwapBuffers()} is sufficient to copy
85 the contents of the native window to the screen when requested.
86
87 However, many EGL implementations do not have a pre-existing window system.
88 Usually only a single full-screen window is provided, and everything else
89 must be simulated some other way.  This can be a problem because
90 of QtOpenGL's assumptions.  We intend to address these assumptions in a
91 future version of Qt, but for now, it is the responsibility of the integrator
92 to provide a rudimentary window system within the EGL implementation.
93 This is the purpose of \c{QWSWSEGL} in the reference integration.
94
95 If it isn't possible for the EGL implementation to provide a rudimentary
96 window system, then full-screen windows using QGLWidget can be supported,
97 but very little else.
98
99 The screen driver needs to inherit from QGLScreen and perform the
100 following operations in its constructor:
101
102 \snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 0
103
104 The \c{setSurfaceFunctions()} call supplies an object that takes care
105 of converting Qt paint devices such as widgets and pixmaps into
106 \c EGLNativeWindowType and \c EGLNativePixmapType values.  Here we
107 only support native windows.  Because OpenGL rendering is direct to
108 the screen, we also indicate that client blit is supported.
109
110 Next, we override the \c{createSurface()} functions in QGLScreen:
111
112 \snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 1
113
114 Even if Qt for Embedded Linux is used in single-process mode, it is
115 necessary to create both client-side and server-side versions of the
116 window surface.  In our case, the server-side is just a stub because
117 the client side directly renders to the screen.
118
119 Note that we only create a \c{PvrEglWindowSurface} if the widget is a
120 QGLWidget.  All other widgets use the normal raster processing.
121 It can be tempting to make \c{createSurface()} create an OpenGL
122 window surface for other widget types as well.  This has not been
123 extensively tested and we do not recommend its use at this time.
124
125 The other main piece is the creation of the \c EGLNativeWindowType
126 value for the widget.  This is done in the \c{createNativeWindow()}
127 override:
128
129 \snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 2
130
131 The details of what needs to be placed in this function will vary
132 from chipset to chipset.  The simplest is to return the native window
133 handle corresponding to the "root" full-screen window:
134
135 \code
136 *native = rootWindowHandle;
137 return true;
138 \endcode
139
140 The most common value for \c rootWindowHandle is zero, but this may
141 not always be the case.  Consult the chipset documentation for the
142 actual value to use.  The important thing is that whatever value is
143 returned must be suitable for passing to the \c{eglCreateWindowSurface()}
144 function of the chipset's EGL implementation.
145
146 In the case of PowerVR, the rudimentary window system in \c{QWSWSEGL}
147 provides a \c PvrQwsDrawable object to represent the \c EGLNativeWindowType
148 value for the widget.
149
150 */