Update copyright headers
[qt:qt.git] / doc / src / platforms / platform-notes.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     \group platform-specific
30     \title Platform-Specific Documentation
31     \brief Documents describing platform-specific features of Qt.
32
33     These documents describe platform-specific features provided by Qt, and
34     discuss issues related to particular platforms and environments.
35
36     \generatelist{related}
37 */
38
39 /*!
40     \page platform-notes.html
41     \ingroup platform-specific
42     \title Platform and Compiler Notes
43     \brief Information about the platforms on which Qt can be used.
44
45     This page contains information about the platforms Qt is currently known
46     to run on, with links to platform-specific notes, including any known bugs
47     or incompatibilities.
48
49     Information about the combinations of platforms and compilers
50     supported by Qt can be found on the \l{Supported Platforms} page.
51
52     \list
53     \o \l{Platform and Compiler Notes - Symbian}
54     \tableofcontents{1 Platform and Compiler Notes - Symbian}
55     \endlist
56
57 */
58
59 /*!
60     \page platform-notes-symbian.html
61     \title Platform and Compiler Notes - Symbian
62     \contentspage Platform and Compiler Notes
63     \ingroup platform-specific
64     \brief Information about the state of support for the Symbian platform.
65
66     This page describes implementation details regarding the Qt for Symbian port. To get 
67     started with application development for Symbian devices, read  the \l 
68     {http://doc.qt.nokia.com/qtcreator/creator-developing-symbian.html} 
69     {Connecting Symbian Devices} document.
70
71     \section1 Source Compatibility
72
73     Qt for Symbian provides the same level of source compatibility guarantee as
74     given for other platforms. That is, a program which compiles against a given
75     version of Qt for Symbian will also compile against all future versions of the
76     same major release.
77
78     \section1 Binary Compatibility
79
80     As with every supported platform, Qt strives to maintain application 
81     behavior and binary compatibility throughout the lifetime of the Qt 4.x 
82     major version and on the \l {Supported Devices}{Symbian devices that support Qt}.
83     Symbian support in Qt SDK and Ovi Store were introduced with Qt 4.6. Each Qt 
84     release contains bug fixes that might change the API behavior and thereby 
85     affect application compatibility.
86
87     In addition, Symbian devices have different input methods, such as different 
88     keyboard styles or touch input, screen sizes, memory, and CPU and GPU 
89     capabilities. Therefore, you must test applications on specific target 
90     devices to ensure compatibility. In order to build applications that are 
91     supported also on earlier devices, select the target in Qt SDK carefully. 
92     Generally, an earlier target (such as S60 5th Edition) is supported on a 
93     larger number of devices than a later target (such as Symbian Belle).
94
95     \target Supported Devices
96     \section1 Supported Devices
97     
98     The \l {http://developer.qt.nokia.com/wiki/support_for_Symbian}{Support for Symbian} document
99     details the Qt support on different Symbian devices.
100
101     The \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian#Supported_Devices}
102     {Nokia Smart Installer for Symbian} document lists how Qt is supported on 
103     different Symbian devices through Smart Installer.
104
105     Qt versions are supported by Symbian devices as follows:
106     \list
107     \o Qt 4.6 is supported by S60 3rd Edition feature pack 1 and newer devices 
108     through \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Smart Installer}.
109     \o Qt 4.7.3 is supported by S60 5th Edition and newer devices
110     through \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Smart Installer}.
111     \endlist
112     
113     Symbian devices have a pre-installed Qt support as follows:
114     \list
115     \o Symbian Anna: Qt 4.7.3 in C: drive. Note that Qt 4.7.4 is supported in Symbian Anna
116     through \l {http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Smart Installer}.
117     \o Symbian Belle: Qt 4.7.4 in device firmware (ROM).
118     \endlist
119     
120
121     \section1 Functionality Support
122
123     The following technologies and classes are not supported:
124     \list
125     \o QtConcurrent
126     \o QtDBus
127     \o \l {http://doc.qt.nokia.com/4.8/printing.html}{Printing support}
128     \o Qt3Support
129     \endlist
130     
131     The following technologies have limited support:
132     
133
134     \table
135     \header \o Module
136             \o Note
137     \row    \o QtSql
138             \o The supported drivers are SQLite and QSYMSQL.
139     \row    \o QtMultimedia
140             \o For support details see \l {Multimedia Support} section.
141     \row    \o QtGui
142             \o QtGui's widgets are deprecated (i.e. they are available but not 
143             recommended to use) in the Symbian port. It is recommended to use \l
144             {http://doc.qt.nokia.com/qt-components-symbian-1.1/symbian-components-functional.html}
145             {Qt Quick Components for Symbian} instead, because they provide 
146             better look and feel on Symbian devices.
147
148             Moreover, the following classes of QtGui \bold {should not 
149             be used} in a Symbian application:
150             
151             \list
152             \o QFileDialog with the \c DontUseNativeDialog option
153             \o QColorDialog with the \c DontUseNativeDialog option
154             \o QFontDialog
155             \o QWizard
156             \o QCalendarWidget
157             \o QDateTimeEdit
158             \o QMdiArea
159             \o QDockWidget
160             \o QMdiSubWindow
161             \o QPrintPreviewWidget
162             \endlist
163             
164             QScrollArea: The scrolling and focus handling of QScrollArea's all 
165             scrollable widgets, for example QListView, differs from native Avkon 
166             list widgets' one. Native Avkon scrollable components support 
167             touch-gesture-based scrolling by dragging and flicking the UI 
168             component but this functionality is not implemented in Qt widgets. 
169             Scrolling by dragging and flicking works also in Qt Quick Components 
170             that implements the \l 
171             {http://www.developer.nokia.com/Resources/Library/Symbian_Design_Guidelines/}
172             {Symbian design guidelines}.
173
174     \endtable
175
176     \section1 Compiler Notes
177     
178     For the application development the necessary compiler toolchain is included in \l 
179     {http://qt.nokia.com/downloads}{Qt SDK}. For instructions compiling Qt 
180     itself see the \l
181     {http://doc.qt.nokia.com/stable/install-symbian.html}
182     {Installing Qt for the Symbian platform} document.
183
184     \section1 Known Issues
185
186     Known issues can be found by visiting the
187     \l{http://qt.gitorious.org/qt/pages/QtKnownIssues}{wiki page} with an
188     up-to-date list of known issues, and the list of bugs can be found by
189     \l{http://bugreports.qt-project.org/browse/QTBUG/component/19171}{browsing} the
190     S60 component in Qt's public task tracker, located at
191     \l{http://bugreports.qt-project.org/}{http://bugreports.qt-project.org/}.
192
193     For information about mixing exceptions with Symbian leaves, see
194     \l{Exception Safety with Symbian}.
195
196     \section1 Required Capabilities
197
198     The Qt libraries are typically signed with \c{All -TCB} capabilites but
199     that does not mean your Qt application needs to be signed with the same
200     capabilities to function properly. The capabilities your application needs
201     to function properly depends on which parts of Qt you use. 
202     In a Qt application Symbian capabilities are defined in the
203     \l {http://doc.qt.nokia.com/4.8/qmake-variable-reference.html#target-capability}
204     {TARGET.CAPABILITY} qmake variable in the project file.
205     Here is an overview for which capabilities may be needed when using different modules:
206
207     \table
208     \header \o Module
209             \o Required Symbian Capability
210     \row    \o QtCore
211             \o \c PowerMgmt if QProcess::kill(...) or QProcess::terminate(...) is called.
212     \row    \o QtCore
213             \o \c AllFiles when \l{http://wiki.forum.nokia.com/index.php/Capabilities_%28Symbian_Signed%29/AllFiles_Capability}{accessing specific areas.}
214     \row    \o QtDeclarative
215             \o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified.
216     \row    \o QtNetwork
217             \o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified.
218     \row    \o QtNetwork
219             \o \c ReadUserData is required to include all the phone's SSL certificates in the system's default CA certificate list
220                   (for example those added by the user or stored in the SIM card),
221                   without this capability only the CA certs built into the phone are used.
222     \row    \o QtMultimedia
223             \o \c UserEnvironment if QAudioInput is used.
224     \row    \o QtWebKit
225             \o \c NetworkServices is automatically added for this module if no capabilities are explicitly specified.
226     \endtable
227
228     \note Some modules rely on other modules. E.g. QtWebkit and QtDeclarative
229     depend on QtNetwork and therefore any application that
230     depends on these modules is also likely to need \c NetworkServices capability.
231
232     For more information see the documentation of the individual Qt classes. If
233     a class does not mention Symbian capabilities, it requires none.
234
235     \target Multimedia Support
236     \section1 Multimedia Support
237
238     Qt Mobility provides a high-level API for multimedia functionality with
239     \l{http://doc.qt.nokia.com/qtmobility/multimedia.html}{QtMultimediaKit}.
240     In addition, Qt provides the low-level \l {QtMultimedia}{QtMultimedia} 
241     module that is internally used by the QtMultimediaKit. For more information
242     on developing multimedia applications for Symbian devices, see
243     \l {http://www.developer.nokia.com/info/sw.nokia.com/id/4abf12e7-72d8-45ef-b1a2-46184abe18ba/Guide_for_Qt_Multimedia_Developers.html}
244     {Guide for Qt Multimedia Developers}.
245
246     Moreover, there is a third multimedia-related module called Phonon. Qt 
247     provides two backends for the Phonon module in Symbian: \i MMF and \i Helix. 
248
249     Note that Phonon is a legacy module and the QtMultimediaKit module is 
250     replacing Phonon in Qt 5. Although Phonon is supported in Symbian for 
251     backwards compatibility and there is no plan to remove Phonon from Symbian 
252     any new applications should use QtMultimediaKit in Symbian using Qt 4.7 
253     bundle. The QtMultimediaKit feature set is comparable to that in Phonon.        
254
255     The following applies to Phonon:
256     \list
257     \o MMF Phonon backend supports video and sound playback through Symbian's 
258     Multimedia Framework, MMF. Phonon's video playback may show artifacts when 
259     the video is moved or resized (for instance, during device orientation 
260     changes from portrait to landscape and vice versa). This problem is present 
261     on S60 5th Edition and earlier versions, as well as in Symbian Anna devices.
262     \o The audio and video formats that Phonon supports depends on what support
263     the platform provides for MMF. The emulator is known to have limited
264     codec support.
265     \o In addition, there exists a backend for the Helix framework. However, since
266     it is not shipped with Qt, its availability depends on the Symbian platform
267     in use. If the MFF plugin fails to load, the Helix plugin, if present on the
268     device, will be loaded instead.
269     \endlist
270
271     \section1 Hardware Accelerated Rendering
272
273     The default graphics system on Symbian Anna is OpenVG, which uses OpenVG
274     hardware to accelerate \l QPainter functions. There are a few exceptions,
275     where Qt will use software rendering fallback.
276
277     Devices like the N8 and C7 only have 32Mb of GPU memory and limited support
278     for EGL surface transparency. These devices can be identified by querying
279     the\c GL_RENDERER or \c VG_RENDERER string which evaluates to \c {VideoCore III}.
280     On these devices, Qt will use software rendering in cases listed below.
281
282         \list
283         \o Translucent windows
284         \o Dialogs
285         \o Popups
286         \endlist
287
288     \section1 OpenGL Support in Symbian
289
290      Qt 4.7 introduces the \l {QtOpenGL} module. QtOpenGL is
291      supported on devices which support OpenGL ES 2.0. Symbian platforms prior
292      to Symbian Anna (and Symbian^3) are not supported.
293
294     \l QGLWidget usage as a \l QGraphicsView viewport is not recommended on
295     Symbian. The OpenVG graphics system is not able to manage OpenGL graphics
296     resources. Also, a QGLWidget object is not able to release its GPU resources
297     when the application goes to the background. If OpenGL functionality is
298     needed, \l { http://doc.qt.nokia.com/4.7-snapshot/qapplication.html#setGraphicsSystem}
299     {OpenGL graphics system} usage is recommended. If an application
300     decides to use QGLWidget, then it is the application's responsibility to
301     destroy and release QGLWidget and related OpenGL resources when the
302     application goes to the background. Otherwise, the \l{Graphics Out Of Memory monitor}
303     may decide to kill the application as it consumes GPU resources while in the
304     background.
305
306     \note \l QGLBuffer, \l QGLFramebufferObject, \l QGLPixelBuffer, \l
307     QGLShader, and \l QGLShaderProgram are direct GPU resources and it is the
308     application's responsibility to manage them.
309
310     \section1 UI Performance in S60 3rd and 5th Edition Devices
311
312     Qt uses the QPainter class to perform low-level painting on widgets and
313     other paint devices. QPainter provides functions to draw complex shapes,
314     aligned text and pixmaps. It can also do vector path clipping, coordinate
315     transformations and Porter-Duff composition. If the underlying graphics
316     architecture does not support all of these operations then Qt uses the
317     raster graphics system for rendering.
318     
319     In Symbian Anna (and Symbian^3) Qt uses hardware accelerated graphics as explained above.
320     This is enabled by \l
321     {http://library.developer.nokia.com/index.jsp?topic=/GUID-E35887BB-7E58-438C-AA27-97B2CDE7E069/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.html}
322     {ScreenPlay Graphics Architecture} in these devices.
323
324     Most of the Symbian S60 3rd and 5th Edition devices have a
325     graphics architecture that does not have native support for all functions
326     provided by QPainter. In these \l
327     {http://library.developer.nokia.com/index.jsp?topic=/GUID-E35887BB-7E58-438C-AA27-97B2CDE7E069/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.html}
328     {non-ScreenPlay} devices Qt uses the raster
329     graphics system by default that has a performance penalty compared
330     to native Symbian rendering.
331
332     In order to be able to perform all functions provided by QPainter, the
333     raster graphics system needs to have pixel level framebuffer access. To
334     make this possible in non-ScreenPlay devices Qt has to create an
335     additional offscreen buffer that is the target for all Qt rendering
336     operations. Qt renders the widget tree to the offscreen buffer and the
337     offscreen buffer is blitted to the framebuffer via Symbian Window Server.
338
339     The following table shows the rendering stacks of native Symbian and Qt in
340     \l {http://library.developer.nokia.com/index.jsp?topic=/GUID-E35887BB-7E58-438C-AA27-97B2CDE7E069/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.html}
341     {non-ScreenPlay devices}.
342
343     \table
344     \header \o Symbian
345             \o Qt
346     \row    \o \image symbian-rendering-stack-non-screenplay.png
347             \o \image symbian-qt-rendering-stack-non-screenplay.png
348     \endtable
349
350     The following diagrams show a simplified sequence of drawing a pixmap in
351     a non-ScreenPlay device.
352
353     \table
354     \header \o Symbian
355     \row    \o \image symbian-draw-pixmap-sequence.png
356     \endtable
357
358     \table
359     \header \o Qt
360     \row    \o \image symbian-qt-draw-pixmap-sequence.png
361     \endtable
362
363     When compared to a native Symbian application, Qt does an additional blit
364     to the offscreen buffer before drawing to the framebuffer. That is the
365     performance penalty which needs to be paid to get all functionality
366     provided by QPainter in non-ScreenPlay architecture.
367 */
368