Класс QQuickRenderControl

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

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

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

Сигналы

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

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

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

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

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

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

void QQuickRenderControl::renderRequested()

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

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

void QQuickRenderControl::sceneChanged()

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

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

QQuickRenderControl::~QQuickRenderControl()

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

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

void QQuickRenderControl::beginFrame()

Указывает начало графического кадра. Вызовы sync() или render() должны быть заключены в вызовы beginFrame() и endFrame().

В отличие от более раннего OpenGL-ориентированного мира Qt 5, отрисовка с другими графическими API требует более чётких точек начала и окончания кадра. При ручном управлении циклом отрисовки через QQuickRenderControl, теперь на пользователя QQuickRenderControl возлагается задача указания этих точек.

Типичный шаг обновления, включая инициализацию отрисовки в существующую текстуру, мог бы выглядеть следующим образом. Пример фрагмента кода предполагает Direct3D 11, но те же концепции относятся и к другим графическим API.

if (!m_quickInitialized) {
    m_quickWindow->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(m_engine->device(), m_engine->context()));

    if (!m_renderControl->initialize())
        qWarning("Failed to initialize redirected Qt Quick rendering");

    m_quickWindow->setRenderTarget(QQuickRenderTarget::fromNativeTexture({ quint64(m_res.texture), 0 },
                                                                         QSize(QML_WIDTH, QML_HEIGHT),
                                                                         SAMPLE_COUNT));

    m_quickInitialized = true;
}

m_renderControl->polishItems();

m_renderControl->beginFrame();
m_renderControl->sync();
m_renderControl->render();
m_renderControl->endFrame(); // Qt Quick's rendering commands are submitted to the device context here

Эта функция была добавлена в Qt 6.0.

См. также endFrame(), initialize(), sync(), render(), QQuickGraphicsDevice и QQuickRenderTarget.

[since 6.0] void QQuickRenderControl::endFrame()

Указывает конец графического кадра. Вызовы sync() или render() должны быть заключены в вызовы beginFrame() и endFrame().

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

Эта функция была добавлена в Qt 6.0.

См. также beginFrame(), initialize(), sync(), render(), QQuickGraphicsDevice и QQuickRenderTarget.

[since 6.0] bool QQuickRenderControl::initialize()

Инициализирует ресурсы графического дерева сцены. При использовании графического API, такого как Vulkan, Metal, OpenGL или Direct3D, для рендеринга Qt Quick, QQuickRenderControl настроит соответствующий движок рендеринга при вызове этой функции. Эта инфраструктура рендеринга существует до тех пор, пока существует QQuickRenderControl.

Для управления тем, какой графический API использует Qt Quick, вызовите QQuickWindow::setGraphicsApi() с одним из значений QSGRendererInterface:GraphicsApi. Это необходимо сделать перед вызовом этой функции.

Для предотвращения создания графическим деревом сцены собственных объектов устройства и контекста, укажите соответствующее QQuickGraphicsDevice, оборачивающее существующие графические объекты, вызвав QQuickWindow::setGraphicsDevice().

Для настройки включения расширений устройств (например, для Vulkan) вызовите QQuickWindow::setGraphicsConfiguration() перед этой функцией.

Примечание: При использовании Vulkan, QQuickRenderControl не создаёт QVulkanInstance автоматически. Вместо этого приложение отвечает за создание подходящего QVulkanInstance и связывание его с QQuickWindow.

Возвращает true при успехе, false в противном случае.

Примечание: Этот вызов не требуется и не должен вызываться при использовании software адаптации Qt Quick.

Эта функция была добавлена в Qt 6.0.

См. также QQuickRenderTarget и QQuickGraphicsDevice.

void QQuickRenderControl::invalidate()

Останавливает рендеринг и освобождает ресурсы.

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

Эта функция вызывается из деструктора. Поэтому, как правило, нет необходимости вызывать её напрямую.

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

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

void QQuickRenderControl::polishItems()

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

void QQuickRenderControl::prepareThread(QThread *targetThread)

Подготавливает рендеринг сцены Qt Quick вне потока GUI.

targetThread указывает поток, в котором будет происходить синхронизация и рендеринг. Нет необходимости вызывать эту функцию в однопоточном сценарии.

void QQuickRenderControl::render()

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

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

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

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

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

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

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

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

[since 6.0] int QQuickRenderControl::samples() const

Возвращает текущее значение количества выборок. 1 или 0 означает отсутствие сглаживания.

Эта функция была добавлена в Qt 6.0.

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

[since 6.0] void QQuickRenderControl::setSamples(int sampleCount)

Устанавливает количество выборок для использования в сглаживании. Когда sampleCount равен 0 или 1, сглаживание отключено.

Примечание: Эта функция всегда используется в сочетании с целевым буфером многократной выборки, что означает, что sampleCount должен совпадать с количеством выборок, переданным в QQuickRenderTarget::fromNativeTexture(), которое в свою очередь должно совпадать с количеством выборок нативного текстурного объекта.

Эта функция была добавлена в Qt 6.0.

См. также samples(), initialize() и QQuickRenderTarget.

bool QQuickRenderControl::sync()

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

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

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

[since 6.0] QQuickWindow *QQuickRenderControl::window() const

Возвращает QQuickWindow, с которым связан этот QQuickRenderControl.

Примечание: QQuickRenderControl связывается с QQuickWindow при создании QQuickWindow. Значение, возвращаемое этой функцией, равно null до этого момента.

Эта функция была добавлена в Qt 6.0.