Класс QOpenGLContext

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

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

Типы

Открытые функции

• 32 открытых функции унаследованные от QObject

Сигналы

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

Статические открытые члены

• 11 статических открытых членов унаследованных от 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.

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

enum 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 может привести к контексту с ядром профиля 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.

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

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

Возвращает значение, указывающее, является ли контекст валидным (т. е. успешно создан).

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

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

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

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

[static] void *QOpenGLContext::openGLModuleHandle()

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

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

Библиотека может быть только 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)

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

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

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

void QOpenGLContext::setNativeHandle(const QVariant &handle)

Устанавливает нативные идентификаторы для данного контекста. При вызове create() и установке нативного идентификатора настройки конфигурации, такие как format(), игнорируются, так как данный QOpenGLContext будет оборачивать уже созданный нативный контекст вместо создания нового с нуля.

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

При вызове 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().

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

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 сохраняет владение объектом. Это позволяет кэшировать и совместно использовать объект.