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