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

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

Этот сигнал применим при использовании графической абстракции RHI с scenegraph. Он излучается раньше, чем afterRendering(), и гарантирует, что не только кадр, но и запись основного прохода рендеринга scenegraph всё ещё активна. Это позволяет вставлять команды без необходимости генерировать целые отдельные проходы рендеринга (что обычно очистит присоединённые изображения). Нативные графические объекты можно запросить с помощью 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).

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

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

Примечание: Этот сигнал будет испущен только при использовании адаптации 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)

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

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

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

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

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

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

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

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.

См. также QSGRectangleNode.

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

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

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 и QSGTexture::nativeTexture().

qreal QQuickWindow::effectiveDevicePixelRatio() const

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

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

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

void QQuickWindow::endExternalCommands()

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

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

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

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

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

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

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

[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 не должно выполняться в том же процессе.

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

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

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

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

[static] 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::isPersistentOpenGLContext() const

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

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

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

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() всё ещё равно false. Однако некоторые функции интерфейса рендерера, в частности QSGRendererInterface::getResource(), не будут функциональны до тех пор, пока дерево сцены не будет запущено. Запросы к бэкенду, такие как QSGRendererInterface::graphicsApi() или QSGRendererInterface::shaderType(), с другой стороны, всегда будут функциональными.

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

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

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

void QQuickWindow::resetOpenGLState()

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

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

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

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

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

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

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

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

Окно берёт на себя ответственность за 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 под деревом сцены.

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

Предупреждение: Этот флаг полностью игнорируется при работе с абстракцией графического API 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. 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 по умолчанию.

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

[static] void QQuickWindow::setSceneGraphBackend(QSGRendererInterface::GraphicsApi api)

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

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

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

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

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

[static] void QQuickWindow::setSceneGraphBackend(const QString &backend)

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

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

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

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

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

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

[static] 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] QQuickWindow::TextRenderType QQuickWindow::textRenderType()

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

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

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

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

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