Класс 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] 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, но драйвер и/или оборудование поддерживают только контексты профиля Core версии 3.2, то вы получите контекст профиля Core версии 3.2.

Возвращает 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.

См. также QOpenGLFramebufferObject.

void QOpenGLContext::doneCurrent()

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

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

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

QSet<QByteArray> QOpenGLContext::extensions() const

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

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

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

QOpenGLExtraFunctions *QOpenGLContext::extraFunctions() const

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

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

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

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

QSurfaceFormat QOpenGLContext::format() const

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

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

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

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

См. также 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 не загружается динамически, возвращаемое значение определяется во время компиляции и никогда не меняется.

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

QScreen *QOpenGLContext::screen() const

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

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

void QOpenGLContext::setFormat(const QSurfaceFormat &format)

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

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

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

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, since 5.5] bool QOpenGLContext::supportsThreadedOpenGL()

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

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

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

QSurface *QOpenGLContext::surface() const

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

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

void QOpenGLContext::swapBuffers(QSurface *surface)

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

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