QQuickPaintedItem

The QQuickPaintedItem class provides a way to use the QPainter API in the QML Scene Graph. More…

Synopsis

Functions

• def contentsBoundingRect ()

• def contentsScale ()

• def contentsSize ()

• def fillColor ()

• def mipmap ()

• def opaquePainting ()

• def performanceHints ()

• def renderTarget ()

• def resetContentsSize ()

• def setContentsScale (arg__1)

• def setContentsSize (arg__1)

• def setFillColor (arg__1)

• def setMipmap (enable)

• def setOpaquePainting (opaque)

• def setPerformanceHint (hint[, enabled=true])

• def setPerformanceHints (hints)

• def setRenderTarget (target)

• def setTextureSize (size)

• def textureSize ()

• def update ([rect=QRect()])

Virtual functions

• def paint (painter)

Signals

• def contentsScaleChanged ()

• def contentsSizeChanged ()

• def fillColorChanged ()

• def renderTargetChanged ()

• def textureSizeChanged ()

Detailed Description

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.

To enable 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() .

Note

It important to understand the performance implications such items can incur. See RenderTarget and renderTarget .

See also

Scene Graph - Painted Item Writing QML Extensions with C++

class PySide6.QtQuick.QQuickPaintedItem([parent=None])

Parameters

parent – PySide6.QtQuick.QQuickItem

Constructs a QQuickPaintedItem with the given parent item.

PySide6.QtQuick.QQuickPaintedItem.RenderTarget

This enum describes QQuickPaintedItem ‘s render targets. The render target is the surface QPainter paints onto before the item is rendered on screen.

Constant	Description
QQuickPaintedItem.Image	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	As of Qt 6.0, this value is ignored.
QQuickPaintedItem.InvertedYFramebufferObject	As of Qt 6.0, this value is ignored.

See also

setRenderTarget()

PySide6.QtQuick.QQuickPaintedItem.PerformanceHint

(inherits enum.Flag) This enum describes flags that you can enable to improve rendering performance in QQuickPaintedItem . By default, none of these flags are set.

Constant	Description
QQuickPaintedItem.FastFBOResizing	As of Qt 6.0, this value is ignored.

PySide6.QtQuick.QQuickPaintedItem.contentsBoundingRect()

Return type

PySide6.QtCore.QRectF

This function is provided for compatibility, use size in combination with textureSize to decide the size of what you are drawing.

See also

width() height() textureSize()

PySide6.QtQuick.QQuickPaintedItem.contentsScale()

Return type

float

This property holds Obsolete method for scaling the contents..

This function is provided for compatibility, use size() in combination with textureSize() to decide the size of what you are drawing.

See also

width() height() textureSize()

PySide6.QtQuick.QQuickPaintedItem.contentsScaleChanged()

PySide6.QtQuick.QQuickPaintedItem.contentsSize()

Return type

PySide6.QtCore.QSize

This property holds Obsolete method for setting the contents size..

This function is provided for compatibility, use size in combination with textureSize to decide the size of what you are drawing.

See also

width() height() textureSize()

PySide6.QtQuick.QQuickPaintedItem.contentsSizeChanged()

PySide6.QtQuick.QQuickPaintedItem.fillColor()

Return type

PySide6.QtGui.QColor

This property holds The item’s background fill color..

By default, the fill color is set to transparent .

PySide6.QtQuick.QQuickPaintedItem.fillColorChanged()

PySide6.QtQuick.QQuickPaintedItem.mipmap()

Return type

bool

Returns true if mipmaps are enabled; otherwise, false is returned.

By default, mipmapping is not enabled.

See also

setMipmap()

PySide6.QtQuick.QQuickPaintedItem.opaquePainting()

Return type

bool

Returns true if this item is opaque; otherwise, false is returned.

By default, painted items are not opaque.

See also

setOpaquePainting()

abstract PySide6.QtQuick.QQuickPaintedItem.paint(painter)

Parameters

painter – PySide6.QtGui.QPainter

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.

Note

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.

Warning

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.

See also

width() height() textureSize

PySide6.QtQuick.QQuickPaintedItem.performanceHints()

Return type

PerformanceHints

Returns the performance hints.

By default, no performance hint is enabled.

See also

setPerformanceHint() setPerformanceHints()

PySide6.QtQuick.QQuickPaintedItem.renderTarget()

Return type

RenderTarget

This property holds The item’s render target..

This property defines which render target the QPainter renders into, it can be either Image , FramebufferObject or 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.

Warning

Resizing a framebuffer object is a costly operation, avoid using the FramebufferObject render target if the item gets resized often.

By default, the render target is Image .

PySide6.QtQuick.QQuickPaintedItem.renderTargetChanged()

PySide6.QtQuick.QQuickPaintedItem.resetContentsSize()

This convenience function is equivalent to calling setContentsSize (QSize()).

PySide6.QtQuick.QQuickPaintedItem.setContentsScale(arg__1)

Parameters

arg__1 – float

This property holds Obsolete method for scaling the contents..

This function is provided for compatibility, use size() in combination with textureSize() to decide the size of what you are drawing.

See also

width() height() textureSize()

PySide6.QtQuick.QQuickPaintedItem.setContentsSize(arg__1)

Parameters

arg__1 – PySide6.QtCore.QSize

This property holds Obsolete method for setting the contents size..

This function is provided for compatibility, use size in combination with textureSize to decide the size of what you are drawing.

See also

width() height() textureSize()

PySide6.QtQuick.QQuickPaintedItem.setFillColor(arg__1)

Parameters

arg__1 – PySide6.QtGui.QColor

This property holds The item’s background fill color..

By default, the fill color is set to transparent .

PySide6.QtQuick.QQuickPaintedItem.setMipmap(enable)

Parameters

enable – bool

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

See also

mipmap()

PySide6.QtQuick.QQuickPaintedItem.setOpaquePainting(opaque)

Parameters

opaque – bool

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

See also

opaquePainting()

PySide6.QtQuick.QQuickPaintedItem.setPerformanceHint(hint[, enabled=true])

Parameters

• hint – PerformanceHint

• enabled – bool

Sets the given performance hint on the item if enabled is true; otherwise clears the performance hint.

By default, no performance hint is enabled/

See also

setPerformanceHints() performanceHints()

PySide6.QtQuick.QQuickPaintedItem.setPerformanceHints(hints)

Parameters

hints – PerformanceHints

Sets the performance hints to hints

By default, no performance hint is enabled/

See also

setPerformanceHint() performanceHints()

PySide6.QtQuick.QQuickPaintedItem.setRenderTarget(target)

Parameters

target – RenderTarget

This property holds The item’s render target..

This property defines which render target the QPainter renders into, it can be either Image , FramebufferObject or 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.

Warning

Resizing a framebuffer object is a costly operation, avoid using the FramebufferObject render target if the item gets resized often.

By default, the render target is Image .

PySide6.QtQuick.QQuickPaintedItem.setTextureSize(size)

Parameters

size – PySide6.QtCore.QSize

This property 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.

Note

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.

PySide6.QtQuick.QQuickPaintedItem.textureSize()

Return type

PySide6.QtCore.QSize

This property 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.

Note

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.

PySide6.QtQuick.QQuickPaintedItem.textureSizeChanged()

PySide6.QtQuick.QQuickPaintedItem.update([rect=QRect()])

Parameters

rect – PySide6.QtCore.QRect

Schedules a redraw of the area covered by rect in this item. You can call this function whenever your item needs to be redrawn, such as if it changes appearance or size.

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.

See also

paint()