Класс QOpenGLContext

Класс 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.

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

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

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

[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

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

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

Примечание: Реализация 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::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, например, в рамках нового кадра.