Класс QOpenGLContext

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

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

Типы public

Функции public

• 31 функция public, унаследованная от QObject

Сигналы

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

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

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

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

• 1 свойство, унаследованное от QObject
• 1 public слот, унаследованный от QObject
• 9 защищенных функций, унаследованных от 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 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().

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

Возвращает 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 профилем может привести к контексту 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 с совместным использованием, если он присутствует. В противном случае возвращает нулевой указатель.

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

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

На некоторых платформах возвращаемое значение 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. Возвращаемый объект типа QVariant содержит платформозависимое значение. Эти классы можно найти в модуле QtPlatformHeaders.

На платформах, где получение системного идентификатора не поддерживается, или если ни create(), ни setNativeHandle() не вызывались, возвращается нулевой объект QVariant.

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

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

[static] void *QOpenGLContext::openGLModuleHandle()

Возвращает платформозависимый идентификатор реализации OpenGL, которая используется в данный момент. (например, HMODULE в Windows)

На платформах, где динамическая переключаемость GL не используется, возвращаемое значение равно null.

Библиотека может быть только 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 — это QVariant, содержащий платформозависимое значение.

Когда 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 в качестве аргумента в нешаблонную функцию.

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

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

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