diff options
Diffstat (limited to 'doc/userguide')
| -rw-r--r-- | doc/userguide/index.html | 1012 |
1 files changed, 432 insertions, 580 deletions
diff --git a/doc/userguide/index.html b/doc/userguide/index.html index 19d3b145e..cdb26f140 100644 --- a/doc/userguide/index.html +++ b/doc/userguide/index.html @@ -1,4 +1,4 @@ -<!DOCTYPE html PUBliC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> @@ -25,76 +25,93 @@ </div> <div id="main"> <div id="text" class="fill"> - <h2><font color="red">WARNING: This document has not been updated for a long time.</font></h2> + <b><font color="red">WARNING: This document is under review.</font></b> <br/> <br/> -<UL> - - <LI> Overview </LI> - <LI> Developing with JOGL </LI> - <UL> - <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> - <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> - <LI> Windows </LI> - <LI> Linux </LI> - <LI> Solaris, Linux (X11 platforms) </LI> - <LI> Macintosh OS X </LI> - </UL> - <LI> Version History </LI> - -</UL> - -<H2> Overview </H2> - -<P> - -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. 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> +<ul> + + <li> <a href="#overview">Overview</a> </li> + <li> <a href="#access">Accessing JOGL</a> + <ul> + <li> <a href="#building">Building the source tree</a></li> + <li> <a href="#localinstallation">Local installation</a> + <ul> + <li> <a href="#archivefiles">7z Archives</a></li> + <li> <a href="#jarfilesandclasspath">JAR Files & CLASSPATH</a> + <ul> + <li> <a href="#atomicjarfiles">Atomic JAR files</a></li> + </ul></li> + <li> <a href="#automatednativelibraryloading">Automated Native Library Loading</a></li> + <li> <a href="#traditionallibraryloading">Traditional Native Library Loading</a></li> + <li> <a href="#ideusers">Settings for IDE's users</a></li> + <li> <a href="#badpractice">Bad practice</a></li> + <li> <a href="#notefordebianusers">Note for Debian Linux users</a></li> + </ul></li> + <li> <a href="#onlinedeployment">Online Deployment</a> + <ul> + <li> <a href="#applets">Applets</a></li> + <li> <a href="#jnlpwebstart">JNLP / Web Start</a></li> + </ul></li> + </ul></li> + <li> <a href="#joglapi">Using the JOGL API</a> + <ul> + <li> <a href="#gldrawableandglcontext">GLDrawable and GLContext</a></li> + <li> <a href="#glprofile">GLProfile</a></li> + <li> <a href="#creatingaglautodrawable">Creating a GLAutoDrawable</a></li> + <li> <a href="#writingagleventlistener">Writing a GLEventListener</a></li> + <li> <a href="#checkingextensionsandfunctionsavailability">Checking extensions and functions availability</a></li> + <li> <a href="#useofniobuffers">Use of NIO buffers</a></li> + <li> <a href="#documentationofclang">Documentation of C language functions matching with Jogl methods</a></li> + <li> <a href="#performance">Performance</a></li> + <li> <a href="#composablepipeline">Using the Composable Pipeline</a></li> + <li> <a href="#heavylightweightissues">Heavyweight and Lightweight Issues</a></li> + <li> <a href="#swtawtissues">SWT/AWT issues</a></li> + <li> <a href="#multithreadingissues">AWT Multithreading Issues</a></li> + <li> <a href="#pbuffers">Pbuffers</a></li> + <li> <a href="#glu">GLU</a></li> + <li> <a href="#moreresources">More Resources</a></li> + </ul></li> + <li> <a href="#platformnotes">Platform notes</a> + <ul> + <li> <a href="#allplatforms">All Platforms</a></li> + <li> <a href="#windows">Windows</a></li> + <li> <a href="#x11unix">X11 Platforms (Linux, Solaris, ..)</a></li> + <li> <a href="#macosx">Macintosh OS X</a></li> + </ul></li> + <li> <a href="#versionhistory">Version History</a></li> + +</ul> + +<h2> <a name="overview">Overview</a> </h2> + +<p> + The JOGL project hosts the development version of the Java™ Binding for the OpenGL® API, + and is designed to provide hardware-supported 3D graphics to applications written in Java. +</p> +<p> + It provides full access to the APIs in the OpenGL 1.3 - 3.0, 3.1 - 3.3, ≥ 4.0, ES 1.x and ES 2.x specification + as well as nearly all vendor extensions. + <a href="../Overview-OpenGL-Evolution-And-JOGL.html">OpenGL Evolution & JOGL</a> + (<a href="../bouml/html-svg/fig128069.svg">UML</a>) gives you a brief overview of OpenGL, + its profiles and how we map them to JOGL. +</p> +<p> + It integrates with the AWT, Swing and SWT widget sets, as well with custom windowing toolkits using the NativeWindow API. + <a href="../NEWT-Overview.html">JOGL also provides its own native windowing toolkit, NEWT</a>. +</p> + +<p> +AWT integration is available via AWT GLCanvas and NEWT's NewtCanvasAWT, +where Swing integration is available via GLJPanel. +</p> +<p> +SWT integration is available via SWT GLCanvas and by using the SWT/AWT brigde. +</p> +<p> +Other windowing systems or widgets sets 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 @@ -105,131 +122,136 @@ composable pipeline model which can provide faster debugging for 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, JavaSE For Embedded, J2ME, Android 2.3 and later. It also only -supports truecolor (15 bits per pixel and higher) rendering; it does +</p> + +Jogl is designed for the most recent versions of the Java platform +and for this reason supports only: +<ul> + <li>Java 1.6 (Level 6.0) + <ul> + <li> J2SE ≥ 1.6 (OpenJDK, Oracle, ..)</li> + <li> JavaSE ≥ 1.6 For Embedded (Oracle) </li> + </ul></li> + <li>Android SDK API Level 9 (Version 2.3 Gingerbread)</li> +</ul> + +<p> +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 -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 +mind and often uses NIO internally in the implementation. Nevertheless non +NIO/direct buffers/arrays are supported as well, since they allow faster processing on +CPU intensive tasks. +The Jogl binding is itself written almost completely in the Java programming language. +Most of the native code is autogenerated during the build process by a new tool called <a href="../../../gluegen/www/">GlueGen</a>, the source code of -which is available from its own java.net project. - -</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. +which is available from its own jogamp.org project. -Jogl is a community project lead by the JogAmp Foundation. +</p> -</P> +<h2> <a name="access">Accessing JOGL</a> </h2> -<H2> Developing with JOGL </H2> +<h3> <a name="building">Building the source tree</a> </h3> -<H3> Building the source tree </H3> - -<P> +<p> Most developers using JOGL will download the most current -<a href="http://jogamp.org/deployment/jogamp-current/archive/">release build</a>. +<a href="../../../deployment/jogamp-current/archive/">release build</a>. Separate instructions are available on how to -<a href="http://jogamp.org/jogl/doc/HowToBuild.html">build the source tree</a>. +<a href="../HowToBuild.html">build the source tree</a>. -</P> +</p> -<H3> Local installation for development </H3> +<h3> <a name="localinstallation">Local Installation</a> </h3> -<H4> Automatic extraction of native libraries </H4> +See <a href="../deployment/JOGL-DEPLOYMENT.html">deployment</a> for deployment details. -<P> +<h4> <a name="archivefiles">7zip Archives</a> </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). +A 7zip archive for all platforms and all JogAmp modules including JOGL +is available, named <code>jogamp-all-platforms.7z</code>, +as available <a href="../../../deployment/jogamp-current/archive/jogamp-all-platforms.7z">here</a>. +It 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 7zip +bundles. -</P> +</p> -<P> +<h4> <a name="jarfilesandclasspath">JAR Files & CLASSPATH</a> </h4> -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). +Modify your <code>CLASSPATH</code> +environment variable to include the full paths to +<code>gluegen-rt.jar</code> and <code>jogl.all.jar</code>, for example +<pre> +".;C:\Some\Other\Package\foo.jar;C:\Users\myhome\jogamp-all-platforms\jar\gluegen-rt.jar;C:\Users\myhome\jogamp-all-platforms\jar\jogl.all.jar". +</pre> +(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.) The path separator is ":" under Solaris, Mac and Linux. -</P> +<h5> <a name="atomicjarfiles">Atomic JAR files</a> </h5> -<H4> Installation </H4> +<p> -<H5> Jogl distribution </H5> +Note that the 7zip archive contain more jar files +than just the above mentioned. Additional atomic jars <code>jogamp-all-platforms/jar/atomic/</code> +illustrate how JOGL may be partitioned to achieve a smaller deployment +size, in particular on smaller devices. See <a href="../deployment/JOGL-DEPLOYMENT.html">deployment</a> for details. -<P> +</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 7zip -bundles. +<h4> <a name="automatednativelibraryloading">Automated Native Library Loading</a> </h4> -</P> +<p> -<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. This allows desktop applications as well as traditional Applets +to utilize the native library JAR files the same way Webstart/JNLP does. -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. +</p> -</P> +<p> +To allow the native JAR file library loading to work, ensure that all JogAmp JAR files +are left unmodified within their common directory. +</p> -<H5> The classpath (for Java libraries) </H5> +<p> +In case the native library JAR files cannot be opened, it falls back to the traditional +native library loading mechanism via the java library path. +</p> -<P> +<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.) The path separator is ":" under Solaris, Mac and Linux. +This feature is enabled by default and - for whatever reason - it can be disabled by setting the +property <code>jogamp.gluegen.UseTempJarCache</code> +to false (as a VM argument, <code>-Djogamp.gluegen.UseTempJarCache=false</code> in command line). -</P> +</p> -<H5> The library path (for native libraries) </H5> +<h4> <a name="traditionallibraryloading">Traditional Native Library Loading</a> </h4> -<P> +<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 +If you don't use <a href="#automatednativelibraryloading">automatic native libraries loading</a>, +as enabled by default, you must set either the VM property <code>java.library.path</code> +or the platform-dependent environment variable used for the location of native libraries, +<code>PATH</code> on Windows, <code>LD_LIBRARY_PATH</code> on Unix (Linux, Solaris, ..) +and <code>DYLD_LIBRARY_PATH</code> on Mac OS X. +The environment variable shall contain the full path to the "lib" directory; for example, on Windows, add +<code>"C:\Users\myhome\jogamp-all-platforms\lib\windows-amd64"</code> 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. -</P> +</p> -<H5> Settings for IDE's users </H5> +<h4> <a name="ideusers">Settings for IDE's users</a> </h4> -<P> +<p> Eclipse users must add the JARs containing Java libraries into the Java Build Path of their project. They must set the native library location @@ -240,127 +262,98 @@ 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> +</p> -<H5> Bad practices </H5> +<h4> <a name="badpractice">Bad practice</a> </h4> -<P> +<p> Dropping the JOGL jars and native libraries into the extension directory of the JRE is <b>strongly discouraged</b>. Doing so will cause conflicts with third-party applications launched via Java Web Start, and causes confusion later when upgrading the distribution. -</P> -<P> +</p> +<p> 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. -</P> +</p> -<H5> Note for Debian Linux users </H5> +<h4> <a name="notefordebianusers">Note for Debian Linux users</a> </h4> -<P> +<p> DEB packages are available for this distribution on its official repositories. -</P> +</p> -<H3> Java Web Start integration </H3> +<h3> <a name="onlinedeployment">Online Deployment</a> </h3> -<P> - -The recommended distribution vehicle for applications using JOGL is -Java Web Start. JOGL-based applications do not even need to be signed; -all that is necessary is to reference the JOGL extension JNLP file. -Because the JOGL jar files are signed, an unsigned application can -reference the signed JOGL library and continue to run inside the -sandbox. - -</P> -<P> +The recommended distribution vehicle for <i>online</i> applications using JOGL is +either using Applets or Java Web Start. JOGL-based applications do not even need to be signed; +all that is necessary is to reference the online resources using the appropriate URLs. +<p> Please read <a href="../deployment/JOGL-DEPLOYMENT.html">JOGL Deployment</a>. +</p> -<H3> Applet support </H3> - -<P> - -Lilian Chamontin, in conjunction with several other members of the -JOGL community, has contributed a JOGL applet installer. This -installer uses some clever tricks to allow deployment of unsigned -applets which use JOGL into existing web browsers and JREs as far back -as 1.4.2, which is the earliest version of Java supported by JOGL. - -</P> -<P> +<h4> <a name="applets">Applets</a> </h4> -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 -release builds of JOGL all of these jars are signed by Sun -Microsystems, so the developer can deploy applets without needing any -certificates. +<p> +You might want to have a look at our <a href="../../../deployment/jogamp-current/jogl-test-applets.html">Test page for JOGL Applet</a> +</p> -</P> -<P> +Here are documented Applet launch examples: +<ol> + <li> <a href="../../../deployment/jogamp-current/jogl-applet-runner-newt-gears-normal-napplet.html">Pure Applet</a> (<b>recommended</b>)</li> + <li> <a href="../../../deployment/jogamp-current/jogl-applet-runner-newt-gears-normal.html">JNLP Applet w/ AppletLauncher-fallback </a></li> +</ol> -The JOGLAppletInstaller javadoc describes the basic steps for -deployment of an applet utilizing JOGL. Please refer to this -documentation for more information. A live example of deploying an -unsigned JOGL applet will be added to this documentation shortly once -the first signed build of the JOGLAppletInstaller has been shipped. +<h4> <a name="jnlpwebstart">JNLP / Webstart</a> </h4> -</P> +<p> +Here is a documented <a href="../../../deployment/jogamp-current/jogl-applet-runner-newt-gears-normal.html">JNLP Applet w/ AppletLauncher-fallback </a>, +which also documents how to utilize JOGL via WebStart with slight modifications. +</p> -<H2> GLDrawable and GLContext </H2> +<h2> <a name="joglapi">Using the JOGL API</a> </h2> -<P> +<h3> <a name="gldrawableandglcontext">GLDrawable and GLContext</a> </h3> +<p> -The JSR-231 APIs specify interfaces two low-level OpenGL abstractions: +The 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 +created for a particular drawable. In these abstractions, a context is always associated with exactly one drawable. -</P> +</p> -<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> +</p> -<H2> GLProfile </H2> +<h3> GLProfile </h3> -<P> +<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. +GLProfile instances maps OpenGL profiles introduced in OpenGL 3, please read <a href="../Overview-OpenGL-Evolution-And-JOGL.html">this</a> for more details. -</P> +</p> -<H2> Creating a GLAutoDrawable </H2> +<h3> Creating a GLAutoDrawable </h3> -<P> +<p> Jogl provides three basic widgets into which OpenGL rendering can be performed. The GLCanvas is a heavyweight AWT widget which supports @@ -383,30 +376,28 @@ 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> +</p> GLCanvas, GLWindow and GLJPanel implement a common interface called GLAutoDrawable so applications can switch between them with minimal code changes. The GLAutoDrawable interface provides -<UL> +<ul> - <LI> access to the GL object for calling OpenGL routines + <li> access to the GL object for calling OpenGL routines</li> - <LI> a callback mechanism (GLEventListener) for performing OpenGL - rendering + <li> a callback mechanism (GLEventListener) for performing OpenGL + rendering</li> - <LI> a <CODE>display()</CODE> method for forcing OpenGL rendering to - be performed synchronously + <li> a <code>display()</code> method for forcing OpenGL rendering to + be performed synchronously</li> - <LI> AWT- and Swing-independent abstractions for getting and setting - the size of the widget and adding and removing event listeners + <li> AWT- and Swing-independent abstractions for getting and setting + the size of the widget and adding and removing event listeners</li> -</UL> +</ul> -</P> -<P> +<p> When creating GLCanvas, GLWindow and GLJPanel instances, the user may request a certain set of OpenGL parameters in the form of a GLCapabilities @@ -415,8 +406,8 @@ GLCapabilitiesChooser, share textures and display lists with other GLDrawables, and specify the display device on which the GLAutoDrawable will be created (GLCanvas and GLWindow only). -</P> -<P> +</p> +<p> A GLCapabilities object specifies the OpenGL parameters for a newly-created widget, such as the color, alpha,, z-buffer and @@ -425,8 +416,8 @@ double-buffered. The default capabilities are loosely specified but provide for truecolor RGB, a reasonably large depth buffer, double-buffered, with no alpha, stencil, or accumulation buffers. -</P> -<P> +</p> +<p> An application can override the default pixel format selection algorithm by providing a GLCapabilitiesChooser to the GLCanvas or @@ -441,8 +432,8 @@ array. The DefaultGLCapabilitiesChooser uses the window system's recommendation when it is available, and otherwise attempts to use a platform-independent selection algorithm. -</P> -<P> +</p> +<p> The GLJPanel can be made non-opaque according to Swing's rendering model, so it can act as an overlay to other Swing or Java2D drawing. @@ -453,11 +444,11 @@ rendering underneath it will then show through areas where OpenGL has produced an alpha value less than 1.0. See the JGears and JRefract demos for examples of how to use this functionality. -</P> +</p> -<H2> Writing a GLEventListener </H2> +<h3> Writing a GLEventListener </h3> -<P> +<p> Applications implement the GLEventListener interface to perform OpenGL drawing via callbacks. When the methods of the GLEventListener are @@ -465,26 +456,26 @@ 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> +</p> +<p> -The <CODE>init()</CODE> method is called when a new OpenGL context is +The <code>init()</code> method is called when a new OpenGL context is 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 +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 -<CODE>init()</CODE> method may be called more than once during the +<code>init()</code> method may be called more than once during the lifetime of the application. The init() method should therefore be kept as short as possible and only contain the OpenGL initialization -required for the <CODE>display()</CODE> method to run properly. It is +required for the <code>display()</code> method to run properly. It is the responsibility of the application to keep track of how its various OpenGL contexts share display lists, textures and other OpenGL objects so they can be either be reinitialized or so that reinitialization can -be skipped when the <CODE>init()</CODE> callback is called. +be skipped when the <code>init()</code> callback is called. -</P> -<P> +</p> +<p> Note also that the GLEventListener should be added to the GLAutoDrawable before the GLAutoDrawable is shown or rendered to for @@ -494,24 +485,24 @@ maintain internal state to keep track of whether init() has been called on a particular GLEventListener since the last time an OpenGL context was created for that GLAutoDrawable. -</P> -<P> +</p> +<p> -The <CODE>display()</CODE> method is called to perform per-frame -rendering. The <CODE>reshape()</CODE> method is called when the +The <code>display()</code> method is called to perform per-frame +rendering. The <code>reshape()</code> method is called when the drawable has been resized; the default implementation automatically resizes the OpenGL viewport so often it is not necessary to do any -work in this method. The <CODE>displayChanged()</CODE> method is +work in this method. The <code>displayChanged()</code> method is designed to allow applications to support on-the-fly screen mode switching, but support for this is not yet implemented so the body of this method should remain empty. -</P> -<P> +</p> +<p> 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> +<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 from there. The reason is that multithreading issues inherent to the @@ -522,21 +513,21 @@ thread that does not have a current context. This will usually cause the application to crash. For more information please see the section on multithreading. -</P> +</p> -<H3> Checking extensions and functions availability </H3> +<h3> Checking extensions and functions availability </h3> -<P> +<p> GLBase.isFunctionAvailable(String glFunctionName) and GLBase.isExtensionAvailable(String glExtensionName) allow to check whether OpenGL functions and extensions are available. -</P> +</p> -<H3> Use of NIO buffers </H3> +<h3> Use of NIO buffers </h3> -<P> +<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 @@ -550,49 +541,50 @@ mind that direct NIO buffers are page-aligned and allocated in the native heap 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> +</p> -<H3> Documentation of C language functions matching with Jogl methods </H3> +<h3> Documentation of C language functions matching with Jogl methods </h3> -<P> +<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> +</p> -<H3> Performances </H3> +<h3> Performance </h3> -<P> +<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> +</p> -<H2> Using the Composable Pipeline </H2> +<h2> Using the Composable Pipeline </h2> -<P> +<p> Jogl supports the "composable pipeline" paradigm introduced by the Magician Java binding for OpenGL. The DebugGL pipeline calls -<CODE>glGetError</CODE> after each OpenGL call, reporting any errors +<code>glGetError</code> after each OpenGL call, reporting any errors found. It can greatly speed up development time because of its fine-grained error checking as opposed to the manual error checking usually required in OpenGL programs written in C. The TraceGL prints logging information upon each OpenGL call and is helpful when an application crash makes it difficult to see where the error occurred. -</P> -<P> +</p> +<p> -To use these pipelines, call <CODE>GLAutoDrawable.setGL</CODE> at the -beginning of the <CODE>init</CODE> method in your GLEventListener. For +To use these pipelines, call <code>GLAutoDrawable.setGL</code> at the +beginning of the <code>init</code> method in your GLEventListener. For example, +</p> -<PRE> +<pre> class MyListener implements GLEventListener { public void init(GLDrawable drawable) { drawable.setGL(new DebugGL(drawable.getGL())); @@ -601,10 +593,9 @@ class MyListener implements GLEventListener { // ... } -</PRE> +</pre> -</P> -<P> +<p> Note that the GLAutoDrawable.setGL() method simply calls setGL() on the default OpenGL context created by the GLAutoDrawable, so @@ -614,14 +605,14 @@ in the context object itself. The composable pipeline needs to be re-installed every time GLContext.makeCurrent() returns CONTEXT_CURRENT_NEW. -</P> - -<P> +</p> +<p> N.B: DebugGL and TraceGL have been splitted into several classes matching with all GL subclasses. +</p> -<PRE> +<pre> if (drawable.getGL().isGL4bc()) { final GL4bc gl4bc = drawable.getGL().getGL4bc(); @@ -652,13 +643,11 @@ else { } } -</PRE> - -</P> +</pre> -<H2> Heavyweight and Lightweight Issues </H2> +<h2> Heavyweight and Lightweight Issues </h2> -<P> +<p> As mentioned above, JOGL supplies both a heavyweight (GLCanvas) and a lightweight (GLJPanel) widget to be able to provide the fastest @@ -674,18 +663,18 @@ 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> +</p> +<p> When using JPopupMenus or Swing tool tips in conjunction with the GLCanvas, it is necessary to disable the use of lightweight widgets for the popups. See the methods -<CODE>ToolTipManager.setLightWeightPopupEnabled</CODE>, -<CODE>JPopupMenu.setLightWeightPopupEnabled</CODE>, and -<CODE>JPopupMenu.setDefaultLightWeightPopupEnabled</CODE>. +<code>ToolTipManager.setLightWeightPopupEnabled</code>, +<code>JPopupMenu.setLightWeightPopupEnabled</code>, and +<code>JPopupMenu.setDefaultLightWeightPopupEnabled</code>. -</P> -<P> +</p> +<p> There are occasionally problems with certain LayoutManagers and component configurations where if a GLCanvas is placed in the middle @@ -704,8 +693,8 @@ matter, but for others like the BoxLayout it does. See the test case attached to Issue 135 for an example. Replacing the GLCanvas with an ordinary Canvas yields the same behavior. -</P> -<P> +</p> +<p> One suggestion was to override getPreferredSize() so that if a preferred size has not been set by the user, to default to (0, @@ -721,18 +710,18 @@ demo breaks in the same way it originally did. Therefore this solution is fragile because it isn't clear which of these methods are used internally by the AWT and for what purposes. -</P> -<P> +</p> +<p> There are two possible solutions, both application-specific. The best and most portable appears to be to put the GLCanvas into a JPanel and set the JPanel's preferred size to (0, 0). The JPanel will cause this constraint to be enforced on its contained GLCanvas. The other -workaround is to call <CODE>setPreferredSize(new Dimension(0, -0))</CODE> on a newly-created GLCanvas; this method is new in 1.5. +workaround is to call <code>setPreferredSize(new Dimension(0, +0))</code> on a newly-created GLCanvas; this method is new in 1.5. -</P> -<P> +</p> +<p> Another issue that occasionally arises on Windows is flickering during live resizing of a GLCanvas. This is caused by the AWT's repainting @@ -740,33 +729,35 @@ the background of the Canvas and can not be overridden on a per-Canvas basis, for example when subclassing Canvas into GLCanvas. The repainting of the background of Canvases on Windows can be disabled by specifying the system property -<CODE>-Dsun.awt.noerasebackground=true</CODE>. Whether to specify this +<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://javagaming.org/forums/index.php?topic=8770.0">"TIP: JOGL + Swing flicker"</a> in the JOGL forum. -</P> +</p> -<H2> SWT/AWT issues </H2> +<h2> SWT/AWT issues </h2> -<P> +<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 +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> +</p> + +<h2> AWT Multithreading Issues </h2> -<H2> Multithreading Issues </H2> +Below statements incorrect! -<P> +<p> Jogl was designed to interoperate with the AWT, an inherently multithreaded GUI toolkit. OpenGL, in contrast, was originally @@ -775,50 +766,50 @@ reason Jogl provides a framework in which it is possible to write correct multithreaded OpenGL applications using the GLEventListener paradigm. -</P> -<P> +</p> +<p> If an application written using Jogl interacts in any way with the mouse or keyboard, the AWT is processing these events and the multithreaded aspects of the program must be considered. -</P> -<P> +</p> +<p> 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>GLAutoDrawable.display()</CODE> manually at the end of the mouse +<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> +</p> +<p> In the continuous repaint model, the application typically has a main -loop which is calling <CODE>GLAutoDrawable.display()</CODE> +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> +</p> +<p> Both of these models (repaint-on-demand and repaint continually) still require the user to think about which thread keyboard and mouse events are coming in on, and which thread is performing the OpenGL rendering. -OpenGL rendering <B>may not</B> occur directly inside the mouse or +OpenGL rendering <b>may not</b> occur directly inside the mouse or 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>GLAutoDrawable.display()</CODE>. +<code>GLAutoDrawable.display()</code>. -</P> -<P> +</p> +<p> It is generally recommended that applications perform as little work as possible inside their mouse and keyboard handlers to keep the GUI @@ -826,16 +817,16 @@ responsive. However, since OpenGL commands can not be run from directly within the mouse or keyboard event listener, the best practice is to store off state when the listener is entered and retrieve this state during the next call to -<CODE>GLEventListener.display()</CODE>. +<code>GLEventListener.display()</code>. -</P> -<P> +</p> +<p> Furthermore, it is recommended that if there are long computational -sequences in the GLEventListener's <CODE>display</CODE> method which +sequences in the GLEventListener's <code>display</code> method which reference variables which may be being simultaneously modified by the AWT thread (mouse and keyboard listeners) that copies of these -variables be made upon entry to <CODE>display</CODE> and these copies +variables be made upon entry to <code>display</code> and these copies be referenced throughout display() and the methods it calls. This will prevent the values from changing while the OpenGL rendering is being performed. Errors of this kind show up in many ways, including certain @@ -845,13 +836,13 @@ the scene. Restructuring the display() method as described has solved all instances of this kind of error that have been seen with Jogl to date. -</P> -<P> +</p> +<p> Prior to Jogl 1.1 b10, the Jogl library attempted to give applications strict control over which thread or threads performed OpenGL -rendering. The <CODE>setRenderingThread()</CODE>, -<CODE>setNoAutoRedrawMode()</CODE> and <CODE>display()</CODE> APIs +rendering. The <code>setRenderingThread()</code>, +<code>setNoAutoRedrawMode()</code> and <code>display()</code> APIs were originally designed to allow the application to create its own animation thread and avoid OpenGL context switching on platforms that supported it. Unfortunately, serious stability issues caused by @@ -860,8 +851,8 @@ platform implementation have arisen on three of Jogl's major supported platforms: Windows, Linux and Mac OS X. In order to address these bugs, the threading model in Jogl 1.1 b10 and later has changed. -</P> -<P> +</p> +<p> All GLEventListener callbacks and other internal OpenGL context management are now performed on one thread. (In the current @@ -869,17 +860,17 @@ 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>GLAutoDrawable.display()</CODE> method is called from user code, +<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>setNoAutoRedrawMode()</CODE> API still works as previously +<code>setRenderingThread()</code> optimization is now a no-op. The +<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.) -</P> -<P> +</p> +<p> Most applications will not see a change in behavior from this change in the Jogl implementation. Applications which use thread-local @@ -887,28 +878,28 @@ storage or complex multithreading and synchronization may see a change in their control flow requiring code changes. While it is strongly recommended to change such applications to work under the new threading model, the old threading model can be used by specifying the -system property <CODE>-Djogl.1thread=auto</CODE> or -<CODE>-Djogl.1thread=false</CODE>. The "auto" setting is equivalent to +system property <code>-Djogl.1thread=auto</code> or +<code>-Djogl.1thread=false</code>. The "auto" setting is equivalent to the behavior in 1.1 b09 and before, where on ATI cards the single-threaded mode would be used. The "false" setting is equivalent to disabling the single-threaded mode. "true" is now the default setting. -</P> -<P> +</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 +In the 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> +</p> -<H2> Pbuffers </H2> +<h2> Pbuffers </h2> -<P> +<p> Jogl exposes hardware-accelerated offscreen rendering (pbuffers) with a minimal and platform-agnostic API. Several recent demos have been @@ -917,18 +908,18 @@ However, the pbuffer support in Jogl remains one of the more experimental aspects of the package and the APIs may need to change in the future. -</P> -<P> +</p> +<p> To create a pbuffer, call -<CODE>GLDrawableFactory.createGLPbuffer()</CODE>. It is wise to call -<CODE>GLDrawableFactory.canCreateGLPbuffer()</CODE> first to ensure +<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. +<code>createGLPbuffer</code> returns. -</P> -<P> +</p> +<p> A pbuffer is used in conjunction with the GLEventListener mechanism by calling its display() method. Rendering, as always, occurs while the @@ -938,11 +929,11 @@ 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> +</p> -<H2> GLU </H2> +<h2> GLU </h2> -<P> +<p> Jogl contains support for the GLU (OpenGL Utility Library) version 1.3. Jogl originally supported GLU by wrapping the C version of the @@ -952,115 +943,99 @@ pure Java port is enabled by default, and addresses stability issues on certain Linux distributions as well as the lack of native GLU 1.3 support on the Windows platform. In case of problems with the Java port, the C version of the GLU library may be used by specifying the -system property <CODE>-Djogl.glu.nojava</CODE> on the command +system property <code>-Djogl.glu.nojava</code> on the command line. All of the same functionality is exposed with both the Java and C versions of the GLU library; currently NURBS support is the only missing feature on both sides. If you run into problems with the Java port of the GLU library please file a bug using the Issue Tracker on the Jogl home page. -</P> -<P> +</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 +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> -<P> +</p> +<p> N.B: Some GLU features are only implemented in the subclass GLUgl2. -</P> +</p> -<H2> More Resources </H2> +<h2> More Resources </h2> -<P> +<p> +Our <a href="../../../wiki/">Wiki pages</a>, +have a look at the +<a href="../../../wiki/index.php/Jogl_Tutorial">Jogl Tutorial</a> resource listing. +</p> -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 +<p> + +The <a href="http://forum.jogamp.org/">JOGL forum</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 threads contain a lot of useful information (which still needs to be distilled into documentation). -</P> -<P> +</p> +<p> -The <A HREF="http://download.java.net/media/jogl/demos/www/">JOGL demos</A> provide +The <a href="../../../jogl-demos/www/">JOGL demos</a> provide several examples of usage of the library. -</P> -<P> - -Pepijn Van Eeckhoudt, Kevin Duling and Abdul Bezrati have done <A -HREF="http://pepijn.fab4.be/software/nehe-java-ports/">JOGL ports of -many of the the NeHe demos</A>. These are small examples of various -pieces of OpenGL functionality. See also the <A -HREF="http://nehe.gamedev.net/">NeHe web site</A>. - -</P> -<P> +</p> +<p> -Pepijn also did a <A -HREF="http://www.glexcess.com/files/glexcess.jar">JOGL port</a> of -Paolo Martella's <A HREF="http://www.glexcess.com/">GLExcess</A> -demo. To see the news update about this port, go to the main GLExcess -site and scroll down. +Pepijn Van Eeckhoudt, Kevin Duling and Abdul Bezrati have done <a +href="http://pepijn.fab4.be/software/nehe-java-ports/">JOGL ports of +many of the the NeHe demos</a>. These are small examples of various +pieces of OpenGL functionality. See also the <a +href="http://nehe.gamedev.net/">NeHe web site</a>. -</P> -<P> +</p> -Gregory Pierce's <A -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> -<P> +For release information about the JOGL library, please see the +<a href="../../../wiki/index.php/Jogamp_Versioning_and_Releases">Jogamp Versioning and Release</a>. -For release information about the JOGL library, please see the <A -HREF="http://javagaming.org/forums/index.php?topic=1596.0">JOGL Release -Information</A> thread on the JOGL forum on javagaming.org. +</p> +<p> -</P> -<P> +Please post on the <a href="http://forum.jogamp.org/">JOGL forum</a> +if you have a resource you'd like to add to this documentation +or like to edit the <a href="../../../wiki/index.php">Wiki Pages</a> yourself. -Please post on the JOGL forum if you have a resource you'd like to add -to this documentation. +</p> -</P> +<h2> Platform Notes </h2> -<H2> Platform Notes </H2> +<h3> All Platforms </h3> -<H3> All Platforms </H3> - -<P> +<p> The following issues, among others, are outstanding on all platforms: -</P> +</p> -<UL> +<ul> -<LI> A few remaining stability issues, mostly on older graphics cards. +<li> A few remaining stability issues, mostly on older graphics cards.</li> -<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> -</UL> +<h3> Windows </h3> -<H3> Windows </H3> - -<P> +<p> For correct operation, it is necessary to specify the system property -<CODE>-Dsun.java2d.noddraw=true</CODE> when running JOGL applications +<code>-Dsun.java2d.noddraw=true</code> when running JOGL applications on Windows; this system property disables the use of DirectDraw by Java2D. There are driver-level incompatibilities between DirectDraw and OpenGL which manifest themselves as application crashes, poor @@ -1070,174 +1045,51 @@ same application, not even just in the same window, so disabling Java2D's DirectDraw pipeline and forcing it to use its GDI pipeline is the only way to work around these issues. Java Web Start applications may set this system property by adding the following line to the -<CODE><resources></CODE> section of the JNLP file: <PRE> -<property name="sun.java2d.noddraw" value="true"/> </PRE> - -</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 -not reproducible at the time of this writing on desktop Radeon -hardware or older ATI mobile chips. The bug is documented in <A -HREF="https://jogl.dev.java.net/issues/show_bug.cgi?id=166">JOGL Issue -166</A> and a bug has been filed with ATI. You can confirm the -presence of the bug either with the test case in that bug report or by -simply running the Gears demo; if the process size grows over time in -the Task Manager, the memory leak is present on your hardware. For the -time being, you can work around this memory leak by specifying the -system property <CODE>-Djogl.GLContext.nofree</CODE> on the command -line when launching your JOGL applications. There is no good -general-purpose workaround for this bug which behaves well on all -hardware. - -</P> - -<H3> Linux </H3> - -<P> - -The Sun JDK "compatibility" RPMs (java-1.5.0-sun-compat, -java-1.6.0-sun-compat) provided by jpackage.org are incompatible with -JOGL. These RPMs symlink an internal JDK directory to /usr/lib, which -overrides how both NVidia and ATI currently provide their drivers to -some Linux distributions, which is through an override in -/etc/ld.so.conf (actually, in /etc/ld.so.conf.d). The implicit -presence of /usr/lib on LD_LIBRARY_PATH forces the /usr/lib/libGL.so.1 -version of OpenGL to be used, which is typically Mesa and which will -provide only software rendering. - -</P> -<P> - -Unfortunately the JPackage maintainers have so far been unreceptive to -changing their installation mechanism; see <a -href="https://www.zarb.org/pipermail/jpackage-discuss/2007-January/010871.html">this -mailing list posting</a>. Until this is resolved, we strongly -discourage the use of the JPackage installers for the Sun JDK. -Instead, download the JRE or JDK installers directly from Sun's -website. - -</P> -<P> - -Archived forum postings illustrating this problem are <a -href="http://www.javagaming.org/forums/index.php?topic=15610.0">here</a> -and <a -href="http://www.javagaming.org/forums/index.php?topic=16105.0">here</a>. - -</P> - -<H3> Solaris, Linux (X11 platforms) </H3> - -<P> - -Support has been added to the JOGL library for allowing multiple -threads to each have an OpenGL context current simultaneously, for -example to implement multi-head CAVE-like environments. Normally a -global AWT lock is held between calls to GLContext.makeCurrent() / -release() for on-screen heavyweight contexts (for example, those -associated with a Canvas or GLCanvas). We have found this to be -necessary for stability purposes on all supported X11 platforms, even -with relatively robust drivers such as those from NVidia. - -</P> -<P> - -To enable multiple GLContexts to be made current simultaneously on X11 -platforms, specify the command line argument -<CODE>-Djogl.GLContext.optimize</CODE> when starting the JVM. Note -that this may incur robustness problems, in particular when resizing -or moving windows. We have also found that ATI's proprietary drivers -do not work at all with this flag, apparently because they cause GLX -tokens to be sent to the X server for various GL calls even for direct -contexts. For this reason if the GLX vendor is ATI then this flag -currently has no effect. - -</P> - -<H3> Mac OS X </H3> - -<P> - -There are some problems with visual artifacts and stability problems -with some of the Jogl demos on Mac OS X. It appears that at least some -of these problems are due to bugs in Apple's OpenGL support. Bugs have -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 -implementation, can be used either with the provided GLCanvas widget -or with the Cocoa NSOpenGLView. In order to use it with Cocoa the -following steps should be taken: - -<UL> - -<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> - -<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. </LI> +<code><resources></code> section of the JNLP file: <code> +<property name="sun.java2d.noddraw" value="true"/> </code> -</UL> +</p> -<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. +<h3> X11 Platforms (Linux, Solaris, ..) </h3> -</P> -<P> +<h3> Mac OS X </h3> The following issues remain with the Mac OS X port: -<UL> +<ul> -<LI> Due to the mechanism by which the Cocoa graphics system selects +<li> Due to the mechanism by which the Cocoa graphics system selects 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. </LI> - -</UL> +and the GLCapabilitiesChooser is ignored. </li> -</P> +</ul> -<H2> Version History </H2> +<h2> Version History </h2> -<P> +<p> -JOGL's version history can be found online in the <a -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://javagaming.org/forums/index.php?topic=4217.0">"JOGL 1.1 -released"</a>. +JOGL's version history can be found online in the +<a href="../../../wiki/index.php/Jogamp_Versioning_and_Releases">Jogamp Versioning and Release</a>. -</P> +</p> -<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>. +The whole evolution of JOGL is described <a href="../Overview-OpenGL-Evolution-And-JOGL.html">here</a>. -</P> +</p> </div> </div> <div id="footer"> <div id="footer_left"> - <span xmlns:dc="http://purl.org/dc/elements/1.1/" property="dc:title">JogAmp.org</span> - by <a xmlns:cc="http://creativecommons.org/ns#" href="http://jogamp.org" property="cc:attributionName" rel="cc:attributionURL">http://jogamp.org</a> + <span>JogAmp.org</span> + by <a href="../../">http://jogamp.org</a> is licensed under a <br/> - <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>. + <a href="http://creativecommons.org/licenses/by/3.0/us/">Creative Commons Attribution 3.0 License</a>. </div> </div> </div> |