QOpenGLFramebufferObject Class

成员函数文档

[explicit] QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, GLenum target = GL_TEXTURE_2D)

创建一个 OpenGL 帧缓冲区对象，并将一个 2D OpenGL 纹理绑定到大小为size 的缓冲区上。该纹理被绑定到帧缓冲区对象中的GL_COLOR_ATTACHMENT0 目标上。

参数target 用于指定 OpenGL 纹理目标。默认目标为GL_TEXTURE_2D 。请注意，除非使用 OpenGL 2.0 或更高版本，否则GL_TEXTURE_2D 纹理的宽度和高度必须为 2 的幂（例如 256x512）。

默认情况下，不附加深度缓冲区和模板缓冲区。可通过使用其中一个重载的构造函数来切换此行为。

默认的内部纹理格式为：桌面版 OpenGL 采用GL_RGBA8 ，OpenGL/ES 采用GL_RGBA 。

在创建 QOpenGLFramebufferObject 时，务必已设置有效的 OpenGL 上下文，否则初始化将失败。

另请参阅 size()、texture() 和attachment()。

QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, const QOpenGLFramebufferObjectFormat &format)

根据提供的format ，基于给定的size 构建一个OpenGL帧缓冲区对象。

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

创建一个 OpenGL 帧缓冲区对象，并将一个 2D OpenGL 纹理绑定到给定的width 和height 的缓冲区上。

另请参阅 size() 和texture()。

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

根据提供的format ，基于给定的width 和height 构建一个OpenGL帧缓冲区对象。

QOpenGLFramebufferObject::QOpenGLFramebufferObject(const QSize &size, QOpenGLFramebufferObject::Attachment attachment, GLenum target = GL_TEXTURE_2D, GLenum internalFormat = 0)

创建一个 OpenGL 帧缓冲区对象，并将纹理绑定到给定size 的缓冲区上。

attachment 参数描述了深度/模板缓冲区的配置，target 描述了纹理目标，internalFormat 描述了内部纹理格式。默认的纹理目标为GL_TEXTURE_2D ，而默认的内部格式对于桌面版OpenGL为GL_RGBA8 ，对于OpenGL/ES为GL_RGBA 。

另请参阅 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 ，而默认内部格式对于桌面版OpenGL为GL_RGBA8 ，对于OpenGL/ES为GL_RGBA 。

另请参阅 size()、texture() 和attachment()。

[virtual noexcept] 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。

void QOpenGLFramebufferObject::addColorAttachment(int width, int height, GLenum internalFormat = 0)

创建并附加一个额外纹理或渲染缓冲区，其大小分别为width 和height 。

当internalFormat 与0 不相同时，该参数指定纹理或渲染缓冲区的内部格式。否则，将使用默认值 GL_RGBA 或 GL_RGBA8。

QOpenGLFramebufferObject::Attachment QOpenGLFramebufferObject::attachment() const

返回与该帧缓冲区对象关联的深度缓冲区和模板缓冲区的状态。

另请参阅 setAttachment()。

bool QOpenGLFramebufferObject::bind()

将渲染从默认的、由窗口系统提供的帧缓冲区切换到此帧缓冲区对象。成功时返回true ，否则返回false。

另请参阅 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)

将source 帧缓冲区对象中sourceRect 矩形内的内容复制到target 帧缓冲区对象中targetRect 矩形内。

如果source 或target 的值为 0，则将分别使用默认帧缓冲区代替帧缓冲区对象作为源或目标。

除非hasOpenGLFramebufferBlit() 返回 true，否则此函数将不起作用。

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 驱动程序中这可能会导致管道停滞。

另请参阅 hasOpenGLFramebufferBlit()。

[static] void QOpenGLFramebufferObject::blitFramebuffer(QOpenGLFramebufferObject *target, QOpenGLFramebufferObject *source, GLbitfield buffers = GL_COLOR_BUFFER_BIT, GLenum filter = GL_NEAREST)

用于在两个帧缓冲区对象之间进行位图复制（blit）的便捷方法。

[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, 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)。

QOpenGLFramebufferObjectFormat QOpenGLFramebufferObject::format() const

返回此帧缓冲区对象的格式。

GLuint QOpenGLFramebufferObject::handle() const

返回此帧缓冲区对象的 OpenGL 帧缓冲区对象句柄（由glGenFrameBuffersEXT() 函数返回）。该句柄可用于将新的图像或缓冲区附加到帧缓冲区。用户有责任清理并销毁这些对象。

[static] bool QOpenGLFramebufferObject::hasOpenGLFramebufferBlit()

如果该系统上存在 OpenGL 的 `GL_EXT_framebuffer_blit ` 扩展，则返回 `true `；否则返回 `false`。

另请参阅 blitFramebuffer()。

[static] bool QOpenGLFramebufferObject::hasOpenGLFramebufferObjects()

如果该系统上存在 OpenGL 的GL_EXT_framebuffer_object 扩展，则返回true ；否则返回false 。

int QOpenGLFramebufferObject::height() const

返回帧缓冲区对象附加项的高度。

bool QOpenGLFramebufferObject::isBound() const

如果帧缓冲区对象当前已绑定到当前上下文，则返回true ；否则返回 false。

bool QOpenGLFramebufferObject::isValid() const

如果帧缓冲区对象有效，则返回true 。

如果初始化过程失败、用户将无效的缓冲区附加到帧缓冲区对象上，或者当纹理目标为GL_TEXTURE_2D 时指定了非 2 的幂的宽度/高度作为纹理大小，则帧缓冲区可能会失效。 如果 OpenGL 版本为 2.0 或更高，或者存在 GL_ARB_texture_non_power_of_two 扩展，则不适用“非 2 的幂”的限制。

如果创建该帧缓冲区的QOpenGLContext 被销毁，且没有其他共享上下文能够接管该帧缓冲区的所有权，则该帧缓冲区也会失效。

bool QOpenGLFramebufferObject::release()

将渲染切换回默认设置，即由窗口系统提供的帧缓冲区。成功时返回true ，否则返回false。

另请参阅 bind()。

void QOpenGLFramebufferObject::setAttachment(QOpenGLFramebufferObject::Attachment attachment)

将帧缓冲区对象的连接设置为attachment 。

这可用于根据需要释放或重新附加深度缓冲区和模板缓冲区。

另请参阅 attachment()。

QSize QOpenGLFramebufferObject::size() const

返回附加到该帧缓冲区对象上的颜色和深度/模板附件的大小。

QList<QSize> QOpenGLFramebufferObject::sizes() const

返回附加到此帧缓冲区对象上的所有颜色附件的大小。

GLuint QOpenGLFramebufferObject::takeTexture()

返回与该帧缓冲区对象关联的纹理的纹理 ID。该纹理的所有权将转移给调用方。

如果帧缓冲区对象当前已被绑定，则会隐式执行release()。在下一次调用bind()时，将创建一个新的纹理。

如果使用的是多采样帧缓冲区对象，则不存在纹理，且此函数的返回值将无效。同样，不完整的帧缓冲区对象也会返回 0。

另请参阅 texture()、bind() 和release()。

GLuint QOpenGLFramebufferObject::takeTexture(int colorAttachmentIndex)

返回此帧缓冲区对象中索引为colorAttachmentIndex 的颜色附件所关联的纹理的纹理ID。该纹理的所有权将转移给调用方。

当 `colorAttachmentIndex ` 为 `0` 时，其行为与该函数的无参数版本完全相同。

如果帧缓冲区对象当前已被绑定，则会隐式执行release()。在下一次调用bind()时，将创建一个新的纹理。

如果使用的是多采样帧缓冲区对象，则不存在纹理，且该函数的返回值将无效。同样，不完整的帧缓冲区对象也会返回 0。

GLuint QOpenGLFramebufferObject::texture() const

返回作为此帧缓冲区对象默认渲染目标附加的纹理的纹理 ID。该纹理 ID 可在您自己的 OpenGL 代码中作为普通纹理进行绑定。

如果使用的是多采样帧缓冲区对象，则此函数返回的值将无效。

当连接了多个纹理时，返回值是第一个纹理的 ID。

另请参阅 takeTexture() 和textures()。

QList<GLuint> QOpenGLFramebufferObject::textures() const

返回所有已附加纹理的纹理 ID。

如果使用的是多采样帧缓冲区对象，则返回一个空向量。

另请参阅 takeTexture() 和texture()。

QImage QOpenGLFramebufferObject::toImage(bool flipped = true) const

将此帧缓冲区对象的内容作为QImage 返回。

如果 `flipped ` 为真，则图像会从 OpenGL 坐标系转换为光栅坐标系。若与 `QOpenGLPaintDevice` 配合使用，则 `flipped ` 的值应与 `QOpenGLPaintDevice::paintFlipped()` 的值相反。

返回的图像格式为预乘的 ARGB32 或 RGB32。 后者仅在`internalTextureFormat()`设置为GL_RGB 时使用。自 Qt 5.2 起，当不支持读取 (A)RGB32 时（包括 OpenGL ES），该函数将回退到预乘 RGBA8888 或 RGBx8888 格式。 自 Qt 5.4 起，若内部格式为 RGB10_A2，则返回 A2BGR30 图像；自 Qt 5.12 起，若内部格式为 RGBA16，则返回 RGBA64 图像。

如果帧缓冲区中的渲染未考虑预乘透明度，请创建一个采用非预乘格式的包装器 `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(bool flipped, int colorAttachmentIndex) const

返回此帧缓冲区对象中索引为colorAttachmentIndex 的颜色附件的内容，并将其作为QImage 返回。当flipped 设置为true 时，此方法会将图像从OpenGL坐标转换为光栅坐标。

int QOpenGLFramebufferObject::width() const

返回帧缓冲区对象附加项的宽度。