Класс QQuickWindow

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

Этот класс был представлен в Qt 5.0.

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

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

Свойства

• activeFocusItem : QQuickItem* const
• цвет : QColor
• contentItem : QQuickItem* const

Общие функции

Переопределённые публичные функции

Открытые слоты

Сигналы

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

Переопределённые защищённые функции

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

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

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

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

Отображение

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

Сигнал sceneGraphInitialized() генерируется в потоке отображения до того, как сцена QML отобразится на экране в первый раз. Если графическая сцена отображения была освобождена, сигнал будет сгенерирован снова перед отображением следующего кадра.

Интеграция с OpenGL

При использовании стандартной адаптации OpenGL, возможно интегрировать вызовы OpenGL напрямую в QQuickWindow, используя тот же контекст OpenGL, что и Qt Quick Scene Graph. Это делается путём подключения к сигналу QQuickWindow::beforeRendering() или QQuickWindow::afterRendering().

Примечание: При использовании QQuickWindow::beforeRendering(), убедитесь, что вы отключили очистку перед отрисовкой с помощью QQuickWindow::setClearBeforeRendering().

Экспонирование и видимость

Когда экземпляр QQuickWindow намеренно скрывается с помощью hide() или setVisible(false), он перестанет отображаться, и его графическая сцена и контекст графики могут быть освобождены. Сигнал sceneGraphInvalidated() будет генерироваться, когда это произойдёт.

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

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

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

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

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

Форматы контекста и поверхности

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

См. такжеГраф сцены — OpenGL в QML.

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

enum QQuickWindow::CreateTextureOptionflags QQuickWindow::CreateTextureOptions

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

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

enum QQuickWindow::NativeObjectType

Указывает тип нативного объекта, передаваемого в функции, такие как createTextureFromNativeObject().

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

enum QQuickWindow::RenderStage

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

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

enum QQuickWindow::SceneGraphError

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

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

enum QQuickWindow::TextRenderType

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

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

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

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

QQuickWindow::QQuickWindow(QWindow *parent = nullptr)

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

[signal] void QQuickWindow::afterAnimating()

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

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

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

[signal] void QQuickWindow::afterRenderPassRecording()

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

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

Если не используется RHI (и используется OpenGL напрямую), сигнал испускается после завершения рендеринга рендерером, но перед afterRendering(). Это позволяет создавать приложения, которые работают одинаково как с RHI, так и без него.

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

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

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

[signal] void QQuickWindow::afterRendering()

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

Этот сигнал можно использовать для рисования с помощью прямого OpenGL поверх содержимого QML или для скриншота текущего буфера кадра.

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

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

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

Предупреждение: Очень важно, чтобы обработчик сигнала для afterRendering() оставлял контекст OpenGL в том же состоянии, в котором он был при входе в обработчик сигнала. Если этого не сделать, сцена может отображаться неправильно.

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

[signal] void QQuickWindow::afterSynchronizing()

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

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

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

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

Предупреждение: При использовании адаптации OpenGL убедитесь, что обработчик сигнала после afterSynchronizing() оставляет контекст OpenGL в том же состоянии, в котором он был при входе в обработчик сигнала. Если этого не сделать, сцена может отображаться неправильно.

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

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

[signal] void QQuickWindow::beforeRenderPassRecording()

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

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

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

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

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

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

[signal] void QQuickWindow::beforeRendering()

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

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

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

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

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

Предупреждение: Убедитесь, что обработчик сигнала для beforeRendering оставляет контекст OpenGL в том же состоянии, в котором он был при входе в обработчик сигнала. Если этого не сделать, сцена может отображаться неправильно.

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

[signal] void QQuickWindow::beforeSynchronizing()

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

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

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

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

Предупреждение: Убедитесь, что обработчик сигнала для beforeSynchronizing оставляет контекст GL в том же состоянии, в котором он был при входе в обработчик сигнала. Если этого не сделать, сцена может отображаться неправильно.

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

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

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

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

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

См. также QMenuBar как глобальная строка меню.

[signal] void QQuickWindow::frameSwapped()

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

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

[signal] void QQuickWindow::openglContextCreated(QOpenGLContext *context)

Этот сигнал испускается в потоке GUI, когда контекст OpenGL context для этого окна создан, но до того, как он станет текущим.

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

QQuickWindow::openglContext() всё ещё вернёт 0 для этого окна до тех пор, пока не будет испущен QQuickWindow::sceneGraphInitialize().

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

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

[slot] void QQuickWindow::releaseResources()

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

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

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

[signal] void QQuickWindow::sceneGraphAboutToStop()

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

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

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

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

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

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

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

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

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

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

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

[signal] void QQuickWindow::sceneGraphInitialized()

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

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

[signal] void QQuickWindow::sceneGraphInvalidated()

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

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

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

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

[slot] void QQuickWindow::update()

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

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

[override virtual] QQuickWindow::~QQuickWindow()

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

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

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

void QQuickWindow::beginExternalCommands()

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

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

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

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

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

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

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

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

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

bool QQuickWindow::clearBeforeRendering() const

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

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

QSGImageNode *QQuickWindow::createImageNode() const

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

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

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

См. также QSGImageNode.

QSGNinePatchNode *QQuickWindow::createNinePatchNode() const

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

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

QSGRectangleNode *QQuickWindow::createRectangleNode() const

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

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

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

См. также QSGRectangleNode.

QSGTexture *QQuickWindow::createTextureFromId(uint id, const QSize &size, QQuickWindow::CreateTextureOptions options = CreateTextureOption()) const

Создаёт новый объект QSGTexture из существующего идентификатора OpenGL-текстуры id и size.

Вызывающий функцию отвечает за удаление возвращённой текстуры.

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

Используйте options для настройки атрибутов текстуры. Опция TextureUsesAtlas игнорируется.

Предупреждение: Эта функция вернёт null, если графический сценарий ещё не инициализирован или OpenGL не используется.

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

Примечание: Эта функция не имеет эффекта при выполнении на абстракции графики RHI. Используйте createTextureFromNativeObject() вместо этого.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QSGTexture *QQuickWindow::createTextureFromNativeObject(QQuickWindow::NativeObjectType type, const void *nativeObjectPtr, int nativeLayout, const QSize &size, QQuickWindow::CreateTextureOptions options = CreateTextureOption()) const

Создаёт новый объект QSGTexture из существующего объекта родного API.

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

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

В настоящее время эта функция подходит только для 2D текстур RGBA.

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

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

Используйте options для настройки атрибутов текстуры. Здесь учитываются только TextureHasAlphaChannel и TextureHasMipmaps.

Предупреждение: В отличие от createTextureFromId(), эта функция никогда не берёт владения родным объектом, и флаг TextureOwnsGLTexture игнорируется.

size задаёт размер в пикселях.

nativeObjectPtr — указатель на дескриптор родного объекта. В OpenGL родной дескриптор имеет значение GLuint, поэтому nativeObjectPtr — указатель на GLuint. В Vulkan родной дескриптор — VkImage, поэтому nativeObjectPtr — указатель на VkImage. В Direct3D 11 и Metal nativeObjectPtr — указатель на ID3D11Texture2D или MTLTexture.

Примечание: Обратите внимание, что nativeObjectPtr всегда является указателем на тип дескриптора родной текстуры, даже если сам родной тип является указателем.

nativeLayout используется только для таких API, как Vulkan. Применительно к этому, он должен указывать текущую компоновку изображения, например, значение VkImageLayout.

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

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

qreal QQuickWindow::effectiveDevicePixelRatio() const

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

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

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

void QQuickWindow::endExternalCommands()

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

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

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

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

Примечание: Эта функция не имеет эффекта, когда граф сцены использует OpenGL напрямую, и абстракция графического API RHI не используется. В этом случае обратитесь к resetOpenGLState().

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

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

bool QQuickWindow::event(QEvent *e)

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

void QQuickWindow::exposeEvent(QExposeEvent *)

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

void QQuickWindow::focusInEvent(QFocusEvent *ev)

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

void QQuickWindow::focusOutEvent(QFocusEvent *ev)

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

QImage QQuickWindow::grabWindow()

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

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

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

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

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

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

bool QQuickWindow::hasDefaultAlphaBuffer()

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

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

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

void QQuickWindow::hideEvent(QHideEvent *)

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

QQmlIncubationController *QQuickWindow::incubationController() const

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

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

bool QQuickWindow::isPersistentOpenGLContext() const

Возвращает, может ли контекст OpenGL быть освобождён во время жизненного цикла QQuickWindow.

Примечание: Это подсказка. Когда и как это происходит, зависит от реализации. Также это имеет эффект только при использовании стандартной адаптации графа сцены OpenGL.

bool QQuickWindow::isPersistentSceneGraph() const

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

Примечание: Это подсказка. Когда и как это происходит, зависит от реализации.

bool QQuickWindow::isSceneGraphInitialized() const

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

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).

QQuickItem *QQuickWindow::mouseGrabberItem() const

Возвращает элемент, который в данный момент захватывает мышь.

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

QOpenGLContext *QQuickWindow::openglContext() const

Возвращает контекст OpenGL, используемый для отрисовки.

Примечание: Если граф сцены не готов или граф сцены не использует OpenGL (или RHI поверх OpenGL), эта функция вернёт null.

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

QOpenGLFramebufferObject *QQuickWindow::renderTarget() const

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

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

Примечание: Эта функция вернёт nullptr при отсутствии адаптации графика сцены OpenGL.

Примечание: Эта функция не имеет эффекта и возвращает nullptr при выполнении на абстракции графического API RHI.

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

uint QQuickWindow::renderTargetId() const

Возвращает идентификатор FBO целевого объекта отрисовки, если он задан; в противном случае возвращает 0.

QSize QQuickWindow::renderTargetSize() const

Возвращает размер текущего целевого объекта отрисовки; в противном случае возвращает пустой размер.

QSGRendererInterface *QQuickWindow::rendererInterface() const

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

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

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

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

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

void QQuickWindow::resetOpenGLState()

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

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

Эта функция не затрагивает состояние в фиксированной конвейерной обработке.

Эта функция не очищает буферы цвета, глубины и трафарета. Используйте QQuickWindow::setClearBeforeRendering для управления очисткой буфера цвета. Буферы глубины и трафарета могут быть перезаписаны рендерером графа сцены. Очищайте их вручную по мере необходимости.

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

Примечание: Эта функция не имеет эффекта при выполнении на графической абстракции RHI. С RHI функции для вставки нативных графических команд — это beginExternalCommands() и endExternalCommands().

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

См. также QQuickWindow::beforeRendering(), beginExternalCommands() и endExternalCommands().

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

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

[static] QString QQuickWindow::sceneGraphBackend()

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

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

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

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

void QQuickWindow::scheduleRenderJob(QRunnable *job, QQuickWindow::RenderStage stage)

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

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

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

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

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

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

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

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

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

void QQuickWindow::setClearBeforeRendering(bool enabled)

Устанавливает, будет ли граф сцены QML очищать буфер цвета перед началом отрисовки на enabled.

Отключив очистку буфера цвета, можно отрисовывать контент OpengGL под графом сцены.

Буфер цвета очищается по умолчанию.

Предупреждение: Этот флаг полностью игнорируется при работе с графической абстракцией RHI вместо непосредственного использования OpenGL. Так как явные команды очистки не существуют в некоторых современных API, граф сцены больше не может предложить такую гибкость. Изображения, связанные с целевым объектом отрисовки, всегда будут очищаться при запуске пасса отрисовки. В качестве решения альтернативой отключению очисток, инициированных графом сцены, является сигнал beforeRenderPassRecording().

См. также clearBeforeRendering(), beforeRendering() и beforeRenderPassRecording().

[static] void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)

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

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

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

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

void QQuickWindow::setPersistentOpenGLContext(bool persistent)

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

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

Сигнал QOpenGLContext::aboutToBeDestroyed() испускается из QQuickWindow::openglContext() при освобождении контекста OpenGL. Сигнал QQuickWindow::sceneGraphInitialized() испускается, когда для этого окна создается новый контекст OpenGL. Используйте Qt::DirectConnection для этих сигналов, чтобы быть уведомленным.

Контекст OpenGL всё равно будет освобожден при удалении последнего QQuickWindow.

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

См. также isPersistentOpenGLContext(), setPersistentSceneGraph(), QOpenGLContext::aboutToBeDestroyed() и sceneGraphInitialized().

void QQuickWindow::setPersistentSceneGraph(bool persistent)

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

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

Сигнал QQuickWindow::sceneGraphInvalidated() испускается при очистке. Сигнал QQuickWindow::sceneGraphInitialized() испускается при пересоздании сцены для этого окна. Используйте Qt::DirectConnection для этих сигналов, чтобы быть уведомленным.

Узлы и ресурсы сцены всё равно будут освобождены при удалении последнего QQuickWindow.

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

void QQuickWindow::setRenderTarget(QOpenGLFramebufferObject *fbo)

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

Указанный fbo должен быть создан в контексте окна или в контексте, совмещенном с ним.

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

Примечание: Эта функция не имеет эффекта при работе с графической абстракцией RHI.

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

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

void QQuickWindow::setRenderTarget(uint fboId, const QSize &size)

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

Устанавливает целевой объект отрисовки для этого окна в FBO с fboId и size.

Указанный FBO должен быть создан в контексте окна или в контексте, совмещенном с ним.

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

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

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

void QQuickWindow::setSceneGraphBackend(QSGRendererInterface::GraphicsApi api)

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

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

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

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

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

void QQuickWindow::setSceneGraphBackend(const QString &backend)

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

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

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

Если backend недопустим или произошла ошибка, используется бэкэнд по умолчанию (OpenGL или программный, в зависимости от конфигурации Qt).

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

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

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

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

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

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

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

void QQuickWindow::showEvent(QShowEvent *)

Реализует: QWindow::showEvent(QShowEvent *ev).

QQuickWindow::TextRenderType QQuickWindow::textRenderType()

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

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

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

void QQuickWindow::wheelEvent(QWheelEvent *event)

Реализует: QWindow::wheelEvent(QWheelEvent *ev).