Класс QOpenGLFramebufferObject

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

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

Типы публичного доступа

Публичные функции

Статические публичные члены

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

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

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

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

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

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

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

Возможно отрисовка в QOpenGLFramebufferObject с помощью QPainter и QOpenGLPaintDevice в отдельном потоке.

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

enum QOpenGLFramebufferObject::Attachment

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

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

[since 5.7] enum 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.

Примечание: Эта функция работает только при поддержке нескольких целей рендеринга реализацией 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.