From 7635d77689193e729db248300634571aea4d8c81 Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Wed, 28 Oct 2020 18:25:27 +0100 Subject: Organize QtOpenGLWidgets documentation Move snippets to the right place, and give the widgets class a place to live. QtOpenGLWidgets is just a library, not a separate module, but we need a module page that the class can refer to for correct build instructions. Change-Id: I6d955ad3c4cd1003a828cc1f256deb6e7fb50ec4 Reviewed-by: Paul Wicking --- src/opengl/doc/qtopengl.qdocconf | 4 +- .../code/doc_gui_widgets_qopenglwidget.cpp | 209 +++++++++++++++++++++ .../snippets/code/src_gui_opengl_qopenglbuffer.cpp | 68 +++++++ .../snippets/code/src_gui_opengl_qopengldebug.cpp | 133 +++++++++++++ .../snippets/code/src_gui_qopenglshaderprogram.cpp | 116 ++++++++++++ src/opengl/doc/src/qtopengl-index.qdoc | 3 - src/opengl/doc/src/qtopengl-module.qdoc | 16 +- 7 files changed, 544 insertions(+), 5 deletions(-) create mode 100644 src/opengl/doc/snippets/code/doc_gui_widgets_qopenglwidget.cpp create mode 100644 src/opengl/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp create mode 100644 src/opengl/doc/snippets/code/src_gui_opengl_qopengldebug.cpp create mode 100644 src/opengl/doc/snippets/code/src_gui_qopenglshaderprogram.cpp (limited to 'src/opengl') diff --git a/src/opengl/doc/qtopengl.qdocconf b/src/opengl/doc/qtopengl.qdocconf index 6153e97e04..857ad46c8f 100644 --- a/src/opengl/doc/qtopengl.qdocconf +++ b/src/opengl/doc/qtopengl.qdocconf @@ -11,8 +11,10 @@ project = QtOpenGL # /examples. # Paths are relative to the location of this file. -headerdirs += .. +headerdirs += .. \ + ../../openglwidgets sourcedirs += .. \ + ../../openglwidgets \ ../../../examples/opengl/doc/src exampledirs += ../../../examples/opengl \ . \ diff --git a/src/opengl/doc/snippets/code/doc_gui_widgets_qopenglwidget.cpp b/src/opengl/doc/snippets/code/doc_gui_widgets_qopenglwidget.cpp new file mode 100644 index 0000000000..633a413b4f --- /dev/null +++ b/src/opengl/doc/snippets/code/doc_gui_widgets_qopenglwidget.cpp @@ -0,0 +1,209 @@ +/**************************************************************************** +** +** 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:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class MyGLWidget : public QOpenGLWidget +{ +public: + MyGLWidget(QWidget *parent) : QOpenGLWidget(parent) { } + +protected: + void initializeGL() override + { + // Set up the rendering context, load shaders and other resources, etc.: + QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions(); + f->glClearColor(1.0f, 1.0f, 1.0f, 1.0f); + ... + } + + void resizeGL(int w, int h) override + { + // Update projection matrix and other size related settings: + m_projection.setToIdentity(); + m_projection.perspective(45.0f, w / float(h), 0.01f, 100.0f); + ... + } + + void paintGL() override + { + // Draw the scene: + QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions(); + f->glClear(GL_COLOR_BUFFER_BIT); + ... + } + +}; +//! [0] + +//! [1] +class MyGLWidget : public QOpenGLWidget, protected QOpenGLFunctions +{ + ... + void initializeGL() override + { + initializeOpenGLFunctions(); + glClearColor(...); + ... + } + ... +}; +//! [1] + +//! [2] +QOpenGLWidget *widget = new QOpenGLWidget(parent); +QSurfaceFormat format; +format.setDepthBufferSize(24); +format.setStencilBufferSize(8); +format.setVersion(3, 2); +format.setProfile(QSurfaceFormat::CoreProfile); +widget->setFormat(format); // must be called before the widget or its parent window gets shown +//! [2] + +//! [3] + ... + void paintGL() override + { + QOpenGLFunctions_3_2_Core *f = QOpenGLContext::currentContext()->versionFunctions(); + ... + f->glDrawArraysInstanced(...); + ... + } + ... +//! [3] + +//! [4] +class MyGLWidget : public QOpenGLWidget +{ + ... + +private: + QOpenGLVertexArrayObject m_vao; + QOpenGLBuffer m_vbo; + QOpenGLShaderProgram *m_program; + QOpenGLShader *m_shader; + QOpenGLTexture *m_texture; +}; + +MyGLWidget::MyGLWidget() + : m_program(0), m_shader(0), m_texture(0) +{ + // No OpenGL resource initialization is done here. +} + +MyGLWidget::~MyGLWidget() +{ + // Make sure the context is current and then explicitly + // destroy all underlying OpenGL resources. + makeCurrent(); + + delete m_texture; + delete m_shader; + delete m_program; + + m_vbo.destroy(); + m_vao.destroy(); + + doneCurrent(); +} + +void MyGLWidget::initializeGL() +{ + m_vao.create(); + if (m_vao.isCreated()) + m_vao.bind(); + + m_vbo.create(); + m_vbo.bind(); + m_vbo.allocate(...); + + m_texture = new QOpenGLTexture(QImage(...)); + + m_shader = new QOpenGLShader(...); + m_program = new QOpenGLShaderProgram(...); + + ... +} +//! [4] + +//! [5] +void MyGLWidget::initializeGL() +{ + // context() and QOpenGLContext::currentContext() are equivalent when called from initializeGL or paintGL. + connect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup); +} + +void MyGLWidget::cleanup() +{ + makeCurrent(); + delete m_texture; + m_texture = 0; + ... + doneCurrent(); +} +//! [5] + +//! [6] +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QSurfaceFormat format; + format.setDepthBufferSize(24); + format.setStencilBufferSize(8); + format.setVersion(3, 2); + format.setProfile(QSurfaceFormat::CoreProfile); + QSurfaceFormat::setDefaultFormat(format); + + MyWidget widget; + widget.show(); + + return app.exec(); +} +//! [6] diff --git a/src/opengl/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp b/src/opengl/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp new file mode 100644 index 0000000000..bd768b1ed7 --- /dev/null +++ b/src/opengl/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include + +namespace src_gui_opengl_qopenglbuffer { +void wrapper() { + +//! [0] +QOpenGLBuffer buffer1(QOpenGLBuffer::IndexBuffer); +buffer1.create(); + +QOpenGLBuffer buffer2 = buffer1; +//! [0] + + +//! [1] +QOpenGLBuffer::release(QOpenGLBuffer::VertexBuffer); +//! [1] + +} // wrapper +} // src_gui_opengl_qopenglbuffer diff --git a/src/opengl/doc/snippets/code/src_gui_opengl_qopengldebug.cpp b/src/opengl/doc/snippets/code/src_gui_opengl_qopengldebug.cpp new file mode 100644 index 0000000000..241450c23a --- /dev/null +++ b/src/opengl/doc/snippets/code/src_gui_opengl_qopengldebug.cpp @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include +#include +#include +#include + +namespace src_gui_opengl_qopengldebug { +struct LogHandler : public QObject +{ + Q_OBJECT +public slots: + static bool handleLoggedMessage() { return true; }; +}; +struct SnippetWrapper : public QObject +{ + Q_OBJECT + void wrapper1(LogHandler *receiver); + const QWidget *receiver; +}; + +void wrapper0() { + +//! [0] +GLenum error = GL_NO_ERROR; +do { + error = glGetError(); + if (error != GL_NO_ERROR) { + // handle the error + } +} while (error != GL_NO_ERROR); +//! [0] + + +//! [1] +QSurfaceFormat format; +// asks for a OpenGL 3.2 debug context using the Core profile +format.setMajorVersion(3); +format.setMinorVersion(2); +format.setProfile(QSurfaceFormat::CoreProfile); +format.setOption(QSurfaceFormat::DebugContext); + +QOpenGLContext *context = new QOpenGLContext; +context->setFormat(format); +context->create(); +//! [1] + +} // wrapper0 + + +void SnippetWrapper::wrapper1(LogHandler *receiver) { +//! [2] +QOpenGLContext *ctx = QOpenGLContext::currentContext(); +QOpenGLDebugLogger *logger = new QOpenGLDebugLogger(this); + +logger->initialize(); // initializes in the current context, i.e. ctx +//! [2] + + +//! [3] +ctx->hasExtension(QByteArrayLiteral("GL_KHR_debug")); +//! [3] + + +//! [4] +const QList messages = logger->loggedMessages(); +for (const QOpenGLDebugMessage &message : messages) + qDebug() << message; +//! [4] + + +//! [5] +connect(logger, &QOpenGLDebugLogger::messageLogged, receiver, &LogHandler::handleLoggedMessage); +logger->startLogging(); +//! [5] + + +//! [6] +QOpenGLDebugMessage message = + QOpenGLDebugMessage::createApplicationMessage(QStringLiteral("Custom message")); + +logger->logMessage(message); +//! [6] + +} // SnippetWrapper::wrapper1 +} // src_gui_opengl_qopengldebug diff --git a/src/opengl/doc/snippets/code/src_gui_qopenglshaderprogram.cpp b/src/opengl/doc/snippets/code/src_gui_qopenglshaderprogram.cpp new file mode 100644 index 0000000000..131936ed3f --- /dev/null +++ b/src/opengl/doc/snippets/code/src_gui_qopenglshaderprogram.cpp @@ -0,0 +1,116 @@ +/**************************************************************************** +** +** 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:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include +#include +#include + +namespace src_gui_qopenglshaderprogram { +QString code; +QObject *context = nullptr; +QRectF rect() { return QRectF(); } + +void wrapper() { +//! [0] +QOpenGLShader shader(QOpenGLShader::Vertex); +shader.compileSourceCode(code); + +QOpenGLShaderProgram program(context); +program.addShader(&shader); +program.link(); + +program.bind(); +//! [0] + +//! [1] +program.addShaderFromSourceCode(QOpenGLShader::Vertex, + "attribute highp vec4 vertex;\n" + "uniform highp mat4 matrix;\n" + "void main(void)\n" + "{\n" + " gl_Position = matrix * vertex;\n" + "}"); +program.addShaderFromSourceCode(QOpenGLShader::Fragment, + "uniform mediump vec4 color;\n" + "void main(void)\n" + "{\n" + " gl_FragColor = color;\n" + "}"); +program.link(); +program.bind(); + +int vertexLocation = program.attributeLocation("vertex"); +int matrixLocation = program.uniformLocation("matrix"); +int colorLocation = program.uniformLocation("color"); +//! [1] + +//! [2] +static GLfloat const triangleVertices[] = { + 60.0f, 10.0f, 0.0f, + 110.0f, 110.0f, 0.0f, + 10.0f, 110.0f, 0.0f +}; + +QColor color(0, 255, 0, 255); + +QMatrix4x4 pmvMatrix; +pmvMatrix.ortho(rect()); + +program.enableAttributeArray(vertexLocation); +program.setAttributeArray(vertexLocation, triangleVertices, 3); +program.setUniformValue(matrixLocation, pmvMatrix); +program.setUniformValue(colorLocation, color); + +glDrawArrays(GL_TRIANGLES, 0, 3); + +program.disableAttributeArray(vertexLocation); +//! [2] + +} // wrapper +} // src_gui_qopenglshaderprogram diff --git a/src/opengl/doc/src/qtopengl-index.qdoc b/src/opengl/doc/src/qtopengl-index.qdoc index 53f1599c1b..a655a3e20f 100644 --- a/src/opengl/doc/src/qtopengl-index.qdoc +++ b/src/opengl/doc/src/qtopengl-index.qdoc @@ -31,9 +31,6 @@ \brief The Qt OpenGL module offers classes that make it easy to use OpenGL in Qt applications. - \warning This module should not be used anymore for new code. Please - use the corresponding OpenGL classes in \l{Qt GUI}. - \section1 Introduction OpenGL is a standard API for rendering 3D graphics. OpenGL only diff --git a/src/opengl/doc/src/qtopengl-module.qdoc b/src/opengl/doc/src/qtopengl-module.qdoc index 0ba78ed5dc..0d1c9e687f 100644 --- a/src/opengl/doc/src/qtopengl-module.qdoc +++ b/src/opengl/doc/src/qtopengl-module.qdoc @@ -35,5 +35,19 @@ \brief The Qt OpenGL module offers classes that make it easy to use OpenGL in Qt applications. - \warning This module should not be used anymore for new code. + The \l{Qt OpenGL Widgets C++ Classes}{Qt OpenGL Widgets} library provides + a C++ widget class for rendering OpenGL graphics into widgets UIs. + + \generatelist classesbymodule QtOpenGLWidgets +*/ + +/* + This "module" only exists so that classes in that separate library have + the correct build system documentation. +*/ +/*! + \module QtOpenGLWidgets + \title Qt OpenGL Widgets C++ Classes + \qtcmakepackage OpenGLWidgets + \qtvariable openglwidgets */ -- cgit v1.2.3