EGL API - Native Platform Graphics Interface

You can use the javax.microedition.khronos.egl package to provide bindings for EGL™ 1.0 and 1.1 for the OpenGL® ES API. The rendering contexts that are supported provide a container for the OpenGL ES rendering state.

The rendering surfaces that are supported include the following:

  • Window surfaces: onscreen rendering
  • Pbuffer surfaces: offscreen rendering of pixel buffers
  • Pixmap surfaces: offscreen rendering to client buffers

The most commonly used feature of this package is the EGL10 interface. This interface contains the programming language bindings for EGL 1.0.

All OpenGL ES drawing except to Pbuffer surfaces must be preceded by a call to eglWaitNative(EGL10.EGL_CORE_NATIVE_ENGINE, target) where target is an object that describes the rendering target. This must be followed by a call to eglWaitGL(). When drawing to an image, the results are not guaranteed to appear in the image pixels until eglWaitGL() has returned.

Pbuffer surfaces are created using EGL10.eglCreatePbufferSurface() and are accessible only from EGL-based APIs.

Code sample: Rendering a single frame using EGL10

private void render()
{
    if (!egl.eglMakeCurrent(eglDisplay, eglSurface, eglSurface, eglContext))
    {
        int error = egl.eglGetError();

        if ( error == EGL11.EGL_CONTEXT_LOST )
            handleContextLost();
        else
            handleError("eglMakeCurrent failed: " + error);
    }
        
    // Signal that we're about to begin GL rendering
    egl.eglWaitNative(EGL10.EGL_CORE_NATIVE_ENGINE, graphics);
        
    // Check for a viewport change
    if (vpWidth != getWidth() || vpHeight != getHeight())
    {
        vpWidth = getWidth();
        vpHeight = getHeight();
        renderer.sizeChanged(gl, vpWidth, vpHeight);
    }
        
    renderer.render(gl);
        
    // Signal that we're finish GL rendering
    egl.eglWaitGL();
}

Set up EGL

  1. Get an object that implements the EGL™ 1.1 interface.
    EGL11 egl = (EGL11)EGLContext.getEGL();
  2. Get and initialize the default EGL display.
    EGLDisplay eglDisplay = egl.eglGetDisplay(EGL11.EGL_DEFAULT_DISPLAY);
    egl.eglInitialize(eglDisplay, null);
  3. Specify the configuration attributes that you want.
    int[] configAttributes = { 
    EGL11.EGL_RED_SIZE, 5,
    EGL11.EGL_GREEN_SIZE, 6,
    EGL11.EGL_BLUE_SIZE, 5,
    EGL11.EGL_ALPHA_SIZE, EGL11.EGL_DONT_CARE,
    EGL11.EGL_DEPTH_SIZE, EGL11.EGL_DONT_CARE,
    EGL11.EGL_STENCIL_SIZE, EGL11.EGL_DONT_CARE,
    EGL11.EGL_NONE}
  4. Create an integer array with one element to hold the return value that indicates the number of EGL configurations that matched the attributes specified by the configAttributes array. Create an EGLConfig array with one element to store the first EGL configuration that matches the attributes. Invoke eglChooseConfig() and provide, as arguments, the EGLDisplay object that you initialized in step 2, the array that specifies the configuration attributes to match, a placeholder for the first matching EGLConfig object, the size of the EGLConfig placeholder (1), and the num_configs array to store the number of configurations that matched. Store the single configuration from the eglConfigs array in the EGLConfig variable eglConfig.
    int[] num_configs = new int[1];
    EGLConfig[] eglConfigs = new EGLConfigs[1];
    egl.eglChooseConfig(eglDisplay,configAttributes,eglConfigs,1, num_configs);
    EGLConfig eglConfig = eglConfigs[0];
  5. Invoke eglCreateWindowSurface() to create an EGL surface and provide, as arguments, eglDisplay and eglConfig, which are the instances of EGLDisplay and EGLConfig that you set up in steps 2 and 4. In the following code sample, eglCreateWindowSurface() is invoked from a class that is derived from the Screen class, and the this argument binds the EGLSurface object to the current screen.
    EGLSurface eglSurface = egl.eglCreateWindowSurface(eglDisplay, eglConfig, this, null);
  6. Invoke eglCreateContext() to create an EGL context.
    EGLContext eglContext = egl.eglCreateContext(eglDisplay, eglConfig, EGL10.EGL_NO_CONTEXT, null);
  7. Invoke eglMakeCurrent() to bind the EGL context to the EGL surface and EGL display.
    egl.eglMakeCurrent(eglDisplay, eglSurface, eglSurface, eglContext);
You can now use the statement gl = (GL11)eglContext.getGL(); to get an object that implements the GL11 interface, which lets you start working with OpenGL ES 1.1.
Next topic: Native I/O
Previous topic: JSR 239 packages

Was this information helpful? Send us your comments.