diff options
| -rw-r--r-- | doc/userguide/index.html | 333 |
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> |