1 files changed, 227 insertions, 0 deletions
diff --git a/doc/src/platforms/emb-opengl.qdoc b/doc/src/platforms/emb-opengl.qdoc
new file mode 100644
index 0000000..e61ccde
--- /dev/null
+++ b/doc/src/platforms/emb-opengl.qdoc
@@ -0,0 +1,227 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $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 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.
+
+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
+
+Qt for Embedded Linux is shipped with a reference integration example
+that demonstrates all three uses.
+
+\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. 
+
+\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.
+
+\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.
+
+The elements of an accelerated Qt for Embedded Linux system are shown in the
+diagram below.
+
+\image qt-embedded-opengl1.png
+
+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.
+
+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.
+
+\section1 The Reference Integration
+
+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.)
+
+The diagram below shows how OpenGL ES is used within the acceleration architecture:
+
+\image qt-embedded-opengl2.png
+
+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. 
+
+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}.
+
+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.
+
+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 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.
+
+\omit
+
+\section1 Future Directions
+
+\section2 API Improvements
+
+Nokia is now working on enhancing the API for integrating OpenGL
+with Qt for Embedded Linux. The current design plan includes the following
+features:
+
+\list
+
+  \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.
+
+  \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.
+
+  \o Improve performance as opportunities arise.
+
+\endlist
+
+\section2 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
+
+*/