1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
30 \title Painting Classes
33 \brief Classes that provide support for painting.
35 See also this introduction to the \link coordsys.html Qt
36 coordinate system. \endlink
41 \title Rendering in 3D
44 \brief Classes that provide support for rendering in 3D.
48 \page paintsystem.html
50 \brief A system for painting on the screen or on print devices using the same API
52 \ingroup frameworks-technologies
53 \ingroup qt-basic-concepts
56 Qt's paint system enables painting on screen and print devices
57 using the same API, and is primarily based on the QPainter,
58 QPaintDevice, and QPaintEngine classes.
60 QPainter is used to perform drawing operations, QPaintDevice is an
61 abstraction of a two-dimensional space that can be painted on
62 using a QPainter, and QPaintEngine provides the interface that the
63 painter uses to draw onto different types of devices. The
64 QPaintEngine class is used internally by QPainter and
65 QPaintDevice, and is hidden from application programmers unless
66 they create their own device type.
68 \image paintsystem-core.png
70 The main benefit of this approach is that all painting follows the
71 same painting pipeline making it easy to add support for new
72 features and providing default implementations for unsupported
77 \o \l{Classes for Painting}
78 \o \l{Paint Devices and Backends}
79 \o \l{Drawing and Filling}
80 \o \l{Coordinate System}
81 \o \l{Reading and Writing Image Files}
83 \o \l{Printing with Qt}
86 \section1 Classes for Painting
88 These classes provide support for painting onto a paint device.
90 \annotatedlist painting
92 Alternatively, Qt provides the QtOpenGL module, offering classes
93 that makes it easy to use OpenGL in Qt applications. Among others,
94 the module provides an OpenGL widget class that can be used just
95 like any other Qt widget, except that it opens an OpenGL display
96 buffer where the OpenGL API can be used to render the contents.
101 \page paintsystem-devices.html
102 \title Paint Devices and Backends
104 \contentspage The Paint System
105 \nextpage Drawing and Filling
107 \section1 Creating a Paint Device
109 The QPaintDevice class is the base class of objects that can be
110 painted, i.e. QPainter can draw on any QPaintDevice
111 subclass. QPaintDevice's drawing capabilities are currently
112 implemented by the QWidget, QImage, QPixmap, QGLWidget,
113 QGLPixelBuffer, QPicture and QPrinter subclasses.
115 \image paintsystem-devices.png
120 The QWidget class is the base class of all user interface
121 objects. The widget is the atom of the user interface: it receives
122 mouse, keyboard and other events from the window system, and
123 paints a representation of itself on the screen.
127 The QImage class provides a hardware-independent image
128 representation which is designed and optimized for I/O, and for
129 direct pixel access and manipulation. QImage supports several
130 image formats including monochrome, 8-bit, 32-bit and
131 alpha-blended images.
133 One advantage of using QImage as a paint device is that it is
134 possible to guarantee the pixel exactness of any drawing operation
135 in a platform-independent way. Another benefit is that the
136 painting can be performed in another thread than the current GUI
141 The QPixmap class is an off-screen image representation which is
142 designed and optimized for showing images on screen. Unlike
143 QImage, the pixel data in a pixmap is internal and is managed by
144 the underlying window system, i.e. pixels can only be accessed
145 through QPainter functions or by converting the QPixmap to a
148 To optimize drawing with QPixmap, Qt provides the QPixmapCache
149 class which can be used to store temporary pixmaps that are
150 expensive to generate without using more storage space than the
153 Qt also provides the QBitmap convenience class, inheriting
154 QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and
155 is mainly used for creating custom QCursor and QBrush objects,
156 constructing QRegion objects, and for setting masks for pixmaps
159 \row \o \bold {OpenGL Widget}
161 As mentioned previously, Qt provides the QtOpenGL module offering
162 classes that makes it easy to use OpenGL in Qt applications. For
163 example, the QGLWidget enables the OpenGL API for
166 But QGLWidget is also a QWidget subclass, and can be used by
167 QPainter as any other paint device. One huge benefit from this is
168 that it enables Qt to utilize the high performance of OpenGL for
169 most drawing operations, such as transformations and pixmap
172 \row \o \bold {Pixel Buffer}
174 The QtOpenGL module also provides the QGLPixelBuffer class which
175 inherits QPaintDevice directly.
177 QGLPixelBuffer encapsulates an OpenGL pbuffer. Rendering into a
178 pbuffer is normally done using full hardware acceleration which
179 can be significantly faster than rendering into a QPixmap.
181 \row \o \bold {Framebuffer Object}
183 The QtOpenGL module also provides the QGLFramebufferObject class
184 which inherits QPaintDevice directly.
186 QGLFramebufferObject encapsulates an OpenGL framebuffer object.
187 Framebuffer objects can also be used for off-screen rendering, and
188 offer several advantages over pixel buffers for this purpose.
189 These are described in the QGLFramebufferObject class documentation.
191 \row \o \bold {Picture}
193 The QPicture class is a paint device that records and replays
194 QPainter commands. A picture serializes painter commands to an IO
195 device in a platform-independent format. QPicture is also
196 resolution independent, i.e. a QPicture can be displayed on
197 different devices (for example svg, pdf, ps, printer and screen)
200 Qt provides the QPicture::load() and QPicture::save() functions
201 as well as streaming operators for loading and saving pictures.
203 \row \o \bold {Printer}
205 The QPrinter class is a paint device that paints on a printer. On
206 Windows or Mac OS X, QPrinter uses the built-in printer
207 drivers. On X11, QPrinter generates postscript and sends that to
208 lpr, lp, or another print program. QPrinter can also print to any
209 other QPrintEngine object.
211 The QPrintEngine class defines an interface for how QPrinter
212 interacts with a given printing subsystem. The common case when
213 creating your own print engine, is to derive from both
214 QPaintEngine and QPrintEngine.
216 The output format is by default determined by the platform the
217 printer is running on, but by explicitly setting the output format
218 to QPrinter::PdfFormat, QPrinter will generate its output as a PDF
221 \row \o \bold {Custom Backends}
223 Support for a new backend can be implemented by deriving from the
224 QPaintDevice class and reimplementing the virtual
225 QPaintDevice::paintEngine() function to tell QPainter which paint
226 engine should be used to draw on this particular device. To
227 actually be able to draw on the device, this paint engine must be
228 a custom paint engine created by deriving from the QPaintEngine
233 \section1 Selecting the Painting Backend
235 Since Qt 4.5, it is possible to replace the paint engines and paint
236 devices used for widgets, pixmaps and the offscreen double buffer. By
237 default the backends are:
242 \o Software Rasterizer
251 \o Software Rasterizer
254 Passing a command line parameter to the application, such as,
255 \c{-graphicssystem raster}, specifies that Qt should use the software
256 rasterizer for this application. The Software rasterizer is fully
257 supported on all platforms.
260 > analogclock -graphicssystem raster
263 There is also a \c{-graphicssystem opengl} mode that uses OpenGL for
264 all drawing. Currently, this engine is experimental as it does not draw
265 everything correctly.
267 Qt also supports being configured using \c {-graphicssystem
268 raster|opengl} in which case all applications will use the
269 specified graphics system for its graphics.
273 \page paintsystem-drawing.html
274 \title Drawing and Filling
276 \previouspage Paint Devices and Backends
277 \contentspage The Paint System
278 \nextpage Coordinate System
282 QPainter provides highly optimized functions to do most of the
283 drawing GUI programs require. It can draw everything from simple
284 graphical primitives (represented by the QPoint, QLine, QRect,
285 QRegion and QPolygon classes) to complex shapes like vector
286 paths. In Qt vector paths are represented by the QPainterPath
287 class. QPainterPath provides a container for painting operations,
288 enabling graphical shapes to be constructed and reused.
292 \o \image paintsystem-painterpath.png
293 \o \bold QPainterPath
295 A painter path is an object composed of lines and curves. For
296 example, a rectangle is composed by lines and an ellipse is
299 The main advantage of painter paths over normal drawing operations
300 is that complex shapes only need to be created once; then they can
301 be drawn many times using only calls to the QPainter::drawPath()
304 A QPainterPath object can be used for filling, outlining, and
305 clipping. To generate fillable outlines for a given painter path,
306 use the QPainterPathStroker class.
310 Lines and outlines are drawn using the QPen class. A pen is
311 defined by its style (i.e. its line-type), width, brush, how the
312 endpoints are drawn (cap-style) and how joins between two
313 connected lines are drawn (join-style). The pen's brush is a
314 QBrush object used to fill strokes generated with the pen,
315 i.e. the QBrush class defines the fill pattern.
317 QPainter can also draw aligned text and pixmaps.
319 When drawing text, the font is specified using the QFont class. Qt
320 will use the font with the specified attributes, or if no matching
321 font exists, Qt will use the closest matching installed font. The
322 attributes of the font that is actually used can be retrieved
323 using the QFontInfo class. In addition, the QFontMetrics class
324 provides the font measurements, and the QFontDatabase class
325 provides information about the fonts available in the underlying
328 Normally, QPainter draws in a "natural" coordinate system, but it
329 is able to perform view and world transformations using the
330 QTransform class. For more information, see \l {Coordinate
331 System}, which also describes the rendering process, i.e. the
332 relation between the logical representation and the rendered
333 pixels, and the benefits of anti-aliased painting.
337 \bold {Anti-Aliased Painting}
339 When drawing, the pixel rendering is controlled by the
340 QPainter::Antialiasing render hint. The QPainter::RenderHint enum
341 is used to specify flags to QPainter that may or may not be
342 respected by any given engine.
344 The QPainter::Antialiasing value indicates that the engine should
345 antialias edges of primitives if possible, i.e. smoothing the
346 edges by using different color intensities.
348 \o \image paintsystem-antialiasing.png
354 Shapes are filled using the QBrush class. A brush is defined
355 by its color and its style (i.e. its fill pattern).
357 Any color in Qt is represented by the QColor class which supports
358 the RGB, HSV and CMYK color models. QColor also support
359 alpha-blended outlining and filling (specifying the transparency
360 effect), and the class is platform and device independent (the
361 colors are mapped to hardware using the QColormap class). For more
362 information, see the QColor class documentation.
364 When creating a new widget, it is recommend to use the colors in
365 the widget's palette rather than hard-coding specific colors. All
366 widgets in Qt contain a palette and use their palette to draw
367 themselves. A widget's palette is represented by the QPalette
368 class which contains color groups for each widget state.
370 The available fill patterns are described by the Qt::BrushStyle
371 enum. These include basic patterns spanning from uniform color to
372 very sparse pattern, various line combinations, gradient fills and
373 textures. Qt provides the QGradient class to define custom
374 gradient fills, while texture patterns are specified using the
379 \o \image paintsystem-fancygradient.png
382 The QGradient class is used in combination with QBrush to specify
385 \image paintsystem-gradients.png
387 Qt currently supports three types of gradient fills: Linear
388 gradients interpolate colors between start and end points, radial
389 gradients interpolate colors between a focal point and end points
390 on a circle surrounding it, and conical gradients interpolate
391 colors around a center point.
397 \page paintsystem-images.html
398 \title Reading and Writing Image Files
400 \previouspage Coordinate System
401 \contentspage The Paint System
404 The most common way to read images is through QImage and QPixmap's
405 constructors, or by calling the QImage::load() and QPixmap::load()
406 functions. In addition, Qt provides the QImageReader class which
407 gives more control over the process. Depending on the underlying
408 support in the image format, the functions provided by the class
409 can save memory and speed up loading of images.
411 Likewise, Qt provides the QImageWriter class which supports
412 setting format specific options, such as the gamma level,
413 compression level and quality, prior to storing the image. If you
414 do not need such options, you can use QImage::save() or
415 QPixmap::save() instead.
421 QMovie is a convenience class for displaying animations, using the
422 QImageReader class internally. Once created, the QMovie class
423 provides various functions for both running and controlling the
426 \o \image paintsystem-movie.png
429 The QImageReader and QImageWriter classes rely on the
430 QImageIOHandler class which is the common image I/O interface for
431 all image formats in Qt. QImageIOHandler objects are used
432 internally by QImageReader and QImageWriter to add support for
433 different image formats to Qt.
435 A list of the supported file formats are available through the
436 QImageReader::supportedImageFormats() and
437 QImageWriter::supportedImageFormats() functions. Qt supports
438 several file formats by default, and in addition new formats can
439 be added as plugins. The currently supported formats are listed in
440 the QImageReader and QImageWriter class documentation.
442 Qt's plugin mechanism can also be used to write a custom image
443 format handler. This is done by deriving from the QImageIOHandler
444 class, and creating a QImageIOPlugin object which is a factory for
445 creating QImageIOHandler objects. When the plugin is installed,
446 QImageReader and QImageWriter will automatically load the plugin
449 \section1 Rendering SVG files
453 \o \image paintsystem-svg.png
454 \o \bold {SVG Rendering}
456 Scalable Vector Graphics (SVG) is a language for describing two-dimensional
457 graphics and graphical applications in XML. SVG 1.1 is a W3C Recommendation
458 and forms the core of the current SVG developments in Qt. SVG 1.2 is the
459 specification currently being developed by the \l{SVG Working Group}, and it
460 is \l{http://www.w3.org/TR/SVG12/}{available in draft form}.
461 The \l{Mobile SVG Profiles} (SVG Basic and SVG Tiny) are aimed at
462 resource-limited devices and are part of the 3GPP platform for third generation
463 mobile phones. You can read more about SVG at \l{About SVG}.
465 Qt supports the \l{SVG 1.2 Tiny Static Features}{static features} of
466 \l{SVG 1.2 Tiny}. ECMA scripts and DOM manipulation are currently not
469 SVG drawings can be rendered onto any QPaintDevice subclass. This
470 approach gives developers the flexibility to experiment, in order
471 to find the best solution for each application.
473 The easiest way to render SVG files is to construct a QSvgWidget and
474 load an SVG file using one of the QSvgWidget::load() functions.
476 QSvgRenderer is the class responsible for rendering SVG files for
477 QSvgWidget, and it can be used directly to provide SVG support for
479 To load an SVG file, construct a QSvgRenderer with a file name or the
480 contents of a file, or call QSvgRenderer::load() on an existing
481 renderer. If the SVG file has been loaded successfully the
482 QSvgRenderer::isValid() will return true.
484 Once you have loaded the SVG file successfully, you can render it
485 with the QSvgRenderer::render() function. Note that this scheme allows
486 you to render SVG files on all paint devices supported by Qt, including
487 QWidget, QGLWidget, and QImage. See the \l{SVG Viewer Example}{SVG Viewer}
488 example for more details.
494 \page paintsystem-styling.html
497 \previouspage Reading and Writing Image Files
498 \contentspage The Paint System
499 \nextpage Printing with Qt
501 Qt's built-in widgets use the QStyle class to perform nearly all
502 of their drawing. QStyle is an abstract base class that
503 encapsulates the look and feel of a GUI, and can be used to make
504 the widgets look exactly like the equivalent native widgets or to
505 give the widgets a custom look.
507 Qt provides a set of QStyle subclasses that emulate the native
508 look of the different platforms supported by Qt (QWindowsStyle,
509 QMacStyle, QMotifStyle, etc.). These styles are built into the
510 QtGui library, other styles can be made available using Qt's
513 Most functions for drawing style elements take four arguments:
516 \o an enum value specifying which graphical element to draw
517 \o a QStyleOption object specifying how and where to render that element
518 \o a QPainter object that should be used to draw the element
519 \o a QWidget object on which the drawing is performed (optional)
522 The style gets all the information it needs to render the
523 graphical element from the QStyleOption class. The widget is
524 passed as the last argument in case the style needs it to perform
525 special effects (such as animated default buttons on Mac OS X),
526 but it isn't mandatory. In fact, QStyle can be used to draw on any
527 paint device (not just widgets), in which case the widget argument
530 \image paintsystem-stylepainter.png
532 The paint system also provides the QStylePainter class inheriting
533 from QPainter. QStylePainter is a convenience class for drawing
534 QStyle elements inside a widget, and extends QPainter with a set
535 of high-level drawing functions implemented on top of QStyle's
536 API. The advantage of using QStylePainter is that the parameter
537 lists get considerably shorter.
541 \o \inlineimage paintsystem-icon.png
544 The QIcon class provides scalable icons in different modes and states.
546 QIcon can generate pixmaps reflecting an icon's state, mode and
547 size. These pixmaps are generated from the set of pixmaps
548 made available to the icon, and are used by Qt widgets to show an
549 icon representing a particular action.
551 The rendering of a QIcon object is handled by the QIconEngine
552 class. Each icon has a corresponding icon engine that is
553 responsible for drawing the icon with a requested size, mode and
558 For more information about widget styling and appearance, see the
559 \l{Styles and Style Aware Widgets}.