QQuickPaintedItem Class
QQuickPaintedItem 类提供了在 QML 场景图中使用QPainter API 的方法。更多
| Header： | #include <QQuickPaintedItem> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Quick)target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake： | QT += quick |
| 继承： | QQuickItem |
公共类型
| enum | PerformanceHint { FastFBOResizing } |
| flags | PerformanceHints |
| enum | RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject } |
属性
- fillColor : QColor
- renderTarget : RenderTarget
- textureSize : QSize
公共函数
| QQuickPaintedItem(QQuickItem *parent = nullptr) | |
| virtual | ~QQuickPaintedItem() override |
| bool | antialiasing() const |
| QColor | fillColor() const |
| bool | mipmap() const |
| bool | opaquePainting() const |
| virtual void | paint(QPainter *painter) = 0 |
| QQuickPaintedItem::PerformanceHints | performanceHints() const |
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setAntialiasing(bool enable) |
| void | setFillColor(const QColor &) |
| void | setMipmap(bool enable) |
| void | setOpaquePainting(bool opaque) |
| void | setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true) |
| void | setPerformanceHints(QQuickPaintedItem::PerformanceHints hints) |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
| void | setTextureSize(const QSize &size) |
| QSize | textureSize() const |
| void | update(const QRect &rect = QRect()) |
重新实现的公共函数
| virtual bool | isTextureProvider() const override |
| virtual QSGTextureProvider * | textureProvider() const override |
信号
| void | fillColorChanged() |
| void | renderTargetChanged() |
| void | textureSizeChanged() |
重新实现的受保护函数
| virtual void | itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override |
| virtual void | releaseResources() override |
| virtual QSGNode * | updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data) override |
详细说明
QQuickPaintedItem 可将QPainter API 与 QML 场景图结合使用。它在场景图中设置了一个纹理矩形，并使用QPainter 在纹理上涂画。Qt XML 6 中的渲染目标始终是QImage 。当渲染目标是QImage 时，QPainter 首先渲染到图像中，然后将内容上传到纹理上。调用update() 可触发重绘。
要启用QPainter 进行反锯齿渲染，请使用setAntialiasing() 。
要编写自己的绘制项目，首先要创建一个 QQuickPaintedItem 的子类，然后开始实现其唯一的纯虚拟公共函数：paint() ，该函数实现了实际的绘制。绘制将在跨度为 0,0 到width(),height() 的矩形内进行。
注意： 了解此类项目对性能的影响非常重要。请参见QQuickPaintedItem::RenderTarget 和QQuickPaintedItem::renderTarget 。
另请参阅 Scene Graph - Painted Item和Writing QML Extensions with C++。
成员类型文档
枚举 QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints
此枚举描述了可以启用的标志，以提高QQuickPaintedItem 中的渲染性能。默认情况下，这些标志均未设置。
| 常量 | 值 | 说明 |
|---|---|---|
QQuickPaintedItem::FastFBOResizing | 0x1 | 从 Qt 6.0 开始，此值将被忽略。 |
PerformanceHints 类型是QFlags<PerformanceHint> 的类型定义。它存储 PerformanceHint 值的 OR 组合。
enum QQuickPaintedItem::RenderTarget
该枚举描述了QQuickPaintedItem 的渲染目标。渲染目标是QPainter 在屏幕上渲染项目之前绘制的表面。
| 常量 | 值 | 描述 |
|---|---|---|
QQuickPaintedItem::Image | 0 | 默认值；QPainter 使用光栅绘制引擎绘制到QImage 上。图像内容随后需要上传到显存，如果项目较大，这一操作可能会很慢。这种渲染目标允许高质量的抗锯齿和快速的项目大小调整。 |
QQuickPaintedItem::FramebufferObject | 1 | 从 Qt 6.9 开始，只要使用的渲染 API 是 OpenGL，此值就能启用硬件加速绘制，否则将被忽略。对于 Qt 6.0 至 Qt 6.8 版本，在所有渲染 API 上都将忽略该值。这通常会带来更好的渲染性能，但会牺牲抗锯齿质量。 |
QQuickPaintedItem::InvertedYFramebufferObject | 2 | 与 FramebufferObject 相同，但渲染会围绕 X 轴翻转。 |
另请参阅 setRenderTarget().
属性文档
fillColor : QColor
该属性用于保存项目的背景填充颜色。
默认情况下，填充颜色设置为Qt::transparent 。
将填充颜色设置为无效颜色（例如 QColor()）可禁用背景填充。这可能会提高性能，而且如果paint() 函数绘制到每一帧的所有像素，这样做也是安全的。
访问函数：
| QColor | fillColor() const |
| void | setFillColor(const QColor &) |
通知信号：
| void | fillColorChanged() |
renderTarget : RenderTarget
该属性用于保存项目的呈现目标。
该属性定义了QPainter 渲染的目标，可以是QQuickPaintedItem::Image 、QQuickPaintedItem::FramebufferObject 或QQuickPaintedItem::InvertedYFramebufferObject 。
每种方法都有一定的优势，通常是性能与质量的比较。使用帧缓存对象可以避免将图像内容上传到图形内存中的纹理，而使用图像则可以实现高质量的抗锯齿。
警告 调整帧缓冲对象的大小是一项代价高昂的操作，如果项目经常调整大小，请避免使用QQuickPaintedItem::FramebufferObject 渲染目标。
默认情况下，呈现目标是QQuickPaintedItem::Image 。
访问功能：
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
通知信号：
| void | renderTargetChanged() |
textureSize : QSize
定义纹理的大小。
改变纹理的大小不会影响paint() 中使用的坐标系。我们会应用一个缩放因子，因此在width(),height() 的 0,0 范围内进行绘制。
默认情况下，纹理大小与该项目大小相同。
注： 如果项目位于设备像素比不同于 1 的窗口上，则该缩放因子将隐式应用于纹理尺寸。
访问功能：
| QSize | textureSize() const |
| void | setTextureSize(const QSize &size) |
Notifier 信号：
| void | textureSizeChanged() |
成员函数 文档
[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)
用给定的parent 项目构建一个 QQuickPaintedItem。
[override virtual noexcept] QQuickPaintedItem::~QQuickPaintedItem()
bool QQuickPaintedItem::antialiasing() const
如果启用了抗锯齿绘制，则返回 true；否则返回 false。
默认情况下，不启用反锯齿。
另请参阅 setAntialiasing()。
[override virtual] bool QQuickPaintedItem::isTextureProvider() const
重实现：QQuickItem::isTextureProvider() const.
[override virtual protected] void QQuickPaintedItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)
重实现：QQuickItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value).
bool QQuickPaintedItem::mipmap() const
如果启用了 mipmap，则返回 true；否则返回 false。
默认情况下，mipmap 未启用。
另请参阅 setMipmap()。
bool QQuickPaintedItem::opaquePainting() const
如果该项目不透明，则返回 true；否则返回 false。
默认情况下，绘制的项目不透明。
另请参阅 setOpaquePainting()。
[pure virtual] void QQuickPaintedItem::paint(QPainter *painter)
该函数通常由 QML 场景图调用，以本地坐标绘制项目内容。
底层纹理的大小由textureSize 或项目大小乘以窗口的设备像素比定义。
fillColor 填充项目后调用该函数。
使用painter 在QQuickPaintedItem 子类中重新实现该函数，以提供项目的绘制实现。
注： QML 场景图使用两个独立的线程，主线程负责处理事件或更新动画，而第二个线程负责实际发布图形资源更新和记录绘制调用。因此，paint() 并不是由 GUI 主线程调用的，而是由启用了 GL 的渲染器线程调用的。在调用 paint() 时，GUI 线程会被阻塞，因此这是线程安全的。
警告 在此函数内创建 QObject、发射信号、启动计时器等类似操作时必须格外小心，因为这些操作会与渲染线程产生亲缘关系。
另请参阅 width(),height() 和textureSize 。
QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const
返回性能提示。
默认情况下，不启用性能提示。
另请参阅 setPerformanceHint() 和setPerformanceHints()。
[override virtual protected] void QQuickPaintedItem::releaseResources()
重新实现：QQuickItem::releaseResources().
void QQuickPaintedItem::setAntialiasing(bool enable)
如果enable 为 true，则会启用抗锯齿绘制。
默认情况下，不启用反锯齿。
另请参阅 antialiasing().
void QQuickPaintedItem::setMipmap(bool enable)
如果enable 为 true，则会在相关纹理上启用多重贴图。
mipmapping 可以提高渲染速度，并减少项目缩放时产生的混叠伪影。
默认情况下，mipmapping 未启用。
另请参阅 mipmap().
void QQuickPaintedItem::setOpaquePainting(bool opaque)
如果opaque 为 true，则该项目为不透明；否则，它将被视为半透明。
不透明的项目不会与场景的其他部分混合，如果项目的内容不透明，则应将其设置为 true，以加快渲染速度。
默认情况下，绘制的项目是不透明的。
另请参阅 opaquePainting().
void QQuickPaintedItem::setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)
如果enabled 为 true，则在项目上设置给定的性能hint ；否则清除性能提示。
默认情况下，不启用性能提示。
另请参阅 setPerformanceHints() 和performanceHints()。
void QQuickPaintedItem::setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
将性能提示设置为hints
默认情况下，不启用性能提示
另请参阅 setPerformanceHint() 和performanceHints()。
[override virtual] QSGTextureProvider *QQuickPaintedItem::textureProvider() const
重实现：QQuickItem::textureProvider() const.
void QQuickPaintedItem::update(const QRect &rect = QRect())
重绘rect 所覆盖的区域。只要您的项目需要重绘，如改变外观或大小，您就可以调用此函数。
此函数不会立即绘制，而是安排一个绘制请求，在下一帧渲染时由 QML 场景图处理。项目只有在可见时才会被重绘。
另请参阅 paint().
[override virtual protected] QSGNode *QQuickPaintedItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data)
重实现：QQuickItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *updatePaintNodeData).
© 2025 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.
