Класс QVulkanInstance

Класс QVulkanInstance представляет собой собственный экземпляр Vulkan, обеспечивающий рендеринг Vulkan на QSurface. Подробнее...

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

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

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

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

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

Vulkan — это кроссплатформенный API явной графики и вычислений. Этот класс обеспечивает поддержку загрузки библиотеки Vulkan и создания instance кроссплатформенным способом. Для ознакомления с экземплярами Vulkan обратитесь к разделу 3.2 спецификации.

Инициализация

Аналогично QOpenGLContext, фактическое создание экземпляра Vulkan происходит только при вызове create(). Это позволяет использовать QVulkanInstance в качестве обычной переменной-члена, сохраняя при этом контроль над тем, когда выполнять инициализацию.

Запрос поддерживаемых слоев и расширений на уровне экземпляра возможен путем вызова supportedLayers() и supportedExtensions(). Это гарантирует загрузку библиотеки Vulkan и, следовательно, может быть безопасно вызвано до create().

Экземпляры хранят состояние Vulkan для каждого приложения, и создание объекта VkInstance инициализирует библиотеку Vulkan. На практике обычно будет один экземпляр, созданный на ранней стадии в main(). Объект затем остается активным до выхода из приложения.

Каждое основанное на Vulkan QWindow должно быть связано с QVulkanInstance путем вызова QWindow::setVulkanInstance(). Таким образом, типичный шаблон приложения выглядит следующим образом:

    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 автоматически включает минимальный набор расширений, необходимых ему в новом созданном экземпляре. На практике это означает семейство расширений VK_KHR_*_surface.

По умолчанию вывод отладки Vulkan, например сообщения от слоев проверки, направляется в qDebug(). Это можно отключить, передав флаг NoDebugOutputRedirect в setFlags() до вызова create().

Для включения дополнительных слоёв и расширений, предоставьте список с помощью setLayers() и setExtensions() перед вызовом create(). Если указанный слой или расширение не сообщается как доступный для экземпляра, запрос игнорируется. После успешного вызова create(), значения, возвращаемые функциями, такими как layers() и extensions(), отражают фактически включенные слои и расширения. При необходимости, например, для предотвращения запросов расширений, которые конфликтуют и, таким образом, приведут к ошибке создания экземпляра Vulkan, список фактически поддерживаемых слоёв и расширений можно проверить с помощью supportedLayers() и supportedExtensions() перед вызовом create().

Например, для включения стандартных слоёв валидации можно сделать следующее:

    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
    }

Или, в качестве альтернативы, для принятия решений перед попыткой создания экземпляра Vulkan:

    QVulkanInstance inst;

    if (inst.supportedLayers().contains("VK_LAYER_KHRONOS_validation")) {
        // ...
    }
    bool ok = inst.create();
    // ...

Использование существующего экземпляра

По умолчанию QVulkanInstance создаёт новый экземпляр Vulkan. При работе с внешними движками и рендерерами это иногда может быть нежелательно. Если уже имеется доступный VkInstance дескриптор, вызовите setVkInstance() перед вызовом create(). Таким образом, дополнительные экземпляры не будут созданы, и QVulkanInstance не будет владеть этим дескриптором.

Доступ к основным командам Vulkan

Чтобы получить доступ к VkInstance дескриптору, который обёртка QVulkanInstance, вызовите vkInstance(). Для разрешения функций Vulkan, вызовите getInstanceProcAddr(). Для основных команд Vulkan ручное разрешение не требуется, так как они предоставляются объектами QVulkanFunctions и QVulkanDeviceFunctions, доступными через functions() и deviceFunctions().

Получение нативного Vulkan-поверхности для окна

Две общие операции, специфичные для систем окон, - это получение поверхности (дескриптор VkSurfaceKHR) для окна и проверка, поддерживает ли заданная семейство очереди отображение на заданную поверхность. Для предотвращения WSI-специфических деталей в приложениях, это абстрагируется QVulkanInstance и базовыми слоями QPA.

Для создания Vulkan-поверхности для окна или извлечения существующей, вызовите surfaceForWindow(). Большинство платформ будут создавать поверхность только через VK_KHR_*_surface при первом вызове surfaceForWindow(), но могут быть платформоспецифические вариации внутреннего поведения. После создания последующие вызовы surfaceForWindow() просто возвращают тот же дескриптор. Это хорошо согласуется со структурой типичных подклассов QWindow, поддерживающих Vulkan.

Для проверки, может ли заданная семейство очереди в физическом устройстве использоваться для отображения на заданную поверхность, вызовите supportsPresent(). Это включает в себя как общие vkGetPhysicalDeviceSurfaceSupportKHR проверки, так и WSI-специфические vkGetPhysicalDevice*PresentationSupportKHR проверки.

Отладка

Помимо возврата false от create() или 0 от surfaceForWindow(), критические ошибки также будут выводиться в отладочный вывод с помощью qWarning(). Дополнительный логгирование можно запросить, включив отладочный вывод для категории логгирования qt.vulkan. Фактический код ошибки Vulkan при создании экземпляра можно получить, вызвав errorCode() после неудачного вызова create().

В некоторых особых случаях может потребоваться переопределить имя библиотеки Vulkan. Этого можно достичь, установив QT_VULKAN_LIB переменную окружения.

Пример

Ниже приведены основные принципы создания QWindow, совместимого с Vulkan:

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

}

Использование C++ связываний для Vulkan

Также возможно комбинировать Qt's Vulkan-возможности с C++ обёрткой Vulkan, например, Vulkan-Hpp. Предварительным условием является то, что C++ слой должен уметь принимать нативные дескрипторы (VkInstance, VkSurfaceKHR) в своих классах без принятия на себя владения (так как владение остаётся у QVulkanInstance и QWindow). Также следует учесть следующее:

• Некоторые обёртки требуют поддержки исключений. Qt не использует исключения. Чтобы включить обработку исключений для приложения, добавьте CONFIG += exceptions в файл .pro.
• Некоторые обёртки вызывают функции Vulkan напрямую, предполагая, что vulkan.h предоставляет прототипы и приложение подключается к библиотеке Vulkan, экспортирующей все необходимые символы. Qt может не подключаться напрямую к библиотеке Vulkan. Поэтому на некоторых платформах может потребоваться добавить LIBS += -lvulkan или аналогичное в файл .pro приложения.
• Заголовки классов QVulkan могут включать vulkan.h с VK_NO_PROTOTYPES включённым. Это может вызвать проблемы в заголовках C++ обёрток, которые полагаются на прототипы. Поэтому в коде приложения может потребоваться включить vulkan.hpp или аналогичное перед любым из заголовков QVulkan.

См. также QVulkanFunctions и QSurface::SurfaceType.

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

QVulkanInstance::DebugFilter

Тип для функций обратного вызова фильтрации отладки.

См. также installDebugOutputFilter() и removeDebugOutputFilter().

[since 5.10] перечисление QVulkanInstance::Flagфлаги QVulkanInstance::Flags

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

Это перечисление было введено или изменено в Qt 5.10.

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

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

QVulkanInstance::QVulkanInstance()

Конструирует новый экземпляр.

QVulkanInstance::~QVulkanInstance()

Деструктор.

QVersionNumber QVulkanInstance::apiVersion() const

Возвращает запрошенную версию API Vulkan, с которой приложение ожидает работать, или нулевую версию, если setApiVersion() не вызывалась до create().

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

bool QVulkanInstance::create()

Инициализирует библиотеку Vulkan и создаёт новый или использует существующий экземпляр Vulkan.

Возвращает true при успехе, false при ошибке или если Vulkan не поддерживается.

При успехе указатель на этот QVulkanInstance доступен через статическую функцию current().

Экземпляр Vulkan и библиотека доступны до тех пор, пока существует этот QVulkanInstance или пока не вызывается destroy().

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 во время выполнения не поддерживает их, вызов любой такой недоступной функции приведёт к неопределённому поведению. Для надлежащей поддержки версий Vulkan выше 1.0 может потребоваться установить соответствующую версию API экземпляра, вызвав setApiVersion() перед create(). Кроме того, приложения должны проверять версию физического устройства apiVersion в VkPhysicalDeviceProperties.

См. также functions() и resetDeviceFunctions().

VkResult QVulkanInstance::errorCode() const

Возвращает код ошибки Vulkan после неудачной create(), VK_SUCCESS в противном случае.

Значение обычно является результатом vkCreateInstance() (при создании нового экземпляра Vulkan, а не адаптации существующего), но также может быть VK_NOT_READY если плагин платформы не поддерживает Vulkan.

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 может потребоваться установить соответствующую версию API экземпляра, вызвав setApiVersion() перед create(). Для запроса версии реализации Vulkan на уровне экземпляра вызовите supportedApiVersion().

См. также deviceFunctions() и supportedApiVersion().

PFN_vkVoidFunction QVulkanInstance::getInstanceProcAddr(const char *name)

Разрешает функцию Vulkan с заданным именем name.

Для основных команд Vulkan предпочтительнее использовать функции-обёртки, доступные через functions() и deviceFunctions().

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

Устанавливает функцию-фильтр filter, которая вызывается для каждого сообщения отладки Vulkan. Когда обратный вызов возвращает true, сообщение останавливается (отфильтровывается) и не будет отображаться в отладочном выводе.

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

bool QVulkanInstance::isValid() const

Возвращает true, если create() выполнилась успешно и экземпляр корректен.

QByteArrayList QVulkanInstance::layers() const

Возвращает включённые слои экземпляра, если create() был вызван и выполнился успешно. В противном случае — запрошенные слои.

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

[since 5.15] void QVulkanInstance::presentAboutToBeQueued(QWindow *window)

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

Хотя на некоторых платформах она будет бесполезной, на других платформах она может выполнять синхронизацию, зависящую от системного окна. Например, на Wayland она добавит запрос wl_surface.frame, чтобы предотвратить блокировку драйвера для минимизированных окон.

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

void QVulkanInstance::presentQueued(QWindow *window)

Эта функция должна вызываться рендерером приложения после постановки операции представления в очередь для window.

Хотя на некоторых платформах она будет бесполезной, на других платформах она может выполнять синхронизацию, зависящую от системного окна. Например, на X11 она обновит _NET_WM_SYNC_REQUEST_COUNTER.

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

Удаляет функцию-фильтр filter, установленную ранее функцией installDebugOutputFilter().

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

void QVulkanInstance::resetDeviceFunctions(VkDevice device)

Деактивирует и уничтожает объект QVulkanDeviceFunctions для данного device.

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

Нет необходимости вызывать это перед уничтожением QVulkanInstance, так как очистка выполняется автоматически.

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

void QVulkanInstance::setApiVersion(const QVersionNumber &vulkanVersion)

Указывает самую высокую версию API Vulkan, которую приложение предназначено использовать.

По умолчанию vulkanVersion равна 0, что соответствует Vulkan 1.0.

Разработчикам приложений рекомендуется ознакомиться с apiVersion примечаниями в спецификации Vulkan.

См. также apiVersion() и supportedApiVersion().

void QVulkanInstance::setExtensions(const QByteArrayList &extensions)

Указывает список дополнительных расширений экземпляра extensions для включения. Безопасно указывать и неподдерживаемые расширения, так как они игнорируются при отсутствии поддержки во время выполнения. Расширения, относящиеся к поверхности, необходимые Qt, всегда будут добавляться автоматически, нет необходимости включать их в этот список.

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

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

Настраивает поведение create() на основе предоставленных flags.

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

void QVulkanInstance::setLayers(const QByteArrayList &layers)

Указывает список слоёв экземпляра layers для включения. Безопасно указывать и неподдерживаемые слои, так как они будут проигнорированы, если не поддерживаются во время выполнения.

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

void QVulkanInstance::setVkInstance(VkInstance existingVkInstance)

Заставляет QVulkanInstance принять существующую обработку VkInstance вместо создания новой.

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

QVersionNumber QVulkanInstance::supportedApiVersion() const

Возвращает версию функциональности уровня экземпляра, поддерживаемую реализацией Vulkan.

На практике это либо значение, возвращаемое vkEnumerateInstanceVersion, если эта функция доступна (с Vulkan 1.1 и новее), или 1.0.

Приложения, которые хотят разветвлять своё использование функций и API Vulkan в зависимости от версии Vulkan, доступной во время выполнения, могут использовать эту функцию для определения версии, которую следует передать в setApiVersion() перед вызовом create().

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

QVulkanInfoVector<QVulkanExtension> QVulkanInstance::supportedExtensions() const

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

QVulkanInfoVector<QVulkanLayer> QVulkanInstance::supportedLayers() const

Возвращает список поддерживаемых слоёв уровня экземпляра.

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

Возвращает true, если семейство очередей с queueFamilyIndex в physicalDevice поддерживает отображение на window.

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

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

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

Возвращает обработку поверхности Vulkan или 0 при ошибке.

VkInstance QVulkanInstance::vkInstance() const

Возвращает обработку VkInstance, которую оборачивает этот QVulkanInstance, или nullptr если create() ещё не был успешно вызван и никакой существующий экземпляр не был предоставлен через setVkInstance().

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