JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java (public API).
|
<style> table, th, td { border: 1px solid black; } </style>
This specification, an optional set of packages, describes the Java(TM) bindings to the native OpenGL(R) 3D graphics library profiles:
Inclusion Criteria explains the OpenGL profile separation.
See OpenGL Runtime Requirements.
An implementation is available as JOGL, a JogAmp module.
Other API bindings are available as JogAmp modules:
This binding has dependencies to the following:
A mobile JavaVM with language 1.6 support, ie:
with
The NativeWindow Protocol is included in JogAmp\'s implementation
OpenGL today is not just a single set of functions, it offers many profiles for different purposes, e.g. ES1, ES2 and ES3 for mobile, GL [ 3.1 .. 4.5 ] core for a programmable shader application, etc.
JOGL reflects these profiles with an OO abstraction model, specifying interfaces encapsulating common subsets.
The packages defined by this specification include:
The com.jogamp.opengl package
This package contains all Java bindings for all OpenGL profiles.
See Inclusion Criteria explaining the OpenGL profile seperation.
See OpenGL Runtime Requirements.
The main OpenGL profile interfaces are:
com.jogamp.opengl.GL2
interface
This interface contains all OpenGL [ 1.0 .. 3.0 ] methods, as well as most of it\'s extensions defined at the time of this specification.
OpenGL extensions whose functionality was incorporated into core OpenGL ≤ 3.0, are subsumed into the core namespace.
Future extensions will be added with a maintenance update
com.jogamp.opengl.GL3
interface
This interface contains all OpenGL [ 3.1 .. 3.3 ] core methods, as well as most of it\'s extensions defined at the time of this specification.
Note: OpenGL [ 3.1 .. 3.3 ] core profile does not includes fixed point functionality.
Future extensions will be added with a maintenance update
com.jogamp.opengl.GL3bc
interface
This interface contains all OpenGL [ 3.1 .. 3.3 ] compatibility methods, as well as most of it\'s extensions defined at the time of this specification.
Note: OpenGL [ 3.1 .. 3.3 ] compatibility profile does includes fixed point functionality.
Future extensions will be added with a maintenance update
com.jogamp.opengl.GL4
interface
This interface contains all OpenGL [ 4.0 .. 4.5 ] core methods, as well as most of it\'s extensions defined at the time of this specification.
Note: OpenGL [ 4.0 .. 4.5 ] core profile does not includes fixed point functionality.
Future extensions will be added with a maintenance update
com.jogamp.opengl.GL4bc
interface
This interface contains all OpenGL [ 4.0 .. 4.5 ] compatibility profile, as well as most of it\'s extensions defined at the time of this specification.
Note: OpenGL [ 4.0 .. 4.5 ] compatibility profile does includes fixed point functionality.
Future extensions will be added with a maintenance update
com.jogamp.opengl.GLES1
interface
This interface contains all OpenGL ES [ 1.0 .. 1.1 ] methods, as well as most of it\'s extensions defined at the time of this specification.
Future extensions will be added with a maintenance update
com.jogamp.opengl.GLES2
interface
This interface contains all OpenGL ES 2.0 methods, as well as most of it\'s extensions defined at the time of this specification.
Future extensions will be added with a maintenance update
com.jogamp.opengl.GLES3
interface
This interface contains all OpenGL ES [ 3.0 .. 3.2 ] methods, as well as most of it\'s extensions defined at the time of this specification.
Future extensions will be added with a maintenance update
Additionally the packages contains interfaces resembling intersecting common profiles. These common profiles may be utilize for cross profile code supposed to either run on desktop and mobile devices, or across GL profiles themselves:
com.jogamp.opengl.GLBase
interface
Common interface containing the profile type identification and conversion methods.
Used to query which specialized profile class an instance of this object actually is and offering a protocol to convert it to these types.
com.jogamp.opengl.GL
interface
Common interface containing the subset of all profiles, GL4bc, GL4, GL3bc, GL3, GL2, GLES1, GLES2 and GLES3.
This interface reflects common data types, texture and framebuffer functionality.
com.jogamp.opengl.GL2ES1
interface
Interface containing the common subset of GL2 and GLES1.
This interface reflects the fixed functionality of OpenGL, without the immediate mode API.
com.jogamp.opengl.GL2ES2
interface
Interface containing the common subset of GL2 and GLES2. Interface is almost GLES2 complete.
This interface reflects the programmable shader functionality of desktop and embedded OpenGL up until GLES2.
com.jogamp.opengl.GL3ES3
interface
Interface containing the common subset of core GL3 and GLES3. Interface is almost GLES3 complete, lacking GL_ARB_ES3_compatibility
extension.
This interface reflects the programmable shader functionality of desktop and embedded OpenGL up until GLES3.
com.jogamp.opengl.GL4ES3
interface
Interface containing the common subset of core GL4 and GLES3. Interface is GLES3 complete w/o vendor extensions.
This interface reflects the programmable shader functionality of desktop and embedded OpenGL up until GLES3.
com.jogamp.opengl.GL2GL3
interface
Interface containing the common subset of core GL3 (OpenGL 3.1+) and GL2 (OpenGL 3.0), also known as the OpenGL 3.0 forward compatible, non deprecated subset.
This interface reflects only the programmable shader functionality of desktop OpenGL
The com.jogamp.opengl.glu package
This package contains bindings for the OpenGL Graphics System Utility (GLU) Library version 1.3, inclusive, with the exception of the GLU NURBS routines which are not exposed.
The Java language bindings to the pre-existing C APIs in these packages have been created using 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. These rules should be followed as closely as possible for all future APIs that share the com.jogamp.opengl namespace.
Functions are named in the same way as in the C binding. That is, an OpenGL API function glClear is bound to Java method GL.glClear. Although it would be possible to drop the gl prefix (since it is redundant with the interface name GL), the resulting code was deemed to look too foreign to experienced OpenGL developers. For the same reason, we have also carried over all type suffixes like 3f and 3fv from methods such as glColor3f and glColor3fv, respectively.
Extension suffixes, such as EXT, ARB, and vendor-specific suffixes, are retained so as to match C conventions.
Constants are named in the same way as in the C binding. For instance, the OpenGL constant GL_RGB is bound to Java constant GL.GL_RGB.
All 8-bit integral types become byte, all 16-bit integral types become short, and all 32-bit integral types become int. All 32-bit floating-point types become float and all 64-bit floating-point types become double.
Integer return values that can only be GL_TRUE or GL_FALSE are mapped to boolean.
OpenGL 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 New I/O (NIO) Buffer object. The Buffer may be of any type allowable by the function (and compatible with the other arguments to the function) and may be direct or indirect. An example of an OpenGL API in this category is glTexImage2D.
Functions that take a typed pointer (e.g., GLfloat *) argument for immediate use are given two bindings. The first takes a Java primitive array with a type that matches the C pointer type (i.e., GLfloat* maps to float[]). The second takes a typed Buffer object (i.e., GLfloat* maps to FloatBuffer). An example of an OpenGL API in this category is glColor3fv.
Functions that take an untyped (void*) pointer argument for deferred use are given a single binding that takes a Buffer object. The Buffer may be of any type allowable by the function (and compatible with the other arguments to the function), but must be direct. That is, it may 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." An example of an OpenGL API in this category is 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 a Java primitive array whose memory location may change.
Functions that take a typed (e.g., GLfloat*) pointer argument for deferred use are given a single binding that takes a typed Buffer object (i.e., GLfloat* maps to FloatBuffer). The Buffer must be direct. That is, it may not have been created from a Java primitive array using the wrap method. An example of an OpenGL API in this category is glFeedbackBuffer.
Methods that read or write a specific number of values from an array or Buffer argument do not read or write any subsequent elements of the array or Buffer.
An outgoing C char* pointer, if representing a null-terminated, read-only C string, maps to a Java String. An outgoing C char** pointer, if similarly representing an array of read-only C strings, maps to a Java String[] (array of String objects). All other char* pointers, including those representing mutable C strings as used in some Get methods, are mapped to byte[] and ByteBuffer.
Each C method argument that is mapped to a primitive array in Java is actually mapped to two separate parameters: the appropriate primitive array type in Java and an integer offset parameter. The value of the integer offset is the index which the method will start reading from within the array. Earlier indices will be ignored. This mapping provides more congruity with existing Java APIs and allows reuse of a single array across multiple Java method calls by changing the index in much the same way that C pointers permit for C arrays.
Since there are two ways to expand a given C method pointer parameter, it would be possible for C methods with multiple pointer arguments to expand to many Java methods if one was to consider every possible combination of mappings (the C method would expand to the number of pointer parameters to the power of 2). In order to avoid an API explosion, we restrict a given Java method to like kind mappings only. In other words, a given C method with N typed pointer parameters for immediate use, where N >= 1, will map to exactly two Java methods: One with all primitive arrays and one with all Buffer types.
Also, methods that accept multiple Buffer arguments require all direct or all non-direct Buffers. Direct and non-direct buffers should never be mixed within an API call by an application.
When allocating a New I/O Buffer (in particular, a direct ByteBuffer) to be passed to the APIs in these packages, it is essential to set the byte ordering of the newly-allocated ByteBuffer to the native byte ordering of the platform: e.g. ByteBuffer.allocateDirect(...).order(ByteOrder.nativeOrder());
. The byte order of the ByteBuffer indicates how multi-byte values such as int and float are stored in the Buffer either using methods like putInt and putFloat or views such as IntBuffer or FloatBuffer. The Java bindings perform no conversion or byte swapping on the outgoing data to OpenGL, and the native OpenGL implementation expects data in the host CPU\'s byte order, so it is essential to always match the byte order of the underlying platform when filling Buffers with data.
When a Buffer object is passed to an OpenGL 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, 4 for a IntBuffer or FloatBuffer, and 8 for DoubleBuffer). The array offset given by Buffer<type>.arrayOffset() is also added in the offset for wrapped arrays.
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.
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 language bindings, as described below.
In the interest of efficiency, the Java API does not generally throw exceptions. However, running an application with the DebugGL composable pipeline, which is part of the API, will force an exception to be thrown at the point of failure.
Many errors are defined by OpenGL merely to set the error code, rather than throwing an exception. For example, passing a bad enumerated parameter value may result in the error flag being set to GL.GL_INVALID_VALUE. 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 impact performance by inhibiting the ability of the hardware to pipeline work.
Exception behavior is defined in cases that could otherwise lead to illegal memory accesses in the underlying OpenGL engine. Implementations should take necessary steps to prevent the GL from accessing or overwriting memory except for properly allocated Buffers and array method arguments.
An implementation should take care to validate arguments correctly before invoking native methods that could potentially access memory illegally. In particular, methods that validate the contents of an array (such as a list of GL attributes) or a Buffer should take precautions against exploits in which a separate thread attempts to alter the contents of the argument during the time interval following validation but preceding passage of the argument to the underlying native engine.
Sharing of server-side OpenGL objects such as buffer objects, e.g. VBOs, and textures among OpenGL contexts is supported in this specification.
See GLSharedContextSetter
interface for details.
OpenGL functions and OpenGL extensions have been included in the Java bindings according the following rules:
com.jogamp.opengl.GL3
interface:
GL/glcorearb.h
.GL_ARB_compatibility
, is chosen because:com.jogamp.opengl.GL2
interface
Bindings for all core GLU APIs have been included with the exception of the GLU NURBS APIs. These APIs may be included in a future maintenance release of the Java bindings.
While the Java APIs for OpenGL extensions are unconditionally exposed, the underlying functions may not be present. A program can query whether a potentially unavailable function is actually available at runtime by using the method GL.isFunctionAvailable.
Bindings for OpenGL extensions not covered in this specification may be supplied by individual vendors or groups. Such bindings may be considered for inclusion in a future version of this specification. In order to avoid fragmentation, vendors creating extension bindings should expose new extensions using the method GL.getExtension. This method is intended to provide a mechanism for vendors who wish to provide access to new OpenGL extensions without changing the public API of the core package.
Names for added extension methods and extension-defined constants and Java bindings for C parameters should follow the guidelines set forth in this specification.
Platform-specific extensions such as those that begin with WGL, GLX, CGL, etc. are not included in the API. Each implementation can choose to export all, some, or none of these APIs via the GL.getPlatformGLExtensions API which returns an Object whose underlying data type is specific to a given implementation.
Therefore, any usage of these APIs is both platform and implementation specific.
An OpenGL ≥ 4.0 version is required to instantiate a GL4
context.
An OpenGL ≥ 3.1 version is required to instantiate a GL3
context.
An OpenGL ≥ 1.5 version is required to instantiate a GL2
context.
Even though OpenGL extensions whose functionality was included into core OpenGL by version 3.0, inclusive, are not included in the bindings, it should be noted that OpenGL version 3.0 is not an absolute requirement on the runtime system. This is because a user could query whether any particular function is available before calling certain core APIs that might not be present. Also, if the core function name is not available in the native OpenGL implementation, the extension named equivalent is used instead, e.g. GL_ARB_framebuffer_object. However, in general, it is reasonable to expect at least OpenGL 1.5 to be installed on the runtime system and an implementor of the API is free to require the presence of at least OpenGL 1.5 on the target system.
The JOGL reference implementation require at least OpenGL version 1.1, due to it's dynamical function binding starting with OpenGL 1.2.
In future revisions of the API, this minimum standard may be raised.
An OpenGL ES ≥ 3.0 version is required to instantiate an GLES3
context.
An OpenGL ES ≥ 2.0 version is required to instantiate an GLES2
context.
An OpenGL ES [ 1.0 .. 1.1 ] version is required to instantiate an GLES1
context.
Any Java Bindings for OpenGL implementation should include version information in its jar manifest file. This information can then easily be accessed at runtime via the java.lang.Package API. At least the following information is included in the Reference Implementation jar file manifest: Specification Title, Specification Vendor, Specification Version, Implementation Vendor, and Implementation Version.
JOGL provides com.jogamp.opengl.JoglVersion
implementing com.jogamp.common.util.JogampVersion
, which provides users access to the specification and implementation version, the build date and source code repository branch name and it\'s latest commit identifier.
New core APIs found in future versions of OpenGL, as well as new OpenGL extensions, are expected to be added to the bindings and included into the com.jogamp.opengl namespace via future maintenance updates to the API.
The following is an excerpt of our README.
Bottom line, too much work has been performed to be listed here.
However, let's have a few sentimental points listed and we may add a few more as we go.
OpenGL™ for Java™ (GL4Java) was developed from March 1997 until March 2003.
Its concepts were reused in the subsequently launched JOGL project
initially lead by Sun Microsystems and later by the JogAmp community,
rendering GL4Java effectively JOGL's predecessor. A few of the concepts reused were:
AL_SOFT_events
support in JOALSantina, Rami. Resolution Independent NURBS Curve Rendering using Programmable Graphics Pipeline. GraphiCon'2011. Paper, Slides, Initial Blog, Blog Series
The JogAmp Community is grateful for all the contributions of all of the individuals who have advanced the project. For sure we are not able to list all of them here. Please contact us if you like to be added to this list.
This list can hardly cover all contributors and their contributions.
Since roughly 2010, JOGL development has been continued by individuals of the JogAmp community, see git log for details.
Sven Gothel created *OpenGL™ for Java™ (GL4Java)* in March 1997 and maintained it up until March 2003.
Kenneth Bradley Russell and Christopher John Kline developed JOGL, acquired by Sun Microsystems and released the first public version in 2003.
Gerard Ziemski contributed the original port of JOGL to Mac OS X.
Rob Grzywinski and Artur Biesiadowski contributed the Ant build support. Alex Radeski contributed the cpptasks support in the build process.
Pepijn Van Eeckhoudt and Nathan Parker Burg contributed the Java port of the GLU tessellator. Pepijn also contributed the initial version of the FPSAnimator utility class.
James Walsh (GKW) contributed the substantial port of the GLU mipmap generation code to Java, as well as robustness fixes in the Windows implementation and other areas.
The JSR-231 expert group as a whole provided valuable discussions and guidance in the design of the current APIs. In particular, Kevin Rushforth, Daniel Rice and Travis Bryson were instrumental in the design of the current APIs.
Travis Bryson did extensive work on the GlueGen tool to make it conform to the desired API design. He also shepherded JSR-231 through the standardization process, doing extensive cross-validation of the APIs and implementation along the way, and authored JOGL's nightly build system.
Lilian Chamontin contributed the JOGLAppletLauncher, opening new ways of deploying 3D over the web.
Christopher Campbell collaborated closely with the JOGL development team to enable interoperability between Sun's OpenGL pipeline for Java2D and JOGL in Java SE 6, and also co-authored the TextureIO subsystem.
Sven Gothel refactored the windowing subsystem layer to be generic, introduced the support for multiple GL profiles, realized NEWT etc. He teamed up with Rami Santina, realizing the new graph package exposing generic curve, text and UI support.
Rami Santina researched and implemented the math behind the new graph package RSantina, etc.
The following individuals made significant contributions to various areas of the project (Alphabetical):
The JogAmp Community is grateful for the support of the javagaming.org community and it's own JogAmp forum, from where dozens, if not hundreds, of individuals have contributed discussions, bug reports, bug fixes, and other forms of support.