1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6 \title Painting Classes
9 \brief Classes that provide support for painting.
11 See also this introduction to the \l{coordsys.html}{Qt coordinate system.}
16 \title Rendering in 3D
19 \brief Classes that provide support for rendering in 3D.
23 \page paintsystem.html
25 \brief A system for painting on the screen or on print devices using the same API
27 \ingroup frameworks-technologies
28 \ingroup qt-basic-concepts
31 Qt's paint system enables painting on screen and print devices
32 using the same API, and is primarily based on the QPainter,
33 QPaintDevice, and QPaintEngine classes.
35 QPainter is used to perform drawing operations, QPaintDevice is an
36 abstraction of a two-dimensional space that can be painted on
37 using a QPainter, and QPaintEngine provides the interface that the
38 painter uses to draw onto different types of devices. The
39 QPaintEngine class is used internally by QPainter and
40 QPaintDevice, and is hidden from application programmers unless
41 they create their own device type.
43 \image paintsystem-core.png
45 The main benefit of this approach is that all painting follows the
46 same painting pipeline making it easy to add support for new
47 features and providing default implementations for unsupported
52 \li \l{Classes for Painting}
53 \li \l{Paint Devices and Backends}
54 \li \l{Drawing and Filling}
55 \li \l{Coordinate System}
56 \li \l{Reading and Writing Image Files}
59 \section1 Classes for Painting
61 These classes provide support for painting onto a paint device.
63 \annotatedlist painting
69 \page paintsystem-devices.html
70 \title Paint Devices and Backends
72 \nextpage Drawing and Filling
74 \section1 Creating a Paint Device
76 The QPaintDevice class is the base class of objects that can be
77 painted, i.e. QPainter can draw on any QPaintDevice
78 subclass. QPaintDevice's drawing capabilities are among others
79 implemented by QWidget, QImage, QPixmap, QPicture, QPrinter, and
86 The QWidget class is the base class of user interface
87 elements in the \l {Qt Widgets} module. It receives mouse, keyboard
88 and other events from the window system, and paints a
89 representation of itself on the screen.
93 The QImage class provides a hardware-independent image
94 representation which is designed and optimized for I/O, and for
95 direct pixel access and manipulation. QImage supports several
96 image formats including monochrome, 8-bit, 32-bit and
99 One advantage of using QImage as a paint device is that it is
100 possible to guarantee the pixel exactness of any drawing operation
101 in a platform-independent way. Another benefit is that the
102 painting can be performed in another thread than the current GUI
107 The QPixmap class is an off-screen image representation which is
108 designed and optimized for showing images on screen. Unlike
109 QImage, the pixel data in a pixmap is internal and is managed by
110 the underlying window system, i.e. pixels can only be accessed
111 through QPainter functions or by converting the QPixmap to a
114 To optimize drawing with QPixmap, Qt provides the QPixmapCache
115 class which can be used to store temporary pixmaps that are
116 expensive to generate without using more storage space than the
119 Qt also provides the QBitmap convenience class, inheriting
120 QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and
121 is mainly used for creating custom QCursor and QBrush objects,
122 constructing QRegion objects.
124 \row \li \b {OpenGL Paint Device}
126 As mentioned previously, Qt is offering classes that makes it easy
127 to use OpenGL in Qt applications. For example, the QOpenGLPaintDevice
128 enables the OpenGL API for rendering with QPainter.
130 \row \li \b {Picture}
132 The QPicture class is a paint device that records and replays
133 QPainter commands. A picture serializes painter commands to an IO
134 device in a platform-independent format. QPicture is also
135 resolution independent, i.e. a QPicture can be displayed on
136 different devices (for example svg, pdf, ps, printer and screen)
139 Qt provides the QPicture::load() and QPicture::save() functions
140 as well as streaming operators for loading and saving pictures.
144 \row \li \b {Custom Backends}
146 Support for a new backend can be implemented by deriving from the
147 QPaintDevice class and reimplementing the virtual
148 QPaintDevice::paintEngine() function to tell QPainter which paint
149 engine should be used to draw on this particular device. To
150 actually be able to draw on the device, this paint engine must be
151 a custom paint engine created by deriving from the QPaintEngine
159 \page paintsystem-drawing.html
160 \title Drawing and Filling
162 \previouspage Paint Devices and Backends
163 \nextpage Coordinate System
167 QPainter provides highly optimized functions to do most of the
168 drawing GUI programs require. It can draw everything from simple
169 graphical primitives (represented by the QPoint, QLine, QRect,
170 QRegion and QPolygon classes) to complex shapes like vector
171 paths. In Qt vector paths are represented by the QPainterPath
172 class. QPainterPath provides a container for painting operations,
173 enabling graphical shapes to be constructed and reused.
177 \li \image paintsystem-painterpath.png
180 A painter path is an object composed of lines and curves. For
181 example, a rectangle is composed by lines and an ellipse is
184 The main advantage of painter paths over normal drawing operations
185 is that complex shapes only need to be created once; then they can
186 be drawn many times using only calls to the QPainter::drawPath()
189 A QPainterPath object can be used for filling, outlining, and
190 clipping. To generate fillable outlines for a given painter path,
191 use the QPainterPathStroker class.
195 Lines and outlines are drawn using the QPen class. A pen is
196 defined by its style (i.e. its line-type), width, brush, how the
197 endpoints are drawn (cap-style) and how joins between two
198 connected lines are drawn (join-style). The pen's brush is a
199 QBrush object used to fill strokes generated with the pen,
200 i.e. the QBrush class defines the fill pattern.
202 QPainter can also draw aligned text and pixmaps.
204 When drawing text, the font is specified using the QFont class. Qt
205 will use the font with the specified attributes, or if no matching
206 font exists, Qt will use the closest matching installed font. The
207 attributes of the font that is actually used can be retrieved
208 using the QFontInfo class. In addition, the QFontMetrics class
209 provides the font measurements, and the QFontDatabase class
210 provides information about the fonts available in the underlying
213 Normally, QPainter draws in a "natural" coordinate system, but it
214 is able to perform view and world transformations using the
215 QTransform class. For more information, see \l {Coordinate
216 System}, which also describes the rendering process, i.e. the
217 relation between the logical representation and the rendered
218 pixels, and the benefits of anti-aliased painting.
222 \b {Anti-Aliased Painting}
224 When drawing, the pixel rendering is controlled by the
225 QPainter::Antialiasing render hint. The QPainter::RenderHint enum
226 is used to specify flags to QPainter that may or may not be
227 respected by any given engine.
229 The QPainter::Antialiasing value indicates that the engine should
230 antialias edges of primitives if possible, i.e. smoothing the
231 edges by using different color intensities.
233 \li \image paintsystem-antialiasing.png
239 Shapes are filled using the QBrush class. A brush is defined
240 by its color and its style (i.e. its fill pattern).
242 Any color in Qt is represented by the QColor class which supports
243 the RGB, HSV and CMYK color models. QColor also support
244 alpha-blended outlining and filling (specifying the transparency
245 effect), and the class is platform and device independent (the
246 colors are mapped to hardware using the QColormap class). For more
247 information, see the QColor class documentation.
249 The available fill patterns are described by the Qt::BrushStyle
250 enum. These include basic patterns spanning from uniform color to
251 very sparse pattern, various line combinations, gradient fills and
252 textures. Qt provides the QGradient class to define custom
253 gradient fills, while texture patterns are specified using the
258 \li \image paintsystem-fancygradient.png
261 The QGradient class is used in combination with QBrush to specify
264 \image paintsystem-gradients.png
266 Qt currently supports three types of gradient fills: Linear
267 gradients interpolate colors between start and end points, radial
268 gradients interpolate colors between a focal point and end points
269 on a circle surrounding it, and conical gradients interpolate
270 colors around a center point.
276 \page paintsystem-images.html
277 \title Reading and Writing Image Files
279 \previouspage Coordinate System
281 The most common way to read images is through QImage and QPixmap's
282 constructors, or by calling the QImage::load() and QPixmap::load()
283 functions. In addition, Qt provides the QImageReader class which
284 gives more control over the process. Depending on the underlying
285 support in the image format, the functions provided by the class
286 can save memory and speed up loading of images.
288 Likewise, Qt provides the QImageWriter class which supports
289 setting format specific options, such as the gamma level,
290 compression level and quality, prior to storing the image. If you
291 do not need such options, you can use QImage::save() or
292 QPixmap::save() instead.
298 QMovie is a convenience class for displaying animations, using the
299 QImageReader class internally. Once created, the QMovie class
300 provides various functions for both running and controlling the
303 \li \image paintsystem-movie.png
306 The QImageReader and QImageWriter classes rely on the
307 QImageIOHandler class which is the common image I/O interface for
308 all image formats in Qt. QImageIOHandler objects are used
309 internally by QImageReader and QImageWriter to add support for
310 different image formats to Qt.
312 A list of the supported file formats are available through the
313 QImageReader::supportedImageFormats() and
314 QImageWriter::supportedImageFormats() functions. Qt supports
315 several file formats by default, and in addition new formats can
316 be added as plugins. The currently supported formats are listed in
317 the QImageReader and QImageWriter class documentation.
319 Qt's plugin mechanism can also be used to write a custom image
320 format handler. This is done by deriving from the QImageIOHandler
321 class, and creating a QImageIOPlugin object which is a factory for
322 creating QImageIOHandler objects. When the plugin is installed,
323 QImageReader and QImageWriter will automatically load the plugin
1.10.0