Класс QOpenGLContext

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

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

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

Типы public

Функции public

Сигналы

Статические public члены

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

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

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

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

После того, как QOpenGLContext был сделан текущим, вы можете выполнять отрисовку в него независимо от платформы, используя средства OpenGL Qt, такие как 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 профиль, но драйвер и/или оборудование поддерживают только контексты 3.2 Core профиля, то вы получите контекст 3.2 Core профиля.

Возвращает 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 профиля может привести к контексту OpenGL 4.x core профиля. Аналогично, запрос 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.

На некоторых платформах ситуации потери контекста избежать нельзя. Однако на других они могут потребовать явного включения. Это можно сделать, включив ResetNotification в QSurfaceFormat. Это приведет к установке RESET_NOTIFICATION_STRATEGY_EXT в LOSE_CONTEXT_ON_RESET_EXT в базовом контексте OpenGL. QOpenGLContext затем будет отслеживать состояние через glGetGraphicsResetStatusEXT() в каждом вызове makeCurrent().

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

bool QOpenGLContext::makeCurrent(QSurface *surface)

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

Если surface — nullptr, это эквивалентно вызову 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)

Устанавливает контекст shareContext для совместного использования текстур, шейдеров и других ресурсов OpenGL. Необходимо вызвать 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() после этого.

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

template <typename TYPE> TYPE *QOpenGLContext::versionFunctions() const

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

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

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

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

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

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

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