QVulkanInstance 类

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

}

bool myDebugFilter(VkDebugReportFlagsEXT flags, VkDebugReportObjectTypeEXT objectType, uint64_t object,
                   size_t location, int32_t messageCode, const char *pLayerPrefix, const char *pMessage)

std::function<bool(DebugMessageSeverityFlags severity, DebugMessageTypeFlags type, const void *message)>;

成员函数文档

QVulkanInstance::QVulkanInstance()

构造一个新实例。

[noexcept] QVulkanInstance::~QVulkanInstance()

析构函数。

QVersionNumber QVulkanInstance::apiVersion() const

返回应用程序期望运行的请求的Vulkan API版本，或者在调用setApiVersion()之前没有调用create()时，返回一个空版本号。

另请参阅 setApiVersion()。

[since 6.5] void QVulkanInstance::clearDebugOutputFilters()

删除之前通过 installDebugOutputFilter() 安装的 所有过滤器函数。

此功能是在 Qt 6.5 中引入的。

另请参阅 installDebugOutputFilter。

bool QVulkanInstance::create()

初始化 Vulkan 库并创建一个新的或采用现有的 Vulkan 实例。

如果成功则返回 true，如果出错或 Vulkan 不受支持则返回 false。

如果成功，可以通过 vkInstance() 获取此 QVulkanInstance 的指针。

Vulkan 实例和库在 QVulkanInstance 存在期间或直到调用 destroy() 时都可用。

默认情况下，VkInstance 使用具有 VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR 标志创建。这意味着还将枚举 Vulkan 可移植物理设备。如果不希望这样，请设置 NoPortabilityDrivers 标志。

void QVulkanInstance::destroy()

销毁底层的平台实例，从而销毁 VkInstance（当所有者时）。QVulkanInstance 对象可以通过再次调用 create() 重新使用。

QVulkanDeviceFunctions *QVulkanInstance::deviceFunctions(VkDevice device)

返回一个 QVulkanDeviceFunctions 对象，该对象公开了设备级别的 Vulkan 核心命令集，并且跨平台保证可用。

核心 Vulkan 1.0 API 的功能将始终可用。当涉及到更高的 Vulkan 版本，如 1.1 和 1.2 时，QVulkanDeviceFunctions 对象将尝试为这些版本解析核心 API 功能，但如果运行时 Vulkan 物理设备不支持这些功能，则调用任何此类不受支持的功能将导致未指定行为。要正确启用对高于 1.0 的 Vulkan 版本的支持，可能需要通过在 setApiVersion() 调用之前设置合适的实例 API 版本来调用 create()。此外，应用程序应检查 VkPhysicalDeviceProperties 中的物理设备的 apiVersion。

另外参见 functions() 和 resetDeviceFunctions。

VkResult QVulkanInstance::errorCode() const

在不成功调用 create() 后返回 Vulkan 错误代码；否则返回 VK_SUCCESS。

该值通常是创建新 Vulkan 实例时从 vkCreateInstance() 返回的值（而不是采用现有实例），但如果平台插件不支持 Vulkan，也可能返回 VK_NOT_READY。

QByteArrayList QVulkanInstance::extensions() const

当 create() 被调用并且成功时，返回启用的实例扩展。否则返回请求的扩展。

另外参见 setExtensions。

QVulkanInstance::Flags QVulkanInstance::flags() const

返回请求的标志。

另外参见 setFlags。

QVulkanFunctions *QVulkanInstance::functions() const

返回对应的 QVulkanFunctions 对象，该对象公开核心 Vulkan 命令集，不包括设备级别功能，并且在跨平台保证中始终是有效的。

核心 Vulkan 1.0 API 的功能将始终可用。当涉及到更高的 Vulkan 版本，如 1.1 和 1.2 时，QVulkanFunctions 对象将尝试为这些版本解析核心 API 功能，但如果运行时 Vulkan 实现不支持这些功能，则调用任何此类不受支持的功能将导致未指定行为。此外，要正确启用对高于 1.0 的 Vulkan 版本的支持，可能需要通过在 setApiVersion() 调用之前设置合适的实例 API 版本来调用 create()。为了查询 Vulkan 实现的实例级别版本，请调用 supportedApiVersion()。

另外参见 deviceFunctions() 和 supportedApiVersion。

PFN_vkVoidFunction QVulkanInstance::getInstanceProcAddr(const char *name)

解析具有给定 name 的 Vulkan 函数。

对于核心 Vulkan 命令，最好使用从 functions() 和 deviceFunctions() 可获取的函数包装器。

[since 6.5] void QVulkanInstance::installDebugOutputFilter(QVulkanInstance::DebugUtilsFilter filter)

为每个 Vulkan 调试消息安装一个 filter 函数。当回调返回 true 时，消息被阻止（过滤掉）并不会出现在调试输出中。

此功能是在 Qt 6.5 中引入的。

另请参阅clearDebugOutputFilters。

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

这是一个重载函数。

为每个 Vulkan 调试消息安装一个 filter 函数。当回调返回 true 时，消息被阻止（过滤掉）并不会出现在调试输出中。

另请参阅removeDebugOutputFilter。

bool QVulkanInstance::isValid() const

如果 create() 运行成功且实例有效，则返回 true。

QByteArrayList QVulkanInstance::layers() const

如果在调用 create() 且成功情况下，返回启用的实例层，否则返回请求的层。

另请参阅setLayers。

void QVulkanInstance::presentAboutToBeQueued(QWindow *window)

在将 window 的呈现操作入队列之前，应由应用程序的渲染器调用此函数。

虽然在某些平台上这可能是无操作的，但是一些可能会执行与窗口系统相关的同步。例如，在 Wayland 上，这将发送一个 wl_surface.frame 请求，以防止驱动程序在最小化窗口上阻塞。

void QVulkanInstance::presentQueued(QWindow *window)

在将 window 的呈现操作入队列后，应由应用程序的渲染器调用此函数。

虽然在某些平台上这可能是无操作的，但是一些可能会执行与窗口系统相关的同步。例如，在 X11 上，这将更新 _NET_WM_SYNC_REQUEST_COUNTER。

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

这是一个重载函数。

移除通过 installDebugOutputFilter 安装的先前安装的 filter 函数。

另请参阅 installDebugOutputFilter。

void QVulkanInstance::resetDeviceFunctions(VkDevice device)

使给定 device 的 QVulkanDeviceFunctions 对象失效并销毁。

当在应用程序打算继续运行的情况下销毁一个 VkDevice，并且可能稍后创建新的逻辑 Vulkan 设备时，必须调用此函数。

在销毁 QVulkanInstance 之前无需调用此函数，因为此时会自动进行清理。

另请参阅deviceFunctions。

void QVulkanInstance::setApiVersion(const QVersionNumber &vulkanVersion)

指定应用程序设计使用的最高 Vulkan API 版本。

默认情况下，vulkanVersion 为 0，对应 Vulkan 1.0。

建议应用程序开发人员熟悉 Vulkan 规范中关于 apiVersion 的说明，参见Vulkan 规范。

另请参阅：apiVersion() 和 supportedApiVersion()。

void QVulkanInstance::setExtensions(const QByteArrayList &extensions)

指定启用额外的实例 扩展 的列表。也可以安全地指定不支持扩展，因为这些在运行时不受支持时会被忽略。

另请参阅：extensions()。

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

根据提供的 标志 配置 create() 的行为。

另请参阅：flags()。

void QVulkanInstance::setLayers(const QByteArrayList &layers)

指定要启用的实例 层 的列表。也可以安全地指定不支持层，因为这些在运行时不受支持时会被忽略。

另请参阅：layers()。

void QVulkanInstance::setVkInstance(VkInstance existingVkInstance)

使 QVulkanInstance 采取现有的 VkInstance 处理，而不是创建一个新的。

另请参阅：vkInstance()。

QVersionNumber QVulkanInstance::supportedApiVersion() const

返回 Vulkan 实现支持的实例级功能版本。

实际上，这可能是如果该函数可用（对于 Vulkan 1.1 及更高版本）的情况下从 vkEnumerateInstanceVersion 返回的值，或者为 1.0。

希望根据运行时提供的 Vulkan 版本根据自己的 Vulkan 特性和 API 使用进行分支的应用程序可以使用此函数在调用 create() 之前确定传递给 setApiVersion() 的版本。

另请参阅 setApiVersion()。

QVulkanInfoVector<QVulkanExtension> QVulkanInstance::supportedExtensions() const

返回支持实例级别的扩展列表。

QVulkanInfoVector<QVulkanLayer> QVulkanInstance::supportedLayers() const

返回支持实例级别的层列表。

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

如果 queueFamilyIndex 在 physicalDevice 中的队列家族支持向 window 展示，返回 true。

在检查指定 Vulkan 设备的队列时调用此函数，以确定哪个队列可用于执行展示。

[静态] VkSurfaceKHR QVulkanInstance::surfaceForWindow(QWindow *window)

创建或检索给定 window 的已存在的 VkSurfaceKHR 处理句柄。

返回 Vulkan 表面处理句柄或失败时返回 0。

VkInstance QVulkanInstance::vkInstance() const

返回此 QVulkanInstance 所封装的 VkInstance 处理句柄，或在 create() 尚未成功调用且未通过 setVkInstance() 提供现有实例时返回 nullptr。

另请参阅 setVkInstance。