diff options
| -rw-r--r-- | doc/src/platforms/emb-opengl.qdoc | 230 |
1 files changed, 0 insertions, 230 deletions
diff --git a/doc/src/platforms/emb-opengl.qdoc b/doc/src/platforms/emb-opengl.qdoc deleted file mode 100644 index 2ed5d04..0000000 --- a/doc/src/platforms/emb-opengl.qdoc +++ /dev/null @@ -1,230 +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$ -** -****************************************************************************/ - -/*! -\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. - -*/ |