CopperSpice API  1.9.1
QVulkanWindow Class Reference

Subclass of QWindow to perform Vulkan rendering. More...

Inheritance diagram for QVulkanWindow:
QWindow QObject QSurface

Public Typedefs

using VulkanFlags = QFlags< VulkanOptions >
 

Public Types

enum  VulkanOptions : uint32_t
 
- Public Types inherited from QWindow
enum  AncestorMode
 
enum  Visibility
 
- Public Types inherited from QSurface
enum  SurfaceClass
 
enum  SurfaceType
 

Public Methods

 QVulkanWindow (QWindow *parent=nullptr)
 
 ~QVulkanWindow ()
 
QVector< VkPhysicalDeviceProperties > availablePhysicalDevices ()
 
QMatrix4x4 clipCorrectionMatrix ()
 
VkFormat colorFormat () const
 
int concurrentFrameCount () const
 
virtual QVulkanWindowRenderercreateRenderer ()
 
VkCommandBuffer currentCommandBuffer () const
 
int currentFrame () const
 
VkFramebuffer currentFramebuffer () const
 
int currentSwapChainImageIndex () const
 
VkRenderPass defaultRenderPass () const
 
VkFormat depthStencilFormat () const
 
VkImage depthStencilImage () const
 
VkImageView depthStencilImageView () const
 
VkDevice device () const
 
uint32_t deviceLocalMemoryIndex () const
 
void exposeEvent (QExposeEvent *event) override
 
QVulkanWindow::VulkanFlags flags () const
 
void frameReady ()
 
VkCommandPool graphicsCommandPool () const
 
VkQueue graphicsQueue () const
 
uint32_t graphicsQueueFamilyIndex () const
 
uint32_t hostVisibleMemoryIndex () const
 
bool isValid () const
 
VkImage msaaColorImage (int idx) const
 
VkImageView msaaColorImageView (int idx) const
 
VkPhysicalDevice physicalDevice () const
 
const VkPhysicalDeviceProperties * physicalDeviceProperties () const
 
VkSampleCountFlagBits sampleCountFlagBits () const
 
void setDeviceExtensions (const QStringList &extensions)
 
void setFlags (QVulkanWindow::VulkanFlags flags)
 
void setPhysicalDeviceIndex (int idx)
 
void setPreferredColorFormats (const QVector< VkFormat > &formats)
 
void setSampleCount (int sampleCount)
 
QVector< QVulkanExtensionPropertiessupportedDeviceExtensions ()
 
QVector< int > supportedSampleCounts ()
 
VkImage swapChainImage (int idx) const
 
int swapChainImageCount () const
 
QSize swapChainImageSize () const
 
VkImageView swapChainImageView (int idx) const
 
- Public Methods inherited from QWindow
 QWindow (QScreen *screen=nullptr)
 
 QWindow (QWindow *parent)
 
virtual ~QWindow ()
 
QSize baseSize () const
 
Qt::ScreenOrientation contentOrientation () const
 
void create ()
 
QCursor cursor () const
 
void destroy ()
 
qreal devicePixelRatio () const
 
QString filePath () const
 
Qt::WindowFlags flags () const
 
virtual QObjectfocusObject () const
 
QSurfaceFormat format () const override
 
QRect frameGeometry () const
 
QMargins frameMargins () const
 
QPoint framePosition () const
 
QRect geometry () const
 
QIcon icon () const
 
bool isActive () const
 
bool isAncestorOf (const QWindow *child, AncestorMode mode=IncludeTransients) const
 
bool isExposed () const
 
bool isModal () const
 
bool isTopLevel () const
 
bool isVisible () const
 
QPoint mapFromGlobal (const QPoint &pos) const
 
QPoint mapToGlobal (const QPoint &pos) const
 
QRegion mask () const
 
QSize maximumSize () const
 
QSize minimumSize () const
 
Qt::WindowModality modality () const
 
QWindow * parent () const
 
QPoint position () const
 
void reportContentOrientationChange (Qt::ScreenOrientation orientation)
 
QSurfaceFormat requestedFormat () const
 
void resize (const QSize &newSize)
 
void resize (int w, int h)
 
QScreenscreen () const
 
void setBaseSize (const QSize &size)
 
void setCursor (const QCursor &cursor)
 
void setFilePath (const QString &filePath)
 
void setFlags (Qt::WindowFlags flags)
 
void setFormat (const QSurfaceFormat &format)
 
void setFramePosition (const QPoint &point)
 
void setGeometry (const QRect &rect)
 
void setGeometry (int posx, int posy, int w, int h)
 
void setIcon (const QIcon &icon)
 
bool setKeyboardGrabEnabled (bool grab)
 
void setMask (const QRegion &region)
 
void setMaximumSize (const QSize &size)
 
void setMinimumSize (const QSize &size)
 
void setModality (Qt::WindowModality modality)
 
bool setMouseGrabEnabled (bool grab)
 
void setParent (QWindow *parent)
 
void setPosition (const QPoint &pt)
 
void setPosition (int posx, int posy)
 
void setScreen (QScreen *screen)
 
void setSizeIncrement (const QSize &size)
 
void setSurfaceType (SurfaceType surfaceType)
 
void setTransientParent (QWindow *parent)
 
void setVulkanInstance (QVulkanInstance *instance)
 
void setWindowState (Qt::WindowState state)
 
QSize size () const override
 
QSize sizeIncrement () const
 
SurfaceType surfaceType () const override
 
QWindow * transientParent () const
 
Qt::WindowType type () const
 
void unsetCursor ()
 
QVulkanInstancevulkanInstance () const
 
Qt::WindowState windowState () const
 
WId winId () const
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 
- Public Methods inherited from QSurface
virtual ~QSurface ()
 
bool supportsOpenGL () const
 
SurfaceClass surfaceClass () const
 

Static Public Members

static constexpr const int MAX_CONCURRENT_FRAME_COUNT = 10
 

Additional Inherited Members

- Public Signals inherited from QWindow
void contentOrientationChanged (Qt::ScreenOrientation orientation)
 
void focusObjectChanged (QObject *object)
 
void modalityChanged (Qt::WindowModality modality)
 
void screenChanged (QScreen *screen)
 
void windowStateChanged (Qt::WindowState windowState)
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 
- Public Slots inherited from QWindow
void alert (int msec)
 
bool close ()
 
void hide ()
 
void lower ()
 
void raise ()
 
void requestActivate ()
 
void requestUpdate ()
 
void setMaximumWidth (int width)
 
void setVisible (bool visible)
 
void show ()
 
void showFullScreen ()
 
void showMaximized ()
 
void showMinimized ()
 
void showNormal ()
 
- Public Slots inherited from QObject
void deleteLater ()
 
- Static Public Methods inherited from QWindow
static QWindow * fromWinId (WId id)
 
- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, std::nullptr_t, const QObject *receiver, std::nullptr_t)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 
- Protected Methods inherited from QWindow
bool event (QEvent *event) override
 
virtual void focusInEvent (QFocusEvent *event)
 
virtual void focusOutEvent (QFocusEvent *event)
 
virtual void hideEvent (QHideEvent *event)
 
virtual void keyPressEvent (QKeyEvent *event)
 
virtual void keyReleaseEvent (QKeyEvent *event)
 
virtual void mouseDoubleClickEvent (QMouseEvent *event)
 
virtual void mouseMoveEvent (QMouseEvent *event)
 
virtual void mousePressEvent (QMouseEvent *event)
 
virtual void mouseReleaseEvent (QMouseEvent *event)
 
virtual void moveEvent (QMoveEvent *event)
 
virtual bool nativeEvent (const QByteArray &eventType, void *message, long *result)
 
virtual void resizeEvent (QResizeEvent *event)
 
virtual void showEvent (QShowEvent *event)
 
virtual void tabletEvent (QTabletEvent *event)
 
virtual void wheelEvent (QWheelEvent *event)
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 
- Protected Methods inherited from QSurface
 QSurface (SurfaceClass type)
 
- Properties inherited from QWindow
 active
 
 contentOrientation
 
 flags
 
 height
 
 maximumHeight
 
 maximumWidth
 
 minimumHeight
 
 minimumWidth
 
 modality
 
 opacity
 
 title
 
 visibility
 
 visible
 
 width
 
 x
 
 y
 
- Properties inherited from QObject
 objectName
 

Detailed Description

QVulkanWindow is a Vulkan capable QWindow that manages a Vulkan device, a graphics queue, a command pool and buffer, a depth stencil image and a double-buffered FIFO swapchain, while taking care of correct behavior when it comes to events like resize, special situations like not having a device queue supporting both graphics and presentation, device lost scenarios, and additional functionality like reading the rendered content back. Conceptually it is the counterpart of QOpenGLWindow in the Vulkan system.

QVulkanWindow does not always eliminate the need to implement a fully custom QWindow subclass as it will not necessarily be sufficient in advanced use cases.

QVulkanWindow can be embedded into QWidget based user interfaces via QWidget::createWindowContainer(). This approach has a number of limitations.

Example

The following is a typical application using QVulkanWindow.

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;
};
class VulkanWindow : public QVulkanWindow
{
public:
return new VulkanRenderer(this);
}
};
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
// 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();
}

The following explains the funcionality of example shown above.

  • Similarly to QVulkanInstance, device extensions can be queried via supportedDeviceExtensions() before the actual initialization. Requesting an extension to be enabled is done via setDeviceExtensions(). Such calls must be made before the window becomes visible, that is, before calling show() or similar methods. Unsupported extension requests are gracefully ignored.
  • The renderer is implemented in a QVulkanWindowRenderer subclass, an instance of which is created in the createRenderer() factory method.
  • The basic Vulkan resources (physical device, graphics queue, a command pool, the window's main command buffer, image formats, etc.) are exposed on the QVulkanWindow via lightweight getter methods. Some of these are for convenience only, and applications are always free to query, create and manage additional resources directly via the Vulkan API.
  • The renderer lives in the gui/main thread, like the window itself. This thread is then throttled to the presentation rate, similarly to how OpenGL with a swap interval of 1 would behave. However, the renderer implementation is free to utilize multiple threads in any way it sees fit. The accessors like vulkanInstance(), currentCommandBuffer(), etc. can be called from any thread. The submission of the main command buffer, the queueing of present, and the building of the next frame do not start until frameReady() is invoked on the gui/main thread.

Critical errors are printed via qWarning() automatically.

Coordinate System

There are two notable differences to be aware of: First, with Vulkan Y points down the screen in clip space, while OpenGL uses an upwards pointing Y axis. Second, the standard OpenGL projection matrix assume a near and far plane values of -1 and 1, while Vulkan prefers 0 and 1.

In order to help applications migrate from OpenGL-based code without having to flip Y coordinates in the vertex data, and to allow using QMatrix4x4 methods like QMatrix4x4::perspective() while keeping the Vulkan viewport's minDepth and maxDepth set to 0 and 1, QVulkanWindow provides a correction matrix retrievable by calling clipCorrectionMatrix().

Multisampling

While disabled by default, multisample antialiasing is fully supported by QVulkanWindow. Additional color buffers and resolving into the swapchain's non-multisample buffers are all managed automatically.

To query the supported sample counts, call supportedSampleCounts(). When the returned set contains 4, 8, ..., passing one of those values to setSampleCount() requests multisample rendering.

Unlike QSurfaceFormat::setSamples(), the list of supported sample counts are exposed to the applications in advance and there is no automatic falling back to lower sample counts in setSampleCount(). If the requested value is not supported, a warning is shown and a no multisampling will be used.

sRGB Support

While many applications will be fine with the default behavior of QVulkanWindow when it comes to swapchain image formats, setPreferredColorFormats() allows requesting a pre-defined format. This is useful most notably when working in the sRGB color space. Passing a format like VK_FORMAT_B8G8R8A8_SRGB results in choosing an sRGB format, when available.

Validation Layers

During application development it can be extremely valuable to have the Vulkan validation layers enabled. As shown in the example code above, calling QVulkanInstance::setLayers() on the QVulkanInstance before QVulkanInstance::create() enables validation, assuming the Vulkan driver stack in the system contains the necessary layers.

Layers, Device Features, and Extensions

To enable instance layers call QVulkanInstance::setLayers() before creating the QVulkanInstance. To query what instance layer are available call QVulkanInstance::supportedLayers(). To enable device extensions, call setDeviceExtensions() early on when setting up the QVulkanWindow. To query what device extensions are available, call supportedDeviceExtensions().

Specifying an unsupported layer or extension is handled gracefully: this will not fail instance or device creation, but the layer or extension request is rather ignored.

QVulkanWindow enables all Vulkan 1.1 features which are reported as supported from vkGetPhysicalDeviceFeatures().

See also
QVulkanInstance, QVulkanWindowRenderer, QWindow

Member Typedef Documentation

Typedef for QFlags<VulkanOptions> which contains an OR combination of VulkanOptions values.

Refer to QVulkanWindow::VulkanOptions for the enum documentation.

Member Enumeration Documentation

This enum describes the flags that can be passed to setFlags().

Constant Value Description
QVulkanWindow::PersistentResources 0x0001 Ensures no graphics resources are released when the window becomes unexposed. The default behavior is to release everything and reinitialize later when it becomes visible again.

Constructor & Destructor Documentation

QVulkanWindow::QVulkanWindow ( QWindow parent = nullptr)

Constructs a new QVulkanWindow with the given parent. The surface type is set to QSurface::VulkanSurface.

QVulkanWindow::~QVulkanWindow ( )

Destroys the QVulkanWindow.

Method Documentation

QVector< VkPhysicalDeviceProperties > QVulkanWindow::availablePhysicalDevices ( )

Returns the list of properties for the supported physical devices in the system.

This method can be called before making the window visible.

QMatrix4x4 QVulkanWindow::clipCorrectionMatrix ( )

Returns a QMatrix4x4 that can be used to correct for coordinate system differences between OpenGL and Vulkan.

By pre-multiplying the projection matrix with this matrix, applications can continue to assume that Y is pointing upwards, and can set minDepth and maxDepth in the viewport to 0 and 1, respectively, without having to do any further corrections to the vertex Z positions. Geometry from OpenGL applications can then be used as-is, assuming a rasterization state matching the OpenGL culling and front face settings.

VkFormat QVulkanWindow::colorFormat ( ) const

Returns the color buffer format used by the swapchain.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources().
See also
setPreferredColorFormats()
int QVulkanWindow::concurrentFrameCount ( ) const

Returns the number of frames which can be potentially active at the same time. This value is constant for the entire lifetime of the QVulkanWindow.

See also
currentFrame()
QVulkanWindowRenderer * QVulkanWindow::createRenderer ( )
virtual

Returns a new instance of QVulkanWindowRenderer. This method is called once during the lifetime of the window, at some point after making it visible for the first time. The default implementation returns null and so no rendering will be performed apart from clearing the buffers.

The window takes ownership of the returned renderer object.

VkCommandBuffer QVulkanWindow::currentCommandBuffer ( ) const

Returns The active command buffer for the current swap chain image. Implementations of QVulkanWindowRenderer::startNextFrame() are expected to add commands to this command buffer.

Note
This method must only be called from within startNextFrame() and, in case of asynchronous command generation, up until the call to frameReady().
int QVulkanWindow::currentFrame ( ) const

Returns the current frame index in the range [0, concurrentFrameCount() - 1].

Renderer implementations will have to ensure that uniform data and other dynamic resources exist in multiple copies, in order to prevent frame N altering the data used by the still-active frames N - 1, N - 2, ... N - concurrentFrameCount() + 1.

To avoid relying on dynamic array sizes, applications can use MAX_CONCURRENT_FRAME_COUNT when declaring arrays. This is guaranteed to be always equal to or greater than the value returned from concurrentFrameCount(). Such arrays can then be indexed by the value returned from this function.

This method must only be called from within startNextFrame() and in case of asynchronous command generation, up until the call to frameReady().

class Renderer
{
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
QVulkanWindow *m_window;
};
void Renderer::startNextFrame()
{
VkDescriptorBufferInfo &currentBufInfo = m_uniformBufInfo[m_window->currentFrame()];
// populate currentBufInfo
}
See also
concurrentFrameCount()
VkFramebuffer QVulkanWindow::currentFramebuffer ( ) const

Returns a VkFramebuffer for the current swapchain image using the default render pass.

The framebuffer has two attachments (color, depth-stencil) when multisampling is not in use, and three (color resolve, depth-stencil, multisample color) when sampleCountFlagBits() is greater than VK_SAMPLE_COUNT_1_BIT. Renderers must take this into account, for example when providing clear values.

Note
Applications are not required to use this framebuffer in case they provide their own render pass instead of using the one returned from defaultRenderPass().
This method must only be called from within startNextFrame() and in case of asynchronous command generation, up until the call to frameReady().
See also
defaultRenderPass()
int QVulkanWindow::currentSwapChainImageIndex ( ) const

Returns the current swap chain image index in the range [0, swapChainImageCount() - 1].

Note
This method must only be called from within startNextFrame() and in case of asynchronous command generation, up until the call to frameReady().
VkRenderPass QVulkanWindow::defaultRenderPass ( ) const

Returns a typical render pass with one sub-pass.

Note
Applications are not required to use this render pass. However, they are then responsible for ensuring the current swap chain and depth-stencil images get transitioned from VK_IMAGE_LAYOUT_UNDEFINED to VK_IMAGE_LAYOUT_PRESENT_SRC_KHR and VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL either via the application's custom render pass or by other means.
Stencil read/write is not enabled in this render pass.
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources().
See also
currentFramebuffer()
VkFormat QVulkanWindow::depthStencilFormat ( ) const

Returns the format used by the depth stencil buffers.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources().
VkImage QVulkanWindow::depthStencilImage ( ) const

Returns the depth-stencil image.

Note
Calling this function is only valid from the invocation of QVulkanWindowRenderer::initSwapChainResources() up until QVulkanWindowRenderer::releaseSwapChainResources().
VkImageView QVulkanWindow::depthStencilImageView ( ) const

Returns the depth-stencil image view.

Note
Calling this function is only valid from the invocation of QVulkanWindowRenderer::initSwapChainResources() up until QVulkanWindowRenderer::releaseSwapChainResources().
VkDevice QVulkanWindow::device ( ) const

Returns the active logical device.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources().
uint32_t QVulkanWindow::deviceLocalMemoryIndex ( ) const

Returns a device local memory type index suitable for general use.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources().
It is not guaranteed that this memory type is always suitable. The correct, cross-implementation solution, especially for device local images, is to manually pick a memory type after checking the mask returned from vkGetImageMemoryRequirements.
void QVulkanWindow::exposeEvent ( QExposeEvent event)
overridevirtual

The expose event (event) is sent by the window system whenever the window's exposure on screen changes.

The application can start rendering into the window with QBackingStore and QOpenGLContext as soon as it gets an exposeEvent() such that isExposed() is true.

If the window is moved off screen, is made totally obscured by another window, iconified or similar, this function might be called and the value of isExposed() might change to false. When this happens, an application should stop its rendering as it is no longer visible to the user.

A resize event will always be sent before the expose event the first time a window is shown.

See also
isExposed()

Reimplemented from QWindow::exposeEvent()

QVulkanWindow::VulkanFlags QVulkanWindow::flags ( ) const

Return the requested flags.

void QVulkanWindow::frameReady ( )

This method must be called exactly once in response to each invocation of the QVulkanWindowRenderer::startNextFrame() implementation. At the time of this call, the main command buffer, exposed via currentCommandBuffer(), must have all necessary rendering commands added to it since this method will trigger submitting the commands and queuing the present command.

Note
This method must only be called from the gui/main thread which is where QVulkanWindowRenderer's methods are invoked and where the QVulkanWindow instance lives.
See also
QVulkanWindowRenderer::startNextFrame()
VkCommandPool QVulkanWindow::graphicsCommandPool ( ) const

Returns the active graphics command pool.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources().
VkQueue QVulkanWindow::graphicsQueue ( ) const

Returns the active graphics queue.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources().
uint32_t QVulkanWindow::graphicsQueueFamilyIndex ( ) const

Returns the family index of the active graphics queue.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources(). Implementations of QVulkanWindowRenderer::updateQueueCreateInfo() can also call this method.
uint32_t QVulkanWindow::hostVisibleMemoryIndex ( ) const

Returns a host visible memory type index suitable for general use. The returned memory type will be both host visible and coherent. In addition, it will also be cached, if possible.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initResources() up until QVulkanWindowRenderer::releaseResources().
bool QVulkanWindow::isValid ( ) const

Returns true if this window has successfully initialized all Vulkan resources, including the swapchain.

Note
Initialization happens on the first expose event after the window is made visible.
VkImage QVulkanWindow::msaaColorImage ( int  idx) const

Returns the specified multisample color image, or VK_NULL_HANDLE if multisampling is not in use. The given idx must be in the range [0, swapChainImageCount() - 1].

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initSwapChainResources() up until QVulkanWindowRenderer::releaseSwapChainResources().
VkImageView QVulkanWindow::msaaColorImageView ( int  idx) const

Returns the specified multisample color image view, or VK_NULL_HANDLE if multisampling is not in use. The given idx must be in the range [0, swapChainImageCount() - 1].

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::initSwapChainResources() up until QVulkanWindowRenderer::releaseSwapChainResources().
VkPhysicalDevice QVulkanWindow::physicalDevice ( ) const

Returns the active physical device.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::preInitResources() up until QVulkanWindowRenderer::releaseResources().
const VkPhysicalDeviceProperties * QVulkanWindow::physicalDeviceProperties ( ) const

Returns a pointer to the properties for the active physical device.

Note
Calling this method is only valid from the invocation of QVulkanWindowRenderer::preInitResources() up until QVulkanWindowRenderer::releaseResources().
VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits ( ) const

Returns the current sample count as a VkSampleCountFlagBits value. When targeting the default render target, the rasterizationSamples field of VkPipelineMultisampleStateCreateInfo must be set to this value.

See also
setSampleCount(), supportedSampleCounts()
void QVulkanWindow::setDeviceExtensions ( const QStringList extensions)

Sets the list of device extensions to be enabled. Unsupported extensions are ignored. The swapchain extension will always be added automatically, no need to include it in this list.

Note
This method must be called before the window is made visible or at latest in QVulkanWindowRenderer::preInitResources(), and has no effect if called afterwards.
void QVulkanWindow::setFlags ( QVulkanWindow::VulkanFlags  flags)

Configures the behavior based on the provided flags.

Note
This method must be called before the window is made visible or at latest in QVulkanWindowRenderer::preInitResources(), and has no effect if called afterwards.
void QVulkanWindow::setPhysicalDeviceIndex ( int  idx)

Requests the usage of the physical device with index idx. The index corresponds to the list returned from availablePhysicalDevices().

By default the first physical device is used.

Note
This method must be called before the window is made visible or at latest in QVulkanWindowRenderer::preInitResources(), and has no effect if called afterwards.
void QVulkanWindow::setPreferredColorFormats ( const QVector< VkFormat > &  formats)

Sets the preferred formats of the swapchain. By default no application-preferred format is set. In this case the surface's preferred format will be used or, in absence of that, VK_FORMAT_B8G8R8A8_UNORM.

The list in formats is ordered. If the first format is not supported, the second will be considered, and so on. When no formats in the list are supported, the behavior is the same as in the default case.

To query the actual format after initialization, call colorFormat().

Note
This method must be called before the window is made visible or at latest in QVulkanWindowRenderer::preInitResources(), and has no effect if called afterwards.
Reimplementing QVulkanWindowRenderer::preInitResources() allows dynamically examining the list of supported formats, should that be desired. There the surface is retrievable via QVulkanInstace::surfaceForWindow(), while this method can still safely be called to affect the later stages of initialization.
See also
colorFormat()
void QVulkanWindow::setSampleCount ( int  sampleCount)

Requests multisample antialiasing with the given sampleCount. The valid values are 1, 2, 4, 8, ... up until the maximum value supported by the physical device.

When the sample count is greater than 1, QVulkanWindow will create a multisample color buffer instead of simply targeting the swapchain's images. The rendering in the multisample buffer will get resolved into the non-multisample buffers at the end of each frame.

To examine the list of supported sample counts, call supportedSampleCounts().

When setting up the rendering pipeline, call sampleCountFlagBits() to query the active sample count as a VkSampleCountFlagBits value.

Note
This method must be called before the window is made visible or at latest in QVulkanWindowRenderer::preInitResources(), and has no effect if called afterwards.
See also
supportedSampleCounts(), sampleCountFlagBits()
QVector< QVulkanExtensionProperties > QVulkanWindow::supportedDeviceExtensions ( )

Returns the list of the extensions that are supported by logical devices created from the physical device selected by setPhysicalDeviceIndex().

This method can be called before making the window visible.

QVector< int > QVulkanWindow::supportedSampleCounts ( )

Returns the set of supported sample counts when using the physical device selected by setPhysicalDeviceIndex(), as a sorted list.

By default QVulkanWindow uses a sample count of 1. By calling setSampleCount() with a different value (2, 4, 8, ...) from the set returned by this method, multisample anti-aliasing can be requested.

This method can be called before making the window visible.

See also
setSampleCount()
VkImage QVulkanWindow::swapChainImage ( int  idx) const

Returns the specified swap chain image. The given idx must be in the range [0, swapChainImageCount() - 1].

It is only valid to call this method between calling QVulkanWindowRenderer::initSwapChainResources() and QVulkanWindowRenderer::releaseSwapChainResources().

int QVulkanWindow::swapChainImageCount ( ) const

Returns the number of images in the swap chain. Calling this method is required when providing a custom render pass and framebuffer. The framebuffer is specific to the current swapchain image and hence the application must provide multiple framebuffers.

It is only valid to call this method between calling QVulkanWindowRenderer::initSwapChainResources() and QVulkanWindowRenderer::releaseSwapChainResources().

QSize QVulkanWindow::swapChainImageSize ( ) const

Returns the image size of the swapchain. This usually matches the size of the window, but may also differ in case vkGetPhysicalDeviceSurfaceCapabilitiesKHR reports a fixed size.

It is only valid to call this method between calling QVulkanWindowRenderer::initSwapChainResources() and QVulkanWindowRenderer::releaseSwapChainResources().

VkImageView QVulkanWindow::swapChainImageView ( int  idx) const

Returns the specified swap chain image view. The given idx must be in the range [0, swapChainImageCount() - 1].

It is only valid to call this method between calling QVulkanWindowRenderer::initSwapChainResources() and QVulkanWindowRenderer::releaseSwapChainResources().

Member Data Documentation

QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT = 10
deprecatedstaticconstexpr

A constant value which is always equal to or greater than the maximum value of concurrentFrameCount().