Класс QQuickWindow

Класс QQuickWindow предоставляет окно для отображения графической сцены QML. Подробнее...

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

Открытые типы

Свойства

• activeFocusItem : QQuickItem* const
• цвет : QColor
• contentItem : QQuickItem* const
• временныйРодитель : QWindow* const

Общедоступные функции

Реализованные общедоступные функции

Общедоступные слоты

Сигналы

Статические публичные члены

Реализованные защищенные функции

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

QQuickWindow предоставляет управление графической сценой, необходимой для взаимодействия с и отображения сцены QQuickItems.

QQuickWindow всегда имеет один невидимый корневой элемент. Чтобы добавить элементы в это окно, переместите элементы в родительский корневой элемент или в существующий элемент сцены.

Для удобного отображения сцены из файла QML, см. QQuickView.

Отображение

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

Сигнал sceneGraphInitialized() излучается в потоке отображения перед первым отображением сцены QML на экране. Если графическая сцена отображения была освобождена, сигнал будет снова излучен перед отображением следующего кадра. Видимое, отображаемое на экране QQuickWindow управляется внутренне render loop, из которых в графической сцене предоставляется несколько реализаций. Более подробную информацию об обработке отображения графической сцены см. в Qt Quick Scene Graph.

По умолчанию QQuickWindow использует ускоренный 3D графический API, такой как OpenGL или Vulkan. Подробный обзор графических бэкэндов сцены и поддерживаемых графических API см. в Scene Graph Adaptations.

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

Предупреждение: Поскольку многие сигналы, связанные с отображением, излучаются из потока отображения, соединения должны выполняться с использованием Qt::DirectConnection.

Интеграция с ускоренными 3D графическими API

Возможна прямая интеграция вызовов OpenGL, Vulkan, Metal или Direct3D 11 в QQuickWindow, если QQuickWindow и подлежащая графическая сцена отображаются с использованием одного и того же API. Для доступа к объектам нативного графического интерфейса, таким как идентификаторы устройства или контекста, используйте QSGRendererInterface. Экземпляр QSGRendererInterface можно запросить из QQuickWindow, вызвав rendererInterface(). Средства для этой интеграции — сигналы beforeRendering(), beforeRenderPassRecording(), afterRenderPassRecording() и связанные с ними. Они позволяют отображать подложки или наложения. В качестве альтернативы, QNativeInterface::QSGOpenGLTexture, QNativeInterface::QSGVulkanTexture и другие аналогичные классы позволяют обернуть существующий объект нативной текстуры или изображения в QSGTexture, который затем можно использовать с графической сценой.

Отображение без ускорения

Доступен также ограниченный, чисто программный путь отрисовки. С использованием software бэкенда ряд функций Qt Quick недоступны, элементы QML, которые полагаются на них, вообще не будут отрисованы. В то же время это позволяет QQuickWindow быть функциональным даже на системах, где вообще нет API 3D-графики. Дополнительные сведения см. в разделе Адаптация Qt Quick для программного обеспечения.

Перенаправленная отрисовка

QQuickWindow не обязательно поддерживается родным окном на экране. Отрисовка может быть перенаправлена на целевой пользовательский целевой объект отрисовки, например, на заданную родную текстуру. Это достигается в сочетании с классом QQuickRenderControl и функциями, такими как setRenderTarget(), setGraphicsDevice() и setGraphicsConfiguration().

В этом случае QQuickWindow представляет сцену и предоставляет инфраструктуру для отрисовки кадра. Он не будет поддерживаться циклом отрисовки и родным окном. Вместо этого в этом случае приложение управляет отрисовкой, эффективно заменяя циклы отрисовки. Это позволяет генерировать последовательности изображений, отрисовывать в текстуры для использования во внешних 3D-движках или отрисовывать содержимое Qt Quick в виртуальной реальности.

Управление ресурсами

QML будет пытаться кэшировать изображения и узлы графа сцены для повышения производительности, но в некоторых сценариях с ограниченным объемом оперативной памяти может потребоваться агрессивное освобождение этих ресурсов. Функция releaseResources() может использоваться для принудительного удаления определенных ресурсов, особенно ресурсов, которые кэшируются и могут быть повторно созданы при необходимости.

Кроме того, вызов releaseResources() может привести к освобождению всего графа сцены и связанных графических ресурсов. Сигнал sceneGraphInvalidated() будет выпущен, когда это произойдет. Это поведение контролируется функциями setPersistentGraphics() и setPersistentSceneGraph().

Примечание: Все классы с префиксом QSG должны использоваться исключительно в потоке отрисовки графа сцены. Дополнительную информацию см. в разделе Граф сцены и отрисовка.

Экспозиция и видимость

Когда экземпляр QQuickWindow намеренно скрывается с помощью hide() или setVisible(false), он перестанет отрисовываться, и его граф сцены и контекст графики могут также быть освобождены. Это зависит от настроек, настроенных с помощью setPersistentGraphics() и setPersistentSceneGraph(). Поведение в этом отношении идентично явному вызову функции releaseResources(). Окно может стать неэкспонированным, другими словами, неотображаемым, и другими способами. Это зависит от платформы и системы окон. Например, на Windows сворачивание окна заставляет его прекратить отрисовку. На macOS полное затемнение окна другими окнами сверху вызывает то же самое. В Linux/X11 поведение зависит от менеджера окон.

Контекст OpenGL и форматы поверхности

Хотя можно указать QSurfaceFormat для каждого QQuickWindow, вызвав член-функцию setFormat(), окна также могут быть созданы из QML с помощью элементов Window и ApplicationWindow. В этом случае в создании экземпляра окна не участвует код C++, но приложения все же могут захотеть установить определенные значения формата поверхности, например, запросить определенную версию или профиль OpenGL. Такие приложения могут вызвать статическую функцию QSurfaceFormat::setDefaultFormat() при запуске. Указанный формат будет использоваться для всех созданных впоследствии окон Quick.

Инстанс Vulkan

При использовании Vulkan QQuickWindow автоматически связывается с QVulkanInstance, который создается и управляется внутри графом сцены. Таким образом, большинство приложений не должны беспокоиться о наличии VkInstance, поскольку все происходит автоматически. В сложных случаях приложение может захотеть создать собственный QVulkanInstance для его конфигурации определенным образом. Это тоже возможно. Вызов setVulkanInstance() в QQuickWindow сразу после создания, прежде чем сделать его видимым, приводит к использованию предоставленного приложением QVulkanInstance (и базового VkInstance). При перенаправлении через QQuickRenderControl автоматически не предоставляется QVulkanInstance, а вместо этого ожидается, что приложение предоставит свой собственный и свяжет его с QQuickWindow.

Контексты и устройства графики

При инициализации графа сцены, что обычно происходит, когда окно становится видимым или, в случае перенаправленной отрисовки, инициализация выполняется через QQuickRenderControl, контексты или устройства, необходимые для отрисовки, создаются автоматически. Это включает контексты OpenGL, устройства и контексты устройств Direct3D, устройства Vulkan и Metal. Их также можно запросить кодом приложения после этого через QSGRendererInterface. При использовании basic цикла отрисовки, который выполняет всю отрисовку в потоке пользовательского интерфейса, одно и то же контекст или устройство используется со всеми видимыми QQuickWindow. threaded цикл отрисовки использует выделенный контекст или устройство для каждого потока отрисовки, а значит, и для каждого QQuickWindow. В некоторых графических API предоставляется определенная возможность настройки через setGraphicsConfiguration(). Это позволяет, например, указать список расширений Vulkan для включения на VkDevice. Кроме того, можно предоставить набор существующих контекстов или устройств для использования QQuickWindow вместо того, чтобы позволить ему создать свой собственный. Это достигается с помощью setGraphicsDevice().

См. также QQuickView, QQuickRenderControl, QQuickRenderTarget, QQuickGraphicsDevice, QQuickGraphicsConfiguration и QSGRendererInterface.

Документация по типам членов

перечисление QQuickWindow::CreateTextureOptionфлаги QQuickWindow::CreateTextureOptions

Перечисления CreateTextureOption используются для настройки обертывания текстуры.

Тип CreateTextureOptions является псевдонимом для QFlags<CreateTextureOption>. Он хранит комбинацию значений CreateTextureOption, объединенных операцией ИЛИ.

[since 5.4] перечисление QQuickWindow::RenderStage

Это перечисление было введено или изменено в Qt 5.4.

См. также Граф сцены и отрисовка.

[since 5.3] перечисление QQuickWindow::SceneGraphError

Это перечисление описывает ошибку в сигнале sceneGraphError().

Это перечисление было введено или изменено в Qt 5.3.

[since 5.10] перечисление QQuickWindow::TextRenderType

Этот перечисление описывает тип рендеринга по умолчанию для текстовых элементов в Qt Quick (Текст, Поле ввода текста и т. д.).

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

Это перечисление было введено или изменено в Qt 5.10.

Документация по членам-функциям

QQuickWindow::QQuickWindow(QWindow *parent = nullptr)

Создает окно для отображения QML-сцены с родительским окном parent.

[signal, since 5.3] void QQuickWindow::afterAnimating()

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

В отличие от других аналогичных сигналов, этот сигнал излучается в потоке GUI, а не в потоке рендеринга. Он может использоваться для синхронизации внешних систем анимации с QML-содержимым. В то же время это означает, что этот сигнал не подходит для запуска графических операций.

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

[signal, since 6.0] void QQuickWindow::afterFrameEnd()

Этот сигнал излучается, когда граф сцены отправил кадр. Он излучается после всех других связанных сигналов, таких как afterRendering(). Это последний сигнал, который излучается потоком рендеринга графа сцены при рендеринге кадра.

Примечание: В отличие от frameSwapped(), этот сигнал гарантированно излучается и когда вывод Qt Quick перенаправляется через QQuickRenderControl.

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если вашей функции-обработчику необходимо завершить выполнение перед продолжением, необходимо убедиться, что подключение является прямым (см. Qt::ConnectionType).

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

См. также beforeFrameBegin() и rendererInterface().

[signal, since 5.14] void QQuickWindow::afterRenderPassRecording()

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

Этот сигнал излучается раньше afterRendering(), и он гарантирует, что не только кадр, но и запись основного прохода рендеринга графа сцены все еще активны. Это позволяет вставлять команды, не создавая целого отдельного прохода рендеринга (который, как правило, очищает прикрепленные изображения). Родные графические объекты могут быть запрошены через QSGRendererInterface.

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

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если вашей функции-обработчику необходимо завершить выполнение перед продолжением, необходимо убедиться, что подключение является прямым (см. Qt::ConnectionType).

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

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

[signal] void QQuickWindow::afterRendering()

Сигнал излучается после того, как граф сцены добавил свои команды в буфер команд, который еще не отправлен в очередь графики. Если нужно, функция-обработчик, подключенная к этому сигналу, может запросить родные ресурсы, такие как буфер команд, прежде чем использовать QSGRendererInterface. Однако обратите внимание, что проход рендеринга (или проходы) уже записаны на этом этапе, и добавить больше команд внутри прохода графа сцены невозможно. Вместо этого используйте afterRenderPassRecording() для этого. В Qt 6 этот сигнал имеет ограниченное применение, в отличие от Qt 5. Скорее, обычно используется комбинация beforeRendering() и beforeRenderPassRecording() или beforeRendering() и afterRenderPassRecording() для достижения под- или наложения пользовательского рендеринга.

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

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если вашей функции-обработчику необходимо завершить выполнение перед продолжением, необходимо убедиться, что подключение является прямым (см. Qt::ConnectionType).

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

См. также rendererInterface(), Граф сцены - OpenGL под QML, Граф сцены - Metal под QML, Граф сцены - Vulkan под QML и Граф сцены - Direct3D 11 под QML.

[signal, since 5.3] void QQuickWindow::afterSynchronizing()

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

Этот сигнал может использоваться для подготовки, необходимой после вызовов QQuickItem::updatePaintNode(), в то время как поток GUI все еще заблокирован.

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

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если вашей функции-обработчику необходимо завершить выполнение перед продолжением, необходимо убедиться, что подключение является прямым (см. Qt::ConnectionType).

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

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

[signal, since 6.0] void QQuickWindow::beforeFrameBegin()

Этот сигнал излучается перед тем, как граф сцены начнёт подготовку кадра. Он предшествует сигналам, таким как beforeSynchronizing() или beforeRendering(). Это самый ранний сигнал, излучаемый потоком рендеринга графа сцены при подготовке нового кадра.

Этот сигнал актуален для графических фреймворков более низкого уровня, которым необходимо выполнить определённые операции, такие как очистка ресурсов, на стадии, когда Qt Quick ещё не инициировал запись нового кадра через API-интерфейсы подчинённого графического оборудования.

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если ваша функция-слот должна завершиться перед продолжением выполнения, вы должны убедиться, что подключение является прямым (см. Qt::ConnectionType).

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

См. также afterFrameEnd() и rendererInterface().

[signal, since 5.14] void QQuickWindow::beforeRenderPassRecording()

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

Этот сигнал излучается позже, чем beforeRendering(), и гарантирует, что активен не только кадр, но и запись основного прохода рендеринга графа сцены. Это позволяет вставлять команды без необходимости генерировать целую, отдельную последовательность рендеринга (которая обычно очищает прикреплённые изображения). К родным графическим объектам можно обратиться через QSGRendererInterface.

Примечание: Обновления ресурсов (загрузка, копирование) обычно не могут быть поставлены в очередь изнутри прохода рендеринга. Поэтому более сложный пользовательский рендеринг потребует подключения как к beforeRendering(), так и к этому сигналу.

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если ваша функция-слот должна завершиться перед продолжением выполнения, вы должны убедиться, что подключение является прямым (см. Qt::ConnectionType).

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

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

[signal] void QQuickWindow::beforeRendering()

Этот сигнал излучается после того, как подготовка кадра завершена, что означает наличие буфера команд в режиме записи, где это применимо. При необходимости функция-слот, подключенная к этому сигналу, может запросить родные ресурсы, такие как команда до QSGRendererInterface. Однако следует заметить, что запись основного прохода рендеринга ещё не начата на данном этапе, и добавить команды в этот проход нельзя. Начало прохода означает очистку буферов цвета, глубины и трафарета, поэтому недостижимо подложное рендерирование, просто подключившись к этому сигналу. Подключитесь к beforeRenderPassRecording(). Однако подключение к этому сигналу по-прежнему важно, если требуется запись копий команд, поскольку они не могут быть поставлены в очередь в проходе рендеринга.

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

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если ваша функция-слот должна завершиться перед продолжением выполнения, вы должны убедиться, что подключение является прямым (см. Qt::ConnectionType).

Предупреждение: При использовании OpenGL следует учитывать, что установка специфичных для OpenGL 3.x или 4.x состояний и оставление их включёнными или установленными в значения, отличные от значений по умолчанию, при возвращении из подключённого слота может повлиять на рендеринг графа сцены.

См. также rendererInterface(), Граф сцены - OpenGL под QML, Граф сцены - Metal под QML, Граф сцены - Vulkan под QML и Граф сцены - Direct3D 11 под QML.

[signal] void QQuickWindow::beforeSynchronizing()

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

Несмотря на то, что сигнал излучается из потока рендеринга графа сцены, поток GUI гарантированно заблокирован, как и в QQuickItem::updatePaintNode(). Поэтому безопасно обращаться к данным потока GUI в слоте или лямбда-выражении, подключённых с помощью Qt::DirectConnection.

Этот сигнал можно использовать для выполнения любой подготовки, необходимой перед вызовами QQuickItem::updatePaintNode().

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

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если ваша функция-слот должна завершиться перед продолжением выполнения, вы должны убедиться, что подключение является прямым (см. Qt::ConnectionType).

Предупреждение: При использовании OpenGL следует учитывать, что установка специфичных для OpenGL 3.x или 4.x состояний и оставление их включёнными или установленными в значения, отличные от значений по умолчанию, при возвращении из подключённого слота может повлиять на рендеринг графа сцены.

[signal, since 5.1] void QQuickWindow::closing(QQuickCloseEvent *close)

Этот сигнал излучается, когда окно получает событие close от системы окон.

В macOS Qt создаст элемент меню Quit если нет элемента меню с текстом "выйти" или "закрыть". Этот элемент меню вызывает сигнал QCoreApplication::quit, а не сигнал QQuickWindow::closing().

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

См. также QMenuBar в качестве глобальной панели меню.

[signal] void QQuickWindow::frameSwapped()

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

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

[slot] void QQuickWindow::releaseResources()

Эта функция пытается освободить избыточные ресурсы, в настоящее время удерживаемые QML-сценой.

Вызов этой функции запрашивает у графа сцены освободить кэшированные графические ресурсы, такие как объекты графических конвейеров или программы шейдеров.

Примечание: Освобождение кэшированных графических ресурсов не зависит от подсказки из setPersistentGraphics().

Кроме того, в зависимости от используемого цикла рендеринга, эта функция также может привести к освобождению графа сцены и всех графических ресурсов. Если это произойдёт, будет излучен сигнал sceneGraphInvalidated(), позволяющий пользователям очистить свои собственные графические ресурсы. Функции setPersistentGraphics() и setPersistentSceneGraph() можно использовать, чтобы предотвратить это, если обработка очистки невозможна в приложении, но с затратами на большее использование памяти.

См. также sceneGraphInvalidated(), setPersistentGraphics() и setPersistentSceneGraph().

[signal, since 5.3] void QQuickWindow::sceneGraphAboutToStop()

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

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

Предупреждение: Этот сигнал излучается из потока рендеринга графа сцены. Если ваша функция-слот должна завершиться перед продолжением выполнения, вы должны убедиться, что подключение является прямым (см. Qt::ConnectionType).

Предупреждение: Убедитесь, что обработчик сигнала sceneGraphAboutToStop() оставляет контекст графики в том же состоянии, в котором он был до входа в обработчик. Несоблюдение этого может привести к неправильному рендерингу сцены.

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

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

[signal, since 5.3] void QQuickWindow::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)

Этот сигнал излучается, когда во время инициализации графа сцены произошла ошибка error.

Приложения должны подключаться к этому сигналу, если они хотят обрабатывать ошибки, такие как сбои при создании контекста графики, собственным способом. Если к сигналу не подключён ни один слот, поведение будет другим: Quick выведет message или покажет сообщение об ошибке и завершит приложение.

Этот сигнал будет излучаться из потока GUI.

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

[signal] void QQuickWindow::sceneGraphInitialized()

Этот сигнал излучается, когда граф сцены был инициализирован.

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

[signal] void QQuickWindow::sceneGraphInvalidated()

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

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

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

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

[slot] void QQuickWindow::update()

Планирует отображение следующего кадра окна.

Вызов QQuickWindow::update() отличается от QQuickItem::update() тем, что всегда инициирует перерисовку, независимо от изменений в базовом дереве сцены.

[override virtual] QQuickWindow::~QQuickWindow()

Уничтожает окно.

[override virtual] QAccessibleInterface *QQuickWindow::accessibleRoot() const

Возвращает интерфейс доступности для этого окна или 0, если такой интерфейс создать невозможно.

[since 5.14] void QQuickWindow::beginExternalCommands()

При смешении команд графического API (OpenGL, Vulkan, Metal и т.д.) с рендерингом на основе дерева сцен, необходимо вызвать эту функцию перед записью команд в буфер команд, используемый деревом сцены для рендеринга основного прохода. Это предотвращает перезапись состояния.

На практике эта функция часто вызывается из слота, подключенного к сигналам beforeRenderPassRecording() или afterRenderPassRecording().

Функция не требуется, если команды записываются в собственный буфер команд приложения (например, VkCommandBuffer или MTLCommandBuffer + MTLRenderCommandEncoder, созданные и управляемые приложением, а не полученные из дерева сцены). В графических API, где концепция буфера команд не реализована напрямую (OpenGL, Direct 3D 11), функции beginExternalCommands() и endExternalCommands() вместе обеспечивают замену функции resetOpenGLState() Qt 5.

Вызов этой функции и endExternalCommands() не требуется внутри реализации render() узла QSGRenderNode, так как дерево сцены неявно выполняет необходимые шаги для узлов рендеринга.

Доступ к объектам графического API (таким как графический адаптер, буфер команд или кодировщик) осуществляется через QSGRendererInterface::getResource().

Предупреждение: Обратите внимание на то, что QSGRendererInterface::CommandListResource может возвращать другой объект между beginExternalCommands() и endExternalCommands(). Это может происходить, когда подлежащая реализация предоставляет отдельный вторичный буфер команд для записи внешних графических команд внутри прохода рендеринга. Поэтому всегда запрашивайте CommandListResource после вызова этой функции. Не пытайтесь повторно использовать объект из предыдущего запроса.

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

Функция была добавлена в Qt 5.14.

См. также endExternalCommands() и QQuickOpenGLUtils::resetOpenGLState().

[override virtual protected] void QQuickWindow::closeEvent(QCloseEvent *e)

Переопределяет: QWindow::closeEvent(QCloseEvent *ev).

[since 5.8] QSGImageNode *QQuickWindow::createImageNode() const

Создает простой узел изображения. Если дерево сцены не инициализировано, возвращается значение null.

Это кросс-платформенная альтернатива прямому созданию QSGSimpleTextureNode.

Функция была добавлена в Qt 5.8.

См. также QSGImageNode.

[since 5.8] QSGNinePatchNode *QQuickWindow::createNinePatchNode() const

Создает узел девяти областей. Если дерево сцены не инициализировано, возвращается значение null.

Функция была добавлена в Qt 5.8.

[since 5.8] QSGRectangleNode *QQuickWindow::createRectangleNode() const

Создает простой прямоугольный узел. Если дерево сцены не инициализировано, возвращается значение null.

Это кросс-платформенная альтернатива прямому созданию QSGSimpleRectNode.

Функция была добавлена в Qt 5.8.

См. также QSGRectangleNode.

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image, QQuickWindow::CreateTextureOptions options) const

Создаёт новую текстуру QSGTexture из переданного изображения image. Если изображение имеет альфа-канал, соответствующая текстура также будет иметь альфа-канал.

Вызывающая функция отвечает за удаление возвращённой текстуры. Соответствующий родной объект текстуры также уничтожается вместе с QSGTexture.

Если параметр options содержит TextureCanUseAtlas, движок может поместить изображение в атлас текстур. Текстуры в атласе должны полагаться на QSGTexture::normalizedTextureSubRect() для геометрии и не будут поддерживать QSGTexture::Repeat. Другие значения из CreateTextureOption игнорируются.

Если параметр options содержит TextureIsOpaque, движок создаст текстуру RGB, которая вернёт false для QSGTexture::hasAlphaChannel(). Непрозрачные текстуры в большинстве случаев рендерятся быстрее. Если этот флаг не установлен, текстура будет иметь альфа-канал, основанный на формате изображения.

Если параметр options содержит TextureHasMipmaps, движок создаст текстуру, которая может использовать фильтрацию mipmap. Мипмапированные текстуры не могут быть в атласе.

Если дерево сцены использует OpenGL, возвращаемая текстура будет использовать GL_TEXTURE_2D в качестве целевого типа текстуры и GL_RGBA в качестве внутреннего формата. В других графических API формат текстуры обычно RGBA8. Переопределите QSGTexture для создания текстур с различными параметрами.

Предупреждение: Эта функция вернёт 0, если дерево сцены ещё не инициализировано.

Предупреждение: Возвращаемая текстура не управляется памятью дерева сцены и должна быть явно удалена вызывающей стороной в потоке рендеринга. Это достигается путём удаления текстуры из деструктора QSGNode или использованием deleteLater() в случае, если текстура уже связана с потоком рендеринга.

Функцию можно вызывать из любого потока.

См. также sceneGraphInitialized() и QSGTexture.

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image) const

Это перегруженная функция.

qreal QQuickWindow::effectiveDevicePixelRatio() const

Возвращает коэффициент масштаба пикселей устройства для этого окна.

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

См. также QWindow::devicePixelRatio().

[since 5.14] void QQuickWindow::endExternalCommands()

При смешении команд графического API (OpenGL, Vulkan, Metal и т.д.) с рендерингом на основе дерева сцен, необходимо вызвать эту функцию после записи команд в буфер команд, используемый деревом сцены для рендеринга основного прохода. Это предотвращает перезапись состояния.

На практике эта функция часто вызывается из слота, подключенного к сигналам beforeRenderPassRecording() или afterRenderPassRecording().

Функция не требуется, если команды записываются в собственный буфер команд приложения (например, VkCommandBuffer или MTLCommandBuffer + MTLRenderCommandEncoder, созданные и управляемые приложением, а не полученные из дерева сцены). В графических API, где концепция буфера команд не реализована напрямую (OpenGL, Direct 3D 11), функции beginExternalCommands() и endExternalCommands() вместе обеспечивают замену функции resetOpenGLState() Qt 5.

Вызов этой функции и beginExternalCommands() не требуется внутри реализации render() узла QSGRenderNode, так как дерево сцены неявно выполняет необходимые шаги для узлов рендеринга.

Функция была добавлена в Qt 5.14.

См. также beginExternalCommands() и QQuickOpenGLUtils::resetOpenGLState().

[override virtual protected] bool QQuickWindow::event(QEvent *e)

Переопределяет: QWindow::event(QEvent *ev).

[override virtual protected] void QQuickWindow::exposeEvent(QExposeEvent *)

Переопределяет: QWindow::exposeEvent(QExposeEvent *ev).

[override virtual protected] void QQuickWindow::focusInEvent(QFocusEvent *ev)

Переопределяет: QWindow::focusInEvent(QFocusEvent *ev).

[override virtual protected] void QQuickWindow::focusOutEvent(QFocusEvent *ev)

Переопределяет: QWindow::focusOutEvent(QFocusEvent *ev).

QImage QQuickWindow::grabWindow()

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

Возможен вызов функции grabWindow(), когда окно не отображается. Для этого необходимо, чтобы окно было создано, имело корректные размеры и ни одно другое окно QQuickWindow не рендерилось в том же процессе.

Примечание: При использовании этого окна в сочетании с QQuickRenderControl результат этой функции — пустое изображение, если не используется software бэкенд. Это связано с тем, что при перенаправлении вывода в управляемый приложением графический ресурс (например, текстуру) с помощью QQuickRenderControl и setRenderTarget(), приложение лучше подходит для управления и выполнения потенциальной операции чтения, поскольку оно полностью контролирует этот ресурс с самого начала.

Предупреждение: Вызов этой функции может привести к проблемам производительности.

Предупреждение: Этот метод может вызываться только из потока GUI.

[static, since 6.0] QSGRendererInterface::GraphicsApi QQuickWindow::graphicsApi()

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

Стандартный способ запроса API, используемого графическим деревом, — использование QSGRendererInterface::graphicsApi() после инициализации графического дерева, например, при или после выдачи сигнала sceneGraphInitialized(). В этом случае вы получите истинное значение, поскольку тогда известно, что всё было инициализировано правильно с использованием этого графического API.

Это не всегда удобно. Если приложение должно настраивать внешние фреймворки или работать с setGraphicsDevice() таким образом, который зависит от встроенной логики выбора API графического дерева, то не всегда возможно отложить такие операции до того, как окно QQuickWindow будет отображено или вызов QQuickRenderControl::initialize().

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

Примечание: Этот статический метод предназначен для вызова только в главном (GUI) потоке. Для запроса API во время рендеринга используйте QSGRendererInterface, так как этот объект живёт в потоке рендеринга.

Примечание: Эта функция не учитывает бэкэнды графического дерева.

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

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

[since 6.0] QQuickGraphicsConfiguration QQuickWindow::graphicsConfiguration() const

Возвращает QQuickGraphicsDevice, переданный в setGraphicsDevice(), или объект по умолчанию в противном случае.

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

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

[since 6.0] QQuickGraphicsDevice QQuickWindow::graphicsDevice() const

Возвращает QQuickGraphicsDevice, переданный в setGraphicsDevice(), или объект по умолчанию в противном случае.

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

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

const QQuickWindow::GraphicsStateInfo &QQuickWindow::graphicsStateInfo()

Возвращает ссылку на структуру GraphicsStateInfo, описывающую часть внутренней информации RHI, в частности, состояние буферизации с двойным или тройным буфером бэкенда (например, интеграции Vulkan или Metal). Это актуально, когда подлежащий графический API — Vulkan или Metal, и внешний код рендеринга хочет выполнить буферизацию с двойным или тройным буфером собственных часто меняющихся ресурсов, таких как буферы униформ, чтобы избежать блокирования конвейера.

[static, since 5.1] bool QQuickWindow::hasDefaultAlphaBuffer()

Возвращает значение, определяющее, использовать ли альфа-прозрачность для вновь созданных окон.

Функция была добавлена в Qt 5.1.

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

[override virtual protected] void QQuickWindow::hideEvent(QHideEvent *)

Переопределяет: QWindow::hideEvent(QHideEvent *ev).

QQmlIncubationController *QQuickWindow::incubationController() const

Возвращает контроллер инкубации, который вставляет инкубацию между кадрами для данного окна. QQuickView автоматически устанавливает этот контроллер, в противном случае вам необходимо установить его самостоятельно с помощью QQmlEngine::setIncubationController().

Контроллер принадлежит окну и будет уничтожен при удалении окна.

bool QQuickWindow::isPersistentGraphics() const

Возвращает значение, определяющее, могут ли быть освобождены важные графические ресурсы в течение жизни окна QQuickWindow.

Примечание: Это подсказка, и не гарантируется, что она будет учтена.

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

bool QQuickWindow::isPersistentSceneGraph() const

Возвращает значение, определяющее, могут ли быть освобождены узлы и ресурсы графического дерева в течение жизни этого окна QQuickWindow.

Примечание: Это подсказка. Время и способ этого зависят от реализации.

bool QQuickWindow::isSceneGraphInitialized() const

Возвращает true, если графическое дерево было инициализировано; иначе возвращает false.

[override virtual protected] void QQuickWindow::keyPressEvent(QKeyEvent *e)

Переопределяет: QWindow::keyPressEvent(QKeyEvent *ev).

[override virtual protected] void QQuickWindow::keyReleaseEvent(QKeyEvent *e)

Переопределяет: QWindow::keyReleaseEvent(QKeyEvent *ev).

[override virtual protected] void QQuickWindow::mouseDoubleClickEvent(QMouseEvent *event)

Переопределяет: QWindow::mouseDoubleClickEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mouseMoveEvent(QMouseEvent *event)

Переопределяет: QWindow::mouseMoveEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mousePressEvent(QMouseEvent *event)

Переопределяет: QWindow::mousePressEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mouseReleaseEvent(QMouseEvent *event)

Переопределяет: QWindow::mouseReleaseEvent(QMouseEvent *ev).

[since 6.0] QQuickRenderTarget QQuickWindow::renderTarget() const

Возвращает QQuickRenderTarget, переданный в setRenderTarget(), или объект по умолчанию в противном случае.

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

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

[since 5.8] QSGRendererInterface *QQuickWindow::rendererInterface() const

Возвращает текущий интерфейс рендерера. Значение всегда валидно и никогда не равно null.

Примечание: Этот метод можно вызывать в любое время после создания QQuickWindow, даже когда isSceneGraphInitialized() всё ещё false. Однако некоторые функции интерфейса рендерера, в частности, QSGRendererInterface::getResource(), не будут функциональны до тех пор, пока графическое дерево не будет запущено. Запросы бэкенда, такие как QSGRendererInterface::graphicsApi() или QSGRendererInterface::shaderType(), всегда будут функциональны, с другой стороны.

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

Функция была добавлена в Qt 5.8.

См. также QSGRenderNode и QSGRendererInterface.

[override virtual protected] void QQuickWindow::resizeEvent(QResizeEvent *ev)

Переопределяет: QWindow::resizeEvent(QResizeEvent *ev).

[static, since 5.9] QString QQuickWindow::sceneGraphBackend()

Возвращает запрошенный бэкенд Qt Quick для сцены.

Примечание: Значение, возвращаемое этой функцией, может быть устаревшим последующими вызовами setSceneGraphBackend(), пока не будет создан первый QQuickWindow в приложении.

Примечание: Значение отражает только запрос в переменной среды QT_QUICK_BACKEND после создания QQuickWindow.

Функция была добавлена в Qt 5.9.

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

[since 5.4] void QQuickWindow::scheduleRenderJob(QRunnable *job, QQuickWindow::RenderStage stage)

Планирует выполнение job, когда отрисовка этого окна достигнет заданной стадии stage.

Это удобный способ для задач «один раз» в эквивалентных сигналах QQuickWindow.

Окно берет на себя владение job и удалит его при завершении задачи.

Если отрисовка будет остановлена, прежде чем job успеет выполниться, задача будет выполнена и удалена как часть очистки сцены. Если окно никогда не отображается и отрисовка не происходит до уничтожения QQuickWindow, все ожидающие задачи будут уничтожены без вызова метода run().

Если отрисовка происходит в другом потоке, то задача будет выполнена в потоке отрисовки.

Если stage равен NoStage, job будет выполнен при первой возможности, когда поток отрисовки не занят отрисовкой кадра. Если окно не отображается и не может быть отрисовано в момент публикации или обработки задачи, задача удаляется без выполнения метода run(). Если используется не-потоковый рендерер, метод run() задачи выполняется синхронно. При отрисовке с OpenGL контекст OpenGL изменяется на контекст рендерера перед выполнением любой задачи, включая задачи NoStage.

Примечание: Эта функция не запускает отрисовку; задачи, нацеленные на любую стадию, отличную от NoStage, будут сохранены до тех пор, пока отрисовка не будет инициирована где-либо ещё. Чтобы заставить задачу выполнитьс ранее, вызовите QQuickWindow::update();

Функция была добавлена в Qt 5.4.

См. также beforeRendering(), afterRendering(), beforeSynchronizing(), afterSynchronizing(), frameSwapped() и sceneGraphInvalidated().

[static, since 5.1] void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)

useAlpha указывает, использовать ли альфа-прозрачность для вновь созданных окон.

В любом приложении, которое ожидает создания полупрозрачных окон, необходимо установить это значение в true до создания первого QQuickWindow. Значение по умолчанию — false.

Функция была добавлена в Qt 5.1.

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

[static, since 5.8] void QQuickWindow::setGraphicsApi(QSGRendererInterface::GraphicsApi api)

Запрашивает указанный графический api.

При использовании встроенной адаптации графики, api указывает, какой графический API (OpenGL, Vulkan, Metal или Direct3D) должна использовать сцена для отрисовки. Кроме того, software бэкенд также встроен и может быть запрошен, установив api в QSGRendererInterface::Software.

В отличие от setSceneGraphBackend(), которая может использоваться только для запроса определенного бэкенда (доставляемого либо встроенного, либо установленного как динамически загружаемые плагины), эта функция работает с более высоким уровнем концепции графических API. Она охватывает бэкенды, поставляемые с Qt Quick, и, следовательно, имеет соответствующие значения в перечислении QSGRendererInterface::GraphicsApi.

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

Эта функция становится важной в приложениях, которые подготовлены только для отрисовки с заданным API. Например, если приложение выполняет нативную отрисовку OpenGL или Vulkan, оно захочет убедиться, что Qt Quick также использует OpenGL или Vulkan. Такие приложения должны вызвать эту функцию на ранней стадии функции main().

Примечание: Вызов функции должен произойти до создания первого QQuickWindow в приложении. Графический API не может быть изменён после этого.

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

Чтобы узнать, какой графический API использует сцена для отрисовки, используйте QSGRendererInterface::graphicsApi() после того, как сцена инициализирована, что обычно происходит либо когда окно впервые становится видимым, либо когда вызывается QQuickRenderControl::initialize().

Чтобы вернуться к поведению по умолчанию, где сцена выбирает графический API на основе платформы и других условий, установите api в QSGRendererInterface::Unknown.

Функция была добавлена в Qt 5.8.

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

[since 6.0] void QQuickWindow::setGraphicsConfiguration(const QQuickGraphicsConfiguration &config)

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

Такая дополнительная конфигурация, например, указывающая, какие расширения устройств нужно включить для Vulkan, становится актуальной и необходимой при интеграции кода нативного графического рендеринга, который зависит от определённых расширений. То же самое справедливо при интеграции с внешними 3D или VR движками, такими как OpenXR.

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

Экземпляры QQuickGraphicsConfiguration неявно разделяются, копируются и могут передаваться по значению.

Предупреждение: Установка QQuickGraphicsConfiguration на QQuickWindow должна выполняться достаточно рано, до первой инициализации сцены для этого окна. В случае окон на экране это означает, что вызов должен выполняться до вызова show() на QQuickWindow или QQuickView. В случае QQuickRenderControl конфигурация должна быть завершена перед вызовом initialize().

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

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

[since 6.0] void QQuickWindow::setGraphicsDevice(const QQuickGraphicsDevice &device)

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

Эта функция очень часто используется в сочетании с QQuickRenderControl и setRenderTarget() для перенаправления отрисовки Qt Quick в текстуру.

По умолчанию созданное QQuickGraphicsDevice не изменяет поведение по умолчанию. После того как QQuickGraphicsDevice создано через одну из функций-фабрик QQuickGraphicsDevice, таких как QQuickGraphicsDevice::fromDeviceObjects(), и сцена использует соответствующий графический API (в примере fromDeviceObjects() это Vulkan), сцена будет использовать существующие объекты устройства (например, VkPhysicalDevice, VkDevice, и индекс семейства графических очередей в случае Vulkan), инкапсулированные в QQuickGraphicsDevice. Это позволяет использовать одно и то же устройство и, таким образом, совместно использовать ресурсы, такие как буферы и текстуры, между Qt Quick и нативными движками рендеринга.

Предупреждение: Эта функция может быть вызвана только до инициализации сцены и не будет иметь эффекта, если вызвана после. На практике это обычно означает вызов её прямо перед QQuickRenderControl::initialize().

Пример использования с Direct3D:

// native graphics resources set up by a custom D3D rendering engine
ID3D11Device *device;
ID3D11DeviceContext *context;
ID3D11Texture2D *texture;
...
// now to redirect Qt Quick content into 'texture' we could do the following:
QQuickRenderControl *renderControl = new QQuickRenderControl;
QQuickWindow *window = new QQuickWindow(renderControl); // this window will never be shown on-screen
...
window->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(device, context));
renderControl->initialize();
window->setRenderTarget(QQuickRenderTarget::fromD3D11Texture(texture, textureSize);
...

Ключевым аспектом использования этой функции является обеспечение того, чтобы ресурсы или дескрипторы ресурсов, такие как texture в приведённом выше примере, были видимы и доступны как для внешнего движка рендеринга, так и для рендерера сцены. Для этого необходимо использовать одно и то же графическое устройство (или, в случае OpenGL, один и тот же контекст OpenGL).

Экземпляры QQuickGraphicsDevice неявно разделяются, копируются и могут передаваться по значению. Они не владеют связанными нативными объектами (такими как, ID3D11Device в примере).

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

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

См. также graphicsDevice(), QQuickRenderControl, setRenderTarget() и setGraphicsApi().

void QQuickWindow::setPersistentGraphics(bool persistent)

Устанавливает, должны ли графические ресурсы (графическое устройство или контекст, swapchain, буферы, текстуры) сохраняться и не могут быть освобождены до удаления последнего окна, в значение persistent. Значение по умолчанию — true.

При вызове releaseResources() или при скрытии окна (точнее, при отсутствии возможности отображения), некоторые циклы рендеринга имеют возможность освободить все графические ресурсы, а не только кэшированные. Это может временно высвободить память, но также означает, что движку рендеринга придется выполнить полную, потенциально дорогостоящую повторную инициализацию ресурсов, когда окно потребует повторного рендеринга.

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

Примечание: Все графические ресурсы освобождаются при удалении последнего QQuickWindow, независимо от этого параметра.

Примечание: Это подсказка, и не гарантируется, что она будет учтена.

Примечание: Эта подсказка не относится к кэшированным ресурсам, которые относительно дешево удалять и повторно создавать позже. Поэтому вызов releaseResources() обычно приводит к освобождению этих ресурсов независимо от значения этой подсказки.

См. также isPersistentGraphics(), setPersistentSceneGraph(), sceneGraphInitialized(), sceneGraphInvalidated() и releaseResources().

void QQuickWindow::setPersistentSceneGraph(bool persistent)

Устанавливает, являются ли узлы и ресурсы графа сцены persistent. Persistent означает, что узлы и ресурсы не могут быть освобождены. Значение по умолчанию — true.

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

Примечание: Узлы и ресурсы графа сцены всегда освобождаются при удалении последнего QQuickWindow, независимо от этого параметра.

Примечание: Это подсказка, и не гарантируется, что она будет учтена.

См. также isPersistentSceneGraph(), setPersistentGraphics(), sceneGraphInvalidated(), sceneGraphInitialized() и releaseResources().

void QQuickWindow::setRenderTarget(const QQuickRenderTarget &target)

Устанавливает целевой объект рендеринга для этого окна в значение target.

QQuickRenderTarget служит непросвечивающим идентификатором рендерируемого объекта нативного уровня, чаще всего это 2D-текстура, и связанными метаданными, например, размером в пикселях.

QQuickRenderTarget по умолчанию означает отсутствие перенаправления. В то же время допустимый target, созданный с помощью одной из статических функций-фабрик QQuickRenderTarget, активирует перенаправление рендеринга Qt Quick сцены: он больше не будет использовать цветовые буферы для поверхности, связанной с окном, а вместо этого будет использовать текстуры или другие графические объекты, указанные в target.

Например, если граф сцены использует Vulkan для рендеринга, можно перенаправить его вывод в VkImage. Для графических API, таких как Vulkan, также необходимо указать расположение изображения. Экземпляры QQuickRenderTarget неявно совместно используются, они копируемы и могут передаваться по значению. Однако они не владеют связанными объектами нативного уровня (например, VkImage в примере).

QQuickRenderTarget rt = QQuickRenderTarget::fromVulkanImage(vulkanImage, VK_IMAGE_LAYOUT_PREINITIALIZED, pixelSize);
quickWindow->setRenderTarget(rt);

Эта функция часто используется в сочетании с QQuickRenderControl и невидимым QQuickWindow для рендеринга содержимого Qt Quick в текстуру без создания отображаемого на экране нативного окна для данного QQuickWindow.

Если требуемый целевой объект или связанные данные, такие как размер, меняются, вызовите эту функцию с новым QQuickRenderTarget. Создание экземпляров QQuickRenderTarget и вызов этой функции несложны, но имейте в виду, что установка нового target с другим объектом нативного уровня или другими данными может привести к потенциально затратным шагам инициализации при готовности графа сцены рендерить следующий кадр. Поэтому меняйте целевой объект только при необходимости.

Примечание: Эта функция не должна использоваться при использовании бэкенда software. Вместо этого используйте grabWindow() для рендеринга содержимого в QImage.

Примечание: Окно не получает права владения на какие-либо нативные объекты, на которые ссылается target.

Примечание: Ответственность за обеспечение того, что нативные объекты, на которые ссылается target, также являются допустимыми для рендерера графа сцены, лежит на вызывающей стороне. Например, при использовании Vulkan, Metal и Direct3D это означает, что текстура или изображение создаются на том же графическом устройстве, которое используется графиком сцены внутри. Поэтому, когда используются объекты текстур, созданные на уже существующем устройстве или контексте, эта функция часто используется в сочетании с setGraphicsDevice().

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

Предупреждение: Эта функция может вызываться только из потока, выполняющего рендеринг.

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

См. также renderTarget(), QQuickRenderControl, setGraphicsDevice() и setGraphicsApi().

void QQuickWindow::setSceneGraphBackend(const QString &backend)

Запрашивает бэкенд Qt Quick графа сцены backend. Бэкенды могут быть встроенными или установлены в виде загружаемых динамически плагинов.

Это перегруженная функция.

Примечание: Вызов функции должен произойти до построения первого QQuickWindow в приложении. Его нельзя изменить после этого.

Если backend недействителен или произошла ошибка, запрос игнорируется.

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

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

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

void QQuickWindow::setTextRenderType(QQuickWindow::TextRenderType renderType)

Устанавливает тип рендеринга по умолчанию для текстовых элементов в Qt Quick в значение renderType.

Примечание: Установка типа рендеринга повлияет только на элементы, созданные после этого; тип рендеринга существующих элементов не будет изменен.

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

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

void QQuickWindow::showEvent(QShowEvent *)

Переопределяет: QWindow::showEvent(QShowEvent *ev).

void QQuickWindow::tabletEvent(QTabletEvent *event)

Переопределяет: QWindow::tabletEvent(QTabletEvent *ev).

QQuickWindow::TextRenderType QQuickWindow::textRenderType()

Возвращает тип рендеринга текстовых элементов в Qt Quick. По умолчанию — QQuickWindow::QtTextRendering.

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

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

void QQuickWindow::wheelEvent(QWheelEvent *event)

Переопределяет: QWindow::wheelEvent(QWheelEvent *ev).