QQuickFramebufferObject Class
The QQuickFramebufferObject class is a convenience class for integrating OpenGL rendering using a framebuffer object (FBO) with Qt Quick. More...
Header: | #include <QQuickFramebufferObject> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
qmake: | QT += quick |
Inherits: | QQuickItem |
Public Types
class | Renderer |
Properties
- mirrorVertically : bool
- textureFollowsItemSize : bool
Public Functions
QQuickFramebufferObject(QQuickItem *parent = nullptr) | |
virtual QQuickFramebufferObject::Renderer * | createRenderer() const = 0 |
bool | mirrorVertically() const |
void | setMirrorVertically(bool enable) |
void | setTextureFollowsItemSize(bool follows) |
bool | textureFollowsItemSize() const |
Reimplemented Public Functions
virtual bool | isTextureProvider() const override |
virtual void | releaseResources() override |
virtual QSGTextureProvider * | textureProvider() const override |
Signals
void | mirrorVerticallyChanged(bool) |
void | textureFollowsItemSizeChanged(bool) |
Detailed Description
Warning: This class is only functional when Qt Quick is rendering via OpenGL. It is not compatible with other graphics APIs, such as Vulkan or Metal. It should be treated as a legacy class that is only present in order to enable Qt 5 applications to function without source compatibility breaks as long as they tie themselves to OpenGL.
On most platforms, the rendering will occur on a dedicated thread. For this reason, the QQuickFramebufferObject class enforces a strict separation between the item implementation and the FBO rendering. All item logic, such as properties and UI-related helper functions needed by QML should be located in a QQuickFramebufferObject class subclass. Everything that relates to rendering must be located in the QQuickFramebufferObject::Renderer class.
To avoid race conditions and read/write issues from two threads it is important that the renderer and the item never read or write shared variables. Communication between the item and the renderer should primarily happen via the QQuickFramebufferObject::Renderer::synchronize() function. This function will be called on the render thread while the GUI thread is blocked.
Using queued connections or events for communication between item and renderer is also possible.
Both the Renderer and the FBO are memory managed internally.
To render into the FBO, the user should subclass the Renderer class and reimplement its Renderer::render() function. The Renderer subclass is returned from createRenderer().
The size of the FBO will by default adapt to the size of the item. If a fixed size is preferred, set textureFollowsItemSize to false
and return a texture of your choosing from QQuickFramebufferObject::Renderer::createFramebufferObject().
Starting Qt 5.4, the QQuickFramebufferObject class is a texture provider and can be used directly in ShaderEffects and other classes that consume texture providers.
See also Scene Graph and Rendering.
Property Documentation
mirrorVertically : bool
This property controls if the size of the FBO's contents should be mirrored vertically when drawing. This allows easy integration of third-party rendering code that does not follow the standard expectations.
The default value is false
.
Access functions:
bool | mirrorVertically() const |
void | setMirrorVertically(bool enable) |
Notifier signal:
void | mirrorVerticallyChanged(bool) |
textureFollowsItemSize : bool
This property controls if the size of the FBO's texture should follow the dimensions of the QQuickFramebufferObject item. When this property is false, the FBO will be created once the first time it is displayed. If it is set to true, the FBO will be recreated every time the dimensions of the item change.
The default value is true
.
Access functions:
bool | textureFollowsItemSize() const |
void | setTextureFollowsItemSize(bool follows) |
Notifier signal:
void | textureFollowsItemSizeChanged(bool) |
Member Function Documentation
QQuickFramebufferObject::QQuickFramebufferObject(QQuickItem *parent = nullptr)
Constructs a new QQuickFramebufferObject with parent parent.
[pure virtual]
QQuickFramebufferObject::Renderer *QQuickFramebufferObject::createRenderer() const
Reimplement this function to create a renderer used to render into the FBO.
This function will be called on the rendering thread while the GUI thread is blocked.
[override virtual]
bool QQuickFramebufferObject::isTextureProvider() const
Reimplements: QQuickItem::isTextureProvider() const.
[override virtual]
void QQuickFramebufferObject::releaseResources()
Reimplements: QQuickItem::releaseResources().
[override virtual]
QSGTextureProvider *QQuickFramebufferObject::textureProvider() const
Reimplements: QQuickItem::textureProvider() const.
© 2024 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.