source: trunk/doc/src/examples/svgalib.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

File size: 14.4 KB
RevLine 
[2]1/****************************************************************************
2**
[846]3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
[561]4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
[2]6**
7** This file is part of the documentation of the Qt Toolkit.
8**
[846]9** $QT_BEGIN_LICENSE:FDL$
[2]10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
[846]13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
[2]15**
[846]16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
[2]21**
[561]22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
[2]24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example qws/svgalib
30 \title Accelerated Graphics Driver Example
31
32 The Accelerated Graphics Driver example shows how you can write
33 your own accelerated graphics driver and \l {add your graphics
34 driver to Qt for Embedded Linux}. In \l{Qt for Embedded Linux},
35 painting is a pure software implementation and is normally performed
36 in two steps:
37 The clients render each window onto a corresponding surface
38 (stored in memory) using a paint engine, and then the server uses
39 the graphics driver to compose the surface images and copy them to
40 the screen. (See the \l{Qt for Embedded Linux Architecture} documentation
41 for details.)
42
43 The rendering can be accelerated in two ways: Either by
44 accelerating the copying of pixels to the screen, or by
45 accelerating the explicit painting operations. The first is done
46 in the graphics driver implementation, the latter is performed by
47 the paint engine implementation. Typically, both the pixel copying
48 and the painting operations are accelerated using the following
49 approach:
50
51 \list 1
52 \o \l {Step 1: Creating a Custom Graphics Driver}
53 {Creating a Custom Graphics Driver}
54
55 \o \l {Step 2: Implementing a Custom Raster Paint Engine}
56 {Implementing a Custom Paint Engine}
57
58 \o \l {Step 3: Making the Widgets Aware of the Custom Paint
59 Engine}{Making the Widgets Aware of the Custom Paint Engine}
60
61 \endlist
62
63 After compiling the example code, install the graphics driver
64 plugin with the command \c {make install}. To start an application
65 using the graphics driver, you can either set the environment
66 variable \l QWS_DISPLAY and then run the application, or you can
67 just run the application using the \c -display switch:
68
69 \snippet doc/src/snippets/code/doc_src_examples_svgalib.qdoc 0
70
71 \table
72 \header \o SVGAlib
73 \row \o
74
75 Instead of interfacing the graphics hardware directly, this
76 example relies on \l {http://www.svgalib.org}{SVGAlib} being
77 installed on your system. \l {http://www.svgalib.org}{SVGAlib} is
78 a small graphics library which provides acceleration for many
79 common graphics cards used on desktop computers. It should work on
80 most workstations and has a small and simple API.
81
82 \endtable
83
84 \section1 Step 1: Creating a Custom Graphics Driver
85
86 The custom graphics driver is created by deriving from the QScreen
87 class. QScreen is the base class for implementing screen/graphics
88 drivers in Qt for Embedded Linux.
89
90 \snippet examples/qws/svgalib/svgalibscreen.h 0
91 \codeline
92 \snippet examples/qws/svgalib/svgalibscreen.h 1
93
94 The \l {QScreen::}{connect()}, \l {QScreen::}{disconnect()}, \l
95 {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()}
96 functions are declared as pure virtual functions in QScreen and
97 must be implemented. They are used to configure the hardware, or
98 query its configuration: \l {QScreen::}{connect()} and \l
99 {QScreen::}{disconnect()} are called by both the server and client
100 processes, while the \l {QScreen::}{initDevice()} and \l
101 {QScreen::}{shutdownDevice()} functions are only called by the
102 server process.
103
104 QScreen's \l {QScreen::}{setMode()} and \l {QScreen::}{blank()}
105 functions are also pure virtual, but our driver's implementations
106 are trivial. The last two functions (\l {QScreen::}{blit()} and \l
107 {QScreen::}{solidFill()}) are the ones involved in putting pixels
108 on the screen, i.e., we reimplement these functions to perform the
109 pixel copying acceleration.
110
111 Finally, the \c context variable is a pointer to a \l
112 {http://www.svgalib.org}{SVGAlib} specific type. Note that the
113 details of using the \l {http://www.svgalib.org}{SVGAlib} library
114 is beyond the scope of this example.
115
116 \section2 SvgalibScreen Class Implementation
117
118 The \l {QScreen::}{connect()} function is the first function that