Difference between revisions of "Jogl FAQ"

From JogampWiki
Jump to: navigation, search
(Why you should learn direct from start the modern OpenGL (programmable and shader based) over the deprecated fixed function pipeline)
 
(36 intermediate revisions by 5 users not shown)
Line 3: Line 3:
 
__TOC__
 
__TOC__
  
== Get the Source Code ==
+
== [[Jogamp Versioning and Releases|Versioning and Releases]] ==
 
+
Create a local copy/branch of the git repository,
+
either anonymous:
+
 
+
* git clone git://github.com/sgothel/gluegen.git gluegen
+
* git clone git://github.com/sgothel/jogl.git jogl
+
* git clone git://github.com/sgothel/jogl-demos.git jogl-demos
+
 
+
or via SSH and your user credential, so you can easily push back your
+
changes to the github server:
+
 
+
* git clone git@github.com:username/gluegen.git gluegen
+
* git clone git@github.com:username/jogl.git jogl
+
* git clone git@github.com:username/jogl-demos.git jogl-demos
+
 
+
== How to participate and use git ==
+
 
+
Yes, gluegen, jogl and all the stuff has been [http://blog.jausoft.com/2009/07/08/svn-to-git-migration-1/ migrated to git],
+
thanks to the great git toolchain.
+
 
+
In the past we were using a centralized repository only, ''SVN'',
+
and you really needed access to it as a developer.
+
 
+
Thanks to the distributed nature of git, this is no more a real issue.
+
The only thing left is to provide a media to offer your branch to one of us,
+
this can be via [http://www.kernel.org/pub/software/scm/git/docs/everyday.html#Individual%20Developer%20%28Participant%29 email], [http://weblog.masukomi.org/wp-content/uploads/2008/03/config_remote_repo.svg http],  [http://kernel.org/pub/software/scm/git/docs/howto/use-git-daemon.txt git], ssh, whatever you wish - it's easy.
+
For bigger projects maintained in a branch or if you don't have your own public server
+
to offer yours, ''we are pleased to grant you write access'' to our repository!
+
 
+
However, '''don't just modify the master branch without our permission''',
+
or any other existing branch which is not assigned to you!
+
''We will just trust you here'', but if you misbehave, your privileges will be removed.
+
Instead, '''create a branch of your own and push it to the server''', then you will ask
+
one of us to pull your branch, which we will verify and merge, if it's fine. Thanks to git, this is so easy now.
+
And this is the current way [http://whygitisbetterthanx.com/#any-workflow how you collaborate] using a [http://whygitisbetterthanx.com/#distributed distributed SCM].
+
 
+
== How to develop Cross-Device Applications ==
+
First you have to pick your lowest common denominator of an OpenGL profile, ie OpenGL ES1 or ES2.
+
For either we offer an intersecting desktop GL profile, GL2ES1 or GL2ES2.
+
Use the latter while creating your GLCapabilities.
+
Build and run your application with the minimum GL profile JARS, e.g. on the desktop use:
+
 
+
~/jogl-demos> . ./setenv-jogl.sh JOGL_GL2ES12_MIN ../jogl/build
+
 
+
Here you are on a Unix platform (not Window) and your common build subdirectory is 'build'.
+
''jogl-demos/setenv-jogl.sh'' is provided within ''jogl-demos'', which itself utilizes ''jogl/etc/profile.jogl''.
+
 
+
This uses the GlueGen/JOGL JARS:
+
* gluegen-rt.jar
+
* nativewindow.core.jar
+
* jogl.core.jar
+
* jogl.util.jar
+
* jogl.gl2es12.x11.jar
+
* jogl.util.fixedfuncemu.jar
+
* newt.core.jar
+
* newt.ogl.jar
+
 
+
On a mobile device using CVM, you would use:
+
* gluegen-rt-cdc.jar
+
* nativewindow.core.cdc.jar
+
* jogl.core.cdc.jar
+
* jogl.util.cdc.jar
+
* jogl.egl.cdc.jar
+
* jogl.gles1.cdc.jar or jogl.gles2.cdc.jar
+
* jogl.util.fixedfuncemu.cdc.jar
+
* newt.core.cdc.jar
+
* newt.ogl.cdc.jar
+
 
+
Now, the same Java application shall run on all devices, desktop and mobile.
+
See ''demos.es1.RedSquare'' of the ''jogl-demos'' repository.
+
 
+
On the desktop you may run the ES1 demo:
+
 
+
~/jogl-demos> sh java-run-newt.sh demos.es1.RedSquare -GL2ES1
+
 
+
and the output is:
+
null RedSquare.run() 0
+
User screen size 0x0
+
Detected screen size 1920x1200
+
GLProfile[GL2ES1/GL2ES12] Entering initialization
+
GLProfile[GL2ES1/GL2ES12] GL Profile: GLProfile[GL2ES1/GL2ES12]
+
GLProfile[GL2ES1/GL2ES12] GL:com.sun.opengl.impl.gl2es12.GL2ES12Impl@b815859
+
GLProfile[GL2ES1/GL2ES12] GL_VERSION=3.0.0 NVIDIA 185.18.14
+
GLProfile[GL2ES1/GL2ES12] GL_EXTENSIONS: ..
+
  
 
== What are the Runtime OpenGL Version Requirements ? ==
 
== What are the Runtime OpenGL Version Requirements ? ==
Line 104: Line 20:
  
 
'''JOGL requires at least an OpenGL version 1.1''',
 
'''JOGL requires at least an OpenGL version 1.1''',
due to it's dynamical function binding starting with OpenGL 1.2.
+
due to its dynamical function binding starting with OpenGL 1.2.
  
== Bugreports & Testing ==
+
== Use and test Autobuilds ==
For all bug reports, please add the following information to your email:
+
* Test case
+
** Source code, or reference to it
+
** Invocation command-line
+
* Platform
+
** OS & version
+
** Architecture
+
** Java version (java -version)
+
* JOGL Source/build versions
+
** GIT revision incl. URL and/or
+
** Autobuild version (date, filename and URL)
+
** Exceptions, stdout/stderr log file
+
  
If possible, please add the following system properties to enable DEBUG logging:
+
I like to summarize how to manually test the JOGL autobuilds, starting with 2010-11-10.
''-Dnewt.debug=all -Dnativewindow.debug=all -Djogl.debug=all''
+
  
For example:
+
You can fetch autobuilds from one the [[Jogamp Versioning and Releases#Autobuilds|autobuild folder]].
  
java -Djava.awt.headless=true -Dnewt.debug=all -Dnativewindow.debug=all \
+
=== Runtime Version Check ===
-Djogl.debug=all demos.es2.RedSquare 2>&1 | tee RedSquare.report.log
+
 
+
To test applets use the jcontrol panel or edit ''~/.java/deployment.properties'' directly and
+
 
+
* Add JRE Arguments: <pre>-Djava.awt.headless=true -Dnewt.debug=all -Dnativewindow.debug=all -Djogl.debug=all</pre>
+
* Enable logging/trace
+
* Show the console window, or just use th latest log-file in <pre>~/.java/deployment/log/</pre>
+
  
 +
The simplest verification of a JOGL build is to use the
 +
[[Jogamp Versioning and Releases#Runtime Version Check|runtime version check]]
 +
and the [[Jogamp Versioning and Releases#Runtime Debug Logs|runtime debug test]].
  
== Test Autobuilds & Shell Scripts ==
+
See [[#Bugreports & Testing]].
I like to summarize how to manually test the JOGL autobuilds, starting with 2009-07-02.
+
  
The general nightly download sites are
+
=== JOGL Demos ===
* http://download.java.net/media/jogl/builds/nightly/
+
  
 
Let’s assume we are in the test directory ‘test’, from which we operate from this point.
 
Let’s assume we are in the test directory ‘test’, from which we operate from this point.
  
* Get [http://download.java.net/media/jogl/builds/nightly/jogl-demos.zip jogl-demos.zip]. Extract the archive, i.e. <pre>unzip jogl-demos.zip</pre>
+
* Get [http://jogamp.org/deployment/jogamp-current/archive/jogl-demos.7z jogl-demos.7z]. Extract the archive, i.e. [http://www.7-zip.org/7z.html <pre>7z x jogl-demos.7z</pre>]
  
* Get [http://download.java.net/media/jogl/builds/nightly/ jogl-2.0-pre-20090702-linux-amd64.zip]. In case we have build a reference implementation (RI) the substring ‘pre-yyyymmdd-’ will be dropped. Replace the version 2.0 with the latest available and the OS/arch linux-amd64 with your test platform. Extract the archive, ie <pre>unzip jogl-2.0-pre-20090702-linux-amd64.zip</pre>. Create a symbolic link or rename the archive directory from ''jogl-2.0-pre-20090702-linux-amd64'' to ''jogl'', ie <pre>ln -s jogl-2.0-pre-20090702-linux-amd64 jogl</pre>.
+
* Get [http://jogamp.org/deployment/jogamp-current/archive/jogamp-all-platforms.7z jogamp-all-platforms.7z]. Extract the archive, i.e. [http://www.7-zip.org/7z.html <pre>7z x jogamp-all-platforms.7z</pre>] Create a symbolic link or rename the archive directory from ''jogamp-all-platforms'' to ''jogl'', ie <pre>ln -s jogamp-all-platforms jogl</pre>.
 
* If you like to test the binding to NV’s Cg, [http://developer.nvidia.com/object/cg_download.html download and install]
 
* If you like to test the binding to NV’s Cg, [http://developer.nvidia.com/object/cg_download.html download and install]
  
Line 183: Line 80:
 
For this case I would recommend the native ES2 implementation from imageon SDK_OGLES2_LINUX_PCEMULATION_2.02.22.0756.
 
For this case I would recommend the native ES2 implementation from imageon SDK_OGLES2_LINUX_PCEMULATION_2.02.22.0756.
  
 +
== Bugreports & Testing ==
 +
For all bug reports, please add the following information to
 +
your bug report:
 +
* [[#JOGL, Platform and OpenGL Version]]
 +
* [[#Detailed Debug Log]]
 +
* your email
  
== How to use JOGL in Applets (part 1) ==
+
Please use one of the [{{SERVER}}/deployment/archive/master/?C=M;O=D latest aggregated archives],
A Java Applet using JOGL may utilize 2 methods
+
as described in [[Downloading and installing JOGL#Downloading the latest aggregated autobuild|this section]].
* [https://jdk6.dev.java.net/plugin2/jnlp/ New  JNLP Applet]
+
* [https://applet-launcher.dev.java.net/ Applet-Launcher]
+
  
Standard JNLP Applets are supported starting with Java 6u14, however, if you run MacOSX or an older version of  Java,
+
Using our [{{SERVER}}/bugzilla/ bug tracking system] is strongly recommended.<br>
you may need to use the Applet-Launcher.
+
We also have a [[SW Tracking|bug overview page]] available via this wiki.
  
Below we utilize both, the standard JNLP mechanism of 6u14 as the default,
+
'''Please add all subsequent information as stated below to your bugreport''',<br>
or falling back to our  Applet-Launcher.
+
otherwise we are not capable to hunt it down for you and us.
  
You will find the JNLP file applet-gears.jnlp further below, which is being used in case of a JNLP launch,
+
=== JOGL, Platform and OpenGL Version ===
otherwise it is ignored and the archive tags are being used, hence the applet-launcher will be started.
+
  
The below demo is [http://download.java.net/media/jogl/demos/www/applettest-jnlp.html online here].
+
Please perform a [[Jogamp Versioning and Releases#Runtime Version Check|runtime version check]],
 +
which provides the following information:
  
Note: It is important for the startup time to have the same JVM arguments in the applet tags,
+
* Platform
as well as within the JNLP applet description, here see property sun.java2d.noddraw.
+
** OS & version
Only if JVM arguments of the JNLP applet description are satisfied by the applet tag’s JVM,
+
** Architecture
the plugin will not need to start a new JVM. OF course, the applet tag’s JVM spec may exceed the JNLP applet’s one.
+
** OpenGL Version
 +
** Java version (java -version)
 +
* JOGL version
 +
** GIT revision
 +
** Autobuild version
  
Note: A bug on MacOSX is known, launching 2 JOGL applets in 2 tabs.
+
Send us the resulting file <pre>test.log</pre>.
 +
 
 +
=== Detailed Debug Log ===
 +
 
 +
Please perform a [[Jogamp Versioning and Releases#Runtime Debug Logs|runtime debug test]].
 +
 
 +
Send us the resulting file <pre>test_dbg.log</pre>.
 +
 
 +
=== Detailed Bug Information ===
 +
 
 +
* Your Test case
 +
** Source code, [{{SERVER}}/git/?p=jogl.git;a=blob;f=src/junit/com/jogamp/test/junit/newt/TestGLWindows00NEWT.java <b>a junit test</b>] would be best.
 +
** Invocation command-line
 +
** Exceptions, stdout/stderr log file
 +
 
 +
==== Applications ====
 +
 
 +
Adding a comprehensive [{{SERVER}}/git/?p=jogl.git;a=blob;f=src/junit/com/jogamp/test/junit/newt/TestGLWindows00NEWT.java <b>junit test</b>]
 +
would help us the most to reproduce the bug, to discuss it with you and to achieve a good response time.<br>
 +
You may add it to your [{{SERVER}}/bugzilla/ bug report] directly or better, give us your [[How to Contribute|git repository pull request]].
 +
 
 +
If possible, please add the following system properties to enable DEBUG logging:
 +
''-Dnewt.debug=all -Dnativewindow.debug=all -Djogl.debug=all''
 +
 
 +
For example:
 +
 
 +
java -Djava.awt.headless=true -Dnewt.debug=all -Dnativewindow.debug=all \
 +
-Djogl.debug=all demos.es2.RedSquare 2>&1 | tee RedSquare.report.log
 +
 
 +
Attach the log file to your bug report ..
 +
 
 +
==== Applets and Java Webstart ====
 +
 
 +
To test ''applets'' and ''javaws'' use
 +
* the jcontrol panel
 +
* or edit the ''java properties file'':
 +
** Unix: ''~/.java/deployment.properties''
 +
** Windows: ''\Users\<username>\AppData\LocalLow\Sun\Java\Deployment\deployment.properties''
 +
 
 +
where you add the following JRE Arguments. The ''jnlp'' prefix supports the ''javaws'' launch method.
 +
* jcontrol panel: <pre>-Djnlp.newt.debug=all -Djnlp.nativewindow.debug=all -Djnlp.jogl.debug=all</pre>
 +
* properties file: <pre>deployment.javaws.jre.0.args=-Djnlp.newt.debug\=all -Djnlp.nativewindow.debug\=all -Djnlp.jogl.debug\=all</pre> Of course you have to add these arguments to all of your JRE lines, ie ''0'' and ''1'', etc, if they exist.
 +
 
 +
You also want to
 +
* Enable logging/trace
 +
* Show the console window, or just use the latest log files in  
 +
** Unix: ''~/.java/deployment/log/'', or
 +
** Windows: ''\Users\<username>\AppData\LocalLow\Sun\Java\Deployment\log\''
  
 +
Hence the ''java properties file'' (see location above) shall contain the following:
 
<pre>
 
<pre>
<applet code="org.jdesktop.applet.util.JNLPAppletLauncher"
+
...
      width=600
+
deployment.log=true
      height=400
+
deployment.trace=true
      archive="http://download.java.net/media/applet-launcher/applet-launcher.jar,
+
deployment.javaws.jre.0.args=-Djnlp.newt.debug\=all -Djnlp.nativewindow.debug\=all -Djnlp.jogl.debug\=all
              http://download.java.net/media/jogl/jsr-231-2.x-webstart/nativewindow.all.jar,
+
deployment.javaws.jre.1.args=-Djnlp.newt.debug\=all -Djnlp.nativewindow.debug\=all -Djnlp.jogl.debug\=all
              http://download.java.net/media/jogl/jsr-231-2.x-webstart/jogl.all.jar,
+
...
              http://download.java.net/media/gluegen/webstart-2.x/gluegen-rt.jar,
+
              http://download.java.net/media/jogl/jsr-231-2.x-demos-webstart/jogl-demos.jar">
+
  <param name="codebase_lookup" value="false">
+
  <param name="subapplet.classname" value="demos.applets.GearsApplet">
+
  <param name="subapplet.displayname" value="JOGL Gears Applet">
+
  <param name="noddraw.check" value="true">
+
  <param name="progressbar" value="true">
+
  <param name="jnlpNumExtensions" value="1">
+
  <param name="jnlpExtension1"
+
          value="http://download.java.net/media/jogl/jsr-231-2.x-webstart/jogl-core.jnlp">
+
  <param name="java_arguments" value="-Dsun.java2d.noddraw=true">
+
  <param name="jnlp_href" value="applet-gears.jnlp">
+
</applet>
+
 
</pre>
 
</pre>
  
Where the referenced JNLP file applet-gears.jnlp looks as follow:
+
Best practice:
 +
* Close your browser and ensure no JVM is running anymore
 +
* Delete all old log files in above log file folder
 +
* Start browser and the test applet
 +
* Close browser after test .. maybe after a while if you see nothing
 +
* Attach all new generated *.trace files to your bug report ..
  
<pre>
+
== Get the Source Code ==
<?xml version="1.0" encoding="utf-8"?>
+
<jnlp href="applet-gears.jnlp">
+
  <information>
+
    <title>JOGL JNLP Applet Gears Demo</title>
+
    <vendor>Sun Microsystems, Inc.</vendor>
+
    <homepage href="http://jogl-demos.dev.java.net/"/>
+
    <description>Gears Demo</description>
+
    <description kind="short">Brian Paul's Gears demo ported to Java and JOGL.</description>
+
    <offline-allowed/>
+
  </information>
+
  
    <resources>
+
Create a local copy/branch of a [[Jogamp SCM Repositories|git repository]]
      <j2se href="http://java.sun.com/products/autodl/j2se" version="1.4+"/>
+
either anonymous:
      <property name="sun.java2d.noddraw" value="true"/>
+
      <jar href="http://download.java.net/media/jogl/jsr-231-2.x-demos-webstart/jogl-demos.jar" main="true"/>
+
      <jar href="http://download.java.net/media/jogl/jsr-231-2.x-demos-webstart/jogl-demos-util.jar"/>
+
      <extension name="jogl-all-awt" href="http://download.java.net/media/jogl/jsr-231-2.x-webstart/jogl-all-awt.jnlp" />
+
    </resources>
+
  
  <applet-desc
+
* git clone git://github.com/sgothel/gluegen.git gluegen
      name="Gears-Applet"
+
* git clone git://github.com/sgothel/jogl.git jogl
      main-class="demos.applets.GearsApplet"
+
* git clone git://github.com/sgothel/jogl-demos.git jogl-demos
      width="640"
+
 
      height="480">
+
or via SSH and your user credential, so you can easily push back your
  </applet-desc>
+
changes to the github server:
</jnlp>
+
 
</pre>
+
* git clone git@github.com:username/gluegen.git gluegen
 +
* git clone git@github.com:username/jogl.git jogl
 +
* git clone git@github.com:username/jogl-demos.git jogl-demos
 +
 
 +
== [http://jogamp.org/jogl/doc/HowToBuild.html How to build] ==
 +
 
 +
== [[How to Contribute]] ==
 +
 
 +
== Common Runtime Problems ==
 +
 
 +
=== X11: OpenGL library is not picked up correctly,  no OpenGL available ===
 +
 
 +
In case you are running a DRI machine, eg ATI's proprietary driver or
 +
an open source one, you may need to ensure that the environment variable '''LIBGL_DRIVERS_PATH'''
 +
is set properly.
 +
 
 +
I ran into this while testing the 32bit builds on a 64bit machine
 +
as a different user. Since '''LIBGL_DRIVERS_PATH''' is only setup for the desktop user
 +
on Ubuntu, some ''/etc/X11/Xsession.d/'' script, I couldn't get a GL context to work.
 +
 
 +
So I had to set mine to the value:
 +
export LIBGL_DRIVERS_PATH=/usr/lib/fglrx/dri:/usr/lib32/fglrx/dri
 +
 
 +
See also:
 +
[https://bugs.launchpad.net/ubuntu/+source/fglrx-installer/+bug/250944 Ubuntu fglrx bug entry]
 +
 
 +
== How to develop Cross-Device Applications ==
 +
First you have to pick your lowest common denominator of an OpenGL profile, ie OpenGL ES1 or ES2.
 +
For either we offer an intersecting desktop GL profile, GL2ES1 or GL2ES2.
 +
Use the latter while creating your GLCapabilities.
 +
Build and run your application with the minimum GL profile JARS, e.g. on the desktop use:
 +
 
 +
~/jogl-demos> . ./setenv-jogl.sh JOGL_GL2ES12_MIN ../jogl/build
 +
 
 +
Here you are on a Unix platform (not Window) and your common build subdirectory is 'build'.
 +
''jogl-demos/setenv-jogl.sh'' is provided within ''jogl-demos'', which itself utilizes ''jogl/etc/profile.jogl''.
 +
 
 +
This uses the GlueGen/JOGL JARS:
 +
* gluegen-rt.jar
 +
* jogl-all.jar
 +
 
 +
This uses the GlueGen/JOGL atomic JARS for minimal deployment:
 +
* gluegen-gl.jar
 +
* nativewindow-core.jar
 +
* jogl-core.jar
 +
* jogl-util.jar
 +
* jogl-util-fixedfuncemu.jar
 +
* newt-core.jar
 +
* newt-awt.jar
 +
 
 +
Please check [http://jogamp.org/jogl/doc/deployment/JOGL-DEPLOYMENT.html JOGL Deployment] also.
 +
 
 +
Now, the same Java application shall run on all devices, desktop and mobile.
 +
See ''demos.es1.RedSquare'' of the ''jogl-demos'' repository.
 +
 
 +
On the desktop you may run the ES1 demo:
 +
 
 +
~/jogl-demos> sh java-run-newt.sh demos.es1.RedSquare -GL2ES1
 +
 
 +
and the output is:
 +
null RedSquare.run() 0
 +
User screen size 0x0
 +
Detected screen size 1920x1200
 +
GLProfile[GL2ES1/GL2ES12] Entering initialization
 +
GLProfile[GL2ES1/GL2ES12] GL Profile: GLProfile[GL2ES1/GL2ES12]
 +
GLProfile[GL2ES1/GL2ES12] GL:com.sun.opengl.impl.gl2es12.GL2ES12Impl@b815859
 +
GLProfile[GL2ES1/GL2ES12] GL_VERSION=3.0.0 NVIDIA 185.18.14
 +
GLProfile[GL2ES1/GL2ES12] GL_EXTENSIONS: ..
 +
 
 +
== Is my phone, embedded device or OpenGL ES driver supported by JogAmp? ==
 +
 
 +
* [[OpenGL ES Driver compatibility matrix]]
 +
 
 +
== How to use JOGL in Applets ==
 +
 
 +
See:
 +
* [[Using JOGL in a Java applet|Using JOGL in a Java Applet]]
 +
* [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html#NApplets JOGL Deployment as an NApplet]
  
 
== What is ''Newt's'' Threading Model for native window events ? ==
 
== What is ''Newt's'' Threading Model for native window events ? ==
Line 264: Line 271:
 
is the event dispatch thread (EDT) model.
 
is the event dispatch thread (EDT) model.
  
It's introduction was necessary to allow a 'peace of mind',
+
Newt's EDT impl. creates one EDT per NEWT Display,
 +
as the Display is a unique abstraction of a graphics device connection
 +
serving all of it's Screens and Windows.
 +
 
 +
EDT is being used to
 +
* dispatch native Screen and Window events
 +
* lifecycle Screen and Window functionality
 +
** create / destroy
 +
** reparenting
 +
** native <i>repaint</i> calls (if no <i>AnimatorControl</i> is attached and animating)
 +
** ..
 +
 
 +
EDT is <b>not</b>
 +
* blocking your rendering with event dispatching,
 +
* needed for pipelining your rendering commands,
 +
* hence not hindering your high performance rendering in it's own thread, eg an <i>Animator</i>
 +
 
 +
Using EDT is not mandatory, and you can turn it off in the NewtFactory,
 +
and deal with the event dispatch manually.
 +
 
 +
It's introduction was necessary to allow a <i>peace of mind</i>,
 
high performance and reactive solution of the dispatch event problem.
 
high performance and reactive solution of the dispatch event problem.
 
Some OS, especially MS-Windows, require one to create the native Window
 
Some OS, especially MS-Windows, require one to create the native Window
Line 271: Line 298:
 
as it is difficult to solve this from a framework operating with multiple temporary threads,
 
as it is difficult to solve this from a framework operating with multiple temporary threads,
 
a web browser for example.
 
a web browser for example.
 
Newt's EDT impl. creates one EDT per Display and calling thread,
 
as the Display instance is unique per thread.
 
 
Using EDT is not mandatory, and you can turn it off in the NewtFactory,
 
and deal with the event dispatch manually.
 
  
 
== How to use ''Newt'' with multiple Windows & Threads ==
 
== How to use ''Newt'' with multiple Windows & Threads ==
Line 387: Line 408:
 
However you do it .. the generic AWT 'restrictions' apply here
 
However you do it .. the generic AWT 'restrictions' apply here
 
as well.
 
as well.
 +
 +
 +
== Using OpenGL without a visible component ==
 +
Sometimes you might want to do OpenGL work without a visible GLDrawable or before making your drawable visible.
 +
* http://jogamp.762907.n3.nabble.com/Binding-textures-without-showing-the-GLCanvas-tp960145p960234.html
 +
 +
== Why you should learn direct from start the modern OpenGL (programmable and shader based) over the deprecated fixed function pipeline ==
 +
 +
I see everyday A LOT of beginers who start with the old deprecated OpenGL. This is wrong, this is so wrong. [https://github.com/elect86/ I, personally,] went through this and today I realize I did it wrong and I wished someone could have told me that at the time I start.
 +
 +
In order to say you why you should start right away learning modern OpenGL, I will use the words of [http://web.archive.org/web/20140207031129/http://www.arcsynthesis.org/gltut/About%20this%20Book.html Jason L. McKesson]:
 +
 +
"
 +
Programmability. Virtually all of the aforementioned sources instruct beginners using something called “fixed functionality.” This represents configurations in older graphics processors that define how a particular rendering operation will proceed. It is generally considered easiest to teach neophyte graphics programmers using the fixed function pipeline.
 +
 +
This is considered true because it is easy to get something to happen with fixed functionality. It's simpler to make pictures that look like something real. The fixed function pipeline is like training wheels for a bicycle.
 +
 +
There are downsides to this approach. First, much of what is learned with this approach must be inevitably abandoned when the user encounters a graphics problem that must be solved with programmability. Programmability wipes out almost all of the fixed function pipeline, so the knowledge does not easily transfer.
 +
 +
A more insidious problem is that the fixed function pipeline can give the ''illusion'' of knowledge. A user can think they understand what they are doing, but they're really just copy-and-pasting code around. Programming thus becomes akin to magical rituals: you put certain bits of code before other bits, and everything seems to work.
 +
 +
This makes debugging nightmarish. Because the user never really understood what the code does, the user is unable to diagnose what a particular problem could possibly mean. And without that ability, debugging becomes a series of random guesses as to what the problem is.
 +
 +
By contrast, you cannot use a programmable system successfully without first understanding it. Confronting programmable graphics hardware means confronting issues that fixed function materials often gloss over. This may mean a slower start overall, but when you finally get to the end, you truly ''know'' how everything works.
 +
 +
Another problem is that, even if you truly understand the fixed function pipeline, it limits how you think about solving problems. Because of its inflexibility, it focuses your mind along certain problem solving possibilities and away from others. It encourages you to think of textures as pictures; vertex data as texture coordinates, colors, or positions; and the like. By its very nature, it limits creativity and problem solving.
 +
 +
Lastly, even on mobile systems, fixed functionality is generally not available in the graphics hardware. Programmability is the order of the day for most graphics hardware, and this will only become more true in the future.
 +
"

Latest revision as of 13:08, 26 August 2015

JOGL FAQ

Versioning and Releases

What are the Runtime OpenGL Version Requirements ?

The current JOGL2 spec is in WIP state, but mostly finished. We do not require any extra features of GL versions > 1.1, hence it shall just work.

E.g. if you want to

  • support OpenGL platforms not supporting a version > 1.2
  • use GL ≥ 1.3 features optionally

Just query their availability e.g.:

gl.isExtensionAvailable("GL_VERSION_1_3")

If you call a > 1.2 GL function where it is not available, a GLException is thrown.

JOGL requires at least an OpenGL version 1.1, due to its dynamical function binding starting with OpenGL 1.2.

Use and test Autobuilds

I like to summarize how to manually test the JOGL autobuilds, starting with 2010-11-10.

You can fetch autobuilds from one the autobuild folder.

Runtime Version Check

The simplest verification of a JOGL build is to use the runtime version check and the runtime debug test.

See #Bugreports & Testing.

JOGL Demos

Let’s assume we are in the test directory ‘test’, from which we operate from this point.

We assume java is in your binary search path.

On X11/Unix and MaxOSX you can test the build as follows:

sh java-run-newt.sh demos.es2.RedSquare -GL2 -GL2 -GL2
sh java-run.sh demos.gears.Gears

and with debug output

sh java-dbg-newt.sh demos.es2.RedSquare -GL2 -GL2 -GL2
sh java-dbg.sh demos.gears.Gears

On Windows you shall be able to run:

java-win32.bat demos.es2.RedSquare -GL2 -GL2 -GL2
java-win32.bat demos.gears.Gears

and with debug output

java-win32-dbg.bat demos.es2.RedSquare -GL2 -GL2 -GL2
java-win32-dbg.bat demos.gears.Gears

The windows scripts are pretty simple and flat.

The magic unix scripts offer more features and can be used either in the autobuild environment or in your development one.

  • setenv-jogl.sh <JOGL-PROFILE> [<jogl-build-dir>]

Looks up and invokes profile.jogl, finds gluegen, sets the environment variables (CLASSPATH, LD_LIBRARY_PATH & PATH).

  • jogl/etc/profile.jogl <JOGL-PROFILE> [<jogl-build-dir>]

JOGL profiles are one of JOGL_ALL, JOGL_ES1_MIN, JOGL_ES1_MAX, JOGL_ES2_MIN, JOGL_ES2_MAX, JOGL_GL2ES12_MIN, JOGL_GL2ES12_MAX, JOGL_GL2_MIN, JOGL_GL2_MAX. Looks up the set of JAR files necessary to satisfy the chosen JOGL-PROFILE.

This allows you to test a specific environment, ie ES2 without GL2 and AWT, using JOGL_ES2_MIN. For this case I would recommend the native ES2 implementation from imageon SDK_OGLES2_LINUX_PCEMULATION_2.02.22.0756.

Bugreports & Testing

For all bug reports, please add the following information to your bug report:

Please use one of the latest aggregated archives, as described in this section.

Using our bug tracking system is strongly recommended.
We also have a bug overview page available via this wiki.

Please add all subsequent information as stated below to your bugreport,
otherwise we are not capable to hunt it down for you and us.

JOGL, Platform and OpenGL Version

Please perform a runtime version check, which provides the following information:

  • Platform
    • OS & version
    • Architecture
    • OpenGL Version
    • Java version (java -version)
  • JOGL version
    • GIT revision
    • Autobuild version
Send us the resulting file
test.log
.

Detailed Debug Log

Please perform a runtime debug test.

Send us the resulting file
test_dbg.log
.

Detailed Bug Information

  • Your Test case
    • Source code, a junit test would be best.
    • Invocation command-line
    • Exceptions, stdout/stderr log file

Applications

Adding a comprehensive junit test would help us the most to reproduce the bug, to discuss it with you and to achieve a good response time.
You may add it to your bug report directly or better, give us your git repository pull request.

If possible, please add the following system properties to enable DEBUG logging: -Dnewt.debug=all -Dnativewindow.debug=all -Djogl.debug=all

For example:

java -Djava.awt.headless=true -Dnewt.debug=all -Dnativewindow.debug=all \
-Djogl.debug=all demos.es2.RedSquare 2>&1 | tee RedSquare.report.log

Attach the log file to your bug report ..

Applets and Java Webstart

To test applets and javaws use

  • the jcontrol panel
  • or edit the java properties file:
    • Unix: ~/.java/deployment.properties
    • Windows: \Users\<username>\AppData\LocalLow\Sun\Java\Deployment\deployment.properties

where you add the following JRE Arguments. The jnlp prefix supports the javaws launch method.

  • jcontrol panel:
    -Djnlp.newt.debug=all -Djnlp.nativewindow.debug=all -Djnlp.jogl.debug=all
  • properties file:
    deployment.javaws.jre.0.args=-Djnlp.newt.debug\=all -Djnlp.nativewindow.debug\=all -Djnlp.jogl.debug\=all
    Of course you have to add these arguments to all of your JRE lines, ie 0 and 1, etc, if they exist.

You also want to

  • Enable logging/trace
  • Show the console window, or just use the latest log files in
    • Unix: ~/.java/deployment/log/, or
    • Windows: \Users\<username>\AppData\LocalLow\Sun\Java\Deployment\log\

Hence the java properties file (see location above) shall contain the following:

...
deployment.log=true
deployment.trace=true
deployment.javaws.jre.0.args=-Djnlp.newt.debug\=all -Djnlp.nativewindow.debug\=all -Djnlp.jogl.debug\=all
deployment.javaws.jre.1.args=-Djnlp.newt.debug\=all -Djnlp.nativewindow.debug\=all -Djnlp.jogl.debug\=all
...

Best practice:

  • Close your browser and ensure no JVM is running anymore
  • Delete all old log files in above log file folder
  • Start browser and the test applet
  • Close browser after test .. maybe after a while if you see nothing
  • Attach all new generated *.trace files to your bug report ..

Get the Source Code

Create a local copy/branch of a git repository either anonymous:

or via SSH and your user credential, so you can easily push back your changes to the github server:

  • git clone git@github.com:username/gluegen.git gluegen
  • git clone git@github.com:username/jogl.git jogl
  • git clone git@github.com:username/jogl-demos.git jogl-demos

How to build

How to Contribute

Common Runtime Problems

X11: OpenGL library is not picked up correctly, no OpenGL available

In case you are running a DRI machine, eg ATI's proprietary driver or an open source one, you may need to ensure that the environment variable LIBGL_DRIVERS_PATH is set properly.

I ran into this while testing the 32bit builds on a 64bit machine as a different user. Since LIBGL_DRIVERS_PATH is only setup for the desktop user on Ubuntu, some /etc/X11/Xsession.d/ script, I couldn't get a GL context to work.

So I had to set mine to the value:

export LIBGL_DRIVERS_PATH=/usr/lib/fglrx/dri:/usr/lib32/fglrx/dri

See also: Ubuntu fglrx bug entry

How to develop Cross-Device Applications

First you have to pick your lowest common denominator of an OpenGL profile, ie OpenGL ES1 or ES2. For either we offer an intersecting desktop GL profile, GL2ES1 or GL2ES2. Use the latter while creating your GLCapabilities. Build and run your application with the minimum GL profile JARS, e.g. on the desktop use:

~/jogl-demos> . ./setenv-jogl.sh JOGL_GL2ES12_MIN ../jogl/build

Here you are on a Unix platform (not Window) and your common build subdirectory is 'build'. jogl-demos/setenv-jogl.sh is provided within jogl-demos, which itself utilizes jogl/etc/profile.jogl.

This uses the GlueGen/JOGL JARS:

  • gluegen-rt.jar
  • jogl-all.jar

This uses the GlueGen/JOGL atomic JARS for minimal deployment:

  • gluegen-gl.jar
  • nativewindow-core.jar
  • jogl-core.jar
  • jogl-util.jar
  • jogl-util-fixedfuncemu.jar
  • newt-core.jar
  • newt-awt.jar

Please check JOGL Deployment also.

Now, the same Java application shall run on all devices, desktop and mobile. See demos.es1.RedSquare of the jogl-demos repository.

On the desktop you may run the ES1 demo:

~/jogl-demos> sh java-run-newt.sh demos.es1.RedSquare -GL2ES1

and the output is:

null RedSquare.run() 0
User screen size 0x0
Detected screen size 1920x1200
GLProfile[GL2ES1/GL2ES12] Entering initialization
GLProfile[GL2ES1/GL2ES12] GL Profile: GLProfile[GL2ES1/GL2ES12]
GLProfile[GL2ES1/GL2ES12] GL:com.sun.opengl.impl.gl2es12.GL2ES12Impl@b815859
GLProfile[GL2ES1/GL2ES12] GL_VERSION=3.0.0 NVIDIA 185.18.14
GLProfile[GL2ES1/GL2ES12] GL_EXTENSIONS: ..

Is my phone, embedded device or OpenGL ES driver supported by JogAmp?

How to use JOGL in Applets

See:

What is Newt's Threading Model for native window events ?

As of today, Newt's default threading model to handle native events is the event dispatch thread (EDT) model.

Newt's EDT impl. creates one EDT per NEWT Display, as the Display is a unique abstraction of a graphics device connection serving all of it's Screens and Windows.

EDT is being used to

  • dispatch native Screen and Window events
  • lifecycle Screen and Window functionality
    • create / destroy
    • reparenting
    • native repaint calls (if no AnimatorControl is attached and animating)
    • ..

EDT is not

  • blocking your rendering with event dispatching,
  • needed for pipelining your rendering commands,
  • hence not hindering your high performance rendering in it's own thread, eg an Animator

Using EDT is not mandatory, and you can turn it off in the NewtFactory, and deal with the event dispatch manually.

It's introduction was necessary to allow a peace of mind, high performance and reactive solution of the dispatch event problem. Some OS, especially MS-Windows, require one to create the native Window and dispatch it's events from the same native thread. As it was easy to handle these requirements from a simple test application, as it is difficult to solve this from a framework operating with multiple temporary threads, a web browser for example.

How to use Newt with multiple Windows & Threads

Newt is capable of handling multiple threads and windows.

For best performance, you may create one thread per window, if possible.

Below you see the invocation of the ES2 RedSquare jogl-demos utilizing multiple threads.

  • Single thread (Unix, Win32)
    java -Djava.awt.headless=true demos.es2.RedSquare -GL2
  • Single thread (MacOSX)
    java -XstartOnFirstThread -Djava.awt.headless=true demos.es2.RedSquare -GL2
  • Multiple threads & windows (Unix, Win32)
    java -Djava.awt.headless=true demos.es2.RedSquare -GL2 -GL2 -GL2 -GL2
  • Multiple threads & windows (MacOSX)
    java -XstartOnFirstThread -Djava.awt.headless=true com.sun.javafx.newt.util.MainThread demos.es2.RedSquare -GL2 -GL2 -GL2 -GL2

The serialization of the main Java class through com.sun.javafx.newt.util.MainThread may be used for all platforms, since it only takes effect on MacOSX. This allows you an almost platform independent invocation of your multithreaded Java applications.

On MacOSX, com.sun.javafx.newt.util.MainThread will occupy the main thread and serializes all native window related tasks through it. This mechanism is thread safe utilizes reentrant locking.

Why using AWT for high performance is not a good idea ?

AWT (on many implementations) holds the lock to the underlying native resources, e.g. X11 display, screen and window surface, hence we have to obey these locks for any GL action bound to such.

This is still pretty standard matter as long these locks only have to be applied to the actual resource in use.

On AWT, it turns out that we have to use the global JAWT toolkit lock for any native operation, ie OpenGL. This might not be a problem for a single threaded GL application, but if you start a multithreaded beast, you will recognize that it will stumble around.

You can verify this behavior with the ES1 RedSquare demo:

  • AWT - No VSync - One Thread
  java demos.es1.RedSquare -awt -swapi 0 -GL2
      5s: 3379f, 675 fps, 1 ms/f; total: 5s, 675 fps, 1 ms/f

Even here you may experience some stuttering ..

If you force disabling the toolkit lock:

     java -Dnativewindow.nolocking=true demos.es1.RedSquare -awt -swapi 0 -GL2

The demo may freeze forever .. due to native locking.

  • NEWT - No VSync - One Thread
    java -Djava.awt.headless=true demos.es1.RedSquare -swapi 0 -GL2
      5s: 5958f, 1191 fps, 0 ms/f; total: 5s, 1191 fps, 0 ms/f

Runs much smoother .. without the stuttering locking experience ..

This becomes much clearer with more threads:

  • AWT - No VSync - Three Threads
    java demos.es1.RedSquare -awt -swapi 0 -GL2 -GL2 -GL2
      5s: 772f, 151 fps, 6 ms/f; total: 5s, 151 fps, 6 ms/f
  • NEWT - No VSync - Three Threads
    java -Djava.awt.headless=true demos.es1.RedSquare -swapi 0 -GL2 -GL2 -GL2
      5s: 1669f, 333 fps, 2 ms/f; total: 5s, 333 fps, 2 ms/f

Why using Swing for high performance is not a good idea ?

First, all this inherents all arguments from 'Why using AWT for high performance is not a good idea ?

Second, it involves compositioning using different methods, some may not be available on some platforms.

From fast to slow:

1.) External Java2D's GLContext and FBO object.
  • GL stuff HW accelerated.
  • Available on some platforms: Linux/Windows Sun's Java2D impl.
  • Setup with System property 'sun.java2d.opengl' to 'true'.
  • Renders directly into Java2D's FBO object, if available.
2.) Own PBuffer GLContext, which has to be composed.
  • GL stuff HW accelerated.
  • Available on most platforms: No dependency to Java2D implementation.
  • Renders into an own offscreen drawable, and copies it over to AWT's BufferedImage.
3.) Own Pixmap GLContext, which has to be composed.
  • GL stuff unlikely hw accelerated.
  • Available on most platforms: No dependency to Java2D impl.
  • Renders into an own offscreen drawable, and copies it over to AWT's BufferedImage.

As you see, no straight forward HW rendering is involved, assuming that even the windowing manager is using offscreen surfaces - you would have 2 compositions here already.

At least (1) would be 'acceptable' here, if available, but if only (2) is available - the performance would not match the state of the art!

Sure, it might be enough for some UIs or static pictures .. or so, otherwise, I would prefer the 'overlay' method, ie using a GLCanvas within a Swing component, while no menu is being shown.

However you do it .. the generic AWT 'restrictions' apply here as well.


Using OpenGL without a visible component

Sometimes you might want to do OpenGL work without a visible GLDrawable or before making your drawable visible.

Why you should learn direct from start the modern OpenGL (programmable and shader based) over the deprecated fixed function pipeline

I see everyday A LOT of beginers who start with the old deprecated OpenGL. This is wrong, this is so wrong. I, personally, went through this and today I realize I did it wrong and I wished someone could have told me that at the time I start.

In order to say you why you should start right away learning modern OpenGL, I will use the words of Jason L. McKesson:

" Programmability. Virtually all of the aforementioned sources instruct beginners using something called “fixed functionality.” This represents configurations in older graphics processors that define how a particular rendering operation will proceed. It is generally considered easiest to teach neophyte graphics programmers using the fixed function pipeline.

This is considered true because it is easy to get something to happen with fixed functionality. It's simpler to make pictures that look like something real. The fixed function pipeline is like training wheels for a bicycle.

There are downsides to this approach. First, much of what is learned with this approach must be inevitably abandoned when the user encounters a graphics problem that must be solved with programmability. Programmability wipes out almost all of the fixed function pipeline, so the knowledge does not easily transfer.

A more insidious problem is that the fixed function pipeline can give the illusion of knowledge. A user can think they understand what they are doing, but they're really just copy-and-pasting code around. Programming thus becomes akin to magical rituals: you put certain bits of code before other bits, and everything seems to work.

This makes debugging nightmarish. Because the user never really understood what the code does, the user is unable to diagnose what a particular problem could possibly mean. And without that ability, debugging becomes a series of random guesses as to what the problem is.

By contrast, you cannot use a programmable system successfully without first understanding it. Confronting programmable graphics hardware means confronting issues that fixed function materials often gloss over. This may mean a slower start overall, but when you finally get to the end, you truly know how everything works.

Another problem is that, even if you truly understand the fixed function pipeline, it limits how you think about solving problems. Because of its inflexibility, it focuses your mind along certain problem solving possibilities and away from others. It encourages you to think of textures as pictures; vertex data as texture coordinates, colors, or positions; and the like. By its very nature, it limits creativity and problem solving.

Lastly, even on mobile systems, fixed functionality is generally not available in the graphics hardware. Programmability is the order of the day for most graphics hardware, and this will only become more true in the future. "