diff options
Diffstat (limited to 'examples/opengl/doc/src')
| -rw-r--r-- | examples/opengl/doc/src/2dpainting.qdoc | 29 | ||||
| -rw-r--r-- | examples/opengl/doc/src/cube.qdoc | 39 | ||||
| -rw-r--r-- | examples/opengl/doc/src/hellogl2.qdoc | 29 | ||||
| -rw-r--r-- | examples/opengl/doc/src/hellogles3.qdoc | 149 | ||||
| -rw-r--r-- | examples/opengl/doc/src/openglwindow.qdoc | 138 | ||||
| -rw-r--r-- | examples/opengl/doc/src/stereoqopenglwidget.qdoc | 46 | ||||
| -rw-r--r-- | examples/opengl/doc/src/textures.qdoc | 28 |
7 files changed, 350 insertions, 108 deletions
diff --git a/examples/opengl/doc/src/2dpainting.qdoc b/examples/opengl/doc/src/2dpainting.qdoc index 32b332fa8a..5196c78937 100644 --- a/examples/opengl/doc/src/2dpainting.qdoc +++ b/examples/opengl/doc/src/2dpainting.qdoc @@ -1,34 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \example 2dpainting \title 2D Painting Example \ingroup examples-widgets-opengl + \examplecategory {Graphics} \brief The 2D Painting example shows how QPainter and QOpenGLWidget can be used together to display accelerated 2D graphics on supported hardware. diff --git a/examples/opengl/doc/src/cube.qdoc b/examples/opengl/doc/src/cube.qdoc index 05014173c5..d01985701c 100644 --- a/examples/opengl/doc/src/cube.qdoc +++ b/examples/opengl/doc/src/cube.qdoc @@ -1,39 +1,18 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \example cube \ingroup examples-widgets-opengl \title Cube OpenGL ES 2.0 example + \examplecategory {3D} - \brief The Cube OpenGL ES 2.0 example shows how to write mouse rotateable - textured 3D cube using OpenGL ES 2.0 with Qt. It shows how to handle - polygon geometries efficiently and how to write simple vertex and - fragment shader for programmable graphics pipeline. In addition it + \brief Shows how to manually rotate a textured 3D cube with user input. + + The Cube OpenGL ES 2.0 example shows how to manually rotate a textured 3D + cube with user input, using OpenGL ES 2.0 with Qt. It shows how to + handle polygon geometries efficiently and how to write a simple vertex and + fragment shader for a programmable graphics pipeline. In addition it shows how to use quaternions for representing 3D object orientation. This example has been written for OpenGL ES 2.0 but it works also on diff --git a/examples/opengl/doc/src/hellogl2.qdoc b/examples/opengl/doc/src/hellogl2.qdoc index 2fb2e22e0b..29e8ef85cd 100644 --- a/examples/opengl/doc/src/hellogl2.qdoc +++ b/examples/opengl/doc/src/hellogl2.qdoc @@ -1,34 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \example hellogl2 \title Hello GL2 Example \ingroup examples-widgets-opengl + \examplecategory {3D} \brief The Hello GL2 example demonstrates the basic use of the OpenGL-related classes provided with Qt. 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. +*/ diff --git a/examples/opengl/doc/src/openglwindow.qdoc b/examples/opengl/doc/src/openglwindow.qdoc new file mode 100644 index 0000000000..cade2f009a --- /dev/null +++ b/examples/opengl/doc/src/openglwindow.qdoc @@ -0,0 +1,138 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example openglwindow + \title OpenGL Window Example + \ingroup examples-widgets-opengl + \examplecategory {Graphics} + + \brief This example shows how to create a minimal QWindow based application + for the purpose of using OpenGL. + + \image openglwindow-example.png Screenshot of the OpenGLWindow example + + \note This is a low level example of how to use QWindow with OpenGL. + In practice you should consider using the higher level QOpenGLWindow class. + See the \l{Hello GLES3 Example} for a demonstration of the QOpenGLWindow + convenience class. + + \section1 OpenGLWindow Super Class + + Our OpenGLWindow class acts as an API which is then subclassed to do the + actual rendering. It has functions to make a request for render() to be + called, either immediately with renderNow() or as soon as the event loop + has finished processing the current batch of events with renderLater(). + The OpenGLWindow subclass can either reimplement render() for OpenGL based + rendering, or render(QPainter *) for rendering with a QPainter. Use + OpenGLWindow::setAnimating(true) for render() to be called at the vertical + refresh rate, assuming vertical sync is enabled in the underlying OpenGL + drivers. + + In the class that does the OpenGL rendering you will typically want to + inherit from QOpenGLFunctions, as our OpenGLWindow does, in order to get + platform independent access to OpenGL ES 2.0 functions. By inheriting from + QOpenGLFunctions the OpenGL functions it contains will get precedence, and + you will not have to worry about resolving those functions if you want your + application to work with OpenGL as well as OpenGL ES 2.0. + + \snippet openglwindow/openglwindow.h 1 + + The window's surface type must be set to QSurface::OpenGLSurface to + indicate that the window is to be used for OpenGL rendering and not for + rendering raster content with QPainter using a QBackingStore. + + \snippet openglwindow/openglwindow.cpp 1 + + Any OpenGL initialization needed can be done by overriding the initialize() + function, which is called once before the first call to render(), with a + valid current QOpenGLContext. As can be seen in the following code snippet, + the default render(QPainter *) and initialize() implementations are empty, + whereas the default render() implementation initializes a + QOpenGLPaintDevice and then calls into render(QPainter *). + + \snippet openglwindow/openglwindow.cpp 2 + + The renderLater() function simply calls QWindow::requestUpdate() to schedule + an update for when the system is ready to repaint. + + We also call renderNow() when we get an expose event. The exposeEvent() is + the notification to the window that its exposure, meaning visibility, on + the screen has changed. When the expose event is received you can query + QWindow::isExposed() to find out whether or not the window is currently + exposed. Do not render to or call QOpenGLContext::swapBuffers() on a window + before it has received its first expose event, as before then its final + size might be unknown, and in addition what is rendered might not even end + up on the screen. + + \snippet openglwindow/openglwindow.cpp 3 + + In renderNow() we return if we are not currently exposed, in which case + rendering is delayed until we actually get an expose event. If we have not + yet done so, we create the QOpenGLContext with the same QSurfaceFormat as + was set on the OpenGLWindow, and call initialize() for the sake of the sub + class, and initializeOpenGLFunctions() in order for the QOpenGLFunctions + super class to be associated with the correct QOpenGLContext. In any case + we make the context current by calling QOpenGLContext::makeCurrent(), call + render() to do the actual rendering, and finally we schedule for the + rendered contents to be made visible by calling + QOpenGLContext::swapBuffers() with the OpenGLWindow as parameter. + + Once the rendering of a frame using an OpenGL context is initiated by + calling QOpenGLContext::makeCurrent(), giving the surface on which to + render as a parameter, OpenGL commands can be issued. The commands can be + issued either directly by including <qopengl.h>, which also includes the + system's OpenGL headers, or as by using QOpenGLFunctions, which can + either be inherited from for convenience, or accessed using + QOpenGLContext::functions(). QOpenGLFunctions gives access to all the + OpenGL ES 2.0 level OpenGL calls that are not already standard in both + OpenGL ES 2.0 and desktop OpenGL. For more information about the OpenGL and + OpenGL ES APIs, refer to the official \l{http://www.opengl.org/registry/}{OpenGL Registry} and + \l {http://www.khronos.org/registry/gles/}{Khronos OpenGL ES API Registry}. + + If animation has been enabled with OpenGLWindow::setAnimating(true), we + call renderLater() to schedule another update request. + + \snippet openglwindow/openglwindow.cpp 4 + + Enabling animation also schedules an update request as shown in the + following code snippet. + + \snippet openglwindow/openglwindow.cpp 5 + + \section1 Example OpenGL Rendering Sub Class + + Here we sub class OpenGLWindow to show how to do OpenGL to render a + rotating triangle. By indirectly sub classing QOpenGLFunctions we gain + access to all OpenGL ES 2.0 level functionality. + + \snippet openglwindow/main.cpp 1 + + In our main function we initialize QGuiApplication and instantiate our + TriangleOpenGLWindow. We give it a QSurfaceFormat specifying that we want + four samples of multisample antialiasing, as well as a default geometry. + Since we want to have animation we call the above mentioned setAnimating() + function with an argument of true. + + \snippet openglwindow/main.cpp 2 + + The following code snippet shows the OpenGL shader program used in this + example. The vertex and fragment shaders are relatively simple, doing + vertex transformation and interpolated vertex coloring. + + \snippet openglwindow/main.cpp 3 + + Here is the code that loads the shaders and initializes the shader program + By using QOpenGLShaderProgram instead of raw OpenGL we get the convenience + that strips out the highp, mediump, and lowp qualifiers on desktop OpenGL, + where they are not part of the standard. We store the attribute and uniform + locations in member variables to avoid having to do the location lookup + each frame. + + \snippet openglwindow/main.cpp 4 + + Finally, here is our render() function, where we use OpenGL to set up the + viewport, clear the background, and render a rotating triangle. + + \snippet openglwindow/main.cpp 5 +*/ diff --git a/examples/opengl/doc/src/stereoqopenglwidget.qdoc b/examples/opengl/doc/src/stereoqopenglwidget.qdoc new file mode 100644 index 0000000000..0cb45b9808 --- /dev/null +++ b/examples/opengl/doc/src/stereoqopenglwidget.qdoc @@ -0,0 +1,46 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example stereoqopenglwidget + \title QOpenGLWidget Stereoscopic Rendering Example + \examplecategory {Graphics} + \ingroup examples-widgets-opengl + \brief This example shows how to create a minimal QOpenGLWidget based + application with stereoscopic rendering support. + + \note Support for stereoscopic rendering has certain hardware requirements, + such as, a graphics card with stereo support, 3D glasses and specific + monitors. + + \note This example renders two images to two separate buffers. When you + view the images through 3D glasses, they give a 3D holographic effect. + + \image stereoexample-leftbuffer.png + + The above image is what will be rendered to the left buffer. + + \image stereoexample-rightbuffer.png + + The above image is what will be rendered to the right buffer. + + \section1 Setting the correct surface flag + To enable stereoscopic rendering you need to set the flag + QSurfaceFormat::StereoBuffers globally. Just doing it on the widget is not enough + because of how the flag is handled internally. The safest is to do it on + QSurfaceFormat::SetDefaultFormat prior to starting the application. + + \snippet stereoqopenglwidget/main.cpp 1 + + \section1 Rendering twice + After QSurfaceFormat::StereoBuffers is set, then paintGL() will be called twice, + once for each buffer. In paintGL() you can call currentTargetBuffer() to query + which TargetBuffer is currently active. + + In the following snippet we slightly translate the matrix to not render the + vertices on top of each other. This is a simple example just too see that if the + necessary support is there, at runtime you should see two objects, one on the left + and one on the right. + + \snippet stereoqopenglwidget/glwidget.cpp 1 +*/ diff --git a/examples/opengl/doc/src/textures.qdoc b/examples/opengl/doc/src/textures.qdoc index 34c92b8f6e..b7dd6bca80 100644 --- a/examples/opengl/doc/src/textures.qdoc +++ b/examples/opengl/doc/src/textures.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \example textures |