QPaintEngine Class

The QPaintEngine class provides an abstract definition of how QPainter draws to a given device on a given platform. More...

Header: #include <QPaintEngine>

Public Types

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 }

Public Functions

QPaintEngine(PaintEngineFeatures caps = PaintEngineFeatures())
virtual ~QPaintEngine()
virtual bool begin(QPaintDevice *pdev) = 0
void clearDirty(DirtyFlags df)
virtual QPoint coordinateOffset() const
virtual QPixmap createPixmap(QSize size)
virtual QPixmap createPixmapFromImage(QImage image, Qt::ImageConversionFlags flags = Qt::AutoColor)
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, PolygonDrawMode mode)
virtual void drawPolygon(const QPoint *points, int pointCount, 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
void fix_neg_rect(int *x, int *y, int *w, int *h)
bool hasFeature(PaintEngineFeatures feature) const
bool isActive() const
bool isExtended() const
QPaintDevice *paintDevice() const
QPainter *painter() const
void setActive(bool state)
void setDirty(DirtyFlags df)
void setPaintDevice(QPaintDevice *device)
void setSystemClip(const QRegion &region)
void setSystemRect(const QRect &rect)
void syncState()
QRegion systemClip() const
QRect systemRect() const
bool testDirty(DirtyFlags df)
virtual Type type() const = 0
virtual void updateState(const QPaintEngineState &state) = 0

Protected Functions

QPaintEngine(QPaintEnginePrivate &dptr, PaintEngineFeatures caps = PaintEngineFeatures())

Detailed Description

\ingrouppainting \inmodule QtGui

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.

Member Type Documentation

enum QPaintEngine::DirtyFlag
flags QPaintEngine::DirtyFlags

ConstantValueDescription
QPaintEngine::DirtyPen0x0001The pen is dirty and needs to be updated.
QPaintEngine::DirtyBrush0x0002The brush is dirty and needs to be updated.
QPaintEngine::DirtyBrushOrigin0x0004The brush origin is dirty and needs to updated.
QPaintEngine::DirtyFont0x0008The font is dirty and needs to be updated.
QPaintEngine::DirtyBackground0x0010The background is dirty and needs to be updated.
QPaintEngine::DirtyBackgroundMode0x0020The background mode is dirty and needs to be updated.
QPaintEngine::DirtyTransform0x0040The transform is dirty and needs to be updated.
QPaintEngine::DirtyClipRegion0x0080The clip region is dirty and needs to be updated.
QPaintEngine::DirtyClipPath0x0100The clip path is dirty and needs to be updated.
QPaintEngine::DirtyHints0x0200The render hints is dirty and needs to be updated.
QPaintEngine::DirtyCompositionMode0x0400The composition mode is dirty and needs to be updated.
QPaintEngine::DirtyClipEnabled0x0800Whether clipping is enabled or not is dirty and needs to be updated.
QPaintEngine::DirtyOpacity0x1000The constant opacity has changed and needs to be updated as part of the state change in QPaintEngine::updateState().
QPaintEngine::AllDirty0xffffConvenience 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.

enum QPaintEngine::PaintEngineFeature
flags QPaintEngine::PaintEngineFeatures

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.

ConstantValueDescription
QPaintEngine::AlphaBlend0x00000080The engine can alpha blend primitives.
QPaintEngine::Antialiasing0x00000400The engine can use antialiasing to improve the appearance of rendered primitives.
QPaintEngine::BlendModes0x00008000The engine supports blending modes.
QPaintEngine::BrushStroke0x00000800The engine supports drawing strokes that contain brushes as fills, not just solid colors (e.g. a dashed gradient line of width 2).
QPaintEngine::ConicalGradientFill0x00000040The engine supports conical gradient fills.
QPaintEngine::ConstantOpacity0x00001000The engine supports the feature provided by QPainter::setOpacity().
QPaintEngine::LinearGradientFill0x00000010The engine supports linear gradient fills.
QPaintEngine::MaskedBrush0x00002000The engine is capable of rendering brushes that has a texture with an alpha channel or a mask.
QPaintEngine::ObjectBoundingModeGradients0x00010000The 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::PainterPaths0x00000200The engine has path support.
QPaintEngine::PaintOutsidePaintEvent0x20000000The engine is capable of painting outside of paint events.
QPaintEngine::PatternBrush0x00000008The engine is capable of rendering brushes with the brush patterns specified in Qt::BrushStyle.
QPaintEngine::PatternTransform0x00000002The engine has support for transforming brush patterns.
QPaintEngine::PerspectiveTransform0x00004000The engine has support for performing perspective transformations on primitives.
QPaintEngine::PixmapTransform0x00000004The engine can transform pixmaps, including rotation and shearing.
QPaintEngine::PorterDuff0x00000100The engine supports Porter-Duff operations
QPaintEngine::PrimitiveTransform0x00000001The engine has support for transforming drawing primitives.
QPaintEngine::RadialGradientFill0x00000020The engine supports radial gradient fills.
QPaintEngine::RasterOpModes0x00020000The engine supports bitwise raster operations.
QPaintEngine::AllFeatures0xffffffffAll 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.

enum QPaintEngine::PolygonDrawMode

ConstantValueDescription
QPaintEngine::OddEvenMode0The polygon should be drawn using OddEven fill rule.
QPaintEngine::WindingMode1The polygon should be drawn using Winding fill rule.
QPaintEngine::ConvexMode2The polygon is a convex polygon and can be drawn using specialized algorithms where available.
QPaintEngine::PolylineMode3Only the outline of the polygon should be drawn.

enum QPaintEngine::Type

ConstantValueDescription
QPaintEngine::X110 
QPaintEngine::Windows1 
QPaintEngine::MacPrinter4 
QPaintEngine::CoreGraphics3macOS's Quartz2D (CoreGraphics)
QPaintEngine::QuickDraw2macOS's QuickDraw
QPaintEngine::QWindowSystem5Qt for Embedded Linux
QPaintEngine::OpenGL6 
QPaintEngine::Picture7QPicture format
QPaintEngine::SVG8Scalable Vector Graphics XML format
QPaintEngine::Raster9 
QPaintEngine::Direct3D10Windows only, Direct3D based engine
QPaintEngine::Pdf11Portable Document Format
QPaintEngine::OpenVG12 
QPaintEngine::User50First user type ID
QPaintEngine::MaxUser100Last user type ID
QPaintEngine::OpenGL213 
QPaintEngine::PaintBuffer14 
QPaintEngine::Blitter15 
QPaintEngine::Direct2D16Windows only, Direct2D based engine

Member Function Documentation

[explicit] QPaintEngine::QPaintEngine(PaintEngineFeatures caps = PaintEngineFeatures())

Creates a paint engine with the featureset specified by caps.

[protected] QPaintEngine::QPaintEngine(QPaintEnginePrivate &dptr, PaintEngineFeatures caps = PaintEngineFeatures())

\internal

[virtual noexcept] 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().

void QPaintEngine::clearDirty(DirtyFlags df)

\internal

[virtual] QPoint QPaintEngine::coordinateOffset() const

\internal

Returns the offset from the painters origo to the engines origo. This value is used by QPainter for engines who have internal double buffering.

This function only makes sense when the engine is active.

[virtual] QPixmap QPaintEngine::createPixmap(QSize size)

\internal

Creates a QPixmap optimized for this paint engine and device.

[virtual] QPixmap QPaintEngine::createPixmapFromImage(QImage image, Qt::ImageConversionFlags flags = Qt::AutoColor)

\internal

Creates a QPixmap optimized for this paint engine and device.

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

void QPaintEngine::fix_neg_rect(int *x, int *y, int *w, int *h)

\internal

bool QPaintEngine::hasFeature(PaintEngineFeatures feature) const

Returns true if the paint engine supports the specified feature; otherwise returns false.

bool QPaintEngine::isActive() const

Returns true if the paint engine is actively drawing; otherwise returns false.

See also setActive().

bool QPaintEngine::isExtended() const

\internal

Returns true if the paint engine is a QPaintEngineEx derivative.

QPaintDevice *QPaintEngine::paintDevice() const

Returns the device that this engine is painting on, if painting is active; otherwise returns nullptr.

See also setPaintDevice().

QPainter *QPaintEngine::painter() const

Returns the paint engine's painter.

void QPaintEngine::setActive(bool state)

Sets the active state of the paint engine to state.

See also isActive().

void QPaintEngine::setDirty(DirtyFlags df)

\internal

void QPaintEngine::setPaintDevice(QPaintDevice *device)

\internalSets the paintdevice that this engine operates on to device

See also paintDevice().

void QPaintEngine::setSystemClip(const QRegion &region)

\internal

Sets the system clip for this engine. The system clip defines the basis area that the engine has to draw in. All clips that are set will be an intersection with the system clip.

Reset the systemclip to no clip by setting an empty region.

See also systemClip().

void QPaintEngine::setSystemRect(const QRect &rect)

\internal

Sets the target rect for drawing within the backing store. This function should ONLY be used by the backing store.

See also systemRect().

void QPaintEngine::syncState()

\internal

Updates all dirty states in this engine. This function should ONLY be used when drawing with native handles directly and immediate sync from QPainters state to the native state is required.

QRegion QPaintEngine::systemClip() const

\internal

Returns the system clip. The system clip is read only while the painter is active. An empty region indicates that system clip is not in use.

See also setSystemClip().

QRect QPaintEngine::systemRect() const

\internal

Retrieves the rect for drawing within the backing store. This function should ONLY be used by the backing store.

See also setSystemRect().

bool QPaintEngine::testDirty(DirtyFlags df)

\internal

[pure virtual] Type QPaintEngine::type() const

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