QVulkanWindow Class

成员函数文档

[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

返回 swapchain 使用的颜色缓冲区格式。

另请参阅 setPreferredColorFormats()。

int QVulkanWindow::concurrentFrameCount() const

返回可能同时激活的帧数。

    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 的新实例。

该虚拟函数在窗口的生命周期内调用一次，即在窗口首次可见后的某个时刻。

默认实现返回空值，因此除了清除缓冲区外，不会执行任何渲染操作。

窗口拥有返回的呈现器对象的所有权。

VkCommandBuffer QVulkanWindow::currentCommandBuffer() const

返回当前交换链映像的活动命令缓冲区。QVulkanWindowRenderer::startNextFrame() 的实现应向该命令缓冲区添加命令。

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

另请参阅 concurrentFrameCount()。

VkFramebuffer QVulkanWindow::currentFramebuffer() const

使用默认渲染通道返回当前交换链图像的 VkFramebuffer。

当不使用多重采样时，帧缓冲有两个附件（颜色、深度模板）；当sampleCountFlagBits() 大于VK_SAMPLE_COUNT_1_BIT 时，帧缓冲有三个附件（颜色解析、深度模板、多重采样颜色）。渲染器必须考虑到这一点，例如在提供清晰值时。

另请参阅 defaultRenderPass()。

int QVulkanWindow::currentSwapChainImageIndex() const

返回当前交换链图像索引，范围为 [0，swapChainImageCount() - 1]。

VkRenderPass QVulkanWindow::defaultRenderPass() const

返回包含一个子通道的典型渲染通道。

另请参见 currentFramebuffer()。

VkFormat QVulkanWindow::depthStencilFormat() const

返回深度钢网缓冲区使用的格式。

VkImage QVulkanWindow::depthStencilImage() const

返回深度模版图像。

VkImageView QVulkanWindow::depthStencilImageView() const

返回深度钢网图像视图。

VkDevice QVulkanWindow::device() const

返回活动逻辑设备。

uint32_t QVulkanWindow::deviceLocalMemoryIndex() const

返回适合一般使用的设备本地内存类型索引。

QVulkanWindow::Flags QVulkanWindow::flags() const

返回请求的标志。

另请参见 setFlags()。

[signal] void QVulkanWindow::frameGrabbed(const QImage &image)

image 准备就绪时会发出该信号。

void QVulkanWindow::frameReady()

每次调用QVulkanWindowRenderer::startNextFrame() 实现时，都必须准确调用该函数一次。在调用该函数时，通过currentCommandBuffer() 公开的主命令缓冲区必须已添加了所有必要的渲染命令，因为该函数将触发命令提交和当前命令排队。

另请参阅 QVulkanWindowRenderer::startNextFrame() 。

QImage QVulkanWindow::grab()

构建并渲染下一帧图像，但不显示该帧，然后执行图像内容的阻塞回读。

如果渲染器的startNextFrame() 实现直接回调frameReady() ，则返回图像。否则，将返回一幅不完整的图像，图像大小正确，但尚未包含内容。在后一种情况下，内容将通过frameGrabbed() 信号传送。

返回的QImage 格式始终为QImage::Format_RGBA8888 。如果colorFormat() 为VK_FORMAT_B8G8R8A8_UNORM ，则会自动交换红色和蓝色通道，因为这种格式通常用作交换链颜色缓冲区的默认选择。对于任何其他颜色缓冲区格式，本函数都不会进行转换。

VkCommandPool QVulkanWindow::graphicsCommandPool() const

返回活动图形命令池。

VkQueue QVulkanWindow::graphicsQueue() const

返回活动图形队列。

uint32_t QVulkanWindow::graphicsQueueFamilyIndex() const

返回活动图形队列的族索引。

uint32_t QVulkanWindow::hostVisibleMemoryIndex() const

返回适合一般使用的主机可见内存类型索引。

返回的内存类型既是主机可见的，也是连贯的。此外，如果可能，它还将被缓存。

bool QVulkanWindow::isValid() const

如果该窗口已成功初始化所有 Vulkan 资源（包括交换链），则返回 true。

VkImage QVulkanWindow::msaaColorImage(int idx) const

返回指定的多采样彩色图像，如果不使用多采样，则返回VK_NULL_HANDLE 。

idx 必须在 [0, () - 1] 范围内。swapChainImageCount

VkImageView QVulkanWindow::msaaColorImageView(int idx) const

返回指定的多采样彩色图像视图，如果不使用多采样，则返回VK_NULL_HANDLE 。

idx 必须在 [0, () - 1] 范围内。swapChainImageCount

VkPhysicalDevice QVulkanWindow::physicalDevice() const

返回活动物理设备。

const VkPhysicalDeviceProperties *QVulkanWindow::physicalDeviceProperties() const

返回指向活动物理设备属性的指针。

VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits() const

以VkSampleCountFlagBits 的形式返回当前样本数。

在使用默认呈现目标时，必须将VkPipelineMultisampleStateCreateInfo 的rasterizationSamples 字段设置为该值。

另请参阅 setSampleCount() 和supportedSampleCounts()。

void QVulkanWindow::setDeviceExtensions(const QByteArrayList &extensions)

设置要启用的设备extensions 列表。

不支持的扩展将被忽略。

swapchain 扩展名会自动添加，无需将其列入此列表。

[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier)

设置启用的设备功能修改函数modifier 。

此函数在 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 配置行为。

另请参阅 flags()。

void QVulkanWindow::setPhysicalDeviceIndex(int idx)

请求使用索引为idx 的物理设备。索引与availablePhysicalDevices() 返回的列表相对应。

默认情况下使用第一个物理设备。

void QVulkanWindow::setPreferredColorFormats(const QList<VkFormat> &formats)

设置交换链的首选formats 。

默认情况下不设置应用程序首选格式。在这种情况下，将使用表面的首选格式，如果没有，则使用VK_FORMAT_B8G8R8A8_UNORM 。

formats 中的列表是有序的。如果不支持第一种格式，将考虑第二种格式，依此类推。如果不支持列表中的任何格式，则行为与默认情况相同。

要在初始化后查询实际格式，请调用colorFormat() 。

另请参阅 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 值查询活动采样计数。

另请参阅 supportedSampleCounts() 和sampleCountFlagBits()。

QVulkanInfoVector<QVulkanExtension> QVulkanWindow::supportedDeviceExtensions()

返回从setPhysicalDeviceIndex() 所选物理设备创建的逻辑设备所支持的扩展名列表。

QList<int> QVulkanWindow::supportedSampleCounts()

以排序列表形式返回使用setPhysicalDeviceIndex() 所选物理设备时支持的采样计数集。

默认情况下，QVulkanWindow 使用 1 的采样计数。调用setSampleCount() 时，可以使用与本函数返回值不同的值（2、4、8......）来请求多采样抗锯齿。

另请参阅 setSampleCount().

bool QVulkanWindow::supportsGrab() const

如果 swapchain 支持作为传输源使用，则返回 true，这意味着grab() 是有效的。

VkImage QVulkanWindow::swapChainImage(int idx) const

返回指定的交换链映像。

idx 必须在 [0, () - 1] 范围内。swapChainImageCount

int QVulkanWindow::swapChainImageCount() const

返回交换链中图像的数量。

QSize QVulkanWindow::swapChainImageSize() const

返回 swapchain 的图像大小。

这通常与窗口大小一致，但在vkGetPhysicalDeviceSurfaceCapabilitiesKHR 报告固定大小的情况下也可能不同。

此外，在某些平台上观察到，在激活高 DPI 缩放的情况下，Vulkan 报告的表面尺寸是不同的，这意味着QWindow 报告的size() 与devicePixelRatio() 相乘后的值与此处返回的值相比少或多 1 个像素，这可能是由于四舍五入的不同。渲染代码应注意这一点，任何相关的渲染逻辑都必须以此处返回的值为基础，而绝不能以QWindow 报告的尺寸为基础。无论理论上哪种像素尺寸是正确的，Vulkan 渲染都只能依赖 Vulkan API 报告的表面尺寸。否则可能会出现验证错误，例如在设置视口时，因为从 Vulkan 的角度来看，应用程序提供的值可能会超出边界。

VkImageView QVulkanWindow::swapChainImageView(int idx) const

返回指定的交换链图像视图。

idx 必须在 [0, () - 1] 范围内。swapChainImageCount