QQuickPaintedItem 类

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

头文件 #include <QQuickPaintedItem>
CMakefind_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmakeQT += quick
继承 QQuickItem

公共类型

枚举PerformanceHint { FastFBOResizing }
标志PerformanceHints
枚举RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject }

属性

公共函数

QQuickPaintedItem(QQuickItem *parent = nullptr)
virtual~QQuickPaintedItem() override
boolantialiasing() const
QColorfillColor() const
boolmipmap() const
boolopaquePainting() const
virtual voidpaint(QPainter *painter) = 0
QQuickPaintedItem::PerformanceHintsperformanceHints() const
QQuickPaintedItem::RenderTargetrenderTarget() const
voidsetAntialiasing(bool enable)
voidsetFillColor(const QColor &)
voidsetMipmap(bool enable)
voidsetOpaquePainting(bool opaque)
voidsetPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)
voidsetPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
voidsetRenderTarget(QQuickPaintedItem::RenderTarget target)
voidsetTextureSize(const QSize &size)
QSizetextureSize() const
voidupdate(const QRect &rect = QRect())

重实现公共函数

virtual boolisTextureProvider() const override
virtual QSGTextureProvider *textureProvider() const override

信号

重实现受保护函数

virtual voiditemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override
virtual voidreleaseResources() override
virtual QSGNode *updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data) override

详细描述

QQuickPaintedItem 使得可以使用 QPainter API 与 QML 场景图。它设置了一个纹理矩形在场景图中,并使用一个 QPainter 来在纹理上绘制。在 Qt 6 中,渲染目标总是 QImage。当渲染目标是一个 QImage 时,QPainter 首先在图像中渲染,然后将内容上传到纹理。调用 update() 来触发重绘。

要使 QPainter 进行抗锯齿渲染,使用 setAntialiasing

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

注意:理解此类项可能会产生的影响性能非常重要。请参阅QQuickPaintedItem::RenderTargetQQuickPaintedItem::renderTarget

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

成员类型文档

enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints

此枚举描述了可以启用来改进 QQuickPaintedItem 中渲染性能的标志。默认情况下,都不设置这些标志。

常量描述
QQuickPaintedItem::FastFBOResizing0x1自 Qt 6.0 以来,此值被忽略。

PerformanceHints 类型是 QFlags 的类型定义。它存储了 PerformanceHint 值的 OR 组合。

enum QQuickPaintedItem::RenderTarget

此枚举描述 QQuickPaintedItem 的渲染目标。渲染目标是 QPainter 在该项目在屏幕上绘制之前绘制的表面。

常量描述
QQuickPaintedItem::Image0默认值;QPainter 使用光栅绘制引擎将内容绘制到 QImage 中。图像的内容需要随后上传到图形内存,如果该项很大,此操作可能比较慢。此渲染目标允许高质量的抗锯齿和快速项调整大小。
QQuickPaintedItem::FramebufferObject1自 Qt 6.0 以来,此值被忽略。
QQuickPaintedItem::InvertedYFramebufferObject2自 Qt 6.0 以来,此值被忽略。

另请参阅setRenderTarget

属性文档

fillColor : QColor

该属性保存了项目的背景填充颜色。

默认情况下,填充颜色设置为 Qt::transparent

将填充颜色设置为无效颜色(例如,QColor())以禁用背景填充。这可能会提高性能,并且如果在每个帧上() 函数绘制所有像素,则此操作是安全的。

访问功能

QColorfillColor() const
voidsetFillColor(const QColor &)

通知信号

voidfillColorChanged()

renderTarget : RenderTarget

该属性保存了项目的渲染目标。

该属性定义了 QPainter 向哪个渲染目标渲染,可以是 QQuickPaintedItem::ImageQQuickPaintedItem::FramebufferObjectQQuickPaintedItem::InvertedYFramebufferObject

它们各自都有某些优势,通常是性能与质量之间的权衡。使用帧缓冲区对象可以避免将图像内容上传到图形内存中纹理的开销,而使用图像可以实现高质量的抗锯齿。

注意: 调整帧缓冲区对象大小是一项代价昂贵的操作,如果项目经常调整大小,请避免使用 QQuickPaintedItem::FramebufferObject 渲染目标。

默认情况下,渲染目标为 QQuickPaintedItem::Image

访问功能

QQuickPaintedItem::RenderTargetrenderTarget() const
voidsetRenderTarget(QQuickPaintedItem::RenderTarget target)

通知信号

voidrenderTargetChanged()

textureSize : QSize

定义了纹理的大小。

更改纹理的大小不会影响 paint() 中使用的坐标系统。相反,会应用一个缩放因子,因此绘画仍然应该发生在 0,0 到 width()、height() 内。

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

注意: 如果项目位于设备像素比不为 1 的窗口中,此缩放因子将默认应用于纹理大小。

访问功能

QSizetextureSize() const
voidsetTextureSize(const QSize &size)

通知信号

voidtextureSizeChanged()

成员函数文档

[显式] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)

使用指定的 parent 项目构建 QQuickPaintedItem。

[重写虚函数 noexcept] QQuickPaintedItem::~QQuickPaintedItem()

销毁 QQuickPaintedItem

bool QQuickPaintedItem::antialiasing() const

如果启用抗锯齿化绘画,则返回 true;否则返回 false。

默认情况下,不启用抗锯齿化。

另请参阅 setAntialiasing

[重写虚函数] bool QQuickPaintedItem::isTextureProvider() const

重实现: QQuickItem::isTextureProvider() const

[重写虚保护] 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

[纯虚] void QQuickPaintedItem::paint(QPainter *painter)

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

当设置时,基本纹理的大小将由textureSize定义,或者项的大小乘以窗口的设备像素比。

在将fillColor填充到项中之后,将调用此函数。

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

注意: QML场景图使用两个独立的线程,主线程执行诸如处理事件或更新动画等任务,而第二个线程执行实际的图形资源更新和绘制调用记录。因此,paint()不是在主GUI线程中调用,而是在开启GL的渲染线程中调用。这时,GUI线程被阻塞,因此这是线程安全的。

警告: 当在此函数中创建QObjects、发出信号、启动定时器等操作时,必须极为小心,因为这些将具有渲染线程的亲和力。

另请参阅 width()、height() 和 textureSize

QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const

返回性能提示。

默认情况下,不启用任何性能提示。

另请参阅 setPerformanceHint() 和 setPerformanceHints

[重写虚保护] void QQuickPaintedItem::releaseResources()

重实现: QQuickItem::releaseResources

void QQuickPaintedItem::setAntialiasing(bool enable)

如果enable为true,则启用抗锯齿绘制。

默认情况下,不启用抗锯齿化。

另请参阅 antialiasing

void QQuickPaintedItem::setMipmap(bool enable)

如果 启用 为真,则关联的纹理将启用多级贴图。

多级贴图在项目缩放时可以增加渲染速度并减少锯齿伪影。

默认情况下,mipmap不禁用。

另请参阅多级贴图

void QQuickPaintedItem::setOpaquePainting(bool opaque)

如果 opaque 为真,则项目不透明;否则,被视为半透明。

不透明项目不与场景的其他部分混合,如果内容不透明,您应将其设置为 true 以加快渲染速度。

默认情况下,绘制项不是不透明的。

另请参阅不透明绘画

void QQuickPaintedItem::setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)

如果 enabled 为真,则在项目上设置指定的性能 提示;否则清除性能提示。

默认情况下,不启用性能提示。

另请参阅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)。

© 2024 The Qt Company Ltd. 以下是文档贡献者的版权所有。此处提供的文档根据 Free Software Foundation 作为发布者发布的 GNU 自由文档许可证版本 1.3 的条款获得许可。Qt 以及相应的标志是 The Qt Company Ltd 在芬兰以及/或世界其他国家的商标。所有其他商标均为其各自所有者的财产。