Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2007 Sun Microsystems, Inc. All rights reserved.

back to

JSR 239 Final Release

This document contains the JavaTM Binding for the OpenGL® ES API, Specification version 1.0.


java.lang Provides classes that are fundamental to the design of the Java programming language.
java.nio Defines buffers, which are containers for data, and provides an overview of the other NIO packages.
javax.microedition.khronos.egl A package containing the Khronos EGL interfaces.
javax.microedition.khronos.opengles A package containing the Khronos OpenGL(R) ES interfaces.


This document contains the JavaTM Binding for the OpenGL® ES API, Specification version 1.0. The specification contains support for the OpenGL ES API for 2D and 3D graphics, and the EGL API for window system binding. The specification was designed within the Java Community Process ("JCP") as Java Specification Request ("JSR") 239. The specification is subject to the terms of JCP agreements.

This distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

OpenGL is a registered trademark of Silicon Graphics, Inc..


JSR 239 defines an optional package that may be run on a number of Java Micro Edition (Java ME) platforms including CLDC 1.1/MIDP 2.0, CDC 1.0/Personal Basis Profile, and CDC 1.0/Personal Profile, as well as backwards-compatible versions of those platforms. The current release supports the CLDC 1.1/MIDP 2.0 platform only. Support for CDC platforms will be addressed in a maintenance release.

The OpenGL ES and EGL APIs are defined by the Khronos Group ( OpenGL ES defines two profiles: the Common profile and the Common-Lite profile. The Common-Lite profile is a 32-bit fixed-point profile, while the Common profile supports floating point. The Common profile is a superset of the Common-Lite profile. This specification provides bindings to the Common profile (including all fixed-point functions). No separate specification addresses only Common-Lite.

JSR 239 requires an underlying native engine that has been certified by Khronos to be conformant with the OpenGL ES and EGL APIs. This engine must support version 1.0 of the OpenGL ES and EGL and all core extensions associated with those APIs. It may optionally support version 1.1 of the OpenGL ES and EGL APIs. Bindings are also provided for all currently defined optional profile extensions, including the extensions in the OpenGL ES 1.1 Extension Pack. Extension methods that are not supported by the runtime OpenGL ES engine may throw an java.lang.UnsupportedOperationException.


The specification lead for JSR 239 is Daniel Rice of Sun Microsystems, Inc. The JSR 239 expert group consists of the following companies and individuals:

Technical Details

Package Structure

The area contained under the javax.microedition.khronos heading is intended to hold future Java ME bindings for APIs developed by the Khronos group. The following packages are defined by this specification:

API Binding Conventions

The Java programming language bindings to the pre-existing C APIs in these packages follow a consistent set of rules. Vendor-defined extensions should make use of the same rules in order to provide a consistent developer experience.

The rules for creating the Java language binding are described in the following sections. Follow these rules as closely as possible for all future APIs that share the javax.microedition.khronos namespace.

Function Naming

Functions are named in the same way as in the C binding. That is, an OpenGL ES API function Color that gives rise to C functions glColor4f and glColor4x is bound to Java programming language methods GL10.glColor4f and GL10.glColor4x. Although it might be possible to drop the gl prefix (because it is redundant with the interface name GL10), and to use method overriding to eliminate the type suffixes 4f and 4x, the resulting code would look foreign to experienced OpenGL developers.

The need to distinguish between integer and fixed-point parameter (i versus x suffixes), which cannot be performed on the basis of compile-time type information alone, also creates a requirement for the use of suffixes.

Extension suffixes, such as OES, are retained to match C conventions.

Mapping of Primitive Types

All 8-bit integral types become byte, all 16-bit integral types become short, and all 32-bit integral types (including GLfixed) become int. All 32-bit floating-point types become float.

Integer return values that can only be GL_TRUE or GL_FALSE are mapped to boolean.

C strings ((char *)) values are mapped to standard Java UTF-8 Strings.

Mapping of Pointer Arguments

OpenGL ES functions that take pointer arguments fall into several categories:

Functions that take an untyped (void*) pointer argument for immediate use are given a single binding that takes a Buffer object. The Buffer can be of any type allowable by the function (and compatible with the other arguments to the function) and can be direct or indirect.

Functions that take a typed pointer (e.g., GLfloat *) argument for immediate use are given two bindings. The first takes a primitive array with a type that matches the C pointer type (that is, GLfloat* maps to float[]) and an integer offset indicating the first array entry to be read or written. The second takes a typed Buffer object (that is, GLfloat* maps to FloatBuffer).

Functions that take an untyped (void*) pointer argument for deferred use are given a single binding that takes a Buffer object. The Buffer can be of any type allowable by the function (and compatible with the other arguments to the function), but must be direct. That is, it must not have been created from a Java primitive array using the wrap method.

The functions that fall into this category generally have names ending with the suffix "Pointer" (such as glVertexPointer). Because these functions do not consume the data located at the given pointer immediately, but only at some unspecified later time, it is not possible to use an array since the Java virtual machine may relocate the array within system memory.

Functions that take a typed (for example, GLfloat*) pointer argument for deferred use are given a single binding that takes a typed Buffer object (that is, GLfloat* maps to FloatBuffer). The Buffer must be direct. That is, it must not have been created from primitive array using the wrap method. At present, OpenGL ES does not contain functions that fall into this category.

Methods that access an array or Buffer argument ignore (neither read nor write) any elements of the array or Buffer outside the contiguous range [start, start + n - 1], where start is the starting offset given by the offset parameter (in the array case) or the position() method (in the Buffer case), and n is the number of elements to be read or written as defined by the method.

Auto-slicing of Buffers

When a Buffer object is passed to an OpenGL ES function binding, the actual pointer argument that is passed down to the OpenGL C implementation is equal to the starting pointer of the Buffer data, plus an offset given by the Buffer.position() function, multiplied by the data type size in bytes (1 for a ByteBuffer, 2 for a ShortBuffer, and 4 for a IntBuffer or FloatBuffer).

This feature is known as "auto-slicing," as it mimics the effect of calling slice() on the Buffer object without the overhead of explicit object creation.

It is important to remember to "rewind" a Buffer after placing data into it (by means of methods that advance the buffer position) and before passing the buffer into an OpenGL ES method that is to consume the new data.

Errors and Exceptions

For performance reasons, OpenGL functions do not return error values directly. Instead, applications must query for errors using functions such as glGetError. This behavior is largely preserved in the Java programming language bindings, as described next.

Certain forms of error checking are performed immediately and result in the throwing of exceptions. For example, passing null for an array argument, or passing an insufficiently large array for the values that are to be returned will generally result in an IllegalArgumentException. Performing this type of error checking insulates the Java virtual machine from corruption due to bad pointers being passed to the underlying engine.

Conversely, many errors are defined by OpenGL ES merely to set the error code. For example, passing a bad enumerated parameter value to many OpenGL ES functions will result in the error flag being set to GL10.GL_INVALID_ENUM. Attempting to check for such errors in the binding layer would require either replicating the error-checking logic of the underlying engine, or querying the error state after every function. This would greatly affect performance by inhibiting the hardware's ability to pipeline work. Accordingly, we do not check for such errors, leaving them to be handled by the underlying engine.


In the OpenGL ES threading model, calling eglMakeCurrent binds an EGL context to the currently running thread. The context is unbound by calling eglMakeCurrent with arguments of EGL_NO_SURFACE and EGL_NO_CONTEXT. Calls to OpenGL ES functions take place relative to the context bound to the calling thread.

JSR 239 provides an EGLContext class that represents a context. Calling getGL on an EGLContext returns a GL object that is used to call GL functions. This GL object must only be used from the thread that is bound to the EGLContext that instantiated the GL object. The results of calling a GL method from a different thread, or when the associated EGLContext is not bound to any thread, are undefined, but must not cause the Java virtual machine to crash.


Exception behavior is defined in cases that might otherwise lead to illegal memory accesses in the underlying OpenGL ES engine. Take necessary steps in implementations to prevent the GL from accessing or overwriting memory outside of properly allocated Buffers and array method arguments.

Take care to validate arguments correctly in implementations before invoking native methods that could potentially access memory illegally. In particular, take precautions against exploits in which a separate thread attempts to alter the contents of an argument during the time interval following validation but preceding passage of the argument to the underlying native engine in methods that validate the contents of an array (such as a list of EGL attributes) or a Buffer.

Creating Extensions

Bindings for EGL and OpenGL ES extentions may be supplied by individual vendors or groups. Such bindings may be considered for inclusion in a future version of the JSR. Adhere to the following common set of conventions to avoid fragmentation:

To call an extension function, applications cast the returned GL instance to the interface type of the extension, for example by calling ((MYCORP_dummy_extension)gl).glDummyExtensionFunc().

Extension constants are accessed statically using names such as MYCORP_dummy_extension.GL_DUMMY_EXTENSION_CONSTANT.

Related Links

Revision History

Early Draft Review, July 2005

Public Review, November 2005

Proposed Final Draft, February 2006

Version 1.0, June 2006

Version 1.0a, October 2006

Final Release, Oct 2006

This specification is protected under the JSPA version 2.6.
Copyright © 2006 Sun Microsystems, Inc. 4150 Network Circle, California, 95054, U.S.A.
All Rights Reserved. Use is subject to license terms.
Copyright © 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

For more information, please consult the JSR 239 specification.