Класс QVulkanInstance

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

Этот класс был представлен в Qt 5.10.

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

Типы public

Функции public

Статические public члены

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

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

Примечание: Платформенная поддержка экземпляров Vulkan и окон с поверхностями, совместимыми с Vulkan, предоставляется различными плагинами платформы. Однако не все из них поддерживают Vulkan. При запуске на такой платформе create() завершится неудачно и всегда вернет false.

Примечание: Поддержка Vulkan может быть автоматически отключена для данного сборки Qt из-за отсутствия необходимых заголовков Vulkan во время сборки. В этом случае, если вывод configure указывает на отключение поддержки Vulkan, классы QVulkan* будут недоступны.

Примечание: Некоторые функции изменили свою сигнатуру между различными пересмотрами заголовков Vulkan. При сборке Qt и наличии только заголовков со старыми, конфликтующими сигнатурами поддержка Vulkan будет отключена. Рекомендуется использовать заголовки Vulkan 1.0.39 или более поздней версии.

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

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

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

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

Каждое окно QWindow на основе Vulkan должно быть связано с 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(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation");

    bool ok = inst.create();
    if (!ok)
        ... // Vulkan not available
    if (!inst.layers().contains("VK_LAYER_LUNARG_standard_validation"))
        ... // validation layer not available

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

    QVulkanInstance inst;

    if (inst.supportedLayers().contains("VK_LAYER_LUNARG_standard_validation"))
        ...

    bool ok = inst.create();
    ...

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

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

Примечание: Компоненту, создающему внешний экземпляр, необходимо убедиться, что на нём включены необходимые расширения. Это: VK_KHR_surface, платформно-специфичное расширение VK_KHR_*_surface, и VK_EXT_debug_report в случае, если требуется перенаправление вывода отладки QVulkanInstance.

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

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

Примечание: QVulkanFunctions и QVulkanDeviceFunctions генерируются из спецификаций XML API Vulkan при построении библиотек Qt. Поэтому для них нет документации. Они содержат функции Vulkan 1.0 с теми же подписями, что и описаны в документации API Vulkan.

Получение нативного 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.

Пример

Ниже приведён базовый очерк создания Vulkan-совместимого окна QWindow:

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

    }

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

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

Возможно также объединение инструментов Qt для 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.

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

typedef QVulkanInstance::DebugFilter

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

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

enum QVulkanInstance::Flagflags QVulkanInstance::Flags

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

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

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

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

QVulkanInstance::QVulkanInstance()

Создаёт новый экземпляр.

Примечание: Никакой инициализации Vulkan не выполняется в конструкторе.

QVulkanInstance::~QVulkanInstance()

Деструктор.

Примечание: current() вернёт nullptr после уничтожения экземпляра.

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() ещё раз.

int 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 ядра, за исключением функций уровня устройства, и гарантированно работоспособен на всех платформах.

Примечание: Возвращаемый объект принадлежит и управляется QVulkanInstance. Не уничтожайте и не изменяйте его.

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

PFN_vkVoidFunction QVulkanInstance::getInstanceProcAddr(const char *name)

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

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

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

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

Примечание: Фильтрация эффективна только когда NoDebugOutputRedirect не установлен.

Примечание: Установка фильтров не имеет эффекта в противном случае.

Примечание: Этот метод может быть вызван до create().

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

bool QVulkanInstance::isValid() const

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

QByteArrayList QVulkanInstance::layers() const

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

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

void QVulkanInstance::presentQueued(QWindow *window)

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

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

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

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

Примечание: Эта функция может вызываться до create().

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

void QVulkanInstance::setApiVersion(const QVersionNumber &vulkanVersion)

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

По умолчанию vulkanVersion не указана, и проверка версии не выполняется во время создания экземпляра Vulkan.

Примечание: Эта функция может вызываться только до create() и не имеет эффекта, если вызвана после.

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

void QVulkanInstance::setExtensions(const QByteArrayList &extensions)

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

Примечание: Эта функция может вызываться только до create() и не имеет эффекта, если вызвана после.

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

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

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

Примечание: Эта функция может вызываться только до create() и не имеет эффекта, если вызвана после.

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

void QVulkanInstance::setLayers(const QByteArrayList &layers)

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

Примечание: Эта функция может вызываться только до create() и не имеет эффекта, если вызвана после.

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

QVulkanInfoVector<QVulkanExtension> QVulkanInstance::supportedExtensions()

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

Примечание: Эта функция может вызываться до create().

QVulkanInfoVector<QVulkanLayer> QVulkanInstance::supportedLayers()

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

Примечание: Эта функция может вызываться до create().

VkSurfaceKHR QVulkanInstance::surfaceForWindow(QWindow *window)

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

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

int QVulkanInstance::vkInstance() const

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