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

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

перечисление 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.

См. также 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 вне основного (графического) потока.

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

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

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

QOpenGLFunctions_3_3_Core* funcs = 0;
funcs = context->versionFunctions<QOpenGLFunctions_3_3_Core>();
if (!funcs) {
    qWarning() << "Could not obtain required OpenGL context version";
    exit(1);
}

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

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

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

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