Класс 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.

Интеграция с ускоренными 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().

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

Когда экземпляр 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, который выполняет всю отрисовку в потоке GUI, одно и то же устройство или контекст используется со всеми видимыми QQuickWindow. Цикл рендеринга threaded использует выделенный контекст или устройство для каждого потока рендеринга, а следовательно, и для каждого QQuickWindow. В некоторых графических API предоставляется определенная настраиваемость через setGraphicsConfiguration(). Это позволяет, например, указать список расширений Vulkan для включения на VkDevice. Кроме того, можно предоставить набор существующих контекстов или устройств для использования QQuickWindow, вместо того, чтобы позволять ему создавать свой собственный. Это достигается с помощью setGraphicsDevice().

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

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

Перечисление QQuickWindow::CreateTextureOptionflags 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] enum QQuickWindow::TextRenderType

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

Выберите 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(). Это последний сигнал, который излучается потоком рендеринга графа сцены при рендеринге кадра.

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

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

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

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

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

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

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

[signal] void QQuickWindow::afterRendering()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[signal] void QQuickWindow::beforeRendering()

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

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

См. также 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, используемый для рендеринга графическим деревом сцены.

[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()

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

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

[slot] void QQuickWindow::releaseResources()

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

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

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

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

[signal, since 5.3] void QQuickWindow::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()

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

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

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

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

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

Этот метод был добавлен в 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. Текстуры с mipmap не могут быть в атласе.

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

Этот метод может быть вызван из любого потока.

См. также 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()

При смешении команд прямого графического рендеринга (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 не выполнял отрисовку в том же процессе.

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

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

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

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

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

Функция была добавлена в 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.

Эта функция была добавлена в 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 графа сцены.

Эта функция была добавлена в 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.

Эта функция была добавлена в 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().

Чтобы узнать, какой графический 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.

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

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

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

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

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

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

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

В качестве примера, на этот раз с 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 в примере).

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

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

void QQuickWindow::setPersistentGraphics(bool persistent)

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

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

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

void QQuickWindow::setPersistentSceneGraph(bool persistent)

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

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

См. также 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 с другим нативным объектом или другими данными может привести к потенциально дорогостоящим шагам инициализации, когда графическая система собирается отобразить следующий кадр. Поэтому изменяйте целевой объект только при необходимости.

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

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

void QQuickWindow::setSceneGraphBackend(const QString &backend)

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

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

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

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

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

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

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

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

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

[override virtual protected] void QQuickWindow::showEvent(QShowEvent *)

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

[override virtual protected] void QQuickWindow::tabletEvent(QTabletEvent *event)

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

[static, since 5.10] QQuickWindow::TextRenderType QQuickWindow::textRenderType()

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

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

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

[override virtual protected] void QQuickWindow::wheelEvent(QWheelEvent *event)

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