QVulkanWindow Class
QVulkanWindow 类是QWindow 的一个便捷子类，用于执行 Vulkan 渲染。更多内容...
| 头文件： | #include <QVulkanWindow> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake： | QT += gui |
| 继承自： | QWindow |
公共类型
(since 6.7) | EnabledFeatures2Modifier |
| EnabledFeaturesModifier | |
| enum | Flag { PersistentResources } |
| flags | Flags |
| QueueCreateInfoModifier |
公共函数
| QVulkanWindow(QWindow *parent = nullptr) | |
| virtual | ~QVulkanWindow() |
| QList<VkPhysicalDeviceProperties> | availablePhysicalDevices() |
| QMatrix4x4 | clipCorrectionMatrix() |
| VkFormat | colorFormat() const |
| int | concurrentFrameCount() const |
| virtual QVulkanWindowRenderer * | createRenderer() |
| 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 |
| QVulkanWindow::Flags | flags() const |
| void | frameReady() |
| QImage | grab() |
| 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 QByteArrayList &extensions) |
(since 6.7) void | setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier) |
(since 6.7) void | setEnabledFeaturesModifier(QVulkanWindow::EnabledFeatures2Modifier modifier) |
| void | setFlags(QVulkanWindow::Flags flags) |
| void | setPhysicalDeviceIndex(int idx) |
| void | setPreferredColorFormats(const QList<VkFormat> &formats) |
| void | setQueueCreateInfoModifier(const QVulkanWindow::QueueCreateInfoModifier &modifier) |
| void | setSampleCount(int sampleCount) |
| QVulkanInfoVector<QVulkanExtension> | supportedDeviceExtensions() |
| QList<int> | supportedSampleCounts() |
| bool | supportsGrab() const |
| VkImage | swapChainImage(int idx) const |
| int | swapChainImageCount() const |
| QSize | swapChainImageSize() const |
| VkImageView | swapChainImageView(int idx) const |
信号
| void | frameGrabbed(const QImage &image) |
静态公共成员
| const int | MAX_CONCURRENT_FRAME_COUNT |
详细说明
QVulkanWindow 是一个支持 Vulkan 的QWindow ，它管理着一个 Vulkan 设备、一个图形队列、一个命令池和缓冲区、一个深度-模板图像以及一个双缓冲 FIFO 交换链，同时确保在以下事件和特殊情况下行为正确：如窗口调整大小、设备队列不同时支持图形和呈现、 设备丢失等场景，以及读取渲染内容等附加功能时，都能确保行为正确。从概念上讲，它是Vulkan世界中QOpenGLWindow 的对应类。
注意：QVulkanWindow 并不总能完全替代实现完全自定义的 `QWindow ` 子类，因为在高级用例中，它未必足够。
QVulkanWindow 可通过QWidget::createWindowContainer() 嵌入到基于QWidget 的用户界面中。不过，这种方法存在一些限制。请务必先研究documentation 。
一个使用 QVulkanWindow 的典型应用程序可能如下所示：
classVulkanRenderer :publicQVulkanWindowRenderer
{
public:
VulkanRenderer(QVulkanWindow*w): m_window(w),m_devFuncs(nullptr) { }
voidinitResources() override
{
m_devFuncs= m_window->vulkanInstance()->deviceFunctions(m_window->device());
// ..
}
voidinitSwapChainResources() override {/* ... */}
voidreleaseSwapChainResources() override {/* ... */}
voidreleaseResources() override {/* ... */}
voidstartNextFrame() override
{
VkCommandBuffer cmdBuf= m_window->currentCommandBuffer();
// ...
m_devFuncs->vkCmdBeginRenderPass(commandBuffer,renderPassBegin,contents);
// ...
m_window->frameReady();
}
private:
QVulkanWindow*m_window;
QVulkanDeviceFunctions*m_devFuncs;
};
classVulkanWindow :publicQVulkanWindow
{
public:
QVulkanWindowRenderer*createRenderer() override {
return newVulkanRenderer(this);
}
};
intmain(intargc, char *argv[])
{
QGuiApplication app(argc,argv);
QVulkanInstance inst;
// 若可用，启用标准验证层
inst.setLayers({"VK_LAYER_KHRONOS_validation"});
if(!inst.create())
qFatal("Failed to create Vulkan instance: %d", inst.errorCode());
VulkanWindow w;
w.setVulkanInstance(&inst);
w.showMaximized();
returnapp.exec();
}如示例所示，QVulkanWindow 的主要使用模式包括：
- QVulkanInstance 通过QWindow::setVulkanInstance() 进行关联。随后，可在任何线程的任何位置通过QWindow::vulkanInstance() 获取该窗口。
- 与QVulkanInstance 类似，设备扩展可在实际初始化之前通过supportedDeviceExtensions()进行查询。启用扩展的请求需通过setDeviceExtensions()完成。此类调用必须在窗口可见之前进行，即在调用show()或类似函数之前。不支持的扩展请求将被优雅地忽略。
- 渲染器在QVulkanWindowRenderer 的子类中实现，其实例由createRenderer()工厂函数创建。
- 核心 Vulkan 命令通过QVulkanFunctions 对象提供，可通过调用QVulkanInstance::functions() 获取该对象。在通过调用QVulkanInstance::deviceFunctions() 创建 VkDevice 后，即可使用设备级函数。
- 下一帧的绘制调用在QVulkanWindowRenderer::startNextFrame() 中构建。实现应将命令添加到currentCommandBuffer() 返回的命令缓冲区中。该函数返回并不表示命令已准备好提交，而是需要显式调用frameReady()。这允许异步生成命令，甚至可以在多个线程上进行。 简单的实现只需在QVulkanWindowRenderer::startNextFrame()结束时调用frameReady()即可。
- 基本 Vulkan 资源（物理设备、图形队列、命令池、窗口的主命令缓冲区、图像格式等）通过轻量级的获取函数在 QVulkanWindow 上公开。其中部分资源仅为方便起见，应用程序始终可以自由地通过 Vulkan API 直接查询、创建和管理其他资源。
- 渲染器与窗口本身一样，运行在 GUI/主线程中。该线程随后会被限制为呈现速率，这类似于 OpenGL 将交换间隔设为 1 时的行为。不过，渲染器实现可以自由地以任何它认为合适的方式利用多个线程。 诸如 `vulkanInstance()`、`currentCommandBuffer()` 等访问器函数可在任何线程中调用。主命令缓冲区的提交、呈现操作的排队以及下一帧的构建，只有在 GUI/主线程上调用 `frameReady()` 之后才会开始。
- 当窗口显示出来时，内容会自动更新。可以通过调用QWindow::requestUpdate() 请求进一步的更新。若要持续渲染，请在调用frameReady() 之后调用requestUpdate()。
若需进行故障排除，请启用日志类别qt.vulkan 。严重错误会通过qWarning() 自动输出。
OpenGL 与 Vulkan 之间的坐标系差异
有两个值得注意的差异：首先，在 Vulkan 中，Y 轴在剪裁空间中指向屏幕下方，而 OpenGL 使用的 Y 轴则指向屏幕上方。其次，标准的 OpenGL 投影矩阵假设近平面和远平面的值为 -1 和 1，而 Vulkan 则更倾向于使用 0 和 1。
为了帮助应用程序从基于 OpenGL 的代码迁移，同时无需在顶点数据中翻转 Y 坐标，并允许在将 Vulkan 视口中的 minDepth 和 maxDepth 设置为 0 和 1 的情况下使用QMatrix4x4 中的函数（如QMatrix4x4::perspective()），QVulkanWindow 提供了一个校正矩阵，可通过调用clipCorrectionMatrix() 获取。
多采样
虽然默认处于禁用状态，但 QVulkanWindow 完全支持多采样抗锯齿。额外的颜色缓冲区以及将其解析到交换链的非多采样缓冲区中的操作均由系统自动管理。
要查询支持的采样数，请调用supportedSampleCounts()。当返回的集合包含 4、8、... 等值时，将其中一个值传递给setSampleCount() 即可请求多采样渲染。
注意：与 QSurfaceFormat::setSamples() 不同 ，支持的采样数列表会提前向应用程序公开，且在setSampleCount() 中不会自动降级到较低的采样数。如果请求的值不受支持，则会显示警告，并且不会使用多采样渲染。
读取图像
当supportsGrab() 返回 true 时，QVulkanWindow 可以从颜色缓冲区将数据读回至QImage 。grab() 是一项速度慢且效率低下的操作，因此应避免频繁使用。尽管如此，它仍然很有价值，因为它允许应用程序截取屏幕截图，或让工具和测试对 GPU 渲染的输出进行处理和验证。
sRGB 支持
虽然对于交换链图像格式，许多应用程序使用 QVulkanWindow 的默认行为即可满足需求，但setPreferredColorFormats() 允许请求预定义的格式。这在 sRGB 色彩空间中尤为有用。传递类似VK_FORMAT_B8G8R8A8_SRGB 的格式参数，将在可用时选择 sRGB 格式。
验证层
在应用程序开发过程中，启用 Vulkan 验证层往往极具价值。如上文示例代码所示，在调用QVulkanInstance::create() 之前，先对QVulkanInstance 调用QVulkanInstance::setLayers() 可启用验证功能——前提是系统中的 Vulkan 驱动程序堆栈包含必要的验证层。
注意：请 注意不同平台之间的差异。在桌面平台上，通常只需安装Vulkan SDK即可。但例如在 Android 平台上，则需要随应用程序一起部署额外的共享库，并且必须使用不同的验证层名称列表。有关更多信息，请参阅Android Vulkan 开发页面。
注意：QVulkanWindow 不暴露设备层，因为该功能自 Vulkan API 1.0.13 版本起已被废弃。
图层、设备特性和扩展
要启用实例层，请在创建 `QVulkanInstance` 之前调用 `QVulkanInstance::setLayers()`。要查询可用的实例层，请调用 `QVulkanInstance::supportedLayers()`。
要启用设备扩展，请在设置 QVulkanWindow 的早期阶段调用setDeviceExtensions()。要查询可用的设备扩展，请调用supportedDeviceExtensions()。
指定不支持的层或扩展时，系统会进行平滑处理：这不会导致实例或设备的创建失败，而是直接忽略该层或扩展的请求。
关于设备特性，QVulkanWindow 会启用所有由 vkGetPhysicalDeviceFeatures() 报告为受支持的 Vulkan 1.0 特性。作为此规则的例外，robustBufferAccess 永远不会被启用。若需启用该特性，请使用下文所述的回调机制。
这并不总是理想的，而且对于 Vulkan 1.1 及更高版本而言可能不够用。 因此，通过向setEnabledFeaturesModifier() 注册回调函数，也可以完全控制用于设备创建的 VkPhysicalDeviceFeatures。一旦设置，回调函数将被调用，从而允许其修改 VkPhysicalDeviceFeatures 或 VkPhysicalDeviceFeatures2。
安全注意事项
QVulkanWindow 使用的所有数据均应为可信内容。这包括传递给setDeviceExtensions() 的设备扩展名称、通过setEnabledFeaturesModifier() 和setQueueCreateInfoModifier() 注册的回调函数所写入的设备创建参数，以及由QVulkanWindowRenderer 实现生成的所有渲染内容和 Vulkan 命令参数。 Vulkan 实现本身是一个可信的、进程内的平台依赖项，详情请参阅QVulkanInstance 。
警告： 建议应用程序开发 人员在允许引入不属于应用程序且不受开发者控制的用户提供内容之前，仔细考虑其潜在影响。
另请参阅 QVulkanInstance 和QWindow 。
成员类型文档
[since 6.7] QVulkanWindow::EnabledFeatures2Modifier
一个在图形初始化期间被调用的函数，用于修改将写入 VkDeviceCreateInfo 的 VkPhysicalDeviceFeatures2。
默认情况下，QVulkanWindow 会启用物理设备报告为支持的所有Vulkan 1.0核心功能，但存在某些例外。特别是，robustBufferAccess 始终处于禁用状态，以避免意外的性能损失。
然而，在使用 Vulkan 1.1、1.2 或 1.3 的功能和扩展时，这并不总是足够的。因此引入了此回调机制。如果运行时仅涉及 Vulkan 1.0，请改用setEnabledFeaturesModifier()。
传递给回调函数的 VkPhysicalDeviceFeatures2 引用中，`sType ` 已设置，其余成员均被清零。具体是将成员设为 true，还是根据需要设置pNext 链，由该函数自行决定。
注意：在 设置pNext 链时 ，请确保被引用的对象具有足够长的生命周期，例如将其作为成员变量存储在QVulkanWindow 子类中。
此 typedef 于 Qt 6.7 中引入。
另请参阅 setEnabledFeaturesModifier()。
QVulkanWindow::EnabledFeaturesModifier
一个在图形初始化期间被调用的函数，用于修改创建 Vulkan 设备对象时传入的 VkPhysicalDeviceFeatures。
默认情况下，QVulkanWindow 会启用物理设备报告为支持的所有 Vulkan 1.0 核心功能，但存在某些例外。特别是，robustBufferAccess 始终处于禁用状态，以避免出现意外的性能损失。
在调用该函数时，传入的 VkPhysicalDeviceFeatures 引用中的所有成员值均被清零。该函数可根据需要自行修改这些成员值。
注意：若要 控制 Vulkan 1.1、1.2 或 1.3 的功能，请改用EnabledFeatures2Modifier 。
另请参阅 setEnabledFeaturesModifier()。
enum QVulkanWindow::Flag
flags QVulkanWindow::Flags
此枚举描述了可传递给setFlags()的标志。
| 常量 | 值 | 描述 |
|---|---|---|
QVulkanWindow::PersistentResources | 0x01 | 确保当窗口变为不可见时，不会释放任何图形资源。默认行为是释放所有资源，并在窗口再次可见时重新初始化。 |
Flags 类型是QFlags<Flag> 的 typedef。它存储 Flag 值的按“或”运算组合。
QVulkanWindow::QueueCreateInfoModifier
一个在图形初始化期间被调用的函数，用于添加需要创建的额外队列。
若渲染器除默认图形队列外还需其他队列（例如传输队列），请设置此函数。可通过提供的队列族属性来选择额外队列的索引。随后，渲染器可在 initResources() 中请求实际的队列。
注意：在 请求额外图形队列时， Qt 自身始终会请求一个图形队列。您需要在 queueCreateInfo 中查找相应的条目并对其进行操作，以获取该额外队列。
另请参阅 ` setQueueCreateInfoModifier()`。
成员函数文档
[explicit] QVulkanWindow::QVulkanWindow(QWindow *parent = nullptr)
使用给定的parent 创建一个新的QVulkanWindow。
将表面类型设置为QSurface::VulkanSurface 。
[virtual noexcept] QVulkanWindow::~QVulkanWindow()
析构函数。
QList<VkPhysicalDeviceProperties> QVulkanWindow::availablePhysicalDevices()
返回系统中受支持的物理设备的属性列表。
注意： 在将窗口显示出来之前即可调用此 函数。
QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()
返回一个QMatrix4x4 ，可用于校正OpenGL和Vulkan之间的坐标系差异。
通过对投影矩阵进行此矩阵的预乘，应用程序可以继续假设 Y 轴指向上方，并将视口中的 minDepth 和 maxDepth 分别设置为 0 和 1，而无需对顶点 Z 位置进行任何进一步的校正。 此时，只要渲染状态与 OpenGL 的剔除和前表面设置相匹配，即可直接使用来自 OpenGL 应用程序的几何体。
VkFormat QVulkanWindow::colorFormat() const
返回交换链所使用的颜色缓冲区格式。
注意： 仅在调用QVulkanWindowRenderer::initResources() 之后至QVulkanWindowRenderer::releaseResources() 之前，调用 此函数才有效。
另请参阅 setPreferredColorFormats()。
int QVulkanWindow::concurrentFrameCount() const
返回可能同时处于活动状态的帧数。
注意：该 值在QVulkanWindow 的整个生命周期内保持恒定。
class Renderer {
void startNextFrame();
// ...
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
QVulkanWindow *m_window = nullptr;
};
void Renderer::startNextFrame()
{
const int count = m_window->concurrentFrameCount();
// for (int i = 0; i < count; ++i)
// m_uniformBufInfo[i] = ...
// ...
}另请参阅 currentFrame()。
[virtual] QVulkanWindowRenderer *QVulkanWindow::createRenderer()
返回一个新的QVulkanWindowRenderer 实例。
该虚拟函数在窗口的生命周期内被调用一次，具体是在窗口首次显示之后某个时刻。
默认实现返回 null，因此除了清除缓冲区外，不会执行任何渲染操作。
窗口将拥有返回的渲染器对象。
VkCommandBuffer QVulkanWindow::currentCommandBuffer() const
返回当前交换链帧的活动命令缓冲区。QVulkanWindowRenderer::startNextFrame() 的实现应将命令添加到此命令缓冲区中。
注意：此 函数仅可在 startNextFrame() 内部调用，且在异步命令生成的情况下，必须在调用frameReady() 之前调用。
int QVulkanWindow::currentFrame() const
返回当前帧索引，其取值范围为 [0,concurrentFrameCount() - 1]。
渲染器实现必须确保统一数据和其他动态资源存在多份副本，以防止第 N 帧修改仍处于活动状态的第 N - 1、N - 2、...、N -concurrentFrameCount() + 1 帧所使用的数据。
为避免依赖动态数组大小，应用程序可在声明数组时使用 `MAX_CONCURRENT_FRAME_COUNT `。该值保证始终不小于 `concurrentFrameCount()` 返回的值。此类数组随后可通过该函数返回的值进行索引。
class Renderer {
void startNextFrame();
// ...
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
QVulkanWindow *m_window = nullptr;
};
void Renderer::startNextFrame()
{
VkDescriptorBufferInfo &uniformBufInfo(m_uniformBufInfo[m_window->currentFrame()]);
// ...
}注意：此 函数仅可在 startNextFrame() 内部调用，且在异步命令生成的情况下，必须在调用frameReady() 之前完成。
另请参阅 concurrentFrameCount()。
VkFramebuffer QVulkanWindow::currentFramebuffer() const
使用默认渲染通道，返回当前交换链图像的 VkFramebuffer。
当未使用多采样时，该帧缓冲区有两个附件（颜色、深度-模板）；当sampleCountFlagBits()大于VK_SAMPLE_COUNT_1_BIT 时，则有三个附件（颜色解析、深度-模板、多采样颜色）。渲染器必须考虑到这一点，例如在提供清除值时。
注意： 如果应用程序 提供自己的渲染通道，而不是使用defaultRenderPass()返回的渲染通道，则无需使用此帧缓冲区。
注意：此 函数仅可在 startNextFrame() 内部调用，且在异步命令生成的情况下，必须在调用frameReady() 之前完成。
另请参阅 defaultRenderPass()。
int QVulkanWindow::currentSwapChainImageIndex() const
返回当前交换链图像在 [0,swapChainImageCount() - 1] 范围内的索引。
注意：此 函数仅可在 startNextFrame() 内部调用，且在异步命令生成的情况下，必须在调用frameReady() 之前完成。
VkRenderPass QVulkanWindow::defaultRenderPass() const
返回一个包含一个子渲染通道的典型渲染通道。
注意：应用程序 无需使用此渲染通道。但若不使用，则需确保当前的交换链和深度-模板图像能够通过应用程序自定义的渲染通道或其他方式，从VK_IMAGE_LAYOUT_UNDEFINED 过渡到VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 和VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL 。
注意： 在此渲染通道中，未启用模板 读写功能。
注意： 仅在从调用QVulkanWindowRenderer::initResources() 到QVulkanWindowRenderer::releaseResources() 的期间内，调用 此函数才有效。
另请参阅 currentFramebuffer()。
VkFormat QVulkanWindow::depthStencilFormat() const
返回深度-模板缓冲区所使用的格式。
注意： 仅在从调用QVulkanWindowRenderer::initResources()到QVulkanWindowRenderer::releaseResources()的期间内，调用 此函数才有效。
VkImage QVulkanWindow::depthStencilImage() const
返回深度-模板图像。
注意： 仅在从调用QVulkanWindowRenderer::initSwapChainResources()开始到QVulkanWindowRenderer::releaseSwapChainResources()结束的期间内，调用 此函数才有效。
VkImageView QVulkanWindow::depthStencilImageView() const
返回深度-模板图像视图。
注意： 仅在从调用QVulkanWindowRenderer::initSwapChainResources()开始到QVulkanWindowRenderer::releaseSwapChainResources()结束的期间内，调用 此函数才是有效的。
VkDevice QVulkanWindow::device() const
返回当前活动的逻辑设备。
注意： 仅在从调用QVulkanWindowRenderer::initResources()开始到QVulkanWindowRenderer::releaseResources()结束期间，调用 此函数才是有效的。
uint32_t QVulkanWindow::deviceLocalMemoryIndex() const
返回一个适用于通用用途的设备本地内存类型索引。
注意： 仅在从调用QVulkanWindowRenderer::initResources()开始到QVulkanWindowRenderer::releaseResources()结束的期间内，调用 此函数才有效。
注意： 不能保证该内存类型始终适用。正确的、跨实现的解决方案——尤其是对于设备本地图像——是在检查vkGetImageMemoryRequirements 返回的掩码后，手动选择内存类型。
QVulkanWindow::Flags QVulkanWindow::flags() const
返回请求的标志。
另请参阅 setFlags()。
[signal] void QVulkanWindow::frameGrabbed(const QImage &image)
当image 就绪时，会发出此信号。
void QVulkanWindow::frameReady()
对于每次调用QVulkanWindowRenderer::startNextFrame()实现，都必须精确地调用此函数一次。在调用此函数时，通过currentCommandBuffer()暴露的主命令缓冲区中必须已添加所有必要的渲染命令，因为此函数将触发提交这些命令并将当前命令加入队列。
注意：此 函数必须仅从 GUI/主线程调用，因为该线程既是调用QVulkanWindowRenderer 函数的位置，也是QVulkanWindow 实例所在的位置。
另请参阅 QVulkanWindowRenderer::startNextFrame()。
QImage QVulkanWindow::grab()
构建并渲染下一帧（但不显示），然后对图像内容执行阻塞式读回操作。
如果渲染器的startNextFrame()实现直接调用了frameReady()，则返回该图像。否则，返回一个不完整的图像，该图像具有正确的尺寸但尚未包含内容。在后一种情况下，内容将通过frameGrabbed()信号传递。
返回的 `QImage ` 始终采用 `QImage::Format_RGBA8888` 格式。如果 `colorFormat()` 为 `VK_FORMAT_B8G8R8A8_UNORM`，则红蓝通道会自动交换，因为该格式通常被用作交换链颜色缓冲区的默认选择。对于任何其他颜色缓冲区格式，本函数均不会进行任何转换。
注意： 当帧处理正在进行时（即应用程序尚未调用frameReady() 回调），不应调用此 函数。
注意： 由于额外的阻塞式回读操作，此 函数可能消耗较多资源。
注意：该 函数目前要求交换链支持作为传输源（VK_IMAGE_USAGE_TRANSFER_SRC_BIT ），否则将失败。
VkCommandPool QVulkanWindow::graphicsCommandPool() const
返回当前活动的图形命令池。
注意： 仅在调用QVulkanWindowRenderer::initResources()之后至QVulkanWindowRenderer::releaseResources()之前，调用 此函数才有效。
VkQueue QVulkanWindow::graphicsQueue() const
返回当前活动的图形队列。
注意： 仅在从调用QVulkanWindowRenderer::initResources()开始到QVulkanWindowRenderer::releaseResources()结束期间，调用 此函数才有效。
uint32_t QVulkanWindow::graphicsQueueFamilyIndex() const
返回活动图形队列的家族索引。
注意： 仅在从调用 `QVulkanWindowRenderer::initResources()` 开始到 `QVulkanWindowRenderer::releaseResources()` 结束期间，调用 此函数才有效。`QVulkanWindowRenderer::updateQueueCreateInfo()` 的实现也可以调用此函数。
uint32_t QVulkanWindow::hostVisibleMemoryIndex() const
返回一个适用于通用用途的主机可见内存类型索引。
返回的内存类型既对主机可见，又保持一致性。此外，如果可能的话，它还会被缓存。
注意： 仅在从调用QVulkanWindowRenderer::initResources()开始到QVulkanWindowRenderer::releaseResources()结束期间，调用 此函数才有效。
bool QVulkanWindow::isValid() const
如果该窗口已成功初始化所有 Vulkan 资源（包括交换链），则返回 true。
注意：初始化操作 发生在窗口变为可见后的第一个 expose 事件上。
VkImage QVulkanWindow::msaaColorImage(int idx) const
返回指定的多采样彩色图像；如果未使用多采样，则返回VK_NULL_HANDLE 。
idx 必须在 [0,swapChainImageCount() - 1] 范围内。
注意： 仅在调用QVulkanWindowRenderer::initSwapChainResources() 之后至QVulkanWindowRenderer::releaseSwapChainResources() 之前，调用 此函数才有效。
VkImageView QVulkanWindow::msaaColorImageView(int idx) const
返回指定的多采样彩色图像视图；如果未使用多采样，则返回VK_NULL_HANDLE 。
idx 必须在 [0,swapChainImageCount() - 1] 范围内。
注意： 仅在从调用QVulkanWindowRenderer::initSwapChainResources() 开始到QVulkanWindowRenderer::releaseSwapChainResources() 结束的期间内，调用 此函数才有效。
VkPhysicalDevice QVulkanWindow::physicalDevice() const
返回当前活动的物理设备。
注意： 仅在从调用QVulkanWindowRenderer::preInitResources()开始到QVulkanWindowRenderer::releaseResources()结束期间，调用 此函数才有效。
const VkPhysicalDeviceProperties *QVulkanWindow::physicalDeviceProperties() const
返回指向当前活动物理设备属性的指针。
注意： 仅在调用QVulkanWindowRenderer::preInitResources()至QVulkanWindowRenderer::releaseResources()期间，调用 此函数才有效。
VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits() const
返回当前采样计数，其类型为VkSampleCountFlagBits 。
当目标为默认渲染目标时，必须将VkPipelineMultisampleStateCreateInfo 的rasterizationSamples 字段设置为该值。
另请参阅 setSampleCount() 和supportedSampleCounts()。
void QVulkanWindow::setDeviceExtensions(const QByteArrayList &extensions)
设置要启用的设备extensions 列表。
不支持的扩展将被忽略。
swapchain 扩展将始终自动添加，无需将其包含在此列表中。
注意： 必须在窗口可见之前或最迟在QVulkanWindowRenderer::preInitResources() 函数中调用此函数 ，若在此之后调用则无效。
[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier)
设置已启用设备功能的修改函数modifier 。
注意：若要 控制 Vulkan 1.1、1.2 或 1.3 功能，请改用接受EnabledFeatures2Modifier 作为参数的重载函数。
注意： modifier 会被传递给回调函数，此时其所有成员均被设置为 false。具体如何修改这些成员由该函数自行决定。
该函数在 Qt 6.7 中引入。
另请参阅 EnabledFeaturesModifier 。
[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(QVulkanWindow::EnabledFeatures2Modifier modifier)
设置已启用设备功能的修改函数modifier 。
这是一个重载函数。
该函数在 Qt 6.7 中引入。
另请参阅 EnabledFeatures2Modifier 。
void QVulkanWindow::setFlags(QVulkanWindow::Flags flags)
根据提供的flags 配置行为。
注意： 必须在窗口可见之前或在QVulkanWindowRenderer::preInitResources()中尽早调用此函数 ，若在此之后调用则无效。
另请参阅 flags()。
void QVulkanWindow::setPhysicalDeviceIndex(int idx)
请求使用索引为idx 的物理设备。该索引对应于availablePhysicalDevices() 返回的列表。
默认情况下使用第一个物理设备。
注意： 必须在窗口显示之前或在QVulkanWindowRenderer::preInitResources()中尽早调用此 函数，若在此之后调用则无效。
void QVulkanWindow::setPreferredColorFormats(const QList<VkFormat> &formats)
设置交换链的首选formats 。
默认情况下未设置应用程序首选格式。此时将使用画面的首选格式；若画面未指定首选格式，则使用VK_FORMAT_B8G8R8A8_UNORM 。
formats 中的列表是按顺序排列的。如果第一个格式不被支持，则考虑第二个格式，依此类推。当列表中的所有格式均不被支持时，其行为与默认情况相同。
若要在初始化后查询实际格式，请调用colorFormat()。
注意：此 函数必须在窗口显示之前或最迟在QVulkanWindowRenderer::preInitResources() 中调用，若在此之后调用则无效。
注意： 若需要，可通过重写 QVulkanWindowRenderer::preInitResources()来动态检查支持的格式列表。此时可通过QVulkanInstance::surfaceForWindow()获取表面，同时仍可安全地调用此函数以影响初始化的后续阶段。
另请参阅 colorFormat()。
void QVulkanWindow::setQueueCreateInfoModifier(const QVulkanWindow::QueueCreateInfoModifier &modifier)
设置队列创建信息修改函数modifier 。
另请参阅 QueueCreateInfoModifier 。
void QVulkanWindow::setSampleCount(int sampleCount)
请求使用给定的sampleCount 进行多采样抗锯齿。有效值为1、2、4、8……直至物理设备支持的最大值。
当采样数大于 1 时，QVulkanWindow 将创建一个多采样颜色缓冲区，而不是简单地将渲染结果写入交换链的图像中。多采样缓冲区中的渲染结果将在每帧结束时解析到非多采样缓冲区中。
要查看支持的采样数列表，请调用supportedSampleCounts()。
在设置渲染管线时，请调用sampleCountFlagBits() 以VkSampleCountFlagBits 值的形式查询当前的采样数。
注意： 必须在窗口显示之前或在最迟在QVulkanWindowRenderer::preInitResources()中调用此 函数，若在此之后调用则无效。
另请参阅 supportedSampleCounts() 和sampleCountFlagBits()。
QVulkanInfoVector<QVulkanExtension> QVulkanWindow::supportedDeviceExtensions()
返回由setPhysicalDeviceIndex() 选定的物理设备所创建的逻辑设备所支持的扩展列表。
注意： 在使窗口可见之前即可调用此 函数。
QList<int> QVulkanWindow::supportedSampleCounts()
返回在使用setPhysicalDeviceIndex()选定的物理设备时所支持的采样计数集合，以排序列表的形式呈现。
默认情况下，QVulkanWindow 使用的采样数为 1。通过调用setSampleCount() 并传入与本函数返回集合中不同的值（2、4、8 等），可以请求多采样抗锯齿。
注意： 可在使窗口可见之前调用此 函数。
另请参阅 setSampleCount()。
bool QVulkanWindow::supportsGrab() const
如果该交换链支持作为转账来源，则返回 true，这意味着grab() 函数可用。
注意： 仅在调用QVulkanWindowRenderer::initSwapChainResources() 之后至QVulkanWindowRenderer::releaseSwapChainResources() 之前，调用 此函数才有效。
VkImage QVulkanWindow::swapChainImage(int idx) const
返回指定的交换链图像。
idx 必须位于 [0,swapChainImageCount() - 1] 范围内。
注意： 仅在从调用QVulkanWindowRenderer::initSwapChainResources() 开始到QVulkanWindowRenderer::releaseSwapChainResources() 结束期间，调用 此函数才有效。
int QVulkanWindow::swapChainImageCount() const
返回交换链中的图像数量。
注意： 在提供自定义渲染通道和帧缓冲区时，必须访问 此属性。帧缓冲区与当前交换链图像相关联，因此应用程序必须提供多个帧缓冲区。
注意： 仅在从调用 `QVulkanWindowRenderer::initSwapChainResources()` 开始到 `QVulkanWindowRenderer::releaseSwapChainResources()` 结束期间，调用 此函数才有效。
QSize QVulkanWindow::swapChainImageSize() const
返回交换链的图像尺寸。
这通常与窗口大小一致，但在vkGetPhysicalDeviceSurfaceCapabilitiesKHR 报告固定尺寸的情况下可能会有所不同。
此外，在某些平台上观察到，当启用高 DPI 缩放时，Vulkan 报告的表面尺寸会有所不同，这意味着QWindow 报告的size() 值乘以devicePixelRatio() 后的结果，与此处返回的值相比会少或多 1 像素，这可能是由于舍入误差造成的。 渲染代码应注意这一点，任何相关的渲染逻辑都必须基于此处返回的值，绝不能基于QWindow 报告的尺寸。无论从理论上讲哪种像素尺寸是正确的，Vulkan 渲染都必须始终仅依赖于 Vulkan API 报告的表面尺寸。 否则可能会发生验证错误，例如在设置视口时，因为从 Vulkan 的角度来看，应用程序提供的值可能会超出边界。
注意： 仅在从调用 `QVulkanWindowRenderer::initSwapChainResources()` 开始到 `QVulkanWindowRenderer::releaseSwapChainResources()` 结束的期间内，调用 此函数才是有效的。
VkImageView QVulkanWindow::swapChainImageView(int idx) const
返回指定的交换链图像视图。
idx 必须位于 [0,swapChainImageCount() - 1] 范围内。
注意： 仅在从调用QVulkanWindowRenderer::initSwapChainResources() 开始到QVulkanWindowRenderer::releaseSwapChainResources() 结束期间，调用 此函数才有效。
成员变量文档
const int QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT
该变量存储一个常量值，该值始终等于或大于concurrentFrameCount()的最大值。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
