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 --- .../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/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 +- .../code/doc_gui_widgets_qopenglwidget.cpp | 209 --------------------- 11 files changed, 544 insertions(+), 531 deletions(-) delete mode 100644 src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp delete mode 100644 src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp delete mode 100644 src/gui/doc/snippets/code/src_gui_qopenglshaderprogram.cpp 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 delete mode 100644 src/widgets/doc/snippets/code/doc_gui_widgets_qopenglwidget.cpp diff --git a/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp b/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp deleted file mode 100644 index bd768b1ed7..0000000000 --- a/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp +++ /dev/null @@ -1,68 +0,0 @@ -/**************************************************************************** -** -** 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/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp b/src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp deleted file mode 100644 index 241450c23a..0000000000 --- a/src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp +++ /dev/null @@ -1,133 +0,0 @@ -/**************************************************************************** -** -** 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/gui/doc/snippets/code/src_gui_qopenglshaderprogram.cpp b/src/gui/doc/snippets/code/src_gui_qopenglshaderprogram.cpp deleted file mode 100644 index 131936ed3f..0000000000 --- a/src/gui/doc/snippets/code/src_gui_qopenglshaderprogram.cpp +++ /dev/null @@ -1,116 +0,0 @@ -/**************************************************************************** -** -** 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/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 */ diff --git a/src/widgets/doc/snippets/code/doc_gui_widgets_qopenglwidget.cpp b/src/widgets/doc/snippets/code/doc_gui_widgets_qopenglwidget.cpp deleted file mode 100644 index 633a413b4f..0000000000 --- a/src/widgets/doc/snippets/code/doc_gui_widgets_qopenglwidget.cpp +++ /dev/null @@ -1,209 +0,0 @@ -/**************************************************************************** -** -** 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] -- cgit v1.2.3