PySide6.QtQuick.QQuickPaintedItem

class QQuickPaintedItem

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

PySide6.QtQuick.QQuickPaintedItem的继承图

概要

属性

方法

虚拟方法

信号

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

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

为了使QPainter能够进行抗锯齿渲染，请使用setAntialiasing()。

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

注意

理解这些项目可能带来的性能影响非常重要。请参阅RenderTarget和renderTarget。

另请参阅

场景图 - 绘制项目 编写 QML 扩展 使用 C++

class RenderTarget

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

常量

描述

QQuickPaintedItem.Image

默认情况下；QPainter 使用光栅绘制引擎在 QImage 上绘制。图像的内容随后需要上传到图形内存中，如果项目较大，此操作可能会较慢。此渲染目标允许高质量的抗锯齿和快速的项目调整大小。

QQuickPaintedItem.FramebufferObject

从 Qt 6.0 开始，此值被忽略。

QQuickPaintedItem.InvertedYFramebufferObject

自 Qt 6.0 起，此值被忽略。

另请参阅

setRenderTarget()

class PerformanceHint

(继承自 enum.Flag) 此枚举描述了您可以启用的标志，以提高在 QQuickPaintedItem 中的渲染性能。默认情况下，这些标志均未设置。

常量

描述

QQuickPaintedItem.FastFBOResizing

自 Qt 6.0 起，此值被忽略。

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property contentsScaleᅟ: float

此属性包含用于缩放内容的过时方法。

此函数是为了兼容性提供的，使用size()结合textureSize()来决定你正在绘制的内容的大小。

Access functions:
property contentsSizeᅟ: QSize

此属性包含用于设置内容大小的过时方法。

此函数为兼容性提供，请结合textureSize使用size来决定您正在绘制的内容的大小。

Access functions:
property fillColorᅟ: QColor

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

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

将填充颜色设置为无效颜色（例如 QColor()）以禁用背景填充。这可能会提高性能，并且如果 paint() 函数在每一帧上绘制所有像素，这样做是安全的。

Access functions:
property renderTargetᅟ: QQuickPaintedItem.RenderTarget

此属性保存项目的渲染目标。

此属性定义了QPainter渲染到的渲染目标，它可以是Image、FramebufferObject或InvertedYFramebufferObject。

每种方法都有其特定的优势，通常是性能与质量之间的权衡。使用帧缓冲对象可以避免将图像内容上传到图形内存中的纹理这一昂贵操作，而使用图像则可以实现高质量的抗锯齿效果。

警告

调整帧缓冲对象的大小是一项昂贵的操作，如果项目经常调整大小，请避免使用FramebufferObject渲染目标。

默认情况下，渲染目标是 Image 。

Access functions:
property textureSizeᅟ: QSize

此属性定义了纹理的大小。

更改纹理的大小不会影响在paint()中使用的坐标系。相反，会应用一个比例因子，因此绘画仍应在0,0到width()，height()的范围内进行。

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

注意

如果项目位于设备像素比不同于1的窗口上，此比例因子将隐式应用于纹理大小。

Access functions:
__init__([parent=None])
Parameters:

父级 – QQuickItem

使用给定的parent项构造一个QQuickPaintedItem。

contentsBoundingRect()
Return type:

QRectF

此函数为兼容性提供，请结合textureSize使用size来决定您正在绘制的内容的大小。

contentsScale()
Return type:

浮点数

另请参阅

setContentsScale()

属性 contentsScaleᅟ 的获取器。

contentsScaleChanged()

属性 contentsScaleᅟ 的通知信号。

contentsSize()
Return type:

QSize

另请参阅

setContentsSize()

属性 contentsSizeᅟ 的获取器。

contentsSizeChanged()

属性 contentsSizeᅟ 的通知信号。

fillColor()
Return type:

QColor

另请参阅

setFillColor()

属性 fillColorᅟ 的获取器。

fillColorChanged()

属性 fillColorᅟ 的通知信号。

mipmap()
Return type:

布尔

如果启用了mipmaps，则返回true；否则，返回false。

默认情况下，mipmapping 未启用。

另请参阅

setMipmap()

opaquePainting()
Return type:

布尔

如果此项不透明，则返回 true；否则，返回 false。

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

另请参阅

setOpaquePainting()

abstract paint(painter)
Parameters:

画家 – QPainter

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

底层纹理的大小将由textureSize设置时定义，或者由项目的大小乘以窗口的设备像素比。

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

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

注意

QML场景图使用两个独立的线程，主线程处理诸如事件处理或动画更新等任务，而第二个线程则负责实际发出图形资源更新和记录绘制调用。因此，paint()不是从主GUI线程调用的，而是从启用了GL的渲染器线程调用的。在调用paint()时，GUI线程被阻塞，因此这是线程安全的。

警告

在此函数内创建QObjects、发出信号、启动计时器及类似操作时必须极其谨慎，因为这些操作将与渲染线程具有关联性。

另请参阅

width() height() textureSize

performanceHints()
Return type:

PerformanceHint的组合

返回性能提示。

默认情况下，没有启用性能提示。

renderTarget()
Return type:

RenderTarget

另请参阅

setRenderTarget()

属性 renderTargetᅟ 的获取器。

renderTargetChanged()

属性 renderTargetᅟ 的通知信号。

resetContentsSize()

这个便捷函数等同于调用 setContentsSize (QSize())。

setContentsScale(arg__1)
Parameters:

arg__1 – 浮点数

另请参阅

contentsScale()

属性 contentsScaleᅟ 的设置器。

setContentsSize(arg__1)
Parameters:

arg__1 – QSize

另请参阅

contentsSize()

属性 contentsSizeᅟ 的设置器。

setFillColor(arg__1)
Parameters:

arg__1 – QColor

另请参阅

fillColor()

属性 fillColorᅟ 的设置器。

setMipmap(enable)
Parameters:

enable – 布尔值

如果 enable 为 true，则在关联的纹理上启用 mipmapping。

Mipmapping 在项目缩小比例时提高了渲染速度并减少了锯齿伪影。

默认情况下，mipmapping 未启用。

另请参阅

mipmap()

setOpaquePainting(opaque)
Parameters:

opaque – 布尔值

如果 opaque 为 true，则该项目是不透明的；否则，它被认为是半透明的。

不透明的项目不会与场景的其余部分混合，如果项目的内容是不透明的，你应该将此设置为true以加快渲染速度。

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

另请参阅

opaquePainting()

setPerformanceHint(hint[, enabled=true])
Parameters:

如果enabled为真，则在项目上设置给定的性能hint；否则清除性能提示。

默认情况下，没有启用性能提示。

setPerformanceHints(hints)
Parameters:

提示 – PerformanceHint 的组合

设置性能提示为 hints

默认情况下，没有启用性能提示。

setRenderTarget(target)
Parameters:

目标 – RenderTarget

另请参阅

renderTarget()

属性 renderTargetᅟ 的设置器。

setTextureSize(size)
Parameters:

大小 – QSize

另请参阅

textureSize()

属性 textureSizeᅟ 的设置器。

textureSize()
Return type:

QSize

另请参阅

setTextureSize()

属性 textureSizeᅟ 的获取器。

textureSizeChanged()

属性 textureSizeᅟ 的通知信号。

update([rect=QRect()])
Parameters:

rect – QRect

安排重新绘制此项目中由rect覆盖的区域。每当您的项目需要重新绘制时，例如如果它改变外观或大小，您可以调用此函数。

此函数不会立即引起绘制；相反，它会安排一个绘制请求，该请求在渲染下一帧时由QML场景图处理。只有在项目可见时，项目才会被重新绘制。

另请参阅

paint()