Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-accel.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page qt-embedded-accel.html
30
31     \target add your graphics driver to Qt for Embedded Linux
32
33     \title Adding an Accelerated Graphics Driver to Qt for Embedded Linux
34     \ingroup qt-embedded-linux
35
36     In \l{Qt for Embedded Linux}, painting is a pure software implementation
37     normally performed in two steps. First, each window is rendered
38     onto a QWSWindowSurface using QPaintEngine. Second, the server
39     composes the surface images and copies the composition to the
40     screen (see \l{Qt for Embedded Linux Architecture} for details).
41     \l{Qt for Embedded Linux} uses QRasterPaintEngine (a raster-based implementation of
42     QPaintEngine) to implement painting operations, and uses QScreen
43     to implement window composition.
44
45     It is possible to add an accelerated graphics driver to take
46     advantage of available hardware resources. This is described in
47     detail in the \l {Accelerated Graphics Driver Example} which uses
48     the following approach:
49
50     \tableofcontents
51
52     \warning This feature is under development and is subject to
53     change.
54
55     \section1 Step 1: Create a Custom Screen
56
57     Create a custom screen by deriving from the QScreen class.
58
59     The \l {QScreen::}{connect()}, \l {QScreen::}{disconnect()}, \l
60     {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()}
61     functions are declared as pure virtual functions in QScreen and
62     must be implemented. These functions are used to configure the
63     hardware, or query its configuration. The \l
64     {QScreen::}{connect()} and \l {QScreen::}{disconnect()} are called
65     by both the server and client processes, while the \l
66     {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()}
67     functions are only called by the server process.
68
69     You might want to accelerate the final copying to the screen by
70     reimplementing the \l {QScreen::}{blit()} and \l
71     {QScreen::}{solidFill()} functions.
72
73     \section1 Step 2: Implement a Custom Raster Paint Engine
74
75     Implement the painting operations by subclassing the
76     QRasterPaintEngine class.
77
78     To accelerate a graphics primitive, simply reimplement the
79     corresponding function in your custom paint engine. If there is
80     functionality you do not want to reimplement (such as certain
81     pens, brushes, modes, etc.), you can just call the corresponding
82     base class implementation.
83
84     \section1 Step 3: Make the Paint Device Aware of Your Paint Engine
85
86     To activate your paint engine you must create a subclass of the
87     QCustomRasterPaintDevice class and reimplement its \l
88     {QCustomRasterPaintDevice::}{paintEngine()} function. Let this
89     function return a pointer to your paint engine. In addition, the
90     QCustomRasterPaintDevice::memory() function must be reimplemented
91     to return a pointer to the buffer where the painting should be
92     done.
93
94     \table
95     \header \o Acceleration Without a Memory Buffer
96     \row
97     \o
98
99     By default the QRasterPaintEngine draws into a memory buffer (this can
100     be local memory, shared memory or graphics memory mapped into
101     application memory).
102     In some cases you might want to avoid using a memory buffer directly,
103     e.g if you want to use an accelerated graphic controller to handle all
104     the buffer manipulation. This can be implemented by  reimplementing
105     the QCustomRasterPaintDevice::memory() function to return 0 (meaning
106     no buffer available). Then, whenever a color or image buffer normally
107     would be written into paint engine buffer, the paint engine will call the
108     QRasterPaintEngine::drawColorSpans() and
109     QRasterPaintEngine::drawBufferSpan() functions instead.
110
111     Note that the default implementations of these functions only
112     calls qFatal() with an error message; reimplement the functions
113     and let them do the appropriate communication with the accelerated
114     graphics controller.
115
116     \endtable
117
118     \section1 Step 4: Make the Window Surface Aware of Your Paint Device
119
120     Derive from the QWSWindowSurface class and reimplement its 
121     paintDevice() function. Make this function
122     return a pointer to your custom raster paint device.
123
124     \section1 Step 5: Enable Creation of an Instance of Your Window Surface
125
126     Finally, reimplement QScreen's \l {QScreen::}{createSurface()}
127     function and make this function able to create an instance of your
128     QWSWindowSurface subclass.
129 */