Класс QOpenGLFramebufferObject

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

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

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

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

Функции публичного доступа

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

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

Класс 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 в отдельном потоке.

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

enum QOpenGLFramebufferObject::Attachment

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

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

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()

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

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

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