jogl.git - JOGL repository on http://jogamp.org/ ;

	Commit message (Collapse)	Author	Age	Files	Lines
*	Fixed typo	Kenneth Russel	2006-08-29	1	-1/+1
\| \| \| \|	git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@900 232f8b59-042b-4e1e-8c03-345bb8c30851
*	Moved TCK license to a separate file on Travis's behalf and changed	Kenneth Russel	2006-08-29	1	-897/+33
\| \| \| \| \| \| \|	tck-license.html on his request git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@899 232f8b59-042b-4e1e-8c03-345bb8c30851
*	Added tck-license.html on Travis's request	Kenneth Russel	2006-08-26	1	-0/+903
	git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@895 232f8b59-042b-4e1e-8c03-345bb8c30851

<!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" /> <link href="../../../style.css" rel="stylesheet" type="text/css"/> <title>JOGL Userguide</title> </head> <body> <div id="container"> <div id="header"> <div id="slogan">JOGL Userguide</div> <div id="logo"><a href="http://jogamp.org/">JOGL Userguide</a></div> </div> <div id="menu"> <ul> <li><a href="http://jogamp.org/">Home</a></li> <li><a href="../../../gluegen/www/">Gluegen</a></li> <li><a href="../../../joal/www/">JOAL</a></li> <li><a href="../../../jocl/www/">JOCL</a></li> <li><a href="../../../jogl/www/">JOGL</a></li> <li><a href="../../../demos/www/">Demos</a></li> <li><a href="../../../wiki/">Wiki</a></li> <li><a href="../../../deployment/jogl-next/javadoc_public/">JavaDoc</a></li> </ul> </div> <div id="main"> <div id="text" class="fill"> <b><font color="red">WARNING: This document is under review.</font></b> <br/> <br/> <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 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 and a native windowing toolkit independent of AWT called NEWT. </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 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 jogamp.org project. </p> <h2> <a name="access">Accessing JOGL</a> </h2> <h3> <a name="building">Building the source tree</a> </h3> <p> Most developers using JOGL will download the most current <a href="../../../deployment/jogamp-current/archive/">release build</a>. Separate instructions are available on how to <a href="../HowToBuild.html">build the source tree</a>. </p> <h3> <a name="localinstallation">Local Installation</a> </h3> See <a href="../deployment/JOGL-DEPLOYMENT.html">deployment</a> for deployment details. <h4> <a name="archivefiles">7zip Archives</a> </h4> <p> 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> <h4> <a name="jarfilesandclasspath">JAR Files & CLASSPATH</a> </h4> 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. <h5> <a name="atomicjarfiles">Atomic JAR files</a> </h5> <p> 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> <h4> <a name="automatednativelibraryloading">Automated Native Library Loading</a> </h4> <p> JOGL 2.0 has a brand new feature allowing to automatically extract the proper native libraries required to use JOGL <a href="../deployment/JOGL-DEPLOYMENT.html#NativeJARFiles">from JARs containing them</a> 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 <a href="../deployment/JOGL-DEPLOYMENT.html#NApplets">as NApplets</a> to utilize the native library JAR files the same way Webstart/JNLP does. </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> <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> 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> <h4> <a name="traditionallibraryloading">Traditional Native Library Loading</a> </h4> <p> 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> <h4> <a name="ideusers">Settings for IDE's users</a> </h4> <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 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> <h4> <a name="badpractice">Bad practice</a> </h4> <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> 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> <h4> <a name="notefordebianusers">Note for Debian Linux users</a> </h4> <p> DEB packages are available for this distribution on its official repositories. </p> <h3> <a name="onlinedeployment">Online Deployment</a> </h3> 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> <h4> <a name="applets">Applets</a> </h4> <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> 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> <h4> <a name="jnlpwebstart">JNLP / Webstart</a> </h4> <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> <a name="joglapi">Using the JOGL API</a> </h2> <h3> <a name="gldrawableandglcontext">GLDrawable and GLContext</a> </h3> <p> 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 these abstractions, a context is always associated with exactly one drawable. </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> <h3> GLProfile </h3> <p> 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> <h3> Creating a GLAutoDrawable </h3> <p> 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 lightweight widget which supports hardware acceleration but which is not as fast as the GLCanvas because it typically reads back the frame buffer in order to draw it using Java2D. The GLJPanel is intended to provide 100% correct Swing integration in the circumstances where a GLCanvas can not be used. See <a href = "http://java.sun.com/products/jfc/tsc/articles/mixing/">this article</a> on <a href = "http://java.sun.com/products/jfc/tsc/">The Swing Connection</a> for more information about mixing lightweight and heavyweight widgets. See also the section on "Heavyweight and Lightweight Issues" below. Recent work in the Mustang release of the 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> 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> <li> access to the GL object for calling OpenGL routines</li> <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> <li> AWT- and Swing-independent abstractions for getting and setting the size of the widget and adding and removing event listeners</li> </ul> <p> 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 and GLWindow only). </p> <p> A GLCapabilities object specifies the OpenGL parameters for a newly-created widget, such as the color, alpha,, z-buffer and accumulation buffer bit depths and whether the widget is 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> An application can override the default pixel format selection algorithm by providing a GLCapabilitiesChooser to the GLCanvas or GLJPanel constructor. (Not all platforms support the GLCapabilitiesChooser mechanism, however; it may be ignored, in particular on Mac OS X where pixel format selection is very different than on other platforms.) The chooseCapabilities method will be called with all of the available pixel formats as an array of GLCapabilities objects, as well as the index indicating the window system's recommended choice; it should return an integer index into this 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> 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. In order to enable this, set up your GLCapabilities object with a non-zero alpha depth (a common value is 8 bits) and call setOpaque(false) on the GLJPanel once it has been created. Java2D 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> <h3> Writing a GLEventListener </h3> <p> Applications implement the GLEventListener interface to perform OpenGL drawing via callbacks. When the methods of the GLEventListener are 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> 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 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 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 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. </p> <p> Note also that the GLEventListener should be added to the GLAutoDrawable before the GLAutoDrawable is shown or rendered to for the first time. If this is not done, it is possible that the init() method will not be called on the GLEventListener. JOGL does not 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> 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 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> 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> 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 AWT toolkit make it difficult to reason about which threads certain operations are occurring on, and if the GL object is stored in a field it is unfortunately too easy to accidentally make OpenGL calls from a 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> <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> Performance </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> 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 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> 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> class MyListener implements GLEventListener { public void init(GLDrawable drawable) { drawable.setGL(new DebugGL(drawable.getGL())); // ... } // ... } </pre> <p> Note that the GLAutoDrawable.setGL() method simply calls setGL() on the default OpenGL context created by the GLAutoDrawable, so sophisticated applications creating their own OpenGL contexts can use