Класс QQuickRenderControl

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

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