Класс QOpenGLContext

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

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

Типы

Открытые функции

• 34 открытых функции унаследованные от QObject

Сигналы

• 2 сигнала унаследованные от QObject

Статические открытые члены

• 10 статических открытых членов, унаследованных от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 1 открытая переменная, унаследованная от QObject
• 9 защищенных функций, унаследованных от QObject
• 2 защищенных переменных, унаследованных от QObject

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

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

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.

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

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

Обмен ресурсами контекста

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

Фреймбуфер по умолчанию

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

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

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

перечисление QOpenGLContext::OpenGLModuleType

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

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

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

QOpenGLContext::QOpenGLContext(QObject *parent = nullptr)

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

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

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

[virtual] QOpenGLContext::~QOpenGLContext()

Удаляет объект QOpenGLContext.

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

[signal] void QOpenGLContext::aboutToBeDestroyed()

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

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

[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 в текущей нити или 0, если контекст не текущий.

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.

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

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

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

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

[static] QOpenGLContext *QOpenGLContext::globalShareContext()

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

Это полезно, если вам нужно загрузить объекты 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, пересоздайте основной контекст native 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 thread affinity.

См. также 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, возвращаемое значение равно нулю.

Библиотека может быть только 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)

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

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

void QOpenGLContext::setShareContext(QOpenGLContext *shareContext)

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

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

QOpenGLContext *QOpenGLContext::shareContext() const

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

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

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

QOpenGLContextGroup *QOpenGLContext::shareGroup() const

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

bool QOpenGLContext::supportsThreadedOpenGL()

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

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

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

QSurface *QOpenGLContext::surface() const

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

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

void QOpenGLContext::swapBuffers(QSurface *surface)

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

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

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

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

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

TYPE *QOpenGLContext::versionFunctions() const

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

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

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

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

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

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

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