Класс QOpenGLFramebufferObject

Класс QOpenGLFramebufferObject инкапсулирует объект буфера OpenGL. Подробнее...

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

Открытые типы

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

Static Public Members

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

Класс QOpenGLFramebufferObject encapsuliрует объект OpenGL framebuffer, определённый расширением GL_EXT_framebuffer_object. Он предоставляет поверхность для отрисовки с помощью QPainter при помощи QOpenGLPaintDevice или с помощью прямых вызовов OpenGL. Эта поверхность может быть связана и использована как обычная текстура в собственном коде отрисовки OpenGL. По умолчанию, класс QOpenGLFramebufferObject генерирует 2D текстуру OpenGL (используя целевой параметр GL_TEXTURE_2D), которая используется как целевая поверхность для рендеринга.

Важно: текущий контекст OpenGL должен быть установлен при создании QOpenGLFramebufferObject, иначе инициализация завершится ошибкой.

Создайте экземпляр QOpenGLFrameBufferObject с параметром CombinedDepthStencil прикрепления, если вы хотите, чтобы QPainter корректно отображался. Обратите внимание, что для того, чтобы примитивы отображались с антиалиасингом при рисовании с помощью QPainter, необходимо создать QOpenGLFramebufferObject с более чем одной выборкой на пиксель. Чтобы создать многообразный объект framebuffer, используйте один из конструкторов, принимающих параметр QOpenGLFramebufferObjectFormat, и установите свойство QOpenGLFramebufferObjectFormat::samples() в ненулевое значение.

Для многообразных буферов кадра создаётся буфер рендеринга цвета, в противном случае создаётся текстура с указанным целевым параметром текстуры. Буфер рендеринга цвета или текстура будут иметь указанный внутренний формат и будут привязаны к прикреплению GL_COLOR_ATTACHMENT0 в объекте буфера кадра.

Также поддерживаются несколько целей рендеринга, если реализация OpenGL поддерживает это. В этом случае будут присутствовать несколько текстур (или, в случае многообразного сэмплирования, буферов рендеринга), и каждая из них будет прикреплена к GL_COLOR_ATTACHMENT0, 1, 2, ...

Если вы хотите использовать объект буфера кадра с включённым многообразным сэмплированием в качестве текстуры, сначала необходимо скопировать данные из него в обычный объект буфера кадра с помощью QOpenGLContext::blitFramebuffer().

Можно рисовать в QOpenGLFramebufferObject, используя QPainter и QOpenGLPaintDevice, в отдельном потоке.

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

Перечисление QOpenGLFramebufferObject::Attachment

Этот тип перечисления используется для настройки буферов глубины и трафарета, прикреплённых к объекту буфера кадра при его создании.

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

[since 5.7] Перечисление QOpenGLFramebufferObject::FramebufferRestorePolicy

Этот тип перечисления используется для настройки поведения, связанного с восстановлением привязок буферов кадра при вызове blitFramebuffer().

Это перечисление было введено или изменено в Qt 5.7.

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

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

QOpenGLFramebufferObject::QOpenGLFramebufferObject(int width, int height, const QOpenGLFramebufferObjectFormat &format)

Создаёт объект буфера кадра OpenGL заданной ширины и высоты на основе предоставленного формата.

QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, const QOpenGLFramebufferObjectFormat &format)

Создаёт объект буфера кадра OpenGL заданного размера на основе предоставленного формата.

QOpenGLFramebufferObject::QOpenGLFramebufferObject(int width, int height, QOpenGLFramebufferObject::Attachment attachment, GLenum target = GL_TEXTURE_2D, GLenum internalFormat = 0)

Создаёт объект буфера кадра OpenGL и привязывает текстуру к буферу заданной ширины и высоты.

Параметр attachment описывает конфигурацию буфера глубины/трафарета, target — целевой параметр текстуры, а internalFormat — внутренний формат текстуры. Значение по умолчанию для целевого параметра текстуры — GL_TEXTURE_2D, а значение по умолчанию для внутреннего формата — GL_RGBA8 для настольного OpenGL и GL_RGBA для OpenGL/ES.

См. также size(), texture() и attachment().

QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, QOpenGLFramebufferObject::Attachment attachment, GLenum target = GL_TEXTURE_2D, GLenum internalFormat = 0)

Создаёт объект буфера кадра OpenGL и привязывает текстуру к буферу заданного размера.

Параметр attachment описывает конфигурацию буфера глубины/трафарета, target — целевой параметр текстуры, а internalFormat — внутренний формат текстуры. Значение по умолчанию для целевого параметра текстуры — GL_TEXTURE_2D, а значение по умолчанию для внутреннего формата — GL_RGBA8 для настольного OpenGL и GL_RGBA для OpenGL/ES.

См. также size(), texture() и attachment().

QOpenGLFramebufferObject::QOpenGLFramebufferObject(int width, int height, GLenum target = GL_TEXTURE_2D)

Создаёт объект буфера кадра OpenGL и привязывает 2D текстуру OpenGL к буферу заданной ширины и высоты.

См. также size() и texture().

QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, GLenum target = GL_TEXTURE_2D)

Создаёт объект буфера кадра OpenGL и привязывает 2D текстуру OpenGL к буферу заданного размера size. Текстура привязана к GL_COLOR_ATTACHMENT0 целевому параметру в объекте буфера кадра.

Параметр target используется для указания целевого параметра OpenGL текстуры. Значение по умолчанию для целевого параметра — GL_TEXTURE_2D. Имейте в виду, что для GL_TEXTURE_2D текстур ширина и высота должны быть степенями двойки (например, 256x512), если вы не используете OpenGL 2.0 или выше.

По умолчанию буферы глубины и трафарета не прикреплены. Это поведение можно изменить, используя перегруженные конструкторы.

Значение по умолчанию для внутреннего формата текстуры — GL_RGBA8 для настольного OpenGL и GL_RGBA для OpenGL/ES.

Важно, чтобы текущий контекст OpenGL был установлен при создании QOpenGLFramebufferObject, иначе инициализация завершится ошибкой.

См. также size(), texture() и attachment().

[virtual] QOpenGLFramebufferObject::~QOpenGLFramebufferObject()

Уничтожает объект буфера кадра и освобождает все выделенные ресурсы.

[since 5.6] void QOpenGLFramebufferObject::addColorAttachment(const QSize &size, GLenum internalFormat = 0)

Создаёт и прикрепляет дополнительную текстуру или буфер рендеринга шириной и высотой size.

Прикрепление всегда существует в GL_COLOR_ATTACHMENT0. Используйте эту функцию для настройки дополнительных прикреплений в GL_COLOR_ATTACHMENT1, GL_COLOR_ATTACHMENT2 и т. д.

Если internalFormat не равно 0, оно определяет внутренний формат текстуры или буфера рендеринга. В противном случае используется значение по умолчанию GL_RGBA или GL_RGBA8.

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

[since 5.6] void QOpenGLFramebufferObject::addColorAttachment(int width, int height, GLenum internalFormat = 0)

Это перегруженная функция.

Создаёт и прикрепляет дополнительную текстуру или буфер рендеринга размером width и height.

Если internalFormat не равно 0, оно определяет внутренний формат текстуры или буфера рендеринга. В противном случае используется значение по умолчанию GL_RGBA или GL_RGBA8.

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

QOpenGLFramebufferObject::Attachment QOpenGLFramebufferObject::attachment() const

Возвращает состояние буферов глубины и трафарета, присоединённых к этому объекту фреймбуфера.

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

bool QOpenGLFramebufferObject::bind()

Переключает отрисовку с используемого по умолчанию фреймбуфера системы окон на этот объект фреймбуфера. Возвращает true при успехе, false в противном случае.

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

[static] bool QOpenGLFramebufferObject::bindDefault()

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

См. также bind() и release().

[static, since 5.7] void QOpenGLFramebufferObject::blitFramebuffer(QOpenGLFramebufferObject *target, const QRect &targetRect, QOpenGLFramebufferObject *source, const QRect &sourceRect, GLbitfield buffers, GLenum filter, int readColorAttachmentIndex, int drawColorAttachmentIndex, QOpenGLFramebufferObject::FramebufferRestorePolicy restorePolicy)

Копирует область sourceRect из фреймбуфера source в область targetRect фреймбуфера target.

Если source или target равны 0, используется фреймбуфер по умолчанию вместо объекта фреймбуфера в качестве источника или цели соответственно.

Функция не будет выполняться, если hasOpenGLFramebufferBlit() возвращает false.

Параметр buffers должен быть маской, состоящей из любого сочетания GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, и GL_STENCIL_BUFFER_BIT. Любой тип буфера, который отсутствует как в источнике, так и в целевых буферах, игнорируется.

Прямоугольники sourceRect и targetRect могут иметь разные размеры; в этом случае buffers не должен содержать GL_DEPTH_BUFFER_BIT или GL_STENCIL_BUFFER_BIT. Параметр filter должен быть установлен в GL_LINEAR или GL_NEAREST, и определяет, следует ли использовать линейную или ближайшую интерполяцию при масштабировании.

Если source равно target, копия выполняется внутри одного и того же буфера. Результаты не определены, если прямоугольники источника и цели перекрываются и имеют разные размеры. Размеры также должны быть одинаковыми, если какой-либо из объектов фреймбуфера является многообразным фреймбуфером.

При использовании нескольких целевых поверхностей рендеринга, readColorAttachmentIndex и drawColorAttachmentIndex указывают индекс цветовых прикреплений в фреймбуферах источника и назначения.

Параметр restorePolicy определяет, должен ли фреймбуфер, который был привязан до вызова этой функции, быть восстановлен, или если должен быть привязан фреймбуфер по умолчанию перед возвратом, или если вызывающая сторона отвечает за отслеживание и настройку привязанного фреймбуфера. Восстановление предыдущего фреймбуфера может быть относительно дорогостоящим из-за вызова glGetIntegerv, который на некоторых драйверах OpenGL может означать задержку конвейера.

Функция была добавлена в Qt 5.7.

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

[static] void QOpenGLFramebufferObject::blitFramebuffer(QOpenGLFramebufferObject *target, const QRect &targetRect, QOpenGLFramebufferObject *source, const QRect &sourceRect, GLbitfield buffers, GLenum filter, int readColorAttachmentIndex, int drawColorAttachmentIndex)

Это перегруженная функция.

Удобная перегрузка для копирования между двумя объектами фреймбуфера и восстановления предыдущей привязки фреймбуфера. Эквивалентно вызову blitFramebuffer(target, targetRect, source, sourceRect, buffers, filter, readColorAttachmentIndex, drawColorAttachmentIndex, RestoreFrameBufferBinding).

[static] void QOpenGLFramebufferObject::blitFramebuffer(QOpenGLFramebufferObject *target, const QRect &targetRect, QOpenGLFramebufferObject *source, const QRect &sourceRect, GLbitfield buffers = GL_COLOR_BUFFER_BIT, GLenum filter = GL_NEAREST)

Это перегруженная функция.

* Удобная перегрузка для копирования между двумя объектами фреймбуфера.

[static] void QOpenGLFramebufferObject::blitFramebuffer(QOpenGLFramebufferObject *target, QOpenGLFramebufferObject *source, GLbitfield buffers = GL_COLOR_BUFFER_BIT, GLenum filter = GL_NEAREST)

Это перегруженная функция.

Удобная перегрузка для копирования между двумя объектами фреймбуфера.

QOpenGLFramebufferObjectFormat QOpenGLFramebufferObject::format() const

Возвращает формат этого объекта фреймбуфера.

GLuint QOpenGLFramebufferObject::handle() const

Возвращает дескриптор OpenGL объекта фреймбуфера для этого объекта фреймбуфера (возвращаемый функцией glGenFrameBuffersEXT()). Этот дескриптор можно использовать для присоединения новых изображений или буферов к фреймбуферу. Пользователь несёт ответственность за очистку и уничтожение этих объектов.

[static] bool QOpenGLFramebufferObject::hasOpenGLFramebufferBlit()

Возвращает true если расширение OpenGL GL_EXT_framebuffer_blit присутствует в этой системе; в противном случае возвращает false.

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

[static] bool QOpenGLFramebufferObject::hasOpenGLFramebufferObjects()

Возвращает true если расширение OpenGL GL_EXT_framebuffer_object присутствует в этой системе; в противном случае возвращает false.

int QOpenGLFramebufferObject::height() const

Возвращает высоту прикреплений фреймбуфера.

bool QOpenGLFramebufferObject::isBound() const

Возвращает true если объект фреймбуфера в настоящее время привязан к текущему контексту, в противном случае возвращается false.

bool QOpenGLFramebufferObject::isValid() const

Возвращает true если объект фреймбуфера действителен.

Фреймбуфер может стать недействительным, если процесс инициализации завершается неудачно, пользователь присоединяет недействительный буфер к объекту фреймбуфера или задаёт размер текстуры с шириной/высотой, не являющейся степенью двойки, если целевой параметр текстуры равен GL_TEXTURE_2D. Ограничение на нестепени двойки не применяется, если версия OpenGL 2.0 или выше, или если расширение GL_ARB_texture_non_power_of_two присутствует.

Фреймбуфер также может стать недействительным, если QOpenGLContext, в котором был создан фреймбуфер, уничтожен, и нет других общих контекстов, которые могут принять на себя владение фреймбуфером.

bool QOpenGLFramebufferObject::release()

Переключает отрисовку обратно к используемому по умолчанию фреймбуферу системы окон. Возвращает true при успехе, false в противном случае.

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

void QOpenGLFramebufferObject::setAttachment(QOpenGLFramebufferObject::Attachment attachment)

Устанавливает прикрепления объекта фреймбуфера в attachment.

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

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

QSize QOpenGLFramebufferObject::size() const

Возвращает размер цветовых и прикреплений глубины/трафарета, присоединённых к этому объекту фреймбуфера.

[since 5.6] QList<QSize> QOpenGLFramebufferObject::sizes() const

Возвращает размеры всех цветовых прикреплений, присоединённых к этому объекту фреймбуфера.

Функция была добавлена в Qt 5.6.

[since 5.3] GLuint QOpenGLFramebufferObject::takeTexture()

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

Если объект буфера кадра в настоящее время связан, будет неявно выполнен release(). При следующем вызове bind() будет создана новая текстура.

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

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

См. также texture(), bind() и release().

[since 5.6] GLuint QOpenGLFramebufferObject::takeTexture(int colorAttachmentIndex)

Это перегруженная функция.

Возвращает идентификатор текстуры, прикреплённой к цветному приложению с индексом colorAttachmentIndex этого объекта буфера кадра. Владение текстурой передаётся вызывающей стороне.

Когда colorAttachmentIndex равно 0, поведение идентично варианту функции без параметров.

Если объект буфера кадра в настоящее время связан, будет неявно выполнен release(). При следующем вызове bind() будет создана новая текстура.

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

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

GLuint QOpenGLFramebufferObject::texture() const

Возвращает идентификатор текстуры, прикреплённой в качестве целевого объекта рендеринга по умолчанию в этом объекте буфера кадра. Этот идентификатор текстуры может быть связан как обычная текстура в вашем собственном OpenGL-коде.

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

Когда прикреплено несколько текстур, возвращаемое значение — это идентификатор первой.

См. также takeTexture() и textures().

[since 5.6] QList<GLuint> QOpenGLFramebufferObject::textures() const

Возвращает идентификатор всех прикреплённых текстур.

Если используется объект буфера кадра с многократной выборкой, возвращается пустой список.

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

См. также takeTexture() и texture().

QImage QOpenGLFramebufferObject::toImage(bool flipped = true) const

Возвращает содержимое этого объекта буфера кадра в виде QImage.

Если flipped равно true, изображение переворачивается с координат OpenGL на растровые координаты. Если используется вместе с QOpenGLPaintDevice, flipped должно быть противоположно значению QOpenGLPaintDevice::paintFlipped().

Возвращаемое изображение имеет формат premultiplied ARGB32 или RGB32. Последний используется только когда internalTextureFormat() установлено в GL_RGB. С Qt 5.2 функция будет использовать премультиплицированные RGBA8888 или RGBx8888 при чтении в (A)RGB32, не поддерживаемое, включая OpenGL ES. С Qt 5.4 возвращается изображение A2BGR30, если внутренний формат RGB10_A2, а с Qt 5.12 - RGBA64, если внутренний формат RGBA16.

Если рендеринг в буфере кадра не производился с учётом премультиплицированного альфа-канала, создайте обёртку QImage с не-премультиплицированным форматом. Это необходимо перед выполнением операций, таких как QImage::save(), так как в противном случае данные изображения будут демультиплицированы, даже если они не были премультиплицированы изначально. Для создания такой обёртки без копирования пиксельных данных сделайте следующее:

QImage fboImage(fbo.toImage());
QImage image(fboImage.constBits(), fboImage.width(), fboImage.height(), QImage::Format_ARGB32);

Для объектов буфера кадра с многократной выборкой образцы разрешаются с использованием расширения GL_EXT_framebuffer_blit. Если расширение недоступно, содержимое возвращаемого изображения не определено.

Для однократной выборки содержимое извлекается через glReadPixels. Это потенциально дорогостоящая и неэффективная операция. Поэтому рекомендуется использовать эту функцию как можно реже.

См. также QOpenGLPaintDevice::paintFlipped().

[since 5.6] QImage QOpenGLFramebufferObject::toImage(bool flipped, int colorAttachmentIndex) const

Это перегруженная функция.

Возвращает содержимое цветного приложения с индексом colorAttachmentIndex этого объекта буфера кадра в виде QImage. Этот метод переворачивает изображение с координат OpenGL на растровые координаты, когда flipped установлено в true.

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

int QOpenGLFramebufferObject::width() const

Возвращает ширину прикреплений объекта буфера кадра.