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

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

Примечание: Если включена проверка отсечения, она ограничит область копирования.

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

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

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

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

Возвращаемое изображение имеет формат предварительно умноженного ARGB32 или RGB32. Последний используется только тогда, когда internalTextureFormat() установлено в GL_RGB. Начиная с Qt 5.2, функция переходит к предварительно умноженному RGBA8888 или RGBx8888 при чтении в (A)RGB32, что включает OpenGL ES. Начиная с Qt 5.4, если внутренний формат — RGB10_A2, возвращается изображение A2BGR30, а с 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

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