QQuickFramebufferObject Class
QQuickFramebufferObject 类是一个便捷类，用于将使用帧缓冲区对象（FBO）的 OpenGL 渲染与Qt Quick 集成。更多内容...
| 头文件： | #include <QQuickFramebufferObject> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake： | QT += quick |
| 继承自： | QQuickItem |
公共类型
| class | Renderer |
属性
- mirrorVertically : bool
- textureFollowsItemSize : bool
公共函数
| QQuickFramebufferObject(QQuickItem *parent = nullptr) | |
| virtual QQuickFramebufferObject::Renderer * | createRenderer() const = 0 |
| bool | mirrorVertically() const |
| void | setMirrorVertically(bool enable) |
| void | setTextureFollowsItemSize(bool follows) |
| bool | textureFollowsItemSize() const |
重新实现的公共函数
| virtual bool | isTextureProvider() const override |
| virtual void | releaseResources() override |
| virtual QSGTextureProvider * | textureProvider() const override |
信号
| void | mirrorVerticallyChanged(bool) |
| void | textureFollowsItemSizeChanged(bool) |
详细说明
警告：此类 仅在 Qt Quick 通过OpenGL进行渲染时才有效。它与其他图形API（如Vulkan或Metal）不兼容。应将其视为一个遗留类，其存在仅是为了确保Qt 5应用程序在绑定到OpenGL的情况下能够正常运行，且不破坏源代码兼容性。
在大多数平台上，渲染将在专用线程上进行。因此，QQuickFramebufferObject 类强制要求项目实现与 FBO 渲染之间保持严格分离。 所有项目逻辑（例如属性以及 QML 所需的 UI 相关辅助函数）都应位于 QQuickFramebufferObject 类的子类中。所有与渲染相关的内容必须位于QQuickFramebufferObject::Renderer 类中。
为避免两个线程之间的竞争条件和读写问题，渲染器与项绝不能读写共享变量，这一点至关重要。项与渲染器之间的通信应主要通过QQuickFramebufferObject::Renderer::synchronize() 函数进行。该函数将在渲染线程上被调用，而此时 GUI 线程会被阻塞。
也可以使用队列连接或事件来实现项与渲染器之间的通信。
渲染器（Renderer）和 FBO 均由系统内部进行内存管理。
要将内容渲染到 FBO 中，用户应继承 Renderer 类并重写其Renderer::render() 函数。createRenderer() 会返回该 Renderer 子类。
FBO 的大小默认会适应项的大小。如果希望使用固定大小，请将 `textureFollowsItemSize ` 设置为 `false `，并从 `QQuickFramebufferObject::Renderer::createFramebufferObject()` 中返回您选择的纹理。
从 Qt 5.4 开始，QQuickFramebufferObject 类即为texture provider ，可直接用于ShaderEffects 以及其他使用纹理提供程序的类中。
另请参阅 “场景图”和“渲染”。
属性文档
mirrorVertically : bool
此属性控制在绘制时是否应将 FBO 内容的大小进行垂直镜像。这使得可以轻松集成不符合标准预期的第三方渲染代码。
默认值为false 。
访问函数：
| bool | mirrorVertically() const |
| void | setMirrorVertically(bool enable) |
通知信号：
| void | mirrorVerticallyChanged(bool) |
textureFollowsItemSize : bool
该属性控制FBO纹理的大小是否应遵循QQuickFramebufferObject 项的尺寸。当该属性为false时，FBO将在首次显示时创建一次。如果设置为true，则每当该项的尺寸发生变化时，FBO都会被重新创建。
默认值为true 。
访问函数：
| bool | textureFollowsItemSize() const |
| void | setTextureFollowsItemSize(bool follows) |
通知器信号：
| void | textureFollowsItemSizeChanged(bool) |
成员函数文档
QQuickFramebufferObject::QQuickFramebufferObject(QQuickItem *parent = nullptr)
创建一个新的 QQuickFramebufferObject，其父对象为parent 。
[pure virtual] QQuickFramebufferObject::Renderer *QQuickFramebufferObject::createRenderer() const
重写此函数，以创建一个用于将内容渲染到 FBO 中的渲染器。
该函数将在渲染线程上被调用，而此时 GUI 线程处于阻塞状态。
[override virtual] bool QQuickFramebufferObject::isTextureProvider() const
重新实现了：QQuickItem::isTextureProvider() const。
[override virtual] void QQuickFramebufferObject::releaseResources()
重写了：QQuickItem::releaseResources()。
[override virtual] QSGTextureProvider *QQuickFramebufferObject::textureProvider() const
重新实现了：QQuickItem::textureProvider() const。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
