Класс QQuickRenderControl

Класс QQuickRenderControl предоставляет механизм для отрисовки сцены Qt Quick на целевом offscreen рендере полностью под управлением приложения. Подробнее...

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

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

Сигналы

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

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

QQuickWindow и QQuickView и их связанные внутренние циклы рендеринга выводят сцену Qt Quick на нативное окно. В некоторых случаях, например, при интеграции с сторонними OpenGL, Vulkan, Metal или Direct 3D рендерами, может быть полезно получить сцену в текстуре, которую затем можно использовать произвольным образом в внешнем рендеринге. Такой механизм также необходим при интеграции с VR-фреймворком. QQuickRenderControl делает это возможным с использованием аппаратного ускорения, в отличие от ограниченного по производительности альтернативного использования QQuickWindow::grabWindow()

При использовании QQuickRenderControl, QQuickWindow не обязательно отображать или даже создавать. Это означает, что не будет базового нативного окна для него. Вместо этого экземпляр QQuickWindow связывается с контролем рендеринга, используя перегрузку конструктора QQuickWindow, и объект текстуры или изображения, указанный с помощью QQuickWindow::setRenderTarget().

Управление графическими устройствами, контекстами, объектами изображения и текстур возлагается на приложение. Устройство или контекст, которые будут использоваться Qt Quick, должны быть созданы перед вызовом initialize(). Создание объекта текстуры может быть отложено, см. ниже. Qt 5.4 добавляет возможность для QOpenGLContext принять существующие нативные контексты. В сочетании с QQuickRenderControl это позволяет создать QOpenGLContext, который совместно использует существующий контекст внешнего рендеринга. Этот новый QOpenGLContext затем можно использовать для рендеринга сцены Qt Quick в текстуру, которая также доступна для контекста другого движка. Для Vulkan, Metal и Direct 3D нет предоставленных Qt обёрток для объектов устройств, поэтому существующие могут быть переданы напрямую через QQuickWindow::setGraphicsDevice().

Загрузка и создание QML компонентов происходит с использованием QQmlEngine. После создания корневого объекта его необходимо присоединить к contentItem() QQuickWindow.

Приложениям, как правило, необходимо подключиться к 4 важным сигналам:

• QQuickWindow::sceneGraphInitialized() Издается в какой-то момент после вызова QQuickRenderControl::initialize(). По этому сигналу приложение ожидает создать свой фреймбуфер и связать его с QQuickWindow.
• QQuickWindow::sceneGraphInvalidated() Когда ресурсы сцены освобождаются, объект фреймбуфера тоже может быть уничтожен.
• QQuickRenderControl::renderRequested() Указывает, что сцена должна быть отрисована с помощью вызова render(). После установки контекста в активное состояние, приложения ожидают вызвать render().
• QQuickRenderControl::sceneChanged() Указывает, что сцена изменилась, что означает, что перед рендерингом необходимо также выполнить полировку и синхронизацию.

Для отправки событий, например, событий мыши или клавиатуры, в сцену используйте QCoreApplication::sendEvent() с экземпляром QQuickWindow в качестве получателя.

Примечание: В целом QQuickRenderControl поддерживается во всех бекендах Qt Quick. Однако некоторые функции, в частности grab(), могут быть недоступны во всех случаях.

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

QQuickRenderControl::QQuickRenderControl(QObject *parent = nullptr)

Конструирует объект QQuickRenderControl с родительским объектом parent.

[signal] void QQuickRenderControl::renderRequested()

Этот сигнал излучается, когда графика сцены должна быть отрисована. Необязательно вызывать sync().

Примечание: Избегайте непосредственного запуска рендеринга при срабатывании этого сигнала. Вместо этого предпочтительнее отложить его, например, с помощью таймера. Это приведёт к лучшей производительности.

[signal] void QQuickRenderControl::sceneChanged()

Этот сигнал излучается, когда графика сцены обновлена, что означает, что необходимо вызвать polishItems() и sync(). Если sync() возвращает true, то необходимо вызвать render().

Примечание: Избегайте непосредственного запуска полировки, синхронизации и рендеринга при срабатывании этого сигнала. Вместо этого предпочтительнее отложить его, например, с помощью таймера. Это приведёт к лучшей производительности.

[override virtual] QQuickRenderControl::~QQuickRenderControl()

Уничтожает экземпляр. Освобождает все ресурсы сцены.

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

[since 6.0] void QQuickRenderControl::beginFrame()

Указывает начало графического кадра. Вызовы sync() или render() должны быть заключены в вызовы beginFrame() и endFrame().

В отличие от более раннего OpenGL-исключительно мира Qt 5, рендеринг с другими графическими API требует более чётко определённых моментов начала и окончания кадра. При ручном управлении циклом рендеринга с помощью QQuickRenderControl, теперь пользователю QQuickRenderControl необходимо указать эти моменты.

Типичный шаг обновления, включающий инициализацию рендеринга в существующую текстуру, может выглядеть следующим образом. Примерный фрагмент предполагает Direct3D 11, но те же концепции относятся и к другим графическим API.

if (!m_quickInitialized) {
    m_quickWindow->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(m_engine->device(), m_engine->context()));

    if (!m_renderControl->initialize())
        qWarning("Failed to initialize redirected Qt Quick rendering");

    m_quickWindow->setRenderTarget(QQuickRenderTarget::fromNativeTexture({ quint64(m_res.texture), 0 },
                                                                         QSize(QML_WIDTH, QML_HEIGHT),
                                                                         SAMPLE_COUNT));

    m_quickInitialized = true;
}

m_renderControl->polishItems();

m_renderControl->beginFrame();
m_renderControl->sync();
m_renderControl->render();
m_renderControl->endFrame(); // Qt Quick's rendering commands are submitted to the device context here

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

См. также endFrame(), initialize(), sync(), render(), QQuickGraphicsDevice и QQuickRenderTarget.

[since 6.0] void QQuickRenderControl::endFrame()

Указывает конец кадра графики. Вызовы sync() или render() должны быть заключены в вызовы beginFrame() и endFrame().

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

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

См. также beginFrame(), initialize(), sync(), render(), QQuickGraphicsDevice и QQuickRenderTarget.

[since 6.0] bool QQuickRenderControl::initialize()

Инициализирует ресурсы иерархии сцены. При использовании графического API, такого как Vulkan, Metal, OpenGL или Direct3D, для отрисовки Qt Quick, QQuickRenderControl настроит соответствующий движок рендеринга при вызове этой функции. Эта инфраструктура рендеринга существует до тех пор, пока существует QQuickRenderControl.

Чтобы контролировать графический API, используемый Qt Quick, вызовите QQuickWindow::setGraphicsApi() с одним из QSGRendererInterface:GraphicsApi констант. Это необходимо сделать до вызова этой функции.

Чтобы предотвратить создание иерархией сцены собственных объектов устройства и контекста, укажите соответствующее QQuickGraphicsDevice, обертывающее существующие графические объекты, вызвав QQuickWindow::setGraphicsDevice().

Чтобы настроить, какие расширения устройств включить (например, для Vulkan), вызовите QQuickWindow::setGraphicsConfiguration() перед этой функцией.

Примечание: При использовании Vulkan QQuickRenderControl не создаёт QVulkanInstance автоматически. Вместо этого приложение отвечает за создание подходящего QVulkanInstance и связывание его с QQuickWindow. Перед инициализацией QVulkanInstance настоятельно рекомендуется запросить список желаемых расширений Qt Quick, вызвав статическую функцию QQuickGraphicsConfiguration::preferredInstanceExtensions(), и передать полученный список в QVulkanInstance::setExtensions().

Возвращает true при успехе, false в противном случае.

Примечание: При использовании адаптации Qt Quick software этот вызов не требуется и не должен вызываться.

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

См. также QQuickRenderTarget, QQuickGraphicsDevice и QQuickGraphicsConfiguration::preferredInstanceExtensions().

void QQuickRenderControl::invalidate()

Останавливает отрисовку и освобождает ресурсы.

Это эквивалентно операциям очистки, которые происходят с реальным QQuickWindow, когда окно скрывается.

Эта функция вызывается из деструктора. Поэтому обычно нет необходимости вызывать её напрямую.

После вызова invalidate() можно повторно использовать экземпляр QQuickRenderControl, вызвав initialize() снова.

Примечание: Эта функция не учитывает QQuickWindow::persistentSceneGraph() или QQuickWindow::persistentGraphics(). Это означает, что ресурсы, специфичные для контекста, всегда освобождаются.

void QQuickRenderControl::polishItems()

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

void QQuickRenderControl::prepareThread(QThread *targetThread)

Подготавливает отрисовку сцены Qt Quick вне потока GUI.

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

void QQuickRenderControl::render()

Отрисовывает иерархию сцены с использованием текущего контекста.

[virtual] QWindow *QQuickRenderControl::renderWindow(QPoint *offset)

Переопределяется в подклассах для возвращения реального окна, в которое происходит отрисовка этим контролем.

Если offset не равен null, он устанавливается в смещение контроля внутри окна.

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

[static] QWindow *QQuickRenderControl::renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr)

Возвращает реальное окно, в которое отрисовывается win, если таковое имеется.

Если offset не равен null, он устанавливается в смещение рендеринга внутри его окна.

[since 6.0] int QQuickRenderControl::samples() const

Возвращает текущее значение количества сэмплов. 1 или 0 означает отсутствие многократной выборки.

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

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

[since 6.0] void QQuickRenderControl::setSamples(int sampleCount)

Устанавливает количество сэмплов, используемых для многократной выборки. При значении sampleCount 0 или 1, многократная выборка отключена.

Примечание: Эта функция всегда используется в сочетании с целевым рендерингом многократной выборки, что означает, что sampleCount должен соответствовать количеству сэмплов, переданному QQuickRenderTarget::fromNativeTexture(), которое, в свою очередь, должно соответствовать количеству сэмплов исходной текстуры.

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

См. также samples(), initialize() и QQuickRenderTarget.

bool QQuickRenderControl::sync()

Эта функция используется для синхронизации сцены QML с графической иерархией сцены.

Если используется отдельный поток рендеринга, поток GUI должен блокироваться на время этого вызова.

Возвращает true, если синхронизация изменила иерархию сцены.

[since 6.0] QQuickWindow *QQuickRenderControl::window() const

Возвращает QQuickWindow, с которым связан этот QQuickRenderControl.

Примечание: QQuickRenderControl связывается с QQuickWindow при создании QQuickWindow. Значение, возвращаемое этой функцией, равно null до этого момента.

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