Класс QVulkanWindow

Класс QVulkanWindow — это удобный подкласс QWindow для выполнения рендеринга Vulkan. Подробнее...

• Список всех членов, включая унаследованные члены

Открытые типы

Открытые функции

Сигналы

Статические открытые члены

Подробное описание

QVulkanWindow — это поддерживающее Vulkan окно QWindow, которое управляет устройством Vulkan, графической очередью, пулом команд и буфером, изображением глубины/трафарета и буферизованным FIFO-обменником, одновременно обеспечивая корректное поведение при таких событиях, как изменение размера, особых ситуациях, таких как отсутствие очереди устройств, поддерживающей как графику, так и представление, сценариях потери устройства, и дополнительной функциональности, такой как считывание обратно отрендеренного контента. Концептуально это аналог QOpenGLWindow в мире Vulkan.

QVulkanWindow можно встроить в пользовательские интерфейсы на основе QWidget с помощью QWidget::createWindowContainer(). Однако этот подход имеет ряд ограничений. Сначала обязательно ознакомьтесь с документацией.

Типичное приложение, использующее QVulkanWindow, может выглядеть следующим образом:

class VulkanRenderer : public QVulkanWindowRenderer
{
public:
    VulkanRenderer(QVulkanWindow *w) : m_window(w), m_devFuncs(nullptr) { }

    void initResources() override
    {
        m_devFuncs = m_window->vulkanInstance()->deviceFunctions(m_window->device());
        // ..
    }
    void initSwapChainResources() override { /* ... */ }
    void releaseSwapChainResources() override { /* ... */ }
    void releaseResources() override { /* ... */ }

    void startNextFrame() override
    {
        VkCommandBuffer cmdBuf = m_window->currentCommandBuffer();
        // ...
        m_devFuncs->vkCmdBeginRenderPass(commandBuffer, renderPassBegin, contents);
        // ...
        m_window->frameReady();
    }

private:
    QVulkanWindow *m_window;
    QVulkanDeviceFunctions *m_devFuncs;
};

class VulkanWindow : public QVulkanWindow
{
public:
    QVulkanWindowRenderer *createRenderer() override {
        return new VulkanRenderer(this);
    }
};

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QVulkanInstance inst;
    // enable the standard validation layers, when available
    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();

    return app.exec();
}

Как видно из примера, основные шаблоны использования QVulkanWindow следующие:

• Экземпляр QVulkanInstance ассоциируется с помощью QWindow::setVulkanInstance(). Затем он может быть получен с помощью QWindow::vulkanInstance() из любой точки приложения на любом потоке.
• Аналогично QVulkanInstance, расширения устройства можно запросить с помощью supportedDeviceExtensions() перед фактической инициализацией. Запрос на включение расширения выполняется с помощью setDeviceExtensions(). Такие вызовы должны быть выполнены до того, как окно станет видимым, то есть перед вызовом show() или аналогичных функций. Запросы на расширения, которые не поддерживаются, игнорируются.
• Рендерер реализован в подклассе QVulkanWindowRenderer, экземпляр которого создается в фабричной функции createRenderer().
• Основные команды Vulkan предоставляются объектом QVulkanFunctions, который можно получить, вызвав QVulkanInstance::functions(). Функции уровня устройства доступны после создания VkDevice вызовом QVulkanInstance::deviceFunctions().
• Создание команд для следующего кадра происходит в QVulkanWindowRenderer::startNextFrame(). Реализация должна добавить команды в буфер команд, возвращаемый из currentCommandBuffer(). Возврат из функции не означает, что команды готовы к отправке. Требуется явный вызов frameReady(). Это позволяет асинхронно генерировать команды, возможно, на нескольких потоках. Простые реализации просто вызывают frameReady() в конце QVulkanWindowRenderer::startNextFrame().
• Основные ресурсы Vulkan (физическое устройство, графический очередь, пул команд, основной буфер команд окна, форматы изображений и т. д.) доступны в QVulkanWindow через лёгкие функции-геттеры. Некоторые из них предназначены для удобства, и приложения всегда могут запросить, создать и управлять дополнительными ресурсами напрямую через API Vulkan.
• Рендерер работает в главном потоке GUI, как и само окно. Этот поток затем ограничивается скоростью отображения, подобно тому, как ведёт себя OpenGL с интервалом переключения 1. Однако реализация рендерера может использовать несколько потоков любым удобным способом. Доступ к данным, например, vulkanInstance(), currentCommandBuffer() и т. д., может быть выполнен с любого потока. Отправка основного буфера команд, вставка для отображения и построение следующего кадра не начинаются до тех пор, пока не будет вызван frameReady() в главном потоке GUI.
• Когда окно становится видимым, содержимое обновляется автоматически. Дальнейшие обновления можно запросить, вызвав QWindow::requestUpdate(). Для непрерывного отображения вызовите requestUpdate() после frameReady().

Для отладки включите категорию регистрации qt.vulkan. Критические ошибки выводятся с помощью qWarning() автоматически.

Отличия систем координат OpenGL и Vulkan

Следует учитывать две заметные разницы: во-первых, в Vulkan Y-координата направлена вниз в пространстве обрезки, а в OpenGL используется направленная вверх Y-ось. Во-вторых, стандартная матрица проекции OpenGL предполагает значения ближней и дальней плоскостей от -1 до 1, а Vulkan предпочитает 0 и 1.

Для помощи приложениям в миграции из кода на основе OpenGL без необходимости переворота Y-координат в данных вершин и для возможности использования функций QMatrix4x4, таких как QMatrix4x4::perspective(), при одновременном сохранении значений minDepth и maxDepth для видового порта Vulkan равными 0 и 1, QVulkanWindow предоставляет матрицу коррекции, которую можно получить, вызвав clipCorrectionMatrix().

Многократная выборка

Хотя по умолчанию отключена, многократная выборка для сглаживания является полностью поддерживаемой QVulkanWindow. Дополнительные буферы цвета и преобразование в буферы без многократной выборки в цепочке обмена управляются автоматически.

Для запроса поддерживаемых значений количества выборок вызовите supportedSampleCounts(). Если возвращаемый набор содержит 4, 8, ..., передача одного из этих значений в setSampleCount() запрашивает рендеринг с многократной выборкой.

Чтение изображений обратно

Если supportsGrab() возвращает true, QVulkanWindow может выполнить чтение из буфера цвета в QImage. grab() — медленная и неэффективная операция, поэтому следует избегать частых её вызовов. Тем не менее, она полезна, так как позволяет приложениям делать снимки экрана или инструментам и тестам обрабатывать и проверять вывод рендеринга графического процессора.

Поддержка sRGB

Хотя многие приложения будут работать нормально со значениями по умолчанию QVulkanWindow, что касается форматов изображений цепочки обмена, setPreferredColorFormats() позволяет запросить предварительно определённый формат. Это особенно полезно при работе в цветовом пространстве sRGB. Передача формата, например, VK_FORMAT_B8G8R8A8_SRGB приводит к выбору формата sRGB, если он доступен.

Слои валидации

Во время разработки приложения очень полезно иметь включённые слои валидации Vulkan. Как показано в примере кода выше, вызов QVulkanInstance::setLayers() на QVulkanInstance до QVulkanInstance::create() включает валидацию, при условии, что стеки драйверов Vulkan на системе содержат необходимые слои.

См. также QVulkanInstance и QWindow.

Документация по типам членов

перечисление QVulkanWindow::Flagфлаги QVulkanWindow::Flags

Это перечисление описывает флаги, которые можно передать в setFlags().

Тип Flags — это синоним для QFlags<Flag>. Он хранит комбинацию значений Flag, полученную с помощью операции побитового ИЛИ.

QVulkanWindow::QueueCreateInfoModifier

Функция, вызываемая во время графической инициализации для добавления дополнительных очередей, которые должны быть созданы.

Устанавливается, если рендереру необходимы дополнительные очереди помимо стандартной графической очереди (например, очередь переноса). Предоставленные свойства семейства очередей можно использовать для выбора индексов дополнительных очередей. Затем рендерер может запросить фактическую очередь в initResources().

См. также setQueueCreateInfoModifier().

Документация по функциям-членам

QVulkanWindow::QVulkanWindow(QWindow *parent = nullptr)

Конструктор нового QVulkanWindow с заданным parent.

Тип поверхности устанавливается в QSurface::VulkanSurface.

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

Этот сигнал излучается, когда image готова.

[virtual] QVulkanWindow::~QVulkanWindow()

Деструктор.

QList<VkPhysicalDeviceProperties> QVulkanWindow::availablePhysicalDevices()

Возвращает список свойств поддерживаемых физических устройств в системе.

QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()

Возвращает QMatrix4x4, которую можно использовать для исправления различий в системах координат OpenGL и Vulkan.

При умножении матрицы проекции на эту матрицу приложения могут продолжать считать, что ось Y направлена вверх, и могут установить minDepth и maxDepth в представлении соответственно в 0 и 1 без необходимости дальнейших коррекций позиций Z вершин. Геометрия из приложений OpenGL может затем использоваться как есть, предполагая состояние растеризации, соответствующее настройкам обрезки и передней грани OpenGL.

VkFormat QVulkanWindow::colorFormat() const

Возвращает формат буфера цвета, используемый обменной цепочкой.

См. также 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.

Этот виртуальный метод вызывается один раз в течение жизненного цикла окна, в какой-то момент после его первого отображения.

Реализация по умолчанию возвращает null, поэтому отрисовка не будет выполняться, кроме очистки буферов.

Окно принимает во владение возвращённый объект рендерера.

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

void QVulkanWindow::frameReady()

Этот метод должен вызываться ровно один раз в ответ на каждый вызов реализации QVulkanWindowRenderer::startNextFrame(). В момент этого вызова основной буфер команд, доступный через currentCommandBuffer(), должен содержать все необходимые команды рендеринга, так как эта функция запустит отправку команд и поставку команды отображения.

См. также QVulkanWindowRenderer::startNextFrame().

QImage QVulkanWindow::grab()

Создаёт и рендерит следующий кадр без его отображения, а затем выполняет блокирующее чтение содержимого изображения.

Возвращает изображение, если реализация startNextFrame() рендерера вызывает frameReady() напрямую. В противном случае возвращает неполное изображение, имеющее правильный размер, но не содержащее содержимого пока. Содержимое будет передано через сигнал frameGrabbed() в последнем случае.

VkCommandPool QVulkanWindow::graphicsCommandPool() const

Возвращает активный буфер команд графики.

VkQueue QVulkanWindow::graphicsQueue() const

Возвращает активную очередь графики.

[since 5.15] uint32_t QVulkanWindow::graphicsQueueFamilyIndex() const

Возвращает индекс семейства активной очереди графики.

Эта функция была добавлена в Qt 5.15.

uint32_t QVulkanWindow::hostVisibleMemoryIndex() const

Возвращает индекс типа памяти, доступной для хоста, подходящей для общего использования.

Возвращаемый тип памяти будет как доступной для хоста, так и согласованной. Кроме того, он также будет кэширован, если это возможно.

bool QVulkanWindow::isValid() const

Возвращает true, если данное окно успешно инициализировало все ресурсы Vulkan, включая буфер обмена.

VkImage QVulkanWindow::msaaColorImage(int idx) const

Возвращает указанный цветной многообразный объект, или VK_NULL_HANDLE если многообразное отображение не используется.

idx должен находиться в диапазоне [0, swapChainImageCount() - 1].

VkImageView QVulkanWindow::msaaColorImageView(int idx) const

Возвращает указанный цветной многообразный объект представления, или VK_NULL_HANDLE если многообразное отображение не используется.

idx должен находиться в диапазоне [0, swapChainImageCount() - 1].

VkPhysicalDevice QVulkanWindow::physicalDevice() const

Возвращает активное физическое устройство.

const VkPhysicalDeviceProperties *QVulkanWindow::physicalDeviceProperties() const

Возвращает указатель на свойства активного физического устройства.

VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits() const

Возвращает текущее значение сэмплирования как VkSampleCountFlagBits значение.

При целевом рендеринге по умолчанию, поле rasterizationSamples в VkPipelineMultisampleStateCreateInfo должно быть установлено на это значение.

См. также setSampleCount() и supportedSampleCounts().

void QVulkanWindow::setDeviceExtensions(const QByteArrayList &extensions)

Устанавливает список расширений устройства extensions, которые будут включены.

Неподдерживаемые расширения игнорируются.

Расширение буфера обмена всегда добавляется автоматически, нет необходимости включать его в этот список.

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

[since 5.15] void QVulkanWindow::setQueueCreateInfoModifier(const QVulkanWindow::QueueCreateInfoModifier &modifier)

Устанавливает функцию изменения информации о создании очереди modifier.

Эта функция была добавлена в Qt 5.15.

См. также 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

Возвращает true, если обменный буфер поддерживает использование в качестве источника передачи, что означает, что grab() функционален.

VkImage QVulkanWindow::swapChainImage(int idx) const

Возвращает указанный обменный буфер изображения.

idx должен находиться в диапазоне [0, swapChainImageCount() - 1].

int QVulkanWindow::swapChainImageCount() const

Возвращает количество изображений в обменном буфере.

QSize QVulkanWindow::swapChainImageSize() const

Возвращает размер изображения обменного буфера.

Обычно это совпадает с размером окна, но может отличаться в случае, если vkGetPhysicalDeviceSurfaceCapabilitiesKHR сообщает о фиксированном размере.

VkImageView QVulkanWindow::swapChainImageView(int idx) const

Возвращает указанный обменный буфер представления изображения.

idx должен находиться в диапазоне [0, swapChainImageCount() - 1].