File: index.html

package info (click to toggle)
libjogl2-java 2.3.2%2Bdfsg-9
links: PTS, VCS
area: main
in suites: bullseye, buster
size: 43,876 kB
sloc: java: 218,529; ansic: 75,727; xml: 6,703; objc: 3,139; sh: 2,736; cpp: 139; awk: 46; makefile: 29
file content (1100 lines) | stat: -rw-r--r-- 43,099 bytes
parent folder | download | duplicates (4)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <link href="../../../style.css" rel="stylesheet" type="text/css"/>
        <title>JOGL Userguide</title>
    </head>
    <body>
        <div id="container">
            <div id="header">
                <div id="slogan">JOGL Userguide</div>
                <div id="logo"><a href="http://jogamp.org/">JOGL Userguide</a></div>
            </div>
            <div id="menu">
                <ul>
                    <li><a href="http://jogamp.org/">Home</a></li>
                    <li><a href="../../../gluegen/www/">Gluegen</a></li>
                    <li><a href="../../../joal/www/">JOAL</a></li>
                    <li><a href="../../../jocl/www/">JOCL</a></li>
                    <li><a href="../../../jogl/www/">JOGL</a></li>
                    <li><a href="../../../demos/www/">Demos</a></li>
                    <li><a href="../../../wiki/">Wiki</a></li>
                    <li><a href="../../../deployment/jogl-next/javadoc_public/">JavaDoc</a></li>
                </ul>
            </div>
            <div id="main">
                <div id="text" class="fill">
                    <b><font color="red">WARNING: This document is under review.</font></b>
                    <br/>
                    <br/>
<ul>

  <li> <a href="#overview">Overview</a> </li>
  <li> <a href="#access">Accessing JOGL</a>
  <ul>
    <li> <a href="#building">Building the source tree</a></li>
    <li> <a href="#localinstallation">Local installation</a>
      <ul>
        <li> <a href="#archivefiles">7z Archives</a></li>
        <li> <a href="#jarfilesandclasspath">JAR Files &amp; CLASSPATH</a>
        <ul>
            <li> <a href="#atomicjarfiles">Atomic JAR files</a></li>
        </ul></li>
        <li> <a href="#automatednativelibraryloading">Automated Native Library Loading</a></li>
        <li> <a href="#traditionallibraryloading">Traditional Native Library Loading</a></li>
        <li> <a href="#ideusers">Settings for IDE's users</a></li>
        <li> <a href="#badpractice">Bad practice</a></li>
        <li> <a href="#notefordebianusers">Note for Debian Linux users</a></li>
      </ul></li>
    <li> <a href="#onlinedeployment">Online Deployment</a>
    <ul>
      <li> <a href="#applets">Applets</a></li>
      <li> <a href="#jnlpwebstart">JNLP / Web Start</a></li>
    </ul></li>
  </ul></li>
  <li> <a href="#joglapi">Using the JOGL API</a>
  <ul>
    <li> <a href="#gldrawableandglcontext">GLDrawable and GLContext</a></li>
    <li> <a href="#glprofile">GLProfile</a></li>
    <li> <a href="#creatingaglautodrawable">Creating a GLAutoDrawable</a></li>
    <li> <a href="#writingagleventlistener">Writing a GLEventListener</a></li>
    <li> <a href="#checkingextensionsandfunctionsavailability">Checking extensions and functions availability</a></li>
    <li> <a href="#useofniobuffers">Use of NIO buffers</a></li>
    <li> <a href="#documentationofclang">Documentation of C language functions matching with Jogl methods</a></li>
    <li> <a href="#performance">Performance</a></li>
    <li> <a href="#composablepipeline">Using the Composable Pipeline</a></li>
    <li> <a href="#heavylightweightissues">Heavyweight and Lightweight Issues</a></li>
    <li> <a href="#swtawtissues">SWT/AWT issues</a></li>
    <li> <a href="#multithreadingissues">AWT Multithreading Issues</a></li>
    <li> <a href="#pbuffers">Pbuffers</a></li>
    <li> <a href="#glu">GLU</a></li>
    <li> <a href="#moreresources">More Resources</a></li>
  </ul></li>
  <li> <a href="#platformnotes">Platform notes</a>
  <ul>
    <li> <a href="#allplatforms">All Platforms</a></li>
    <li> <a href="#windows">Windows</a></li>
    <li> <a href="#x11unix">X11 Platforms (Linux, Solaris, ..)</a></li>
    <li> <a href="#macosx">Macintosh OS X</a></li>
  </ul></li>
  <li> <a href="#versionhistory">Version History</a></li>

</ul>

<h2> <a name="overview">Overview</a> </h2>

<p>
    The JOGL project hosts the development version of the Java&trade; Binding for the OpenGL&reg; API,
    and is designed to provide hardware-supported 3D graphics to applications written in Java.
</p>
<p>
    It provides full access to the APIs in the OpenGL 1.3 - 3.0, 3.1 - 3.3, &ge; 4.0, ES 1.x and ES 2.x specification
    as well as nearly all vendor extensions.
    <a href="../Overview-OpenGL-Evolution-And-JOGL.html">OpenGL Evolution &amp; JOGL</a>
    (<a href="../bouml/html-svg/fig128069.svg">UML</a>) gives you a brief overview of OpenGL, 
    its profiles and how we map them to JOGL.
</p>
<p>
    It integrates with the AWT, Swing and SWT widget sets, as well with custom windowing toolkits using the NativeWindow API.
    <a href="../NEWT-Overview.html">JOGL also provides its own native windowing toolkit, NEWT</a>.
</p>

<p>
AWT integration is available via AWT GLCanvas and NEWT's NewtCanvasAWT,
where Swing integration is available via GLJPanel.
</p>
<p>
SWT integration is available via SWT GLCanvas and by using the SWT/AWT brigde.
</p>
<p>
Other windowing systems or widgets sets can be implemented by using the NativeWindow API.
</p>

<p>

Jogl provides access to the latest OpenGL routines
(OpenGL 4.x with nearly all vendor extensions) as well as platform-independent
access to hardware-accelerated offscreen rendering ("pbuffers"). Jogl
also provides some of the most popular features introduced by other
Java bindings for OpenGL like GL4Java, LWJGL and Magician, including a
composable pipeline model which can provide faster debugging for
Java-based OpenGL applications than the analogous C program and a native windowing 
toolkit independent of AWT called NEWT.

</p>

Jogl is designed for the most recent versions of the Java platform
and for this reason supports only:
<ul>
   <li>Java 1.6 (Level 6.0)
     <ul>
        <li> J2SE &ge; 1.6 (OpenJDK, Oracle, ..)</li>
        <li> JavaSE &ge; 1.6 For Embedded (Oracle) </li>
     </ul></li>
   <li>Android SDK API Level 9 (Version 2.3 Gingerbread)</li>
</ul>

<p>
It also only supports truecolor (15 bits per pixel and higher) rendering; it does
not support color-indexed modes. It was designed with New I/O (NIO) in
mind and often uses NIO internally in the implementation. Nevertheless non 
NIO/direct buffers/arrays are supported as well, since they allow faster processing on 
CPU intensive tasks.  
The Jogl binding is itself written almost completely in the Java programming language.
Most of the native code is autogenerated during the
build process by a new tool called <a
href="../../../gluegen/www/">GlueGen</a>, the source code of
which is available from its own jogamp.org project.

</p>

<h2> <a name="access">Accessing JOGL</a> </h2>

<h3> <a name="building">Building the source tree</a> </h3>

<p>

Most developers using JOGL will download the most current 
<a href="../../../deployment/jogamp-current/archive/">release build</a>. 
Separate instructions are available on how to 
<a href="../HowToBuild.html">build the source tree</a>.

</p>

<h3> <a name="localinstallation">Local Installation</a> </h3>

See <a href="../deployment/JOGL-DEPLOYMENT.html">deployment</a> for deployment details.

<h4> <a name="archivefiles">7zip Archives</a> </h4>
<p>

A 7zip archive for all platforms and all JogAmp modules including JOGL
is available, named <code>jogamp-all-platforms.7z</code>, 
as available <a href="../../../deployment/jogamp-current/archive/jogamp-all-platforms.7z">here</a>.
It contains the Java classes to call OpenGL from Java, as
well as the associated JNI native libraries. JOGL depends on some
run-time support classes and native code provided by the GlueGen
project; these classes and native code are also provided in the 7zip
bundles.

</p>

<h4> <a name="jarfilesandclasspath">JAR Files &amp; CLASSPATH</a> </h4>

Modify your <code>CLASSPATH</code>
environment variable to include the full paths to 
<code>gluegen-rt.jar</code> and <code>jogl-all.jar</code>, for example
<pre>
".;C:\Some\Other\Package\foo.jar;C:\Users\myhome\jogamp-all-platforms\jar\gluegen-rt.jar;C:\Users\myhome\jogamp-all-platforms\jar\jogl-all.jar".
</pre>
(If you did not previously set the CLASSPATH environment variable, you
may want to make sure that ".", the current directory, is on your new
CLASSPATH.) The path separator is ":" under Solaris, Mac and Linux. 

<h5> <a name="atomicjarfiles">Atomic JAR files</a> </h5>

<p>

Note that the 7zip archive contain more jar files
than just the above mentioned. Additional atomic jars <code>jogamp-all-platforms/jar/atomic/</code>
illustrate how JOGL may be partitioned to achieve a smaller deployment
size, in particular on smaller devices. See <a href="../deployment/JOGL-DEPLOYMENT.html">deployment</a> for details.

</p>

<h4> <a name="automatednativelibraryloading">Automated Native Library Loading</a> </h4>

<p>

JOGL 2.0 has a brand new feature allowing to automatically extract the proper native 
libraries required to use JOGL 
<a href="../deployment/JOGL-DEPLOYMENT.html#NativeJARFiles">from JARs containing them</a> 
without relying on the Java 
library path or any platform-dependent environment variable allowing to set the location 
of native libraries. This allows desktop applications as well as traditional Applets 
<a href="../deployment/JOGL-DEPLOYMENT.html#NApplets">as NApplets</a> 
to utilize the native library JAR files the same way Webstart/JNLP does.

</p>

<p>
To allow the native JAR file library loading to work, ensure that all JogAmp JAR files
are left unmodified within their common directory.
</p>

<p>
In case the native library JAR files cannot be opened, it falls back to the traditional 
native library loading mechanism via the java library path.
</p>

<p>

This feature is enabled by default and - for whatever reason - it can be disabled by setting the 
property <code>jogamp.gluegen.UseTempJarCache</code>
to false (as a VM argument, <code>-Djogamp.gluegen.UseTempJarCache=false</code> in command line).

</p>

<h4> <a name="traditionallibraryloading">Traditional Native Library Loading</a> </h4>

<p>

If you don't use <a href="#automatednativelibraryloading">automatic native libraries loading</a>,
as enabled by default, you must set either the VM property <code>java.library.path</code> 
or the platform-dependent environment variable used for the location of native libraries,
<code>PATH</code> on Windows, <code>LD_LIBRARY_PATH</code> on Unix (Linux, Solaris, ..)
and <code>DYLD_LIBRARY_PATH</code> on Mac OS X.
The environment variable shall contain the full path to the "lib" directory; for example, on Windows, add
<code>"C:\Users\myhome\jogamp-all-platforms\lib\windows-amd64"</code> to your PATH using
the System control panel, Advanced tab, Environment Variables
button. At this point your Java installation should be able to see the Jogl class files.

</p>

<h4> <a name="ideusers">Settings for IDE's users</a> </h4>

<p>

Eclipse users must add the JARs containing Java libraries into the Java 
Build Path of their project. They must set the native library location 
of these JARs if they have disabled the automatic extraction of native 
libraries. Netbeans users must add the JARs containing Java libraries 
into their project. In the “project” tab, select the "Libraries" node, 
select the item "Add JAR/Folder" and select the required JARs. Users of 
other IDEs should consult the IDE's documentation to see how to add jar 
files and native libraries to their current project.

</p>

<h4> <a name="badpractice">Bad practice</a> </h4>

<p>

Dropping the JOGL jars and native libraries into the extension
directory of the JRE is <b>strongly discouraged</b>. Doing so will
cause conflicts with third-party applications launched via Java Web
Start, and causes confusion later when upgrading the distribution.

</p>
<p>

If you are on the Linux platform, please see the Linux-specific
platform notes, below, with information on incompatibility between the
JPackage Java RPMs and JOGL. 

</p>

<h4> <a name="notefordebianusers">Note for Debian Linux users</a> </h4>

<p>

DEB packages are available for this distribution on its official repositories.

</p>

<h3> <a name="onlinedeployment">Online Deployment</a> </h3>

The recommended distribution vehicle for <i>online</i> applications using JOGL is
either using Applets or Java Web Start. JOGL-based applications do not even need to be signed;
all that is necessary is to reference the online resources using the appropriate URLs.

<p>
Please read <a href="../deployment/JOGL-DEPLOYMENT.html">JOGL Deployment</a>.
</p>

<h4> <a name="applets">Applets</a> </h4>

<p>
You might want to have a look at our <a href="../../../deployment/jogamp-current/jogl-test-applets.html">Test page for JOGL Applet</a>
</p>

Here are documented Applet launch examples:
<ol>
  <li> <a href="../../../deployment/jogamp-current/jogl-applet-runner-newt-gears-normal-napplet.html">Pure Applet</a> (<b>recommended</b>)</li>
  <li> <a href="../../../deployment/jogamp-current/jogl-applet-runner-newt-gears-normal.html">JNLP Applet w/ AppletLauncher-fallback </a></li>
</ol>

<h4> <a name="jnlpwebstart">JNLP / Webstart</a> </h4>

<p>
Here is a documented <a href="../../../deployment/jogamp-current/jogl-applet-runner-newt-gears-normal.html">JNLP Applet w/ AppletLauncher-fallback </a>,
which also documents how to utilize JOGL via WebStart with slight modifications.
</p>

<h2> <a name="joglapi">Using the JOGL API</a> </h2>

<h3> <a name="gldrawableandglcontext">GLDrawable and GLContext</a> </h3>
<p>

The APIs specify interfaces two low-level OpenGL abstractions:
drawables and contexts. An OpenGL drawable is effectively a surface
upon which OpenGL rendering will be performed. In order to perform
rendering, an OpenGL rendering context is needed. Contexts and
drawables typically go hand-in-hand. More than one context may be
created for a particular drawable. In these abstractions, a
context is always associated with exactly one drawable.

</p>

<p>

Most end users will not need to use these abstractions directly.
However, when sharing textures, display lists and other OpenGL objects
between widgets, the concrete identifier for the "namespace" for these
objects is the GLContext.

</p>

<h3> GLProfile </h3>

<p>

GLProfile instances maps OpenGL profiles introduced in OpenGL 3, please read <a href="../Overview-OpenGL-Evolution-And-JOGL.html">this</a> for more details.

</p>

<h3> Creating a GLAutoDrawable </h3>

<p>

Jogl provides three basic widgets into which OpenGL rendering can be
performed. The GLCanvas is a heavyweight AWT widget which supports
hardware acceleration and which is intended to be the primary widget
used by applications. The GLJPanel is a fully Swing-compatible
lightweight widget which supports hardware acceleration but which is
not as fast as the GLCanvas because it typically reads back the frame
buffer in order to draw it using Java2D. The GLJPanel is intended to
provide 100% correct Swing integration in the circumstances where a
GLCanvas can not be used. See <a href =
"http://java.sun.com/products/jfc/tsc/articles/mixing/">this
article</a> on <a href = "http://java.sun.com/products/jfc/tsc/">The
Swing Connection</a> for more information about mixing lightweight and
heavyweight widgets. See also the section on "Heavyweight and
Lightweight Issues" below. Recent work in the Mustang release of the
JDK has sped up the GLJPanel significantly when the Java2D OpenGL
pipeline is enabled; see <a
href="http://www.javagaming.org/forums/index.php?topic=10813.0">this
forum discussion</a> for more details.
GLWindow is a NEWT widget which supports hardware acceleration and which 
is intended to be the primary widget used by AWT-less applications.

</p>

GLCanvas, GLWindow and GLJPanel implement a common interface called
GLAutoDrawable so applications can switch between them with minimal
code changes. The GLAutoDrawable interface provides

<ul>

  <li> access to the GL object for calling OpenGL routines</li>

  <li> a callback mechanism (GLEventListener) for performing OpenGL
  rendering</li>

  <li> a <code>display()</code> method for forcing OpenGL rendering to
  be performed synchronously</li>

  <li> AWT- and Swing-independent abstractions for getting and setting
  the size of the widget and adding and removing event listeners</li>

</ul>

<p>

When creating GLCanvas, GLWindow and GLJPanel instances, the user may request a
certain set of OpenGL parameters in the form of a GLCapabilities
object, customize the format selection algorithm by specifying a
GLCapabilitiesChooser, share textures and display lists with other
GLDrawables, and specify the display device on which the
GLAutoDrawable will be created (GLCanvas and GLWindow only).

</p>
<p>

A GLCapabilities object specifies the OpenGL parameters for a
newly-created widget, such as the color, alpha,, z-buffer and
accumulation buffer bit depths and whether the widget is
double-buffered. The default capabilities are loosely specified but
provide for truecolor RGB, a reasonably large depth buffer,
double-buffered, with no alpha, stencil, or accumulation buffers. 

</p>
<p>

An application can override the default pixel format selection
algorithm by providing a GLCapabilitiesChooser to the GLCanvas or
GLJPanel constructor. (Not all platforms support the
GLCapabilitiesChooser mechanism, however; it may be ignored, in
particular on Mac OS X where pixel format selection is very different
than on other platforms.) The chooseCapabilities method will be called
with all of the available pixel formats as an array of GLCapabilities
objects, as well as the index indicating the window system's
recommended choice; it should return an integer index into this
array. The DefaultGLCapabilitiesChooser uses the window system's
recommendation when it is available, and otherwise attempts to use a
platform-independent selection algorithm.

</p>
<p>

The GLJPanel can be made non-opaque according to Swing's rendering
model, so it can act as an overlay to other Swing or Java2D drawing.
In order to enable this, set up your GLCapabilities object with a
non-zero alpha depth (a common value is 8 bits) and call
setOpaque(false) on the GLJPanel once it has been created. Java2D
rendering underneath it will then show through areas where OpenGL has
produced an alpha value less than 1.0. See the JGears and JRefract
demos for examples of how to use this functionality.

</p>

<h3> Writing a GLEventListener </h3>

<p>

Applications implement the GLEventListener interface to perform OpenGL
drawing via callbacks. When the methods of the GLEventListener are
called, the underlying OpenGL context associated with the drawable is
already current. The listener fetches the GL object out of the
GLAutoDrawable and begins to perform rendering.

</p>
<p>

The <code>init()</code> method is called when a new OpenGL context is
created for the given GLAutoDrawable. Any display lists or textures
used during the application's normal rendering loop can be safely
initialized in <code>init()</code>. It is important to note that
because the underlying AWT window may be destroyed and recreated while
using the same GLCanvas and GLEventListener, the GLEventListener's
<code>init()</code> method may be called more than once during the
lifetime of the application. The init() method should therefore be
kept as short as possible and only contain the OpenGL initialization
required for the <code>display()</code> method to run properly. It is
the responsibility of the application to keep track of how its various
OpenGL contexts share display lists, textures and other OpenGL objects
so they can be either be reinitialized or so that reinitialization can
be skipped when the <code>init()</code> callback is called.

</p>
<p>

Note also that the GLEventListener should be added to the
GLAutoDrawable before the GLAutoDrawable is shown or rendered to for
the first time. If this is not done, it is possible that the init()
method will not be called on the GLEventListener. JOGL does not
maintain internal state to keep track of whether init() has been
called on a particular GLEventListener since the last time an OpenGL
context was created for that GLAutoDrawable.

</p>
<p>

The <code>display()</code> method is called to perform per-frame
rendering. The <code>reshape()</code> method is called when the
drawable has been resized; the default implementation automatically
resizes the OpenGL viewport so often it is not necessary to do any
work in this method.  The <code>displayChanged()</code> method is
designed to allow applications to support on-the-fly screen mode
switching, but support for this is not yet implemented so the body of
this method should remain empty.

</p>
<p>

It is strongly recommended that applications always refetch the GL
object out of the GLAutoDrawable upon each call to the
<code>init()</code>, <code>display()</code> and <code>reshape()</code>
methods and pass the GL object down on the stack to any drawing
routines, as opposed to storing the GL in a field and referencing it
from there. The reason is that multithreading issues inherent to the
AWT toolkit make it difficult to reason about which threads certain
operations are occurring on, and if the GL object is stored in a field
it is unfortunately too easy to accidentally make OpenGL calls from a
thread that does not have a current context. This will usually cause
the application to crash. For more information please see the section
on multithreading.

</p>

<h3> Checking extensions and functions availability </h3>

<p>

GLBase.isFunctionAvailable(String glFunctionName) and 
GLBase.isExtensionAvailable(String glExtensionName) allow to check whether 
OpenGL functions and extensions are available.

</p>

<h3> Use of NIO buffers </h3>

<p>

Use com.jogamp.common.nio.Buffers to create any NIO buffer intented to be 
used by JOGL in order to avoid native ordering and size problems. Jogl does 
not modify the position of a buffer passed to its methods but such a position 
affects its behaviour. Direct NIO buffers are faster and should be used when 
performances are important. Indirect NIO buffers can be used for non critical 
operations, for example to retrieve the value of an OpenGL constant. Keep in 
mind that direct NIO buffers are page-aligned and allocated in the native heap 
(whereas indirect NIO buffers are allocated in Java heap). Use the VM argument 
"-XX:MaxDirectMemorySize" to increase the maximum size of the direct memory if 
the creation of direct NIO buffers fails, use the VM argument "-Xmx" to increase 
the maximum size of Java heap if the creation of undirect NIO buffers fails.

</p>

<h3> Documentation of C language functions matching with Jogl methods </h3>

<p>

Jogl documentation often refers to C language functions. You can find the 
documentation of these functions in OpenGL references pages <a href="http://www.opengl.org/sdk/docs/">here</a>.

</p>

<h3> Performance </h3>

<p>

JOGL has a low memory footprint. It uses direct NIO buffers in order to avoid 
copying data both in Java heap and in the native heap when calling native functions. 
JOGL accesses OpenGL through JNI; as a JNI call only takes a few nanoseconds, it 
does not drive programs using JOGL noticeably slower than their C/C++ equivalents.

</p>

<h2> Using the Composable Pipeline </h2>

<p>

Jogl supports the "composable pipeline" paradigm introduced by the
Magician Java binding for OpenGL. The DebugGL pipeline calls
<code>glGetError</code> after each OpenGL call, reporting any errors
found. It can greatly speed up development time because of its
fine-grained error checking as opposed to the manual error checking
usually required in OpenGL programs written in C. The TraceGL prints
logging information upon each OpenGL call and is helpful when an
application crash makes it difficult to see where the error occurred.

</p>
<p>

To use these pipelines, call <code>GLAutoDrawable.setGL</code> at the
beginning of the <code>init</code> method in your GLEventListener. For
example,
</p>

<pre>
class MyListener implements GLEventListener {
  public void init(GLDrawable drawable) {
    drawable.setGL(new DebugGL(drawable.getGL()));
    // ...
  }

  // ...
}
</pre>

<p>

Note that the GLAutoDrawable.setGL() method simply calls setGL() on
the default OpenGL context created by the GLAutoDrawable, so
sophisticated applications creating their own OpenGL contexts can use
the composable pipeline with these contexts by setting the GL object
in the context object itself. The composable pipeline needs to be
re-installed every time GLContext.makeCurrent() returns
CONTEXT_CURRENT_NEW.

</p>

<p>
N.B: DebugGL and TraceGL have been splitted into several classes matching 
with all GL subclasses.
</p>

<pre>

if (drawable.getGL().isGL4bc()) {
    final GL4bc gl4bc = drawable.getGL().getGL4bc();
    drawable.setGL(new DebugGL4bc(gl4bc));
} 
else {
    if (drawable.getGL().isGL4()) {
        final GL4 gl4 = drawable.getGL().getGL4();
        drawable.setGL(new DebugGL4(gl4));
    }
    else {
          if (drawable.getGL().isGL3bc()) {
              final GL3bc gl3bc = drawable.getGL().getGL3bc();
              drawable.setGL(new DebugGL3bc(gl3bc));
          }
          else {
              if (drawable.getGL().isGL3()) {
                  final GL3 gl3 = drawable.getGL().getGL3();
                  drawable.setGL(new DebugGL3(gl3));
              }
              else {
                  if (drawable.getGL().isGL2()) {
                      final GL2 gl2 = drawable.getGL().getGL2();
                      drawable.setGL(new DebugGL2(gl2));
                  }
              }
          }
     }
}

</pre>

<h2> Heavyweight and Lightweight Issues </h2>

<p>

As mentioned above, JOGL supplies both a heavyweight (GLCanvas) and a
lightweight (GLJPanel) widget to be able to provide the fastest
possible performance for applications which need it as well as 100%
correct Swing integration, again for applications which need it. The
GLCanvas usually provides higher performance than the GLJPanel, though
in recent releases the GLJPanel's speed has been improved when the
Java2D/OpenGL pipeline is active as described in <a
href="http://www.javagaming.org/forums/index.php?topic=10813.0">this
forum discussion</a>. Nonetheless, the GLCanvas can be used in almost
every kind of application except those using JInternalFrames. Please
see the Swing Connection article mentioned above for details on mixing
heavyweight and lightweight widgets. A couple of common pitfalls are
described here.

</p>
<p>

When using JPopupMenus or Swing tool tips in conjunction with the
GLCanvas, it is necessary to disable the use of lightweight widgets
for the popups. See the methods
<code>ToolTipManager.setLightWeightPopupEnabled</code>,
<code>JPopupMenu.setLightWeightPopupEnabled</code>, and
<code>JPopupMenu.setDefaultLightWeightPopupEnabled</code>.

</p>
<p>

There are occasionally problems with certain LayoutManagers and
component configurations where if a GLCanvas is placed in the middle
of a set of lightweight widgets then it may only grow and never
shrink. These issues are documented somewhat in <a href =
"https://jogl.dev.java.net/issues/show_bug.cgi?id=135">JOGL Issue
135</a> and most recently in the thread <a
href="http://javagaming.org/forums/index.php?topic=8699.0">"Resize
behaviour"</a> in the JOGL forum. The root cause is behavior of the
Canvas, and in particular its ComponentPeer. The implementation of
getPreferredSize() calls getMinimumSize() and getMinimumSize() turns
around and calls Component.getSize(). This effectively means that the
Canvas will report its preferred size as being as large as the
component has ever been. For some layout managers this doesn't seem to
matter, but for others like the BoxLayout it does. See the test case
attached to Issue 135 for an example. Replacing the GLCanvas with an
ordinary Canvas yields the same behavior.

</p>
<p>

One suggestion was to override getPreferredSize() so that if a
preferred size has not been set by the user, to default to (0,
0). This works fine for some test cases but breaks all of the other
JOGL demos because they use a different LayoutManager. There appear to
be a lot of interactions between heavyweight vs. lightweight widgets
and layout managers. One experiment which was done was to override
setSize() in GLCanvas to update the preferred size.  This works down
to the size specified by the user; if the window is resized any
smeller the same problem appears. If reshape() (the base routine of
setSize(), setBounds(), etc.) is changed to do the same thing, the
demo breaks in the same way it originally did. Therefore this solution
is fragile because it isn't clear which of these methods are used
internally by the AWT and for what purposes.

</p>
<p>

There are two possible solutions, both application-specific. The best
and most portable appears to be to put the GLCanvas into a JPanel and
set the JPanel's preferred size to (0, 0). The JPanel will cause this
constraint to be enforced on its contained GLCanvas. The other
workaround is to call <code>setPreferredSize(new Dimension(0,
0))</code> on a newly-created GLCanvas; this method is new in 1.5.

</p>
<p>

Another issue that occasionally arises on Windows is flickering during
live resizing of a GLCanvas. This is caused by the AWT's repainting
the background of the Canvas and can not be overridden on a per-Canvas
basis, for example when subclassing Canvas into GLCanvas.  The
repainting of the background of Canvases on Windows can be disabled by
specifying the system property
<code>-Dsun.awt.noerasebackground=true</code>. Whether to specify this
flag depends on the application and should not be done universally,
but instead on a case-by-case basis. Some more detail is in the thread
<a href="http://javagaming.org/forums/index.php?topic=8770.0">"TIP:
JOGL + Swing flicker"</a> in the JOGL forum.

</p>

<h2> SWT/AWT issues </h2>

<p>

The AWT GLCanvas has to be created once the size of the frame that contains it 
is no more zero. It is highly advised to do it inside a component listener 
so that it is called when the frame is resized. This listener has to be 
immediately removed after the creation of the canvas.

Laying out the frame (by calling <code>doLayout()</code>) before starting the animator (or calling <code>display()</code>) is necessary because 
the width of the canvas cannot be equal to zero and the SWT/AWT helper returns 
AWT frames with a strange behavior (width and height equal to zero, lazy layout 
and validation).

</p>

<h2> AWT Multithreading Issues </h2>

Below statements incorrect!

<p>

Jogl was designed to interoperate with the AWT, an inherently
multithreaded GUI toolkit. OpenGL, in contrast, was originally
designed in single-threaded C programming environments. For this
reason Jogl provides a framework in which it is possible to write
correct multithreaded OpenGL applications using the GLEventListener
paradigm.

</p>
<p>

If an application written using Jogl interacts in any way with the
mouse or keyboard, the AWT is processing these events and the
multithreaded aspects of the program must be considered.

</p>
<p>

OpenGL applications usually behave in one of two ways: either they
repaint only on demand, for example when mouse input comes in, or they
repaint continually, regardless of whether user input is coming in. In
the repaint-on-demand model, the application can merely call
<code>GLAutoDrawable.display()</code> manually at the end of the mouse
or keyboard listener to cause repainting to be done. Alternatively if
the application knows the concrete type of the GLDrawable it can call
repaint() to have the painting scheduled for a later time.

</p>
<p>

In the continuous repaint model, the application typically has a main
loop which is calling <code>GLAutoDrawable.display()</code>
repeatedly, or is using the Animator class, which does this
internally. In both of these cases the OpenGL rendering will be done
on this thread rather than the internal AWT event queue thread which
dispatches mouse and keyboard events.

</p>
<p>

Both of these models (repaint-on-demand and repaint continually) still
require the user to think about which thread keyboard and mouse events
are coming in on, and which thread is performing the OpenGL rendering.
OpenGL rendering <b>may not</b> occur directly inside the mouse or
keyboard handlers, because the OpenGL context for the drawable is not
current at this point (hence the warning about storing a GL object in
a field, where it can be fetched and accidentally used by another
thread). However, a mouse or keyboard listener may invoke
<code>GLAutoDrawable.display()</code>.

</p>
<p>

It is generally recommended that applications perform as little work
as possible inside their mouse and keyboard handlers to keep the GUI
responsive. However, since OpenGL commands can not be run from
directly within the mouse or keyboard event listener, the best
practice is to store off state when the listener is entered and
retrieve this state during the next call to
<code>GLEventListener.display()</code>.

</p>
<p>

Furthermore, it is recommended that if there are long computational
sequences in the GLEventListener's <code>display</code> method which
reference variables which may be being simultaneously modified by the
AWT thread (mouse and keyboard listeners) that copies of these
variables be made upon entry to <code>display</code> and these copies
be referenced throughout display() and the methods it calls. This will
prevent the values from changing while the OpenGL rendering is being
performed. Errors of this kind show up in many ways, including certain
kinds of flickering of the rendered image as certain pieces of objects
are rendered in one place and other pieces are rendered elsewhere in
the scene. Restructuring the display() method as described has solved
all instances of this kind of error that have been seen with Jogl to
date.

</p>
<p>

Prior to Jogl 1.1 b10, the Jogl library attempted to give applications
strict control over which thread or threads performed OpenGL
rendering. The <code>setRenderingThread()</code>,
<code>setNoAutoRedrawMode()</code> and <code>display()</code> APIs
were originally designed to allow the application to create its own
animation thread and avoid OpenGL context switching on platforms that
supported it. Unfortunately, serious stability issues caused by
multithreading bugs in either vendors' OpenGL drivers or in the Java
platform implementation have arisen on three of Jogl's major supported
platforms: Windows, Linux and Mac OS X. In order to address these
bugs, the threading model in Jogl 1.1 b10 and later has changed.

</p>
<p>

All GLEventListener callbacks and other internal OpenGL context
management are now performed on one thread. (In the current
implementation, this thread is the AWT event queue thread, which is a
thread internal to the implementation of the AWT and which is always
present when the AWT is being used. Future versions of Jogl may change
the thread on which the OpenGL work is performed.) When the
<code>GLAutoDrawable.display()</code> method is called from user code,
it now performs the work synchronously on the AWT event queue thread,
even if the calling thread is a different thread. The
<code>setRenderingThread()</code> optimization is now a no-op. The
<code>setNoAutoRedrawMode()</code> API still works as previously
advertised, though now that all work is done on the AWT event queue
thread it no longer needs to be used in most cases. (It was previously
useful for working around certain kinds of OpenGL driver bugs.)

</p>
<p>

Most applications will not see a change in behavior from this change
in the Jogl implementation. Applications which use thread-local
storage or complex multithreading and synchronization may see a change
in their control flow requiring code changes. While it is strongly
recommended to change such applications to work under the new
threading model, the old threading model can be used by specifying the
system property <code>-Djogl.1thread=auto</code> or
<code>-Djogl.1thread=false</code>. The "auto" setting is equivalent to
the behavior in 1.1 b09 and before, where on ATI cards the
single-threaded mode would be used. The "false" setting is equivalent
to disabling the single-threaded mode. "true" is now the default
setting.

</p>
<p>

In the APIs the single-threaded behavior continues to be the
default and the <code>setRenderingThread()</code> and
<code>setNoAutoRedrawMode()</code> APIs have been removed. The public
<code>Threading</code> class still provides some control over the
internal use of threads in the library as well as external access to
these mechanisms.

</p>

<h2> Pbuffers </h2>

<p>

Jogl exposes hardware-accelerated offscreen rendering (pbuffers) with
a minimal and platform-agnostic API. Several recent demos have been
successfully ported from C/C++ to Java using Jogl's pbuffer APIs.
However, the pbuffer support in Jogl remains one of the more
experimental aspects of the package and the APIs may need to change in
the future.

</p>
<p>

To create a pbuffer, call
<code>GLDrawableFactory.createGLPbuffer()</code>. It is wise to call
<code>GLDrawableFactory.canCreateGLPbuffer()</code> first to ensure
the graphics card has pbuffer support first. The pbuffer is created
immediately and is available for rendering as soon as
<code>createGLPbuffer</code> returns.

</p>
<p>

A pbuffer is used in conjunction with the GLEventListener mechanism by
calling its display() method. Rendering, as always, occurs while the
pbuffer's OpenGL context is current. There are render-to-texture
options that can be specified in the GLCapabilities for the pbuffer
which can make it easier to operate upon the resulting pixels. These
APIs are however highly experimental and not yet implemented on all
platforms.

</p>

<h2> GLU </h2>

<p>

Jogl contains support for the GLU (OpenGL Utility Library) version
1.3. Jogl originally supported GLU by wrapping the C version of the
APIs, but over time, and thanks to the contributions of several
individuals, it now uses a pure-Java version of SGI's GLU library. The
pure Java port is enabled by default, and addresses stability issues
on certain Linux distributions as well as the lack of native GLU 1.3
support on the Windows platform. In case of problems with the Java
port, the C version of the GLU library may be used by specifying the
system property <code>-Djogl.glu.nojava</code> on the command
line. All of the same functionality is exposed with both the Java and
C versions of the GLU library; currently NURBS support is the only
missing feature on both sides. If you run into problems with the Java
port of the GLU library please file a bug using the Issue Tracker on
the Jogl home page.

</p>
<p>

To use the GLU, simply instantiate a GLU object via <code>new
GLU()</code> at the beginning of your program. The methods on the GLU
object may be called at any point when an OpenGL context is current.
Because the GLU implementation is not thread-safe, one GLU object
should be created for each GLEventListener or other entity performing
OpenGL rendering in a given thread.

</p>
<p>

N.B: Some GLU features are only implemented in the subclass GLUgl2.

</p>

<h2> More Resources </h2>

<p>
Our <a href="../../../wiki/">Wiki pages</a>,
have a look at the 
<a href="../../../wiki/index.php/Jogl_Tutorial">Jogl Tutorial</a> resource listing.
</p>

<p>

The <a href="http://forum.jogamp.org/">JOGL forum</a> 
is the best place to ask questions about the library. Many users, as well
as the Jogl developers, read this forum frequently, and the archived
threads contain a lot of useful information (which still needs to be
distilled into documentation).

</p>
<p>

The <a href="../../../jogl-demos/www/">JOGL demos</a> provide
several examples of usage of the library.

</p>
<p>

Pepijn Van Eeckhoudt, Kevin Duling and Abdul Bezrati have done <a
href="http://pepijn.fab4.be/software/nehe-java-ports/">JOGL ports of
many of the the NeHe demos</a>. These are small examples of various
pieces of OpenGL functionality. See also the <a
href="http://nehe.gamedev.net/">NeHe web site</a>.

</p>

<p>

For release information about the JOGL library, please see the 
<a href="../../../wiki/index.php/Jogamp_Versioning_and_Releases">Jogamp Versioning and Release</a>.

</p>
<p>

Please post on the <a href="http://forum.jogamp.org/">JOGL forum</a> 
if you have a resource you'd like to add to this documentation
or like to edit the <a href="../../../wiki/index.php">Wiki Pages</a> yourself.

</p>

<h2> Platform Notes </h2>

<h3> All Platforms </h3>

<p>

The following issues, among others, are outstanding on all platforms:

</p>

<ul>

<li> A few remaining stability issues, mostly on older graphics cards.</li>

</ul>

<h3> Windows </h3>

<p>

For correct operation, it is necessary to specify the system property
<code>-Dsun.java2d.noddraw=true</code> when running JOGL applications
on Windows; this system property disables the use of DirectDraw by
Java2D. There are driver-level incompatibilities between DirectDraw
and OpenGL which manifest themselves as application crashes, poor
performance, bad flickering, and other artifacts. This poor behavior
may exhibit itself when OpenGL and DirectDraw are simply used in the
same application, not even just in the same window, so disabling
Java2D's DirectDraw pipeline and forcing it to use its GDI pipeline is
the only way to work around these issues. Java Web Start applications
may set this system property by adding the following line to the
<code>&lt;resources&gt;</code> section of the JNLP file: <code>
&lt;property name="sun.java2d.noddraw" value="true"/&gt; </code>

</p>

<h3> X11 Platforms (Linux, Solaris, ..) </h3>

<h3> Mac OS X </h3>

The following issues remain with the Mac OS X port:

<ul>

<li> Due to the mechanism by which the Cocoa graphics system selects
OpenGL pixel formats, the GLCapabilitiesChooser mechanism can not be
implemented on Mac OS X as on other platforms. Currently the
underlying Cocoa pixel format selection is used on an
NSOpenGLPixelFormat derived from the settings in the GLCapabilities,
and the GLCapabilitiesChooser is ignored. </li>

</ul>

<h2> Version History </h2>

<p>

JOGL's version history can be found online in the 
<a href="../../../wiki/index.php/Jogamp_Versioning_and_Releases">Jogamp Versioning and Release</a>.

</p>

<p>

The whole evolution of JOGL is described <a href="../Overview-OpenGL-Evolution-And-JOGL.html">here</a>.

</p>

                </div>
            </div>
            <div id="footer">
                <div id="footer_left">
                    <span>JogAmp.org</span>
                    by <a href="../../">http://jogamp.org</a>
                    is licensed under a <br/>
                    <a href="http://creativecommons.org/licenses/by/3.0/us/">Creative Commons Attribution 3.0 License</a>.
                </div>
            </div>
        </div>
    </body>
</html>