QQuickPaintedItem 类
QQuickPaintedItem 类提供了一种在 QML 场景图中使用 QPainter API 的方式。更多...
头文件 | #include <QQuickPaintedItem> |
CMake | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
qmake | QT += quick |
继承 | QQuickItem |
公共类型
枚举 | PerformanceHint { FastFBOResizing } |
标志 | PerformanceHints |
枚举 | 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 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::FastFBOResizing | 0x1 | 自 Qt 6.0 以来,此值被忽略。 |
PerformanceHints 类型是 QFlags
enum QQuickPaintedItem::RenderTarget
此枚举描述 QQuickPaintedItem 的渲染目标。渲染目标是 QPainter 在该项目在屏幕上绘制之前绘制的表面。
常量 | 值 | 描述 |
---|---|---|
QQuickPaintedItem::Image | 0 | 默认值;QPainter 使用光栅绘制引擎将内容绘制到 QImage 中。图像的内容需要随后上传到图形内存,如果该项很大,此操作可能比较慢。此渲染目标允许高质量的抗锯齿和快速项调整大小。 |
QQuickPaintedItem::FramebufferObject | 1 | 自 Qt 6.0 以来,此值被忽略。 |
QQuickPaintedItem::InvertedYFramebufferObject | 2 | 自 Qt 6.0 以来,此值被忽略。 |
另请参阅setRenderTarget。
属性文档
fillColor : QColor
该属性保存了项目的背景填充颜色。
默认情况下,填充颜色设置为 Qt::transparent。
将填充颜色设置为无效颜色(例如,QColor())以禁用背景填充。这可能会提高性能,并且如果在每个帧上
访问功能
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() |
成员函数文档
[显式]
QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)
使用指定的 parent 项目构建 QQuickPaintedItem。
[重写虚函数 noexcept]
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 在芬兰以及/或世界其他国家的商标。所有其他商标均为其各自所有者的财产。