Класс QOpenGLContext

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

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

Типы public

Функции public

Сигналы

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

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

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.

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

[since 5.3] перечисление 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, если такая функция не найдена.

[since 5.8] QFunctionPointer QOpenGLContext::getProcAddress(const char *procName) const

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

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

[static, since 5.5] 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().

[since 5.3] bool QOpenGLContext::isOpenGLES() const

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

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

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

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

bool QOpenGLContext::isValid() const

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

На некоторых платформах значение 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 affinity нити.

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

template <typename QNativeInterface> QNativeInterface *QOpenGLContext::nativeInterface() const

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

Эта функция предоставляет доступ к платформенно-специфичному функционалу QOpenGLContext, как определено в пространстве имён QNativeInterface:

Если запрошенный интерфейс недоступен, возвращается nullptr.

[static, since 5.3] 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)

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

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

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

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

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

[static, since 5.5] bool QOpenGLContext::supportsThreadedOpenGL()

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

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

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

QSurface *QOpenGLContext::surface() const

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

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

void QOpenGLContext::swapBuffers(QSurface *surface)

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

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