Update copyright headers
[qt:qt.git] / doc / src / examples / hellogl_es.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     \example opengl/hellogl_es
30     \title Hello GL ES Example
31
32     \brief The Hello GL ES example is the \l{Hello GL Example} ported to OpenGL ES.
33     It also included some effects from the OpenGL \l{Overpainting Example}.
34
35     \image hellogl-es-example.png
36
37     A complete introduction to OpenGL ES and a description of all differences
38     between OpenGL and OpenGL ES is out of the scope of this document; but
39     we will describe some of the major issues and differences.
40
41     Since Hello GL ES is a direct port of standard OpenGL code, it is a fairly
42     good example for porting OpenGL code to OpenGL ES.
43
44     \tableofcontents
45
46     \section1 Using QGLWidget
47
48     QGLWidget can be used for OpenGL ES similar to the way it is used with
49     standard OpenGL; but there are some differences. We use EGL 1.0 to embedd
50     the OpenGL ES window within the native window manager. In
51     QGLWidget::initializeGL() we initialize OpenGL ES.
52
53     \section1 Porting OpenGL to OpenGL ES
54
55     Since OpenGL ES is missing the immediate mode and does not support quads,
56     we have to create triangle arrays.
57
58     We create a quad by adding vertices to a QList of vertices. We create both
59     sides of the quad and hardcode a distance of 0.05f. We also compute the
60     correct normal for each face and store them in another QList.
61
62     \snippet examples/opengl/hellogl_es/glwidget.cpp 0
63
64     And then we convert the complete list of vertexes and the list of normals
65     into the native OpenGL ES format that we can use with the OpenGL ES API.
66
67     \snippet examples/opengl/hellogl_es/glwidget.cpp 1
68
69     In \c paintQtLogo() we draw the triangle array using OpenGL ES. We use
70     q_vertexTypeEnum to abstract the fact that our vertex and normal arrays
71     are either in float or in fixed point format.
72
73     \snippet examples/opengl/hellogl_es/glwidget.cpp 2
74
75     \section1 Using QGLPainter
76
77     Since the \c QGLPainter is slower for OpenGL ES we paint the bubbles with
78     the rasterizer and cache them in a QImage. This happends only once during
79     the initialiazation.
80
81     \snippet examples/opengl/hellogl_es/bubble.cpp 0
82
83     For each bubble this QImage is then drawn to the QGLWidget by using the
84     according QPainter with transparency enabled.
85
86     \snippet examples/opengl/hellogl_es/bubble.cpp 1
87
88     Another difference beetwen OpenGL and OpenGL ES is that OpenGL ES does not
89     support glPushAttrib(GL_ALL_ATTRIB_BITS). So we have to restore all the
90     OpenGL states ourselves, after we created the QPainter in
91     GLWidget::paintGL().
92
93     \snippet examples/opengl/hellogl_es/glwidget.cpp 3
94
95     Setting up up the model view matrix and setting the right OpenGL states is
96     done in the same way as for standard OpenGL.
97
98     \snippet examples/opengl/hellogl_es/glwidget.cpp 4
99
100     Now we have to restore the OpenGL state for the QPainter. This is not done
101     automatically for OpenGL ES.
102
103     \snippet examples/opengl/hellogl_es/glwidget.cpp 5
104
105     Now we use the QPainter to draw the transparent bubbles.
106
107     \snippet examples/opengl/hellogl_es/glwidget.cpp 6
108
109     In the end, we calculate the framerate and display it using the QPainter
110     again.
111
112     \snippet examples/opengl/hellogl_es/glwidget.cpp 7
113
114     After we finished all the drawing operations we swap the screen buffer.
115
116     \snippet examples/opengl/hellogl_es/glwidget.cpp 8
117
118     \section1 Summary
119
120     Similar to the \l{Hello GL Example}, we subclass QGLWidget to render
121     a 3D scene using OpenGL ES calls. QGLWidget is a subclass of QWidget.
122     Hence, its \l{QGLWidget}'s subclasses can be placed in layouts and
123     provided with interactive features just like normal custom widgets.
124
125     QGLWidget allows pure OpenGL ES rendering to be mixed with QPainter calls,
126     but care must be taken to maintain the state of the OpenGL ES
127     implementation.
128 */