diff options
Diffstat (limited to 'src/gui')
18 files changed, 677 insertions, 363 deletions
diff --git a/src/gui/accessible/qaccessible.cpp b/src/gui/accessible/qaccessible.cpp index 6b48f573b2..a3f53e149b 100644 --- a/src/gui/accessible/qaccessible.cpp +++ b/src/gui/accessible/qaccessible.cpp @@ -1309,14 +1309,7 @@ QColor QAccessibleInterface::backgroundColor() const For example to notify about a focus change when re-implementing QWidget::setFocus, the event could be used as follows: - \code - void MyWidget::setFocus(Qt::FocusReason reason) - { - // handle custom focus setting... - QAccessibleEvent event(f, QAccessible::Focus); - QAccessible::updateAccessibility(&event); - } - \endcode + \snippet code/src_gui_accessible_qaccessible.cpp 2 To enable in process screen readers, all events must be sent after the change has happened. */ @@ -1826,14 +1819,7 @@ void QAccessibleInterface::virtual_hook(int /*id*/, void * /*data*/) Qt's QLineEdit for example has its accessibility support implemented in QAccessibleLineEdit. - \code -void *QAccessibleLineEdit::interface_cast(QAccessible::InterfaceType t) -{ - if (t == QAccessible::TextInterface) - return static_cast<QAccessibleTextInterface*>(this); - return QAccessibleWidget::interface_cast(t); -} - \endcode + \snippet code/src_gui_accessible_qaccessible.cpp 3 \sa QAccessible::InterfaceType, QAccessibleTextInterface, QAccessibleValueInterface, QAccessibleActionInterface, diff --git a/src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp b/src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp index 98d40c94f9..2fd76d08c7 100644 --- a/src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp +++ b/src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp @@ -51,3 +51,21 @@ //! [1] typedef QAccessibleInterface* myFactoryFunction(const QString &key, QObject *); //! [1] + +//! [2] +void MyWidget::setFocus(Qt::FocusReason reason) +{ + // handle custom focus setting... + QAccessibleEvent event(f, QAccessible::Focus); + QAccessible::updateAccessibility(&event); +} +//! [2] + +//! [3] +void *QAccessibleLineEdit::interface_cast(QAccessible::InterfaceType t) +{ + if (t == QAccessible::TextInterface) + return static_cast<QAccessibleTextInterface*>(this); + return QAccessibleWidget::interface_cast(t); +} +//! [3] diff --git a/src/gui/doc/snippets/code/src_gui_math3d_qquaternion.cpp b/src/gui/doc/snippets/code/src_gui_math3d_qquaternion.cpp new file mode 100644 index 0000000000..b5cd00d5aa --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_math3d_qquaternion.cpp @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + QVector3D result = q.rotatedVector(vector); +//! [0] + +//! [1] + QVector3D result = (q * QQuaternion(0, vector) * q.conjugated()).vector(); +//! [1] diff --git a/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp b/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp new file mode 100644 index 0000000000..4a4a6fe16d --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + QOpenGLBuffer buffer1(QOpenGLBuffer::IndexBuffer); + buffer1.create(); + + QOpenGLBuffer buffer2 = buffer1; +//! [0] + +//! [1] + QOpenGLBuffer::release(QOpenGLBuffer::VertexBuffer); +//! [1] diff --git a/src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp b/src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp new file mode 100644 index 0000000000..4ab84deb3e --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtWidgets module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [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] + +//! [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<QOpenGLDebugMessage> 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] diff --git a/src/gui/doc/snippets/code/src_gui_opengl_qopenglfunctions.cpp b/src/gui/doc/snippets/code/src_gui_opengl_qopenglfunctions.cpp new file mode 100644 index 0000000000..68a20dcb7c --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_opengl_qopenglfunctions.cpp @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + class MyGLWindow : public QWindow, protected QOpenGLFunctions + { + Q_OBJECT + public: + MyGLWindow(QScreen *screen = 0); + + protected: + void initializeGL(); + void paintGL(); + + QOpenGLContext *m_context; + }; + + MyGLWindow(QScreen *screen) + : QWindow(screen), QOpenGLWidget(parent) + { + setSurfaceType(OpenGLSurface); + create(); + + // Create an OpenGL context + m_context = new QOpenGLContext; + m_context->create(); + + // Setup scene and render it + initializeGL(); + paintGL(); + } + + void MyGLWindow::initializeGL() + { + m_context->makeCurrent(this); + initializeOpenGLFunctions(); + } +//! [0] + +//! [1] + void MyGLWindow::paintGL() + { + m_context->makeCurrent(this); + glActiveTexture(GL_TEXTURE1); + glBindTexture(GL_TEXTURE_2D, textureId); + ... + m_context->swapBuffers(this); + m_context->doneCurrent(); + } +//! [1] + +//! [2] + QOpenGLFunctions glFuncs(QOpenGLContext::currentContext()); + glFuncs.glActiveTexture(GL_TEXTURE1); +//! [2] + +//! [3] + QOpenGLFunctions *glFuncs = QOpenGLContext::currentContext()->functions(); + glFuncs->glActiveTexture(GL_TEXTURE1); +//! [3] + +//! [4] + QOpenGLFunctions funcs(QOpenGLContext::currentContext()); + bool npot = funcs.hasOpenGLFeature(QOpenGLFunctions::NPOTTextures); +//! [4] diff --git a/src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp b/src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp index b48e9e8610..b9a8d8d90e 100644 --- a/src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp +++ b/src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp @@ -68,3 +68,31 @@ mailto:user@foo.com?subject=Test&body=Just a test //! [2] QDesktopServices::openUrl(QUrl("file:///C:/Documents and Settings/All Users/Desktop", QUrl::TolerantMode)); //! [2] + +//! [3] +<key>LSApplicationQueriesSchemes</key> +<array> + <string>https</string> +</array> +//! [3] + +//! [4] +<key>CFBundleURLTypes</key> +<array> + <dict> + <key>CFBundleURLSchemes</key> + <array> + <string>myapp</string> + </array> + </dict> +</array> +//! [4] + +//! [5] +QDesktopServices::storageLocation(QDesktopServices::DataLocation) +//! [5] + +//! [6] +QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + + "/data/organization/application" +//! [6] diff --git a/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanfunctions.cpp b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanfunctions.cpp new file mode 100644 index 0000000000..77c5444df5 --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanfunctions.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + void Window::render() + { + QVulkanInstance *inst = vulkanInstance(); + QVulkanFunctions *f = inst->functions(); + ... + VkResult err = f->vkAllocateCommandBuffers(device, &cmdBufInfo, &cmdBuf); + ... + } +//! [0] + +//! [1] + void Window::render() + { + QVulkanInstance *inst = vulkanInstance(); + QVulkanDeviceFunctions *df = inst->deviceFunctions(device); + VkResult err = df->vkAllocateCommandBuffers(device, &cmdBufInfo, &cmdBuf); + ... + } +//! [1] diff --git a/src/gui/doc/snippets/code/src_gui_vulkan_qvulkaninstance.cpp b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkaninstance.cpp new file mode 100644 index 0000000000..50afe7c0ff --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkaninstance.cpp @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + int main(int argc, char **argv) + { + QGuiApplication app(argc, argv); + + QVulkanInstance inst; + if (!inst.create()) + return 1; + + ... + window->setVulkanInstance(&inst); + window->show(); + + return app.exec(); + } +//! [0] + +//! [1] + QVulkanInstance inst; + + // Enable validation layer, if supported. Messages go to qDebug by default. + inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation"); + + bool ok = inst.create(); + if (!ok) + ... // Vulkan not available + if (!inst.layers().contains("VK_LAYER_LUNARG_standard_validation")) + ... // validation layer not available +//! [1] + +//! [2] + QVulkanInstance inst; + + if (inst.supportedLayers().contains("VK_LAYER_LUNARG_standard_validation")) + ... + + bool ok = inst.create(); + ... +//! [2] + +//! [3] + class VulkanWindow : public QWindow + { + public: + VulkanWindow() { + setSurfaceType(VulkanSurface); + } + + void exposeEvent(QExposeEvent *) { + if (isExposed()) { + if (!m_initialized) { + m_initialized = true; + // initialize device, swapchain, etc. + QVulkanInstance *inst = vulkanInstance(); + QVulkanFunctions *f = inst->functions(); + uint32_t devCount = 0; + f->vkEnumeratePhysicalDevices(inst->vkInstance(), &devCount, nullptr); + ... + // build the first frame + render(); + } + } + } + + bool event(QEvent *e) { + if (e->type == QEvent::UpdateRequest) + render(); + return QWindow::event(e); + } + + void render() { + ... + requestUpdate(); // render continuously + } + + private: + bool m_initialized = false; + }; + + int main(int argc, char **argv) + { + QGuiApplication app(argc, argv); + + QVulkanInstance inst; + if (!inst.create()) { + qWarning("Vulkan not available"); + return 1; + } + + VulkanWindow window; + window.showMaximized(); + + return app.exec(); + + } +//! [3] diff --git a/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanwindow.cpp b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanwindow.cpp new file mode 100644 index 0000000000..65eca4a77f --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanwindow.cpp @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + class VulkanRenderer : public QVulkanWindowRenderer + { + public: + VulkanRenderer(QVulkanWindow *w) : m_window(w) { } + + void initResources() override + { + m_devFuncs = m_window->vulkanInstance()->deviceFunctions(m_window->device()); + ... + } + void initSwapChainResources() override { ... } + void releaseSwapChainResources() override { ... } + void releaseResources() override { ... } + + void startNextFrame() override + { + VkCommandBuffer cmdBuf = m_window->currentCommandBuffer(); + ... + m_devFuncs->vkCmdBeginRenderPass(...); + ... + m_window->frameReady(); + } + + private: + QVulkanWindow *m_window; + QVulkanDeviceFunctions *m_devFuncs; + }; + + class VulkanWindow : public QVulkanWindow + { + public: + QVulkanWindowRenderer *createRenderer() override { + return new VulkanRenderer(this); + } + }; + + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + + QVulkanInstance inst; + // enable the standard validation layers, when available + inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation"); + if (!inst.create()) + qFatal("Failed to create Vulkan instance: %d", inst.errorCode()); + + VulkanWindow w; + w.setVulkanInstance(&inst); + w.showMaximized(); + + return app.exec(); + } +//! [0] + +//! [1] + class Renderer { + ... + VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT]; + }; + + void Renderer::startNextFrame() + { + VkDescriptorBufferInfo &uniformBufInfo(m_uniformBufInfo[m_window->currentFrame()]); + ... + } +//! [1] + +//! [2] + class Renderer { + ... + VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT]; + }; + + void Renderer::startNextFrame() + { + const int count = m_window->concurrentFrameCount(); + for (int i = 0; i < count; ++i) + m_uniformBufInfo[i] = ... + ... + } +//! [2] diff --git a/src/gui/math3d/qquaternion.cpp b/src/gui/math3d/qquaternion.cpp index fe1b0425a8..899ec12eb3 100644 --- a/src/gui/math3d/qquaternion.cpp +++ b/src/gui/math3d/qquaternion.cpp @@ -325,15 +325,11 @@ void QQuaternion::normalize() Rotates \a vector with this quaternion to produce a new vector in 3D space. The following code: - \code - QVector3D result = q.rotatedVector(vector); - \endcode + \snippet code/src_gui_math3d_qquaternion.cpp 0 is equivalent to the following: - \code - QVector3D result = (q * QQuaternion(0, vector) * q.conjugated()).vector(); - \endcode + \snippet code/src_gui_math3d_qquaternion.cpp 1 */ QVector3D QQuaternion::rotatedVector(const QVector3D& vector) const { diff --git a/src/gui/opengl/qopenglbuffer.cpp b/src/gui/opengl/qopenglbuffer.cpp index 000494244d..537097c09f 100644 --- a/src/gui/opengl/qopenglbuffer.cpp +++ b/src/gui/opengl/qopenglbuffer.cpp @@ -63,12 +63,7 @@ QT_BEGIN_NAMESPACE QOpenGLBuffer objects can be copied around as a reference to the underlying OpenGL buffer object: - \code - QOpenGLBuffer buffer1(QOpenGLBuffer::IndexBuffer); - buffer1.create(); - - QOpenGLBuffer buffer2 = buffer1; - \endcode + \snippet code/src_gui_opengl_qopenglbuffer.cpp 0 QOpenGLBuffer performs a shallow copy when objects are copied in this manner, but does not implement copy-on-write semantics. The original @@ -484,9 +479,7 @@ void QOpenGLBuffer::release() been bound to the context but wants to make sure that it is released. - \code - QOpenGLBuffer::release(QOpenGLBuffer::VertexBuffer); - \endcode + \snippet code/src_gui_opengl_qopenglbuffer.cpp 1 */ void QOpenGLBuffer::release(QOpenGLBuffer::Type type) { diff --git a/src/gui/opengl/qopengldebug.cpp b/src/gui/opengl/qopengldebug.cpp index 7072db5af4..2e628a2bd5 100644 --- a/src/gui/opengl/qopengldebug.cpp +++ b/src/gui/opengl/qopengldebug.cpp @@ -89,16 +89,7 @@ QT_BEGIN_NAMESPACE call. Moreover, OpenGL errors stack up, therefore glGetError should always be used in a loop like this: - \code - - GLenum error = GL_NO_ERROR; - do { - error = glGetError(); - if (error != GL_NO_ERROR) - // handle the error - } while (error != GL_NO_ERROR); - - \endcode + \snippet code/src_gui_opengl_qopengldebug.cpp 0 If you try to clear the error stack, make sure not just keep going until GL_NO_ERROR is returned but also break on GL_CONTEXT_LOST as that error @@ -125,20 +116,7 @@ QT_BEGIN_NAMESPACE to create a debug context from Qt, you must set the QSurfaceFormat::DebugContext format option on the QSurfaceFormat used to create the QOpenGLContext object: - \code - - 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(); - - \endcode + \snippet code/src_gui_opengl_qopengldebug.cpp 1 Note that requesting a 3.2 OpenGL Core Profile is just for the example's purposes; this class is not tied to any specific OpenGL or OpenGL ES @@ -152,24 +130,13 @@ QT_BEGIN_NAMESPACE object), and like the other OpenGL functions in Qt you \e{must} initialize it before usage by calling initialize() whilst there is a current OpenGL context: - \code - - QOpenGLContext *ctx = QOpenGLContext::currentContext(); - QOpenGLDebugLogger *logger = new QOpenGLDebugLogger(this); - - logger->initialize(); // initializes in the current context, i.e. ctx - - \endcode + \snippet code/src_gui_opengl_qopengldebug.cpp 2 Note that the \c{GL_KHR_debug} extension \e{must} be available in the context in order to access the messages logged by OpenGL. You can check the presence of this extension by calling: - \code - - ctx->hasExtension(QByteArrayLiteral("GL_KHR_debug")) - - \endcode + \snippet code/src_gui_opengl_qopengldebug.cpp 3 where \c{ctx} is a valid QOpenGLContext. If the extension is not available, initialize() will return false. @@ -179,13 +146,7 @@ QT_BEGIN_NAMESPACE OpenGL implementations keep an internal log of debug messages. Messages stored in this log can be retrieved by using the loggedMessages() function: - \code - - const QList<QOpenGLDebugMessage> messages = logger->loggedMessages(); - for (const QOpenGLDebugMessage &message : messages) - qDebug() << message; - - \endcode + \snippet code/src_gui_opengl_qopengldebug.cpp 4 The internal log has a limited size; when it fills up, older messages will get discarded to make room for the new incoming messages. When you call @@ -203,12 +164,7 @@ QT_BEGIN_NAMESPACE you need to connect a suitable slot to the messageLogged() signal, and start logging by calling startLogging(): - \code - - connect(logger, &QOpenGLDebugLogger::messageLogged, receiver, &LogHandler::handleLoggedMessage); - logger->startLogging(); - - \endcode + \snippet code/src_gui_opengl_qopengldebug.cpp 5 Similarly, logging can be disabled at any time by calling the stopLogging() function. @@ -259,14 +215,7 @@ QT_BEGIN_NAMESPACE \l{QOpenGLDebugMessage::}{createThirdPartyMessage()}, and then inserting it into the log by calling logMessage(): - \code - - QOpenGLDebugMessage message = - QOpenGLDebugMessage::createApplicationMessage(QStringLiteral("Custom message")); - - logger->logMessage(message); - - \endcode + \snippet code/src_gui_opengl_qopengldebug.cpp 6 Note that OpenGL implementations have a vendor-specific limit to the length of the messages that can be inserted in the debug log. You can retrieve diff --git a/src/gui/opengl/qopenglfunctions.cpp b/src/gui/opengl/qopenglfunctions.cpp index 4f48604a88..b4ff21f3fd 100644 --- a/src/gui/opengl/qopenglfunctions.cpp +++ b/src/gui/opengl/qopenglfunctions.cpp @@ -90,65 +90,18 @@ void CLASS::init(QOpenGLContext *context) \ that need it. The recommended way to use QOpenGLFunctions is by direct inheritance: - \code - class MyGLWindow : public QWindow, protected QOpenGLFunctions - { - Q_OBJECT - public: - MyGLWindow(QScreen *screen = 0); - - protected: - void initializeGL(); - void paintGL(); - - QOpenGLContext *m_context; - }; - - MyGLWindow(QScreen *screen) - : QWindow(screen), QOpenGLWidget(parent) - { - setSurfaceType(OpenGLSurface); - create(); - - // Create an OpenGL context - m_context = new QOpenGLContext; - m_context->create(); - - // Setup scene and render it - initializeGL(); - paintGL(); - } - - void MyGLWindow::initializeGL() - { - m_context->makeCurrent(this); - initializeOpenGLFunctions(); - } - \endcode + \snippet code/src_gui_opengl_qopenglfunctions.cpp 0 The \c{paintGL()} function can then use any of the OpenGL ES 2.0 functions without explicit resolution, such as glActiveTexture() in the following example: - \code - void MyGLWindow::paintGL() - { - m_context->makeCurrent(this); - glActiveTexture(GL_TEXTURE1); - glBindTexture(GL_TEXTURE_2D, textureId); - ... - m_context->swapBuffers(this); - m_context->doneCurrent(); - } - \endcode + \snippet code/src_gui_opengl_qopenglfunctions.cpp 1 QOpenGLFunctions can also be used directly for ad-hoc invocation of OpenGL ES 2.0 functions on all platforms: - \code - QOpenGLFunctions glFuncs(QOpenGLContext::currentContext()); - glFuncs.glActiveTexture(GL_TEXTURE1); - \endcode + \snippet code/src_gui_opengl_qopenglfunctions.cpp 2 An alternative approach is to query the context's associated QOpenGLFunctions instance. This is somewhat faster than the previous @@ -157,10 +110,7 @@ void CLASS::init(QOpenGLContext *context) \ resolving happens only once for a given context, regardless of the number of QOpenGLFunctions instances initialized for it. - \code - QOpenGLFunctions *glFuncs = QOpenGLContext::currentContext()->functions(); - glFuncs->glActiveTexture(GL_TEXTURE1); - \endcode + \snippet code/src_gui_opengl_qopenglfunctions.cpp 3 QOpenGLFunctions provides wrappers for all OpenGL ES 2.0 functions, including the common subset of OpenGL 1.x and ES @@ -175,10 +125,7 @@ void CLASS::init(QOpenGLContext *context) \ feature. For example, the following checks if non power of two textures are available: - \code - QOpenGLFunctions funcs(QOpenGLContext::currentContext()); - bool npot = funcs.hasOpenGLFeature(QOpenGLFunctions::NPOTTextures); - \endcode + \snippet code/src_gui_opengl_qopenglfunctions.cpp 4 \sa QOpenGLContext, QSurfaceFormat */ diff --git a/src/gui/util/qdesktopservices.cpp b/src/gui/util/qdesktopservices.cpp index de9d087c21..b6eac91478 100644 --- a/src/gui/util/qdesktopservices.cpp +++ b/src/gui/util/qdesktopservices.cpp @@ -187,12 +187,7 @@ void QOpenUrlHandlerRegistry::handlerDestroyed(QObject *handler) \l{https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl}{canOpenURL(_:)}. For example, the following lines enable URLs with the HTTPS scheme: - \code - <key>LSApplicationQueriesSchemes</key> - <array> - <string>https</string> - </array> - \endcode + \snippet code/src_gui_util_qdesktopservices.cpp 3 \sa setUrlHandler() */ @@ -252,17 +247,7 @@ bool QDesktopServices::openUrl(const QUrl &url) To use this function for receiving data from other apps on iOS you also need to add the custom scheme to the \c CFBundleURLSchemes list in your Info.plist file: - \code - <key>CFBundleURLTypes</key> - <array> - <dict> - <key>CFBundleURLSchemes</key> - <array> - <string>myapp</string> - </array> - </dict> - </array> - \endcode + \snippet code/src_gui_util_qdesktopservices.cpp 4 For more information, see the Apple Developer Documentation for \l{https://developer.apple.com/documentation/uikit/core_app/allowing_apps_and_websites_to_link_to_your_content/communicating_with_other_apps_using_custom_urls?language=objc}{Communicating with Other Apps Using Custom URLs}. @@ -346,14 +331,9 @@ void QDesktopServices::unsetUrlHandler(const QString &scheme) wasn't called, while in Qt 5 it defaults to the name of the executable. Therefore, if you still need to access the Qt 4 path (for example for data migration to Qt 5), replace - \code - QDesktopServices::storageLocation(QDesktopServices::DataLocation) - \endcode + \snippet code/src_gui_util_qdesktopservices.cpp 5 with - \code - QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + - "/data/organization/application" - \endcode + \snippet code/src_gui_util_qdesktopservices.cpp 6 (assuming an organization name and an application name were set). */ diff --git a/src/gui/vulkan/qvulkanfunctions.cpp b/src/gui/vulkan/qvulkanfunctions.cpp index c5f9616d20..73dbeb9ab6 100644 --- a/src/gui/vulkan/qvulkanfunctions.cpp +++ b/src/gui/vulkan/qvulkanfunctions.cpp @@ -66,16 +66,7 @@ QT_BEGIN_NAMESPACE The typical usage is the following: - \code - void Window::render() - { - QVulkanInstance *inst = vulkanInstance(); - QVulkanFunctions *f = inst->functions(); - ... - VkResult err = f->vkAllocateCommandBuffers(device, &cmdBufInfo, &cmdBuf); - ... - } - \endcode + \snippet code/src_gui_vulkan_qvulkanfunctions.cpp 0 \note Windowing system interface (WSI) specifics and extensions are excluded. This class only covers core Vulkan commands, with the exception @@ -118,15 +109,7 @@ QT_BEGIN_NAMESPACE The typical usage is the following: - \code - void Window::render() - { - QVulkanInstance *inst = vulkanInstance(); - QVulkanDeviceFunctions *df = inst->deviceFunctions(device); - VkResult err = df->vkAllocateCommandBuffers(device, &cmdBufInfo, &cmdBuf); - ... - } - \endcode + \snippet code/src_gui_vulkan_qvulkanfunctions.cpp 1 The QVulkanDeviceFunctions object specific to the provided VkDevice is created when QVulkanInstance::deviceFunctions() is first called with the diff --git a/src/gui/vulkan/qvulkaninstance.cpp b/src/gui/vulkan/qvulkaninstance.cpp index 8236d9625a..000c2b8caa 100644 --- a/src/gui/vulkan/qvulkaninstance.cpp +++ b/src/gui/vulkan/qvulkaninstance.cpp @@ -97,22 +97,7 @@ QT_BEGIN_NAMESPACE calling QWindow::setVulkanInstance(). Thus a typical application pattern is the following: - \code - int main(int argc, char **argv) - { - QGuiApplication app(argc, argv); - - QVulkanInstance inst; - if (!inst.create()) - return 1; - - ... - window->setVulkanInstance(&inst); - window->show(); - - return app.exec(); - } - \endcode + \snippet code/src_gui_vulkan_qvulkaninstance.cpp 0 \section1 Configuration @@ -138,31 +123,12 @@ QT_BEGIN_NAMESPACE For example, to enable the standard validation layers, one could do the following: - \code - QVulkanInstance inst; - - // Enable validation layer, if supported. Messages go to qDebug by default. - inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation"); - - bool ok = inst.create(); - if (!ok) - ... // Vulkan not available - if (!inst.layers().contains("VK_LAYER_LUNARG_standard_validation")) - ... // validation layer not available - \endcode + \snippet code/src_gui_vulkan_qvulkaninstance.cpp 1 Or, alternatively, to make decisions before attempting to create a Vulkan instance: - \code - QVulkanInstance inst; - - if (inst.supportedLayers().contains("VK_LAYER_LUNARG_standard_validation")) - ... - - bool ok = inst.create(); - ... - \endcode + \snippet code/src_gui_vulkan_qvulkaninstance.cpp 2 \section1 Adopting an Existing Instance @@ -229,62 +195,7 @@ QT_BEGIN_NAMESPACE The following is the basic outline of creating a Vulkan-capable QWindow: - \code - class VulkanWindow : public QWindow - { - public: - VulkanWindow() { - setSurfaceType(VulkanSurface); - } - - void exposeEvent(QExposeEvent *) { - if (isExposed()) { - if (!m_initialized) { - m_initialized = true; - // initialize device, swapchain, etc. - QVulkanInstance *inst = vulkanInstance(); - QVulkanFunctions *f = inst->functions(); - uint32_t devCount = 0; - f->vkEnumeratePhysicalDevices(inst->vkInstance(), &devCount, nullptr); - ... - // build the first frame - render(); - } - } - } - - bool event(QEvent *e) { - if (e->type == QEvent::UpdateRequest) - render(); - return QWindow::event(e); - } - - void render() { - ... - requestUpdate(); // render continuously - } - - private: - bool m_initialized = false; - }; - - int main(int argc, char **argv) - { - QGuiApplication app(argc, argv); - - QVulkanInstance inst; - if (!inst.create()) { - qWarning("Vulkan not available"); - return 1; - } - - VulkanWindow window; - window.showMaximized(); - - return app.exec(); - - } - \endcode + \snippet code/src_gui_vulkan_qvulkaninstance.cpp 3 \note In addition to expose, a well-behaving window implementation will also have to take care of additional events like resize and diff --git a/src/gui/vulkan/qvulkanwindow.cpp b/src/gui/vulkan/qvulkanwindow.cpp index 2e65ab49c5..6d12377a60 100644 --- a/src/gui/vulkan/qvulkanwindow.cpp +++ b/src/gui/vulkan/qvulkanwindow.cpp @@ -74,60 +74,7 @@ Q_LOGGING_CATEGORY(lcGuiVk, "qt.vulkan") A typical application using QVulkanWindow may look like the following: - \code - class VulkanRenderer : public QVulkanWindowRenderer - { - public: - VulkanRenderer(QVulkanWindow *w) : m_window(w) { } - - void initResources() override - { - m_devFuncs = m_window->vulkanInstance()->deviceFunctions(m_window->device()); - ... - } - void initSwapChainResources() override { ... } - void releaseSwapChainResources() override { ... } - void releaseResources() override { ... } - - void startNextFrame() override - { - VkCommandBuffer cmdBuf = m_window->currentCommandBuffer(); - ... - m_devFuncs->vkCmdBeginRenderPass(...); - ... - m_window->frameReady(); - } - - private: - QVulkanWindow *m_window; - QVulkanDeviceFunctions *m_devFuncs; - }; - - class VulkanWindow : public QVulkanWindow - { - public: - QVulkanWindowRenderer *createRenderer() override { - return new VulkanRenderer(this); - } - }; - - int main(int argc, char *argv[]) - { - QGuiApplication app(argc, argv); - - QVulkanInstance inst; - // enable the standard validation layers, when available - inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation"); - if (!inst.create()) - qFatal("Failed to create Vulkan instance: %d", inst.errorCode()); - - VulkanWindow w; - w.setVulkanInstance(&inst); - w.showMaximized(); - - return app.exec(); - } - \endcode + \snippet code/src_gui_vulkan_qvulkanwindow.cpp 0 As it can be seen in the example, the main patterns in QVulkanWindow usage are: @@ -2439,18 +2386,7 @@ VkFramebuffer QVulkanWindow::currentFramebuffer() const concurrentFrameCount(). Such arrays can then be indexed by the value returned from this function. - \code - class Renderer { - ... - VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT]; - }; - - void Renderer::startNextFrame() - { - VkDescriptorBufferInfo &uniformBufInfo(m_uniformBufInfo[m_window->currentFrame()]); - ... - } - \endcode + \snippet code/src_gui_vulkan_qvulkanwindow.cpp 1 \note This function must only be called from within startNextFrame() and, in case of asynchronous command generation, up until the call to frameReady(). @@ -2477,20 +2413,7 @@ int QVulkanWindow::currentFrame() const \note The value is constant for the entire lifetime of the QVulkanWindow. - \code - class Renderer { - ... - VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT]; - }; - - void Renderer::startNextFrame() - { - const int count = m_window->concurrentFrameCount(); - for (int i = 0; i < count; ++i) - m_uniformBufInfo[i] = ... - ... - } - \endcode + \snippet code/src_gui_vulkan_qvulkanwindow.cpp 2 \sa currentFrame() */ |