Qt Documentation

Contents

QQuickPaintedItem Class

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

Header: #include <QQuickPaintedItem>
qmake: QT += quick
Inherits: QQuickItem.
Inherited By:

Public Types

enum PerformanceHint { FastFBOResizing }
flags PerformanceHints
enum RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject }

Properties

Public Functions

QQuickPaintedItem(QQuickItem * parent = 0)
virtual ~QQuickPaintedItem()
bool antialiasing() const
QRectF contentsBoundingRect() const
qreal contentsScale() const
QSize contentsSize() const
QColor fillColor() const
bool mipmap() const
bool opaquePainting() const
virtual void paint(QPainter * painter) = 0
PerformanceHints performanceHints() const
RenderTarget renderTarget() const
void resetContentsSize()
void setAntialiasing(bool enable)
void setContentsScale(qreal)
void setContentsSize(const QSize &)
void setFillColor(const QColor &)
void setMipmap(bool enable)
void setOpaquePainting(bool opaque)
void setPerformanceHint(PerformanceHint hint, bool enabled = true)
void setPerformanceHints(PerformanceHints hints)
void setRenderTarget(RenderTarget target)
void update(const QRect & rect = QRect())

Reimplemented Public Functions

virtual bool isTextureProvider() const
virtual QSGTextureProvider * textureProvider() const

Signals

void contentsScaleChanged()
void contentsSizeChanged()
void fillColorChanged()
void renderTargetChanged()

Reimplemented Protected Functions

virtual void releaseResources()
virtual QSGNode * updatePaintNode(QSGNode * oldNode, UpdatePaintNodeData * data)
  • 33 protected functions inherited from QQuickItem
  • 9 protected functions inherited from QObject

Additional Inherited Members

  • 1 public slot inherited from QQuickItem
  • 1 public slot inherited from QObject
  • 11 static public members inherited from QObject
  • 33 protected functions inherited from QQuickItem
  • 9 protected functions inherited from QObject

Detailed Description

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

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 can be either a QImage or a QOpenGLFramebufferObject. When the render target is a QImage, QPainter first renders into the image then the content is uploaded to the texture. When a QOpenGLFramebufferObject is used, QPainter paints directly onto 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. To get the size of the area painted by the item, use contentsBoundingRect().

Starting Qt 5.4, the QQuickPaintedItem is a texture provider and can be used directly in ShaderEffects and other classes that consume texture providers.

Member Type Documentation

enum QQuickPaintedItem::​PerformanceHint
flags QQuickPaintedItem::​PerformanceHints

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

ConstantValueDescription
QQuickPaintedItem::FastFBOResizing0x1If your item gets resized often and you are using the QQuickPaintedItem::FramebufferObject render target, set this flag to true to reduce the item resizing time at the cost of using more graphics memory. Resizing a Framebuffer object is a costly operation, by enabling this property the Framebuffer Object will use a texture larger than the actual size of the item to avoid as much as possible resizing it.

The PerformanceHints type is a typedef for QFlags<PerformanceHint>. It stores an OR combination of PerformanceHint values.

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

ConstantValueDescription
QQuickPaintedItem::Image0The 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::FramebufferObject1QPainter paints into a QOpenGLFramebufferObject using the GL paint engine. Painting can be faster as no texture upload is required, but anti-aliasing quality is not as good as if using an image. This render target allows faster rendering in some cases, but you should avoid using it if the item is resized often.
QQuickPaintedItem::InvertedYFramebufferObject2Exactly as for FramebufferObject above, except once the painting is done, prior to rendering the painted image is flipped about the x-axis so that the top-most pixels are now at the bottom. Since this is done with the OpenGL texture coordinates it is a much faster way to achieve this effect than using a painter transform.

See also setRenderTarget().

Property Documentation

contentsScale : qreal

This property holds the scale of the contents.

All painting happening in paint() is scaled by the contents scale. This is distinct from the scale of the item in regards to scale().

The default value is 1.

Access functions:

qreal contentsScale() const
void setContentsScale(qreal)

Notifier signal:

void contentsScaleChanged()

contentsSize : QSize

This property holds the size of the contents.

The contents size is the size of the item in regards to how it is painted using the paint() function. This is distinct from the size of the item in regards to height() and width().

Access functions:

QSize contentsSize() const
void setContentsSize(const QSize &)

Notifier signal:

void contentsSizeChanged()

fillColor : QColor

This property holds the item's background fill color.

By default, the fill color is set to Qt::transparent.

Access functions:

QColor fillColor() const
void setFillColor(const QColor &)

Notifier signal:

void fillColorChanged()

renderTarget : RenderTarget

This property holds the item's render target.

This property defines which render target the QPainter renders into, it can be either QSGPaintedItem::Image, QSGPaintedItem::FramebufferObject or QSGPaintedItem::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 QQuickPaintedItem::FramebufferObject render target if the item gets resized often.

By default, the render target is QQuickPaintedItem::Image.

Access functions:

RenderTarget renderTarget() const
void setRenderTarget(RenderTarget target)

Notifier signal:

void renderTargetChanged()

Member Function Documentation

QQuickPaintedItem::​QQuickPaintedItem(QQuickItem * parent = 0)

Constructs a QQuickPaintedItem with the given parent item.

[virtual] QQuickPaintedItem::​~QQuickPaintedItem()

Destroys the QQuickPaintedItem.

bool QQuickPaintedItem::​antialiasing() const

Returns true if antialiased painting is enabled; otherwise, false is returned.

By default, antialiasing is not enabled.

See also setAntialiasing().

QRectF QQuickPaintedItem::​contentsBoundingRect() const

This function returns the outer bounds of the item as a rectangle; all painting must be restricted to inside an item's bounding rect.

If the contents size has not been set it reflects the size of the item; otherwise it reflects the contents size scaled by the contents scale.

Use this function to know the area painted by the item.

See also QQuickItem::width(), QQuickItem::height(), contentsSize(), and contentsScale().

[virtual] bool QQuickPaintedItem::​isTextureProvider() const

bool QQuickPaintedItem::​mipmap() const

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

By default, mipmapping is not enabled.

See also setMipmap().

bool QQuickPaintedItem::​opaquePainting() const

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

By default, painted items are not opaque.

See also 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 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 OpenGL rendering. 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.

PerformanceHints QQuickPaintedItem::​performanceHints() const

Returns the performance hints.

By default, no performance hint is enabled.

See also setPerformanceHint() and setPerformanceHints().

[virtual protected] void QQuickPaintedItem::​releaseResources()

void QQuickPaintedItem::​resetContentsSize()

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

void QQuickPaintedItem::​setAntialiasing(bool enable)

If enable is true, antialiased painting is enabled.

By default, antialiasing is not enabled.

See also antialiasing().

void QQuickPaintedItem::​setMipmap(bool enable)

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

void QQuickPaintedItem::​setOpaquePainting(bool opaque)

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

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

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() and performanceHints().

void QQuickPaintedItem::​setPerformanceHints(PerformanceHints hints)

Sets the performance hints to hints

By default, no performance hint is enabled/

See also setPerformanceHint() and performanceHints().

[virtual] QSGTextureProvider * QQuickPaintedItem::​textureProvider() const

void QQuickPaintedItem::​update(const QRect & rect = 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.

Note that calling this function will trigger a repaint of the whole scene.

See also paint().

[virtual protected] QSGNode * QQuickPaintedItem::​updatePaintNode(QSGNode * oldNode, UpdatePaintNodeData * data)

Reimplemented from QQuickItem::updatePaintNode().

© 2015 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.