Initial attempt to revise documentation to be accurate with respect to

JSR-231 APIs


git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@469 232f8b59-042b-4e1e-8c03-345bb8c30851

1 files changed, 170 insertions, 133 deletions

diff --git a/doc/userguide/index.html b/doc/userguide/index.html
index 5b1868855..87d423bde 100644
--- a/doc/userguide/index.html
+++ b/doc/userguide/index.html
@@ -18,7 +18,8 @@
     <LI> Java Web Start integration
     <LI> Applet support
   </UL>
-  <LI> Creating a GLDrawable
+  <LI> GLDrawable and GLContext
+  <LI> Creating a GLAutoDrawable
   <LI> Writing a GLEventListener
   <LI> Using the Composable Pipeline
   <LI> Heavyweight and Lightweight Issues
@@ -56,28 +57,29 @@ Java-based OpenGL applications than the analogous C program.
 </P>
 <P>
 
-Jogl was designed for the most recent version of the Java platform and
-for this reason supports only J2SE 1.4 and later. It also only
+Jogl was designed for the most recent versions of the Java platform
+and for this reason supports only J2SE 1.4 and later. It also only
 supports truecolor (15 bits per pixel and higher) rendering; it does
-not support color-indexed modes. Certain areas of the public APIs are
-more restrictive than in other bindings; for example, the GLCanvas and
-GLJPanel classes are final, unlike in GL4Java, and the GLContext class
-is no longer exposed in the public API. These changes have been made
-to keep the public API simple and because most of the programming
-errors that have been seen with earlier Java/OpenGL interfaces, in
-particular GL4Java, have been related to subclassing the OpenGL widget
-classes and performing manual OpenGL context management. Several
-complex and leading-edge OpenGL demonstrations have been successfully
-ported from C/C++ to Jogl without needing direct access to any of
-these APIs. However, all of these classes and concepts are accessible
-at the Java programming language level in implementation packages, and
-in fact the Jogl binding is itself written almost completely in the
-Java programming language. There are roughly 150 lines of handwritten
-C code in the entire Jogl source base (100 of which work around bugs
-in older OpenGL drivers on Windows); the rest of the native code is
-autogenerated during the build process by a new tool called GlueGen,
-the source code of which is in the Jogl source tree. Documentation for
-GlueGen is forthcoming.
+not support color-indexed modes. It was designed with New I/O (NIO) in
+mind and uses NIO internally in the implementation. The Jogl binding
+is itself written almost completely in the Java programming language.
+There are roughly 150 lines of handwritten C code in the entire Jogl
+source base (100 of which work around bugs in older OpenGL drivers on
+Windows); the rest of the native code is autogenerated during the
+build process by a new tool called GlueGen, the source code of which
+is in the Jogl source tree. Documentation for GlueGen is forthcoming.
+
+</P>
+<P>
+
+The JOGL source tree in its current form is an experimental workspace
+for the <a href="http://jcp.org/en/jsr/detail?id=231">JSR-231</a> Java
+Bindings for OpenGL JSR. JOGL is not the official reference
+implementation, but an evolving workspace. Snapshots of the JOGL
+source tree are run through the JSR-231 Technology Compatibility Kit
+(TCK) to become the official reference implementation (RI). As of this
+writing the JSR has not been finalized, so the first official RI of
+the JSR has not yet been produced.
 
 </P>
 
@@ -192,7 +194,29 @@ the first signed build of the JOGLAppletInstaller has been shipped.
 
 </P>
 
-<H2> Creating a GLDrawable </H2>
+<H2> GLDrawable and GLContext </H2>
+
+<P>
+
+The JSR-231 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 the JSR-231 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>
+
+<H2> Creating a GLAutoDrawable </H2>
 
 <P>
 
@@ -201,56 +225,51 @@ 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 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 =
+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.
+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.
 
 </P>
 <P>
 
 Both the GLCanvas and GLJPanel implement a common interface called
-GLDrawable so applications can switch between them with minimal code
-changes. The GLDrawable interface provides
+GLAutoDrawable so applications can switch between them with minimal
+code changes. The GLAutoDrawable interface provides
 
 <UL>
 
-  <LI> access to the GL and GLU objects for calling OpenGL routines
+  <LI> access to the GL object for calling OpenGL routines
 
-  <LI> the mechanism for registering GLEventListeners for performing
-  OpenGL rendering
+  <LI> a callback mechanism (GLEventListener) for performing OpenGL
+  rendering
 
   <LI> a <CODE>display()</CODE> method for forcing OpenGL rendering to
-  be performed
-
-  <LI> exclusion methods (<CODE>setRenderingThread()</CODE>,
-  <CODE>setNoAutoRedrawMode()</CODE>) for controlling the
-  multithreading behavior of the widget
+  be performed synchronously
 
   <LI> AWT- and Swing-independent abstractions for getting and setting
   the size of the widget and adding and removing event listeners
 
-  <LI> a platform-independent mechanism for creating
-  hardware-accelerated offscreen surfaces (pbuffers) for performing
-  advanced rendering techniques
-
 </UL>
 
 </P>
 <P>
 
-GLCanvas and GLJPanel instances are created using the factory methods
-in GLDrawableFactory. These factory methods allow the user to request
-a certain set of OpenGL parameters in the form of a GLCapabilities
-object, to customize the format selection algorithm by specifying a
-GLCapabilitiesChooser, to share textures and display lists with other
-GLDrawables, and to specify the display device on which the GLDrawable
-will be created.
+When creating GLCanvas 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 only).
 
 </P>
 <P>
@@ -266,9 +285,12 @@ double-buffered, with no alpha, stencil, or accumulation buffers.
 <P>
 
 An application can override the default pixel format selection
-algorithm by providing a GLCapabilitiesChooser to the
-GLDrawableFactory. The chooseCapabilities method will be called with
-all of the available pixel formats as an array of GLCapabilities
+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
@@ -294,17 +316,17 @@ demos for examples of how to use this functionality.
 <P>
 
 Applications implement the GLEventListener interface to perform OpenGL
-drawing. 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 GLDrawable and
-begins to perform rendering.
+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 GLDrawable. Any display lists or textures used
-during the application's normal rendering loop can be safely
+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
@@ -332,8 +354,8 @@ this method should remain empty.
 </P>
 <P>
 
-It is strongly recommended that applications always refetch the GL and
-GLU objects out of the GLDrawable upon each call to the
+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
@@ -363,7 +385,7 @@ application crash makes it difficult to see where the error occurred.
 </P>
 <P>
 
-To use these pipelines, call <CODE>GLDrawable.setGL</CODE> at the
+To use these pipelines, call <CODE>GLAutoDrawable.setGL</CODE> at the
 beginning of the <CODE>init</CODE> method in your GLEventListener. For
 example,
 
@@ -379,6 +401,17 @@ class MyListener implements GLEventListener {
 </PRE>
 
 </P>
+<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>
 
 <H2> Heavyweight and Lightweight Issues </H2>
 
@@ -388,11 +421,15 @@ 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 provides much higher performance than the GLJPanel in nearly
-all situations and 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.
+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>
@@ -413,7 +450,7 @@ 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://192.18.37.44/forums/index.php?topic=8699.0">"Resize
+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
@@ -463,8 +500,8 @@ 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://192.18.37.44/forums/index.php?topic=8770.0">"TIP: JOGL
-+ Swing flicker"</a> in the JOGL forum.
+<a href="http://javagaming.org/forums/index.php?topic=8770.0">"TIP:
+JOGL + Swing flicker"</a> in the JOGL forum.
 
 </P>
 
@@ -493,20 +530,20 @@ 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>GLDrawable.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
+<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>GLDrawable.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.
+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>
@@ -519,7 +556,7 @@ 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>GLDrawable.display()</CODE>.
+<CODE>GLAutoDrawable.display()</CODE>.
 
 </P>
 <P>
@@ -573,11 +610,11 @@ 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>GLDrawable.display()</CODE> method is called from user code, it
-now performs the work synchronously on the AWT event queue thread,
+<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>setNoAutoRedraw()</CODE> API still works as previously
+<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.)
@@ -599,6 +636,16 @@ to disabling the single-threaded mode. "true" is now the default
 setting.
 
 </P>
+<P>
+
+In the JSR-231 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>
 
@@ -614,37 +661,23 @@ the future.
 </P>
 <P>
 
-To create a pbuffer, create a GLCanvas and (assuming it reports that
-it can create an offscreen drawable) make a pbuffer using the
-<CODE>createOffscreenDrawable</CODE> API. Because of the multithreaded
-nature of the AWT, the pbuffer is actually created lazily. However,
-even if multiple pbuffers are created, and the order in which they are
-rendered is significant, handling the lazy instantiation can be
-straightforward: the display(GLDrawable) method of one pbuffer's
-GLEventListener can directly call another pbuffer's display() method.
-See the source code for the Jogl demonstrations such as the
-ProceduralTexturePhysics demo and the HDR demo for examples of this
-usage.
-
-</P>
-<P>
-
-Additionally, pbuffers are only created when the parent GLCanvas's
-display(), init(), or reshape() methods are called; in other words, it
-may be necessary to manually "prime" the GLCanvas by calling display()
-on it until it creates all of its requested pbuffers. Again, please
-see the demonstrations for concrete examples of this. We hope that it
-may be possible to hide many of these details in the future.
+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 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.
+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>
 
@@ -668,12 +701,22 @@ 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>
 
 <H2> More Resources </H2>
 
 <P>
 
-The <A HREF="http://192.18.37.44/forums/index.php?board=25.0">JOGL
+The <A HREF="http://javagaming.org/forums/index.php?board=25.0">JOGL
 forum</A> on <A HREF="http://javagaming.org/">javagaming.org</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
@@ -708,14 +751,14 @@ site and scroll down.
 <P>
 
 Gregory Pierce's <A
-HREF="http://192.18.37.44/forums/index.php?topic=1474.0">introduction
+HREF="http://javagaming.org/forums/index.php?topic=1474.0">introduction
 to JOGL</a> is a useful tutorial on starting to use the JOGL library.
 
 </P>
 <P>
 
 For release information about the JOGL library, please see the <A
-HREF="http://192.18.37.44/forums/index.php?topic=1596.0">JOGL Release
+HREF="http://javagaming.org/forums/index.php?topic=1596.0">JOGL Release
 Information</A> thread on the JOGL forum on javagaming.org.
 
 </P>
@@ -740,6 +783,12 @@ The following issues, among others, are outstanding on all platforms:
 
 <LI> A few remaining stability issues, mostly on older graphics cards.
 
+<LI> JOGL now supports experimental integration and interoperability
+with the Java2D/OpenGL pipeline in Java SE 6 (Mustang), enabling a
+much faster GLJPanel as well as other features. Please see <a
+href="http://www.javagaming.org/forums/index.php?topic=10813.0">this
+forum discussion</a> for more details.
+
 </UL>
 
 <H3> Windows </H3>
@@ -763,14 +812,6 @@ may set this system property by adding the following line to the
 </P>
 <P>
 
-JOGL currently does not interoperate well with the OpenGL pipeline for
-Java2D available in JDK 5.0 and later. We will address this in a
-future JOGL release and plan to have better interoperability by the
-time JDK 6.0 is shipped.
-
-</P>
-<P>
-
 There is a serious memory leak in ATI's OpenGL drivers which is
 exhibited on Windows XP on Mobility Radeon 9700 hardware. It's
 possible it will be present on other hardware as well though it was
@@ -808,7 +849,6 @@ been filed about these problems and it is hoped they will be addressed
 in the near future.
 
 </P>
-
 <P>
 
 The Mac OS X port of Jogl, in particular the GL interface and its
@@ -818,14 +858,10 @@ following steps should be taken:
 
 <UL>
 
-<LI> Instantiate a
-<CODE>net.java.games.jogl.impl.macosx.MacOSXDummyGLContext</CODE> using the
-public constructor taking no arguments.
-
-<LI> Upon the first render of your application, or whenever the
-available OpenGL routines might have changed (because a window moved
-from one screen to another) call the publicly-accessible method 
-<CODE>MacOSXDummyGLContext.resetGLFunctionAvailability()</CODE>.
+<LI> Create an "external" OpenGL context using the
+<CODE>GLDrawableFactory.createExternalGLContext()</CODE> API. The
+context object must be created while a real underlying OpenGL context
+is current.
 
 <LI> Fetch the GL instance out of the context using getGL() as usual.
 Only use the GL instance when the OpenGL context from the NSOpenGLView
@@ -833,9 +869,10 @@ is current.
 
 </UL>
 
-<B>NOTE:</B> the Cocoa interoperability has not yet been retested
-since the GLCanvas was implemented. Please report any problems found
-with using Jogl with an NSOpenGLView.
+<B>NOTE:</B> the Cocoa interoperability has not been retested
+recently, though similar interoperability has been tested on other
+platforms. Please report any problems found with using Jogl with an
+NSOpenGLView.
 
 </P>
 <P>
@@ -860,10 +897,10 @@ and the GLCapabilitiesChooser is ignored.
 <P>
 
 JOGL's version history can be found online in the <a
-href="http://192.18.37.44/forums/index.php?topic=1596.0">"JOGL Release
+href="http://javagaming.org/forums/index.php?topic=1596.0">"JOGL Release
 Information"</a> thread in the JOGL forum. Comments about the 1.1
 release train are in the thread <a
-href="http://192.18.37.44/forums/index.php?topic=4217.0">"JOGL 1.1
+href="http://javagaming.org/forums/index.php?topic=4217.0">"JOGL 1.1
 released"</a>.
 
 </BODY>