Класс QOffscreenSurface

Класс QOffscreenSurface представляет собой внеэкранную поверхность в базовой платформе. Подробнее...

Этот класс был представлен в Qt 5.1.

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

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

Переопределённые открытые функции

Сигналы

Подробное описание

QOffscreenSurface предназначен для использования с QOpenGLContext, чтобы позволить рендеринг с OpenGL в произвольном потоке без необходимости создания QWindow.

Несмотря на то, что поверхность, как правило, рендерится, пиксели поверхности недоступны. QOffscreenSurface следует использовать только для создания ресурсов OpenGL, таких как текстуры или объекты фреймбуфера.

Приложение обычно использует QOffscreenSurface для выполнения некоторых длительных задач в отдельном потоке, чтобы избежать блокирования основного потока рендеринга. Ресурсы, созданные в контексте QOffscreenSurface, могут быть совмещены с основным контекстом OpenGL. Некоторые распространённые случаи использования включают асинхронную загрузку текстур или рендеринг в QOpenGLFramebufferObject.

Реализация внеэкранной поверхности зависит от базовой платформы, но обычно использует буфер пикселей (pbuffer). Если платформа не реализует или не поддерживает внеэкранные поверхности, QOffscreenSurface будет использовать невидимый QWindow внутри.

Примечание: Из-за того, что QOffscreenSurface поддерживается QWindow на некоторых платформах, приложения, совместимые с различными платформами, должны убедиться, что create() вызывается только в главном (GUI) потоке. Затем QOffscreenSurface можно безопасно использовать с makeCurrent() в других потоках, но инициализация и уничтожение всегда должны выполняться в главном (GUI) потоке.

Примечание: Чтобы создать внеэкранную поверхность, которая гарантированно будет совместима с заданным контекстом и окном, убедитесь, что формат установлен на фактический формат контекста или окна, то есть QSurfaceFormat, возвращаемый из QOpenGLContext::format() или QWindow::format() после создания контекста или окна. Передача формата, возвращаемого из QWindow::requestedFormat() в setFormat(), может привести к несовместимой внеэкранной поверхности, так как интерфейс базовой системы окон может предложить разные конфигурации для оконных и pbuffer-поверхностей.

Примечание: Некоторые платформы могут использовать расширение безповерхностного контекста (например, EGL_KHR_surfaceless_context), если оно доступно. В этом случае не будет никакой базовой нативной поверхности. Для случаев использования QOffscreenSurface (рендеринг в FBO, загрузка текстур) это не проблема.

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

QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen = nullptr)

Создаёт внеэкранную поверхность для targetScreen.

Базовая поверхность платформы не создаётся до тех пор, пока не будет вызван create().

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

QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen, QObject *parent)

Создаёт внеэкранную поверхность для targetScreen с заданным parent.

Базовая поверхность платформы не создаётся до тех пор, пока не будет вызван create().

Эта функция была представлена в Qt 5.10.

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

[signal] void QOffscreenSurface::screenChanged(QScreen *screen)

Этот сигнал генерируется, когда экран внеэкранной поверхности screen изменяется, либо явно с помощью setScreen(), либо автоматически, когда экран окна удалён.

[virtual] QOffscreenSurface::~QOffscreenSurface()

Уничтожает внеэкранную поверхность.

void QOffscreenSurface::create()

Выделяет ресурсы платформы, связанные с внеэкранной поверхностью.

В этот момент формат поверхности, заданный с помощью setFormat(), разрешается в фактическую нативную поверхность.

Вызовите destroy(), чтобы освободить ресурсы платформы, если это необходимо.

Примечание: Некоторые платформы требуют, чтобы эта функция вызывалась в главном (GUI) потоке.

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

void QOffscreenSurface::destroy()

Освобождает нативные ресурсы платформы, связанные с этой внеэкранной поверхностью.

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

[override virtual] QSurfaceFormat QOffscreenSurface::format() const

Реализует: QSurface::format() const.

Возвращает фактический формат этой внеэкранной поверхности.

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

См. также setFormat(), create() и requestedFormat().

bool QOffscreenSurface::isValid() const

Возвращает true, если эта внеэкранная поверхность допустима; в противном случае возвращает false.

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

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

void *QOffscreenSurface::nativeHandle() const

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

Эта функция была представлена в Qt 5.9.

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

QSurfaceFormat QOffscreenSurface::requestedFormat() const

Возвращает запрошенный формат поверхности этой внеэкранной поверхности.

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

Это значение установлено с помощью setFormat().

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

QScreen *QOffscreenSurface::screen() const

Возвращает экран, к которому подключена поверхность offscreen.

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

void QOffscreenSurface::setFormat(const QSurfaceFormat &format)

Устанавливает формат поверхности offscreen.

Формат поверхности будет разрешен в функции create(). Вызов этой функции после create() не приведет к повторному разрешению формата поверхности родной поверхности.

См. также format(), create() и destroy().

void QOffscreenSurface::setNativeHandle(void *handle)

Устанавливает родной обработчик, к которому подключена поверхность offscreen, в handle.

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

Примечание: Интерпретация родного обработчика зависит от платформы. Только некоторые платформы поддерживают принятие родных обработчиков поверхностей offscreen, и платформы, которые не реализуют эту поддержку, проигнорируют обработчик.

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

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

void QOffscreenSurface::setScreen(QScreen *newScreen)

Устанавливает экран, к которому подключена поверхность offscreen.

Если поверхность offscreen уже создана, она будет пересоздана на newScreen.

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

[override virtual] QSize QOffscreenSurface::size() const

Переопределяет: QSurface::size() const.

Возвращает размер поверхности offscreen.

[override virtual] QSurface::SurfaceType QOffscreenSurface::surfaceType() const

Переопределяет: QSurface::surfaceType() const.

Возвращает тип поверхности offscreen.

Тип поверхности offscreen всегда QSurface::OpenGLSurface.