Planet JogAmp

Version 3.1.0

admin — Sun, 06 May 2012 02:08:26 GMT

The latest release of dyn4j adds a number of new features. See the features page for more details or the release notes. It also contains a number of important bug fixes. On the other hand, the API has been changed slightly and may break code written against older versions.

The Sandbox app has also seen some changes. Many bug fixes along with the features in dyn4j have been added. In addition, the threading issue on some platforms has been resolved by using the Newt-AWT bridge offered by JOGL. This makes the app far more efficient at handling input. The Sandbox includes precompiled tests along with the declarative (xml) tests. This allows the deprecation of the TestBed application. The Sandbox will take its place as the sole testing application.

Launch the Sandbox

When running the Sandbox application you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today.

Both applications require Java 1.6+.

Awesome! Just as last year @twbompo ported my PC 4k entry for...

Thu, 03 May 2012 21:35:56 GMT

Awesome! Just as last year @twbompo ported my PC 4k entry for Revision 2012 ?Hartverdrahtet? to WebGL (using libgdx). Nice Job! The port is available here. It?s always encouraging to see that it actually pays off opensourcing ur stuff :)

As the fragment main and post-processing shaders of my Revision...

Sun, 29 Apr 2012 14:45:22 GMT

As the fragment main and post-processing shaders of my Revision 2012 PC 4k entry port were processed or better ?obfusicated? with the shader minifier tool to meet the size restriction of <=4096 bytes, it became nearly impossible to understand or make any sense of the GLSL code. So here is the ?unminified? version with additional comments I used during development (as good as it gets):?main.fs post.fs

As promised before, here?s the direct 1:1 JOGL2 port of my PC 4k...

Sun, 29 Apr 2012 14:33:36 GMT

As promised before, here?s the direct 1:1 JOGL2 port of my PC 4k intro competition entry for Revision 2012. Sure it got a little bigger while porting but the shader and control code remained more or less untouched.?

The intro renders a fullscreen billboard using a single fragment shader. The shader basically encapsulates a?sphere-tracing based raymarcher for a single fractal formula with camera handling. Additionally a second post-processing shader is applied to the render output from the raymarching shader. Post effects are god-rays, tv-lines and noise to make the overall look more interesting and less ?sterile?. The different intro parts are all parameter and camera position variations of the same fractal.?Anyway, code as always on Github:?GL3_Hartverdrahtet_Port.java?and the corresponding main+postprocessing shaders: main.fs post.fs

Jogl/JogAmp Status Update ..

Sven — Thu, 19 Apr 2012 19:26:50 GMT

Last weeks the new video streaming feature GLMediaPlayer
was added for Android and machines w/ Libav/FFmpeg pre-installed.

We produced a presentation video showcasing JogAmp’s objectives:

Jogl/JogAmp on the Web, Desktop and Mobile 2012

RC6 is now underway, I still have to add some supplied patches and walk through the buglist though.
However, this time I have to complete this task until tomorrow regardless whether I could complete the bug walk or not.

Cheers, Sven

Back from Revision 2012 :) It was a blast to say the least....

Sun, 15 Apr 2012 12:07:06 GMT

Back from Revision 2012 :) It was a blast to say the least. I?ve met so many interesting people from all over?Europe, I?m still flashed by all those overwhelming impressions. Definitly coming back there next year. As on last?years Revision I had again prepared an entry for the PC 4k (executable size has to be <=4096 bytes) called??Hartverdrahtet?. Nearly took me two month to prepare. Technically speaking it?s more or less an enhanced version?of what I?ve already done last year, but this time the shader does not only use up every ALU peformance ur GPU has?to offer but also goes quite heavy on the texture units to render some nice post-effects (e.g. god-rays). I guess?the crowd really liked what I did in 4k, so I eventually placed 1st (take a look at the voting slices). Placing?first also got me a little bit attention press wise, thus heise.de and 4players.de mentioned the production?(sorry, german only). My buddy tokra with whom I was awarded the ?Newcomer Award? last year, also released stg for?the VIC20 called ?VIC can again? (a new interlaced graphics mode). After Revision I took the liberty of doing some?chillout for a couple of days, but stay tuned as I?m currently working on a JOGL port of ?Hartverdrahtet? ?

Spam incoming :) ? another nine fractal bitmap orbit...

Sun, 01 Apr 2012 17:10:22 GMT

Spam incoming :) ? another nine fractal bitmap orbit trapping variations: #1, #2, #3, #4, #5, #6, #7, #8 and #9. Enjoy!

GPU Vertex and Fragment shader introduction.

xerxes — Fri, 23 Mar 2012 12:15:56 GMT

I have posted a small JogAmp JOGL OpenGL ES 2.0 Vertex and Fragment shader introduction at:
https://github.com/xranby/jogl/blob/master/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/RawGL2ES2demo.java#L54

The nice thing about this introduction are that it will run unmodified on both Desktop OpenGL GL2 systems and Mobile OpenGL ES2 systems.
It uses the GL2ES2 GLProfile that use the common subset of OpenGL calls found in both desktop GL2 and mobile ES2.


wget http://jogamp.org/deployment/jogamp-test/archive/jogamp-all-platforms.7z
7z x jogamp-all-platforms.7z
cd jogamp-all-platforms
wget https://raw.github.com/xranby/jogl/master/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/RawGL2ES2demo.java
javac -cp jar/jogl.all.jar:jar/gluegen-rt.jar RawGL2ES2demo.java
java -cp jar/jogl.all.jar:jar/gluegen-rt.jar:. RawGL2ES2demo

As I can?t get my fingers off these flare bitmaps, here is...

Sat, 10 Mar 2012 16:38:10 GMT

As I can?t get my fingers off these flare bitmaps, here is yet another one in the series ?

And here we go with another one in the series ?

Sat, 10 Mar 2012 16:34:56 GMT

And here we go with another one in the series ?

Version 3.0.3

admin — Sat, 03 Mar 2012 22:07:01 GMT

Version 3.0.3 is a maintenance release with very few changes. The primary change was the move of the Settings class from being a singleton to being a member of the World class. This allows each instance of the World class to have different settings. The changes may break compatibility with previous versions, although they should be minimal.

And another one in the Julia-Set fractal bitmap orbit trapping...

Sat, 03 Mar 2012 14:28:15 GMT

And another one in the Julia-Set fractal bitmap orbit trapping series ?

The logical consequence of my last six postings: Julia-set...

Fri, 02 Mar 2012 19:08:41 GMT

The logical consequence of my last six postings: Julia-set fractal bitmap orbit traps. Same codebase as the last six times ofcourse ?

Overview of over ~40 different bitmap variations for my fractal...

Thu, 01 Mar 2012 21:09:01 GMT

Overview of over ~40 different bitmap variations for my fractal bitmap orbit trapping fragment shader. Guess I?m ready for some new stuff here, so next up: julia-set fractal bitmap orbit trapping :)

Another fractal bitmap orbit trapping experiment. Seems that...

Wed, 29 Feb 2012 15:48:07 GMT

Another fractal bitmap orbit trapping experiment. Seems that highly translucent flare bitmaps work quite well. Guess I?ll have to dig in deeper on these ? code is ofcourse the same as before.

Another try in my ?A fractal a day keeps the doctor...

Tue, 28 Feb 2012 13:56:03 GMT

Another try in my ?A fractal a day keeps the doctor away!?-series. Code stays the same.

Jogl/JogAmp RC6 Beta / Linux Armv7 Builds

Sven — Tue, 28 Feb 2012 02:05:42 GMT

Besides adding proper Mac OS X support (10.5.8 – 10.7.*, incl. OpenJDK7),
OpenGL 4.2 and latest EGL, ES1 and ES2 extension updates and lot’s of stabilization’s,
Xerxes R?nby and myself worked on a proper Linux ARMv7 support.
Both were able to test on Omap4 (Pandaboard ES), Tegra2 (AC100), where Xerxes also tested on other machines, eg. Nokia N9 MeeGo.

Even though GlueGen and JOGL in general support EGL and ES1/ES2 since 2008 incl. the GL profile selection,
we figured we need better support for multiple GL implementations on one platform, Mesa3D software and the hardware EGL/ES ones.
Without tweaking your default configuration, JOGL chooses the right implementation for the desired profile,
e.g. hardware accelerate GLES2 for the desired common GL2ES2 profile on your mobile device, even though Mesa is installed.

Besides tiny big fixes and workarounds the biggest amount of work was to attach the Linux ARMv7 job to Jenkins.
We use a cross-compile and cross-test environment, where the build host cross-compiles and makes the Pandaboard ES
fetch the artifacts via rsync and execute the tests. Later the build host pulls the results and forwards them to the Jenkins master.

All JogAmp modules are now build for Linux-Armv7,
a test release is made available here.
You may like to try the test Applets.
Note: This week RC6 will be released under the usual location and the above test URL will cease to exist.

I dared to test browser support via OpenJDK and the IcedTea Plugin,
and for some reason .. it just works

Please feel welcome to join the discussion.

JOGL on Linux-ARMv7-Omap4

Hardware accelerated Gears running on Nokia N9 using OpenJDK 6 JamVM and JogAmp JOGL OpenGL ES bindings

xerxes — Mon, 27 Feb 2012 11:18:27 GMT

Today JogAmp added a workaround to deal with GPU drivers that reports a bogus 0Hz screen refresh rate. With this fix in place hardware acceleration are working out of the box on Nokia N9 MeeGo phones in combination with the Nokia compiled Imaginative Technologies SGX 530 GPU drivers!

If you have OpenJDK installed on any ARMv7 board with a proper OpenGL-ES libEGL and libGLES driver setup then you can try running this for yourself by using my prebuilt jogamp-armv7 jars.

wget http://labb.zafena.se/jogamp/armv7/jogamp-armv7.tar.gz

tar zxvf jogamp-armv7.tar.gz

cd jogamp

sh ./run-desktop.sh

Source and build instructions are available.

JogAmp JOGL OpenGL-ES Driver compatiblity matrix

I am tracking ARMv7 libEGL/libGLES* GPU drivers compatiblity with JogAmp here:

http://jogamp.org/wiki/index.php/OpenGL_ES_Driver_compatibility_matrix

Chuck Norris force you to use the produced jars from the JogAmp “Chuck Norris” build-bot!

https://jogamp.org/chuck/job/jogl/684/

http://jogamp.org/deployment/autobuilds/master/jogl-b684-2012-02-27_11-04-43/
http://jogamp.org/deployment/autobuilds/master/jogl-b684-2012-02-27_11-04-43/artifact.properties uses gluegen build 510
http://jogamp.org/deployment/autobuilds/master/gluegen-b510-2012-02-25_20-44-27/

Assemble a ARMv7 jogamp testfolder using the JogAmp daily build:

wget http://jogamp.org/deployment/autobuilds/master/gluegen-b510-2012-02-25_20-44-27/gluegen-2.0-b510-20120225-linux-armv7.7z

wget http://jogamp.org/deployment/autobuilds/master/jogl-b684-2012-02-27_11-04-43/jogl-2.0-b684-20120227-linux-armv7.7z

7z x gluegen-2.0-b510-20120225-linux-armv7.7z

7z x jogl-2.0-b684-20120227-linux-armv7.7z

mkdir -p jogamp/jar
cp -r jogl*/etc jogamp/etc/
cp gluegen*/jar/*.jar jogamp/jar
cp gluegen*/lib/* jogamp/jar
cp jogl*/jar/*.jar jogamp/jar
cp jogl*/lib/lib* jogamp/jar
cp /usr/share/java/hamcrest-core.jar jogamp/
cp /usr/share/java/junit4.jar jogamp/

cd jogamp

java -cp jar/gluegen.jar:jar/jogl.all-mobile.jar:jar/jogl.test.jar:hamcrest-core.jar:junit4.jar com/jogamp/opengl/test/junit/jogl/demos/es2/newt/TestGearsES2NEWT -time 40000

Enjoy!

OpenGL ES hardware acceleration on OpenJDK ARM GNU/Linux twitter stream.

xerxes — Fri, 24 Feb 2012 22:46:45 GMT

I have created a Twitter stream where I track my current progress on getting desktop OpenJDK applications running faster on ARM by taking advantage of the OpenGL ES, possibly in combination with the lima driver, and OpenVG hardware acceleration.

OpenJDK? currently fallback to used CPU bound software rendering to draw most of Java2D and 3D application on ARM.

I decided to look into it and noticed that OpenJDK internally currently only support fast hardware acceleration on GNU/Linux systems by using the standard libGL OpenGL library, this libGL library do not support the latest ARM system on a chip GPU designs instead it allways fallback to use the uttelry slow Mesa software rasterizer. In order to get things fast OpenJDK need to take controll of the ARM GPU’s using the libEGL and libGLES* OpenGL ES library drivers.

You can get OpenJDK running 2x faster today by simply setting:

_JAVA_OPTIONS=”-Dsun.java2d.xrender=true”

This will enable the xrender pipeline made by Clemens, its compiled in most OpenJDK builds and are simply waiting for you to switch it on to test it, its not as fast as the libEGL drivers but its faster than the pure software rendered X11 pipeline.

I expect to get OpenJDK running butter smooth when proper hardware acceleration using JogAmp or LWJGL are in place, both of these API have recently added OpenGL ES support in the latest releases. A promising candidate to make it happen are to combine the JogAmp JOGL OpenGL ES bindings with Brandon Borkholder’s GLG2D.

https://twitter.com/#!/xranby -Tweeets for you!

Yet another fractal bitmap orbit trap variation. Setup- and...

Fri, 24 Feb 2012 22:36:49 GMT

Yet another fractal bitmap orbit trap variation. Setup- and shader-code stays the same, as before just varied the bitmap.

A fractal orbit trap a day keeps the doctor away! ? or stg...

Thu, 23 Feb 2012 18:14:23 GMT

A fractal orbit trap a day keeps the doctor away! ? or stg like that. As promised before another orbit trap variation. Setup and shader code stays the same, only varied the bitmap.

Back when doing my PC 4k entry for the Revision 2011 I felt I...

Wed, 22 Feb 2012 18:10:00 GMT

Back when doing my PC 4k entry for the Revision 2011 I felt I only scratched the surface to what?s possible with fractal bitmap orbit traps. So finally I got the time to revisit these beauties. This time a quite extended visit, so be prepared for a lot more videos in the coming weeks. The setup/init code on Github:?GL3_FractalBitmapOrbitTrapping.java?and the shader: .fs

Having recently bought a new GPU (ATI 6990M) it was time to test...

Tue, 21 Feb 2012 13:30:00 GMT

Having recently bought a new GPU (ATI 6990M) it was time to test a quite cool feature I had to pass on for a while: double precision floating-point arithmetic (GL_ARB_gpu_shader_fp64). So it was obviously time for another field trip into the world of fractals, and this time a really deep one. Code can be found here: GL4_Mandelbrot_DoublePrecision.java Shader code: .fs

Upgrade to JOGL2.0 build #661

Tue, 21 Feb 2012 02:03:00 GMT

Saying “it has been a while” since my last upgrade of JOGL2 would be putting it mildy .. anyway I finally won the struggle with procrastination and downed a new version today: Build #661 (15.02.2012 14:00:11). Tested all my current routines with the new build, and so far all seem to run flawlessly both on ATI and NVIDIA. Nice work there jogamp community! A minor downside is the never ending story with NEWT bugs wich is more than ever up2date (at least on Windows). So I guess I?ll have to spam bugzilla within the next few days ?

Version 3.0.2

admin — Tue, 20 Dec 2011 21:44:46 GMT

3.0.2 introduces significant changes in the Sandbox application along with some minor bug fixes to dyn4j and some new features. Specifically, small CCD improvements, a new fixture filter TypeFilter, and tangent speed settings on contacts. Bug fixes include: a fix to the Body.setMass(Mass.Type) method, auto-sleeping bug, and a rotation disc computation bug. In addition, both dyn4j and Sandbox have been internationalized (any volunteers for translating?).

The Sandbox includes many new features and fixes. First, is the ability to add Rays to test raycasting. Next, all output angles are in Degrees (GUI, xml, and java files). Finally there is a new Export feature to export a simulation to a Java class file. This allows you to create a simulation inside the Sandbox application and export it for use in your application.

Soon I plan to post some videos on how to get started and some of the useful features contained in the Sandbox application.

Launch the TestBed		Launch the Sandbox

When running either test application you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today.

Both applications require Java 1.6+.

JogAmp Release v2.0-rc4

Sven — Fri, 02 Dec 2011 08:56:56 GMT

After tons of bug fixes and Mac OS X, Solaris and Android platform support
we finally have v2.0-rc4.

Besides many important bug fixes this release supports
Mac OS X 10.6.4 and 10.7.

The Applet browser plugin is also enhanced and validated
on all platforms for FF, Chrome, Safari and IE where supported.

http://jogamp.org/deployment/jogamp-current/jogl-test-applets.html

+++

We have to thank each other for our ongoing support,
bug reports, inspiration and pushing for results.

Thank you.

+++

The following aliasing of URL location has been made,
ie. all are aligned to v2.0-rc4 for now.

http://jogamp.org/deployment/

v2.0-rc4 -> archive/rc/v2.0-rc4
jogamp-current -> v2.0-rc4
jogamp-next -> v2.0-rc4
webstart -> v2.0-rc4
webstart-next -> v2.0-rc4

Developer downloads at:
http://jogamp.org/deployment/v2.0-rc4/archive/

Git repositories have been tagged w/ v2.0-rc4.

+++

Planned for RC5 so far:

RC5:

Maven2 integration (I know .. a bit late it is already)
Mobile/Android autobuilds / release
More bugfixes
Update the graph package

+++

Please join the discussion in our forum.

You may like to comment on this release here.

Cheers, Sven

JOGL Test Statistics (Linux, Windows and OS X)

Sven — Thu, 13 Oct 2011 22:27:02 GMT

To conclude my today series of blog entries, I thought it might be a good idea to show our automatic test statistics.

Here are the latest good and failed test charts for all platforms:

Test Stats 20111013 All	Test Stats 20111013 All - Errors Only
Test Stats 20111013 All - Failure Chart

And finally the progress on OS X with all tests included:

Test OS X 20111013 Overview
Test OS X 20111013 Count	Test OS X 20111013 Runtime

Besides adding running all unit tests to OSX, we also made sure that it’s performance is now equal to the other platforms, ie. around 4 minutes runtime for all tests.

But be aware that these features will be promoted to the next release RC4,
so you would need to wait or use the autobuilds, see Downloading the latest automatic build.

Jogl OS X Port is Nigh :)

Sven — Thu, 13 Oct 2011 21:48:16 GMT

Since the mouse features were to easy to add and my Android vacation should take a bit longer, our OS X port was a good candidate to burn some hours I don’t have.

What should work for OS X by now:

NEWT Top-Level Windowing
NEWT Child Window w/ NEWT Parent
NEWT Child Window w/ AWT Parent
JOGL incl. shared context
NEWT works w/ AWT enabled JVM out of the box
Method to execute a Runnable on the MainThread
The new native Jar loading facility (Application, Applet, Webstart)

The window positioning code was a torture, since the AWT components are not top-level on OS X. Hence we have to calculation the proper screen size position in bottom-left coordination space, even when resizing the window.
Maybe there are still some glitches in case of a NEWT child within an AWT floating Container, but most cases work fine.

Shared or offscreen context destruction was another issue.
We have to run this task on the MainThread, otherwise we experienced a ~10s freeze.

Btw our MainThread semantics have been simplified a lot.
On OS X, it just launches the user main class in a new thread while continuing as the NSApp MainThread.
In short, it is no more required when using an AWT enabled JVM, since it already launches as the NSApp MainThread.

After a few more cleanups, I will prepare the next release and test our new native Jar loading mechanism
and Applets in general.

But be aware that these features will be promoted to the next release RC4,
so you would need to wait or use the autobuilds, see Downloading the latest automatic build.

Note on the side: Motivation for the OS X port was not my liking of the platform, which I don’t, but to just complete our platform independent solution. Hence having NEWT working well on OS X is mandatory here.

New NEWT Mouse Features

Sven — Thu, 13 Oct 2011 21:20:48 GMT

After doing all the Android work, I thought I need a break and finally
added the NEWT mouse features some are desiring:

Visibility
set pointer visible or invisible
Confined
confine pointer to window, or not
Warp
set mouse position within the window

This is NEWT’s minimal API addition in this regard.

The InputEvent’s modifiers expose the above states confined and invisible
which can be easily queried and reacted upon in the event listener, as shown in GearsES2.

This allows you to have a game-like mouse navigation, where you control the direction w/o pressing the mouse button (which you may need for something else), not seeing the mouse pointer and last but not least,
not leaving the game window.

Tested w/ TestGearsES2NEWT, using
GearsES2.

This is currently impl. for X11 and Windows and I am currently adding these to our OSX port.
Since the default operation for these features are NOP and touchscreen don’t require any of those, there is no work to do on Android in this regard.

But be aware that these features will be promoted to the next release RC4,
so you would need to wait or use the autobuilds, see Downloading the latest automatic build.

Finished my post processing anti-aliasing evaluation and settled...

Tue, 11 Oct 2011 14:17:00 GMT

Finished my post processing anti-aliasing evaluation and settled with a combination of FXAA and 2xFSAA. As before I used the Mandelbrot and Displaylist routines as basis for the experiments. Source on Github: GL3_FXAA_Mandelbrot.java and GL3_FXAA_DisplayLists.java. JOGL ?friendly? fragment shader (eliminated the need for a dedicated vertex shader): .fs

Android Test APKs [201110080141utc]

Sven — Sat, 08 Oct 2011 02:11:23 GMT

Since we were not able to hook up the Android test machine to Jenkins
to produce builds and a release, I thought it might be of interest to share my builds with
whoever is interested.

Just go to this test deployment folder:
http://jogamp.org/deployment/test/android/201110080141utc/

Download all the APKs:

gluegen-rt.apk
jogl.all-android.apk
jogl.test.apk
jogl.android-launcher.apk

and install them via the ADB:

   adb install gluegen-rt.apk
   adb install jogl.all-android.apk
   adb install jogl.test.apk
   adb install jogl.android-launcher.apk

You can uninstall them as follows:

adb uninstall com.jogamp.common
adb uninstall javax.media.opengl
adb uninstall com.jogamp.opengl.test
adb uninstall com.jogamp.android.launcher

The APKs are currently just signed with a temporary key and debug is enabled.

Uninstalling them manually is required when you like to try to test a new version,
which will appear in the same parent folder under a different timestamp soon.

Please visit our forum at http://forum.jogamp.org/,
actual thread for this test release is
http://forum.jogamp.org/Android-Test-APKs-201110080141utc-td3404613.html,
and leave your comments there if you like, thank you.

The API in regards to Android is under review and will change
to make the experience more comfortable.

However, we already achieved to run a Java module on desktop as an application or applet
and on Android / Mobile w/o any change.
This is the main goal of porting JOGL on Android, no need for native code or rewriting your application.

Cheers, Sven

Continuing with my experiments regarding anti aliasing, I took a...

Thu, 06 Oct 2011 15:17:00 GMT

Continuing with my experiments regarding anti aliasing, I took a look at the idea of combining post-processing anti-aliasing (FXAA) with super sampling as explained by Timothy Lottes. As the above picture clearly shows the results of 2xFSAA+FXAA line up somewhat between 2xFSAA and 4xFSAA at the cost of 2xFSAA (as FXAA is neglectable performance wise). JOGL2 port/implementation coming up shortly ?

JOGL/JogAmp @ Red Square / Moscow ? NURBS @ GraphiCon?2011

Sven — Wed, 05 Oct 2011 19:26:34 GMT

While being in Moscow at GraphiCon’2011 to release Rami’s paper

GraphiCon 2011 Book

Resolution Independent NURBS Curves Rendering using Programmable Graphics Pipeline

about the math of JOGL’s new graph package …

Resolution Independent GPU Accelerated Curve & Font Rendering

.. we finally made good progress in completing the Android port including graph.

JOGL/JogAmp @ Red Square / Moscow (edited)

0:00 – 1:20 : Part 1 – Gears ES 2.0 @ Red Square @ Day
1:25 – 2:50 : Part 2 – All Demos @ Red Square @ Night
2:50 – 3:45 : Part 3 – Graph UI on Tablet & Phone

With the current rate post-processing antialiasing techniques...

Wed, 05 Oct 2011 12:31:27 GMT

With the current rate post-processing antialiasing techniques are invented my projection is that we will run out of four letter acronyms by the end of the year: MLAA, FXAA, SRAA, GPAA, NFAA (to name only a few). So I felt it was time to revisit the whole anti-aliasing problem and started with porting/evaluating FXAA. Looks promising, more to come ?

Bug Hunting on Android ?

Sven — Tue, 04 Oct 2011 23:34:20 GMT

While fixing JOGL for Android,
Rami and I are testing the code against the consumer devices:

Asus Transformer, Android 3.2, NV Tegra2
Samsung Galaxy Tab 10.1, Android 3.1, NV Tegra2
Samsung Galaxy S2, Android 2.3, ARM Mali 400 MP
Samsung Galaxy S1, Android 2.3, Omap 34xx

We have expected glitches in the OpenGL drivers and/or Android environment
and even found bugs which does not exist on a similar device, ie device 1 and 2.

Device 3 works absolutely flawless, kudos to the ARM developer
of the MALI silicon and it’s drivers! No workaround is necessary and our demos worked
straight out of the box, even w/ multisampling enabled.

Device 4 shows flickering on all demos, where the FPS value
is always just around 18-23, hence below V-Sync.
We actually have no clue why, since device 3 works perfect. Since both devices are mostly equal
but it’s GPU .. we must assume it’s about the Omap3 driver.

The Tegra2 devices gave us quite a headache

Device 1 and 2 (hence Tegra2) exposes the following bugs:

discard in fragment shader freezes the GLSL compiler
mixing sampler2D w/ a non texture code path let’s GLSL compiler result in error
P1202 Texture's gl states do not match with shader's

Device 2 also exposes an interesting bug not available on the other Tegra2 device,
which rendered all our demos invisible, ie. resulting in a blank screen, where only the clear color was shown.
Hunting down this one took also quite a while, but after stumbling over NV’s PerfHud ES and some hints about how to enable it on consumer devices the culprit was found.
The GLState Viewer exposed that our uniform mat4 mgl_PMVMatrix[2]; wasn’t set via glUniformMatrix4fv(..), probably a bug within the OpenGL ES 2.0 driver code.
Actually device 1 and 2′s libGLESv2_tegra.so differ where the other EGL/GL driver files are the same. However, replacing it did not do the trick.
~~Replacing the mat4 array with a simple uniform mat4 mgl_PMVMatrix; did the trick, ofc we need a better workaround for this case.~~

Update: The mat4 array bug turns out to be Android 3.0 Dalvik Issue 16434. A simple workaround for our PMVMatrix is submitted.

Further more Tegra2 doesn’t support the old fashioned MSAA, but their own new extension
EGL_NV_coverage_sample, to which we will have to revert to in our multisample GLCapabilties.

Version 3.0.1

admin — Tue, 04 Oct 2011 02:22:34 GMT

3.0.1 incorporates many small changes. JUnit test, the TestBed and a new testing/demo application, Sandbox, have been moved around to better structure the project. Many major and minor bug fixes have been made. The most visible change is the normalization of the Joint class methods. In addition, the WeldJoint class now supports a soft joint setting.

Launch the TestBed		Launch the Sandbox

When running either test application you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today…

Both applications require Java 1.6+.

In the TestBed application, be sure to type the “c” key to get the TestBed Control Panel so you can play with the simulator. Use the Controls tab to view all the key board and mouse options. Use the Tests tab to run a test of your choosing. Use the Draw Options tab to set what is drawn to the screen. And finally, use the Simulation Settings tab to play with all the different settings allowed by the engine.

In the Sandbox application, use the menus, toolbar and the tree (right click for context menus) to run tests, save them, add bodies/joints, etc.

JogAmp Deployment Enhancements: Automatic loading of native JARs (Applet/Application)

Sven — Fri, 23 Sep 2011 17:22:06 GMT

Currently implemented in modules GlueGen and JOGL. TODO: JOAL and JOCL.

jogamp-next points now to the signed beta build gluegen_410-joal_213-jogl_489-jocl_424-signed.

See how it (NApplet) works online on the new JOGL Applet Test page.

Without the need for using

our Applet-Launcher
the JNLP extension
setting up the native library folder for applications

we automatically

verify all it’s certificates (for non applications)
cache the JAR files native libraries
use the cached native libraries

As you can see in the documented html pages:

.. this simplifies the tag writing and removes the need to write your JNLP file.

The native JAR download mechanism still benefits from the applet’s
network cache mechanism, hence downloads the JAR only

if it doesn’t exist, or
if the server version is updated

Of course, this causes a network connection but surely not a big deal
and more correct. Users can still use the JNLP mechanism of course
using the JNLP tag:

  <update check="background" policy="always"/>

Applications don’t need to worry about the system dependent way
of dropping and publish the native lib folder anymore.
Applications also load the native JAR file and use their native libs,
just deploy all JARs in the same folder – done.

Git commits in this regard:
– GlueGen from f357a00e511f0049865392adecc4d042663da6e6 upto 609e649443f900116039cda7a1bc7c9359b0242f

– JOGL from ac358bd66878e63a370377d4c7f625ec5b1b9e31 upto 424a5ecbd7575eb39343638696c19cd617577912

This feature will be enabled in general for rc4 soon.

Please reply w/ your concerns and ideas etc,
so we can make this one work fine and secure for all.

Cheers, Sven

Resolution independent curves @ GraphiCon 2011

Rami — Wed, 07 Sep 2011 07:01:52 GMT

Will be presenting by the end of this month the paper behind the Resolution Independent Fonts, Curve, and UI rendering API added recently to jogl.

Title:??Resolution Independent NURBS Curves Rendering using Programmable Graphics Pipeline

Abstract:
Non-Uniform Rational B-Splines (NURBS) are widely used,especially in the design and manufacturing industry, for their precision and ability to represent complex shapes. These properties come at the cost of being computationally expensive for rendering. Many methods have tackled NURBS rendering by view based approximations and/or heavy pre-processing. We present a method for resolution independent rendering of curves and shapes, de?ned by NURBS, by utilizing the high parallelism of the programmable graphics hardware. The computation of the curve is processed directly on the GPU, without the need for complex pre-processing and/or additional storage of the basis functions as textures. Our method enables rendering of a complex NURBS shape in precise form, by de?ning only the curve?s hull. We also present a method to enhance the performance of the preprocessing stage, mainly triangulation, that ?tsour requirements and speeds up the process. With opti-mized preprocessing and using only the mobile pro?le of theprogrammable graphics pipeline, we achieve a fast and resolution independent method for rendering NURBS based 2d shapes on desktop and mobile devices.

Conference Program: ???http://gc2011.graphicon.ru/en/program/scientific#en4

Thanks to Sven Gothel and the Jogamp Community for all the fruitful discussions regarding this topic.

Hope to see you all there!

Update: Paper and slides published on Jogamp.org.

Siggraph 2011 ? Vancouver

Rami — Wed, 31 Aug 2011 10:25:26 GMT

Once again siggraph was great… didnt get time to see Vancouver but it looked nice!

had the pleasure to co-present with Sven the latest development on Jogamp.org, mainly JOGL highlighting the newly added support for embedded devices (linux ARM and Android) and the
new Resolution independent Font and User Interface. In all, it was a great “journey” and the feedback we got was great as well.

More:
The journey to Siggraph (the story)
JOGL Embedded Devices (the status)

The presentation well be posted to jogamp.org by next week, we need to add snapshots to it…etc)

The Pictures: (courtesy of Justin)

Setting up the presentation and devices

Left to right: projector problems, goodmorning...

Talking..

JogAmp @ Siggraph2011

Rami — Wed, 15 Jun 2011 15:35:11 GMT

Cross posting announcement with Sven Gothel.
++++++++++++++++++++++++++++++++++++++++++++++++++++++

Jogamp will be at Siggraph this year after the great success of last year’s BOF.

JogAmp: 2D/3D & Multimedia Across Devices

Tuesday, 9 August | 2:30 pm ? 4:30 pm | Vancouver Convention Centre
JogAmp provides JOGL (OpenGL), JOCL (OpenCL) across devices on top of Java.
Showcasing Resolution Independent Curve, Font and UI GPU Rendering on desktop and mobile (Android, etc).

Jogamp Community
sgothel (at) jogamp.org

Our goal is to

recapitulate last year progress and discuss our directions
demonstrate JogAmp Modules (JOGL, JOCL, ..) on multiple devices, PC (Windows, Linux, ..) and Mobile (Android, Linux.
showcase our new resolution Independent Curve rendering, utilized shapes, fonts and UI. We also like to discuss it?s usability and how to accomplish a complete UI toolkit
showcase user contributions and applications / use-cases

If you would like to showcase some tool/demo that uses jogl please contact us asap.

all our results will be visible as usual via?jogamp.org.

Hope to see you there….

Cheers,

Version 3.0.0

admin — Sun, 05 Jun 2011 19:15:55 GMT

3.0.0 incorporates big changes to the library. The base package has been changed, the broadphase collision detection code has been updated adding 3 new implementations, many bug fixes and performance enhancements, a new joint, better documentation, many more JUnit tests, new example applications, and more.

Show Me The TestBed!

When running you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today…

All the releases require Java 1.6+. Be sure to type the “c” key to get the TestBed Control Panel so you can play with the simulator.

Use the Controls tab to view all the key board and mouse options. Use the Tests tab to run a test of your choosing. Use the Draw Options tab to set what is drawn to the screen. And finally, use the Simulation Settings tab to play with all the different settings allowed by the engine.

GPU based User Interface ? WIP

Rami — Fri, 08 Apr 2011 15:49:34 GMT

One the goals behind the work done in GPU based Curve Rendering, was the ability to investigate the
possibilities regarding GPU based user interface in a 2D/3D scene – ontop of jogl.

As a test, pushed to repo a testcase for rendering a button with a label, using the Resolution Independent Region/Text Renderer.

https://github.com/rsantina/jogl/commit/e6de1dcd253ef4d6ba9f584b4ed3540c85c66d2c

Screenshots: (click to view)

Resolution Independent Button

Resolution Independent Button - rotated

Resolution Independent Button - closeup

Resolution Independent Button - clicked

Cheers,

GPU based Resolution Independent Font & Curve Rendering ? initial Release

Rami — Fri, 01 Apr 2011 15:58:21 GMT

Below is about the latest project done by Sven Gothel and myself, which is now published/merged in JogAmp – Jogl Project.

The story: At first we started this project as an idea, started with a chat with Sven on possible ways to by pass the Microsoft patent on GPU Curve Rendering. So after digging into the math of Loop/Blinn patent, devised a way to solve the problem with a different approach than the one used in the patent, the math behind the new approach will be published here soon (need to type them, currently on a notebook with too many scrabble).

After making sure the math works in theory, moved into developing a prototype for the algorithm. While doing this, developed a tessellation utility to provide Delaunay based triangulation of the curved outlines, mainly to avoid using a hack on GLU tessellation to get the triangles and not to have a slow solution. After having a working version of the demo, we went into the ?harder? part, getting good quality AA on the ever so tiny fonts. After lots of discussions and fighting the small dimples in the curves, we were able to devise a method that provided the best output of all the others we tried and sharp quality Anti Aliasing.

At that point, we moved from building a prototype (proof of concept) to building an API so that we can add it to JOGL API, which was a great experience by it self, thinking of all the ways the user might wanna use it. ?We looked into making it more generic, usable, readable, and stable for a user. Not to forget making sure all the code is BSD license clean.

Yesterday,?we reached to a point where we agreed that its ?clean? and good for an initial public release, merge with jogl project. ?More than enjoying the results and outcomes the best part was the collaboration and the discussion held during the project development. ?In short it was a great experience, and lots of fun!

As for the tech part:?first some new snapshots,

(click image to view)

Text with two pass AA

Font Set showing all the glyphs in two pass rendering

Manually Defined Region - One Pass

Small text string - Two Pass Rendering

?as a continuation to the earlier post, we have cleaned up the repository of the curve rendering module, and now merged into jogamp.org – jogl project. (git sub-tree merge ).
The text and region renderer, have two rendering types defining the rendering Technique (SINGLE_PASS or TWO_PASS).

Single Pass: the region with no AA for the straight edges and general shape, where only the curved regions have implicit AA function embedded in the calculations in the relevant fragment shader. This type of rendering is useful for most cases where AA quality on very small fonts/regions is not important. Example usage would be having text scattered around in a 3D scene. The developer is then free to use/plug in his post processing or just use MSAA which gives good results in most cases.

Two Pass: (check the pictures above) render the region to an FBO and then in a second pass attach it to the Bounding Box of the String and do a variant of a Gaussian blur on the text/region. Giving the ever sharp effect on the text that can?t be accomplished in a single pass rendering (at least all the other approaches that I tried). The sharpness of the final shape is dependent on the variable texture size for the first pass (giving the user a way to play with the effect: blurry to sharp). Note: later this will be available in an automatic manner. (hopefully not too later)

To see details on how to use it you can take a look at the unit tests, and demos also pushed to the jogl repository.

https://github.com/sgothel/jogl
https://github.com/rsantina/jogl

Having said all that, download the latest jogl build and try the demos,
would love hearing your feedback and ideas.

Cheers

GPU Resolution Independent Curve Rendering ? Brief

Rami — Tue, 15 Mar 2011 14:31:31 GMT

In the past couple of weeks, I worked on developing a new technique to create an API for resolution independent?curve bounded regions and text in general. ?The main goal of this project was to move out of the Microsoft Patent Loop/Blinn approach which uses Bezier (Quadratic/Cubic) curve rendering to solve the problem.

To by-pass the Microsoft patent, developed the functions and parameters based on nurbs blending functions. The result of this approach gives great results especially in the region of injection points which where a main concern as well. ?The next problem?approached?was?Anti aliasing for the rendered curves especially targeting small fonts, since MSAA on small fonts will give a blurry non-sharp effect.

Below are some snapshots from demos created to use the new text/curve renderer API (where the algorithm is implemented). Later on, ?will publish the detailed algorithm with a review of the AA techniques used and tested. But first will work in the upcoming week or so to polish the API before pushing to jogl repository.

Click on image to view original size (all images are in png format to preserve quality)

- A text string rendered with AA.

- Rendering a small text using the same algorithm with AA.

- Zoom in to the text showing Resolution independence.

- Rotated text in a 3D scene.

- A general curve bounded region rendered.

The dyn4j TestBed Now Uses JOGL

William — Sat, 05 Feb 2011 19:31:35 GMT

I recently released a new version of the TestBed application (which is used to test the dyn4j project. In this new version I decided to move from Java2D to OpenGL.

There is a great open source project called JOGL that makes the OpenGL API available to Java.

You can test out the new TestBed here.

In addition to the full OpenGL API, JOGL also offers OO approaches to common tasks like texturing, shaders, etc. The project owners, after reviving JOGL and JOAL (thank you!!!) have also been working on a binding to OpenCL called JOCL. This seems very promising and hopefully I’ll have some time to actually look into using this to help speed up some bottlenecks in dyn4j.

As a side note, I do have to say that the OpenGL API is really good and pretty well documented. I had a few “scratch my head” moments but for the most part I’m really liking it.

Version 2.2.3

admin — Sun, 30 Jan 2011 01:39:03 GMT

The new version, 2.2.3, features updated Javadocs, 3 different CCD modes, and a new JOGL based TestBed.

Show Me The TestBed!

When running you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today…

All the releases require Java 1.6+. Be sure to type the “c” key to get the TestBed Control Panel so you can play with the simulator.

Version 2.2.2

admin — Sat, 15 Jan 2011 18:35:08 GMT

The new version, 2.2.2, features one more joint, AngleJoint and a few minor bug fixes. The RopeJoint has been extended to allow for a minimum distance in addition to the maximum distance. See the javadocs or source updates for more details.

When running you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today…

The "Angle" test from the TestBed

All the releases require Java 1.6+. Be sure to type the “c” key to get the TestBed Control Panel so you can play with the simulator.

3D Scene Navigation standards

Rami — Mon, 27 Dec 2010 08:51:35 GMT

Picking up a new software and navigating thru the scene should be easy and intuitive.? Most of the tools out there are picking up a standard set of navigation modes which are the bare essential for a good user experience with your tool.

Sure, some tools add a set of “identity”? navigation mode which identify the software, but that can be tricky business since you need the user to quickly start navigating without worrying or reading the manual. Since very few are willing to read the manual anyways.

While designing your user experience with your visualization tool, it would be a good idea to start with the following set of modes which are intuitive enough for users to start clicking away.

This list assumes your building a navigation system for visualizing a large model for a City, landscape, CAD…etc. For design tools, this list is not nearly complete.

Examine
Summary: The default, basic mouse based navigation, and user fail safe.
Benefits: This mode is your navigation fail safe since if while using another mode and the user isn’t able to get the desired view, this mode can be used for fine tuning.
Usage:
Dragging + Left Mouse: Rotate around viewpoint center or initial clicked location
Dragging + Right Mouse: Translate within current view plane.
Dragging + Middle Mouse: Zoom in/out along current view direction.
Mouse Wheel: smaller step zoom in/out along view direction, best for fine tuning.

Hover
Summary: Keyboard based, game like (easy for people with game experience)
Benefits: Always aligned/oriented along the ground, Intuitive for users with gaming background, best for scene movements, basic impl for a realistic walk
Usage:
W/A/S/D keys: movement around the current perpView plane (view-direction x right).
Arrow keys: same as WASD.
Dragging + Left Mouse: Change looking direction (rotate around the up vector)
Dragging + Right Mouse: nothing (extra: user action)
Dragging + Middle Mouse: nothing
Mouse Wheel: smaller step zoom in/out along view direction, best for fine tuning.
Additional: add gravity to move along the up vector, (great for climbing stairs, dropping to another level, …)

Fly
Summary: mouse based hover like navigation, fly around the scene.
Benefits: Fast movement around the scene, ability to change elevation and “pitch”
Usage:
Dragging + Left Mouse: move forward, turn left/right, or move backwards. depending on mouse diff.
Dragging + Right Mouse: nothing (extra: user action)
Dragging + Middle Mouse: change pitch

Mouse Wheel: smaller step pitch change, best for fine tuning.
Additional: Left+Mouse dragging changes pitch direction, best for continuous movement since moving to middle mouse dragging not very intuitive and causes a slight interruption.

With the above in hand a user can navigate along the scene, reach any view he wants, and have “fun” while doing so. Additional features like zoom-to-window, gravity on/off switch, axis alignment (forcing navigations to align with x, y, and/or z-axis) can be useful as shortcuts.

Another helpful and very intuitive user control is the Over Head navigation control, which can be placed in the top right corner, great for user orientation and a good shortcut for switching views/modes. The best of such controls, in my view, the ViewCube created by AutoDesk AutoCAD.

Version 2.2.1

admin — Sun, 26 Dec 2010 23:58:14 GMT

The new version, 2.2.1, features one more joint, RopeJoint and a few minor bug fixes involving SecurityExceptions for sand-boxed environments. See the javadocs for more details.

When running you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today…

The "Rope" test from the TestBed

All the releases require Java 1.6+. Be sure to type the “c” key to get the TestBed Control Panel so you can play with the simulator.

Tutorial: Displaying Java OpenGL in an Eclipse editor with a menu bar and a run/pause button

Wade Walker — Mon, 06 Dec 2010 22:21:18 GMT

Hi again! Wade Walker here, back for the fourth tutorial in my ongoing series on writing scientific and engineering apps with Java OpenGL and Eclipse. OK, that might sound pretty forbidding, but it?s really not—if you want to write any type of app with a complex interface and 3D graphics, these tutorials can help.

I am returned as well! I am called Stitio, and, much as a viticulturist will build a trellis to guide his vines upwards to the sun, I create these headings to coax our readers? comprehensions to fruition!

Over the last three tutorials, me and my suddenly-wine-loving friend Stitio created a simple Java OpenGL (JOGL) app and showed how we can use the Eclipse Rich Client Platform (RCP) to let it run cross-platform and to create native binaries.

And in this, the quatri?me partie of our oeuvre, we first revisit our humble origins before reaching a new apotheosis!

Hmm, your guess is as good as mine there. But what I think Stitio means is, before we can pile this thing any higher, we need to get a firmer foundation under it. First we?ll rename a few things to make more sense, and we?ll change the type of Eclipse RCP window we draw in so we won?t run into trouble later on. Then we?ll add a menu bar to our app, and finally
we?ll give it a toolbar with a run/pause button that can start and stop the simulation.

Let the science begin! Again!

Preparing the soil: Wherein we set up our workspace yet once more

We?ll build on the previous tutorial, so long-time readers can continue in the same workspace as last time. Or if you?re just joining us, you can create a new workspace directory, unzip JOGL and the previous tutorial into it, and follow the instructions from the second tutorial to import those projects into a new workspace.

As usual, if you just want to skip to the end of this tutorial without all the clicky-typey, you can unzip JOGL and this tutorial into a new workspace directory, import them, and you?re done.

Changing the rootstock: Renaming one?s project and package

When I started this tutorial series, I didn?t realize I?d be expanding the same project over and over. So like an idiot I?ve been naming every tutorial?s project something different. But however! I can pretend I meant to do this all along, and show you how to use Eclipse?s refactoring features to change a project name.

It starts off innocently enough. Right-click the project ?name.wadewalker.vbotutorial? in the package editor and select ?Refactor > Rename??.

Then change the project name to ?name.wadewalker.tutorial? and click ?OK?.

Now, no one says the package name has to match the project, but I?ve got a bit of a compulsiveness problem. To change the package name to ?tutorial?, open the ?src? directory inside the project, right-click ?name.wadewalker.vbotutorial? and select ?Refactor > Rename??.

Then change the package name to ?name.wadewalker.tutorial? and click ?OK?.

In any sane world, that would be the end of it. But there are a few more references to the old project name squirreled away! So, lemons into lemonade, et cetera—here?s how you fix those.

There are three places in the Tutorial.product file that refer to the old name. First, double-click on ?Tutorial.product? inside the ?name.wadewalker.tutorial? project, click the ?Overview? tab at the bottom, and change the product name to ?name.wadewalker.tutorial.product?.

Then change the application name to ?name.wadewalker.tutorial.application? the same way.

Click the ?Dependencies? tab at the bottom of the product editor, then select the ?name.wadewalker.vbotutorial? plugin and click ?Remove?.

Then click ?Add??, type ?name? in the filter box, select ?name.wadewalker.tutorial?, and click ?OK? to add the dependency back with the new name.

There?s one more reference to the old project name inside the plugin.xml file. Double-click ?plugin.xml? to open the plugin file editor, then click the ?Extensions? tab at the bottom, open ?org.eclipse.core.runtime.products? and select ?Tutorial (product)?. Change the application name on the right to ?name.wadewalker.tutorial.application?.

So now our project?s totally renamed, I?ve learned a lesson in thinking ahead, and you?ve learned a lesson in Eclipse refactoring. Champagne and sushi all ?round!

Side note to all you Eclipse smarty-pantses out there: if you wanted to cheat, you could have done these last few changes by closing Eclipse, editing Tutorial.product and plugin.xml in a text editor, and restarting Eclipse. But beware! Sometimes this sort of thing works fine, but other times you also have to delete your .metadata directory and recreate it by re-importing your projects to get things back in sync.

Nipping a view in the bud: Removing our simple ?view? to make way for an ?editor?

Mea culpa number two! I gotta confess to you guys, I used an Eclipse ?view? for the first tutorial because it was easy, it worked, and it kept the tutorial short so we didn?t blast apart the tender cortexes of any first-time Eclipse developers out there.

But the view wasn?t meant to be a long-term choice. Eclipse views are really supposed to show things like code outlines or object properties. There can only be one view of each type open at a time, and they usually show information about the currently selected file or object. Right now our graphical display isn?t editable, but it will be eventually, and views aren?t generally where you?re supposed to be doing your editing in an Eclipse RCP application.

An Eclipse ?editor? is what we really need for the long term. Editors can be attached to files, and they let you put buttons in the toolbar. But you need to create three Java files just to make one editor, so I had put it off until later. Well, it?s later now, babies! Time to yank off those training wheels.

First we get rid of our view?s code. Open ?src > name.wadewalker.tutorial? inside the project, then right-click ?JOGLView.java? and select ?Delete?.

When the confirmation dialog pops up, click ?OK?.

Once the view?s code is gone, we tell Eclipse not to put that view into the workspace anymore. Double-click ?Perspective.java? inside the ?name.wadewalker.tutorial? package and change the contents to look like this:

package name.wadewalker.tutorial;

import org.eclipse.ui.IPageLayout;
import org.eclipse.ui.IPerspectiveFactory;

public class Perspective implements IPerspectiveFactory {

    /*
     * Makes the editor area visible with no views.
     * @see org.eclipse.ui.IPerspectiveFactory#createInitialLayout(org.eclipse.ui.IPageLayout)
     */
    public void createInitialLayout( IPageLayout ipagelayout ) {
        ipagelayout.setEditorAreaVisible( true );
    }
}

Let?s run it and see what butchery we?ve performed on our poor app. Right-click the project ?name.wadewalker.tutorial? in the package explorer and select ?Debug As > Eclipse Application?.

Depending on your workspace, you may see this prompt to save your files. If so, check ?Always save resources before launching? and click ?OK?.

When you finally launch you?ll see an app with an empty editor area like this. It?s naked! One fig leaf, coming up.

Grafting on a new scion: We create an empty editor and let it show us nothing

The first step towards an editor is creating an empty one. To help your clicky-hands grow strong, I?ll show how to do that using the Eclipse GUI instead of by hacking file contents like a savage.

First, there?s one more bit of the view remaining: its ?metadata?. To remove it, double-click ?plugin.xml? to open the plugin file editor, then click the ?Extensions? tab at the bottom. Select ?org.eclipse.ui.views?, then click ?Remove?.

Perhaps our gentle readers would appreciate a tastevin-full of explanation for this ?metadata??

I?ll just pretend like I know what that means. You can customize Eclipse to create RCP apps in two different ways: by adding metadata to the ?plugins.xml? file, and by adding code. Some customizations, like adding a new menu item to Eclipse with a simple plugin, you can do entirely with metadata. The kind of stuff we?re doing in a full-custom RCP app mostly involves adding code.

But a downside to this metadata is that sometimes Eclipse doesn?t have a fully programmatic way to do something. In our case, creating views and editors involves both metadata and code. So as you might expect, now that we?ve removed the view?s metadata, we have to add some metadata for the editor.

Click ?Add??, then type ?org.eclipse.ui.e? in the filter box, select ?org.eclipse.ui.editors?, and click ?Finish?.

Then in the ?Extension Element Details? set the ID to ?name.wadewalker.tutorial.jogleditor?, the name to ?JOGLEditor?, the class to ?JOGLEditor?, and the contributor class to ?JOGLEditorActionBarContributor?. The result should look like this:

Now the metadata for the editor is complete, so we can write some code. Click the ?class? link, set the package to ?name.wadewalker.tutorial.jogleditor? and click ?Finish?.

This creates you a new editor class in JOGLEditor.java. Note that we put it into a separate package. That?s so we can put the other files associated with this editor in there too, for better organization.

The bare-bones editor that Eclipse creates won?t quite work on its own, we need to juice it up a bit. First, add this member into the JOGLEditor class:

    /** Workbench uses this ID to refer to instances of this type of editor. */
    public static final String ssID = "name.wadewalker.tutorial.jogleditor";

Then replace the init() method with this one:

    //================================================================
    /**
     * Initializes this editor with the given editor site and input.
     *
     * @param ieditorsite The editor site.
     * @param ieditorinput The editor input.
     * @throws PartInitException if this editor was not initialized successfully.
     * @see org.eclipse.ui.part.EditorPart#init(org.eclipse.ui.IEditorSite, org.eclipse.ui.IEditorInput)
     */
    @Override
    public void init( IEditorSite ieditorsite, IEditorInput ieditorinput ) throws PartInitException {

        setSite( ieditorsite );
        if( ieditorinput != null )
            setInput( ieditorinput );
    }

The second thing an editor needs is an ?action bar contributor?. In Eclipse-speak, a ?contributor? is a class that?s responsible for putting controls into tool bars, menus, status lines, and similar places. The action bar contributor of an editor puts the custom buttons for the editor into the app?s tool bar.

You may be asking yourself, ?Why have a whole separate class just to put buttons into the tool bar? Isn?t that kind of insane?? Well, it makes sense in the Eclipseiverse. When you?ve got a big framework like Eclipse, you want to have as much separability as possible, so you don?t have to change the whole framework to change one part. And one of the ways they do this is by defining separate class types to handle common tasks like this, so that these separate types can be changed without affecting anything else.

Our first version of the action bar contributor is just an empty shell that does nothing. To create it, navigate back to the plugin editor ?Extensions? tab, click the ?contributorClass? link, set the package to ?name.wadewalker.tutorial.jogleditor? and click ?Finish?.

OK, now the editor?s two-thirds done! But we still need one more file to make it work. See, there?s a reason we didn?t do this in the first tutorial!

The last thing we need is an input object for the editor. The input object is what the editor is editing. If this were a text editor, the input object would wrap a text file. Eventually, once our app supports graphical editing of some science-y data, we?ll store that data in a file and put that file in the input object. But for now, we can just make an empty input object.

To create the input object, right-click ?name.wadewalker.tutorial.jogleditor? in the package explorer, then select ?New > Class?.

Set the class name to ?JOGLEditorInput? and click ?Finish?.

Copy these contents into JOGLEditorInput.java. This is just enough code to get us by for now.

package name.wadewalker.tutorial.jogleditor;

import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.ui.IEditorInput;
import org.eclipse.ui.IPersistableElement;

//================================================================
/**
 * Editor input object for the JOGL editor. Currently these editors
 * aren't associated with any files, but eventually they will be.
 *
 * @author Wade Walker
 * @version 1.0
 */
public class JOGLEditorInput implements IEditorInput {

    //================================================================
    /**
     * Returns an object which is an instance of the given class
     * associated with this object. Returns null if no such object can
     * be found.
     *
     * @param classAdapter the adapter class to look up.
     * @return an object castable to the given class, or null if this
     * object does not have an adapter for the given class.
     * @see org.eclipse.core.runtime.IAdaptable#getAdapter(java.lang.Class)
     */
    @SuppressWarnings("rawtypes")
    public Object getAdapter( Class classAdapter ) {
        if( classAdapter.equals( JOGLEditorInput.class ) )
            return this;

        return null;
    }

    @Override
    public boolean exists() {
        return true;
    }

    @Override
    public ImageDescriptor getImageDescriptor() {
        return null;
    }

    @Override
    public String getName() {
        return "JOGLEditor";
    }

    @Override
    public IPersistableElement getPersistable() {
        return null;
    }

    @Override
    public String getToolTipText() {
        return "Editor that uses JOGL";
    }
}

Now that the editor?s three parts are all created, we can show the empty editor in the workbench. Later on we?ll let the user open editors on demand, but for now, we?ll open one editor when our program starts.

To do that, double-click ?ApplicationWorkbenchWindowAdvisor.java? in the package explorer and add this method.

    //================================================================
    /**
     * Performs final setup once the window is open.
     *
     * @see org.eclipse.ui.application.WorkbenchWindowAdvisor#postWindowOpen()
     */
    @Override
    public void postWindowOpen() {

        IWorkbenchWindow iworkbenchwindow = PlatformUI.getWorkbench().getActiveWorkbenchWindow();

        try {
            iworkbenchwindow.getActivePage().openEditor( new JOGLEditorInput(), JOGLEditor.ssID );
        } catch( PartInitException partinitexception ) {
            // TODO: add error handling
        }
    }

After you paste in this code, you?ll see that some of the class names have red underlines. This means they haven?t been imported yet. Another Eclipse teachable moment! Hover the mouse over each of these until the ?quick fix? window appears, then click the ?import? quick fix to add the import statement at the top of the class.

Now when you right-click the project and select ?Debug As > Eclipse Application? you?ll see an empty editor.

It looks almost exactly like the empty editor area from before, but with a tab showing the editor?s name. Now that?s progress!

The first scion bears fruit: Our new editor displays the graphics from our old view

Now we gotta get our OpenGL graphics back where they were in the last tutorial. Replace the contents of JOGLEditor.java with this:

package name.wadewalker.tutorial.jogleditor;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.FloatBuffer;
import java.util.List;

import javax.media.opengl.GL;
import javax.media.opengl.GL2;
import javax.media.opengl.GL2ES1;
import javax.media.opengl.GLContext;
import javax.media.opengl.GLDrawableFactory;
import javax.media.opengl.GLProfile;
import javax.media.opengl.fixedfunc.GLMatrixFunc;
import javax.media.opengl.glu.GLU;

import name.wadewalker.tutorial.Activator;
import name.wadewalker.tutorial.DataSource;
import name.wadewalker.tutorial.DataSource.DataObject;

import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.jface.action.IAction;
import org.eclipse.jface.bindings.keys.ParseException;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Rectangle;
import org.eclipse.swt.layout.FillLayout;
import org.eclipse.swt.opengl.GLCanvas;
import org.eclipse.swt.opengl.GLData;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Event;
import org.eclipse.swt.widgets.Listener;
import org.eclipse.ui.IActionBars;
import org.eclipse.ui.IEditorInput;
import org.eclipse.ui.IEditorSite;
import org.eclipse.ui.PartInitException;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.part.EditorPart;

import com.jogamp.common.nio.Buffers;

public class JOGLEditor extends EditorPart {

    /** Workbench uses this ID to refer to instances of this type of editor. */
    public static final String ssID = "name.wadewalker.tutorial.jogleditor";

    /** Holds the OpenGL canvas. */
    protected Composite composite;

    /** Widget that displays OpenGL content. */
    protected GLCanvas glcanvas;

    /** Used to get OpenGL object that we need to access OpenGL functions. */
    protected GLContext glcontext;

    /** Source of data to draw. */
    protected DataSource datasource;

    /** X distance to translate the viewport by. */
    protected float fViewTranslateX = 0.0f;

    /** Y distance to translate the viewport by. */
    protected float fViewTranslateY = 0.0f;

    /** Ratio of world-space units to screen pixels.
     * Increasing this zooms the display out,
     * decreasing it zooms the display in. */
    protected float fObjectUnitsPerPixel = 0.03f;

    /** Index of vertex buffer object. We store interleaved vertex and color data here
     * like this: x0, r0, y0, g0, z0, b0, x1, r1, y1, g1, z1, b1...
     * Stored in an array because glGenBuffers requires it. */
    protected int [] aiVertexBufferIndices = new int [] {-1};

    /** Constant used in FPS calculation. */ 
    protected static final long slMillisecondsPerSecond = 1000; 

    /** Number of frames drawn since last FPS calculation. */
    protected int iFPSFrames;

    /** Time in milliseconds at start of FPS calculation interval. */
    protected long lFPSIntervalStartTimeMS;

    //================================================================
    /**
     * Constructor.
     */
    public JOGLEditor() {
        datasource = new DataSource();
    }

    @Override
    public void doSave( IProgressMonitor monitor ) {
        // TODO Auto-generated method stub

    }

    @Override
    public void doSaveAs() {
        // TODO Auto-generated method stub

    }

    //================================================================
    /**
     * Initializes this editor with the given editor site and input.
     *
     * @param ieditorsite The editor site.
     * @param ieditorinput The editor input.
     * @throws PartInitException if this editor was not initialized successfully.
     * @see org.eclipse.ui.part.EditorPart#init(org.eclipse.ui.IEditorSite, org.eclipse.ui.IEditorInput)
     */
    @Override
    public void init( IEditorSite ieditorsite, IEditorInput ieditorinput ) throws PartInitException {

        setSite( ieditorsite );
        if( ieditorinput != null )
            setInput( ieditorinput );

        // create action handlers
/*        try {
            Activator.createKeyBinding(
                new IAction [] {
                    ieditorsite.getActionBars().getGlobalActionHandler( RunPauseAction.ssID ),
                }, 
                new String [] {
                    "Space",
                },
                getSite() );
        }
        catch( ParseException parseexception ) {
            throw new PartInitException( parseexception.getMessage() );
        }
        catch( IOException ioexception ) {
            throw new PartInitException( ioexception.getMessage() );
        }*/
    }

    //================================================================
    /**
     * Disposes all OpenGL resources in case this view is closed and reopened.
     * @see org.eclipse.ui.part.WorkbenchPart#dispose()
     */
    @Override
    public void dispose() {
        disposeVertexBuffers();
        glcanvas.dispose();
        super.dispose();
    }

    @Override
    public boolean isDirty() {
        // TODO Auto-generated method stub
        return false;
    }

    @Override
    public boolean isSaveAsAllowed() {
        // TODO Auto-generated method stub
        return false;
    }

    //================================================================
    /**
     * Sets up an OpenGL canvas to draw in.
     * @see org.eclipse.ui.part.WorkbenchPart#createPartControl(org.eclipse.swt.widgets.Composite)
     */
    @Override
    public void createPartControl( Composite compositeParent ) {
        GLProfile glprofile = GLProfile.get( GLProfile.GL2 );

        composite = new Composite( compositeParent, SWT.NONE );
        composite.setLayout( new FillLayout() );

        GLData gldata = new GLData();
        gldata.doubleBuffer = true;
        glcanvas = new GLCanvas( composite, SWT.NO_BACKGROUND, gldata );
        glcanvas.setCurrent();
        glcontext = GLDrawableFactory.getFactory( glprofile ).createExternalGLContext();

        glcanvas.addListener( SWT.Resize, new Listener() {
            public void handleEvent( Event event ) {
                glcanvas.setCurrent();
                glcontext.makeCurrent();
                GL2 gl = glcontext.getGL().getGL2();
                setTransformsAndViewport( gl );
                glcontext.release();
            }
        });

        glcontext.makeCurrent();
        GL2 gl = glcontext.getGL().getGL2();
        gl.setSwapInterval( 1 );
        gl.glClearColor( 1.0f, 1.0f, 1.0f, 1.0f );
        gl.glColor3f( 1.0f, 0.0f, 0.0f );
        gl.glHint( GL2ES1.GL_PERSPECTIVE_CORRECTION_HINT, GL.GL_NICEST );
        gl.glClearDepth( 1.0 );
        gl.glLineWidth( 2 );
        gl.glEnable( GL.GL_DEPTH_TEST );
        glcontext.release();

        // spawn a worker thread to call the renderer in a loop until the program closes.
        (new Thread() {
            public void run() {

                // look at the run/pause button state to see whether we should be running or not 
//                RunPauseAction runpauseaction = (RunPauseAction)getEditorSite().getActionBars().getGlobalActionHandler( RunPauseAction.ssID );

                // render once to get it on screen (we start out paused)
                render();

                try {
                    while( (glcanvas != null) && !glcanvas.isDisposed() ) {
                        // if we're running, render in the GUI thread
                        if( true /*runpauseaction.isRunning()*/ )
                            render();
                        // else we're paused, so sleep for a little so we don't peg the CPU
                        else
                            sleep( 250 );
                    }
                } catch( InterruptedException interruptedexception ) {
                    // if sleep interrupted just let the thread quite
                }
            }
        }).start();
    }

    //================================================================
    /**
     * Calculates the FPS and shows it in the status line.
     */
    protected void calculateAndShowFPS() {
        ++iFPSFrames;
        long lTime = System.currentTimeMillis();
        // update the FPS (once per second at most, to avoid flooding
        // the UI with text updates)
        long lTimeIntervalMS = lTime - lFPSIntervalStartTimeMS;
        if( lTimeIntervalMS >= slMillisecondsPerSecond ) {
            lFPSIntervalStartTimeMS = lTime;
            int iFPS = (int)((double)(iFPSFrames * slMillisecondsPerSecond) / (double)lTimeIntervalMS);
            iFPSFrames = 0;
            getEditorSite().getActionBars().getStatusLineManager().setMessage( String.format( "FPS: %d", iFPS ) );
        }
    }

    //================================================================
    /**
     * Renders into the GUI thread synchronously. Meant to be called
     * from a worker thread.
     */
    private void render() {

        PlatformUI.getWorkbench().getDisplay().syncExec( new Runnable() {
            public void run() {
                if( (glcanvas != null) && !glcanvas.isDisposed() ) {
                    glcanvas.setCurrent();
                    glcontext.makeCurrent();
                    GL2 gl2 = glcontext.getGL().getGL2();
                    gl2.glClear( GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT );
                    gl2.glClearColor( 1.0f, 1.0f, 1.0f, 1.0f );

                    // create vertex buffers if needed, then copy data in
                    int [] aiNumOfVertices = createAndFillVertexBuffer( gl2, datasource.getData() );

                    // needed so material for quads will be set from color map
                    gl2.glColorMaterial( GL.GL_FRONT_AND_BACK, GL2.GL_AMBIENT_AND_DIFFUSE );
                    gl2.glEnable( GL2.GL_COLOR_MATERIAL );

                    // draw all quads in vertex buffer
                    gl2.glBindBuffer( GL.GL_ARRAY_BUFFER, aiVertexBufferIndices[0] );
                    gl2.glEnableClientState( GL2.GL_VERTEX_ARRAY );
                    gl2.glEnableClientState( GL2.GL_COLOR_ARRAY );
                    gl2.glVertexPointer( 3, GL.GL_FLOAT, 6 * Buffers.SIZEOF_FLOAT, 0 );
                    gl2.glColorPointer( 3, GL.GL_FLOAT, 6 * Buffers.SIZEOF_FLOAT, 3 * Buffers.SIZEOF_FLOAT );
                    gl2.glPolygonMode( GL.GL_FRONT, GL2.GL_FILL );
                    gl2.glDrawArrays( GL2.GL_QUADS, 0, aiNumOfVertices[0] );

                    // disable arrays once we're done
                    gl2.glBindBuffer( GL.GL_ARRAY_BUFFER, 0 );
                    gl2.glDisableClientState( GL2.GL_VERTEX_ARRAY );
                    gl2.glDisableClientState( GL2.GL_COLOR_ARRAY );
                    gl2.glDisable( GL2.GL_COLOR_MATERIAL );

                    glcanvas.swapBuffers();
                    glcontext.release();

                    // advance time so the data changes for the next frame
                    datasource.incrementTime( 0.005 );

                    calculateAndShowFPS();
                }
            }
        });
    }

    //================================================================
    /**
     * Sets up an orthogonal projection suitable for a 2D CAD program.
     *
     * @param gl GL object to set transforms and viewport on.
     */
    protected void setTransformsAndViewport( GL2 gl2 ) {

        Rectangle rectangle = glcanvas.getClientArea();
        int iWidth = rectangle.width;
        int iHeight = Math.max( rectangle.height, 1 );

        gl2.glMatrixMode( GLMatrixFunc.GL_PROJECTION );
        gl2.glLoadIdentity();

        // set the clipping planes based on the ratio of object units
        // to screen pixels, but preserving the correct aspect ratio
        GLU glu = new GLU();
        glu.gluOrtho2D( -(fObjectUnitsPerPixel * iWidth) / 2.0f,
                         (fObjectUnitsPerPixel * iWidth) / 2.0f,
                        -(fObjectUnitsPerPixel * iHeight) / 2.0f,
                         (fObjectUnitsPerPixel * iHeight) / 2.0f );

        gl2.glMatrixMode( GLMatrixFunc.GL_MODELVIEW );
        gl2.glViewport( 0, 0, iWidth, iHeight );
        gl2.glLoadIdentity();
        gl2.glTranslatef( fViewTranslateX, fViewTranslateY, 0.0f );
    }

    //================================================================
    /**
     * Creates vertex buffer object used to store vertices and colors
     * (if it doesn't exist). Fills the object with the latest
     * vertices and colors from the data store.
     *
     * @param gl2 GL object used to access all GL functions.
     * @return the number of vertices in each of the buffers.
     */
    protected int [] createAndFillVertexBuffer( GL2 gl2, List<DataObject> listDataObjects ) {

        int [] aiNumOfVertices = new int [] {listDataObjects.size() * 4};
        
        // create vertex buffer object if needed
        if( aiVertexBufferIndices[0] == -1 ) {
            // check for VBO support
            if(    !gl2.isFunctionAvailable( "glGenBuffers" )
                || !gl2.isFunctionAvailable( "glBindBuffer" )
                || !gl2.isFunctionAvailable( "glBufferData" )
                || !gl2.isFunctionAvailable( "glDeleteBuffers" ) ) {
                Activator.openError( "Error", "Vertex buffer objects not supported." );
            }

            gl2.glGenBuffers( 1, aiVertexBufferIndices, 0 );

            // create vertex buffer data store without initial copy
            gl2.glBindBuffer( GL.GL_ARRAY_BUFFER, aiVertexBufferIndices[0] );
            gl2.glBufferData( GL.GL_ARRAY_BUFFER,
                              aiNumOfVertices[0] * 3 * Buffers.SIZEOF_FLOAT * 2,
                              null,
                              GL2.GL_DYNAMIC_DRAW );
        }

        // map the buffer and write vertex and color data directly into it
        gl2.glBindBuffer( GL.GL_ARRAY_BUFFER, aiVertexBufferIndices[0] );
        ByteBuffer bytebuffer = gl2.glMapBuffer( GL.GL_ARRAY_BUFFER, GL2.GL_WRITE_ONLY );
        FloatBuffer floatbuffer = bytebuffer.order( ByteOrder.nativeOrder() ).asFloatBuffer();

        for( DataObject dataobject : listDataObjects )
            storeVerticesAndColors( floatbuffer, dataobject );

        gl2.glUnmapBuffer( GL.GL_ARRAY_BUFFER );

        return( aiNumOfVertices );
    }

    //================================================================
    /**
     * Stores the vertices and colors of one object interleaved into
     * a buffer (vertices in counterclockwise order).
     * @param floatbuffer Buffer to store vertices and colors in.
     * @param dataobject Object whose vertices and colors are stored.
     */
    protected void storeVerticesAndColors( FloatBuffer floatbuffer, DataObject dataobject ) {

        floatbuffer.put( dataobject.getX() );
        floatbuffer.put( dataobject.getY() );
        floatbuffer.put( 0.0f );

        floatbuffer.put( dataobject.getColor()[0] );
        floatbuffer.put( dataobject.getColor()[1] );
        floatbuffer.put( dataobject.getColor()[2] );

        floatbuffer.put( dataobject.getX() + dataobject.getWidth() );
        floatbuffer.put( dataobject.getY() );
        floatbuffer.put( 0.0f );

        floatbuffer.put( dataobject.getColor()[0] );
        floatbuffer.put( dataobject.getColor()[1] );
        floatbuffer.put( dataobject.getColor()[2] );

        floatbuffer.put( dataobject.getX() + dataobject.getWidth() );
        floatbuffer.put( dataobject.getY() + dataobject.getHeight() );
        floatbuffer.put( 0.0f );

        floatbuffer.put( dataobject.getColor()[0] );
        floatbuffer.put( dataobject.getColor()[1] );
        floatbuffer.put( dataobject.getColor()[2] );

        floatbuffer.put( dataobject.getX() );
        floatbuffer.put( dataobject.getY() + dataobject.getHeight() );
        floatbuffer.put( 0.0f );        

        floatbuffer.put( dataobject.getColor()[0] );
        floatbuffer.put( dataobject.getColor()[1] );
        floatbuffer.put( dataobject.getColor()[2] );
    }

    //================================================================
    /**
     * Deletes the vertex and color buffers.
     */
    protected void disposeVertexBuffers() {
        glcontext.makeCurrent();
        GL2 gl2 = glcontext.getGL().getGL2();
        gl2.glDeleteBuffers( 1, aiVertexBufferIndices, 0 );
        aiVertexBufferIndices[0] = -1;
        glcontext.release();
    }

    @Override
    public void setFocus() {
        // TODO Auto-generated method stub

    }
}

This is almost exactly the same code that showed OpenGL in a view last time. It?s just been slightly adapted to go in an editor instead. Also, there are a few bits commented out that we?re not ready to try yet.

Now when you right-click the project and select ?Debug As > Eclipse Application? you?ll see the same animated display as in the last tutorial, but in an editor instead of a view. All this work, just to get back to where we were last time!

Grafting on a second scion: Adding a ?menu bar? to our barren application

OK, now we?re finally ready to blast ahead of where our last tutorial ended. First new feature: a menu bar! There won?t be much in it right now, but we?ve gotta start somewhere.

First we turn on the menu bar by replacing ApplicationWorkbenchWindowAdvisor.preWindowOpen() with this code.

    //================================================================
    /**
     * Configures the window before it opens.
     *
     * @see org.eclipse.ui.application.WorkbenchWindowAdvisor#preWindowOpen()
     */
    @Override
    public void preWindowOpen() {
        IWorkbenchWindowConfigurer iworkbenchwindowconfigurer = getWindowConfigurer();
        iworkbenchwindowconfigurer.setTitle( "Tutorial" );
        iworkbenchwindowconfigurer.setInitialSize( new Point( 400, 300) );
        iworkbenchwindowconfigurer.setShowMenuBar( true );
        iworkbenchwindowconfigurer.setShowCoolBar( false );
        iworkbenchwindowconfigurer.setShowStatusLine( true );
    }

Next, we need to put an ?action? into the menu so we?ll have something to click on. In Eclipse, an action is something the app does in response to user interaction. We wrap these actions up into objects, which we can put into menus and attach to buttons. In this case, we?ll use a standard ?Exit? action that Eclipse defines for us.

Replace the contents of ApplicationActionBarAdvisor.java with this code to add an ?Exit? action to the menu bar:

package name.wadewalker.tutorial;

import org.eclipse.jface.action.ICoolBarManager;
import org.eclipse.jface.action.IMenuManager;
import org.eclipse.jface.action.MenuManager;
import org.eclipse.jface.action.ToolBarManager;
import org.eclipse.ui.IWorkbenchActionConstants;
import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.actions.ActionFactory;
import org.eclipse.ui.actions.ActionFactory.IWorkbenchAction;
import org.eclipse.ui.application.ActionBarAdvisor;
import org.eclipse.ui.application.IActionBarConfigurer;

//================================================================
/**
 * Creates, adds, and disposes the actions for the workbench window.
 *
 * @author Wade Walker
 * @version 1.0
 */
public class ApplicationActionBarAdvisor extends ActionBarAdvisor {

    /** Exits the app. */
    private IWorkbenchAction iworkbenchactionExit;

    //================================================================
    /**
     * Constructor.
     *
     * @param iactionbarconfigurer Data needed to configure the action bar.
     */
    public ApplicationActionBarAdvisor( IActionBarConfigurer iactionbarconfigurer ) {
        super( iactionbarconfigurer );
    }

    //================================================================
    /**
     * Creates and registers actions.
     * 
     * @param iworkbenchwindow Window the actions are for.
     * @see org.eclipse.ui.application.ActionBarAdvisor#makeActions(org.eclipse.ui.IWorkbenchWindow)
     */
    @Override
    protected void makeActions( final IWorkbenchWindow iworkbenchwindow ) {
        iworkbenchactionExit = ActionFactory.QUIT.create( iworkbenchwindow );
        register( iworkbenchactionExit );
    }

    //================================================================
    /**
     * Puts actions into the main menu bar.
     *
     * @param imenumanagerBar The menu manager for the menu bar.
     * @see org.eclipse.ui.application.ActionBarAdvisor#fillMenuBar(org.eclipse.jface.action.IMenuManager)
     */
    @Override
    protected void fillMenuBar( IMenuManager imenumanagerBar ) {

        MenuManager menumanagerFile = new MenuManager( "&File", IWorkbenchActionConstants.M_FILE );
        imenumanagerBar.add( menumanagerFile );
        menumanagerFile.add( iworkbenchactionExit );
    }

    //================================================================
    /**
     * Puts the tool bar into the "cool bar" for the window.
     *
     * @param icoolbarmanager Used to add tool bars.
     * @see org.eclipse.ui.application.ActionBarAdvisor#fillCoolBar(org.eclipse.jface.action.ICoolBarManager)
     */
    @Override
    protected void fillCoolBar( ICoolBarManager icoolbarmanager ) {
        super.fillCoolBar( icoolbarmanager );

        ToolBarManager toolbarmanager = new ToolBarManager();
        icoolbarmanager.add( toolbarmanager );
    }
}

Now when you run the app, you?ll see a menu bar with an ?Exit? action in it. When you select it, the app exits. Hey, I never claimed this first one would set the universe on fire.

Grafting on a third scion, or, ?The Fructification?: Adding a button which runs or pauses our simulation

Eventually our app will be a full-fledged SCIENCE! program that runs some sort of physical simulation, and we?ll need a way to start and stop the simulation so we can interact with it. Ergo, a run/pause button like on an MP3 player.

To add a run/pause button to our toolbar, first we need icons to put on the button. Create a directory named ?jogleditor? inside ?name.wadewalker.tutorial\icons? to hold them.

Now, I could draw some icons myself, but that?s a one-way non-refundable ticket to Ugly App Land. Fortunately for me, there are thousands of icons inside Eclipse already, and they?re easy to get to. Unzip the file ?plugins\org.eclipse.jdt.debug.ui_3.5.0.v20100602-0830.jar? from your Eclipse installation in some convenient place. Then copy ?resume_co.gif? and ?suspend_co.gif? from the ?icons\full\elcl16? directory into our new ?name.wadewalker.tutorial\icons\jogleditor? directory.

Might we not harvest other icons from within Eclipse at a later time?

Indeed we might! Lots of the JAR files inside Eclipse contain useful icons. If you unzip them all and remove everything but the icons from the resulting directories, you?ll have quite a collection. Usually I can find what I need somewhere in there, or at least find a good starting point for a new icon.

Now that we?ve got icons on disk, we need some code to read them in, and some code to set up keyboard shortcuts for buttons. We get that by replacing Activator.java with this code:

package name.wadewalker.tutorial;

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

import javax.media.opengl.GLProfile;

import org.eclipse.core.commands.Category;
import org.eclipse.core.commands.Command;
import org.eclipse.core.commands.ParameterizedCommand;
import org.eclipse.core.commands.contexts.Context;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Status;
import org.eclipse.jface.action.IAction;
import org.eclipse.jface.bindings.Binding;
import org.eclipse.jface.bindings.Scheme;
import org.eclipse.jface.bindings.keys.KeyBinding;
import org.eclipse.jface.bindings.keys.KeySequence;
import org.eclipse.jface.bindings.keys.ParseException;
import org.eclipse.jface.commands.ActionHandler;
import org.eclipse.jface.dialogs.ErrorDialog;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.ui.IWorkbenchPartSite;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.commands.ICommandService;
import org.eclipse.ui.contexts.IContextService;
import org.eclipse.ui.handlers.IHandlerService;
import org.eclipse.ui.keys.IBindingService;
import org.eclipse.ui.plugin.AbstractUIPlugin;
import org.osgi.framework.BundleContext;

/**
 * The activator class controls the plug-in life cycle
 */
public class Activator extends AbstractUIPlugin {

    // The plug-in ID
    public static final String PLUGIN_ID = "name.wadewalker.tutorial"; //$NON-NLS-1$

    // The shared instance
    private static Activator plugin;
    
    /** Eclipse packages needed during key binding. */
    private static final String ssDefaultSchemeID = "org.eclipse.ui.defaultAcceleratorConfiguration";
    private static final String ssParentContextID = "org.eclipse.ui.contexts.window";

    /** ID and name of command category used in key binding. */
    private static final String ssCommandCategoryID = "Tutorial.commands.category";
    private static final String ssCommandCategoryName = "Tutorial commands";

    /** ID and name of command context used in key binding. */
    private static final String ssContextID = "viewerKeyContext";
    private static final String ssContextName = "In Placement Editor";

    // Needed to set up threading properly for JOGL on Linux systems. This
    // has to be done before any X11 calls, so it goes here in the class
    // Eclipse loads first.
    // NOTE: If you don't put this early enough, you'll probably get SIGSEGV
    // in libpthread.so (or other sorts of multithreading errors) when you
    // try to run the program.
    static {
        GLProfile.initSingleton();
    }

    /**
     * The constructor
     */
    public Activator() {
    }

    /*
     * (non-Javadoc)
     * @see org.eclipse.ui.plugin.AbstractUIPlugin#start(org.osgi.framework.BundleContext)
     */
    public void start(BundleContext context) throws Exception {
        super.start(context);
        plugin = this;
    }

    /*
     * (non-Javadoc)
     * @see org.eclipse.ui.plugin.AbstractUIPlugin#stop(org.osgi.framework.BundleContext)
     */
    public void stop(BundleContext context) throws Exception {
        plugin = null;
        super.stop(context);
    }

    /**
     * Returns the shared instance
     *
     * @return the shared instance
     */
    public static Activator getDefault() {
        return plugin;
    }

    /**
     * Returns an image descriptor for the image file at the given
     * plug-in relative path
     *
     * @param path the path
     * @return the image descriptor
     */
    public static ImageDescriptor getImageDescriptor(String path) {
        return imageDescriptorFromPlugin(PLUGIN_ID, path);
    }

    //================================================================
    /**
     * Returns an image descriptor for the specified icon.
     *
     * @param sIconPath Path to the icon file inside the "icons"
     * directory of the plugin project.
     * @return the image descriptor for the specified icon.
     */
    public static ImageDescriptor getIcon( String sIconPath ) {

        ImageDescriptor imagedescriptor = Activator.getImageDescriptor( "icons/" + sIconPath );
        if( imagedescriptor == null )
            imagedescriptor = ImageDescriptor.getMissingImageDescriptor();

        return( imagedescriptor );
    }

    //================================================================
    /**
     * Opens an error dialog box and logs the error.
     * @param sDialogTitle Title of dialog box.
     * @param istatus Status object to get message from.
     */
    public static void openError( String sDialogTitle, IStatus istatus ) {
        ErrorDialog.openError( PlatformUI.getWorkbench().getActiveWorkbenchWindow().getShell(),
                               sDialogTitle,
                               null,
                               istatus );
        Activator.getDefault().log( sDialogTitle + " : " + istatus.getMessage() );
    }

    //================================================================
    /**
     * Opens an "internal error" dialog box and logs the error.
     * @param exception Exception containing the message to put in the dialog box.
     */
    public static void openError( Exception exception ) {
        openError( "Internal error", new Status( Status.ERROR,
                                                 Activator.PLUGIN_ID,
                                                   exception.getMessage() != null
                                                 ? exception.getMessage()
                                                 : exception.getClass().toString() ) );
        Activator.getDefault().log( exception.getMessage(), exception );
    }

    //================================================================
    /**
     * Opens an error dialog box and logs the error.
     * @param sDialogTitle Dialog box title.
     * @param sMessage Message to put in dialog box.
     */
    public static void openError( String sDialogTitle, String sMessage ) {
        openError( sDialogTitle, new Status( Status.ERROR, Activator.PLUGIN_ID, sMessage ) );
        Activator.getDefault().log( sDialogTitle + " : " + sMessage );
    }

    //================================================================
    /**
     * Prints a message to the Eclipse log.
     *
     * @param sMessage Message to print.
     */
    public void log( String sMessage ) {
        log( sMessage, null );
    }

    //================================================================
    /**
     * Prints a message to the Eclipse log.
     *
     * @param sMessage Message to print.
     * @param exception Exception we're logging.
     */
    public void log( String sMessage, Exception exception ) {
        getLog().log( new Status( Status.INFO, PLUGIN_ID, Status.OK, sMessage, exception ) );
    }

    //================================================================
    /**
     * Creates key bindings for an array of actions, saving them to
     * the preference store if needed.
     *
     * Only creates a new key sequence if one doesn't exist for this
     * context; otherwise, leaves any altered user preferences in place.
     *
     * Takes an array so the number of writes to the preference store
     * can be minimized.
     *
     * TODO: this code is using the binding service in a way that
     * Paul Webster (the guy responsible for this part of Eclipse)
     * seems uncomfortable with, but right now there's no other option.
     * This code may be able to be replaced after Eclipse 3.4 sometime,
     * when PW finally puts in a programmatic interface for this.
     *
     * @param aiaction Actions to create key binding for.
     * @param asKey Keys to bind actions to (in the format required by KeySequence).
     * If the key string of an action is null, this method still activates
     * a handler and defines this action's command, which is needed to stop
     * some logged warnings when showing actions in menus.
     * @param iworkbenchpartsite Site to do the binding at.
     * @throws ParseException if one of the key strings can't be parsed.
     * @throws IOException if the key bindings can't be saved to the preference store.
     */
    public static void createKeyBinding( IAction [] aiaction,
                                         String [] asKey,
                                         IWorkbenchPartSite iworkbenchpartsite )
        throws ParseException, IOException {
        assert( aiaction.length == asKey.length );

        // services outside loop for speed
        IHandlerService ihandlerservice = (IHandlerService)iworkbenchpartsite.getService( IHandlerService.class );
        ICommandService icommandservice = (ICommandService)iworkbenchpartsite.getService( ICommandService.class );
        IContextService icontextservice = (IContextService)iworkbenchpartsite.getService( IContextService.class );
        IBindingService ibindingservice = (IBindingService)PlatformUI.getWorkbench().getAdapter( IBindingService.class );

        // current bindings
        Binding [] abinding = ibindingservice.getBindings();

        // new  bindings
        List<Binding> listNewBindings = new ArrayList<Binding>( 0 );

        for( int i = 0; i < aiaction.length; i++ ) {

            ActionHandler actionhandler = new ActionHandler( aiaction[i] );
            ihandlerservice.activateHandler( aiaction[i].getActionDefinitionId(), actionhandler );
    
            Category category = icommandservice.getCategory( ssCommandCategoryID );
            if( !category.isDefined() )
                category.define( ssCommandCategoryName, null );
    
            Command command = icommandservice.getCommand( aiaction[i].getActionDefinitionId() );
            if( !command.isDefined() )
                command.define( aiaction[i].getText(), aiaction[i].getDescription(), category );

            Context context = icontextservice.getContext( ssContextID );
            if( !context.isDefined() )
                context.define( ssContextName, null, ssParentContextID );

            icontextservice.activateContext( ssContextID );

            boolean bCreateNewBinding = true;

            // make sure the binding doesn't already exist for this context
            for( Binding binding : abinding ) {                    
                if(    (binding.getParameterizedCommand() != null)
                    && binding.getParameterizedCommand().getCommand().getId().equals( aiaction[i].getActionDefinitionId() )
                    && binding.getContextId().equals( ssContextID ) )
                    bCreateNewBinding = false;
            }

            if( bCreateNewBinding && (asKey[i] != null) ) {
                ParameterizedCommand parameterizedcommand = new ParameterizedCommand( command, null );
                KeySequence keysequence = KeySequence.getInstance( asKey[i] );
                listNewBindings.add( new KeyBinding( keysequence, parameterizedcommand,
                                                     ssDefaultSchemeID, ssContextID,
                                                     null, null, null,
                                                     Binding.USER ) );
            }
        }

        if( listNewBindings.size() == 0 )
            return;

        // add new bindings to current and save them
        Binding [] abindingNew = listNewBindings.toArray( new Binding [] {} );
        Binding [] abindingPlusNew = new Binding[abinding.length + abindingNew.length];

        System.arraycopy( abinding, 0, abindingPlusNew, 0, abinding.length );
        System.arraycopy( abindingNew, 0, abindingPlusNew, abinding.length, abindingNew.length );

        Scheme schemeDefault = ibindingservice.getScheme( ssDefaultSchemeID );
        ibindingservice.savePreferences( schemeDefault, abindingPlusNew );
    }
}

Now we create the action that happens when the user presses the run/pause button. Back when we put the exit action in the menu bar, we used an existing action that Eclipse defined. But this time we have to make our own action from scratch.

Right-click ?name.wadewalker.tutorial.jogleditor? in the package explorer, then select ?New > Class?. Set the class name to ?RunPauseAction? and click ?Finish?.

Replace the contents of RunPauseAction.java with this code:

package name.wadewalker.tutorial.jogleditor;

import name.wadewalker.tutorial.Activator;

import org.eclipse.jface.action.Action;

//================================================================
/**
 * Runs or pauses the simulation on alternate button presses.
 * Changes the picture and tooltip of the button accordingly.
 *
 * @author Wade Walker
 * @version 1.0
 */
public class RunPauseAction extends Action {

    /** Unique action ID for the Eclipse platform. */
    public static final String ssID = "JOGLEditor.RunPauseAction";

    /** True if the simulation is running, false if it's paused. */
    private boolean bRunning = false;

    //================================================================
    /**
     * Constructor.
     */
    public RunPauseAction() {
        super( "Run", Action.AS_PUSH_BUTTON );
        setToolTipText( "Run simulation" );
        setImageDescriptor( Activator.getIcon( "jogleditor/resume_co.gif" ) );
        setId( ssID );
        setActionDefinitionId( ssID );
    }

    //================================================================
    /**
     * Code to run the action.
     *
     * @see org.eclipse.jface.action.Action#run()
     */
    @Override
    public void run() {
        if( bRunning ) {
            setToolTipText( "Run simulation" );
            setImageDescriptor( Activator.getIcon( "jogleditor/resume_co.gif" ) );
        }
        else {
            setToolTipText( "Pause simulation" );
            setImageDescriptor( Activator.getIcon( "jogleditor/suspend_co.gif" ) );
        }
        bRunning = !bRunning;
    }

    //================================================================
    /**
     * Accessor.
     * @return true if the simulation is running, false otherwise.
     */
    public boolean isRunning() {
        return( bRunning );
    }
}

Turn on the toolbar by changing one line in ApplicationWorkbenchWindowAdvisor.preWindowOpen() to this:

        iworkbenchwindowconfigurer.setShowCoolBar( true );

Now finally we can finish the action bar contributor for our editor and make it add our new button to the tool bar. Replace the contents of JOGLEditorActionBarContributor.java with this code:

package name.wadewalker.tutorial.jogleditor;

import org.eclipse.jface.action.IToolBarManager;
import org.eclipse.ui.IActionBars;
import org.eclipse.ui.IWorkbenchPage;
import org.eclipse.ui.part.EditorActionBarContributor;

//================================================================
/**
 * Contributes the JOGLEditor's actions to the action bar.
 *
 * @author Wade Walker
 * @version 1.0
 */
public class JOGLEditorActionBarContributor extends EditorActionBarContributor {

    /** Runs and pauses the simulation. */
    private RunPauseAction runpauseaction;

    //================================================================
    /**
     * Constructor. Creates the actions.
     */
    public JOGLEditorActionBarContributor() {
        runpauseaction = new RunPauseAction();
    }

    //================================================================
    /**
     * Registers action handlers.
     *
     * @param iactionbars Used to register global actions.
     * @param iworkbenchpage Used to set part listeners.
     * @see org.eclipse.ui.part.EditorActionBarContributor#init(org.eclipse.ui.IActionBars, org.eclipse.ui.IWorkbenchPage)
     */
    @Override
    public void init( IActionBars iactionbars, IWorkbenchPage iworkbenchpage ) {
        super.init( iactionbars, iworkbenchpage );

        // register handlers
        iactionbars.setGlobalActionHandler( RunPauseAction.ssID, runpauseaction );
    }

    //================================================================
    /**
     * Contributes the editor's actions to the tool bar.
     *
     * @param itoolbarmanager Used to add actions to the editor tool bar.
     * @see org.eclipse.ui.part.EditorActionBarContributor#contributeToToolBar(org.eclipse.jface.action.IToolBarManager)
     */
    @Override
    public void contributeToToolBar( IToolBarManager itoolbarmanager ) {
        itoolbarmanager.add( runpauseaction );
    }
}

To let the editor use the new action, comment in the block of code at the end of JOGLEditor.init() and the two lines in JOGLEditor.createPartControl().

From viniculture to oenology: Savoring our completed vintage

Now when you run the app, you can see a ?Run simulation? button in the toolbar, complete with tooltip and keyboard shortcut.

When you click the ?Run simulation? button or press the space bar, the animation begins, the frame rate climbs to its max, and the button icon and tooltip change to ?Pause simulation?.

Clicking or pressing the space bar again pauses the simulation. Here?s what our app looks like in Linux:

And there you have it! A complete app that lets you start, stop, and exit in a civilized way.

Resources which the reader may find helpful

Eclipse: At http://wiki.eclipse.org/index.php/Eclipse_FAQs there?s a ton of information about Eclipse, including definitions of confusing Eclipse terms.

Eclipse RCP: At http://wiki.eclipse.org/RCP they?ve got a long list of resources that will help with Eclipse RCP programming.

A list of the revisions which we have made to this document

12/06/2010: Wrote the first version.

12/11/2010: Fixed the Tutorial.project file to remove outdated reference to “vbotutorial”.

Version 2.2.0

admin — Sat, 20 Nov 2010 22:57:45 GMT

The new version, 2.2.0, features convex hull and convex decomposition algorithms. Intended for use during runtime or for pre-processing. See the javadocs for more details.

When running you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today…

The "Decompose" test from the TestBed

All the releases require Java 1.6+. Be sure to type the “c” key to get the TestBed Control Panel so you can play with the simulator.

Tutorial: Creating native binary executables for multi-platform Java apps with OpenGL and Eclipse RCP

Wade Walker — Mon, 25 Oct 2010 03:02:52 GMT

Greets to my peeps, and to eybody reppin? the 512! Wade Walker back in the house, and hype for some third-time tutorialization.

I also return to the dwelling! Debonair of aspect, felicitous of phrase: ?Stitio? is my nom-de-guerre!

Hey, did I miss something? I thought your name was ?Interstitius? or something Latiny like that.

?Interstitius? was not so swashbuckling as I had hoped. This shorter, Italianate version should manifest my dashing and adventurous persona to any pulchritudinous lady-beings who may chance upon these writings.

That kind of sounds like you?re an alien AI impersonating a Renaissance Italian Musketeer.

Even so! You have seized upon the very crux of my intent!

People keep telling me that.

So! In our last tutorial, me and the mutably-named Stitio showed how to speed up the rendering in our cross-platform scientific application by using OpenGL?s vertex buffer objects.

This time, we?ll show you how to create true native binaries for these sorts of Eclipse RCP apps. This lets you distribute them the same way as non-Java apps, so you don?t have to use wrapper scripts or other hackery.

Ante-ante-prelude: An overview of how ?Java apps? are normally launched

When you compile a Java app, it?s turned into .class files, one per Java class. Eclipse puts them into the ?bin? or ?classes? directory inside the project directory. Here are the .class files for our previous tutorial:

These files are full of platform-independent Java byte code that the Java virtual machine (JVM) interprets. To run an app that?s compiled into a directory of files like this, you have to type

java ?classpath MyClassDir MyMainClassName

But some users are gonna be put off by this. It would be nicer if you could just double-click ?MyApp.exe? to run, like for a normal app.

We can get closer to that by packaging our .class files into a single JAR (Java ARchive) file. Here?s how you do it:

jar cfm MyApp.jar MyMainClassName MyClassDir/*.class

This makes a single .jar file containing all your .class files, with a ?manifest? file inside that tells Java which class is your main class. Then you run it like this

java -jar MyApp.jar

Or on Windows if you have a Java Runtime Environment (JRE) installed, you can just double-click the JAR file and Windows will add in the java -jar for you.

They call these kinds of .jar files ?executable JARs?, but they?re not native binary executables, they?re really just zip files full of .class files. And this type of JAR can?t hold the native libraries that are in Java OpenGL, because those libraries have to be sitting on the file system separately so the operating system can see them.

Ante-prelude: How might one create a ?Java native binary??

Well, there?s no way to do it by using the ?java? and ?jar? commands that come with a Java installation. You have to use some third-party system. If we weren?t already using Eclipse, we might use something like launch4j or JSmooth.

But! Eclipse itself comes as a native binary, and it has its own built-in system that lets you create similar ones for your Eclipse RCP apps. Take a look at the Eclipse installation:

You can see there?s a small native binary, ?eclipse.exe?, plus a bunch of directories. These directories contain all the JAR files and other stuff that?s part of Eclipse. When you run ?eclipse.exe?, it finds the JRE on your system, unpacks any native libraries into its ?configuration? directory, shows a splash screen, then runs java -jar SomeEclipseJARFile.jar for you.

But why is there so much stuff in this installation directory? It?s possible to make a Java native binary that?s one single executable file: an executable header with the JAR file appended. So why doesn?t Eclipse do it like that?

Several reasons. First, having a ?plugins? directory lets you drop additional JARs into the installation. You need to do this if your app is something like Eclipse, where you can download and install new features over time.

Second, if your app contains native libraries (.dll or .so files), they need to be unpacked and written out as separate files before the operating system can load them. Eclipse does that for you, and hides them down inside the ?configuration? directory.

Third, the ?eclipse.ini? file let users pass extra startup arguments to the app or the JVM without having to put them on the command line every time.

And fourth, you can include a ?jre? directory in the installation that makes your app completely independent of any Java installation on the host computer.

So, bottom line: Eclipse?s native binary system is complex, but gives you lots of options and room to grow your app into something bigger later on.

Prelude: We augment our Eclipse installation

Eclipse can already export native binaries for the platform you?re running it on. But if you want to export native binaries for all the other platforms at the same time, you have to install the Eclipse Delta Pack. To find it, start at the Eclipse download site and click the ?Other Downloads? link under ?Eclipse Classic?.

Then click the version of Eclipse you?ve got installed under ?Build Name?. I?ve got version 3.6.1 installed.

Then finally click on the delta pack download link. The one I got was ?eclipse-3.6.1-delta-pack.zip?.

Unzip this file where you want to install the delta pack. I put it beside my Eclipse installation and called it ?eclipse-3.6.1-delta-pack?. You can also unzip it directly onto your Eclipse installation, but everyone seems to advise against that. Here?s how mine looks.

We still have to tell Eclipse where to find the delta pack, but we can?t do that until we set up our workspace, since Eclipse stores that setting in your workspace?s ?.metadata? directory.

Intermezzo: For expediency?s sake, we re-use our previous project

We?ll use our previous masterwork as a starting point. First, create a new workspace directory and unzip this file and this file from the last tutorial into it. Then follow the instructions from the last tutorial to import those projects into your workspace.

Or, as usual, if you just wanna skip to the end of this tutorial without all the typing and clicking, create your new workspace directory and unzip this file and this file into it, then import the projects. You?ll still have to point Eclipse at your delta pack, though.

Entremet: We inform Eclipse as to the location of our ?delta pack?

Now that we have a workspace to store these settings, click ?Window > Preferences? from the menu, open ?Plug-in Development? on the left, click ?Target Platform?, and select the ?Running Platform? on the right. Then click ?Edit??.

When the ?Edit Target Definition? dialog appears, click ?Add??.

Then select ?Directory? and click ?Next?.

Enter the directory where you put the delta pack. Mine is right beside Eclipse, so I can do it like this: ?${eclipse_home}\..\eclipse-3.6.1-delta-pack?. Then click ?Finish?.

Now you should see the delta pack in your platform like this. Click ?Finish? again.

Finally, click ?OK? to dismiss the Preferences dialog. Eclipse will grind for a moment, then the delta pack is in! Just remember, if you make a new workspace later, you gotta do this again.

Opus: The creation of our ?product?

Now we tell Eclipse what it needs to know to export our tutorial as native binaries. Right-click the ?name.wadewalker.tutorial? project in the Package Explorer and select ?New > Product Configuration?. Enter ?Tutorial? as the file name, then click ?Finish?.

This creates a new file ?Tutorial.product? in the ?name.wadewalker.tutorial? directory. This file will hold all the settings we need to export native binaries. It should look like this to start with:

Now change the version to ?1.0.0?. Click the ?Application? drop-down and select ?name.wadewalker.vbotutorial.application?.

Then click the ?Launching? tab at the bottom of the Tutorial.product window. Enter ?Tutorial? as the launcher name.

Then click the ?Overview? tab to go back, and click the ?Eclipse Product export wizard? link to start the native binary export.

When the export wizard comes up, set the root directory to ?bin?. Then set the destination to an empty directory where you want the native binaries to go. I put mine in a directory called ?installation? beside the workspace, but it can be anywhere. Minor annoyance: this apparently has to be an absolute path. Then check the ?Export for multiple platforms? box and click ?Next?.

Check the boxes of the platforms you want to export to. I?m doing Linux GTK 32- and 64-bit, Mac OS X Cocoa 64-bit, and Windows 32- and 64-bit. I don?t have a way to test the Mac version right now, but we can at least see that it exports. Click ?Finish? to start the export process.

Exporting takes a minute or so, but once it?s done you should see this in your destination directory:

There?s one directory per platform, and one common ?repository? that holds JARs and other files that are the same for all platforms. If you look down inside the ?win32.win32.x86_64\bin? directory, you?ll see an installation that looks just like Eclipse:

Double-click on that executable, and pow! Here?s the binary running on Windows 7 64-bit:

And onomatopoeia! Here it is on CentOS 5.4 64-bit:

Now you can write one Java OpenGL app, export it, and get native binaries for five different platforms at once. And that, my friends, is super-genius-ness in action!

Postlude: Where further customization is left for your amusement, chiefly due to our laziness

You can see from all the tabs and fields of the ?Tutorial.product? file that there?s a lot more customization you can do. You can put in a custom splash screen, custom icon, custom JVM arguments, and a lot more.

One thing that doesn?t work right as of Eclipse 3.6.1 is the ?Bundle JRE for this environment with the product? check box on the ?Launching? tab of ?Tutorial.product?. If you check the box, re-export, and compare the exported product to the one you had before, you?ll see they?re freaken identical.

But then we open up the smartness hose on this problem. Find the JRE directory of your system?s Java installation, which looks like this:

Create a new directory in your app?s installation (under the same platform as your system) and name it ?jre?. Then copy the contents of the above JRE directory into it. Now that platform in your installation should look like this:

And now when you double-click your ?Tutorial.exe?, it will use the ?java.dll? and ?jvm.dll? from this new ?jre? directory instead of using your system?s installation of the JRE. I?ve confirmed this with Windows Process Explorer, and I?ve done it on Linux the same way. The Eclipse launcher always looks here first, so we?re just putting a JRE right where it expects to find one.

I usually put this annoying little step in an installation script. I custom-made a zipped JRE for each platform, and I have the script unzip them into the right directories during the install process.

Resources which the reader may find helpful

Windows Process Explorer: Get it here. It helps verify that you?re really getting the JRE from where you think you are. It?s also handy for seeing where the JOGL DLLs get unpacked to.

Eclipse product configurations: There?s a tutorial from Lars Vogel here that has more details than I give.

A list of the revisions which we have made to this document

10/24/2010: Wrote the first version.

10/25/2010: Fixed the links to full-sized images.

11/19/2010: Added a link to the completed version of this tutorial.

Tutorial: Faster rendering with vertex buffer objects

Wade Walker — Sun, 17 Oct 2010 22:06:07 GMT

Hi again! Wade Walker here: engineer, would-be scientist, and second-time tutorializer.

I return as well! Dashing being-about-town and nascent heading-writer ?Interstitius?, at your service

What can I say?he brings a unique sensibility to his work. Anyway, in our last tutorial, me and Stish showed how to create the skeleton of a scientific app using Eclipse RCP and Java OpenGL (JOGL, which I like to pronounce ?joggle?).

This time, I?ll show how to speed up rendering by using OpenGL?s ?vertex buffer objects? instead of glBegin and glEnd like we did last time. I?ll also keep evolving the tutorial towards a ?real? scientific app by making the data source more like scientific data.

Science, ho!

Formerly our method of drawing was easy, but slow

This is how you draw one quadrilateral (what we call a ?square?, ?rectangle?, ?trapezoid?, or ?rhombus? in English, except that the last two are technically Greek) in old-style OpenGL:

glBegin( GL_QUADS );
    glVertex3f( -1.0f, 1.0f, 0.0f );    // top left
    glVertex3f( 1.0f, 1.0f, 0.0f );     // top right
    glVertex3f( 1.0f,-1.0f, 0.0f );     // bottom right
    glVertex3f( -1.0f,-1.0f, 0.0f );    // bottom left
glEnd();

Perfectly straightforward ? it draws one quad, which has four vertices, as quads often do. Easy to understand, easy to write. So why not do everything like this?

In a somewhat predictable inversion, our new method is difficult, but fast

Here?s why we can?t: in a real app, you?ve got a huge mess of stuff between glBegin and glEnd, and the OpenGL driver will struggle to optimize it into something efficient that it can send to the graphics card. Sometimes this works OK, but other times the driver can?t handle it well, and the result is something that?s correct, but slow.

Here?s how we fix it. We create a vertex buffer object, which is just a big chunk of memory that holds the objects we want to draw. Then we send it to our graphics card all at once, where it gets drawn super-fast by dedicated hardware.

The new hotness of vertex buffer objects makes you do all the hard work of setting up your object data in the exact format that the graphics card can process the fastest. So at the price of a few extra drops of programmer brain-juice, your users get faster graphics. And everyone?s happy!

I won?t show an example yet, because it?s too ugly to put first thing in the tutorial. Just hold on to that dream of gloriously fast graphics while we set up this new project.

Importing all of one?s projects at a stroke

This time instead of crawling through the tutorial one file at a time, I zipped up all the projects so you can slurp them into Eclipse all at once.

Download this file and this file, rename them so they end with ?.zip? instead of ?-zip-not-a.doc?, and unzip them inside an empty folder that you?ll use as a new Eclipse workspace. Then start Eclipse, select ?File > Switch Workspace > Other??, browse to your new workspace folder, and click ?OK?. If you see the welcome screen, click the ?Workbench? button on the right to go past it.

?Then select ?File > Import?? from the main menu, select ?Existing Projects into Workspace?, and click ?Next?.

Click ?Browse??, navigate to your workspace folder, and click ?OK?. Then you should see these seven projects. Click ?Finish? to import them into your workspace.

The word ?import? is a little misleading here, since the projects were already in your workspace folder. What happened just then was Eclipse wrote into its ?.metadata? folder inside the workspace folder, to tell itself which projects are in the workbench. The next time you open Eclipse, you should see the same projects again.

A rather unsporting leap forward to reveal this tutorial?s outcome

Let?s run the tutorial first to see what it does, then I?ll go back and explain it. After importing the projects, you should be seeing this:

Now right-click on ?name.wadewalker.vbotutorial? in the ?Package Explorer? view on the left, then select ?Run As > Eclipse Application.? Now bask in the glory of vertex buffer objects! Yes, bask!

Perhaps a bit of explanation is needed for this rather uninspiring image?

I?m on it. This is supposed to approximate what a scientific visualization program might do. The sine wave on screen is made of 300,000 skinny vertical quads of different colors. The quads are stationary, but they?re constantly changing size to make the sine wave look like it?s moving. The ?frames per second? (FPS) counter in the bottom left shows you how fast your system can render this demo. The code that creates this data is in DataSource.java.

Before an actual scientist VR-stabs me over the internet, let me say that of course no scientist would need to visualize something so simple. Because they?re all ?ber-geniuses! But this demo is to show us how to program, not how to drop science. The point is that we have a source of data that?s constantly changing, and we have to throw it up on screen as it evolves.

So how does it work?

Creating a vertex buffer object ex nihilo

Technically it?s not created from nothing, it?s created from electrons, smarty-shorts. To see how, open up the ?name.wadewalker.vbotutorial? project in the Package Explorer on the left, then drill down to ?src/name.wadewalker.vbotutorial?, double-click on ?JOGLView.java?, and scroll to this part.

//================================================================
/**
 * Creates vertex buffer object used to store vertices and colors
 * (if it doesn't exist). Fills the object with the latest
 * vertices and colors from the data store.
 *
 * @param gl2 GL object used to access all GL functions.
 * @return the number of vertices in each of the buffers.
 */
protected int [] createAndFillVertexBuffer( GL2 gl2, List<DataObject> listDataObjects ) {

    int [] aiNumOfVertices = new int [] {listDataObjects.size() * 4};
        
    // create vertex buffer object if needed
    if( aiVertexBufferIndices[0] == -1 ) {
        // check for VBO support
        if(    !gl2.isFunctionAvailable( "glGenBuffers" )
            || !gl2.isFunctionAvailable( "glBindBuffer" )
            || !gl2.isFunctionAvailable( "glBufferData" )
            || !gl2.isFunctionAvailable( "glDeleteBuffers" ) ) {
            Activator.openError( "Error", "Vertex buffer objects not supported." );
        }

        gl2.glGenBuffers( 1, aiVertexBufferIndices, 0 );

        // create vertex buffer data store without initial copy
        gl2.glBindBuffer( GL.GL_ARRAY_BUFFER, aiVertexBufferIndices[0] );
        gl2.glBufferData( GL.GL_ARRAY_BUFFER,
                          aiNumOfVertices[0] * 3 * Buffers.SIZEOF_FLOAT * 2,
                          null,
                          GL2.GL_DYNAMIC_DRAW );
    }

    // map the buffer and write vertex and color data directly into it
    gl2.glBindBuffer( GL.GL_ARRAY_BUFFER, aiVertexBufferIndices[0] );
    ByteBuffer bytebuffer = gl2.glMapBuffer( GL.GL_ARRAY_BUFFER, GL2.GL_WRITE_ONLY );
    FloatBuffer floatbuffer = bytebuffer.order( ByteOrder.nativeOrder() ).asFloatBuffer();

    for( DataObject dataobject : listDataObjects )
        storeVerticesAndColors( floatbuffer, dataobject );

    gl2.glUnmapBuffer( GL.GL_ARRAY_BUFFER );

    return( aiNumOfVertices );
}

First we create a vertex buffer object with glGenBuffers, then do a glBufferData to allocate the size we want. Every vertex needs three floats for the position (x, y, z), and three more for the color (r, g, b). Then we use glMapBuffer to get an object we can write into, we write all our floats into it, then we call glUnmapBuffer to finish.

Might you explain why both colors and vertices are placed into a so-called ?vertex buffer??

Aha, good point! It?s true that in math, a ?vertex? is really just a point where lines meet, but in computer graphics we can also consider the color to be a part of the vertex. There can be more stuff in a vertex too, like the normal vector, texture coordinates, and other things we don?t need yet. So ?vertex buffer? isn?t really a misnomer.

Why, then, do we interdigitate the positions and colors? Could we not write all of one, then all of the other?

Alternating positions and colors in a single vertex buffer speeds things up by preserving data locality. When you write the data into the buffer, you don?t want to be writing to two widely separated addresses, because your computer?s memory system isn?t good at that.

Similarly, if the graphics card has to fetch the positions from one address in memory and the colors from a very different address to render each triangle, it?s gonna be slower than if all the data for that triangle is close together.

I originally used separate position and color buffers for this tutorial, and when I switched to one ?interdigitated? buffer, I got a 5% to 10% increase in frame rate.

Rendering one?s vertex buffer

Here?s the code to draw the vertex buffer we just created, also in JOGLView.java:

// needed so material for quads will be set from color map
gl2.glColorMaterial( GL.GL_FRONT_AND_BACK, GL2.GL_AMBIENT_AND_DIFFUSE );
gl2.glEnable( GL2.GL_COLOR_MATERIAL );

// draw all quads in vertex buffer
gl2.glBindBuffer( GL.GL_ARRAY_BUFFER, aiVertexBufferIndices[0] );
gl2.glEnableClientState( GL2.GL_VERTEX_ARRAY );
gl2.glEnableClientState( GL2.GL_COLOR_ARRAY );
gl2.glVertexPointer( 3, GL.GL_FLOAT, 6 * Buffers.SIZEOF_FLOAT, 0 );
gl2.glColorPointer( 3, GL.GL_FLOAT, 6 * Buffers.SIZEOF_FLOAT, 3 * Buffers.SIZEOF_FLOAT );
gl2.glPolygonMode( GL.GL_FRONT, GL2.GL_FILL );
gl2.glDrawArrays( GL2.GL_QUADS, 0, aiNumOfVertices[0] );

// disable arrays once we're done
gl2.glBindBuffer( GL.GL_ARRAY_BUFFER, 0 );
gl2.glDisableClientState( GL2.GL_VERTEX_ARRAY );
gl2.glDisableClientState( GL2.GL_COLOR_ARRAY );
gl2.glDisable( GL2.GL_COLOR_MATERIAL );

glcanvas.swapBuffers();

We use glVertexPointer and glColorPointer to set the starting positions in the buffer, with the first color pointer three floats after the first position. Then we tell the graphics card that each new position and color is six floats past the current one. We call that a ?stride? of six floats, which is 24 bytes. Then finally we draw the whole buffer full of quads with just one command, glDrawArrays.

What, then, is the benefit of all our labors?

I did this tutorial with glBegin/glEnd first, as a test. When I switched to a vertex buffer, the frame rate increased by 100%.

And this is a worst-case scenario, too. In many apps, most of the scene will be constant from one frame to the next, so we can just move the viewpoint and call glDrawArrays again without changing the vertex buffer at all.

As a test, I changed the tutorial code to only write the vertex buffer once, and the frame rate jumped from 14 to 25. So vertex buffers are almost 200% faster than glBegin/glEnd for this more common situation.

Might we run faster still?

There are 600K triangles here (2 per quad), and at 14 FPS, that?s 8.4 million triangles per second. With the vertex buffer written only once, we get 25 FPS, or 15M tris/sec.

I downloaded the NVIDIA performance tools and profiled a couple of C++ DirectX demos that come with them. One got 5.7M tris/sec, and one got 8.4M tris/sec. They had texturing and other effects turned on, so their rendering isn?t as simple as ours, but their triangle rates seem comparable.

But! When I look at the theoretical maximum speed, things aren?t so clear. My graphics card is an NVIDIA GeForce 8800 GTX, which can supposedly do 250M tris/sec on the 3DMark06 benchmark. That would give 417 FPS on our tutorial! Why is 3DMark06 16 times faster than us?

A few thought-experiments as to how our speed could be increased

Part of it may be the geometrical primitives 3DMark06 is rendering. We?re rendering quads, which have four vertices for two triangles, which means two vertices per triangle. If we jumped ahead in the OpenGL playbook and used triangle strips instead, we could get that down to one vertex per triangle, which could double our frame rate.

But we need to double our rate three more times to get to that theoretical max. If we removed the color information and just drew all the triangles in the same color, we could halve the size of our vertices and maybe double the speed again.

But how do we double it two more times? No clue.

Maybe changing the vertex buffer every frame is saturating the bus between my computer and the video card? Let?s check.

My video card is designed for an x16 PCI Express 1.x slot, which is rated at 4GB/sec. In this tutorial, each vertex buffer is (300,000 quads) * (4 verts/quad) * (6 floats/vert) * (4 bytes/float) = 28,800,000 bytes. At 14 FPS, that?s 403,000,000 bytes/sec, which is only about 10% of our bus capacity. So that can?t be the problem.

Hmm, I?m out of ideas for the moment. But handing back my super-genius credentials isn?t an option, so I?ll look into this and cover it in a future tutorial.

Resources which the reader may find helpful

OpenGL tutorials: Check out http://nehe.gamedev.net/. These go over OpenGL more slowly and thoroughly than I do, and are recommended.

The OpenGL Programming Guide, n^th edition: You can buy it for about $50 on Amazon. It?s definitive, but not exactly a tutorial. The style of OpenGL I?ve used so far is actually 1.5 to 2.0, not the latest 4.1 stuff, so make sure to get a book about the version you want.

Basic documentation: At http://www.opengl.org/ you can find docs for the C API calls. The ones in JOGL are Java-fied, but you can usually tell how to translate one to the other.

A list of the revisions which we have made to this document

10/17/2010: Wrote first version.

10/23/2010: Updated to split the zip file and include JOGL for multiple platforms.

10/26/2010: Fixed the links to full-sized images.

MM Adaptive Rendering using JOGL and Newt

Rami — Mon, 11 Oct 2010 10:31:00 GMT

Was working recently on creating an adaptive renderer, using JOGL. The goal of this project was to ensure high frame rate and usability while walking thru a model of a large data set. Ideally, containing approx. a million+ complex geometric objects. What follows is a description on how it was done. (you might see this as lengthy or over simplified…depends)

Before I go into the details, lets see what is required to achieve a “good” adaptive rendering for massive model visualization (MMV).

What is required:
1- Ability to navigate smoothly within the large data set
2- Renderer can hide objects to speed the rendering.
3- At any point, near objects should always be visible and in high resolution
4- When navigation stops, hidden objects should be re-shown.
5- Keep CPU/GPU usage to minimum when navigation is stopped.
6- Don’t block the application when re-showing objects on scene.

A bit of background, the application uses AWT and Swing for Interface, and JOGL for rendering. Using an AWT canvas to do this doesnt work since (6) would need to be compromised since AWT treats the display as another UI.
With the addition of Newt – AWT parenting added to JOGL 2, We can go ahead and render in an independent thread which is independent of the AWT EDT. This takes care of (6)

Now to the rest. To ensure high frame rate we will need to hide objects while rendering, In a large model we will for sure have a lot of occluded objects which at any point can reduce the number of objects drawn on scene. And also depending on the occlusion results u can know approx. how many fragments resulted from each object.

Using this information you can sort your objects depending on the occlusion result. You can do this on every frame (using two pass rendering) if you have time or every couple of frames if you need every ms (which is usually the case). If you have objects that require to be rendered in the end, like transparent objects, a separate list is needed. This ensures (3) since near objects will have high fragment count. Large objects in scene will also have high fragment count, which is a plus to always have large object shown giving the general structure of the scene helping in user orientation.

We create a threshold value set to the minimum fragment count to render. This threshold will stop rendering the objects once we reach an object with fragment_count less than the threshold. An initial value can be set by statistical computations of fragment counts, like median, avg, or min value. In our case, chose a value between avg and min.

Using this threshold, and our statistical fragment count curve, which tell us approx how much objects will be hidden, we can choose the best new threshold. The curve is used to create a smooth hiding and showing of objects.

With this information and the current fps we can render the scene.

During navigation, at each frame we update the threshold to reach the required fps, this is done using a convergence approach of the threshold on the curve with respect to the desired fps. A convergence approach since you cant reach a stable desired fps in a linear manipulation of the threshold.

When navigation stops, in each frame we move gradually the threshold to its min value. (disable occlusion tests in this stage since viewpoint wont be changed)

To ensure (1), we move the camera based on fps ensuring that we will rotate, move:? x and y steps per second where x and y are application defined.

This ensures that the navigation is consistent.
Now we have all the modules, we need now an animator that puts all these together and ensures (5).
a high level pseudo code for the? animator is shown below:

while(shouldNotStop){
if(!animate and !popingup){
lock.wait() // pauses the animator – ensuring (6)
}

—render with current threshold (two or single pass)

// update camera position and orientation if needed
// returning if navigation is still active (stooped or not)
animate = navigationMode->continueNavigation

if(!animate) {
// start poping up the objects until all objects that are no totally occluded
// are rendered
popingup = renderer ->popupObjects
}

Hope you find this useful!

Tutorial: A cross-platform graphical application using Java, OpenGL, and Eclipse

Wade Walker — Sat, 09 Oct 2010 13:57:21 GMT

Hi! My name?s Wade Walker. I?m an engineer and wanna-be scientist.

And you may call me ?Interstitius?. I am something of a Renaissance-being, but my current occupation is penning the headings between these paragraphs.

Yeah, that doesn?t come across weird at all! But this guy comes highly recommended, so I figured I?d give him a try. What?s with the name, anyway?

It is a Latinate nom de plume, of course. I thought it dashing and flamboyant, much like myself.

Um, OK sure. Don?t ask questions you don?t want answered, et cetera. Anyway moving on!

At my day job, I write engineering apps that help chip designers make the chips that go into all your iStuff. But by night, and also on weekends, I write scientific apps as a hobby. And before anyone asks: no, I don?t live in my mom?s basement. Trust me, I?m perfectly normal. Except for writing science apps.

I?m gonna write a set of tutorials that walk you through creating a cross-platform graphical app using Java, OpenGL, and the Eclipse Rich Client Platform (?Eclipse RCP? for short). There are lots of other ways to do this, like with C++ and Qt, but I?m lazy and I figured I?d stick with what I know.

What do I get out of this? Glad you asked!

No one has asked anything as yet.

Dude, that?s just for color. Not supposed to be literal. Anyway, what I get out of tutorializing is this: I?m in the process of translating my hobby science app from C# and DirectX to Java and OpenGL. So I figured I might as well write up how I do it, and maybe help out some other folks in the process.

In this first tutorial, I?ll make a bare-bones app that draws a rotating 3-D demo object in a window using Java OpenGL (JOGL).

A brief description of the intended audience of this tutorial

Nice heading, I-dog! Just keep ?em punchy like that and you?ll do great.

I?m aiming these tutorials at people who want to write cross-platform graphical ?workbench? apps, the kind where users create some kind of project and edit it interactively using 3D hardware-accelerated graphics. Apps like this are common in the sciences, in engineering, and in the graphic arts.

You should be able to do these tutorials if you?ve got a bit of software dev experience, but you don?t need any prior exposure to Java, Eclipse, or OpenGL. I?ll give you working code for each tutorial that you can adapt and use for whatever you want. Then you can gradually figure out how it works as you customize it.

Java, Eclipse, and OpenGL are all super-deep neck-beard topics that take years of study to master, so don?t feel like you need to totally comprehend every bit of these tutorials the first time you see them. My main point in putting them up here is to give you working starting points for your own stuff and to get you past some common roadblocks, not to instantly transmute you into a super-genius like me.

Quick pro tip for any eager beavers out there: If you already know how to set up an Eclipse workspace and just want to see the money shot, here?s a zip file of the JOGL projects, and here?s another zip file for the tutorial project. Just change the file names to end in ?.zip? instead of ?-zip-not-a.doc?, unzip them, import them into Eclipse, and go nuts!

Now, let?s do this!

Put ?Java? and the ?Eclipse development environment? in order

If you don?t already have it, download and install the Standard Edition of the latest Java Development Kit (the Java SE JDK) from here. When I downloaded it, the latest version was JDK 7 update 4. You?ll have to pick the platform you?re running on, too. I?m running Windows 7 64-bit, so I picked the ?Windows x64? platform.

Note! A JDK isn?t the same as a Java Runtime Environment (JRE) or Java browser plug-in that you may already have installed. If you?re not sure, check your installed programs to make sure you really have the JDK and not something else.

Further note! If you?re running on Mac OS X, you may already have a Java JDK installed at /System/Library/Java/JavaVirtualMachines/1.6.0.jdk, since it used to ship with the operating system. If not, you can install Oracle’s JDK 7 from here. Or if you don’t want to try JDK 7 on OS X yet, you can install Apple’s JDK 6 as documented here. Just be aware that if you want this tutorial to build on more than one platform without changing any Eclipse settings, it’s best to have the same version of the JDK installed on all your platforms.

After your JDK is set, download and install ?Eclipse for RCP and RAP Developers? from here. When I downloaded it, the latest version was 3.7.2, nicknamed ?Indigo? because of the obvious similarity between ?a dye-producing plant? and ?a software development environment?. I downloaded the Windows 64-bit version of this too. To run Eclipse, you just unzip it into any directory and double-click on ?eclipse.exe?.

The first time you run Eclipse, it?ll show you the world?s most unhelpful welcome page. Click the ?Workbench? button on the right to go past it.

?Then Eclipse will ask you what ?workspace? to open. Set this to a directory where you want to create your new projects for this tutorial, then click ?OK?. You can switch between workspaces or create new ones later on by selecting ?File > Switch Workspace? from the main menu.

Here?s what your new empty workspace should look like now.

Eclipse is a great sprawling beast, baroque but hyper-useful, and I can?t even try to explain everything about it here. I?ll just keep to the minimum that we need to make this tutorial work, and you can pick up the rest as you need it.

Obtain ?Java OpenGL?, or ?JOGL? as it is commonly known

Um, I-man? You don?t have to scare-quote all the tech words. I think our audience can figure it out.

My apologies.

No biggie, just trying to keep it casual up in here. Java OpenGL, or yes, ?JOGL? as it?s known to those of us in the know, such as myself, is maintained by the super-programmers at JogAmp. So grab the latest gluegen and JOGL archive files from here. I got five .7z files from gluegen-b547-2012-04-19_20-39-21 and five from jogl-b736-2012-04-19_20-43-43, which were the latest builds at the time of this writing.

gluegen-2.0-b547-20120419-linux-amd64.7z

gluegen-2.0-b547-20120419-linux-i586.7z

gluegen-2.0-b547-20120419-macosx-universal.7z

gluegen-2.0-b547-20120419-windows-amd64.7z

gluegen-2.0-b547-20120419-windows-i586.7z

jogl-2.0-b736-20120419-linux-amd64.7z

jogl-2.0-b736-20120419-linux-i586.7z

jogl-2.0-b736-20120419-macosx-universal.7z

jogl-2.0-b736-20120419-windows-amd64.7z

jogl-2.0-b736-20120419-windows-i586.7z

Since I develop on 64-bit Windows 7, I only need gluegen-2.0-b547-20120419-windows-amd64.7z and jogl-2.0-b736-20120419-windows-amd64.7z to run on my main computer, but I got all ten so I can make this project multi-platform. Unzip these files somewhere convenient. To unzip .7z files, I recommend 7-Zip on Windows and Linux, and Keka on Mac OS X.

Create JOGL projects within Eclipse

To use JOGL from an Eclipse RCP project, we have to repackage it a bit. JOGL is made of two types of files: JAR files that are common to all platforms, and library files (.dll files on Windows, .so files on Linux, and .jnilib or .dylib files on Mac OS X) that are specific to each platform you want your program to run on. We?ll put the JOGL JARs in an Eclipse plug-in project, and the JOGL library files in separate Eclipse plug-in fragment projects. If you?re not familiar with Eclipse don?t worry about what the different Eclipse project types mean right now. This setup is just a good way for all the platforms? libraries to live together without anything blowing up.

First we create a project to hold the JAR files. Select ?File > New > Project?? from the Eclipse main menu to bring up the ?New Project? wizard. Open ?Plug-in Development?, select ?Plug-in from Existing JAR Archives?, and click ?Next?.

Click ?Add External??, and in the ?Open? dialog that pops up, navigate to the ?jar? directory inside an unzipped gluegen archive, select ?gluegen-rt.jar? and click ?Open?. Then do the same thing for the ?jogl.all.jar? file in the “jar” directory of an unzipped JOGL archive. It doesn’t matter which platform’s archive you get these JARs from, since they’re all the same. Click ?Next? when you’re done.

Enter ?com.jogamp.jogl? as the project name. Set the plug-in version to ?2.0.0?. Set the plug-in name to “JOGL” and the plug-in provider to ?jogamp.org?. Uncheck ?Unzip the JAR archives into the project?. Then click ?Finish?, and Eclipse will magically create the project especially just for you.

Your finished project should look like this. The new ?com.jogamp.jogl? directory is inside your workspace directory. The settings you typed in are stored in the ?META-INF/MANIFEST.MF? and ?build.properties? files that the wizard just created for you. The wizard also copied the gluegen and JOGL JAR files into your new project.

Next we create projects to hold the platform-specific libraries. Eclipse calls this type of project a ?fragment? because it?s an ?extra bit? of the earlier JAR project, and it holds stuff we only need on some platforms. Select ?File > New > Project?? to bring up the ?New Project? wizard again. Then open ?Plug-in Development?, select ?Fragment Project?, and click ?Next?.

Enter ?com.jogamp.jogl-windows-amd64? as the project name, then click ?Next?.

Set the plug-in version to ?2.0.0?, the name to ?jogl-windows-amd64?, and the plug-in provider to ?jogamp.org?. Set the host plug-in ID to ?com.jogamp.jogl? (that?s the project this one is a fragment of). Set the minimum version to ?2.0.0?. Then click ?Finish? to create the project.

When the overview of this fragment comes up, set the platform filter to the incantation ?(& (osgi.os=win32) (osgi.arch=x86_64))?. This makes sure the fragment project is only loaded when your program is run on a 64-bit Windows system.

In Windows, manually copy all the DLLs from the ?lib? directories inside the unzipped ?*-windows-amd64? gluegen and JOGL archives into the new ?com.jogamp.jogl-windows-amd64? directory in your workspace. Then back in Eclipse, right-click the ?com.jogamp.jogl-windows-amd64? project and select ?Refresh?. You should see the DLLs in your project like this:

To finish setting up this fragment, click the ?Build? tab at the bottom of the main window and check all the DLLs under ?Binary Build? list. It should look like this:

Create one?s other fragments, mutatis mutandis

I guess what Stish means by that is, we can create fragments for the rest of the platforms that we want to support by redoing what we just did for the 64-bit Windows fragment, but making the necessary changes for each one. Here are the fragment names and platform filters for all five:

com.jogamp.jogl-linux-amd64: (& (osgi.os=linux) (osgi.arch=x86_64))

com.jogamp.jogl-linux-i586: (& (osgi.os=linux) (osgi.arch=x86))

com.jogamp.jogl-macosx-universal: (& (osgi.os=macosx) (osgi.arch=x86_64))

com.jogamp.jogl-windows-amd64: (& (osgi.os=win32) (osgi.arch=x86_64))

com.jogamp.jogl-windows-i586: (& (osgi.os=win32) (osgi.arch=x86))

And there is a complete table of the names of the native library files on the JogAmp wiki for reference here. When you?ve created all five fragments, your workspace will look like this:

Note for JDK 7 users on Mac OS X! Due to an incompatibility between JDK 6 and JDK 7 documented here and here, you need to either rename your .jnilib files to .dylib (if you only need to run under Java 7), or create copies of the .jnilib files as .dylib files (if you want to run under both Java 6 and Java 7).

You can see there?s a “Platform filter does not match the current environment” warning at the bottom for each of the platforms other than the one Eclipse is running on now. You could ignore those, but if you’re as compulsive as I am, that’s just not an option. So right-click the first fragment project in the Package Explorer on the left, click Properties, then expand “Plug-in Development” on the left and select “Plug-in Manifest Compiler”. Check “Enable project specific settings”, then change “General > Incompatible environment” to “Ignore”. The properties dialog should look like this when you’re done.

Click “OK”, then click “Yes” when it asks you if it can rebuild the project. Do this for all five fragment projects, and your warnings list will be gloriously empty.

With these five fragment projects included, our app will be able to run with no modification on five different platforms. When we run the app, the Eclipse RCP framework will load the com.jogamp.jogl plugin first, then it will load the correct fragment for the platform the app is running on, without you having to write any custom code or wrapper scripts to try to change the Java library path.

Create one?s principal project

Now that JOGL is ready for use, we can create the main project. Select ?File > New > Project?? to bring up the ?New Project? wizard. Open ?Plug-in Development?, select ?Plug-in Project?, and click ?Next?.

Enter your project?s name. Mine is ?name.wadewalker.tutorial?. Then click ?Next?.

Then set your project version number (mine is ?1.0.0?), your provider (mine is ?Wade Walker?), click ?Yes? beside ?Would you like to create a rich client application??, and click ?Next?.

Select the ?Hello RCP? template under ?Available Templates?. This will make a minimal RCP app that we can stuff our own JOGL code into. Then click ?Next? (not ?Finish?).

Fill in your window title (mine?s ?Tutorial?), and check the ?Add branding? box (this lets you customize your splash screen later). Then click ?Finish? to create the project.

Your project overview should look like this:

Now click the ?Dependencies? tab at the bottom of the main window. Click ?Add?? beside ?Required Plug-ins?, and type ?com.jo? in the ?Select a Plug-in? box. Select ?com.jogamp.jogl (2.0.0)? in the list of matching items, then click ?OK?.

Your dependencies should look like this:

At this point, if you right-click this project in the list, then select ?Run As > Eclipse Application?, you?ll see the most minimal app you can imagine. OK, I guess it could technically be more minimal, but this is pretty bare. But at least it runs! The empty frame inside our window is where the editors go in an RCP app. We?ll get rid of that in a moment, since we don?t want an editor yet.

Add a ?view? to one?s principal application

Eclipse calls the kind of window we?re creating for JOGL a ?view?. To create it, click the ?Extensions? tab, then click the ?Add?? button, type ?org.eclipse.ui.v? in the ?Extension Point filter? box, select ?org.eclipse.ui.views?, and click ?Finish?.

Right-click ?org.eclipse.ui.views? under ?All Extensions? and select ?New > view?. Then under ?Extension Element Details?, fill in the ID (?name.wadewalker.tutorial.joglview?), the name (?JOGLView?), and the class (?name.wadewalker.tutorial.JOGLView?).

Click the ?class? hyperlink under ?Extension Element Details?, then click ?Finish? to create the Java file that implements the JOGL view.

Now we have to tell our program to open this view at startup so we can see it. Open the ?Perspective.java? file by double-clicking it in the package explorer:

And change the contents of ?Perspective.java? in the text editor to this:

package name.wadewalker.tutorial;

import org.eclipse.ui.IPageLayout;
import org.eclipse.ui.IPerspectiveFactory;

public class Perspective implements IPerspectiveFactory {

	public void createInitialLayout(IPageLayout layout) {
		// editor area invisible to avoid empty editor frame below our view  
		layout.setEditorAreaVisible( false );
		layout.addView( "name.wadewalker.tutorial.joglview", IPageLayout.TOP,
						IPageLayout.RATIO_MAX, IPageLayout.ID_EDITOR_AREA);
		}
}

Now if you right-click your project in the list, then select ?Run As > Eclipse Application?, you?ll see that our app has an empty JOGL view now. Still bare, but getting closer! The empty editor frame?s gone too, since we turned it off in the code above.

Now we put in some demo JOGL code. This snippet was originally used to demonstrate the old JOGL 1.1.1 (pre-JogAmp) in SWT (the windowing toolkit that Eclipse uses). Sven Göthel at JogAmp adapted it for JOGL 2.0, then I adapted that to make it an Eclipse ViewPart. Double-click the ?JOGLView.java? file on the left, then replace its contents with this:

/*******************************************************************************
 * Copyright (c) 2000, 2005, 2010 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *     Sven Gothel     - conversion to JOGL 2.0 (original at http://github.com/sgothel/jogl-demos/blob/master/src/demos/swt/Snippet209.java)
 *     Wade Walker     - conversion to an Eclipse ViewPart
 *     
 *******************************************************************************/

package name.wadewalker.tutorial;

/*
 * SWT OpenGL snippet: use JOGL to draw to an SWT GLCanvas
 *
 * For a list of all SWT example snippets see
 * http://www.eclipse.org/swt/snippets/
 * 
 * @since 3.2
 */
import javax.media.opengl.GL;
import javax.media.opengl.GL2;
import javax.media.opengl.GL2ES1;
import javax.media.opengl.GL2GL3;
import javax.media.opengl.GLContext;
import javax.media.opengl.GLDrawableFactory;
import javax.media.opengl.GLProfile;
import javax.media.opengl.fixedfunc.GLMatrixFunc;
import javax.media.opengl.glu.GLU;

import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Rectangle;
import org.eclipse.swt.layout.FillLayout;
import org.eclipse.swt.opengl.GLCanvas;
import org.eclipse.swt.opengl.GLData;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Event;
import org.eclipse.swt.widgets.Listener;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.part.ViewPart;

public class JOGLView extends ViewPart {

    /** Holds the OpenGL canvas. */
    private Composite composite;

    /** Widget that displays OpenGL content. */
    private GLCanvas glcanvas;

    /** Used to get OpenGL object that we need to access OpenGL functions. */
    private GLContext glcontext;

    /** Master rotation angle of the torus, in degrees. */
    private int rot = 0;

    public JOGLView() {
    }

    @Override
    public void createPartControl( Composite compositeParent ) {
        GLProfile glprofile = GLProfile.get(GLProfile.GL2);

        composite = new Composite( compositeParent, SWT.NONE );
        composite.setLayout( new FillLayout() );

        GLData gldata = new GLData();
        gldata.doubleBuffer = true;
        glcanvas = new GLCanvas( composite, SWT.NO_BACKGROUND, gldata );
        glcanvas.setCurrent();
        glcontext = GLDrawableFactory.getFactory( glprofile ).createExternalGLContext();

        glcanvas.addListener(SWT.Resize, new Listener() {
            public void handleEvent(Event event) {
                Rectangle bounds = glcanvas.getBounds();
                float fAspect = (float) bounds.width / (float) bounds.height;
                glcanvas.setCurrent();
                glcontext.makeCurrent();
                GL2 gl = glcontext.getGL().getGL2();
                gl.glViewport(0, 0, bounds.width, bounds.height);
                gl.glMatrixMode(GLMatrixFunc.GL_PROJECTION);
                gl.glLoadIdentity();
                GLU glu = new GLU();
                glu.gluPerspective(45.0f, fAspect, 0.5f, 400.0f);
                gl.glMatrixMode(GLMatrixFunc.GL_MODELVIEW);
                gl.glLoadIdentity();
                glcontext.release();
                }
        });

        glcontext.makeCurrent();
        GL2 gl = glcontext.getGL().getGL2();
        gl.setSwapInterval(1);
        gl.glClearColor(1.0f, 1.0f, 1.0f, 1.0f);
        gl.glColor3f(1.0f, 0.0f, 0.0f);
        gl.glHint(GL2ES1.GL_PERSPECTIVE_CORRECTION_HINT, GL.GL_NICEST);
        gl.glClearDepth(1.0);
        gl.glLineWidth(2);
        gl.glEnable(GL.GL_DEPTH_TEST);
        glcontext.release();

        (new Thread() {
            public void run() {
                while( (glcanvas != null) && !glcanvas.isDisposed() ) {
                    render();
                    try {
                        // don't make loop too tight, or not enough time
                        // to process window messages properly
                        sleep( 1 );
                    } catch( InterruptedException interruptedexception ) {
                        // we just quit on interrupt, so nothing required here
                    }
                }
            }
        }).start();
    }

    protected void render() {
        PlatformUI.getWorkbench().getDisplay().syncExec( new Runnable() {
            public void run() {
                if( (glcanvas != null) && !glcanvas.isDisposed()) {
                    glcanvas.setCurrent();
                    glcontext.makeCurrent();
                    GL2 gl = glcontext.getGL().getGL2();
                    gl.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
                    gl.glClearColor(.3f, .5f, .8f, 1.0f);
                    gl.glLoadIdentity();
                    gl.glTranslatef(0.0f, 0.0f, -10.0f);
                    gl.glRotatef(0.15f * rot, 2.0f * rot, 10.0f * rot, 1.0f);
                    gl.glRotatef(0.3f * rot, 3.0f * rot, 1.0f * rot, 1.0f);
                    rot++;
                    gl.glPolygonMode(GL.GL_FRONT_AND_BACK, GL2GL3.GL_LINE);
                    gl.glColor3f(0.9f, 0.9f, 0.9f);
                    drawTorus(gl, 1, 1.9f + ((float) Math.sin((0.004f * rot))), 15, 15);
                    glcanvas.swapBuffers();
                    glcontext.release();
                }
            }
        });
    }

    protected void drawTorus(GL2 gl, float r, float R, int nsides, int rings) {
        float ringDelta = 2.0f * (float) Math.PI / rings;
        float sideDelta = 2.0f * (float) Math.PI / nsides;
        float theta = 0.0f, cosTheta = 1.0f, sinTheta = 0.0f;
        for (int i = rings - 1; i >= 0; i--) {
            float theta1 = theta + ringDelta;
            float cosTheta1 = (float) Math.cos(theta1);
            float sinTheta1 = (float) Math.sin(theta1);
            gl.glBegin(GL2.GL_QUAD_STRIP);
            float phi = 0.0f;
            for (int j = nsides; j >= 0; j--) {
                phi += sideDelta;
                float cosPhi = (float) Math.cos(phi);
                float sinPhi = (float) Math.sin(phi);
                float dist = R + r * cosPhi;
                gl.glNormal3f(cosTheta1 * cosPhi, -sinTheta1 * cosPhi, sinPhi);
                gl.glVertex3f(cosTheta1 * dist, -sinTheta1 * dist, r * sinPhi);
                gl.glNormal3f(cosTheta * cosPhi, -sinTheta * cosPhi, sinPhi);
                gl.glVertex3f(cosTheta * dist, -sinTheta * dist, r * sinPhi);
            }
            gl.glEnd();
            theta = theta1;
            cosTheta = cosTheta1;
            sinTheta = sinTheta1;
        }
    }

    @Override
    public void setFocus() {
    }

    @Override
    public void dispose() {
        glcanvas.dispose();
        super.dispose();
    }
}

And one last change, this time to Activator.java. It?s only needed on Linux, but it doesn?t hurt other platforms. Stick this code before the constructor.

    // NOTE for Linux: Needed to set up threading properly for JOGL. This
    // has to be done before any X11 calls, so it goes here in the class
    // Eclipse loads first. If you don't put this early enough, you may
    // get SIGSEGV in libpthread.so (or other sorts of multithreading errors)
    // when you try to run the program.
    // NOTE for Mac OS X: If you don't set -Djava.awt.headless=true in the
    // program's VM arguments, this call may freeze the program. This is because
    // it tries to load the AWT library, which can't coexist with SWT on Mac OS X.
    static {
        GLProfile.initSingleton( false );
    }

Then run the main project again, and finally our JOGL view shows an animated wireframe doughnut ? what we super-geniuses call a ?torus?. Success!

Here?s what it looks like in Linux:

And last but not least et cetera, here’s the Mac OS X version:

Now that we?ve got this skeleton up and walking, we?ll start putting some meat on it in the next tutorial.

A quick but important note to those running Mac OS X

On Mac OS X, this application may freeze on startup or log an error saying “Can’t start the AWT because Java was started on the first thread”. If it does, simply right-click the project and select ?Run As > Run Configurations…?. Make sure ?Eclipse Application > name.wadewalker.tutorial.product? is selected in the left pane. Then click the ?Arguments? tab on the right and add ? -Djava.awt.headless=true? to the end of the list of arguments in the ?VM Arguments? box. This insures that AWT will not be loaded, which can cause problems with SWT applications on Mac OS X.

Resources upon which you may draw for more information

JOGL: Sven Göthel and the guys at http://jogamp.org have the source code for JOGL, zipped builds, and discussion forums. This is the main home for JOGL now, even though it still shows up a few other places on the web. Huge props to these guys for taking on such a large project that?s helpful to so many people around the world!

Eclipse RCP programming: Lars Vogel has a great article about creating Eclipse RCP programs at http://www.vogella.de/articles/EclipseRCP/article.html. The other articles on his site are also awesome.

SWT: The snippets at http://www.eclipse.org/swt/snippets/ are very helpful when putting other controls into RCP apps.

A concise history of the changes which we have made to this document

10/09/2010: Wrote this post.

10/17/2010: Punched up the language, added zip files.

10/23/2010: Added fragments for all platforms; split the zip into two parts; fixed the location of GLProfile.initSingleton() after testing on Linux.

10/26/2010: Fixed the links to full-sized images.

3/23/2011: Fixed quote marks in code snipped from Perspective.java.

4/10/2011: Updated code to work with the latest JOGL across all three major platforms. Updated zip file to JOGL b365. Put in new Linux and Mac OS X screenshots.

10/14/2011: Fixed typo in Mac OS X platform filter.

04/20/2012: Updated text for JOGL b736, Eclipse 3.7.2, and Java 1.7.0_03.

04/21/2012: Uploaded new images.

05/1/2012: Updated with .dylib vs. .jnilib information after I got JDK 7 working on Mac OS X.

Version 2.1.0

admin — Fri, 24 Sep 2010 01:52:01 GMT

The next release of dyn4j is ready! The new version, 2.1.0, features a new PulleyJoint and multi-threading support.

When running you may be asked to accept a certificate from me (I just self signed the JARs). The certificates will expire six months from today…

The "Parallel" test from the TestBed

All the releases require Java 1.6+. Be sure to type the “c” key to get the TestBed Control Panel so you can play with the simulator.

Creating a JOGL Eclipse Project

Rami — Sun, 22 Aug 2010 17:46:00 GMT

Below is a how to create an eclipse project for JOGL project, www.jogamp.org.

Why isnt it on github….well since eclipse takes full paths of the src directories, you would need to practicaly re-do it after fetching the project.

1- After downloading the source code, create an eclipse workspace in the jogl directory ..or anywhere else.
2- Create a new Java project (jogl-eclipse) with jdk_6u21…
3- Now delete the src forder from package explorer which will remove it from the disk as well.
4- Go to Project –> Properties

a- In the Java Build Path menu:

Under Source Tab: Link the following sources “…” is the path to your jogl directory.

…/src/jogl/classes –> jogl
../build/jogl/gensrc/classes –> jogl gensrc
…/src/nativewindow/classes –> nativewindow
…/build/nativewindow/gensrc/classes –> nativewindow gensrc
…/src/newt/classes –> newt
…/build/newt/gensrc –> newt gensrc
…/jogl/src/junit –> junit

finally add,
GLUEGEN_HOME/src/java/ –>gluegen common
with the following as excluded paths “com/sun/” and “net/”

In the Libraries tab: add the following as external jars

ant-junit.jar (apache-ant/lib)
gluegen-rt.jar (…/build/jar)
junit.jar (GLUGEN_PATH/make/lib)

b- In the Builders menu:
Add a new Ant Builder: (optional to build from eclipse) with:

Buildfile: …/make/build.xml
Base Directory: …/make

You can then specify the targets if you want. For me I disabled the ant builder and use the command line . You can also add the egit plugin…good for visualizing changes (reporting) but kinda of slow. You will get some errors in the gensrc code from extra semicolon… should be fixed in the emitter

And your done!