Класс QOpenGLFramebufferObject

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

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

Типы

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

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

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

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

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

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

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

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

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

Конструирует объект буфера фреймбуфера OpenGL и привязывает 2D-текстуру OpenGL к буферу с заданной шириной и высотой.

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

QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, 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, 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, const QOpenGLFramebufferObjectFormat &format)

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

Конструирует объект буфера фреймбуфера OpenGL заданного размера size, основываясь на предоставленном формате format.

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

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

Конструирует объект буфера фреймбуфера OpenGL заданной ширины и высоты, основываясь на предоставленном формате 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)

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

Создаёт и прикрепляет дополнительную текстуру или буфер рендеринга заданной ширины и высоты.

Если internalFormat не равно 0, оно задаёт внутренний формат текстуры или буфера рендеринга. В противном случае используется значение по умолчанию GL_RGBA или GL_RGBA8.

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

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, 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) ограничит область копирования, если он включён.

При использовании нескольких выходных изображений (render targets), readColorAttachmentIndex и drawColorAttachmentIndex указывают индекс цветного изображения (color attachment) в источниковом и целевом фреймбуферах соответственно.

Параметр 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(Attachment attachment)

Устанавливает элементы прикрепления (attachments) объекта фреймбуфера на attachment.

Может использоваться для освобождения или повторного прикрепления элементов глубины и трафарета (depth и stencil), если необходимо.

Примечание: Эта функция изменяет текущую привязку фреймбуфера.

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

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

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