Класс QQuickRenderControl

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

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

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

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

Сигналы

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

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

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

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

Управление контекстом и объектом буфера кадра зависит от приложения. Контекст, который будет использоваться Qt Quick, должен быть создан до вызова initialize(). Создание объекта буфера кадра может быть отложено, см. ниже. Qt 5.4 добавляет возможность для QOpenGLContext принять существующие нативные контексты. В сочетании с QQuickRenderControl это позволяет создать QOpenGLContext, который совместно использует существующий контекст внешнего движка отрисовки. Этот новый QOpenGLContext затем можно использовать для отрисовки сцены Qt Quick в текстуру, которая также доступна контексту другого движка.

Загрузка и создание компонентов 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().

QImage QQuickRenderControl::grab()

Захватывает содержимое сцены и возвращает его как изображение.

Примечание: Требуется текущий контекст.

void QQuickRenderControl::initialize(QOpenGLContext *gl)

Инициализирует ресурсы графа сцены. Контекст gl должен быть текущим контекстом OpenGL или null, если он не имеет значения, потому что используется бэкенд Qt Quick, отличный от OpenGL.

Примечание: Qt Quick не берет на себя владение контекстом. Приложение должно уничтожить его после вызова invalidate() или после уничтожения экземпляра QQuickRenderControl.

void QQuickRenderControl::invalidate()

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

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

Эта функция вызывается из деструктора. Поэтому обычно нет необходимости вызывать её напрямую. Однако обратите внимание на то, что это требует контекста, переданного в initialize(), чтобы он был текущим в момент уничтожения экземпляра QQuickRenderControl.

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

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

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, он устанавливается в значение смещения отрисовки внутри его окна.

bool QQuickRenderControl::sync()

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

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

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