javax.microedition.khronos.egl
Interface EGL10

All Superinterfaces:
EGL
All Known Subinterfaces:
EGL11, EGL12

public interface EGL10
extends EGL

The EGL10 interface contains the Java(TM) programming language bindings for EGL 1.0.

The documentation in this interface is normative with respect to instance variable names and values, method names and signatures, and exception behavior. The remaining documentation is placed here for convenience and does not replace the normative documentation found in the EGL specification and relevant extension specifications. EGL documentation is available at the Khronos web site.

Extensions may return values or allow arguments to take on values other than those listed in this specification. Implementations that provide a given extension must pass such values to and from the underlying engine.

If a method throws an exception, the state of the underlying EGL engine is left intact.

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 a platform-specific object describing the rendering target, and followed by a call to eglWaitGL(). Between these calls, the results of calls or calls to any other drawing API, such as MIDP, JSR 184, java.awt, etc., are undefined. When drawing to an image, the results are not guaranteed to appear in the image pixels until eglWaitGL has returned.

It is not required that calls to methods of this interface be mapped one-to-one onto calls to functions in the underlying EGL implementation. Implementations may contain logic to manage configurations, drawing surface access, threading issues, etc., as required in order to integrate EGL-based APIs with other platform drawing APIs. For example, an implementation that makes use of a software back buffer may translate a call to EGL10.eglCreateWindowSurface into a call to the native function eglCreatePixmapSurface targetting the buffer. Naturally, hardware-accelerated implementations should endeavor to avoid such workarounds.

Drawing to a Pbuffer

A Pbuffer is an invisible, possibly hardware-accelerated buffer. Pbuffer surfaces are created using the EGL10.eglCreatePbufferSurface method. Pbuffers are accessible only from EGL-based APIs, and follow the rules set out in the EGL specification. Pbuffers may be used in the same manner on any Java platform.

The integration between EGL and specific Java ME platforms is as follows.

CLDC/MIDP

On the CLDC/MIDP platform, drawing can be performed to four types of targets: javax.microedition.lcdui.Canvas, javax.microedition.lcdui.game.GameCanvas, (mutable) javax.microedition.lcdui.Image, or to a Pbuffer.

The EGL_DEFAULT_DISPLAY token is used to specify a display.

Drawing to a Canvas or GameCanvas

A Canvas or GameCanvas is specified as a drawing target using the eglCreateWindowSurface method. The native_window argument must be an instance of javax.microedition.lcdui.Graphics that was obtained directly from the argument to the Canvas.paint() method or from the GameCanvas.getGraphics() method.

Drawing to a Canvas or GameCanvas allows for mixing of different drawing APIs.

When drawing to a Canvas (that is not a GameCanvas), drawing must take place entirely within the scope of a system-generated call to the Canvas's paint(Graphics) method. The results of drawing to a Canvas outside the scope of such a call are undefined.

Calling eglSwapBuffers is equivalent to calling glFinish, and does not affect the screen output. The normal GameCanvas.flushGraphics method is used to control screen output.

The initial contents of the back buffer for a GameCanvas are initialized to white, and calls to flushGraphics do not alter the buffer contents.

   import javax.microedition.lcdui.Display;
   import javax.microedition.lcdui.Graphics;
   import javax.microedition.lcdui.game.GameCanvas;
   import javax.microedition.midlet.MIDlet;
   import javax.microedition.khronos.egl.*;
   import javax.microedition.khronos.opengles.*;
   
   class MyGameCanvas extends GameCanvas 
   {
     EGL11 egl;
     GL11 gl;
     Graphics midpGraphics;
     javax.microedition.m3g.Graphics3D m3gContext;
     
     MyGameCanvas(MIDlet thisMIDlet) 
     {
         // This example doesn't require key events
        super(true);
   
        // Get a Graphics instance for MIDP rendering
        // and to use in createWindowSurface
        this.midpGraphics = getGraphics();
   
        // Show this GameCanvas on the display
        Display display = Display.getDisplay(thisMIDlet);
        display.setCurrent(this);
   
        // Create an EGL instance
        this.egl = (EGL11)EGLContext.getEGL();
   
        // Get the EGL display object and initialize EGL
        EGLDisplay eglDisplay = egl.eglGetDisplay(EGL11.EGL_DEFAULT_DISPLAY);
        int[] major_minor = new int[2];
        egl.eglInitialize(eglDisplay, major_minor);
        System.out.println("EGL revision: major = " + major_minor[0]);
        System.out.println("EGL revision: minor = " + major_minor[1]);
   
        // Determine the number of available configurations
        int[] num_config = new int[1];
        egl.eglGetConfigs(eglDisplay, null, 0, num_config);
        System.out.println("There are " + num_config[0] + " configurations");
   
        // Locate an 5/6/5 RGB configuration
        int[] configAttrs = { 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
        };
   
        // Grab the first matching config
        EGLConfig[] eglConfigs = new EGLConfig[1];
        egl.eglChooseConfig(eglDisplay, configAttrs, eglConfigs, 1, num_config);
        EGLConfig eglConfig = eglConfigs[0];
    
        // Get a context for EGL rendering
        EGLContext eglContext = egl.eglCreateContext(eglDisplay, eglConfig, EGL11.EGL_NO_CONTEXT, null);
   
        // Get a GL object for rendering
        this.gl = (GL11)eglContext.getGL();
   
        // Bind a window surface to the context
        EGLSurface eglSurface = egl.eglCreateWindowSurface(eglDisplay, eglConfig, midpGraphics, null);
   
        // Make the context current for future GL calls
        egl.eglMakeCurrent(eglDisplay, eglSurface, eglSurface, eglContext);
   
        // Get a context for M3G rendering
        this.m3g = ...;
      }
    
      // The update loop
      public void run() 
      {
        while (true) 
        {
          // Do some MIDP 2D rendering
          // Use of OpenGL ES or M3G is not allowed here
          // MIDP primitives drawn here will appear underneath the
          // OpenGL ES drawing
          midpGraphics.drawLine(...);
   
          // Wait for MIDP drawing to complete
          egl.eglWaitNative(EGL11.EGL_CORE_NATIVE_ENGINE, midpGraphics);
          // Now it is O.K. to use OpenGL ES drawing APIs
   
          // Do some OpenGL ES rendering
          // Use of MIDP, JSR 184, or other drawing APIs is undefined here
          gl.glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
          gl.glClear(GL11.GL_COLOR_BUFFER_BIT | GL11.GL_DEPTH_BUFFER_BIT);
          gl.glFrustumf(...);
          // etc.
   
          // Wait for OpenGL ES rendering to complete
          egl.eglWaitGL();
          // Now it is O.K. to use MIDP drawing APIs
   
          // MIDP primitives drawn here will appear on top of the
          // OpenGL ES drawing
          midpGraphics.drawRect(...);
   
          // Do some M3G (JSR 184) rendering
          m3g.bindTarget(midpGraphics, ...);
          // Now it is O.K. to use M3G, but not MIDP or OpenGL ES
   
          // M3G commands go here
   
          // Wait for M3G drawing to complete
          m3g.releaseTarget();
          // Now it is O.K. to use MIDP drawing APIs
    
          // Do some more MIDP 2D rendering
          // MIDP primitives drawn here will appear on top of the
          // OpenGL ES and M3G drawings
          midp_graphics.drawArc(...);
    
          // Flush the back buffer to the screen
          flushGraphics();
        }
      }
    }
 

Drawing to an Image

The eglCreatePixmapSurface method allows drawing to an Image. The Image must be mutable. The native_pixmap argument must be an instance of javax.microedition.lcdui.Graphics that was obtained from the Image's getGraphics() method.

OpenGL ES drawing must be bracketed between calls to eglWaitNative and eglWaitGL in the same manner as for Canvas and GameCanvas. Calling eglSwapBuffers is equivalent to calling glFinish, since there is no back buffer.

Drawing to an EGLCanvas

EGLCanvas maximizes the potential for efficiency by removing the requirement to allow non-OpenGL ES drawing. The results of drawing to an EGLCanvas using other non-EGL based APIs such as MIDP and JSR 184 is undefined.

An EGLCanvas is specified as a drawing target using the eglCreateWindowSurface method. The native_window argument must be an instance of javax.microedition.lcdui.Graphics that was obtained directly from the EGLCanvas.getGraphics() method.

When an EGLCanvas is set using the Display.setCurrent method, it occupies as much of the screen as is allowed by the platform (leaving room for a status bar if the platform requires one). OpenGL ES drawing is performed to a back buffer, the contents of which are initially undefined. When drawing is complete, a call to eglSwapBuffers causes the contents of the back buffer to be copied to the screen. Following the call, the back buffer contents are once again undefined.

Other platforms

The current specification does not address AWT-based platforms such as CDC/Personal Basis Profile, CDC/Personal Profile, and Java Standard Edition. The details of how to bind to displays and surfaces on these platforms will be provided in a future release of the specification.

Since:
BlackBerry API 5.0.0

Field Summary
static int EGL_ALPHA_SIZE
          EGLConfig attribute name.
static int EGL_BAD_ACCESS
          EGL error code indicating 'bad access'.
static int EGL_BAD_ALLOC
          EGL error code indicating 'bad alloc'.
static int EGL_BAD_ATTRIBUTE
          EGL error code indicating 'bad attribute'.
static int EGL_BAD_CONFIG
          EGL error code indicating 'bad config'.
static int EGL_BAD_CONTEXT
          EGL error code indicating 'bad context'.
static int EGL_BAD_CURRENT_SURFACE
          EGL error code indicating 'bad current surface'.
static int EGL_BAD_DISPLAY
          EGL error code indicating 'bad display'.
static int EGL_BAD_MATCH
          EGL error code indicating 'bad match'.
static int EGL_BAD_NATIVE_PIXMAP
          EGL error code indicating 'bad native pixmap'.
static int EGL_BAD_NATIVE_WINDOW
          EGL error code indicating 'bad native window'.
static int EGL_BAD_PARAMETER
          EGL error code indicating 'bad parameter'.
static int EGL_BAD_SURFACE
          EGL error code indicating 'bad surface'.
static int EGL_BLUE_SIZE
          EGLConfig attribute name.
static int EGL_BUFFER_SIZE
          EGLConfig attribute name.
static int EGL_CONFIG_CAVEAT
          EGLConfig attribute name.
static int EGL_CONFIG_ID
          EGLConfig attribute name.
static int EGL_CORE_NATIVE_ENGINE
          Constant for use as the engine argument of eglWaitNative, indicating the core native engine of the platform.
static Object EGL_DEFAULT_DISPLAY
          An object that is used as an argument to eglGetDisplay to indicate that the defalt display of the device is to be used.
static int EGL_DEPTH_SIZE
          EGLConfig attribute name.
static int EGL_DONT_CARE
          EGLConfig attribute value.
static int EGL_DRAW
          Constant for use in the readdraw argument of eglGetCurrentSurface.
static int EGL_EXTENSIONS
          Constant for use in eglQueryString.
static int EGL_FALSE
          A value corresponding to the 'EGLBoolean' false value.
static int EGL_GREEN_SIZE
          EGLConfig attribute name.
static int EGL_HEIGHT
          EGLSurface attribute name.
static int EGL_LARGEST_PBUFFER
          EGLSurface attribute name.
static int EGL_LEVEL
          EGLConfig attribute name.
static int EGL_MAX_PBUFFER_HEIGHT
          EGLConfig attribute name.
static int EGL_MAX_PBUFFER_PIXELS
          EGLConfig attribute name.
static int EGL_MAX_PBUFFER_WIDTH
          EGLConfig attribute name.
static int EGL_NATIVE_RENDERABLE
          EGLConfig attribute name.
static int EGL_NATIVE_VISUAL_ID
          EGLConfig attribute name.
static int EGL_NATIVE_VISUAL_TYPE
          EGLConfig attribute name.
static int EGL_NONE
          EGLConfig attribute name and value.
static int EGL_NON_CONFORMANT_CONFIG
          EGLConfig attribute value.
static int EGL_NOT_INITIALIZED
          EGL error code indicating 'not initialized'.
static EGLContext EGL_NO_CONTEXT
          An EGLContext object used to indicate a null context.
static EGLDisplay EGL_NO_DISPLAY
          An EGLContext object used to indicate a null display.
static EGLSurface EGL_NO_SURFACE
          An EGLContext object used to indicate a null surface.
static int EGL_PBUFFER_BIT
          EGLConfig attribute value.
static int EGL_PIXMAP_BIT
          EGLConfig attribute value.
static int EGL_PRESERVED_RESOURCES
          EGLConfig attribute name.
static int EGL_READ
          Constant for use in the readdraw argument of eglGetCurrentSurface.
static int EGL_RED_SIZE
          EGLConfig attribute name.
static int EGL_SAMPLES
          EGLConfig attribute name.
static int EGL_SAMPLE_BUFFERS
          EGLConfig attribute name.
static int EGL_SLOW_CONFIG
          EGLConfig attribute value.
static int EGL_STENCIL_SIZE
          EGLConfig attribute name.
static int EGL_SUCCESS
          EGL error code indicating success.
static int EGL_SURFACE_TYPE
          EGLConfig attribute name.
static int EGL_TRANSPARENT_BLUE_VALUE
          EGLConfig attribute name.
static int EGL_TRANSPARENT_GREEN_VALUE
          EGLConfig attribute name.
static int EGL_TRANSPARENT_RED_VALUE
          EGLConfig attribute name.
static int EGL_TRANSPARENT_RGB
          EGLConfig attribute value.
static int EGL_TRANSPARENT_TYPE
          EGLConfig attribute name.
static int EGL_TRUE
          A value corresponding to the 'EGLBoolean' true value.
static int EGL_VENDOR
          Constant for use in eglQueryString.
static int EGL_VERSION
          Constant for use in eglQueryString.
static int EGL_WIDTH
          EGLSurface attribute name.
static int EGL_WINDOW_BIT
          EGLConfig attribute value.
 
Method Summary
 boolean eglChooseConfig(EGLDisplay display, int[] attrib_list, EGLConfig[] configs, int config_size, int[] numConfig)
          Return a list of EGL frame buffer configurations that match specified attributes.
 boolean eglCopyBuffers(EGLDisplay display, EGLSurface surface, Object native_pixmap)
          Copy EGL surface color buffer to a native pixmap.
 EGLContext eglCreateContext(EGLDisplay display, EGLConfig config, EGLContext share_context, int[] attrib_list)
          Create a new EGL rendering context.
 EGLSurface eglCreatePbufferSurface(EGLDisplay display, EGLConfig config, int[] attrib_list)
          Create a new EGL pixel buffer surface.
 EGLSurface eglCreatePixmapSurface(EGLDisplay display, EGLConfig config, Object native_pixmap, int[] attrib_list)
          Create a new EGL pixmap surface.
 EGLSurface eglCreateWindowSurface(EGLDisplay display, EGLConfig config, Object native_window, int[] attrib_list)
          Create a new EGL window surface.
 boolean eglDestroyContext(EGLDisplay display, EGLContext context)
          Destroy an EGL rendering context.
 boolean eglDestroySurface(EGLDisplay display, EGLSurface surface)
          Destroy an EGL surface.
 boolean eglGetConfigAttrib(EGLDisplay display, EGLConfig config, int attribute, int[] value)
          Return information about an EGL frame buffer configuration.
 boolean eglGetConfigs(EGLDisplay display, EGLConfig[] configs, int config_size, int[] num_config)
          Return a list of all EGL frame buffer configurations for a display.
 EGLContext eglGetCurrentContext()
          Return the current EGL rendering context.
 EGLDisplay eglGetCurrentDisplay()
          Return the display for the current EGL rendering context.
 EGLSurface eglGetCurrentSurface(int readdraw)
          Return the read or draw surface for the current EGL rendering context.
 EGLDisplay eglGetDisplay(Object native_display)
          Return an EGL display connection.
 int eglGetError()
          Return error information.
 boolean eglInitialize(EGLDisplay display, int[] major_minor)
          Initialize an EGL display connection.
 boolean eglMakeCurrent(EGLDisplay display, EGLSurface draw, EGLSurface read, EGLContext context)
          Attach an EGL rendering context to EGL surfaces.
 boolean eglQueryContext(EGLDisplay display, EGLContext context, int attribute, int[] value)
          Return EGL rendering context information.
 String eglQueryString(EGLDisplay display, int name)
          Return a string describing an EGL display connection.
 boolean eglQuerySurface(EGLDisplay display, EGLSurface surface, int attribute, int[] value)
          Return EGL surface information.
 boolean eglSwapBuffers(EGLDisplay display, EGLSurface surface)
          Post EGL surface color buffer to a native window.
 boolean eglTerminate(EGLDisplay display)
          Terminate an EGL display connection.
 boolean eglWaitGL()
          Complete GL execution prior to subsequent native rendering calls.
 boolean eglWaitNative(int engine, Object bindTarget)
          Complete native execution prior to subsequent GL rendering calls.
 



Field Detail

EGL_DEFAULT_DISPLAY

static final Object EGL_DEFAULT_DISPLAY
An object that is used as an argument to eglGetDisplay to indicate that the defalt display of the device is to be used.

Since:
BlackBerry API 5.0.0

EGL_NO_DISPLAY

static final EGLDisplay EGL_NO_DISPLAY
An EGLContext object used to indicate a null display.

Since:
BlackBerry API 5.0.0

EGL_NO_CONTEXT

static final EGLContext EGL_NO_CONTEXT
An EGLContext object used to indicate a null context.

Since:
BlackBerry API 5.0.0

EGL_NO_SURFACE

static final EGLSurface EGL_NO_SURFACE
An EGLContext object used to indicate a null surface.

Since:
BlackBerry API 5.0.0

EGL_FALSE

static final int EGL_FALSE
A value corresponding to the 'EGLBoolean' false value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_TRUE

static final int EGL_TRUE
A value corresponding to the 'EGLBoolean' true value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_SUCCESS

static final int EGL_SUCCESS
EGL error code indicating success.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_NOT_INITIALIZED

static final int EGL_NOT_INITIALIZED
EGL error code indicating 'not initialized'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_ACCESS

static final int EGL_BAD_ACCESS
EGL error code indicating 'bad access'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_ALLOC

static final int EGL_BAD_ALLOC
EGL error code indicating 'bad alloc'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_ATTRIBUTE

static final int EGL_BAD_ATTRIBUTE
EGL error code indicating 'bad attribute'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_CONFIG

static final int EGL_BAD_CONFIG
EGL error code indicating 'bad config'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_CONTEXT

static final int EGL_BAD_CONTEXT
EGL error code indicating 'bad context'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_CURRENT_SURFACE

static final int EGL_BAD_CURRENT_SURFACE
EGL error code indicating 'bad current surface'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_DISPLAY

static final int EGL_BAD_DISPLAY
EGL error code indicating 'bad display'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_MATCH

static final int EGL_BAD_MATCH
EGL error code indicating 'bad match'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_NATIVE_PIXMAP

static final int EGL_BAD_NATIVE_PIXMAP
EGL error code indicating 'bad native pixmap'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_NATIVE_WINDOW

static final int EGL_BAD_NATIVE_WINDOW
EGL error code indicating 'bad native window'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_PARAMETER

static final int EGL_BAD_PARAMETER
EGL error code indicating 'bad parameter'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BAD_SURFACE

static final int EGL_BAD_SURFACE
EGL error code indicating 'bad surface'.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BUFFER_SIZE

static final int EGL_BUFFER_SIZE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_ALPHA_SIZE

static final int EGL_ALPHA_SIZE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_BLUE_SIZE

static final int EGL_BLUE_SIZE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_GREEN_SIZE

static final int EGL_GREEN_SIZE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_RED_SIZE

static final int EGL_RED_SIZE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_DEPTH_SIZE

static final int EGL_DEPTH_SIZE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_STENCIL_SIZE

static final int EGL_STENCIL_SIZE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_CONFIG_CAVEAT

static final int EGL_CONFIG_CAVEAT
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_CONFIG_ID

static final int EGL_CONFIG_ID
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_LEVEL

static final int EGL_LEVEL
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_MAX_PBUFFER_HEIGHT

static final int EGL_MAX_PBUFFER_HEIGHT
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_MAX_PBUFFER_PIXELS

static final int EGL_MAX_PBUFFER_PIXELS
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_MAX_PBUFFER_WIDTH

static final int EGL_MAX_PBUFFER_WIDTH
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_NATIVE_RENDERABLE

static final int EGL_NATIVE_RENDERABLE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_NATIVE_VISUAL_ID

static final int EGL_NATIVE_VISUAL_ID
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_NATIVE_VISUAL_TYPE

static final int EGL_NATIVE_VISUAL_TYPE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_PRESERVED_RESOURCES

static final int EGL_PRESERVED_RESOURCES
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_SAMPLES

static final int EGL_SAMPLES
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_SAMPLE_BUFFERS

static final int EGL_SAMPLE_BUFFERS
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_SURFACE_TYPE

static final int EGL_SURFACE_TYPE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_TRANSPARENT_TYPE

static final int EGL_TRANSPARENT_TYPE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_TRANSPARENT_BLUE_VALUE

static final int EGL_TRANSPARENT_BLUE_VALUE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_TRANSPARENT_GREEN_VALUE

static final int EGL_TRANSPARENT_GREEN_VALUE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_TRANSPARENT_RED_VALUE

static final int EGL_TRANSPARENT_RED_VALUE
EGLConfig attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_NONE

static final int EGL_NONE
EGLConfig attribute name and value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_DONT_CARE

static final int EGL_DONT_CARE
EGLConfig attribute value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_PBUFFER_BIT

static final int EGL_PBUFFER_BIT
EGLConfig attribute value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_PIXMAP_BIT

static final int EGL_PIXMAP_BIT
EGLConfig attribute value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_WINDOW_BIT

static final int EGL_WINDOW_BIT
EGLConfig attribute value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_SLOW_CONFIG

static final int EGL_SLOW_CONFIG
EGLConfig attribute value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_NON_CONFORMANT_CONFIG

static final int EGL_NON_CONFORMANT_CONFIG
EGLConfig attribute value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_TRANSPARENT_RGB

static final int EGL_TRANSPARENT_RGB
EGLConfig attribute value.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_VENDOR

static final int EGL_VENDOR
Constant for use in eglQueryString.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_VERSION

static final int EGL_VERSION
Constant for use in eglQueryString.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_EXTENSIONS

static final int EGL_EXTENSIONS
Constant for use in eglQueryString.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_HEIGHT

static final int EGL_HEIGHT
EGLSurface attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_WIDTH

static final int EGL_WIDTH
EGLSurface attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_LARGEST_PBUFFER

static final int EGL_LARGEST_PBUFFER
EGLSurface attribute name.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_DRAW

static final int EGL_DRAW
Constant for use in the readdraw argument of eglGetCurrentSurface.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_READ

static final int EGL_READ
Constant for use in the readdraw argument of eglGetCurrentSurface.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

EGL_CORE_NATIVE_ENGINE

static final int EGL_CORE_NATIVE_ENGINE
Constant for use as the engine argument of eglWaitNative, indicating the core native engine of the platform.

On a JME CLDC/MIDP platform, this specifies the MIDP/LCDUI drawing engine.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Method Detail

eglGetError

int eglGetError()
Return error information.

eglGetError returns the error of the last called EGL function in the current thread. Initially, the error is set to EGL_SUCCESS.

The following errors are currently defined:

Errors

A call to eglGetError sets the error to EGL_SUCCESS.

Returns:
One of EGL_SUCCESS, EGL_NOT_INITIALIZED, EGL_BAD_ACCESS, EGL_BAD_ALLOC, EGL_BAD_ATTRIBUTE, EGL_BAD_CONTEXT, EGL_BAD_CONFIG, EGL_BAD_CURRENT_SURFACE, EGL_BAD_DISPLAY, EGL_BAD_MATCH, EGL_BAD_NATIVE_PIXMAP, EGL_BAD_NATIVE_WINDOW, EGL_BAD_PARAMETER, EGL_BAD_SURFACE, or other error code defined by an extension.
Since:
BlackBerry API 5.0.0

eglGetDisplay

EGLDisplay eglGetDisplay(Object native_display)
Return an EGL display connection.

eglGetDisplay obtains the EGL display connection for the native display native_display.

If display_id is EGL_DEFAULT_DISPLAY, a default display connection is returned.

If no display connection matching native_display is available, EGL_NO_DISPLAY is returned. No error is generated.

Use eglInitialize to initialize the display connection.

Parameters:
native_display - Specifies the display to connect to. EGL_DEFAULT_DISPLAY indicates the default display.
Returns:
An EGLDisplay object.
Throws:
IllegalArgumentException - if native_display is null or is not of a suitable type for the platform.
Since:
BlackBerry API 5.0.0

eglInitialize

boolean eglInitialize(EGLDisplay display,
                      int[] major_minor)
Initialize an EGL display connection.

eglInitialize initializes the EGL display connection obtained with eglGetDisplay. Initializing an already initialized EGL display connection has no effect besides returning the version numbers and returing true.

No value is returned in major_minor if it is specified as null.

Use eglTerminate to release resources associated with an EGL display connection.

Errors

false is returned if eglInitialize fails, true otherwise. major_minor is not modified when false is returned.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display cannot be initialized.

Parameters:
display - Specifies the EGL display connection to initialize.
major_minor - an int array of length at least 2, in which the major and minor version number of the EGL implementation will be returned as elements 0 and 1. May be null.
Returns:
true if the operation succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if major_minor is non-null but has length less than 2.
Since:
BlackBerry API 5.0.0

eglTerminate

boolean eglTerminate(EGLDisplay display)
Terminate an EGL display connection.

eglTerminate releases resources associated with an EGL display connection. Termination marks all EGL resources associated with the EGL display connection for deletion. If contexts or surfaces associated with display is current to any thread, they are not released until they are no longer current as a result of eglMakeCurrent.

Terminating an already terminated EGL display connection has no effect other than returning true. A terminated display may be re-initialized by calling eglInitialize again.

Errors

false is returned if eglTerminate fails, true otherwise.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

Parameters:
display - Specifies the EGL display connection to terminate.
Returns:
true if the operation succeeds.
Throws:
IllegalArgumentException - if display is null.
Since:
BlackBerry API 5.0.0

eglQueryString

String eglQueryString(EGLDisplay display,
                      int name)
Return a string describing an EGL display connection.

eglQueryString returns a String describing an EGL display connection. name can be one of the following:

The string data returned from the native EGL implementation is converted into UTF8 format and returned as a Java String.

Errors

null is returned on failure.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_PARAMETER is generated if name is not an accepted value.

Parameters:
display - Specifies the EGL display connection.
name - Specifies a symbolic constant, one of EGL_VENDOR, EGL_VERSION, or EGL_EXTENSIONS.
Returns:
A String containing the query result.
Throws:
IllegalArgumentException - if display is null.
Since:
BlackBerry API 5.0.0

eglGetConfigs

boolean eglGetConfigs(EGLDisplay display,
                      EGLConfig[] configs,
                      int config_size,
                      int[] num_config)
Return a list of all EGL frame buffer configurations for a display.

eglGetConfigs returns a list of all EGL frame buffer configurations that are available for the specified display. The items in the list can be used in any EGL function that requires an EGL frame buffer configuration. No more than config_size EGLConfigs will be returned even if more are available on the specified display.

configs does not return values, if it is specified as null. This is useful for querying just the number of all frame buffer configurations.

Use eglGetConfigAttrib to retrieve individual attribute values of a frame buffer configuration.

Errors

false is returned on failure, true otherwise. configs and num_config are not modified when false is returned.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_PARAMETER is generated if num_config is null.

Parameters:
display - An array of EGLConfig objects into which a list of configs will be stored, or null.
configs - Specifies the size of the list of configs.
config_size - An int array, in which the number of configs will be returned in element 0.
num_config -
Returns:
true if the operation succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if configs is non-null and configs.length is smaller than config_size.
IllegalArgumentException - if num_config is non-null but has length less than 1.
Since:
BlackBerry API 5.0.0

eglChooseConfig

boolean eglChooseConfig(EGLDisplay display,
                        int[] attrib_list,
                        EGLConfig[] configs,
                        int config_size,
                        int[] numConfig)
Return a list of EGL frame buffer configurations that match specified attributes.

eglChooseConfig returns a list of all EGL frame buffer configurations that match the attributes specified in attrib_list. The items in the list can be used in any EGL function that requires an EGL frame buffer configuration.

configs does not return values, if it is specified as null. This is useful for querying just the number of matching frame buffer configurations.

All attributes in attrib_list, including boolean attributes, are immediately followed by the corresponding desired value. The list is terminated with EGL_NONE. If an attribute is not specified in attrib_list then the default value (see below) is used (and the attribute is said to be specified implicitly). For example, if EGL_DEPTH_SIZE is not specified then it is assumed to be 0. For some attributes, the default is EGL_DONT_CARE meaning that any value is OK for this attribute, so the attribute will not be checked.

If attrib_list is null or empty (first attribute is EGL_NONE), then selection and sorting of EGLConfigs is done according to the default criteria described below.

Attributes are matched in an attribute-specific manner. Some of the attributes, such as EGL_LEVEL, must match the specified value exactly. Others, such as, EGL_RED_SIZE must meet or exceed the specified minimum values. If more than one EGL frame buffer configuration is found, then a list of configurations, sorted according to the "best" match criteria, is returned. The match criteria for each attribute and the exact sorting order is defined below.

The interpretations of the various EGL frame buffer configuration attributes are as follows:

When more than one EGL frame buffer configuration matches the specified attributes, a list of matching configurations is returned. The list is sorted according to the following precedence rules, which are applied in ascending order (i.e., configurations that are considered equal by a lower numbered rule are sorted by the higher numbered rule):

  1. By EGL_CONFIG_CAVEAT, where the precedence is EGL_NONE, EGL_SLOW_CONFIG, and EGL_NON_CONFORMANT_CONFIG.
  2. Larger total number of color components (EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, and EGL_ALPHA_SIZE) that have higher number of bits. If the requested number of bits in attrib_list is zero or EGL_DONT_CARE for a particular color component, then the number of bits for that component is not considered.
  3. Smaller EGL_BUFFER_SIZE.
  4. Smaller EGL_SAMPLE_BUFFERS.
  5. Smaller EGL_SAMPLES.
  6. Smaller EGL_DEPTH_SIZE.
  7. Smaller EGL_STENCIL_SIZE.
  8. By EGL_NATIVE_VISUAL_TYPE, where the precedence order is platform dependent.
  9. Smaller EGL_CONFIG_ID.

(1.1) EGLConfigs are not sorted with respect to the parameters EGL_BIND_TO_TEXTURE_RGB, EGL_BIND_TO_TEXTURE_RGBA, EGL_LEVEL, EGL_NATIVE_RENDERABLE, EGL_MAX_SWAP_INTERVAL, EGL_MIN_SWAP_INTERVAL, EGL_SURFACE_TYPE, EGL_TRANSPARENT_TYPE, EGL_TRANSPARENT_RED_VALUE, EGL_TRANSPARENT_GREEN_VALUE, and EGL_TRANSPARENT_BLUE_VALUE.

Examples

The following example specifies a frame buffer configuration in the normal frame buffer (not an overlay or underlay). The returned frame buffer configuration supports at least 4 bits each of red, green and blue and possible no alpha bits. The code shown in the example may or may not have a depth buffer, or a stencil buffer.

 int attrib_list[] =
 {
     EGL10.EGL_RED_SIZE, 4,
     EGL10.EGL_GREEN_SIZE, 4,
     EGL10.EGL_BLUE_SIZE, 4,
     EGL10.EGL_NONE
 };
 

Notes

eglGetConfigs and eglGetConfigAttrib can be used to implement selection algorithms other than the generic one implemented by eglChooseConfig. Call eglGetConfigs to retrieve all the frame buffer configurations, or alternatively, all the frame buffer configurations with a particular set of attributes. Next call eglGetConfigAttrib to retrieve additional attributes for the frame buffer configurations and then select between them.

EGL implementors are strongly discouraged, but not proscribed, from changing the selection algorithm used by eglChooseConfig. Therefore, selections may change from release to release of the client-side library.

Errors

false is returned on failure, true otherwise. configs and num_config are not modified when false is returned.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_BAD_ATTRIBUTE is generated if attribute_list contains an invalid frame buffer configuration attribute or an attribute value that is unrecognized or out of range.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_PARAMETER is generated if num_config is null.

Parameters:
display - Specifies the EGL display connection.
attrib_list - Specifies attributes required to match by configs.
configs - Returns an array of frame buffer configurations.
config_size - Specifies the size of the array of frame buffer configurations.
numConfig - An int array in which the number of frame buffer configurations will be returned in element 0.
Returns:
true if the operation succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if attrib_list is non-null but is not terminated with EGL_NONE.
IllegalArgumentException - if configs is non-null and configs.length is smaller than config_size.
IllegalArgumentException - if num_config is non-null but has length less than 1.
Since:
BlackBerry API 5.0.0

eglGetConfigAttrib

boolean eglGetConfigAttrib(EGLDisplay display,
                           EGLConfig config,
                           int attribute,
                           int[] value)
Return information about an EGL frame buffer configuration.

eglGetConfigAttrib returns in value[0] the value of attribute for config. attribute can be one of the following:

Errors

false is returned on failure, true otherwise. value is not modified when false is returned.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_CONFIG is generated if config is not an EGL frame buffer configuration.

EGL_BAD_ATTRIBUTE is generated if attribute is not a valid frame buffer configuration attribute.

Parameters:
display - Specifies the EGL display connection.
config - Specifies the EGL frame buffer configuration to be queried.
attribute - Specifies the EGL rendering context attribute to be returned.
value - An int array of length at least 1 in which the requested value will be returned as element 0.
Returns:
true if the query succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if config is null.
IllegalArgumentException - if value is null or has length less than 1.
Since:
BlackBerry API 5.0.0

eglCreateWindowSurface

EGLSurface eglCreateWindowSurface(EGLDisplay display,
                                  EGLConfig config,
                                  Object native_window,
                                  int[] attrib_list)
Create a new EGL window surface.

eglCreateWindowSurface creates an EGL window surface and returns its handle. If eglCreateWindowSurface fails to create a window surface, EGL_NO_SURFACE is returned.

Any EGL rendering context that was created with respect to config can be used to render into the surface. Use eglMakeCurrent to attach an EGL rendering context to the surface.

Use eglQuerySurface to retrieve the ID of config.

Use eglDestroySurface to destroy the surface.

Notes

On JME CLDC/MIDP platforms, native_window must be an instance of javax.microedition.lcdui.Graphics object created directly from an instance of GameCanvas or from the argument supplied to the Canvas.paint method.

Errors

EGL_NO_SURFACE is returned if creation of the context fails.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_CONFIG is generated if config is not an EGL frame buffer configuration.

EGL_BAD_NATIVE_WINDOW may be generated if native_window is not a valid native window.

EGL_BAD_ATTRIBUTE is generated if attrib_list contains an invalid window attribute or if an attribute value is not recognized or is out of range.

EGL_BAD_ALLOC is generated if there are not enough resources to allocate the new surface.

EGL_BAD_MATCH is generated if the attributes of native_window do not correspond to config or if config does not support rendering to windows (the EGL_SURFACE_TYPE attribute does not contain EGL_WINDOW_BIT).

Parameters:
display - Specifies the EGL display connection.
config - Specifies the EGL frame buffer configuration that defines the frame buffer resource available to the surface.
native_window - Specifies the native window.
attrib_list - Specifies window surface attributes. Must be null or empty (first attribute is EGL_NONE).
Returns:
an EGLSurface for rendering to the window.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if config is null.
IllegalArgumentException - if native_window is null or is not of a suitable type for the underlying platform (e.g., not a properly-created javax.microedition.lcdui.Graphics instance for CLDC/MIDP).
IllegalArgumentException - if attrib_list is non-null but is not terminated with EGL_NONE.
Since:
BlackBerry API 5.0.0

eglCreatePixmapSurface

EGLSurface eglCreatePixmapSurface(EGLDisplay display,
                                  EGLConfig config,
                                  Object native_pixmap,
                                  int[] attrib_list)
Create a new EGL pixmap surface.

eglCreatePixmapSurface creates an off-screen EGL pixmap surface and returns its handle. If eglCreatePixmapSurface fails to create a pixmap surface, EGL_NO_SURFACE is returned.

Any EGL rendering context that was created with respect to config can be used to render into the surface. Use eglMakeCurrent to attach an EGL rendering context to the surface.

Use eglQuerySurface to retrieve the ID of config.

Use eglDestroySurface to destroy the surface.

Notes

On JME CLDC/MIDP platforms, native_pixmap must be an instance of javax.microedition.lcdui.Graphics that was created directly from a mutable instance of javax.microedition.lcdui.Image.

Errors

EGL_NO_SURFACE is returned if creation of the context fails.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_CONFIG is generated if config is not an EGL config.

EGL_BAD_NATIVE_PIXMAP may be generated if native_pixmap is not a valid native pixmap.

EGL_BAD_ATTRIBUTE is generated if attrib_list contains an invalid pixmap attribute or if an attribute value is not recognized or out of range.

EGL_BAD_ALLOC is generated if there are not enough resources to allocate the new surface.

EGL_BAD_MATCH is generated if the attributes of native_pixmap do not correspond to config or if config does not support rendering to pixmaps (the EGL_SURFACE_TYPE attribute does not contain EGL_PIXMAP_BIT).

Parameters:
display - Specifies the EGL display connection.
config - Specifies the EGL frame buffer configuration that defines the frame buffer resource available to the surface.
native_pixmap - Specifies the native pixmap.
attrib_list - Specifies pixmap surface attributes. Must be null or empty (first attribute is EGL_NONE).
Returns:
An EGLSurface for offscreen rendering.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if config is null
IllegalArgumentException - if native_pixmap is null or is not of a suitable type for the underlying platform (e.g., not a mutable Image for CLDC/MIDP).
IllegalArgumentException - if attrib_list is non-null but is not terminated with EGL_NONE.
Since:
BlackBerry API 5.0.0

eglCreatePbufferSurface

EGLSurface eglCreatePbufferSurface(EGLDisplay display,
                                   EGLConfig config,
                                   int[] attrib_list)
Create a new EGL pixel buffer surface.

eglCreatePbufferSurface creates an off-screen pixel buffer surface and returns its handle. If eglCreatePbufferSurface fails to create a pixel buffer surface, EGL_NO_SURFACE is returned.

Any EGL rendering context that was created with respect to config can be used to render into the surface. Use eglMakeCurrent to attach an EGL rendering context to the surface.

Use eglQuerySurface to retrieve the dimensions of the allocated pixel buffer surface or the ID of config.

Use eglDestroySurface to destroy the surface.

The pixel buffer surface attributes are specified in attrib_list as a list of attribute value pairs, terminated with EGL_NONE. A null value for attrib_list is treated as an empty list. The accepted attributes for an EGL pixel buffer surface are:

1.1 Notes

If the value of config attribute EGL_TEXTURE_FORMAT is not EGL_NO_TEXTURE, then the pbuffer width and height specify the size of the level zero texture image

If EGL_LARGEST_PBUFFER is specified and if the pbuffer will be used as a texture (i.e. the value of EGL_TEXTURE_TARGET is EGL_TEXTURE_2D, and the value of EGL_TEXTURE FORMAT is EGL_TEXTURE_RGB or EGL_TEXTURE_RGBA), then the aspect ratio will be preserved and the new width and height will be valid sizes for the texture target (e.g. if the underlying OpenGL ES implementation does not support non-power-of-two textures, both the width and height will be a power of 2).

The contents of the depth and stencil buffers may not be preserved when rendering a texture to the pbuffer and switching which image of the texture is rendered to (e.g., switching from rendering one mipmap level to rendering another).

Errors

EGL_NO_SURFACE is returned if creation of the context fails.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_CONFIG is generated if config is not an EGL frame buffer configuration.

EGL_BAD_ATTRIBUTE is generated if attrib_list contains an invalid pixel buffer attribute or if an attribute value is not recognized or out of range.

EGL_BAD_ALLOC is generated if there are not enough resources to allocate the new surface.

EGL_BAD_MATCH is generated if config does not support rendering to pixel buffers (the EGL_SURFACE_TYPE attribute does not contain EGL_PBUFFER_BIT).

(1.1 only) EGL_BAD_VALUE is generated if the EGL_TEXTURE_FORMAT attribute is not EGL_NO_TEXTURE, and EGL_WIDTH and/or EGL_HEIGHT specify an invalid size (e.g., the texture size is not a power of 2, and the underlying OpenGL ES implementation does not support non-power-of-two textures).

(1.1 only) EGL_BAD_VALUE can also be generated if The EGL_TEXTURE_FORMAT attribute is EGL_NO_TEXTURE, and EGL_TEXTURE_TARGET is something other than EGL_NO_TEXTURE; or, EGL_TEXTURE_FORMAT is something other than EGL_NO_TEXTURE, and EGL_TEXTURE_TARGET is EGL_NO_TEXTURE.

Parameters:
display - Specifies the EGL display connection.
config - Specifies the EGL frame buffer configuration that defines the frame buffer resource available to the surface.
attrib_list - Specifies the pixel buffer surface attributes. May be null or empty (first attribute is EGL_NONE).
Returns:
An EGLSurface for offscreen rendering.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if config is null.
IllegalArgumentException - if attrib_list is non-null but is not terminated with EGL_NONE.
Since:
BlackBerry API 5.0.0

eglDestroySurface

boolean eglDestroySurface(EGLDisplay display,
                          EGLSurface surface)
Destroy an EGL surface.

If the EGL surface surface is not current to any thread, eglDestroySurface destroys it immediately. Otherwise, surface is destroyed when it becomes not current to any thread.

(1.1) In OpenGL ES 1.1, resources associated with a pbuffer surface are not released until all color buffers of that pbuffer bound to a texture object have been released.

Errors

false is returned if destruction of the surface fails, true otherwise.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_SURFACE is generated if surface is not an EGL surface.

Parameters:
display - Specifies the EGL display connection.
surface - Specifies the EGL surface to be destroyed.
Returns:
true if the operation succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if surface is null.
Since:
BlackBerry API 5.0.0

eglQuerySurface

boolean eglQuerySurface(EGLDisplay display,
                        EGLSurface surface,
                        int attribute,
                        int[] value)
Return EGL surface information.

eglQuerySurface returns in value[0] the value of attribute for surface. attribute can be one of the following:

1.1 Notes

Querying EGL_TEXTURE_FORMAT, EGL_TEXTURE_TARGET, EGL_MIPMAP_TEXTURE, or EGL_MIPMAP_LEVEL for a non-pbuffer surface is not an error, but value is not modified.

Errors

false is returned on failure, true otherwise. value is not modified when false is returned.

> EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_SURFACE is generated if surface is not an EGL surface.

EGL_BAD_ATTRIBUTE is generated if attribute is not a valid surface attribute.

Parameters:
display - Specifies the EGL display connection.
surface - Specifies the EGL surface to query.
attribute - Specifies the EGL surface attribute to be returned.
value - Returns the requested value.
Returns:
true if the query succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if surface is null.
IllegalArgumentException - if value is null or has length less than 1.
Since:
BlackBerry API 5.0.0

eglCreateContext

EGLContext eglCreateContext(EGLDisplay display,
                            EGLConfig config,
                            EGLContext share_context,
                            int[] attrib_list)
Create a new EGL rendering context.

> eglCreateContext creates an EGL rendering context and returns its handle. This context can be used to render into an EGL drawing surface. If eglCreateContext fails to create a rendering context, EGL_NO_CONTEXT is returned.

If share_context is not EGL_NO_CONTEXT, then all texture objects except object 0, are shared by context share_context and by the newly created context. An arbitrary number of rendering contexts can share a single texture object space. However, all rendering contexts that share a single texture object space must themselves exist in the same address space. Two rendering contexts share an address space if both are owned by a single process.

Currently no attributes are recognized, so attrib_list will normally be null or empty (first attribute is EGL_NONE). However, it is possible that some platforms will define attributes specific to those environments, as an EGL extension. A non-null attribute list that is terminated with EGL_NONE will be passed to the underlying EGL implementation.

Notes

A process is a single execution environment, implemented in a single address space, consisting of one or more threads.

A thread is one of a set of subprocesses that share a single address space, but maintain separate program counters, stack spaces, and other related global data. A thread is the only member of its subprocess group is equivalent to a process.

Errors

EGL_NO_CONTEXT is returned if creation of the context fails.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_CONFIG is generated if config is not an EGL frame buffer configuration.

EGL_BAD_CONTEXT is generated if share_context is not an EGL rendering context and is not EGL_NO_CONTEXT.

EGL_BAD_ATTRIBUTE is generated if attrib_list contains an invalid context attribute or if an attribute is not recognized or out of range.

EGL_BAD_ALLOC is generated if there are not enough resources to allocate the new context.

Parameters:
display - Specifies the EGL display connection.
config - Specifies the EGL frame buffer configuration that defines the frame buffer resource available to the rendering context.
share_context - Specifies the EGL rendering context with which to share texture objects. EGL_NO_CONTEXT indicates that no sharing is to take place.
attrib_list - Specifies attributes.
Returns:
A new EGLContext, or null if context creation was unsuccessful.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if config is null.
IllegalArgumentException - if share_context is null.
IllegalArgumentException - f attrib_list is non-null but is not terminated with EGL_NONE.
Since:
BlackBerry API 5.0.0

eglDestroyContext

boolean eglDestroyContext(EGLDisplay display,
                          EGLContext context)
Destroy an EGL rendering context.

If the EGL rendering context context is not current to any thread, eglDestroyContext destroys it immediately. Otherwise, context is destroyed when it becomes not current to any thread.

Errors

false is returned if destruction of the context fails, true otherwise.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_CONTEXT is generated if context is not an EGL rendering context.

Parameters:
display - Specifies the EGL display connection.
context - Specifies the EGL rendering context to be destroyed.
Returns:
true if the operation succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if context is null.
Since:
BlackBerry API 5.0.0

eglMakeCurrent

boolean eglMakeCurrent(EGLDisplay display,
                       EGLSurface draw,
                       EGLSurface read,
                       EGLContext context)
Attach an EGL rendering context to EGL surfaces.

eglMakeCurrent binds context to the current rendering thread and to the draw and read surfaces. draw is used for all GL operations except for any pixel data read back (glReadPixels, glCopyTexImage2D, and glCopyTexSubImage2D), which is taken from the frame buffer values of read.

If the calling thread has already a current rendering context, that context is flushed and marked as no longer current.

The first time that context is made current, the viewport and scissor dimensions are set to the size of the draw surface. The viewport and scissor are not modified when context is subsequently made current.

To release the current context without assigning a new one, call eglMakeCurrent with draw and read set to EGL_NO_SURFACE and context set to EGL_NO_CONTEXT.

Use eglGetCurrentContext, eglGetCurrentDisplay, and eglGetCurrentSurface to query the current rendering context and associated display connection and surfaces.

Errors

false is returned on failure, true otherwise. If false is returned, the previously current rendering context and surfaces (if any) remain unchanged.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_SURFACE is generated if draw or read is not an EGL surface.

EGL_BAD_CONTEXT is generated if context is not an EGL rendering context.

EGL_BAD_MATCH is generated if draw or read are not compatible with context, or if context is set to EGL_NO_CONTEXT and draw or read are not set to EGL_NO_SURFACE, or if draw or read are set to EGL_NO_SURFACE and context is not set to EGL_NO_CONTEXT.

EGL_BAD_ACCESS is generated if context is current to some other thread.

EGL_BAD_NATIVE_PIXMAP may be generated if a native pixmap underlying either draw or read is no longer valid.

EGL_BAD_NATIVE_WINDOW may be generated if a native window underlying either draw or read is no longer valid.

EGL_BAD_CURRENT_SURFACE is generated if the previous context has unflushed commands and the previous surface is no longer valid.

> EGL_BAD_ALLOC may be generated if allocation of ancillary buffers for draw or read were delayed until eglMakeCurrent is called, and there are not enough resources to allocate them.

EGL_CONTEXT_LOST (1.1 only)

A power management event has occurred. The application must destroy all contexts and reinitialise OpenGL ES state and objects to continue rendering.

Parameters:
display - Specifies the EGL display connection.
draw - Specifies the EGL draw surface.
read - Specifies the EGL read surface.
context - Specifies the EGL rendering context to be attached to the surfaces.
Returns:
true if the operation succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if draw is null.
IllegalArgumentException - if read is null.
IllegalArgumentException - if context is null.
Since:
BlackBerry API 5.0.0

eglGetCurrentContext

EGLContext eglGetCurrentContext()
Return the current EGL rendering context.

eglGetCurrentContext returns the current EGL rendering context, as specified by eglMakeCurrent. If no context is current, EGL_NO_CONTEXT is returned.

Returns:
The current EGLContext, or EGL_NO_CONTEXT.
Since:
BlackBerry API 5.0.0

eglGetCurrentSurface

EGLSurface eglGetCurrentSurface(int readdraw)
Return the read or draw surface for the current EGL rendering context.

eglGetCurrentSurface returns the read or draw surface attached to the current EGL rendering context, as specified by eglMakeCurrent. If no context is current, EGL_NO_SURFACE is returned.

Parameters:
readdraw - Specifies whether the EGL read or draw surface is to be returned, one of EGL_READ or EGL_DRAW.
Returns:
The current EGLSurface used for reading (if readdraw equals EGL_READ, or drawing (if readdraw equals EGL_DRAW).
Throws:
IllegalArgumentException - if readdraw is not one of the specified constants.
Since:
BlackBerry API 5.0.0

eglGetCurrentDisplay

EGLDisplay eglGetCurrentDisplay()
Return the display for the current EGL rendering context.

eglGetCurrentDisplay returns the current EGL display connection for the current EGL rendering context, as specified by eglMakeCurrent. If no context is current, EGL_NO_DISPLAY is returned.

Returns:
The current EGLDisplay
Since:
BlackBerry API 5.0.0

eglQueryContext

boolean eglQueryContext(EGLDisplay display,
                        EGLContext context,
                        int attribute,
                        int[] value)
Return EGL rendering context information.

eglQueryContext returns in value[0] the value of attribute for context. attribute can be one of the following:

Errors

false is returned on failure, true otherwise. value is not modified when false is returned.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_CONTEXT is generated if context is not an EGL rendering context.

EGL_BAD_ATTRIBUTE is generated if attribute is not a valid context attribute.

Parameters:
display - Specifies the EGL display connection.
context - Specifies the EGL rendering context to query.
attribute - Specifies the EGL rendering context attribute to be returned.
value - Returns the requested value.
Returns:
true if the query succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if context is null.
IllegalArgumentException - if value is null or has length less than 1.
Since:
BlackBerry API 5.0.0

eglWaitGL

boolean eglWaitGL()
Complete GL execution prior to subsequent native rendering calls.

GL rendering calls made prior to eglWaitGL are guaranteed to be executed before native rendering calls made after eglWaitGL. The same result can be achieved using glFinish.

eglWaitGL is ignored if there is no current EGL rendering context.

Errors

false is returned if eglWaitGL fails, true otherwise.

EGL_BAD_NATIVE_SURFACE is generated if the surface associated with the current context has a native window or pixmap, and that window or pixmap is no longer valid.

Returns:
true if the operation succeeds.
Since:
BlackBerry API 5.0.0

eglWaitNative

boolean eglWaitNative(int engine,
                      Object bindTarget)
Complete native execution prior to subsequent GL rendering calls.

Native rendering calls made prior to eglWaitNative are guaranteed to be executed before GL rendering calls made after eglWaitNative.

eglWaitNative is ignored if there is no current EGL rendering context.

Notes

In a MIDP environment, OpenGL ES drawing to an Image, Canvas, or GameCanvas must be preceded by a call to eglWaitNative(EGL10.EGL_CORE_NATIVE_ENGINE, graphics) and followed by a call to eglWaitGL(). The bindTarget parameter must be the instance of javax.microedition.lcdui.Graphics obtained from the GameCanvas.getGraphics method (if drawing to a GameCanvas), from the Image.getGraphics() method (if drawing to a mutable Image), or the instance obtained as the parameter to the Canvas.paint method (if drawing to a Canvas).

The results of passing improper values for engine and/or bindTarget are undefined.

The results of MIDP drawing calls are undefined from the time of the call to eglWaitNative until eglWaitGL returns.

Errors

EGL_BAD_PARAMETER is generated if engine is not a recognized marking engine.

EGL_BAD_NATIVE_SURFACE is generated if the surface associated with the current context has a native window or pixmap, and that window or pixmap is no longer valid.

Parameters:
engine - Specifies a particular marking engine to be waited on. Must be EGL_CORE_NATIVE_ENGINE.
bindTarget - the rendering target shared by the native engine and the EGL drawing surface. For MIDP, must be the instance of javax.microedition.lcdui.Graphics representing the targetted Canvas, Image, or GameCanvas.
Returns:
true if the operation succeeds.
Since:
BlackBerry API 5.0.0

eglSwapBuffers

boolean eglSwapBuffers(EGLDisplay display,
                       EGLSurface surface)
Post EGL surface color buffer to a native window.

If surface is a window surface, eglSwapBuffers posts its color buffer to the associated native window.

eglSwapBuffers performs an implicit glFlush before it returns. Subsequent GL commands may be issued immediately after calling eglSwapBuffers, but are not executed until the buffer exchange is completed.

If surface is a pixel buffer or a pixmap, eglSwapBuffers has no effect, and no error is generated.

Notes

The color buffer of surface is left undefined after calling eglSwapBuffers.

On the CLDC/MIDP plaform, calling eglSwapBuffers is equivalent to calling glFinish when drawing to a GameCanvas. The GameCanvas.flushGraphics method is used to copy the contents of the back buffer to the screen.

Errors

false is returned if swapping of the surface buffers fails, true otherwise.

> EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_SURFACE is generated if surface is not an EGL drawing surface.

EGL_CONTEXT_LOST (1.1 only)

A power management event has occurred. The application must destroy all contexts and reinitialise OpenGL ES state and objects to continue rendering.

Parameters:
display - Specifies the EGL display connection.
surface - Specifies the EGL drawing surface whose buffers are to be swapped.
Returns:
true if the operation succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if surface is null.
Since:
BlackBerry API 5.0.0

eglCopyBuffers

boolean eglCopyBuffers(EGLDisplay display,
                       EGLSurface surface,
                       Object native_pixmap)
Copy EGL surface color buffer to a native pixmap.

eglCopyBuffers copies the color buffer of surface to native_pixmap.

eglCopyBuffers performs an implicit glFlush before it returns. Subsequent GL commands may be issued immediately after calling eglCopyBuffers, but are not executed until copying of the color buffer is completed.

Notes

The color buffer of surface is left unchanged after calling eglCopyBuffers.

On JME CLDC/MIDP platforms, native_pixmap must be an instance of javax.microedition.lcdui.Image that is mutable, or an instance of javax.microedition.lcdui.Graphics that was obtained directly from such an image by means of a call to createGraphics() or getGraphics().

On JME Personal Basis Profile and Personal Profile platforms, native_pixmap must be an instance of java.awt.image.BufferedImage, or an instance of java.awt.Graphics that was obtained directly from such an image by means of a call to createGraphics() or getGraphics().

Errors

false is returned if swapping of the surface buffers fails, true otherwise.

EGL_BAD_DISPLAY is generated if display is not an EGL display connection.

EGL_NOT_INITIALIZED is generated if display has not been initialized.

EGL_BAD_SURFACE is generated if surface is not an EGL drawing surface.

EGL_BAD_NATIVE_PIXMAP is generated if the implementation does not support native pixmaps.

EGL_BAD_NATIVE_PIXMAP may be generated if native_pixmap is not a valid native pixmap.

EGL_BAD_MATCH is generated if the format of native_pixmap is not compatible with the color buffer of surface.

(1.1 only) EGL_CONTEXT_LOST is generated if a power management event has occurred. The application must destroy all contexts and reinitialize OpenGL ES state and objects to continue rendering.

Parameters:
display - Specifies the EGL display connection.
surface - Specifies the EGL surface whose color buffer is to be copied.
native_pixmap - Specifies the native pixmap as target of the copy.
Returns:
true if the copy succeeds.
Throws:
IllegalArgumentException - if display is null.
IllegalArgumentException - if surface is null.
IllegalArgumentException - if native_pixmap is null or is not of a suitable type for the underlying platform (e.g., a mutable Image for CLDC/MIDP).
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.