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 | 32 | ||||
| -rw-r--r-- | examples/opengl/doc/src/stereoqopenglwidget.qdoc | 46 | ||||
| -rw-r--r-- | examples/opengl/doc/src/textures.qdoc | 28 |
7 files changed, 218 insertions, 134 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 index f283c7cfc0..cade2f009a 100644 --- a/examples/opengl/doc/src/openglwindow.qdoc +++ b/examples/opengl/doc/src/openglwindow.qdoc @@ -1,33 +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 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. @@ -36,6 +14,8 @@ \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 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 |