From bbc9c854aa96a144175cd3e502e858158fe88dd9 Mon Sep 17 00:00:00 2001 From: Julien Gouesse Date: Tue, 20 Mar 2012 14:54:34 +0100 Subject: 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, ... --- doc/userguide/index.html | 333 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 281 insertions(+), 52 deletions(-) (limited to 'doc/userguide') 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 @@
@@ -63,23 +84,32 @@

-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. + +

+

+ +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.

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 GlueGen, the source code of +href="../../../gluegen/www/">GlueGen, the source code of which is available from its own java.net project.

@@ -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. +

Developing with JOGL

@@ -112,55 +144,117 @@ the JSR has not yet been produced.

Most developers using JOGL will download the most current -release build. +release build. Separate instructions are available on how to -build the source tree. +build the source tree.

Local installation for development

+

Automatic extraction of native libraries

+ +

+ +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). + +

+

-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). + +

+ +

Installation

+ +
Jogl distribution
+ +

+ +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.

+

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. + +

+ +
The classpath (for Java libraries)
+ +

+ +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. + +

+ +
The library path (for native libraries)
+ +

+ +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.

+ +
Settings for IDE's users
+

-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. + +

+ +
Additional JARs
+ +

+ +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.

+ +
Bad practices
+

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. + +

+ +
Note for Debian Linux users
+ +

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

@@ -206,7 +308,7 @@ as 1.4.2, which is the earliest version of Java supported by JOGL.

-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.

+

Most end users will not need to use these abstractions directly. @@ -247,11 +350,19 @@ objects is the GLContext.

+

GLProfile

+ +

+ +GLProfile instances maps OpenGL profiles introduced in OpenGL 3, please read this for more details. + +

+

Creating a GLAutoDrawable

-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 this forum discussion 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.

-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

-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).

@@ -411,6 +524,54 @@ on multithreading.

+

Checking extensions and functions availability

+ +

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

+ +

Use of NIO buffers

+ +

+ +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. + +

+ +

Documentation of C language functions matching with Jogl methods

+ +

+ +Jogl documentation often refers to C language functions. You can find the +documentation of these functions in OpenGL references pages here. + +

+ +

Performances

+ +

+ +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. + +

+

Using the Composable Pipeline

@@ -455,6 +616,46 @@ CONTEXT_CURRENT_NEW.

+

+ +N.B: DebugGL and TraceGL have been splitted into several classes matching +with all GL subclasses. + +

+
+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));
+                  }
+              }
+          }
+     }
+}
+
+
+ +

+

Heavyweight and Lightweight Issues

@@ -547,6 +748,22 @@ JOGL + Swing flicker" in the JOGL forum.

+

SWT/AWT issues

+ +

+ +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 doLayout()) before starting the animator (or calling display()) 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). + +

+

Multithreading Issues

@@ -752,6 +969,11 @@ 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. +

+

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

More Resources

@@ -958,11 +1180,11 @@ following steps should be taken:
  • Create an "external" OpenGL context using the GLDrawableFactory.createExternalGLContext() API. The context object must be created while a real underlying OpenGL context -is current. +is current.
  • 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.
    • @@ -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. @@ -1000,6 +1222,13 @@ release train are in the thread "JOGL 1.1 released". +

    + +

    + +The whole evolution of JOGL (including major changes in JOGL 2.0) is described here. + +

    -- cgit v1.2.3