Класс QOpenGLContext

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

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

Типы public

Функции public

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

Сигналы

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

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

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

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

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от 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.

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

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 = Q_NULLPTR)

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

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

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

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 может привести к контексту 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

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

[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, пересоздайте базовый родной контекст OpenGL, вызвав create(), снова вызовите makeCurrent(), а затем повторно инициализируйте все ресурсы OpenGL.

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

bool QOpenGLContext::makeCurrent(QSurface *surface)

Делает контекст текущим в текущем потоке по отношению к заданной surface. Возвращает true при успехе.

Если surface равен 0, это эквивалентно вызову doneCurrent().

Не вызывайте эту функцию из потока, отличного от того, в котором существует экземпляр QOpenGLContext. Если вы хотите использовать QOpenGLContext из другого потока, сначала убедитесь, что он не является текущим в текущем потоке, вызвав doneCurrent(), если необходимо. Затем вызовите moveToThread(otherThread) перед использованием его в другом потоке.

См. также functions() и doneCurrent().

QVariant QOpenGLContext::nativeHandle() const

Возвращает родной дескриптор контекста.

Эта функция предоставляет доступ к базовому родному контексту QOpenGLContext. Возвращаемая переменная содержит платформоспецифический тип значения. Эти классы можно найти в модуле QtPlatformHeaders.

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

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

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

[static] void *QOpenGLContext::openGLModuleHandle()

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

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

Библиотека может быть только GL, что означает, что функции интерфейса системы окон (например, EGL) могут находиться в другой, отдельной библиотеке.

Примечание: Для этой функции требуется, чтобы экземпляр QGuiApplication уже был создан.

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

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

[static] 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() снова перед началом нового кадра.

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

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