Класс QOpenGLFramebufferObject

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

Этот класс был введён в Qt 5.0.

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

Публичные типы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

перечисление 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.

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

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

[virtual] QOpenGLFramebufferObject::~QOpenGLFramebufferObject()

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

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.

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] 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, копирование выполняется внутри одного и того же буфера. Результаты неопределены, если прямоугольники источника и назначения перекрываются и имеют разные размеры. Размеры также должны быть одинаковыми, если любой из объектов буфера кадра является многообразным.

Примечание: Режим сдвига ножниц (scissor test) будет ограничивать область копирования, если он включен.

При использовании нескольких буферов рендеринга, 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

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

QVector<QSize> QOpenGLFramebufferObject::sizes() const

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

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

GLuint QOpenGLFramebufferObject::takeTexture()

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

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

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

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

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

GLuint QOpenGLFramebufferObject::takeTexture(int colorAttachmentIndex)

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

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

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

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

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

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

GLuint QOpenGLFramebufferObject::texture() const

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

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

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

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

QVector<GLuint> QOpenGLFramebufferObject::textures() const

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

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

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

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

QImage QOpenGLFramebufferObject::toImage(bool flipped) const

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

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

Возвращаемое изображение имеет формат premultiplied ARGB32 или RGB32. Последний используется только тогда, когда internalTextureFormat() установлено в GL_RGB. С Qt 5.2 функция будет использовать по умолчанию premultiplied 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().

QImage QOpenGLFramebufferObject::toImage() const

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

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

QImage QOpenGLFramebufferObject::toImage(bool flipped, int colorAttachmentIndex) const

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

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

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

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

int QOpenGLFramebufferObject::width() const

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