QOpenGLFramebufferObject Class

成员函数文档

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

构造一个 OpenGL 帧缓冲器对象，并将一个尺寸为size 的 2D OpenGL 纹理绑定到缓冲器中。纹理绑定到帧缓冲器对象中的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)

这是一个重载函数。

方便重载，用于在两个帧缓冲对象之间进行混合。

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

如果本系统中存在 OpenGLGL_EXT_framebuffer_blit 扩展，则返回true ；否则返回false 。

另请参阅 blitFramebuffer() 。

[static] bool QOpenGLFramebufferObject::hasOpenGLFramebufferObjects()

如果本系统中存在 OpenGLGL_EXT_framebuffer_object 扩展，则返回true ；否则返回false 。

int QOpenGLFramebufferObject::height() const

返回帧缓冲器对象附件的高度。

bool QOpenGLFramebufferObject::isBound() const

如果帧缓冲器对象当前与当前上下文绑定，则返回true ，否则返回 false。

bool QOpenGLFramebufferObject::isValid() const

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

如果初始化过程失败、用户向 framebuffer 对象附加了无效的缓冲区，或者在纹理目标为GL_TEXTURE_2D 的情况下指定了非二乘以二的宽度/高度作为纹理大小，则 framebuffer 可能变为无效。如果 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 的形式返回该 framebuffer 对象的内容。

如果flipped 为 true，图像将从 OpenGL 坐标翻转为光栅坐标。如果与QOpenGLPaintDevice 一起使用，flipped 应与QOpenGLPaintDevice::paintFlipped() 的值相反。

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

如果在帧缓冲区中进行渲染时没有考虑到预乘法 alpha，则应创建一个非预乘法格式的包装器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

这是一个重载函数。

将此 framebuffer 对象索引colorAttachmentIndex 的颜色附件内容作为QImage 返回。当flipped 设置为true 时，此方法会将图像从 OpenGL 坐标翻转为光栅坐标。

int QOpenGLFramebufferObject::width() const

返回帧缓冲器对象附件的宽度。