Класс QOpenGLFramebufferObject

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

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

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

Открытые функции

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

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

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

Класс 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(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().

QOpenGLFramebufferObject::QOpenGLFramebufferObject(int width, int height, GLenum target = GL_TEXTURE_2D)

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

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

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, 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, const QOpenGLFramebufferObjectFormat &format)

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

QOpenGLFramebufferObject::QOpenGLFramebufferObject(int width, int height, const QOpenGLFramebufferObjectFormat &format)

Создаёт объект OpenGL буфера кадра заданной ширины width и высоты height, основанного на предоставленном формате format.

[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 возвращается изображение 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

Возвращает ширину приложений фреймбуфера.