本页内容

QQuickPaintedItem Class

QQuickPaintedItem 类提供了一种在 QML 场景图中使用QPainter API 的方法。更多内容...

标题: #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 }

属性

公共函数

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

信号

重新实现的受保护函数

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 使得在 QML 场景图中使用QPainter API 成为可能。它会在场景图中设置一个带纹理的矩形,并使用QPainter 在纹理上进行绘制。在 Qt 6 中,渲染目标始终是QImage 。当渲染目标是QImage 时,QPainter 会先将内容渲染到图像中,然后将内容上传到纹理。 调用update()以触发重绘。

若要启用QPainter 的抗锯齿渲染功能,请使用setAntialiasing()。

要编写自己的绘制项,首先需创建 QQuickPaintedItem 的子类,然后从实现其唯一的纯虚公共函数开始:paint(),该函数负责实现实际的绘制。绘制操作将在从 (0, 0) 到width()、height() 所定义的矩形内进行。

注意:必须 了解此类项可能带来的性能影响。请参阅QQuickPaintedItem::RenderTarget 和QQuickPaintedItem::renderTarget 。

另请参阅 “场景图 - 绘制项”和“使用 C++ 编写 QML 扩展”。

成员类型文档

enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints

此枚举描述了可在QQuickPaintedItem 中启用以提升渲染性能的标志。默认情况下,这些标志均未启用。

常量值描述
QQuickPaintedItem::FastFBOResizing0x1从 Qt 6.0 开始,该值将被忽略。

PerformanceHints 类型是QFlags<PerformanceHint> 的 typedef。它存储 PerformanceHint 值的按“或”运算组合。

enum QQuickPaintedItem::RenderTarget

此枚举描述了QQuickPaintedItem 的渲染目标。渲染目标是QPainter 在将对象渲染到屏幕之前进行绘制的表面。

常量值描述
QQuickPaintedItem::Image0默认值;QPainter 使用光栅绘制引擎将内容绘制到QImage 中。图像内容随后需要上传到图形内存,如果项较大,此操作可能会比较慢。此渲染目标支持高质量的抗锯齿和快速的项尺寸调整。
QQuickPaintedItem::FramebufferObject1从 Qt 6.9 开始,只要使用的渲染 API 是 OpenGL,此值将启用硬件加速绘制;否则将被忽略。 对于 Qt 6.0 至 Qt 6.8 版本,该值在所有渲染 API 上均会被忽略。这通常能提供更好的渲染性能,但会以牺牲抗锯齿质量为代价。
QQuickPaintedItem::InvertedYFramebufferObject2与 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()中使用的坐标系。取而代之的是应用了一个缩放因子,因此绘制操作仍应在0,0到width()、height()的范围内进行。

默认情况下,纹理大小将与该项相同。

注意:如果 该项位于设备像素比不为 1 的窗口上,则会隐式地将该缩放因子应用于纹理尺寸。

访问函数:

QSize textureSize() const
void setTextureSize(const QSize &size)

通知信号:

void textureSizeChanged()

成员函数文档

[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)

使用给定的parent 项创建一个QQuickPaintedItem。

[override virtual noexcept] QQuickPaintedItem::~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

如果启用了MIP映射,则返回true;否则返回false。

默认情况下,Mipmap 未启用。

另请参阅 setMipmap()。

bool QQuickPaintedItem::opaquePainting() const

如果该项为不透明,则返回 true;否则返回 false。

默认情况下,绘制后的项目不具有不透明性。

另请参阅 setOpaquePainting()。

[pure virtual] void QQuickPaintedItem::paint(QPainter *painter)

该函数通常由 QML 场景图调用,用于在本地坐标系中绘制项的内容。

底层纹理的大小由textureSize 定义(如果已设置),否则为项目大小乘以窗口的设备像素比率。

该函数在项目被fillColor 填充后被调用。

在QQuickPaintedItem 子类中重写此函数,以使用painter 提供项的绘制实现。

注意: 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 ` 为真,则启用抗锯齿绘制。

默认情况下,抗锯齿功能未启用。

另请参阅 antialiasing()。

void QQuickPaintedItem::setMipmap(bool enable)

如果enable 为true,则关联纹理上将启用Mip映射。

当对象被缩小比例时,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)。

© 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.