Класс QOpenGLFramebufferObject

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

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

Типы public

Функции public

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

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

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

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

Создайте экземпляр QOpenGLFrameBufferObject с прикреплением CombinedDepthStencil, если вы хотите, чтобы QPainter правильно отображался. Обратите внимание, что для того, чтобы примитивы были сглажены при отрисовке с помощью QPainter, вам необходимо создать QOpenGLFramebufferObject с более чем одним образцом на пиксель. Для создания многообразного объекта буфера кадра вы должны использовать один из конструкторов, принимающих параметр 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 заданной ширины width и высоты height на основе предоставленного format.

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

Конструирует объект буфера кадра OpenGL заданного размера size на основе предоставленного format.

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

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

Параметр 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 и привязывает текстуру к буферу заданного размера size.

Параметр 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 к буферу заданной ширины width и высоты height.

См. также 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.

Примечание: Эта функция работает только при поддержке нескольких целей рендеринга реализацией OpenGL. В противном случае функция не добавит дополнительных прикреплений цвета. Используйте QOpenGLFunctions::hasOpenGLFeature() с QOpenGLFunctions::MultipleRenderTargets во время выполнения, чтобы проверить поддержку MRT.

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

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

Эта функция была добавлена в 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 в противном случае.

Примечание: Если был вызван takeTexture(), создается новая текстура и она ассоциируется с объектом буфера. Это потенциально дорого и изменяет состояние контекста (текущая привязанная текстура).

См. также 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()

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

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

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

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

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

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

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

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

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

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

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

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

GLuint QOpenGLFramebufferObject::texture() const

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

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

При наличии нескольких прикреплённых текстур, возвращаемое значение — идентификатор первой из них.

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

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

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

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

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

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

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

Возвращает содержимое этого объекта framebuffer в виде 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.

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

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

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

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

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

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

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

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

Примечание: Эта перегрузка полностью функциональна только при поддержке нескольких целевых объектов рендеринга реализацией OpenGL. В противном случае будет настроен только один цветовой вход.

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

int QOpenGLFramebufferObject::width() const

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