diff -r 000000000000 -r 1918ee327afb doc/src/platforms/emb-opengl.qdoc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/src/platforms/emb-opengl.qdoc Mon Jan 11 14:00:40 2010 +0000 @@ -0,0 +1,230 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qt-embedded-opengl.html + +\title Qt for Embedded Linux and OpenGL +\ingroup qt-embedded-linux + +\section1 Introduction + +\l {http://www.opengl.org}{OpenGL} is an industry standard API for +2D/3D graphics. It provides a powerful, low-level interface between +software and acceleration hardware, and it is operating system and +window system independent. + +\l {http://www.khronos.org/opengles}{OpenGL ES} is a subset +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 support for integrating \l +{http://www.khronos.org/opengles}{OpenGL ES} with Qt for Embedded Linux +for drawing into a QGLWidget. + +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. + +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 + +The \l {QtOpenGL module} offers classes that make it easy to draw 3D +graphics in GUI applications. The module API is cross-platform, so it +is also available on Windows, X11, and Mac OS X. + +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 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 + +Compositing effects can be simulated by adjusting the opacity and +other parameters of the items within a QGraphicsView canvas on a +QGLWidget viewport. + +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. + +\section1 Integrating OpenGL/ES into Qt for Embedded Linux + +\section2 Reference Integration + +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. + +\section2 Integrating Other Chipsets + +In this section we discuss the essential features of the reference +integration that need to be provided for any other chipset integration. + +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. + +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. + +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. + +The screen driver needs to inherit from QGLScreen and perform the +following operations in its constructor: + +\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 0 + +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. + +Next, we override the \c{createSurface()} functions in QGLScreen: + +\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 1 + +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. + +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. + +The other main piece is the creation of the \c EGLNativeWindowType +value for the widget. This is done in the \c{createNativeWindow()} +override: + +\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 2 + +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: + +\code +*native = rootWindowHandle; +return true; +\endcode + +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. + +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. + +\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/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. + +*/