summaryrefslogtreecommitdiffstats
path: root/doc/userguide/index.html
diff options
context:
space:
mode:
authorSven Gothel <[email protected]>2012-03-20 15:09:32 +0100
committerSven Gothel <[email protected]>2012-03-20 15:09:32 +0100
commit111294ef61cd245fc5b26176b859439422748138 (patch)
tree6a37b223f72963c44f2c0b823953cbe52a6aa895 /doc/userguide/index.html
parent42c461a157bbcf9e7268b171a7593c2b3ae6a173 (diff)
parentbbc9c854aa96a144175cd3e502e858158fe88dd9 (diff)
Merge remote-tracking branch 'gouessej/patch-1'
Diffstat (limited to 'doc/userguide/index.html')
-rw-r--r--doc/userguide/index.html333
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>