Introduction

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. OpenGL ES is a subset of the OpenGL standard. Because it is designed for use with embedded systems, it has a smaller, more constrained API.

OpenGL ES version 1.x is designed for fixed function hardware, while its successor OpenGL ES version 2.x is designed for programmable hardware. It is worth noting that there is a significant difference between the two, and that they are not compatible with each other. OpenGL ES 1.x limits processing to a pre-defined set of fixed options for drawing and lighting objects. OpenGL 2.x has a significantly shorter graphics pipeline than 1.x. Instead of using function transformation and a fragment pipeline, 2.x uses the OpenGL ES Shading Language (GLSL ES). Instead of using the pre-defined functions, the programmer writes small shader programs telling the hardware in detail how to render each object.

The QtOpenGL module offers classes that make it easy to draw 3D graphics in GUI applications using OpenGL ES. Qt provides a plugin that integrates both OpenGL ES versions 1.x and 2.x with Qt for Embedded. However, Qt for Embedded can be adapted to a wide range of OpenGL versions.

To translate QPainter operations into OpenGL ES calls (there are actually two subclasses, one for OpenGL/ES 1.1 and another for OpenGL/ES 2.0), Qt uses a subclass of QPaintEngine. 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.

Using OpenGL ES with Qt

To use OpenGL-enabled widgets in a Qt for Embedded application, all that is required is to subclass QGLWidget and draw into instances of the subclass with standard OpenGL functions. The current implementation only supports OpenGL ES and 2D painting within a QGLWidget. Using OpenGL ES to accelerate regular widgets as well as compositing top-level windows with OpenGL ES are not currently supported. These issues will be addressed in future versions of Qt.

Note: 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:

QGraphicsView view(&scene);
view.setViewport(new QGLWidget());
view.setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
view.setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
view.setViewportUpdateMode(QGraphicsView::FullViewportUpdate);
view.setFrameStyle(0);
view.showFullScreen();

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.

Note: OpenGL ES 2.X does not support PBuffers, so QGLPixelBuffer will not work. In this case, QGLFramebufferObject should be used instead. However, OpenGL ES 1.X does not support Framebuffer objects, with the exception of some OpenGL ES 1.X extensions. In this case, please use QGLPixelBuffer.

Note: On most embedded hardware, the OpenGL implementation is actually OpenGL/ES 1.1 or 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.

Using OpenGL with Qt for Embedded Linux

Qt for Embedded Linux provides support for integrating OpenGL ES 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.

Note: OpenGL rendering only works with QGLWidget under QWS. Regular widgets cannot currently support it.

Configure

It is recommended that Qt for Embedded Linux is configured with the -DQT_QWS_CLIENTBLIT and -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.

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.

Integrating OpenGL/ES into Qt for Embedded Linux

Reference Integration

The reference integration for OpenGL into Qt for Embedded Linux is for the PowerVR chipset from Imagination Technologies. It consists of two components: pvreglscreen, which provides the Qt for Embedded Linux screen driver, and QWSWSEGL, which implements a plug-in to the PowerVR EGL implementation to implement low-level OpenGL drawing surfaces.

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 an EGLNativeWindowType value in some underlying window system implementation, and that 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 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:

PvrEglScreen::PvrEglScreen(int displayId)
    : QGLScreen(displayId)
{
    setOptions(NativeWindows);
    setSupportsBlitInClients(true);
    setSurfaceFunctions(new PvrEglScreenSurfaceFunctions(this, displayId));

The setSurfaceFunctions() call supplies an object that takes care of converting Qt paint devices such as widgets and pixmaps into EGLNativeWindowType and 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 createSurface() functions in QGLScreen:

QWSWindowSurface* PvrEglScreen::createSurface(QWidget *widget) const
{
    if (qobject_cast<QGLWidget*>(widget))
        return new PvrEglWindowSurface(widget, (PvrEglScreen *)this, displayId);

    return QScreen::createSurface(widget);
}

QWSWindowSurface* PvrEglScreen::createSurface(const QString &key) const
{
    if (key == QLatin1String("PvrEgl"))
        return new PvrEglWindowSurface();

    return QScreen::createSurface(key);
}

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 PvrEglWindowSurface if the widget is a QGLWidget. All other widgets use the normal raster processing. It can be tempting to make 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 EGLNativeWindowType value for the widget. This is done in the createNativeWindow() override:

bool PvrEglScreenSurfaceFunctions::createNativeWindow(QWidget *widget, EGLNativeWindowType *native)
{

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:

*native = rootWindowHandle;
return true;

The most common value for 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 eglCreateWindowSurface() function of the chipset's EGL implementation.

In the case of PowerVR, the rudimentary window system in QWSWSEGL provides a PvrQwsDrawable object to represent the EGLNativeWindowType value for the widget.