From 8d72aba9e3358fdf51578533ab7f46602f7fd103 Mon Sep 17 00:00:00 2001 From: Laszlo Agocs Date: Sun, 12 Feb 2017 15:08:52 +0100 Subject: Introduce QVulkanWindow A convenience subclass of QWindow that provides a Vulkan-capable window with a double-buffered FIFO swapchain. While advanced use cases are better served by a custom QWindow subclass, many applications can benefit from having a convenient helper that makes getting started easier. Add also three examples of increasing complexity, and a variant that shows embeddeding into widgets via QWindowContainer. [ChangeLog][QtGui] Added QVulkanWindow, a convenience subclass of QWindow. Task-number: QTBUG-55981 Change-Id: I6cdc9ff1390ac6258e278377233fd369a0bfeddc Reviewed-by: Andy Nichols --- examples/vulkan/doc/src/hellovulkantexture.qdoc | 41 +++++++++ examples/vulkan/doc/src/hellovulkantriangle.qdoc | 49 +++++++++++ examples/vulkan/doc/src/hellovulkanwidget.qdoc | 49 +++++++++++ examples/vulkan/doc/src/hellovulkanwindow.qdoc | 101 +++++++++++++++++++++++ 4 files changed, 240 insertions(+) create mode 100644 examples/vulkan/doc/src/hellovulkantexture.qdoc create mode 100644 examples/vulkan/doc/src/hellovulkantriangle.qdoc create mode 100644 examples/vulkan/doc/src/hellovulkanwidget.qdoc create mode 100644 examples/vulkan/doc/src/hellovulkanwindow.qdoc (limited to 'examples/vulkan/doc/src') diff --git a/examples/vulkan/doc/src/hellovulkantexture.qdoc b/examples/vulkan/doc/src/hellovulkantexture.qdoc new file mode 100644 index 0000000000..d0e0ca90a8 --- /dev/null +++ b/examples/vulkan/doc/src/hellovulkantexture.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example hellovulkantexture + \ingroup examples-vulkan + \title Hello Vulkan Texture Vulkan Example + \brief Shows the basics of rendering with textures in a QVulkanWindow + + The \e{Hello Vulkan Texture Example} builds on \l hellovulkantriangle. Here + instead of drawing a single triangle, a triangle strip is drawn in order to + get a quad on the screen. This is then textured using a QImage loaded from + a .png image file. + + \image hellovulkantexture.png + \include examples-run.qdocinc +*/ diff --git a/examples/vulkan/doc/src/hellovulkantriangle.qdoc b/examples/vulkan/doc/src/hellovulkantriangle.qdoc new file mode 100644 index 0000000000..81af776ea1 --- /dev/null +++ b/examples/vulkan/doc/src/hellovulkantriangle.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example hellovulkantriangle + \ingroup examples-vulkan + \title Hello Vulkan Triangle Example + \brief Shows the basics of rendering with QVulkanWindow and the Vulkan API + + The \e{Hello Vulkan Triangle Example} builds on \l hellovulkanwindow. This + time a full graphics pipeline is created, including a vertex and fragment + shader. This pipeline is then used to render a triangle. + + \image hellovulkantriangle.png + + The example also demonstrates multisample antialiasing. Based on the + supported sample counts reported by QVulkanWindow::supportedSampleCounts() + the example chooses between 8x, 4x, or no multisampling. Once configured + via QVulkanWindow::setSamples(), QVulkanWindow takes care of the rest: the + additional multisample color buffers are created automatically, and + resolving into the swapchain buffers is performed at the end of the default + render pass for each frame. + + \include examples-run.qdocinc +*/ diff --git a/examples/vulkan/doc/src/hellovulkanwidget.qdoc b/examples/vulkan/doc/src/hellovulkanwidget.qdoc new file mode 100644 index 0000000000..7987bdeff9 --- /dev/null +++ b/examples/vulkan/doc/src/hellovulkanwidget.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example hellovulkanwidget + \ingroup examples-vulkan + \title Hello Vulkan Widget Example + \brief Shows the usage of QVulkanWindow in QWidget applications + + The \e{Hello Vulkan Widget Example} is a variant of \l hellovulkantriangle + that embeds the QVulkanWindow into a QWidget-based user interface using + QWidget::createWindowContainer(). + + \image hellovulkanwidget.png + + The code to set up the Vulkan pipeline and render the triangle is the same + as in \l hellovulkantriangle. In addition, this example demonstrates + another feature of QVulkanWindow: reading the image content back from the + color buffer into a QImage. By clicking the Grab button, the example + renders the next frame and follows it up with a transfer operation in order + to get the swapchain color buffer content copied into host accessible + memory. The image is then saved to disk via QImage::save(). + + \include examples-run.qdocinc +*/ diff --git a/examples/vulkan/doc/src/hellovulkanwindow.qdoc b/examples/vulkan/doc/src/hellovulkanwindow.qdoc new file mode 100644 index 0000000000..06cc9c1c28 --- /dev/null +++ b/examples/vulkan/doc/src/hellovulkanwindow.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example hellovulkanwindow + \title Hello Vulkan Window Example + \ingroup examples-vulkan + \brief Shows the basics of using QVulkanWindow + + The \e{Hello Vulkan Window Example} shows the basics of using QVulkanWindow + in order to display rendering with the Vulkan graphics API on systems that + support this. + + \image hellovulkanwindow.png + + In this example there will be no actual rendering: it simply begins and + ends a render pass, which results in clearing the buffers to a fixed value. + The color buffer clear value changes on every frame. + + \section1 Startup + + Each Qt application using Vulkan will have to have a \c{Vulkan instance} + which encapsulates application-level state and initializes a Vulkan library. + + A QVulkanWindow must always be associated with a QVulkanInstance and hence + the example performs instance creation before the window. The + QVulkanInstance object must also outlive the window. + + \snippet hellovulkanwindow/main.cpp 0 + + The example enables validation layers, when supported. When the requested + layers are not present, the request will be ignored. Additional layers and + extensions can be enabled in a similar manner. + + \snippet hellovulkanwindow/main.cpp 1 + + Once the instance is ready, it is time to create a window. Note that \c w + lives on the stack and is declared after \c inst. + + \section1 The QVulkanWindow Subclass + + To add custom functionality to a QVulkanWindow, subclassing is used. This + follows the existing patterns from QOpenGLWindow and QOpenGLWidget. + However, QVulkanWindow utilizes a separate QVulkanWindowRenderer object. + This resembles QQuickFramebufferObject, and allows better separation of the + functions that are supposed to be reimplemented. + + \snippet hellovulkanwindow/hellovulkanwindow.h 0 + + The QVulkanWindow subclass reimplements the factory function + QVulkanWindow::createRenderer(). This simply returns a new instance of the + QVulkanWindowRenderer subclass. In order to be able to access various + Vulkan resources via the window object, a pointer to the window is passed + and stored via the constructor. + + \snippet hellovulkanwindow/hellovulkanwindow.cpp 0 + + Graphics resource creation and destruction is typically done in one of the + init - resource functions. + + \snippet hellovulkanwindow/hellovulkanwindow.cpp 1 + + \section1 The Actual Rendering + + QVulkanWindow subclasses queue their draw calls in their reimplementation + of QVulkanWindowRenderer::startNextFrame(). Once done, they are required to + call back QVulkanWindow::frameReady(). The example has no asynchronous + command generation, so the frameReady() call is made directly from + startNextFrame(). + + \snippet hellovulkanwindow/hellovulkanwindow.cpp 2 + + To get continuous updates, the example simply invokes + QWindow::requestUpdate() in order to schedule a repaint. + + \include examples-run.qdocinc +*/ -- cgit v1.2.3