Класс QQuickRenderControl

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

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

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

Сигналы

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

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

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

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

Управление графическими устройствами, контекстами, объектами изображений и текстур осуществляется приложением. Устройство или контекст, которые будут использоваться 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 в качестве получателя.

Для событий клавиатуры также может потребоваться вручную установить фокус на желаемый элемент. На практике это включает вызов forceActiveFocus() на желаемом элементе, например, корневом элементе сцены, после его связывания со сценой (объектом QQuickWindow).

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

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

В отличие от более раннего мира Qt 5, основанного только на OpenGL, отрисовка с другими графическими 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() перед этой функцией.

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

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

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

void QQuickRenderControl::invalidate()

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

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

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

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

void QQuickRenderControl::polishItems()

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

void QQuickRenderControl::prepareThread(QThread *targetThread)

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

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

void QQuickRenderControl::render()

Отрисовывает графическое дерево сцены, используя текущий контекст.

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

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

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

[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, многократная выборка отключена.

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

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

bool QQuickRenderControl::sync()

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

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

Возвращает true, если синхронизация изменила графическое дерево сцены.

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

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

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