diff options
Diffstat (limited to 'examples/opengl/doc/src/hellogles3.qdoc')
-rw-r--r-- | examples/opengl/doc/src/hellogles3.qdoc | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/examples/opengl/doc/src/hellogles3.qdoc b/examples/opengl/doc/src/hellogles3.qdoc new file mode 100644 index 0000000000..d85f40a29f --- /dev/null +++ b/examples/opengl/doc/src/hellogles3.qdoc @@ -0,0 +1,149 @@ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example hellogles3 + \title Hello GLES3 Example + \ingroup examples-widgets-opengl + \examplecategory {Graphics} + \examplecategory {Mobile} + + \brief Demonstrates OpenGL ES 3.0 functions via QOpenGLExtraFunctions. + + \image hellogles3-example.png + \section1 Overview + + This example demonstrates easy, cross-platform usage of OpenGL ES 3.0 + functions via QOpenGLExtraFunctions in an application that + works identically on desktop platforms with OpenGL 3.3 and mobile/embedded + devices with OpenGL ES 3.0. + + This example has no QWidget dependencies, it uses QOpenGLWindow, a + convenience subclass of QWindow that allows easy implementation of windows + that contain OpenGL-rendered content. In this sense it complements the + \l{OpenGL Window Example}, which shows the implementation of an OpenGL-based + QWindow without using the convenience subclass. + + The Qt logo shape implementation is included from the \l{Hello GL2 Example}. + + In other aspects pertaining to using OpenGL there are the following + differences. + + \list + \li The OpenGL context creation has to have a sufficiently high version + number for the features that are in use. + \li The shader's version directive is different. + \endlist + + \section1 Setting up in main.cpp + + Here we instantiate our QGuiApplication, QSurfaceformat and set its + \l{QSurfaceFormat::depthBufferSize()}{depth buffer size}: + + \quotefromfile hellogles3/main.cpp + \skipto int main(int argc, char *argv[]) + \printuntil fmt.setDepthBufferSize(24); + + We request an OpenGL 3.3 core or OpenGL ES 3.0 context, depending on + QOpenGLContext::openGLModuleType(): + + \skipto if (QOpenGLContext::openGLModuleType() == QOpenGLContext::LibGL) { + \printuntil QSurfaceFormat::setDefaultFormat(fmt); + + We set the default surface format and instantiate our GLWindow \c glWindow. + + \section1 Implementing GLWindow + + This class delivers the features of the example application. + + To start, \c GLWindow is declared by implementing a subclass of + QOpenGLWindow: + + \quotefromfile hellogles3/glwindow.h + \skipto class GLWindow : public QOpenGLWindow + \printto { + + The following properties are declared using Q_PROPERTY: + + \printto public: + + The following public functions are declared: + + \printto private slots: + + The following private objects are declared: + + \printto }; + + On the implementation side, those functions that are not declared inline are + implemented (or re-implemented) in \c{glwindow.cpp}. The following selections + will cover implementation particulars pertaining to the use of OpenGL ES 3.0. + + \section2 Animations + + The following code pertains to the animations, and won't be explored here: + + \quotefromfile hellogles3/glwindow.cpp + \skipto GLWindow::GLWindow() + \printto static const char *vertexShaderSource = + + For more information see the documentation for \l QPropertyAnimation, + \l QSequentialAnimationGroup. + + \section2 Shaders + The shaders are defined like so: + + \printto QByteArray versionedShaderCode(const char *src) + + \note These are OpenGL version agnostic. We take this and append + the version like so: + + \printto void GLWindow::initializeGL() + + \section2 Initializing OpenGL + + Initializing the shader program in handled by \c initializeGL(): + + \printuntil m_program = new QOpenGLShaderProgram; + \skipto m_program->addShaderFromSourceCode(QOpenGLShader::Vertex, versionedShaderCode(vertexShaderSource)); + + Now the OpenGL version is prepended and the various matrices and light + position is set: + + \printuntil m_lightPosLoc = m_program->uniformLocation("lightPos"); + + While not strictly required for ES 3, a vertex array object is created. + + \skipto delete m_vao; + \printuntil f->glEnable(GL_CULL_FACE); + + \section2 Resizing the window + + The perspective needs to be aligned with the new window size as so: + + \skipto void GLWindow::resizeGL(int w, int h) + \printto void GLWindow::paintGL() + + \section2 Painting + + We use QOpenGLExtraFunctions instead of QOpenGLFunctions as we want to + do more than what GL(ES) 2.0 offers: + + \printuntil QOpenGLExtraFunctions *f = QOpenGLContext::currentContext()->extraFunctions(); + + We clear the screen and buffers and bind our shader program and texture: + + \printuntil m_texture->bind(); + + Logic for handling an initial \c paintGL() call or a call after a + \c resizeGL() call is implemented like so: + + \printuntil } + + Last, we demonstrate a function introduced in OpenGL 3.1 or OpenGL ES 3.0: + + \skipto f->glDrawArraysInstanced(GL_TRIANGLES, 0, m_logo.vertexCount(), 32 * 36); + \printuntil } + + This works because we earlier requested 3.3 or 3.0 context. +*/ |