QVulkanInstance Class

    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();
    }

    QVulkanInstance inst;

    // Enable validation layer, if supported. Messages go to qDebug by default.
    inst.setLayers({ "VK_LAYER_KHRONOS_validation" });

    bool ok = inst.create();
    if (!ok) {
        // ... Vulkan not available
    }

    if (!inst.layers().contains("VK_LAYER_KHRONOS_validation")) {
        // ... validation layer not available
    }

    QVulkanInstance inst;

    if (inst.supportedLayers().contains("VK_LAYER_KHRONOS_validation")) {
        // ...
    }
    bool ok = inst.create();
    // ...

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();

}

Member Function Documentation

QVulkanInstance::QVulkanInstance()

Constructs a new instance.

QVulkanInstance::~QVulkanInstance()

Destructor.

QVersionNumber QVulkanInstance::apiVersion() const

Returns the requested Vulkan API version against which the application expects to run, or a null version number if setApiVersion() was not called before create().

See also setApiVersion().

bool QVulkanInstance::create()

Initializes the Vulkan library and creates a new or adopts and existing Vulkan instance.

Returns true if successful, false on error or when Vulkan is not supported.

When successful, the pointer to this QVulkanInstance is retrievable via the static function current().

The Vulkan instance and library is available as long as this QVulkanInstance exists, or until destroy() is called.

The VkInstance is always created with the flag VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR set. This means that Vulkan Portability physical devices get enumerated as well.

void QVulkanInstance::destroy()

Destroys the underlying platform instance, thus destroying the VkInstance (when owned). The QVulkanInstance object is still reusable by calling create() again.

QVulkanDeviceFunctions *QVulkanInstance::deviceFunctions(VkDevice device)

Returns the QVulkanDeviceFunctions object that exposes the device level core Vulkan command set and is guaranteed to be functional cross-platform.

The functions from the core Vulkan 1.0 API will be available always. When it comes to higher Vulkan versions, such as, 1.1 and 1.2, the QVulkanDeviceFunctions object will try to resolve the core API functions for those as well, but if the Vulkan physical device at run time has no support for those, calling any such unsupported function will lead to unspecified behavior. To properly enable support for Vulkan versions higher than 1.0, an appropriate instance API version may need to be set by calling setApiVersion() before create(). In addition, applications are expected to check the physical device's apiVersion in VkPhysicalDeviceProperties.

See also functions() and resetDeviceFunctions().

VkResult QVulkanInstance::errorCode() const

Returns the Vulkan error code after an unsuccessful create(), VK_SUCCESS otherwise.

The value is typically the return value from vkCreateInstance() (when creating a new Vulkan instance instead of adopting an existing one), but may also be VK_NOT_READY if the platform plugin does not support Vulkan.

QByteArrayList QVulkanInstance::extensions() const

Returns the enabled instance extensions, if create() was called and was successful. The requested extensions otherwise.

See also setExtensions().

QVulkanInstance::Flags QVulkanInstance::flags() const

Returns the requested flags.

See also setFlags().

QVulkanFunctions *QVulkanInstance::functions() const

Returns the corresponding QVulkanFunctions object that exposes the core Vulkan command set, excluding device level functions, and is guaranteed to be functional cross-platform.

The functions from the core Vulkan 1.0 API will be available always. When it comes to higher Vulkan versions, such as, 1.1 and 1.2, the QVulkanFunctions object will try to resolve the core API functions for those as well, but if the Vulkan instance implementation at run time has no support for those, calling any such unsupported function will lead to unspecified behavior. In addition, to properly enable support for Vulkan versions higher than 1.0, an appropriate instance API version may need to be set by calling setApiVersion() before create(). To query the Vulkan implementation's instance-level version, call supportedApiVersion().

See also deviceFunctions() and supportedApiVersion().

PFN_vkVoidFunction QVulkanInstance::getInstanceProcAddr(const char *name)

Resolves the Vulkan function with the given name.

For core Vulkan commands prefer using the function wrappers retrievable from functions() and deviceFunctions() instead.

void QVulkanInstance::installDebugOutputFilter(QVulkanInstance::DebugFilter filter)

Installs a filter function that is called for every Vulkan debug message. When the callback returns true, the message is stopped (filtered out) and will not appear on the debug output.

See also removeDebugOutputFilter().

bool QVulkanInstance::isValid() const

Returns true if create() was successful and the instance is valid.

QByteArrayList QVulkanInstance::layers() const

Returns the enabled instance layers, if create() was called and was successful. The requested layers otherwise.

See also setLayers().

[since 5.15] void QVulkanInstance::presentAboutToBeQueued(QWindow *window)

This function should be called by the application's renderer before queuing a present operation for window.

While on some platforms this will be a no-op, some may perform windowing system dependent synchronization. For example, on Wayland this will add send a wl_surface.frame request in order to prevent the driver from blocking for minimized windows.

This function was introduced in Qt 5.15.

void QVulkanInstance::presentQueued(QWindow *window)

This function should be called by the application's renderer after queuing a present operation for window.

While on some platforms this will be a no-op, some may perform windowing system dependent synchronization. For example, on X11 this will update _NET_WM_SYNC_REQUEST_COUNTER.

void QVulkanInstance::removeDebugOutputFilter(QVulkanInstance::DebugFilter filter)

Removes a filter function previously installed by installDebugOutputFilter().

See also installDebugOutputFilter().

void QVulkanInstance::resetDeviceFunctions(VkDevice device)

Invalidates and destroys the QVulkanDeviceFunctions object for the given device.

This function must be called when a VkDevice, for which deviceFunctions() was called, gets destroyed while the application intends to continue running, possibly creating a new logical Vulkan device later on.

There is no need to call this before destroying the QVulkanInstance since clean up is then performed automatically.

See also deviceFunctions().

void QVulkanInstance::setApiVersion(const QVersionNumber &vulkanVersion)

Specifies the highest Vulkan API version the application is designed to use.

By default vulkanVersion is 0, which maps to Vulkan 1.0.

Application developers are advised to familiarize themselves with the apiVersion notes in the Vulkan specification.

See also apiVersion() and supportedApiVersion().

void QVulkanInstance::setExtensions(const QByteArrayList &extensions)

Specifies the list of additional instance extensions to enable. It is safe to specify unsupported extensions as well because these get ignored when not supported at run time.

See also extensions().

void QVulkanInstance::setFlags(QVulkanInstance::Flags flags)

Configures the behavior of create() based on the provided flags.

See also flags().

void QVulkanInstance::setLayers(const QByteArrayList &layers)

Specifies the list of instance layers to enable. It is safe to specify unsupported layers as well because these get ignored when not supported at run time.

See also layers().

void QVulkanInstance::setVkInstance(VkInstance existingVkInstance)

Makes QVulkanInstance adopt an existing VkInstance handle instead of creating a new one.

See also vkInstance().

QVersionNumber QVulkanInstance::supportedApiVersion() const

Returns the version of instance-level functionality supported by the Vulkan implementation.

In practice this is either the value returned from vkEnumerateInstanceVersion, if that function is available (with Vulkan 1.1 and newer), or 1.0.

Applications that want to branch in their Vulkan feature and API usage based on what Vulkan version is available at run time, can use this function to determine what version to pass in to setApiVersion() before calling create().

See also setApiVersion().

QVulkanInfoVector<QVulkanExtension> QVulkanInstance::supportedExtensions() const

Returns the list of supported instance-level extensions.

QVulkanInfoVector<QVulkanLayer> QVulkanInstance::supportedLayers() const

Returns the list of supported instance-level layers.

bool QVulkanInstance::supportsPresent(VkPhysicalDevice physicalDevice, uint32_t queueFamilyIndex, QWindow *window)

Returns true if the queue family with queueFamilyIndex within the physicalDevice supports presenting to window.

Call this function when examining the queues of a given Vulkan device, in order to decide which queue can be used for performing presentation.

[static] VkSurfaceKHR QVulkanInstance::surfaceForWindow(QWindow *window)

Creates or retrieves the already existing VkSurfaceKHR handle for the given window.

Returns the Vulkan surface handle or 0 when failed.

VkInstance QVulkanInstance::vkInstance() const

Returns the VkInstance handle this QVulkanInstance wraps, or nullptr if create() has not yet been successfully called and no existing instance has been provided via setVkInstance().

See also setVkInstance().