+ +

eglIntro

+ introduction to managing client API rendering through the + EGL API. +

+ +

Overview

+ The Khronos Native Platform Graphics + Interface (EGL) provides a means for rendering + using a client API such as OpenGL ES + (a 3D renderer for embedded systems), OpenGL (a functional + superset of OpenGL ES for desktop systems), and OpenVG (a 2D + vector graphics renderer) together with a native window + system, such as Microsoft Windows or the X Window System. +

+ Depending on its implementation EGL might be more or less + tightly integrated into the native window system. Most EGL + functions require an EGL display connection, which can be + obtained by calling + eglGetDisplay + and passing in a native display handle or + EGL_DEFAULT_DISPLAY. To initialize and + query what EGL version is supported on the display + connection, call + eglInitialize. +

+ Native window systems supporting EGL make a subset of their + visuals (which may also referred to as pixel formats, frame + buffer configurations, or other similar terms) available for + client API rendering. Windows and pixmaps created with these + visuals may also be rendered into using the native window + system API. +

+ An EGL surface extends a native + window or pixmap with additional auxillary + buffers. These buffers include a color buffer, a + depth buffer, a stencil buffer, and an alpha mask buffer. + Some or all of the buffers listed are included in each EGL + frame buffer configuration. +

+ EGL supports rendering into three types of surfaces: + windows, pixmaps and pixel buffers (pbuffers). EGL window + and pixmap surfaces are associated with corresponding + resources of the native window system. EGL pixel buffers are + EGL only resources, and do not accept rendering through the + native window system. +

+ To render using a client API into an EGL surface, you must + determine the appropriate EGL frame buffer configuration, + which supports the rendering features the application + requires. + eglChooseConfig + returns an EGLConfig matching the required + attributes, if any. A complete list of EGL frame buffer + configurations can be obtained by calling + eglGetConfigs. + Attributes of a particular EGL frame buffer configuration + can be queried by calling + eglGetConfigAttrib. +

+ For EGL window and pixmap surfaces, a suitable native window + or pixmap with a matching native visual must be created + first. For a given EGL frame buffer configuration, the + native visual type and ID can be retrieved with a call to + eglGetConfigAttrib. + For pixel buffers, no underlying native resource is + required. +

+ To create an EGL window surface from a native window, call + eglCreateWindowSurface. + To create an EGL pixmap surface from a native pixmap, call + eglCreatePixmapSurface. + To create a pixel buffer (pbuffer) surface (which has no + associated native buffer), call + eglCreatePbufferSurface + To create a pixel buffer (pbuffer) surface whose color + buffer is provided by an OpenVG VGImage, call + eglCreatePbufferFromClientBuffer. + Use + eglDestroySurface + to release previously allocated resources. +

+ An EGL rendering context is required to bind client API + rendering to an EGL surface. An EGL surface and an EGL + rendering context must have compatible EGL frame buffer + configurations. To create an EGL rendering context, call + eglCreateContext. + The type of client API context created (OpenGL ES, OpenVG, + etc.) can be changed by first calling + eglBindAPI. +

+ An EGL rendering context may be bound to one or two EGL + surfaces by calling + eglMakeCurrent. + This context/surface(s) association specifies the + current context and + current surface, and is used by all + client API rendering commands for the bound context until + eglMakeCurrent + is called with different arguments. +

+ Both native and client API commands may be used to operate + on certain surfaces, however, the two command streams are + not synchronized. Synchronization can be explicitly + specified using by calling + eglWaitCLient, + eglWaitNative, + and possibly by calling other native window system commands. +

+ +

Examples

+ Below is a minimal example of creating an RGBA-format window that + allows rendering with OpenGL ES. + The window is cleared to yellow when the program runs. For simplicity, + the program does not check for any errors. +

+#include <stdlib.h>
+#include <unistd.h>
+#include <EGL/egl.h>
+#include <GLES/gl.h>
+typedef ... NativeWindowType;
+extern NativeWindowType createNativeWindow(void);
+static EGLint const attribute_list[] = {
+        EGL_RED_SIZE, 1,
+        EGL_GREEN_SIZE, 1,
+        EGL_BLUE_SIZE, 1,
+        EGL_NONE
+};
+int main(int argc, char ** argv)
+{
+        EGLDisplay display;
+        EGLConfig config;
+        EGLContext context;
+        EGLSurface surface;
+        NativeWindowType native_window;
+        EGLint num_config;
+
+        /* get an EGL display connection */
+        display = eglGetDisplay(EGL_DEFAULT_DISPLAY);
+
+        /* initialize the EGL display connection */
+        eglInitialize(display, NULL, NULL);
+
+        /* get an appropriate EGL frame buffer configuration */
+        eglChooseConfig(display, attribute_list, &config, 1, &num_config);
+
+        /* create an EGL rendering context */
+        context = eglCreateContext(display, config, EGL_NO_CONTEXT, NULL);
+
+        /* create a native window */
+        native_window = createNativeWindow();
+
+        /* create an EGL window surface */
+        surface = eglCreateWindowSurface(display, config, native_window, NULL);
+
+        /* connect the context to the surface */
+        eglMakeCurrent(display, surface, surface, context);
+
+        /* clear the color buffer */
+        glClearColor(1.0, 1.0, 0.0, 1.0);
+        glClear(GL_COLOR_BUFFER_BIT);
+        glFlush();
+
+        eglSwapBuffers(display, surface);
+
+        sleep(10);
+        return EXIT_SUCCESS;
+}
+

+ +

Using EGL Extensions

+ All supported EGL extensions will have a corresponding definition in + egl.h and a token in the extensions string returned + by + eglQueryString. +

+ +

Future EGL Versions

+ eglInitialize + and + eglQueryString + can be used to determine at run-time what version of EGL is available. + To check the EGL version at compile-time, test whether + EGL_VERSION_x_y + is defined, where x and + y are the major and minor version + numbers. +

+ +

Files

+ + GLES/egl.h + +: +
+ EGL header file +
+

+ +