diff options
author | Laszlo Agocs <laszlo.agocs@qt.io> | 2017-02-12 15:08:52 +0100 |
---|---|---|
committer | Laszlo Agocs <laszlo.agocs@qt.io> | 2017-03-22 15:40:57 +0000 |
commit | 8d72aba9e3358fdf51578533ab7f46602f7fd103 (patch) | |
tree | 5e6ff0ec0ee399bf343654fc9280012eafa29a3d /examples/vulkan/doc | |
parent | 66e162e8f19f8a1f9b4f96008f2853be7fc1822e (diff) |
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 <andy.nichols@qt.io>
Diffstat (limited to 'examples/vulkan/doc')
-rw-r--r-- | examples/vulkan/doc/images/hellovulkantexture.png | bin | 0 -> 10259 bytes | |||
-rw-r--r-- | examples/vulkan/doc/images/hellovulkantriangle.png | bin | 0 -> 30952 bytes | |||
-rw-r--r-- | examples/vulkan/doc/images/hellovulkanwidget.png | bin | 0 -> 25256 bytes | |||
-rw-r--r-- | examples/vulkan/doc/images/hellovulkanwindow.png | bin | 0 -> 2736 bytes | |||
-rw-r--r-- | examples/vulkan/doc/src/hellovulkantexture.qdoc | 41 | ||||
-rw-r--r-- | examples/vulkan/doc/src/hellovulkantriangle.qdoc | 49 | ||||
-rw-r--r-- | examples/vulkan/doc/src/hellovulkanwidget.qdoc | 49 | ||||
-rw-r--r-- | examples/vulkan/doc/src/hellovulkanwindow.qdoc | 101 |
8 files changed, 240 insertions, 0 deletions
diff --git a/examples/vulkan/doc/images/hellovulkantexture.png b/examples/vulkan/doc/images/hellovulkantexture.png Binary files differnew file mode 100644 index 0000000000..0cb47a70be --- /dev/null +++ b/examples/vulkan/doc/images/hellovulkantexture.png diff --git a/examples/vulkan/doc/images/hellovulkantriangle.png b/examples/vulkan/doc/images/hellovulkantriangle.png Binary files differnew file mode 100644 index 0000000000..f88b27a873 --- /dev/null +++ b/examples/vulkan/doc/images/hellovulkantriangle.png diff --git a/examples/vulkan/doc/images/hellovulkanwidget.png b/examples/vulkan/doc/images/hellovulkanwidget.png Binary files differnew file mode 100644 index 0000000000..b85d4dc596 --- /dev/null +++ b/examples/vulkan/doc/images/hellovulkanwidget.png diff --git a/examples/vulkan/doc/images/hellovulkanwindow.png b/examples/vulkan/doc/images/hellovulkanwindow.png Binary files differnew file mode 100644 index 0000000000..c55029312c --- /dev/null +++ b/examples/vulkan/doc/images/hellovulkanwindow.png 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 +*/ |