Класс QOpenGLContext

Класс QOpenGLContext представляет собой собственный контекст OpenGL, позволяющий выполнять отрисовку OpenGL на QSurface. Подробнее...

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

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

Типы публичного доступа

Функции публичного доступа

Сигналы

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

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

QOpenGLContext представляет состояние OpenGL в базовом контексте OpenGL. Чтобы настроить контекст, задайте его экран и формат таким образом, чтобы они соответствовали экрану или экранам, с которыми должен использоваться контекст, при необходимости, предоставьте ему возможность совместно использовать ресурсы с другими контекстами с помощью setShareContext(), а затем вызовите create(). Используйте возвращаемое значение или isValid() для проверки успешного инициализации контекста.

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

Если контекст временно не нужен, например, когда приложение не выполняет отрисовку, может быть полезно удалить его, чтобы освободить ресурсы. Вы можете подключиться к сигналу aboutToBeDestroyed() для очистки любых ресурсов, выделенных с разной принадлежностью, отличной от самого QOpenGLContext.

После того, как контекст QOpenGLContext стал текущим, вы можете отобразить его с помощью независимого от платформы способа, используя Qt OpenGL-помощники, такие как QOpenGLFunctions, QOpenGLBuffer, QOpenGLShaderProgram и QOpenGLFramebufferObject. Также можно напрямую использовать API OpenGL платформы без использования Qt-помощников, хотя это может повлиять на переносимость. Последнее необходимо, когда требуется использовать OpenGL 1.x или OpenGL ES 1.x.

Дополнительную информацию об API OpenGL см. в официальной документации OpenGL.

Пример использования QOpenGLContext см. в примере OpenGL Window.

Связь с потоком

QOpenGLContext можно переместить в другой поток с помощью moveToThread(). Не вызывайте makeCurrent() из потока, отличного от того, к которому принадлежит объект QOpenGLContext. Контекст может быть текущим только в одном потоке и для одной поверхности одновременно, и поток имеет только один текущий контекст за раз.

Совместное использование ресурсов контекста

Ресурсы, такие как текстуры и буферы вершин, можно совместно использовать между контекстами. Используйте setShareContext() перед вызовом create(), чтобы указать, что контексты должны совместно использовать эти ресурсы. QOpenGLContext внутренне отслеживает объект QOpenGLContextGroup, к которому можно получить доступ с помощью shareGroup(), и который можно использовать для поиска всех контекстов в данной группе совместного использования. Группа совместного использования состоит из всех контекстов, которые были успешно инициализированы и совместно используют существующий контекст в группе совместного использования. Контекст без совместного использования имеет группу совместного использования, состоящую из одного контекста.

Основной буфер

На некоторых платформах буфер кадра, отличный от 0, может быть буфером кадра по умолчанию в зависимости от текущей поверхности. Вместо вызова glBindFramebuffer(0), рекомендуется использовать glBindFramebuffer(ctx->defaultFramebufferObject()), чтобы гарантировать переносимость вашего приложения между различными платформами. Однако, если вы используете QOpenGLFunctions::glBindFramebuffer(), это делается автоматически за вас.

См. также QOpenGLFunctions, QOpenGLBuffer, QOpenGLShaderProgram и QOpenGLFramebufferObject.

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

enum QOpenGLContext::OpenGLModuleType

Этот перечисление определяет тип базовой реализации OpenGL.

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

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

QOpenGLContext::QOpenGLContext(QObject *parent = nullptr)

Создает новый экземпляр контекста OpenGL с родительским объектом parent.

Перед использованием необходимо установить правильный формат и вызвать create().

См. также create() и makeCurrent().

[signal] void QOpenGLContext::aboutToBeDestroyed()

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

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

[virtual] QOpenGLContext::~QOpenGLContext()

Уничтожает объект QOpenGLContext.

Если это текущий контекст для потока, также вызывается doneCurrent().

[static] bool QOpenGLContext::areSharing(QOpenGLContext *first, QOpenGLContext *second)

Возвращает true, если контексты first и second используют общие ресурсы OpenGL.

bool QOpenGLContext::create()

Попытка создать контекст OpenGL с текущей конфигурацией.

Текущая конфигурация включает формат, контекст совместного использования и экран.

Если реализация OpenGL на вашей системе не поддерживает запрашиваемую версию контекста OpenGL, то QOpenGLContext попытается создать наиболее соответствующую версию. Фактические свойства созданного контекста можно запросить, используя QSurfaceFormat, возвращаемый функцией format(). Например, если вы запрашиваете контекст, поддерживающий OpenGL 4.3 Core profile, но драйвер и/или оборудование поддерживают только контексты версии 3.2 Core profile, то вы получите контекст 3.2 Core profile.

Возвращает true, если системный контекст был успешно создан и готов к использованию с makeCurrent(), swapBuffers() и т. д.

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

См. также makeCurrent() и format().

[static] QOpenGLContext *QOpenGLContext::currentContext()

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

GLuint QOpenGLContext::defaultFramebufferObject() const

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

На некоторых платформах (например, iOS) буфер кадра по умолчанию зависит от поверхности, на которую выполняется рендеринг, и может отличаться от 0. Таким образом, вместо вызова glBindFramebuffer(0), следует вызвать glBindFramebuffer(ctx->defaultFramebufferObject()), если вы хотите, чтобы ваше приложение работало на разных платформах Qt.

Если вы используете glBindFramebuffer() в QOpenGLFunctions, вам не нужно беспокоиться об этом, так как он автоматически привязывает defaultFramebufferObject() текущего контекста, когда передается 0.

Примечание: Виджеты, которые выполняют рендеринг с помощью буферов кадра, такие как QOpenGLWidget и QQuickWidget, переопределяют значение, возвращаемое этой функцией, когда активна отрисовка, потому что в этот момент правильный "буфер кадра по умолчанию" — это связанный буфер кадра виджета, а не буфер платформы, относящийся к поверхности окна верхнего уровня. Это гарантирует ожидаемое поведение для этой функции и других классов, которые полагаются на неё (например, QOpenGLFramebufferObject::bindDefault() или QOpenGLFramebufferObject::release()).

См. также QOpenGLFramebufferObject.

void QOpenGLContext::doneCurrent()

Удобная функция для вызова makeCurrent с поверхностью 0.

Это приводит к отсутствию текущего контекста в текущем потоке.

См. также makeCurrent() и currentContext().

QSet<QByteArray> QOpenGLContext::extensions() const

Возвращает набор расширений OpenGL, поддерживаемых этим контекстом.

Контекст или контекст совместного использования должен быть текущим.

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

QOpenGLExtraFunctions *QOpenGLContext::extraFunctions() const

Получение экземпляра QOpenGLExtraFunctions для этого контекста.

QOpenGLContext предоставляет это как удобный способ доступа к QOpenGLExtraFunctions, без необходимости управления им вручную.

Возвращаемый экземпляр QOpenGLExtraFunctions готов к использованию и ему не нужно вызывать initializeOpenGLFunctions().

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

См. также QOpenGLFunctions и QOpenGLExtraFunctions.

QSurfaceFormat QOpenGLContext::format() const

Возвращает формат базового платформенного контекста, если был вызван create().

В противном случае возвращает запрашиваемый формат.

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

Например, запрос контекста с OpenGL 3.x core profile может привести к контексту OpenGL 4.x core profile. Аналогично, запрос OpenGL 2.1 может привести к контексту OpenGL 3.0 с включёнными устаревшими функциями. Наконец, в зависимости от драйвера, недоступные версии могут привести либо к ошибке создания контекста, либо к контексту с самой высокой поддерживаемой версией.

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

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

QOpenGLFunctions *QOpenGLContext::functions() const

Получение экземпляра QOpenGLFunctions для этого контекста.

QOpenGLContext предоставляет это как удобный способ доступа к QOpenGLFunctions, без необходимости управления им вручную.

Контекст или контекст совместного использования должны быть текущими.

Возвращаемый экземпляр QOpenGLFunctions готов к использованию и ему не нужно вызывать initializeOpenGLFunctions().

QFunctionPointer QOpenGLContext::getProcAddress(const QByteArray &procName) const

Решает указатель функции на функцию расширения OpenGL, идентифицируемую по procName

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

QFunctionPointer QOpenGLContext::getProcAddress(const char *procName) const

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

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

[static] QOpenGLContext *QOpenGLContext::globalShareContext()

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

Это полезно, если вам нужно загрузить объекты OpenGL (буферы, текстуры и т. д.) перед созданием или отображением QOpenGLWidget или QQuickWidget.

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

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

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

См. также Qt::AA_ShareOpenGLContexts, setShareContext() и makeCurrent().

bool QOpenGLContext::hasExtension(const QByteArray &extension) const

Возвращает true, если этот контекст OpenGL поддерживает указанное расширение OpenGL extension, false, в противном случае.

Контекст или контекст совместного использования должны быть текущими.

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

bool QOpenGLContext::isOpenGLES() const

Возвращает true, если контекст является контекстом OpenGL ES.

Если контекст еще не создан, результат основан на запрошенном формате, заданном с помощью setFormat().

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

См. также create(), format() и setFormat().

bool QOpenGLContext::isValid() const

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

На некоторых платформах возвращаемое значение false для контекста, который был успешно создан ранее, указывает на то, что контекст OpenGL был утерян.

Типичный способ обработки сценариев потери контекста в приложениях — проверка с помощью этой функции всякий раз, когда makeCurrent() терпит неудачу и возвращает false. Если эта функция затем возвращает false, пересоздайте базовый нативный контекст OpenGL, вызвав create(), снова вызовите makeCurrent(), а затем повторно инициализируйте все ресурсы OpenGL.

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

bool QOpenGLContext::makeCurrent(QSurface *surface)

Делает контекст текущим в текущей нити по отношению к заданной surface. Возвращает true, если успешно; в противном случае возвращает false. Последнее может произойти, если поверхность не доступна или графическое оборудование недоступно, например, из-за приостановки приложения.

Если surface равно 0, это эквивалентно вызову doneCurrent().

Избегайте вызова этой функции из другой нити, чем та, в которой находится экземпляр QOpenGLContext. Если вы хотите использовать QOpenGLContext из другой нити, сначала убедитесь, что он не является текущим в текущей нити, вызвав doneCurrent(), если необходимо. Затем вызовите moveToThread(otherThread) перед использованием его в другой нити.

По умолчанию Qt использует проверку, которая навязывает вышеуказанное условие на сродство нити. Все еще возможно отключить эту проверку, установив атрибут приложения Qt::AA_DontCheckOpenGLContextThreadAffinity. Убедитесь, что вы понимаете последствия использования QObjects вне нити, в которой они существуют, как описано в документации по сродству нити QObject.

См. также functions(), doneCurrent() и Qt::AA_DontCheckOpenGLContextThreadAffinity.

QVariant QOpenGLContext::nativeHandle() const

Возвращает нативный дескриптор контекста.

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

На платформах, где получение нативного дескриптора не поддерживается, или если ни create(), ни setNativeHandle() не были вызваны, возвращается нулевая переменная.

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

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

[static] void *QOpenGLContext::openGLModuleHandle()

Возвращает дескриптор, специфичный для платформы, для реализации OpenGL, которая в настоящее время используется. (например, HMODULE в Windows)

На платформах, которые не используют динамическую переключение GL, возвращаемое значение равно nullptr.

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

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

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

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

[static] QOpenGLContext::OpenGLModuleType QOpenGLContext::openGLModuleType()

Возвращает тип базовой реализации OpenGL.

На платформах, где реализация OpenGL не загружается динамически, возвращаемое значение определяется во время компиляции и никогда не меняется.

Примечание: Реализация OpenGL для настольных систем может также уметь создавать совместимые с ES контексты. Поэтому в большинстве случаев предпочтительнее проверять QSurfaceFormat::renderableType() или использовать вспомогательную функцию isOpenGLES().

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

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

QScreen *QOpenGLContext::screen() const

Возвращает экран, для которого был создан контекст.

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

void QOpenGLContext::setFormat(const QSurfaceFormat &format)

Устанавливает формат, с которым должен быть совместим контекст OpenGL. Вам нужно вызвать create(), прежде чем он вступит в силу.

Если формат не установлен явно с помощью этой функции, будет использован формат, возвращаемый QSurfaceFormat::defaultFormat(). Это означает, что при наличии нескольких контекстов отдельные вызовы этой функции можно заменить одним вызовом QSurfaceFormat::setDefaultFormat() перед созданием первого контекста.

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

void QOpenGLContext::setNativeHandle(const QVariant &handle)

Устанавливает нативные дескрипторы для этого контекста. Когда вызывается create(), и нативный дескриптор установлен, параметры конфигурации, такие как format(), игнорируются, так как этот QOpenGLContext будет оборачивать уже созданный нативный контекст, а не создавать новый с нуля.

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

Когда create() вызывается с установленными нативными дескрипторами, QOpenGLContext не принимает владения над дескрипторами, поэтому уничтожение QOpenGLContext не уничтожает нативный контекст.

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

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

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

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

void QOpenGLContext::setScreen(QScreen *screen)

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

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

void QOpenGLContext::setShareContext(QOpenGLContext *shareContext)

Заставляет этот контекст совместно использовать текстуры, шейдеры и другие ресурсы OpenGL с shareContext. Вам нужно вызвать create(), прежде чем он вступит в силу.

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

QOpenGLContext *QOpenGLContext::shareContext() const

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

Если базовая платформа не смогла поддержать запрашиваемое совместное использование, она вернёт 0.

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

QOpenGLContextGroup *QOpenGLContext::shareGroup() const

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

[static] bool QOpenGLContext::supportsThreadedOpenGL()

Возвращает true, если платформа поддерживает рендеринг OpenGL вне основного (GUI) потока.

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

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

QSurface *QOpenGLContext::surface() const

Возвращает поверхность, с которой контекст был установлен как текущий.

Это поверхность, переданная в качестве аргумента функции makeCurrent().

void QOpenGLContext::swapBuffers(QSurface *surface)

Меняет местами задние и передние буферы surface.

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

QAbstractOpenGLFunctions *QOpenGLContext::versionFunctions(const QOpenGLVersionProfile &versionProfile = QOpenGLVersionProfile()) const

Возвращает указатель на объект, предоставляющий доступ ко всем функциям для versionProfile этого контекста. Нет необходимости вызывать QAbstractOpenGLFunctions::initializeOpenGLFunctions(), пока этот контекст является текущим. Также возможно вызвать эту функцию, когда контекст не текущий, но в этом случае ответственность за правильную инициализацию ложится на вызывающую сторону, которая должна вызвать QAbstractOpenGLFunctions::initializeOpenGLFunctions() после этого.

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

TYPE *QOpenGLContext::versionFunctions() const

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

Возвращает указатель на объект, предоставляющий доступ ко всем функциям для версии и профиля этого контекста. Нет необходимости вызывать QAbstractOpenGLFunctions::initializeOpenGLFunctions(), пока этот контекст является текущим. Также возможно вызвать эту функцию, когда контекст не текущий, но в этом случае ответственность за правильную инициализацию ложится на вызывающую сторону, которая должна вызвать QAbstractOpenGLFunctions::initializeOpenGLFunctions() после этого.

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

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

Обратите внимание, что запросы на объекты функций других версий или профилей могут завершиться ошибкой и в таком случае вернут nullptr. Ситуации, в которых создание объекта функций может завершиться ошибкой, возникают, если запрос не может быть удовлетворён из-за запроса функций, отсутствующих в версии или профиле этого контекста. Например:

• Запрос объекта функций 3.3 core profile будет успешен.
• Запрос объекта функций 3.3 compatibility profile завершится ошибкой. Мы не сможем разрешить устаревшие функции.
• Запрос объекта функций 4.3 core profile завершится ошибкой. Мы не сможем разрешить новые функции ядра, введённые в версиях 4.0-4.3.
• Запрос объекта функций 3.1 будет успешен. В 3.1 нет ничего, чего нет и в 3.3 core.

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