The QQuickPaintedItem class provides a way to use the QPainter API in the QML Scene Graph. 更多...
| 头： | #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 |
| 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 |
The QQuickPaintedItem makes it possible to use the QPainter API with the QML Scene Graph. It sets up a textured rectangle in the Scene Graph and uses a QPainter to paint onto the texture. The render target in Qt 6 is always a QImage . When the render target is a QImage , QPainter first renders into the image then the content is uploaded to the texture. Call update () to trigger a repaint.
要启用 QPainter to do anti-aliased rendering, use setAntialiasing ().
To write your own painted item, you first create a subclass of QQuickPaintedItem, and then start by implementing its only pure virtual public function: paint (), which implements the actual painting. The painting will be inside the rectangle spanning from 0,0 to width (), height ().
注意： It important to understand the performance implications such items can incur. See QQuickPaintedItem::RenderTarget and QQuickPaintedItem::renderTarget .
另请参阅 Scene Graph - Painted Item and 采用 C++ 编写 QML 扩展 .
This enum describes flags that you can enable to improve rendering performance in QQuickPaintedItem . By default, none of these flags are set.
| 常量 | 值 | 描述 |
|---|---|---|
QQuickPaintedItem::FastFBOResizing
|
0x1
|
As of Qt 6.0, this value is ignored. |
The PerformanceHints type is a typedef for QFlags <PerformanceHint>. It stores an OR combination of PerformanceHint values.
此枚举描述 QQuickPaintedItem 's render targets. The render target is the surface QPainter paints onto before the item is rendered on screen.
| 常量 | 值 | 描述 |
|---|---|---|
QQuickPaintedItem::Image
|
0
|
The default; QPainter paints into a QImage using the raster paint engine. The image's content needs to be uploaded to graphics memory afterward, this operation can potentially be slow if the item is large. This render target allows high quality anti-aliasing and fast item resizing. |
QQuickPaintedItem::FramebufferObject
|
1
|
As of Qt 6.0, this value is ignored. |
QQuickPaintedItem::InvertedYFramebufferObject
|
2
|
As of Qt 6.0, this value is ignored. |
另请参阅 setRenderTarget ().
This property holds the item's background fill color.
By default, the fill color is set to Qt::transparent .
Set the fill color to an invalid color (e.g. QColor()) to disable background filling. This may improve performance, and is safe to do if the paint () function draws to all pixels on each frame.
访问函数：
| QColor | fillColor () const |
| void | setFillColor (const QColor &) |
通知程序信号：
| void | fillColorChanged () |
This property holds the item's render target.
This property defines which render target the QPainter renders into, it can be either QQuickPaintedItem::Image , QQuickPaintedItem::FramebufferObject or QQuickPaintedItem::InvertedYFramebufferObject .
Each has certain benefits, typically performance versus quality. Using a framebuffer object avoids a costly upload of the image contents to the texture in graphics memory, while using an image enables high quality anti-aliasing.
警告： Resizing a framebuffer object is a costly operation, avoid using the QQuickPaintedItem::FramebufferObject render target if the item gets resized often.
By default, the render target is QQuickPaintedItem::Image .
访问函数：
| QQuickPaintedItem::RenderTarget | renderTarget () const |
| void | setRenderTarget (QQuickPaintedItem::RenderTarget target ) |
通知程序信号：
| void | renderTargetChanged () |
Defines the size of the texture.
Changing the texture's size does not affect the coordinate system used in paint (). A scale factor is instead applied so painting should still happen inside 0,0 to width (), height ().
By default, the texture size will have the same size as this item.
注意： If the item is on a window with a device pixel ratio different from 1, this scale factor will be implicitly applied to the texture size.
访问函数：
| QSize | textureSize () const |
| void | setTextureSize (const QSize & size ) |
通知程序信号：
| void | textureSizeChanged () |
[explicit]
QQuickPaintedItem::
QQuickPaintedItem
(
QQuickItem
*
parent
= nullptr)
Constructs a QQuickPaintedItem with the given parent 项。
[override virtual noexcept]
QQuickPaintedItem::
~QQuickPaintedItem
()
销毁 QQuickPaintedItem .
Returns true if antialiased painting is enabled; otherwise, false is returned.
By default, antialiasing is not enabled.
另请参阅 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).
Returns true if mipmaps are enabled; otherwise, false is returned.
By default, mipmapping is not enabled.
另请参阅 setMipmap ().
Returns true if this item is opaque; otherwise, false is returned.
By default, painted items are not opaque.
另请参阅 setOpaquePainting ().
[pure virtual]
void
QQuickPaintedItem::
paint
(
QPainter
*
painter
)
This function, which is usually called by the QML Scene Graph, paints the contents of an item in local coordinates.
The underlying texture will have a size defined by textureSize when set, or the item's size, multiplied by the window's device pixel ratio.
The function is called after the item has been filled with the fillColor .
Reimplement this function in a QQuickPaintedItem subclass to provide the item's painting implementation, using painter .
注意： The QML Scene Graph uses two separate threads, the main thread does things such as processing events or updating animations while a second thread does the actual issuing of graphics resource updates and the recording of draw calls. As a consequence, paint() is not called from the main GUI thread but from the GL enabled renderer thread. At the moment paint() is called, the GUI thread is blocked and this is therefore thread-safe.
警告： Extreme caution must be used when creating QObjects, emitting signals, starting timers and similar inside this function as these will have affinity to the rendering thread.
另请参阅 width (), height ()，和 textureSize .
Returns the performance hints.
By default, no performance hint is enabled.
另请参阅 setPerformanceHint () 和 setPerformanceHints ().
[override virtual protected]
void
QQuickPaintedItem::
releaseResources
()
重实现： QQuickItem::releaseResources ().
若 enable is true, antialiased painting is enabled.
By default, antialiasing is not enabled.
另请参阅 antialiasing ().
若 enable is true, mipmapping is enabled on the associated texture.
Mipmapping increases rendering speed and reduces aliasing artifacts when the item is scaled down.
By default, mipmapping is not enabled.
另请参阅 mipmap ().
若 opaque is true, the item is opaque; otherwise, it is considered as translucent.
Opaque items are not blended with the rest of the scene, you should set this to true if the content of the item is opaque to speed up rendering.
By default, painted items are not opaque.
另请参阅 opaquePainting ().
Sets the given performance hint on the item if enabled is true; otherwise clears the performance hint.
By default, no performance hint is enabled/
另请参阅 setPerformanceHints () 和 performanceHints ().
Sets the performance hints to hints
By default, no performance hint is enabled/
另请参阅 setPerformanceHint () 和 performanceHints ().
[override virtual]
QSGTextureProvider
*QQuickPaintedItem::
textureProvider
() const
重实现： QQuickItem::textureProvider() const .
调度重新绘制的区域涵盖通过 rect 在此项。可以调用此函数，每当项需要重新绘制时 (譬如：若它改变外观或大小)。
This function does not cause an immediate paint; instead it schedules a paint request that is processed by the QML Scene Graph when the next frame is rendered. The item will only be redrawn if it is visible.
另请参阅 paint ().
[override virtual protected]
QSGNode
*QQuickPaintedItem::
updatePaintNode
(
QSGNode
*
oldNode
,
QQuickItem::UpdatePaintNodeData
*
data
)
重实现： QQuickItem::updatePaintNode (QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *updatePaintNodeData).