Lots of modifications: updates of several links, addition of some warnings about GLU and SWT, some short explanations about NEWT and GLProfile, addition of some complementary information about general aspects of JOGL, ...

1 files changed, 281 insertions, 52 deletions

diff --git a/doc/userguide/index.html b/doc/userguide/index.html
index aa0645bf9..19d3b145e 100644
--- a/doc/userguide/index.html
+++ b/doc/userguide/index.html
@@ -30,32 +30,53 @@
                     <br/>
 <UL>
 
-  <LI> Overview
-  <LI> Developing with JOGL
+  <LI> Overview </LI>
+  <LI> Developing with JOGL </LI>
   <UL>
-    <LI> Building the source tree
-    <LI> Local installation for development
-    <LI> Java Web Start integration
-    <LI> Applet support
+    <LI> Building the source tree </LI>
+    <LI> Local installation for development </LI>
+      <UL>
+        <LI> Automatic extraction of native libraries </LI>
+        <LI> Installation </LI>
+        <UL>
+          <LI> Jogl distribution </LI>
+          <LI> The classpath (for Java libraries) </LI>
+          <LI> The library path (for native libraries) </LI>
+          <LI> Settings for IDE's users </LI>
+          <LI> Additional JARs </LI>
+          <LI> Bad practices </LI>
+          <LI> Note for Debian Linux users </LI>
+        </UL>
+      </UL>
+    <LI> Java Web Start integration </LI>
+    <LI> Applet support </LI>
   </UL>
-  <LI> GLDrawable and GLContext
-  <LI> Creating a GLAutoDrawable
-  <LI> Writing a GLEventListener
-  <LI> Using the Composable Pipeline
-  <LI> Heavyweight and Lightweight Issues
-  <LI> Multithreading Issues
-  <LI> Pbuffers
-  <LI> GLU
-  <LI> More Resources
-  <LI> Platform notes
+  <LI> GLDrawable and GLContext </LI>
+  <LI> GLProfile </LI>
+  <LI> Creating a GLAutoDrawable </LI>
+  <LI> Writing a GLEventListener </LI>
+    <UL>
+      <LI> Checking extensions and functions availability </LI>
+      <LI> Use of NIO buffers </LI>
+      <LI> Documentation of C language functions matching with Jogl methods </LI>
+      <LI> Performances </LI>
+    </UL>
+  <LI> Using the Composable Pipeline </LI>
+  <LI> Heavyweight and Lightweight Issues </LI>
+  <LI> SWT/AWT issues </LI>
+  <LI> Multithreading Issues </LI>
+  <LI> Pbuffers </LI>
+  <LI> GLU </LI>
+  <LI> More Resources </LI>
+  <LI> Platform notes </LI>
   <UL>
-    <LI> All Platforms
-    <LI> Windows
-    <LI> Linux
-    <LI> Solaris, Linux (X11 platforms)
-    <LI> Macintosh OS X
+    <LI> All Platforms </LI>
+    <LI> Windows </LI>
+    <LI> Linux </LI>
+    <LI> Solaris, Linux (X11 platforms) </LI>
+    <LI> Macintosh OS X </LI>
   </UL>
-  <LI> Version History
+  <LI> Version History </LI>
 
 </UL>
 
@@ -63,23 +84,32 @@
 
 <P>
 
-Jogl is a Java programming language binding for the OpenGL 3D graphics
-API. It supports integration with the Java platform's AWT and Swing
+Jogl is a Java programming language binding for the OpenGL and OpenGL-ES 3D graphics
+APIs. It supports integration with the Java platform's AWT and Swing
 widget sets while providing a minimal and easy-to-use API that handles
 many of the issues associated with building multithreaded OpenGL
-applications. Jogl provides access to the latest OpenGL routines
-(OpenGL 2.0 with vendor extensions) as well as platform-independent
+applications. It supports integration with SWT thanks to an experimental heavyweight 
+SWT GLCanvas and by using the SWT/AWT brigde with AWT GLCanvas or with GLWindow 
+(the NEWT/AWT bridge NewtCanvasAWT is necessary in this case). The support of other 
+windowing systems 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.
+Java-based OpenGL applications than the analogous C program and a native windowing 
+toolkit independent of AWT called NEWT.
 
 </P>
 <P>
 
 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
+and for this reason supports only J2SE 1.4 and later, JavaSE For Embedded, J2ME, Android 2.3 and later. 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 uses NIO internally in the implementation. The Jogl binding
@@ -88,7 +118,7 @@ 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 <a
-href="http://kenai.com/projects/gluegen/pages/Home/">GlueGen</a>, the source code of
+href="../../../gluegen/www/">GlueGen</a>, the source code of
 which is available from its own java.net project.
 
 </P>
@@ -103,6 +133,8 @@ source tree are run through the JSR-231 Technology Compatibility Kit
 writing the JSR has not been finalized, so the first official RI of
 the JSR has not yet been produced.
 
+Jogl is a community project lead by the JogAmp Foundation.
+
 </P>
 
 <H2> Developing with JOGL </H2>
@@ -112,55 +144,117 @@ the JSR has not yet been produced.
 <P>
 
 Most developers using JOGL will download the most current 
-<a href="http://download.java.net/media/jogl/builds/archive/">release build</a>. 
+<a href="http://jogamp.org/deployment/jogamp-current/archive/">release build</a>. 
 Separate instructions are available on how to 
-<a href="http://download.java.net/media/jogl/doc/HowToBuild.html">build the source tree</a>.
+<a href="http://jogamp.org/jogl/doc/HowToBuild.html">build the source tree</a>.
 
 </P>
 
 <H3> Local installation for development </H3>
 
+<H4> Automatic extraction of native libraries </H4>
+
+<P>
+
+JOGL 2.0 has a brand new feature allowing to automatically extract the proper native 
+libraries required to use JOGL from JARs containing them without relying on the Java 
+library path (or any platform-dependent environment variable allowing to set the location 
+of native libraries).
+
+</P>
+
 <P>
 
-The JOGL distribution for developers comes in the form of a zip
+This feature is enabled by default. It can be disabled by setting the flag “jogamp.gluegen.UseTempJarCache” 
+to false (as a VM argument, “-Djogamp.gluegen.UseTempJarCache=false” in command line).
+
+</P>
+
+<H4> Installation </H4>
+
+<H5> Jogl distribution </H5>
+
+<P>
+
+The JOGL distribution for developers comes in the form of a 7zip
 archive which 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 zip
+project; these classes and native code are also provided in the 7zip
 bundles.
 
 </P>
+
 <P>
 
 If you are developing a new application which uses JOGL, download the
 zip archive for your platform (for example.,
-jogl-[version]-windows-i586.zip) and unzip it. Modify your CLASSPATH
+jogl-[version]-windows-i586.zip) and unzip it. 
+
+</P>
+
+<H5> The classpath (for Java libraries) </H5>
+
+<P>
+
+Modify your CLASSPATH
 environment variable to include the full paths to jogl.all.jar,
 nativewindow.all.jar, gluegen-rt.jar, and optionally newt.all.jar; for
 example,
 ".;C:\Some\Other\Package\foo.jar;C:\Users\myhome\jogl-[version]-windows-i586\lib\jogl.all.jar;C:\Users\myhome\jogl-[version]-windows-i586\lib\nativewindow.all.jar;C:\Users\myhome\jogl-[version]-windows-i586\lib\gluegen-rt.jar;C:\Users\myhome\jogl-[version]-windows-i586\lib\newt.all.jar".
 (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.) Modify your PATH environment variable (Windows),
-LD_LIBRARY_PATH environment variable (Solaris and Linux), or
-DYLD_LIBRARY_PATH environment variable (Mac OS X) to contain the full
-path to the "lib" directory; for example, on Windows, add
+CLASSPATH.) The path separator is ":" under Solaris, Mac and Linux. 
+
+</P>
+
+<H5> The library path (for native libraries) </H5>
+
+<P>
+
+If you use the automatic extraction of native libraries (enabled by 
+default, see the previous section for more details), the JARs containing 
+the native libraries must be in the same directories than the Java libraries 
+that directly use their native functions. Otherwise, you must set the VM 
+argument java.library.path or you can set the platform-dependent environment 
+variable used for the location of native libraries. Then, modify your PATH 
+environment variable (Windows), LD_LIBRARY_PATH environment variable (Solaris 
+and Linux), or DYLD_LIBRARY_PATH environment variable (Mac OS X) to contain 
+the full path to the "lib" directory; for example, on Windows, add
 "C:\Users\myhome\jogl-[version]-windows-i586\lib" 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. Users of IDEs such as NetBeans and Eclipse should
-consult the IDE's documentation to see how to add jar files and native
-libraries to their current project.
+button. At this point your Java installation should be able to see the Jogl class files.
 
 </P>
+
+<H5> Settings for IDE's users </H5>
+
 <P>
 
-Note that the per-platform zip archives contain many more jar files
+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>
+
+<H5> Additional JARs </H5>
+
+<P>
+
+Note that the per-platform 7zip archives contain many more jar files
 than just the three or four mentioned above. The additional jars
 illustrate how JOGL may be partitioned to achieve a smaller deployment
 size, in particular on smaller devices.
 
 </P>
+
+<H5> Bad practices </H5>
+
 <P>
 
 Dropping the JOGL jars and native libraries into the extension
@@ -173,7 +267,15 @@ Start, and causes confusion later when upgrading the distribution.
 
 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.
+JPackage Java RPMs and JOGL. 
+
+</P>
+
+<H5> Note for Debian Linux users </H5>
+
+<P>
+
+DEB packages are available for this distribution on its official repositories.
 
 </P>
 
@@ -206,7 +308,7 @@ as 1.4.2, which is the earliest version of Java supported by JOGL.
 </P>
 <P>
 
-The JOGLAppletInstaller is distributed inside jogl.jar as a utility
+The JOGLAppletInstaller is distributed inside jogl.all.jar as a utility
 class in com.jogamp.opengl.util. It requires that the developer host a
 local, signed copy of jogl.jar and all of the jogl-natives jars; the
 certificates must be the same on all of these jars. Note that in the
@@ -238,6 +340,7 @@ 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.
@@ -247,11 +350,19 @@ objects is the GLContext.
 
 </P>
 
+<H2> GLProfile </H2>
+
+<P>
+
+GLProfile instances maps OpenGL profiles introduced in OpenGL 3, please read <a href="http://jogamp.org/jogl/doc/Overview-OpenGL-Evolution-And-JOGL.html">this</a> for more details.
+
+</P>
+
 <H2> Creating a GLAutoDrawable </H2>
 
 <P>
 
-Jogl provides two basic widgets into which OpenGL rendering can be
+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
@@ -269,11 +380,13 @@ 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>
 <P>
 
-Both the GLCanvas and GLJPanel implement a common interface called
+GLCanvas, GLWindow and GLJPanel implement a common interface called
 GLAutoDrawable so applications can switch between them with minimal
 code changes. The GLAutoDrawable interface provides
 
@@ -295,12 +408,12 @@ code changes. The GLAutoDrawable interface provides
 </P>
 <P>
 
-When creating GLCanvas and GLJPanel instances, the user may request a
+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 only).
+GLAutoDrawable will be created (GLCanvas and GLWindow only).
 
 </P>
 <P>
@@ -411,6 +524,54 @@ 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> Performances </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>
@@ -455,6 +616,46 @@ CONTEXT_CURRENT_NEW.
 
 </P>
 
+<P>
+
+N.B: DebugGL and TraceGL have been splitted into several classes matching 
+with all GL subclasses.
+
+<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>
+
+</P>
+
 <H2> Heavyweight and Lightweight Issues </H2>
 
 <P>
@@ -547,6 +748,22 @@ 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> Multithreading Issues </H2>
 
 <P>
@@ -753,6 +970,11 @@ 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>
 
@@ -958,11 +1180,11 @@ following steps should be taken:
 <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.
+is current. </LI>
 
 <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
-is current.
+is current. </LI>
 
 </UL>
 
@@ -983,7 +1205,7 @@ 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.
+and the GLCapabilitiesChooser is ignored. </LI>
 
 </UL>
 
@@ -1000,6 +1222,13 @@ release train are in the thread <a
 href="http://javagaming.org/forums/index.php?topic=4217.0">"JOGL 1.1
 released"</a>.
 
+</P>
+
+<P>
+
+The whole evolution of JOGL (including major changes in JOGL 2.0) is described <a href="http://jogamp.org/jogl/doc/Overview-OpenGL-Evolution-And-JOGL.html">here</a>.
+
+</P>
 
                 </div>
             </div>