The BlackBerry 10 Native SDK supports the OpenGL ES 1.1 API and the OpenGL ES 2.0 API. OpenGL ES allows you to render 2-D and 3-D graphics to a display. The OpenGL ES APIs are bound to an Embedded Graphics Library (EGL) surface which is bound to a native window. This forms a pipeline which your OpenGL ES code goes through.
We also have a OpenGL ES guide in the Core documentation that outlines using OpenGL ES in a Core app. All concepts discussed in the guide are relevant to using OpenGL ES in a Cascades app. However, using OpenGL ES in a Cascades app is different than using OpenGL ES in a Core app. This documentation will outline the differences and key concepts you need to know.
Standard graphics pipeline
To display an OpenGL ES model on a device, the standard graphics pipeline on BlackBerry 10 must be set up. Your OpenGL ES code is bound to an EGL surface that is bound to the Screen API. After the pipeline is set up, your OpenGL ES model displays on the device.
OpenGL ES is a 2-D and 3-D graphics API for embedded software systems. The OpenGL ES consists of a subset of the desktop OpenGL API. OpenGL ES interacts directly with the GPU to provide hardware-accelerated graphics in your application. BlackBerry 10 supports two versions of the OpenGL ES API:
- OpenGL ES 1.1 uses a fixed-function rendering pipeline, which allows you to render graphics using traditional lighting and shading models. You can configure stages of the pipeline for specific tasks or disable stages as required.
- OpenGL ES 2.0 uses a programmable rendering pipeline, which allows you to create shaders and program objects, as well as write vertex and fragment shaders using the OpenGL ES Shading Language.
Embedded Graphics Library
The Embedded Graphics Library (EGL) is an interface API between OpenGL ES and the native windowing system on BlackBerry 10. The Screen API provides access to the native windowing system. EGL is used for graphics resource management. EGL provides mechanisms for creating rendering surfaces that OpenGL ES can draw to, while also providing graphics contexts and rendering synchronization. BlackBerry 10 currently supports EGL version 1.4. For more information on EGL, see the Khronos EGL API Registry on the Khronos group website.
Native windowing systemYou can access the native windowing system on BlackBerry 10 by using the Screen API. You can create windows, define window groups, set up displays, and more. EGL is bound to the Screen API to provide a rendering surface for your OpenGL ES model. For more information about the Screen API, see the Screen Graphics Subsystem.
Choosing an OpenGL ES layout
Cascades renders windows through its own UI engine. OpenGL ES can't be bound directly to a window in a Cascades app. However, you can embed foreign windows into the UI of your Cascades app.
There are two layout methods to choose from when you use OpenGL ES in your Cascades app. The following diagram shows the two layout methods available: overlay and underlay.
An overlay is a Screen window that is placed on top of the Cascades window—that is, the Screen window has a higher Z depth than the Cascades window. Overlays are ideal for transparent 3-D controls and content; however, using transparent Screen windows might degrade performance due to window blending.
You can switch between the Screen window with the OpenGL ES model on it and the Cascades window by altering each window's Z depth. However, when the user changes the orientation of the device, you must manually adjust the size of the Screen window and EGL surface to correspond to the changes. When the Screen window is in the foreground window, BlackBerry Platform Services events must be used for event handling. If you put the Screen window to the background, the Cascades signals and slots must be used for incoming events.
To use overlays in your app, see Using overlays.
An underlay is a Screen window that is placed under windows in the Cascades app and gains visibility by using a ForeignWindowControl. Underlays are ideal for opaque 3-D controls and content. The ForeignWindowControl API is designed to allow you to embed Screen windows within the Cascades UI. The visibility of the Screen window can be altered directly from the ForeignWindowControl through the visible property. When you're using an underlay, all events are handled by signals and slots unless you specify (using ForeignWindowControl::keyInputForwardingEnabled) that events should be forwarded to the Screen window.
To use underlays in your app, see Using underlays.
One important aspect of using OpenGL ES in your app is to use a QThread for your OpenGL ES rendering code. Cascades renders through its own UI engine, so if threading isn't used, your OpenGL ES rendering code can be blocked while the Cascades UI engine processes. Blocking the rendering of OpenGL ES code can cause UI lag or flickering leading to a bad user experience. So, we'll avoid this by using threads to run independently from the Cascades UI engine which runs on the main thread. Threads should be used for both overlays and underlays because the same principle applies to both. We'll outline how this is done in Using threads.
Last modified: 2013-09-26