diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/examples/ahigl.qdoc | 572 | ||||
| -rw-r--r-- | doc/src/getting-started/examples.qdoc | 1 | ||||
| -rw-r--r-- | doc/src/getting-started/known-issues.qdoc | 4 | ||||
| -rw-r--r-- | doc/src/internationalization/i18n.qdoc | 3 | ||||
| -rw-r--r-- | doc/src/platforms/emb-opengl.qdoc | 247 | ||||
| -rw-r--r-- | doc/src/qt4-intro.qdoc | 36 | ||||
| -rw-r--r-- | doc/src/snippets/code/doc_src_examples_ahigl.qdoc | 49 | ||||
| -rw-r--r-- | doc/src/snippets/gestures/qgesture.cpp | 32 |
8 files changed, 168 insertions, 776 deletions
diff --git a/doc/src/examples/ahigl.qdoc b/doc/src/examples/ahigl.qdoc deleted file mode 100644 index c5e2387..0000000 --- a/doc/src/examples/ahigl.qdoc +++ /dev/null @@ -1,572 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the Technology Preview License Agreement accompanying -** this package. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain additional -** rights. These rights are described in the Nokia Qt LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@nokia.com. -** -** -** -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example qws/ahigl - \title OpenGL for Embedded Systems Example - - \section1 Introduction - - This example demonstrates how you can use OpenGL for Embedded - Systems (ES) in your own screen driver and \l{add your graphics - driver to Qt for Embedded Linux}. In \l{Qt for Embedded Linux}, - painting is done in software, normally performed in two steps: - First, each client renders its windows onto its window surface in - memory using a paint engine. Then the server uses the screen - driver to compose the window surface images and copy the - composition to the screen. (See the \l{Qt for Embedded Linux - Architecture} documentation for details.) - - This example is not for the novice. It assumes the reader is - familiar with both OpenGL and the screen driver framework - demonstrated in the \l {Accelerated Graphics Driver Example}. - - An OpenGL screen driver for Qt for Embedded Linux can use OpenGL ES - in three ways. First, the \l{QWSServer}{Qt for Embedded Linux server} - can use the driver to compose multiple window images and then show the - composition on the screen. Second, clients can use the driver to - accelerate OpenGL painting operations using the QOpenGLPaintEngine - class. Finally, clients can use the driver to do OpenGL operations - with instances of the QGLWidget class. This example implements all - three cases. - - The example uses an implementation of OpenGL ES from - \l {http://ati.amd.com}{ATI} for the - \l {http://ati.amd.com/products/imageon238x/}{Imageon 2380}. The - OpenGL include files gl.h and egl.h must be installed to compile - the example, and the OpenGL and EGL libraries must be installed - for linking. If your target device is different, you must install - the include files and libraries for that device, and you also - might need to modify the example source code, if any API signatures - in your EGL library differ from the ones used here. - - After compiling and linking the example source, install the - screen driver plugin with the command \c {make install}. To - start an application that uses the plugin, you can either set the - environment variable \l QWS_DISPLAY and then start the - application, or just start the application with the \c -display - switch, as follows: - - \snippet doc/src/snippets/code/doc_src_examples_ahigl.qdoc 0 - - The example driver also implements an animated transition effect - for use when showing new windows or reshowing windows that have - been minimized. To enable this transition effect, run the - application with \c {-display ahigl:effects}. - - \section1 The Class Definitions - - The example comprises three main classes plus some helper classes. - The three main classes are the plugin (QAhiGLScreenPlugin), which - is defined in qscreenahiglplugin.cpp, the screen driver - (QAhiGLScreen), which is defined in qscreenahigl_qws.h, and the - window surface (QAhiGLWindowSurface), which is defined in - qwindowsurface_ahigl_p.h. The "Ahi" prefix in these class names - stands for \e {ATI Handheld Interface}. The example was written - for the ATI Imageon 2380, but it can also be used as a template - for other ATI handheld devices. - - \section2 The Plugin Class Definition - - The screen driver plugin is class QAhiGLScreenPlugin. - - \snippet examples/qws/ahigl/qscreenahiglplugin.cpp 0 - - QAhiGLScreenPlugin is derived from class QScreenDriverPlugin, - which in turn is derived from QObject. - - \section2 The Screen Driver Class Definitions - - The screen driver classes are the public class QAhiGLScreen and - its private implementation class QAhiGLScreenPrivate. QAhiGLScreen - is derived from QGLScreen, which is derived from QScreen. If your - screen driver will only do window compositions and display them, - then you can derive your screen driver class directly from - QScreen. But if your screen driver will do accelerated graphics - rendering operations with the QOpenGLPaintEngine, or if it will - handle instances of class QGLWidget, then you must derive your - screen driver class from QGLScreen. - - \snippet examples/qws/ahigl/qscreenahigl_qws.h 0 - - All functions in the public API of class QAhiGLScreen are virtual - functions declared in its base classes. hasOpenGL() is declared in - QGLScreen. It simply returns true indicating our example screen - driver does support OpenGL operations. The other functions in the - public API are declared in QScreen. They are called by the - \l{QWSServer}{Qt for Embedded Linux server} at the appropriate times. - - Note that class QScreen is a documented class but class QGLScreen - is not. This is because the design of class QGLScreen is not yet - final. - - The only data member in class QAhiGLScreen is a standard d_ptr, - which points to an instance of the driver's private implementation - class QAhiGLScreenPrivate. The driver's internal state is stored - in the private class. Using the so-called d-pointer pattern allows - you to make changes to the driver's internal design without - breaking binary compatibility. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 0 - - Class QAhiGLScreenPrivate is derived from QObject so that it can - use the Qt signal/slot mechanism. QAhiGLScreen is not a QObject, - so it can't use the signal/slot mechanism. Signals meant for our - screen driver are received by slots in the private implementation - class, in this case, windowEvent() and redrawScreen(). - - \section2 The Window Surface Class Definitions - - The window surface classes are QAhiGLWindowSurface and its private - implementation class QAhiGLWindowSurfacePrivate. We create class - QAhiGLWindowSurface so the screen driver can use the OpenGL paint - engine and the OpenGL widget, classes QOpenGLPaintEngine and - QGLWidget. QAhiGLWindowSurface is derived from the more general - OpenGL window surface class, QWSGLWindowSurface, which is derived - from QWSWindowSurface. - - \snippet examples/qws/ahigl/qwindowsurface_ahigl_p.h 0 - - In addition to implementing the standard functionality required by - any new subclass of QWSWindowSurface, QAhiGLWindowSurface also - contains the textureId() function used by QAhiGLScreen. - - The same d-pointer pattern is used in this window surface class. - The private implementation class is QAhiGLWindowSurfacePrivate. It - allows making changes to the state variables of the window surface - without breaking binary compatibility. - - \snippet examples/qws/ahigl/qwindowsurface_ahigl.cpp 0 - - In this case, our private implementation class has no member - functions except for its constructor. It contains only public data - members which hold state information for the window surface. - - \section2 The Helper Classes - - The example screen driver maintains a static \l {QMap} {map} of - all the \l {QWSWindow} {windows} it is showing on the screen. - Each window is mapped to an instance of struct WindowInfo. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 2 - - As each new window is created, an instance of struct WindowInfo is - allocated and inserted into the window map. WindowInfo uses a - GLuint to identify the OpenGL texture it creates for the window. - Note that the example driver, in addition to drawing windows using - OpenGL, also supports drawing windows in the normal way without - OpenGL, but it uses an OpenGL texture for the rendering operations - in either case. Top-level windows that are drawn without OpenGL - are first rendered in the normal way into a shared memory segment, - which is then converted to a OpenGL texture and drawn to the - screen. - - To animate the window transition effect, WindowInfo uses an - instance of the helper class ShowAnimation. The animation is - created by the windowEvent() slot in QAhiGLScreenPrivate, whenever - a \l {QWSServer::WindowEvent} {Show} window event is emitted by - the \l {QWSServer} {window server}. The server emits this signal - when a window is shown the first time and again later, when the - window is reshown after having been minimized. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 1 - - Class ShowAnimation is derived from the QTimeLine class, which is - used for controlling animations. QTimeLine is a QObject, so - ShowAnimation can use the Qt signal/slot mechanism. We will see - how the timeline's \l {QTimeLine::valueChanged()} {valueChanged()} - and \l {QTimeLine::finished()} {finished()} signals are used to - control the animation and then destroy the instance of - ShowAnimation, when the animation ends. The ShowAnimation - constructor needs the pointer to the screen driver's private - implementation class so it can set up these signal/slot - connections. - - \section1 The Class Implementations - - \section2 The Plugin Class Implementation - - QAhiGLScreenPlugin is a straightforward derivation of - QScreenDriverPlugin. It reimplements \l{QScreenDriverPlugin::}{keys()} - and \l{QScreenDriverPlugin::}{create()}. They are - called as needed by the \l{QWSServer}{Qt for Embedded Linux server.} - Recall that the server detects that the ahigl screen driver has - been requested, either by including "ahigl" in the value for the - environment variable QWS_DISPLAY, or by running your application - with a command line like the following. - - \snippet doc/src/snippets/code/doc_src_examples_ahigl.qdoc 1 - - The server calls \l {QScreenDriverPlugin::} {keys()}, which - returns a \l {QStringList} containing the singleton "ahigl" - matching the requested screen driver and telling the server that - it can use our example screen driver. The server then calls \l - {QScreenDriverPlugin::} {create()}, which creates the instance of - QAhiGLScreen. - - \snippet examples/qws/ahigl/qscreenahiglplugin.cpp 1 - - In the code snippet above, the macro Q_EXPORT_PLUGIN2 is used to export - the plugin class, QAhiGLScreen, for the qahiglscreen plugin. - Further information regarding plugins and how to create them - can be found at \l{How to Create Qt Plugins}. - - \section2 The Screen Driver Class Implementations - - The plugin creates the singleton instance of QAhiGLScreen. The - constructor is passed a \c displayId, which is used in the base - class QGLScreen to identify the server that the screen driver is - connected to. The constructor also creates its instance of - QAhiGLScreenPrivate, which instantiates a QTimer. The timeout() - signal of this timer is connected to the redrawScreen() slot so - the timer can be used to limit the frequency of actual drawing - operations in the hardware. - - The public API of class QAhiGLScreen consists of implementations - of virtual functions declared in its base classes. The function - hasOpenGL() is declared in base class QGLScreen. The others are - declared in base class QScreen. - - The \l {QScreen::}{connect()} function is the first one called by - the server after the screen driver is constructed. It initializes - the QScreen data members to hardcoded values that describe the ATI - screen. A better implementation would query the hardware for the - corresponding values in its current state and use those. It asks - whether the screen driver was started with the \c effects option - and sets the \c doEffects flag accordingly. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 7 - - The \l {QScreen::}{initDevice()} function is called by the server - after \l {QScreen::}{connect()}. It uses EGL library functions to - initialize the ATI hardware. Note that some data structures used - in this example are specific to the EGL implementation used, e.g., - the DummyScreen structure. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 8 - - Note the signal/slot connection at the bottom of initDevice(). We - connect the server's QWSServer::windowEvent() signal to the - windowEvent() slot in the screen driver's private implementation - class. The windowEvent() slot handles three window events, - QWSServer::Create, QWSServer::Destroy, and QWSServer::Show. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 5 - - The function manages instances of the helper classes associated - with each window. When a QWSServer::Create event occurs, it means - a new top-level \l {QWSWindow} {window} has been created. In this - case, an instance of helper class WindowInfo is created and - inserted into the window map with the pointer to the new \l - {QWSWindow} {window} as its key. When a QWSServer::Destroy event - occurs, a window is being destroyed, and its mapping is removed - from the window map. These two events are straightforward. The - tricky bits happen when a QWSServer::Show event occurs. This case - occurs when a window is shown for the first time and when it is - reshown after having been minimized. If the window transition - effect has been enabled, a new instance of the helper class - ShowAnimation is created and stored in a QPointer in the window's - instance of WindowInfo. The constructor of ShowAnimation - automatically \l {QTimeLine::start()} {starts} the animation of - the transition effect. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 3 - - To ensure that a ShowAnimation is not deleted until its animation - ends, the \l {QTimeLine::finished()} {finished()} signal is - connected to the \l {QObject::deleteLater()} {deleteLater()} slot. - When the animation ends, the finished() signal is emitted and the - deleteLater() slot deletes the ShowAnimation. The key here is that - the pointer to the ShowAnimation is stored in a QPointer in the - WindowInfo class. This QPointer will also be notified when the - ShowAnimation is deleted, so the QPointer in WindowInfo can null - itself out, if and only if it is still pointing to the instance - of ShowAnimation being deleted. - - The \l {QTimeLine::valueForTime()} {valueForTime()} function in - QTimeLine is reimplemented in ShowAnimation to return time values - that represent a curved path for the window transition effect. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 4 - - valueForTime() is called internally, when the time interval it - computed during the previous call has elapsed. If it computes a - next time value that is different from the one computed - previously, the \l {QTimeLine::valueChanged()} {valueChanged()} - signal is emitted. The ShowAnimation constructor shown above - connects this signal to the redrawScreen() slot in the screen - driver's private implementation class. This is how the animation - actually happens. - - The screen driver's implementation of \l {QScreen::} - {exposeRegion()} is where the main work of the screen driver is - meant to be done, i.e., updating the screen. It is called by the - \l {QWSServer} {window system} to update a particular window's - region of the screen. But note that it doesn't actually update the - screen, i.e., it doesn't actually call redrawScreen() directly, - but starts the updateTimer, which causes redrawScreen() to be - called once for each updateTimer interval. This means that all - calls to exposeRegion() during an updateTimer interval are handled - by a single call to redrawScreen(). Thus updateTimer can be used - to limit the frequency of screen updates. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 13 - - The call to the private function invalidateTexture() destroys - the window's existing texture (image). This ensures that a new - texture will be created for the window, when redrawScreen() is - eventually called. - - But there is a caveat to using updateTimer to limit the frequency - of screen updates. When the driver's animated transition effect - for new windows is enabled and a new window is being shown for the - first time or reshown after having been minimized, an instance of - ShowAnimation is created to run the animation. The valueChanged() - signal of this ShowAnimation is also connected to the - redrawScreen() slot, and QTimeLine, the base class of our - ShowAnimation, uses its own, internal timer to limit the speed of - the animation. This means that in the driver as currently written, - if the window transition effect is enabled (i.e. if the plugin is - started, with \c {-display ahigl:effects}), then redrawScreen() - can be called both when the update timer times out and when the - ShowAnimation timer times out, so the screen might get updated - more often than the frequency established by the update timer. - This may or may not be a bug, depending on your own hardware, if - you use this example as a template for your own OpenGL driver. - - The screen driver's private function redrawScreen() constructs - the window compositions. It is called only by the function of the - same name in the screen driver's private implementation class. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 6 - - Recall that this redrawScreen() in the private implementation - class is a slot function connected to two signals, the \c - timeout() signal of the updateTimer in the private implementation - class, and the valueChanged() signal of the helper class - ShowAnimation. Thus, the screen is only ever updated when a - timeout of one of the two timers occurs. This is important for two - reasons. First, the screen is meant to be updated no more than - once per updateTimer interval. Second, however, if the animated - window transition effect is requested, the screen might be updated - more often than that, and this might be a bug if the hardware - can't handle more frequent updates. - - The redrawScreen() in QAhiGLScreen begins by using standard - OpenGL to fill the screen with the background color. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 10 - - Next it iterates over the list of all \l {QWSWindow} {client - windows} obtained from the \l {QWSServer} {server}, extracting - from each window its instance of QWSWIndowSurface, then using that - window surface to create an OpenGL texture, and finally calling - the helper function drawWindow() to draw the texture on the - screen. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 11 - - Note the call to glBindTexture() immediately before the call to - drawWindow(). This call binds the identifer \c GL_TEXTURE_2D to - the texture we have just created. This makes our texture - accessible to functions in the OpenGL libraries. If you miss that - point, digging into the internals of drawWindow() won't make much - sense. - - Finally, the cursor is added to the window composition, and in the - last statement, the whole thing is displayed on the screen. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 12 - - The call to \c drawWindow(win,progress), in addition to passing a - pointer to the window to be redrawn, also passes the \c progress - parameter obtained by calling \l {QTimeLine::currentValue()} on - the window's instance of ShowAnimation. Recall that the current - value of the timeline is updated internally by a timer local to - the timeline, and the redrawScreen() slot is called whenever the - current value changes. The progress value will only be used if - the animated transition effect has been enabled. These extra calls - of redrawScreen() may cause the screen to be updated more often - than the rate determined by updateTimer. This must be taken - into account, if you set your updateTimer to timeout at the - maximum screen update frequency your hardware can handle. - - The drawWindow() function is not shown here and not explained - further, but the call to drawWindow() is the entry point to a - hierarchy of private helper functions that execute sequences of - OpenGL and EGL library calls. The reader is assumed to be familiar - enough with the OpenGL and EGL APIs to understand the code in - these helper functions on his own. Besides drawWindow(), the list - of these helper functions includes drawQuad(), drawQuadWavyFlag(), - the two overloadings of drawQuad_helper() (used by drawQuad() and - drawQuadWacyFlag()), and setRectCoords(). - - Note the two different ways the window's texture can be created in - redrawScreen(). If the window surface is an OpenGL window surface - (QAhiGLWindowSurface described below), the texture is obtained - from the window surface directly by calling its textureId() - function. But when the window surface is not an OpenGL one, the - static function createTexture() is called with the window - surface's \l {QImage} {image} to copy that image into an OpenGL - texture. This is done with the EGL functions glTexImage2D() and - glTexSubImage2D(). createTexture() is another function that - should be understandable for exsperienced OpenGL users, so it is - not shown or explained further here. - - The two implementations of \l {QScreen::}{createSurface()} are for - instantiating new window surfaces. The overloading with the widget - parameter is called in the client. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 14 - - If the parameter is an \l {QGLWidget} {OpenGL widget}, or, when it - isn't an OpenGL widget but its size is no bigger than 256 x 256, - we instantiate our subclass QAhiGLWindowSurface. Otherwise, we - instantiate a QWSWindowSurface. The size contraint is a - limitation of the OpenGL ES libraries we are using for our ATI - device. - - Note the test at the top of the function asking if our application - process is the \l {QApplication::GuiServer} {server}. We only - create instances of QAhiGLWindowSurface if our client is in the - server process. This is because of an implementation restriction - required by the OpenGL library used in the example. They only - support use of OpenGL in the server process. Hence a client can - use the QAhiGLWindowSurface if the client is in the server - process. - - The other overloading of createSurface() is called by the - server to create a window surface that will hold a copy of a - client side window surface. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 15 - - This overloading accepts a QString parameter identifying the type - of window surface to instantiate. QAhiGLWindowSurface is - instantiated if the parameter is \c ahigl. Otherwise, a normal - QWSWindowSurface is instantiated. The client's window surface - communicates its image data to the server's window surface through - shared memory. - - The implementation of \l {QScreen::}{setMode()}, is a stub in this - example. It would normally reset the frame buffer's resolution. - Its parameters are the \e width, \e height, and the bit \e depth - for the frame buffer's new resolution. If you implement setMode() - in your screen driver, remember that it must emit a signal to warn - other applications to redraw their frame buffers with the new - resolution. There is no significance to setMode() not being - implemented in this example. It simply wasn't implemented. - However, the stub had to be included because QScreen declares - setMode() to be pure virtual. - - Before the application exits, the server will call \l {QScreen::} - {shutdownDevice()} to release the hardware resources. This is also - done using EGL library functions. - - \snippet examples/qws/ahigl/qscreenahigl_qws.cpp 9 - - The server will also call \l {QScreen::}{disconnect()}, but this - function is only a stub in this example. - - \section2 The window Surface Class Implementations - - QAhiGLScreen creates instances of QAhiGLWindowSurface in its two - createSurface() functions, and there are two constructors for - QAhiGLWindowSurface that correspond to these two versions of - createSurface(). The constructor accepting a \l {QWidget} {widget} - parameter is called by the client side version of createSurface(), - and the constructor without the \l {QWidget} {widget} parameter is - called by the server side version. There will be a window surface - constructed on the server side for each one constructed on the - client side. - - \snippet examples/qws/ahigl/qwindowsurface_ahigl.cpp 1 - \codeline - \snippet examples/qws/ahigl/qwindowsurface_ahigl.cpp 2 - - The constructors create an instance of QAhiGLWindowSurfacePrivate, - the private implementation class, which contains all the state - variables for QAhiGLWindowSurface. The client side constructor - also creates an instance of QWSGLPaintDevice, the OpenGL paint - device, for return by \l {QWSWindowSurface::} {paintDevice()}. - This ensures that all \l {QPainter}s used on this surface will use - an OpenGL enabled QPaintEngine. It is a bit of jiggery pokery, - which is required because \l {QWSWindowSurface::} {paintDevice()} - is declared pure virtual. Normally, the client side constructor - will be called with an \l {QGLWidget}{OpenGL widget}, which has - its own \l {QWidget::} {paintEngine()} function that returns the - global static OpenGL paint engine, but because the constructor - also accepts a normal \l {QWidget}{widget}, it must be able to - find the OpenGL paint engine in that case as well, so since \l - {QWSWindowSurface::} {paintDevice()} must be implemented anyway, - the constructor creates an instance of QWSGLPaintDevice, which can - always return the global static pointer to QOpenGLPaintEngine. - - The OpenGL library implementation used for this example only - supports one OpenGL context. This context is therefore shared - among the single instance of QAhiGLScreen and all instances of - QAhiGLWindowSurface. It is passed to both constructors. - - This example uses the OpenGL frame buffer object extension, which - allows for accelerating OpenGL painting operations. Using this - OpenGL extension, painting operations are performed in a frame - buffer object, which QAhiGLScreen later uses to construct window - compositions on the screen. Allocation of the frame buffer object - is performed in \l {QWindowSurface::} {setGeometry()}. A safer way - to use this extension would be to first test to see if the - extension is supported by your OpenGL library, and use a different - approach if it is not. - - \snippet examples/qws/ahigl/qwindowsurface_ahigl.cpp 3 - - Since there can be several instances of the QAhiGLWindowSurface, we need - to make sure that the correct framebuffer object is active before painting. - This is done by reimplementing \l QWindowSurface::beginPaint(): - - \snippet examples/qws/ahigl/qwindowsurface_ahigl.cpp 4 - - Finally we need to make sure that whenever a widget grows beyond the size - supported by this driver (256 x 256), the surface is deleted and a new - standard surface is created instead. This is handled by reimplementing - \l QWSWindowSurface::isValid(): - - \snippet examples/qws/ahigl/qwindowsurface_ahigl.cpp 5 -*/ diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc index 2ad730a7..d72f816 100644 --- a/doc/src/getting-started/examples.qdoc +++ b/doc/src/getting-started/examples.qdoc @@ -1121,7 +1121,6 @@ \o \l{qws/svgalib}{Accelerated Graphics Driver}\raisedaster \o \l{qws/dbscreen}{Double Buffered Graphics Driver}\raisedaster \o \l{qws/mousecalibration}{Mouse Calibration}\raisedaster - \o \l{qws/ahigl}{OpenGL for Embedded Systems}\raisedaster \o \l{qws/simpledecoration}{Simple Decoration}\raisedaster \endlist */ diff --git a/doc/src/getting-started/known-issues.qdoc b/doc/src/getting-started/known-issues.qdoc index 40ac1c7..0b63423 100644 --- a/doc/src/getting-started/known-issues.qdoc +++ b/doc/src/getting-started/known-issues.qdoc @@ -53,6 +53,10 @@ For a list list of known bugs in Qt %VERSION%, see the \l{Task Tracker} on the Qt website. + An overview of known issues may also be found at: + \l{http://qt.gitorious.org/qt/pages/Qt460BetaKnownIssues} + {Known Issues Wiki}. + \section1 Installation Issues \section2 Building the Source Package on Windows 7 diff --git a/doc/src/internationalization/i18n.qdoc b/doc/src/internationalization/i18n.qdoc index 121c822..e873f4e 100644 --- a/doc/src/internationalization/i18n.qdoc +++ b/doc/src/internationalization/i18n.qdoc @@ -42,6 +42,9 @@ /*! \group i18n \title Qt Classes for Internationalization + + See \l{Internationalization with Qt} for information on how to use these classes + in your applications. */ /*! diff --git a/doc/src/platforms/emb-opengl.qdoc b/doc/src/platforms/emb-opengl.qdoc index fea09bb..2ed5d04 100644 --- a/doc/src/platforms/emb-opengl.qdoc +++ b/doc/src/platforms/emb-opengl.qdoc @@ -57,20 +57,20 @@ of the \l {http://www.opengl.org}{OpenGL} standard. Because it is meant for use in embedded systems, it has a smaller, more constrained API. -For reference, Nokia provides a plugin which integrates \l -{http://www.khronos.org/opengles}{OpenGL ES} with Qt for Embedded Linux, -but Qt for Embedded Linux can be adapted to a wide range of OpenGL -versions. +For reference, Nokia provides support for integrating \l +{http://www.khronos.org/opengles}{OpenGL ES} with Qt for Embedded Linux +for drawing into a QGLWidget. -There are three ways to use OpenGL with Qt for Embedded Linux: -\list - \o Perform OpenGL 3D graphics operations in applications; - \o Accelerate normal 2D painting operations; - \o Implement window compositing and special effects. -\endlist +The current implementation supports OpenGL and 2D painting within a +QGLWidget. Using OpenGL to accelerate regular widgets and compositing +top-level windows with OpenGL are not currently supported. These issues +will be addressed in future versions of Qt. -Qt for Embedded Linux is shipped with a reference integration example -that demonstrates all three uses. +It is recommended that Qt for Embedded Linux is configured with the +\c{-DQT_QWS_CLIENTBLIT} and \c{-DQT_NO_QWS_CURSOR} options for optimum +performance. OpenGL is rendered direct to the screen and these options +prevent Qt for Embedded Linux from trying to do its own non-OpenGL +compositing on the QGLWidget contents. \section2 Using OpenGL 3D Graphics in Applications @@ -82,146 +82,149 @@ To use OpenGL-enabled widgets in a Qt for Embedded Linux application, all that is required is to subclass the QGLWidget and draw into instances of the subclass with standard OpenGL functions. +Note that on most embedded hardware, the OpenGL implementation is +actually \l{http://www.khronos.org/opengles/1_X/}{OpenGL/ES 1.1} or +\l{http://www.khronos.org/opengles/2_X/}{OpenGL/ES 2.0}. When painting +within a QGLWidget::paintGL() override, it is necessary to limit the +application to only the features that are present in the OpenGL/ES +implementation. + \section2 Using OpenGL to Accelerate Normal 2D Painting -Qt provides QOpenGLPaintEngine, a subclass of QPaintEngine that -translates QPainter operations into OpenGL calls. This specialized -paint engine can be used to improve 2D rendering performance on -appropriate hardware. It can also overlay controls and decorations -onto 3D scenes drawn using OpenGL. +Qt provides a subclass of QPaintEngine that translates QPainter operations +into OpenGL calls (there are actually two subclasses, one for OpenGL/ES 1.1 +and another for OpenGL/ES 2.0). This specialized paint engine can be used +to improve 2D rendering performance on appropriate hardware. It can also +overlay controls and decorations onto 3D scenes drawn using OpenGL. + +As mentioned above, the OpenGL paint engine is not currently supported +in regular widgets. However, any application that uses QGraphicsView +can set a QGLWidget as the viewport and obtain access to the +OpenGL paint engine that way: + +\code +QGraphicsView view(&scene); +view.setViewport(new QGLWidget); +view.setViewportUpdateMode(QGraphicsView::FullViewportUpdate); +view.showFullScreen(); +\endcode + +It is recommended that the QGraphicsView::FullViewportUpdate flag +be set because the default double-buffered behavior of QGLWidget +does not support partial updates. It is also recommended that the +window be shown full-screen because that usually has the best +performance on current OpenGL/ES implementations. + +Once a QGraphicsView has been initialized as above, regular widgets +can be added to the canvas using QGraphicsProxyWidget if the +application requires them. \section2 Using OpenGL to Implement Window Compositing and Effects -Qt for Embedded Linux includes a complete windowing system, which implements -real transparency. The windowing system can be accelerated using -OpenGL to implement top level window compositing. This makes it easy -to add 3D effects to applications, for instance when windows are -minimized or maximized. - -\section1 Acceleration Architecture - -The diagram below shows the Qt for Embedded Linux painting architecture. - -\image qt-embedded-opengl3.png - -A client process widget uses a paint engine to draw into a window -surface. The server then combines the window surfaces and displays the -composition on the screen. This architecture lets you -control the steps of the painting process by subclassing. - -Subclassing QPaintEngine allows you to implement the QPainter API -using accelerated hardware. Subclassing QWindowSurface lets you -decide the properties of the space your widgets will draw themselves -into, as well as which paint engine they should use to draw themselves -into that space. Subclassing QScreen lets you control the creation of -window surfaces and lets you decide how to implement window -compositing. Using subclassing, your implementation work is minimized -since you can reuse base class functionality you don't need to change. +Compositing effects can be simulated by adjusting the opacity and +other parameters of the items within a QGraphicsView canvas on a +QGLWidget viewport. -The elements of an accelerated Qt for Embedded Linux system are shown in the -diagram below. +While Qt for Embedded Linux does include a complete windowing system, +using OpenGL to composite regular window surfaces can be quite difficult. +Most of Qt for Embedded Linux assumes that the window surface is a plain +raster memory buffer, with QGLWidget being the sole exception. +The need to constantly re-upload the raster memory buffers into OpenGL +textures for compositing can have a significant impact on performance, +which is why we do not recommend implementing that form of compositing. +We intend to address this problem in future versions of Qt. -\image qt-embedded-opengl1.png +\section1 Integrating OpenGL/ES into Qt for Embedded Linux -The applications, using the Qt API, do not depend on the presence of -the acceleration plugin. The plugin uses the graphics hardware to -accelerate painting primitives. Any operations not accelerated by the -plugin are done in software by the software paint engine. +\section2 Reference Integration -To integrate an OpenGL implementation into Qt for Embedded Linux for a -particular platform, you use the same mechanisms you would use for -writing any other accelerated driver. Base classes, e.g., QGLScreen -and QWSGLWindowSurface, are provided to minimize the need for -reimplementing common functionality. +The reference integration for OpenGL into Qt for Embedded Linux +is for the PowerVR chipset from \l{http://www.imgtec.com/}{Imagination +Technologies}. It consists of two components: \c{pvreglscreen} which +provides the Qt for Embedded Linux screen driver, and \c{QWSWSEGL} +which implements a plug-in to the PowerVR EGL implementation to +implement low-level OpenGL drawing surfaces. -\section1 The Reference Integration +\section2 Integrating Other Chipsets -The \l{OpenGL for Embedded Systems Example} is the reference implementation -for integrating OpenGL ES and \l{http://www.khronos.org/egl/}{EGL} with -the graphics acceleration architecture of Qt for Embedded Linux. -(\l{http://www.khronos.org/egl/}{EGL} is a library that binds OpenGL ES to -native windowing systems.) +In this section we discuss the essential features of the reference +integration that need to be provided for any other chipset integration. -The diagram below shows how OpenGL ES is used within the acceleration architecture: +The QtOpenGL module assumes that a QGLWidget can be represented +by a \c EGLNativeWindowType value in some underlying window system +implementation, and that \c{eglSwapBuffers()} is sufficient to copy +the contents of the native window to the screen when requested. -\image qt-embedded-opengl2.png +However, many EGL implementations do not have a pre-existing window system. +Usually only a single full-screen window is provided, and everything else +must be simulated some other way. This can be a problem because +of QtOpenGL's assumptions. We intend to address these assumptions in a +future version of Qt, but for now it is the responsibility of the integrator +to provide a rudimentary window system within the EGL implementation. +This is the purpose of \c{QWSWSEGL} in the reference integration. -The example implements a screen driver plugin that demonstrates all -three uses of OpenGL in Qt for Embedded Linux: 2D graphics acceleration, 3D -graphics operations using the \l {QtOpenGL module}, and top-level -window compositing and special effects. The applications still do -not talk directly to the accelerated plugin. +If it isn't possible for the EGL implementation to provide a rudimentary +window system, then full-screen windows using QGLWidget can be supported, +but very little else. -For 2D graphics, applications use the normal Qt painting API. The example accelerates 2D -painting by using the QOpenGLPaintEngine, which is included in the \l {QtOpenGL module}. +The screen driver needs to inherit from QGLScreen and perform the +following operations in its constructor: -For 3D graphics applications use the OpenGL API directly, together with the functionality -in the Qt OpenGL support classes. The example supports this by creating a -QWSGLWindowSurface whenever a QGLWidget is instantiated. +\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 0 -All access to the display is done through OpenGL. The example subclasses -QWSGLWindowSurface implementation and uses the \l -{http://oss.sgi.com/projects/ogl-sample/registry/EXT/framebuffer_object.txt} -{OpenGL Framebuffer Object extension} to draw windows into an offscreen buffer. This -lets the example use OpenGL to implement top level window compositing of opaque and -semi-transparent windows, and to provide a 3D animated transition effect as each new -window is shown. +The \c{setSurfaceFunctions()} call supplies an object that takes care +of converting Qt paint devices such as widgets and pixmaps into +\c EGLNativeWindowType and \c EGLNativePixmapType values. Here we +only support native windows. Because OpenGL rendering is direct to +the screen, we also indicate that client blit is supported. -The specific OpenGL library being used by the example restricts all -OpenGL operations to occur in a single process. Hence the example -creates instances of QWSGLWindowSurface only in the server process. -Other processes then perform 2D graphics by creating instances -of the standard QWindowSurface classes for client processes. The -standard window surface performs software-based rendering into a -shared memory segment. The server then transfers the contents of this -shared memory into an OpenGL texture before they are drawn onto the -screen during window compositing. +Next, we override the \c{createSurface()} functions in QGLScreen: -\omit +\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 1 -\section1 Future Directions +Even if Qt for Embedded Linux is used in single-process mode, it is +necessary to create both client-side and server-side versions of the +window surface. In our case, the server-side is just a stub because +the client side directly renders to the screen. -\section2 API Improvements +Note that we only create a \c{PvrEglWindowSurface} if the widget is a +QGLWidget. All other widgets use the normal raster processing. +It can be tempting to make \c{createSurface()} create an OpenGL +window surface for other widget types as well. This has not been +extensively tested and we do not recommend its use at this time. -Nokia is now working on enhancing the API for integrating OpenGL -with Qt for Embedded Linux. The current design plan includes the following -features: +The other main piece is the creation of the \c EGLNativeWindowType +value for the widget. This is done in the \c{createNativeWindow()} +override: -\list +\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 2 - \o Provide convenience classes, e.g., QEGLScreen and - QWSEGLWindowSurface, which implement common uses of the EGL - API. These classes will simplify implementing an OpenGL ES - integration. +The details of what needs to be placed in this function will vary +from chipset to chipset. The simplest is to return the native window +handle corresponding to the "root" full-screen window: - \o Extend the screen driver API to provide more control over window - properties and animations, and provide a software-based integration - to enable testing on the desktop. +\code +*native = rootWindowHandle; +return true; +\endcode - \o Improve performance as opportunities arise. +The most common value for \c rootWindowHandle is zero, but this may +not always be the case. Consult the chipset documentation for the +actual value to use. The important thing is that whatever value is +returned must be suitable for passing to the \c{eglCreateWindowSurface()} +function of the chipset's EGL implementation. -\endlist +In the case of PowerVR, the rudimentary window system in \c{QWSWSEGL} +provides a \c PvrQwsDrawable object to represent the \c EGLNativeWindowType +value for the widget. -\section2 OpenVG Support +\section1 OpenVG Support \l {http://www.khronos.org/openvg} {OpenVG} is a dedicated API for 2D graphics on mobile devices. It is therefore more likely to be a better -alternative for 2D acceleration than OpenGL. Until recently, no -OpenVG-capable hardware has been available, so Nokia has not yet -included an OpenVG solution in Qt for Embedded Linux. - -However, Nokia has done a feasibility study, implementing an -OpenVG paint engine on top of a software OpenVG implementation. -Assuming availability of the appropriate hardware, this OpenVG paint -engine can easily be completed and integrated using the existing -acceleration architecture. Since OpenVG shares the same EGL layer as -OpenGL ES, the work already done on the OpenGL integration can be -reused. - -Related technologies included in the \l -{http://www.khronos.org/openkode} {OpenKODE} API set will also be -considered. - -\endomit +alternative for 2D acceleration than OpenGL/ES. Acceleration of +regular widgets is supported with OpenVG, unlike with OpenGL/ES. +See \l{OpenVG Rendering in Qt} for more information on the +OpenVG support in Qt. */ diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc index a946540..cecff0e 100644 --- a/doc/src/qt4-intro.qdoc +++ b/doc/src/qt4-intro.qdoc @@ -546,29 +546,32 @@ trigger on signals and \l{QEvent}s. By inserting animations into the state machine, it is also easier to use the framework for animating GUIs, for instance. - + See \l{The State Machine Framework} documentation for more infromation. - \section1 Multi-touch & Gestures + \section1 Multi-Touch and Gestures - The new multi-touch and gestures support enables user interaction - with more than one finger, and combines sequential touch inputs to - a 'gesture'. + Support for multi-touch input enables users to interact with many + parts of a user interface at the same time, and provides the basis + for gestures. Additional infrastructure for gesture recognition + allows a sequence of touch inputs to be combined to create gestures + that can be used to activate features and trigger actions in an + application. \image gestures.png - The main benefits of this new functionality are: + This new functionality brings a number of benefits: \list - \o Allow users to interact with applications in better ways. - \o Simplify finger-based interaction with UI components. - \o Allowing common basic gestures and multi-touch - gestures. - \o Enable extensibility. + \o Allows users to interact with applications in more natural ways. + \o Simplifies finger-based interaction with UI components. + \o Combines support for common basic gestures and multi-touch gestures + in a single general framework. + \o Enables extensibility by design. \endlist - See the QTouchEvent class documentation for more information. The - Gesture framework API is still subject to change. + See the QTouchEvent class documentation for more information on multi-touch + input and QGestureEvent for gestures. \section1 DOM access API @@ -628,7 +631,7 @@ through C++ APIs in the Qt application, or using the xmlpatternsvalidator command line utility. The implementation of XML Schema Validation supports the specification version 1.0 in large parts. - + \img xml-schema.png See the \l{XML Processing} and QXmlSchema class documentation for more @@ -661,9 +664,10 @@ See the \l{QtMultimedia Module} documentation for more information. - \section1 Classes, functions, etc new in 4.6 + \section1 New Classes, Functions, Macros, etc - Links to classes, functions, and other items that are new in 4.6. + Links to new classes, functions, macros, and other items + introduced in Qt 4.6. \sincelist 4.6 diff --git a/doc/src/snippets/code/doc_src_examples_ahigl.qdoc b/doc/src/snippets/code/doc_src_examples_ahigl.qdoc deleted file mode 100644 index ccdce8b..0000000 --- a/doc/src/snippets/code/doc_src_examples_ahigl.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the Technology Preview License Agreement accompanying -** this package. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain additional -** rights. These rights are described in the Nokia Qt LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@nokia.com. -** -** -** -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [0] -myApplication -qws -display ahigl -//! [0] - - -//! [1] -myApplication -qws -display ahigl -//! [1] diff --git a/doc/src/snippets/gestures/qgesture.cpp b/doc/src/snippets/gestures/qgesture.cpp index 65f8b24..77f5cc2 100644 --- a/doc/src/snippets/gestures/qgesture.cpp +++ b/doc/src/snippets/gestures/qgesture.cpp @@ -64,7 +64,7 @@ private: QGesture *gesture; }; -/*! +/* \class QGesture \since 4.6 @@ -100,7 +100,7 @@ private: \sa QPanGesture */ -/*! \fn bool QGesture::filterEvent(QEvent *event) +/* \fn bool QGesture::filterEvent(QEvent *event) Parses input \a event and emits a signal when detects a gesture. @@ -111,7 +111,7 @@ private: This is a pure virtual function that needs to be implemented in subclasses. */ -/*! \fn void QGesture::started() +/* \fn void QGesture::started() The signal is emitted when the gesture is started. Extended information about the gesture is contained in the signal sender object. @@ -119,19 +119,19 @@ private: In addition to started(), a triggered() signal should also be emitted. */ -/*! \fn void QGesture::triggered() +/* \fn void QGesture::triggered() The signal is emitted when the gesture is detected. Extended information about the gesture is contained in the signal sender object. */ -/*! \fn void QGesture::finished() +/* \fn void QGesture::finished() The signal is emitted when the gesture is finished. Extended information about the gesture is contained in the signal sender object. */ -/*! \fn void QGesture::cancelled() +/* \fn void QGesture::cancelled() The signal is emitted when the gesture is cancelled, for example the reset() function is called while the gesture was in the process of emitting a @@ -140,7 +140,7 @@ private: */ -/*! +/* Creates a new gesture handler object and marks it as a child of \a parent. The \a parent object is also the default event source for the gesture, @@ -156,7 +156,7 @@ QGesture::QGesture(QObject *parent) parent->installEventFilter(this); } -/*! \internal +/* \internal */ QGesture::QGesture(QGesturePrivate &dd, QObject *parent) : QObject(dd, parent) @@ -165,14 +165,14 @@ QGesture::QGesture(QGesturePrivate &dd, QObject *parent) parent->installEventFilter(this); } -/*! +/* Destroys the gesture object. */ QGesture::~QGesture() { } -/*! \internal +/* \internal */ bool QGesture::eventFilter(QObject *receiver, QEvent *event) { @@ -182,13 +182,13 @@ bool QGesture::eventFilter(QObject *receiver, QEvent *event) return filterEvent(event); } -/*! +/* \property QGesture::state \brief The current state of the gesture. */ -/*! +/* Returns the gesture recognition state. */ Qt::GestureState QGesture::state() const @@ -196,7 +196,7 @@ Qt::GestureState QGesture::state() const return d_func()->state; } -/*! +/* Sets this gesture's recognition state to \a state and emits appropriate signals. @@ -237,7 +237,7 @@ void QGesture::updateState(Qt::GestureState state) } } -/*! +/* Sets the \a graphicsItem the gesture is filtering events for. The gesture will install an event filter to the \a graphicsItem and @@ -257,7 +257,7 @@ void QGesture::setGraphicsItem(QGraphicsItem *graphicsItem) graphicsItem->installSceneEventFilter(d->eventFilterProxyGraphicsItem); } -/*! +/* Returns the graphics item the gesture is filtering events for. \sa setGraphicsItem() @@ -267,7 +267,7 @@ QGraphicsItem* QGesture::graphicsItem() const return d_func()->graphicsItem; } -/*! \fn void QGesture::reset() +/* \fn void QGesture::reset() Resets the internal state of the gesture. This function might be called by the filterEvent() implementation in a derived class, or by the user to |