Класс QQuickRenderControl

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

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

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

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

Сигналы

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

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

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

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

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 9 защищенных функций, унаследованных от 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's contentItem().

Приложения обычно должны подключаться к 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 или 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()

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

[signal] void QQuickRenderControl::renderRequested()

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

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

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

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

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

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

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

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

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

[signal] void QQuickRenderControl::sceneChanged()

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

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

bool QQuickRenderControl::sync()

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

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

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