The QPaintEngine class provides an abstract definition of how QPainter draws to a given device on a given platform. More...
| Header: | #include <QPaintEngine> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| enum | DirtyFlag { DirtyPen, DirtyBrush, DirtyBrushOrigin, DirtyFont, DirtyBackground, …, AllDirty } |
| flags | DirtyFlags |
| enum | PaintEngineFeature { AlphaBlend, Antialiasing, BlendModes, BrushStroke, ConicalGradientFill, …, AllFeatures } |
| flags | PaintEngineFeatures |
| enum | PolygonDrawMode { OddEvenMode, WindingMode, ConvexMode, PolylineMode } |
| enum | Type { X11, Windows, MacPrinter, CoreGraphics, QuickDraw, …, Direct2D } |
| QPaintEngine(QPaintEngine::PaintEngineFeatures caps = PaintEngineFeatures()) | |
| virtual | ~QPaintEngine() |
| virtual bool | begin(QPaintDevice *pdev) = 0 |
| virtual void | drawEllipse(const QRectF &rect) |
| virtual void | drawEllipse(const QRect &rect) |
| virtual void | drawImage(const QRectF &rectangle, const QImage &image, const QRectF &sr, Qt::ImageConversionFlags flags = Qt::AutoColor) |
| virtual void | drawLines(const QLineF *lines, int lineCount) |
| virtual void | drawLines(const QLine *lines, int lineCount) |
| virtual void | drawPath(const QPainterPath &path) |
| virtual void | drawPixmap(const QRectF &r, const QPixmap &pm, const QRectF &sr) = 0 |
| virtual void | drawPoints(const QPointF *points, int pointCount) |
| virtual void | drawPoints(const QPoint *points, int pointCount) |
| virtual void | drawPolygon(const QPointF *points, int pointCount, QPaintEngine::PolygonDrawMode mode) |
| virtual void | drawPolygon(const QPoint *points, int pointCount, QPaintEngine::PolygonDrawMode mode) |
| virtual void | drawRects(const QRectF *rects, int rectCount) |
| virtual void | drawRects(const QRect *rects, int rectCount) |
| virtual void | drawTextItem(const QPointF &p, const QTextItem &textItem) |
| virtual void | drawTiledPixmap(const QRectF &rect, const QPixmap &pixmap, const QPointF &p) |
| virtual bool | end() = 0 |
| bool | hasFeature(QPaintEngine::PaintEngineFeatures feature) const |
| bool | isActive() const |
| QPaintDevice * | paintDevice() const |
| QPainter * | painter() const |
| void | setActive(bool state) |
| virtual QPaintEngine::Type | type() const = 0 |
| virtual void | updateState(const QPaintEngineState &state) = 0 |
Qt provides several premade implementations of QPaintEngine for the different painter backends we support. The primary paint engine provided is the raster paint engine, which contains a software rasterizer which supports the full feature set on all supported platforms. This is the default for painting on QWidget-based classes in e.g. on Windows, X11 and macOS, it is the backend for painting on QImage and it is used as a fallback for paint engines that do not support a certain capability. In addition we provide QPaintEngine implementations for OpenGL (accessible through QOpenGLWidget) and printing (which allows using QPainter to draw on a QPrinter object).
If one wants to use QPainter to draw to a different backend, one must subclass QPaintEngine and reimplement all its virtual functions. The QPaintEngine implementation is then made available by subclassing QPaintDevice and reimplementing the virtual function QPaintDevice::paintEngine().
QPaintEngine is created and owned by the QPaintDevice that created it.
See also QPainter, QPaintDevice::paintEngine(), and Paint System.
| Constant | Value | Description |
|---|---|---|
QPaintEngine::DirtyPen |
0x0001 |
The pen is dirty and needs to be updated. |
QPaintEngine::DirtyBrush |
0x0002 |
The brush is dirty and needs to be updated. |
QPaintEngine::DirtyBrushOrigin |
0x0004 |
The brush origin is dirty and needs to updated. |
QPaintEngine::DirtyFont |
0x0008 |
The font is dirty and needs to be updated. |
QPaintEngine::DirtyBackground |
0x0010 |
The background is dirty and needs to be updated. |
QPaintEngine::DirtyBackgroundMode |
0x0020 |
The background mode is dirty and needs to be updated. |
QPaintEngine::DirtyTransform |
0x0040 |
The transform is dirty and needs to be updated. |
QPaintEngine::DirtyClipRegion |
0x0080 |
The clip region is dirty and needs to be updated. |
QPaintEngine::DirtyClipPath |
0x0100 |
The clip path is dirty and needs to be updated. |
QPaintEngine::DirtyHints |
0x0200 |
The render hints is dirty and needs to be updated. |
QPaintEngine::DirtyCompositionMode |
0x0400 |
The composition mode is dirty and needs to be updated. |
QPaintEngine::DirtyClipEnabled |
0x0800 |
Whether clipping is enabled or not is dirty and needs to be updated. |
QPaintEngine::DirtyOpacity |
0x1000 |
The constant opacity has changed and needs to be updated as part of the state change in QPaintEngine::updateState(). |
QPaintEngine::AllDirty |
0xffff |
Convenience enum used internally. |
These types are used by QPainter to trigger lazy updates of the various states in the QPaintEngine using QPaintEngine::updateState().
A paint engine must update every dirty state.
The DirtyFlags type is a typedef for QFlags<DirtyFlag>. It stores an OR combination of DirtyFlag values.
This enum is used to describe the features or capabilities that the paint engine has. If a feature is not supported by the engine, QPainter will do a best effort to emulate that feature through other means and pass on an alpha blended QImage to the engine with the emulated results. Some features cannot be emulated: AlphaBlend and PorterDuff.
| Constant | Value | Description |
|---|---|---|
QPaintEngine::AlphaBlend |
0x00000080 |
The engine can alpha blend primitives. |
QPaintEngine::Antialiasing |
0x00000400 |
The engine can use antialiasing to improve the appearance of rendered primitives. |
QPaintEngine::BlendModes |
0x00008000 |
The engine supports blending modes. |
QPaintEngine::BrushStroke |
0x00000800 |
The engine supports drawing strokes that contain brushes as fills, not just solid colors (e.g. a dashed gradient line of width 2). |
QPaintEngine::ConicalGradientFill |
0x00000040 |
The engine supports conical gradient fills. |
QPaintEngine::ConstantOpacity |
0x00001000 |
The engine supports the feature provided by QPainter::setOpacity(). |
QPaintEngine::LinearGradientFill |
0x00000010 |
The engine supports linear gradient fills. |
QPaintEngine::MaskedBrush |
0x00002000 |
The engine is capable of rendering brushes that has a texture with an alpha channel or a mask. |
QPaintEngine::ObjectBoundingModeGradients |
0x00010000 |
The engine has native support for gradients with coordinate mode QGradient::ObjectBoundingMode. Otherwise, if QPaintEngine::PatternTransform is supported, object bounding mode gradients are converted to gradients with coordinate mode QGradient::LogicalMode and a brush transform for the coordinate mapping. |
QPaintEngine::PainterPaths |
0x00000200 |
The engine has path support. |
QPaintEngine::PaintOutsidePaintEvent |
0x20000000 |
The engine is capable of painting outside of paint events. |
QPaintEngine::PatternBrush |
0x00000008 |
The engine is capable of rendering brushes with the brush patterns specified in Qt::BrushStyle. |
QPaintEngine::PatternTransform |
0x00000002 |
The engine has support for transforming brush patterns. |
QPaintEngine::PerspectiveTransform |
0x00004000 |
The engine has support for performing perspective transformations on primitives. |
QPaintEngine::PixmapTransform |
0x00000004 |
The engine can transform pixmaps, including rotation and shearing. |
QPaintEngine::PorterDuff |
0x00000100 |
The engine supports Porter-Duff operations |
QPaintEngine::PrimitiveTransform |
0x00000001 |
The engine has support for transforming drawing primitives. |
QPaintEngine::RadialGradientFill |
0x00000020 |
The engine supports radial gradient fills. |
QPaintEngine::RasterOpModes |
0x00020000 |
The engine supports bitwise raster operations. |
QPaintEngine::AllFeatures |
0xffffffff |
All of the above features. This enum value is usually used as a bit mask. |
The PaintEngineFeatures type is a typedef for QFlags<PaintEngineFeature>. It stores an OR combination of PaintEngineFeature values.
| Constant | Value | Description |
|---|---|---|
QPaintEngine::OddEvenMode |
0 |
The polygon should be drawn using OddEven fill rule. |
QPaintEngine::WindingMode |
1 |
The polygon should be drawn using Winding fill rule. |
QPaintEngine::ConvexMode |
2 |
The polygon is a convex polygon and can be drawn using specialized algorithms where available. |
QPaintEngine::PolylineMode |
3 |
Only the outline of the polygon should be drawn. |
| Constant | Value | Description |
|---|---|---|
QPaintEngine::X11 |
0 |
|
QPaintEngine::Windows |
1 |
|
QPaintEngine::MacPrinter |
4 |
|
QPaintEngine::CoreGraphics |
3 |
macOS's Quartz2D (CoreGraphics) |
QPaintEngine::QuickDraw |
2 |
macOS's QuickDraw |
QPaintEngine::QWindowSystem |
5 |
Qt for Embedded Linux |
QPaintEngine::OpenGL |
6 |
|
QPaintEngine::Picture |
7 |
QPicture format |
QPaintEngine::SVG |
8 |
Scalable Vector Graphics XML format |
QPaintEngine::Raster |
9 |
|
QPaintEngine::Direct3D |
10 |
Windows only, Direct3D based engine |
QPaintEngine::Pdf |
11 |
Portable Document Format |
QPaintEngine::OpenVG |
12 |
|
QPaintEngine::User |
50 |
First user type ID |
QPaintEngine::MaxUser |
100 |
Last user type ID |
QPaintEngine::OpenGL2 |
13 |
|
QPaintEngine::PaintBuffer |
14 |
|
QPaintEngine::Blitter |
15 |
|
QPaintEngine::Direct2D |
16 |
Windows only, Direct2D based engine |
Creates a paint engine with the featureset specified by caps.
[virtual] QPaintEngine::~QPaintEngine()Destroys the paint engine.
[pure virtual] bool QPaintEngine::begin(QPaintDevice *pdev)Reimplement this function to initialise your paint engine when painting is to start on the paint device pdev. Return true if the initialization was successful; otherwise return false.
See also end() and isActive().
[virtual] void QPaintEngine::drawEllipse(const QRectF &rect)Reimplement this function to draw the largest ellipse that can be contained within rectangle rect.
The default implementation calls drawPolygon().
[virtual] void QPaintEngine::drawEllipse(const QRect &rect)The default implementation of this function calls the floating point version of this function
[virtual] void QPaintEngine::drawImage(const QRectF &rectangle, const
QImage &image, const QRectF &sr, Qt::ImageConversionFlags flags = Qt::AutoColor)Reimplement this function to draw the part of the image specified by the sr rectangle in the given rectangle using the given conversion flags flags, to convert it to a pixmap.
[virtual] void QPaintEngine::drawLines(const QLineF *lines,
int lineCount)The default implementation splits the list of lines in lines into lineCount separate calls to drawPath() or drawPolygon() depending on the feature set of the paint engine.
[virtual] void QPaintEngine::drawLines(const QLine *lines,
int lineCount)This is an overloaded function.
The default implementation converts the first lineCount lines in lines to a QLineF and calls the floating point version of this function.
[virtual] void QPaintEngine::drawPath(const QPainterPath
&path)The default implementation ignores the path and does nothing.
[pure virtual] void QPaintEngine::drawPixmap(const QRectF &r, const
QPixmap &pm, const QRectF &sr)Reimplement this function to draw the part of the pm specified by the sr rectangle in the given r.
[virtual] void QPaintEngine::drawPoints(const QPointF *points,
int pointCount)Draws the first pointCount points in the buffer points
[virtual] void QPaintEngine::drawPoints(const QPoint *points,
int pointCount)Draws the first pointCount points in the buffer points
The default implementation converts the first pointCount QPoints in points to QPointFs and calls the floating point version of drawPoints.
[virtual] void QPaintEngine::drawPolygon(const QPointF *points,
int pointCount, QPaintEngine::PolygonDrawMode mode)Reimplement this virtual function to draw the polygon defined by the pointCount first points in points, using mode mode.
Note: At least one of the drawPolygon() functions must be reimplemented.
[virtual] void QPaintEngine::drawPolygon(const QPoint *points,
int pointCount, QPaintEngine::PolygonDrawMode mode)This is an overloaded function.
Reimplement this virtual function to draw the polygon defined by the pointCount first points in points, using mode mode.
Note: At least one of the drawPolygon() functions must be reimplemented.
[virtual] void QPaintEngine::drawRects(const QRectF *rects,
int rectCount)Draws the first rectCount rectangles in the buffer rects. The default implementation of this function calls drawPath() or drawPolygon() depending on the feature set of the paint engine.
[virtual] void QPaintEngine::drawRects(const QRect *rects,
int rectCount)This is an overloaded function.
The default implementation converts the first rectCount rectangles in the buffer rects to a QRectF and calls the floating point version of this function.
[virtual] void QPaintEngine::drawTextItem(const QPointF &p, const
QTextItem &textItem)This function draws the text item textItem at position p. The default implementation of this function converts the text to a QPainterPath and paints the resulting path.
[virtual] void QPaintEngine::drawTiledPixmap(const QRectF
&rect, const QPixmap &pixmap, const QPointF &p)Reimplement this function to draw the pixmap in the given rect, starting at the given p. The pixmap will be drawn repeatedly until the rect is filled.
[pure virtual] bool QPaintEngine::end()Reimplement this function to finish painting on the current paint device. Return true if painting was finished successfully; otherwise return false.
See also begin() and isActive().
Returns true if the paint engine supports the specified feature; otherwise returns false.
Returns true if the paint engine is actively drawing; otherwise returns false.
See also setActive().
Returns the device that this engine is painting on, if painting is active; otherwise returns nullptr.
Returns the paint engine's painter.
Sets the active state of the paint engine to state.
See also isActive().
[pure virtual] QPaintEngine::Type QPaintEngine::type() constReimplement this function to return the paint engine Type.
[pure virtual] void QPaintEngine::updateState(const QPaintEngineState &state)Reimplement this function to update the state of a paint engine.
When implemented, this function is responsible for checking the paint engine's current state and update the properties that are changed. Use the QPaintEngineState::state() function to find out which properties that must be updated, then use the corresponding get function to retrieve the current values for the given properties.
See also QPaintEngineState.
