Класс QQuickRenderControl

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

Подробнее...

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

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

• 34 открытые функции, унаследованные от QObject

Сигналы

• 2 сигнала, унаследованные от QObject

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

• 10 статических открытых членов, унаследованных от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 1 открытая переменная, унаследованная от QObject
• 9 защищенных функций, унаследованных от QObject
• 2 защищенных переменных, унаследованных от QObject

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

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

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. После создания корневого объекта его необходимо связать с элементом содержимого 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.

[override virtual] QQuickRenderControl::~QQuickRenderControl()

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

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

QImage QQuickRenderControl::grab()

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

Примечание: Требует, чтобы контекст был текущим.

void QQuickRenderControl::initialize(QOpenGLContext *gl)

Инициализирует ресурсы графа сцены. Контекст gl должен быть текущим контекстом OpenGL или нулём, если он не имеет значения, поскольку используется бэкенд 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()

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

[signal] void QQuickRenderControl::renderRequested()

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

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

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

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

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

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

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

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

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

[signal] void QQuickRenderControl::sceneChanged()

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

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

bool QQuickRenderControl::sync()

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

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

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