This API provides access to the threading model for the implementation of
the classes in this package.
OpenGL is specified as a thread-safe API, but in practice there
are multithreading-related issues on most, if not all, of the
platforms which support it. For example, some OpenGL
implementations do not behave well when one context is made
current first on one thread, released, and then made current on a
second thread, although this is legal according to the OpenGL
specification. On other platforms there are other problems.
Due to these limitations, and due to the inherent multithreading
in the Java platform (in particular, in the Abstract Window
Toolkit), it is often necessary to limit the multithreading
occurring in the typical application using the OpenGL API.
In the current reference implementation, for instance, multithreading
has been limited by
forcing all OpenGL-related work for GLAutoDrawables on to a single
thread. In other words, if an application uses only the
GLAutoDrawable and GLEventListener callback mechanism, it is
guaranteed to have the most correct single-threaded behavior on
all platforms.
Applications using the GLContext makeCurrent/release API directly
will inherently break this single-threaded model, as these methods
require that the OpenGL context be made current on the current
thread immediately. For applications wishing to integrate better
with an implementation that uses the single-threaded model, this
class provides public access to the mechanism used by the implementation.
Users can execute Runnables on the
internal thread used for performing OpenGL work, and query whether
the current thread is already this thread. Using these mechanisms
the user can move work from the current thread on to the internal
OpenGL thread if desired.
This class also provides mechanisms for querying whether this
internal serialization of OpenGL work is in effect, and a
programmatic way of disabling it. In the current reference
implementation it is enabled by default, although it could be
disabled in the future if OpenGL drivers become more robust on
all platforms.
In addition to specifying programmatically whether the single
thread for OpenGL work is enabled, users may switch it on and off
using the system property
opengl.1thread
. Valid values
for this system property are:
-Dopengl.1thread=false Disable single-threading of OpenGL work
-Dopengl.1thread=true Enable single-threading of OpenGL work (default -- on a newly-created worker thread)
-Dopengl.1thread=auto Select default single-threading behavior (currently on)
-Dopengl.1thread=awt Enable single-threading of OpenGL work on AWT event dispatch thread (current default on all
platforms, and also the default behavior older releases)
-Dopengl.1thread=worker Enable single-threading of OpenGL work on newly-created worker thread (not suitable for Mac
OS X or X11 platforms, and risky on Windows in applet environments)