|
back to j2megame.org | ||||||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||||||
See:
Description
| Packages | |
| 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 (www.khronos.org). 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:
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:
javax.microedition.khronos.egl - contains bindings
for EGL versions 1.0 and 1.1
javax.microedition.khronos.opengles - contains
bindings for OpenGL ES versions 1.0 and 1.1, including core and
optional profile extensions defined as of the release of those APIs,
as well as the extensions defined in the OpenGL ES 1.1 Extension Pack.
java.nio - contains Buffer classes
modeled after the Java Platform, Standard Edition (Java SE)
java.nio.Buffer hierarchy, for use in storing data on the
native heap for use by APIs defined within this package.
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.
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.
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.
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.
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.
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.
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:
MYCORP_dummy_extension would
be defined in an interface of the same name. The interface should be
defined in a suitable namespace controlled by the vendor defining the
bindings. Interfaces containing multiple related extensions may be
named at the extender's discretion.
EGLContext.getGL(). Return a
String containing the names of the supported extensions
from the GL10.glGetString method when it is called with an
argument of GL10.GL_EXTENSIONS.
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.
JSR 239 Java Community Progess(SM) (JCP(SM)) web page
Khronos web site
Khronos OpenGL ES web site
OpenGL ES 1.0 specification
OpenGL ES 1.0 manual pages
OpenGL ES 1.1 specification
OpenGL ES 1.1 manual pages
OpenGL ES 1.1 Extension Pack specification
General web site for OpenGL technologies
Specification for desktop OpenGL 1.5
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 | ||||||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||||||