1 \section1 Introduction

     2 

     3 \l {http://www.opengl.org}{OpenGL} is an industry standard API for

     4 2D/3D graphics. It provides a powerful, low-level interface between

     5 software and acceleration hardware, and it is operating system and

     6 window system independent. \l {http://www.khronos.org/opengles}{OpenGL ES}

     7 is a subset of the \l {http://www.opengl.org}{OpenGL} standard. Because it

     8 is designed for use with embedded systems, it has a smaller, more

     9 constrained API.

    10 

    11 \l {http://www.khronos.org/opengles/1_X}{OpenGL ES version 1.x} is designed for

    12 fixed function hardware, while its successor \l

    13 {http://www.khronos.org/opengles/2_X}{OpenGL ES version 2.x} is designed for

    14 programmable hardware. It is worth noting that there is a significant

    15 difference between the two, and that they are not compatible with each

    16 other. OpenGL ES 1.x limits processing to a pre-defined set of fixed

    17 options for drawing and lighting objects. OpenGL 2.x has a significantly

    18 shorter graphics pipeline than 1.x. Instead of using function

    19 transformation and a fragment pipeline, 2.x uses the \l

    20 {http://www.khronos.org/registry/gles/specs/2.0/GLSL_ES_Specification_1.0.17.pdf}{OpenGL

    21 ES Shading Language (GLSL ES)}. Instead of using the pre-defined functions,

    22 the programmer writes small shader programs telling the hardware in detail

    23 how to render each object.

    24 

    25 The \l {QtOpenGL module} offers classes that make it easy to draw 3D

    26 graphics in GUI applications using OpenGL ES. Qt provides a plugin that

    27 integrates both OpenGL ES versions \l

    28 {http://www.khronos.org/opengles/1_X}{1.x} and \l

    29 {http://www.khronos.org/opengles/2_X}{2.x} with Qt for Embedded. However,

    30 Qt for Embedded can be adapted to a wide range of OpenGL versions.

    31 

    32 To translate QPainter operations into OpenGL ES calls (there are actually

    33 two subclasses, one for OpenGL/ES 1.1 and another for OpenGL/ES 2.0), Qt

    34 uses a subclass of QPaintEngine.  This specialized paint engine can be used

    35 to improve 2D rendering performance on appropriate hardware.  It can also

    36 overlay controls and decorations onto 3D scenes drawn using OpenGL. 

    37 

    38 \tableofcontents 

    39 

    40 \section1 Using OpenGL ES with Qt

    41 To use OpenGL-enabled widgets in a Qt for Embedded application, all that is

    42 required is to subclass QGLWidget and draw into instances of the subclass

    43 with standard OpenGL functions. The current implementation only

    44 supports OpenGL ES and 2D painting within a QGLWidget. Using OpenGL ES to

    45 accelerate regular widgets as well as compositing top-level windows with

    46 OpenGL ES are not currently supported. These issues will be addressed in

    47 future versions of Qt.

    48 

    49 \note The OpenGL paint engine is not currently supported in regular

    50 widgets. However, any application that uses QGraphicsView can set a

    51 QGLWidget as the viewport and obtain access to the OpenGL paint engine that

    52 way:

    53 

    54 \code

    55     QGraphicsView view(&scene);

    56     view.setViewport(new QGLWidget());

    57     view.setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);

    58     view.setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOff);

    59     view.setViewportUpdateMode(QGraphicsView::FullViewportUpdate);

    60     view.setFrameStyle(0);

    61     view.showFullScreen();

    62 \endcode

    63 

    64 It is recommended that the QGraphicsView::FullViewportUpdate flag

    65 be set because the default double-buffered behavior of QGLWidget

    66 does not support partial updates. It is also recommended that the

    67 window be shown full-screen because that usually has the best

    68 performance on current OpenGL ES implementations.

    69 

    70 Once a QGraphicsView has been initialized as above, regular widgets

    71 can be added to the canvas using QGraphicsProxyWidget if the

    72 application requires them.

    73 

    74 \note OpenGL ES 2.X does not support PBuffers, so QGLPixelBuffer will not

    75 work. In this case, QGLFramebufferObject should be used instead. However,

    76 OpenGL ES 1.X does not support Framebuffer objects, with the exception of

    77 some OpenGL ES 1.X extensions. In this case, please use QGLPixelBuffer. 

    78 

    79 \note On most embedded hardware, the OpenGL implementation is

    80 actually \l{http://www.khronos.org/opengles/1_X/}{OpenGL/ES 1.1} or

    81 \l{http://www.khronos.org/opengles/2_X/}{OpenGL/ES 2.0}.  When painting

    82 within a QGLWidget::paintGL() override, it is necessary to limit the

    83 application to only the features that are present in the OpenGL/ES

    84 implementation.

    85