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

classVulkanWindow :publicQWindow
{
public:
    VulkanWindow() {
        setSurfaceType(VulkanSurface);
    }

    voidexposeEvent(QExposeEvent*) {
        if(isExposed()) {
            if(!m_initialized) {
                m_initialized= true;
                // 初始化设备、交换链等。
                QVulkanInstance*inst =vulkanInstance();
                QVulkanFunctions*f = inst->functions();
                uint32_t devCount= 0;
                f->vkEnumeratePhysicalDevices(inst->vkInstance(), &devCount,nullptr);
                // ...
               // 构建第一帧
                render();
            }
        }
    }

    boolevent(QEvent*e) {
        if(e->type()==QEvent::UpdateRequest)
            render();
        returnQWindow::event(e);
    }

   voidrender() {
       // ...
       requestUpdate();// 持续渲染
    }

private:
    boolm_initialized= false;
};

intmain(intargc, char**argv)
{
    QGuiApplication app(argc,argv);

    QVulkanInstance inst;
    if(!inst.create()) {
        qWarning("Vulkan not available");
       return 1;
    }

    VulkanWindow window;
    window.showMaximized();

    returnapp.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 版本；如果在调用create() 之前未调用setApiVersion()，则返回空版本号。

另请参阅 setApiVersion()。

[since 6.5] void QVulkanInstance::clearDebugOutputFilters()

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

该函数在 Qt 6.5 中引入。

另请参阅 installDebugOutputFilter()。

bool QVulkanInstance::create()

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

若操作成功则返回 true，若发生错误或不支持 Vulkan 则返回 false。

成功时，可通过 `vkInstance()` 获取该 `QVulkanInstance ` 的指针。

只要该 `QVulkanInstance ` 存在，或者在调用 `destroy()` 之前，Vulkan 实例和库均可使用。

默认情况下，创建 VkInstance 时会设置VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR标志。这意味着 Vulkan 可移植性（Vulkan Portability）的物理设备也会被枚举。如果不需要此功能，请设置NoPortabilityDrivers 标志。

void QVulkanInstance::destroy()

销毁底层平台实例，从而销毁 VkInstance（当其被拥有时）。通过再次调用create()，QVulkanInstance 对象仍可被重复使用。

QVulkanDeviceFunctions *QVulkanInstance::deviceFunctions(VkDevice device)

返回一个QVulkanDeviceFunctions 对象，该对象提供了设备级核心Vulkan命令集，并保证在跨平台环境下均可正常运行。

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

另请参阅 functions() 和resetDeviceFunctions()。

VkResult QVulkanInstance::errorCode() const

在create()调用失败后返回Vulkan错误代码，否则返回VK_SUCCESS 。

该值通常是 vkCreateInstance() 的返回值（当创建新的 Vulkan 实例而非采用现有实例时），但如果平台插件不支持 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 实例实现不支持这些函数，调用任何此类不受支持的函数都将导致未定义的行为。 此外，为了正确启用对 Vulkan 1.0 以上版本的支持，可能需要在调用 `create()` 之前，通过调用 `setApiVersion()` 来设置适当的实例 API 版本。要查询 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)

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

该函数在 Qt 6.5 中引入。

另请参阅 clearDebugOutputFilters()。

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

安装一个filter 函数，该函数会在每次输出Vulkan调试消息时被调用。当回调函数返回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 对象失效并销毁该对象。

当某个已调用过 `deviceFunctions()` 的 `VkDevice` 被销毁，而应用程序仍打算继续运行（且可能在后续创建新的逻辑 Vulkan 设备）时，必须调用此函数。

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

另请参阅 deviceFunctions()。

void QVulkanInstance::setApiVersion(const QVersionNumber &vulkanVersion)

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

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

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

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

void QVulkanInstance::setExtensions(const QByteArrayList &extensions)

指定要启用的额外实例extensions 列表。即使指定了不受支持的扩展也完全安全，因为在运行时若不支持，这些扩展会被忽略。

另请参阅 extensions()。

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

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

另请参阅 flags()。

void QVulkanInstance::setLayers(const QByteArrayList &layers)

指定要启用的实例layers 列表。即使指定了不受支持的图层也无妨，因为在运行时若不支持，这些图层会被忽略。

另请参阅 layers()。

void QVulkanInstance::setVkInstance(VkInstance existingVkInstance)

使QVulkanInstance 采用现有的VkInstance句柄，而不是创建一个新的。

Qt 无法在已创建的 VkInstance 上启用图层和扩展。 因此，调用方有责任确保existingVkInstance 适合与 Qt 配合使用。如果涉及基于QRhi 的渲染，请调用QRhiVulkanInitParams::preferredInstanceExtensions() 来查询一组额外的实例扩展列表——这些扩展应由existingVkInstance 的创建者启用，作为上述扩展的补充，前提是运行时系统可提供并支持这些扩展。

另请参阅 vkInstance()。

QVersionNumber QVulkanInstance::supportedApiVersion() const

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

实际上，该值要么是 vkEnumerateInstanceVersion 函数返回的值（如果该函数可用，即在 Vulkan 1.1 及更高版本中），要么就是 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)

如果physicalDevice 中包含queueFamilyIndex 的队列族支持向window 呈现，则返回true。

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

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

为给定的window 创建或获取已存在的VkSurfaceKHR 句柄。

返回 Vulkan 表面句柄；若操作失败，则返回 0。

VkInstance QVulkanInstance::vkInstance() const

返回该QVulkanInstance 所封装的VkInstance句柄；如果尚未成功调用create()，且未通过setVkInstance()提供现有实例，则返回nullptr 。

另请参阅 setVkInstance()。