Qt Reference Documentation

Drawing and Filling

# Paint Devices and Backends

## Creating a Paint Device

The QPaintDevice class is the base class of objects that can be painted, i.e. QPainter can draw on any QPaintDevice subclass. QPaintDevice's drawing capabilities are currently implemented by the QWidget, QImage, QPixmap, QGLWidget, QGLPixelBuffer, QPicture and QPrinter subclasses.

Widget The QWidget class is the base class of all user interface objects. The widget is the atom of the user interface: it receives mouse, keyboard and other events from the window system, and paints a representation of itself on the screen.

Image

The QImage class provides a hardware-independent image representation which is designed and optimized for I/O, and for direct pixel access and manipulation. QImage supports several image formats including monochrome, 8-bit, 32-bit and alpha-blended images.

One advantage of using QImage as a paint device is that it is possible to guarantee the pixel exactness of any drawing operation in a platform-independent way. Another benefit is that the painting can be performed in another thread than the current GUI thread.

Pixmap

The QPixmap class is an off-screen image representation which is designed and optimized for showing images on screen. Unlike QImage, the pixel data in a pixmap is internal and is managed by the underlying window system, i.e. pixels can only be accessed through QPainter functions or by converting the QPixmap to a QImage.

To optimize drawing with QPixmap, Qt provides the QPixmapCache class which can be used to store temporary pixmaps that are expensive to generate without using more storage space than the cache limit.

Qt also provides the QBitmap convenience class, inheriting QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and is mainly used for creating custom QCursor and QBrush objects, constructing QRegion objects, and for setting masks for pixmaps and widgets.

OpenGL Widget

As mentioned previously, Qt provides the QtOpenGL module offering classes that makes it easy to use OpenGL in Qt applications. For example, the QGLWidget enables the OpenGL API for rendering.

But QGLWidget is also a QWidget subclass, and can be used by QPainter as any other paint device. One huge benefit from this is that it enables Qt to utilize the high performance of OpenGL for most drawing operations, such as transformations and pixmap drawing.

Pixel Buffer The QtOpenGL module also provides the QGLPixelBuffer class which inherits QPaintDevice directly. QGLPixelBuffer encapsulates an OpenGL pbuffer. Rendering into a pbuffer is normally done using full hardware acceleration which can be significantly faster than rendering into a QPixmap.
Framebuffer Object The QtOpenGL module also provides the QGLFramebufferObject class which inherits QPaintDevice directly. QGLFramebufferObject encapsulates an OpenGL framebuffer object. Framebuffer objects can also be used for off-screen rendering, and offer several advantages over pixel buffers for this purpose. These are described in the QGLFramebufferObject class documentation.

Picture

The QPicture class is a paint device that records and replays QPainter commands. A picture serializes painter commands to an IO device in a platform-independent format. QPicture is also resolution independent, i.e. a QPicture can be displayed on different devices (for example svg, pdf, ps, printer and screen) looking the same.

Qt provides the QPicture::load() and QPicture::save() functions as well as streaming operators for loading and saving pictures.

Printer

The QPrinter class is a paint device that paints on a printer. On Windows or Mac OS X, QPrinter uses the built-in printer drivers. On X11, QPrinter generates postscript and sends that to lpr, lp, or another print program. QPrinter can also print to any other QPrintEngine object.

The QPrintEngine class defines an interface for how QPrinter interacts with a given printing subsystem. The common case when creating your own print engine, is to derive from both QPaintEngine and QPrintEngine.

The output format is by default determined by the platform the printer is running on, but by explicitly setting the output format to QPrinter::PdfFormat, QPrinter will generate its output as a PDF file.

Custom Backends Support for a new backend can be implemented by deriving from the QPaintDevice class and reimplementing the virtual QPaintDevice::paintEngine() function to tell QPainter which paint engine should be used to draw on this particular device. To actually be able to draw on the device, this paint engine must be a custom paint engine created by deriving from the QPaintEngine class.

## Selecting the Painting Backend

Since Qt 4.5, it is possible to replace the paint engines and paint devices used for widgets, pixmaps and the offscreen double buffer. By default the backends are:

Windows | Software Rasterizer
X11 | X11
Mac OS X | CoreGraphics
Embedded | Software Rasterizer

Passing a command line parameter to the application, such as, `-graphicssystem raster`, specifies that Qt should use the software rasterizer for this application. The Software rasterizer is fully supported on all platforms.

     > analogclock -graphicssystem raster

There is also a `-graphicssystem opengl` mode that uses OpenGL for all drawing. Currently, this engine is experimental as it does not draw everything correctly.

Qt also supports being configured using `-graphicssystem raster|opengl` in which case all applications will use the specified graphics system for its graphics.