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 |
Public Types
| enum | PerformanceHint { FastFBOResizing } |
| enum | RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject } |
Properties
- fillColor : QColor
- renderTarget : RenderTarget
- textureSize : QSize
Public Functions
| QColor | fillColor() const |
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setFillColor(const QColor &) |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
| void | setTextureSize(const QSize &size) |
| QSize | textureSize() const |
Signals
| void | fillColorChanged() |
| void | renderTargetChanged() |
| void | 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 can be either a QImage or, when OpenGL is in use, 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. 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 QQuickPaintedItem::RenderTarget and QQuickPaintedItem::renderTarget.
Member Type Documentation
enum QQuickPaintedItem::PerformanceHint
This enum describes flags that you can enable to improve rendering performance in QQuickPaintedItem. By default, none of these flags are set.
| Constant | Value | Description |
|---|---|---|
QQuickPaintedItem::FastFBOResizing | 0x1 | Resizing an FBO can be a costly operation on a few OpenGL driver implementations. To work around this, one can set this flag to let the QQuickPaintedItem allocate one large framebuffer object and instead draw into a subregion of it. This saves the resize at the cost of using more memory. Please note that this is not a common problem. |
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.
| Constant | Value | Description |
|---|---|---|
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 | QPainter 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::InvertedYFramebufferObject | 2 | Exactly 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
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 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.
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.
Note: Some Qt Quick backends may not support all render target options. For example, it is likely that non-OpenGL backends will lack support for QQuickPaintedItem::FramebufferObject and QQuickPaintedItem::InvertedYFramebufferObject. Requesting these will then be ignored.
Access functions:
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
Notifier signal:
| void | renderTargetChanged() |
textureSize : QSize
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.
Access functions:
| QSize | textureSize() const |
| void | setTextureSize(const QSize &size) |
Notifier signal:
| void | textureSizeChanged() |