Experiences of migrating from JOGL 1.1.1 to JSR231

Just thought I’d record my experiences of refactoring a fairly large OGL application from using the old 1.1.1 to the new JS231 (beta 03 to be specific). Many of these are noted elsewhere (might be worth collating into a migration doc) but repeated here for completeness.

  • Global replace net.java.games.jogl with javax.media.opengl
  • GLU is now in javax.media.opengl.glu which requires an additional step
  • GLU objects are created ab initio with new GLU () - no need to keep pulling them out of the Drawable (but note the one per thread limit)
  • Replace GLDrawable with GLAutoDrawable
  • Except: GLDrawable no longer includes getSize () (any reason not to?)
  • All GL calls where you pass in an array you need to add an extra offset parameter - 0 when refactoring (aside: this is particularly tedious and inelegant - do the extra method bindings really matter?)
  • Some calls which used to allow a direct array argument now needs IntBuffer.wrap (array) (e.g., glDrawPixels)
  • Consequently it would be really useful if you could go straight from a java.awt.image.DataBuffer to a java.nio.Buffer
  • Some GL calls which used to be an ARB or vendor extension are gone and (generally) just knock off the ARB etc to get it to work (e.g., glActiveTexture)
  • The Animator class is now in com.sun.opengl.util for some reason (??)
  • Looks like noAutoRedrawMode is no longer needed

The good news for anyone else who has to do this is that after going through a tedious half day of refactoring, it did just work once it successfully compiled. I’m sure I’ll find an odd gotcha yet to come - the main one that worries me is the necessity to rewind buffers now (but I don’t think any of mine should be anywhere other than 0).

And some other random thoughts while doing this:

  • Common calls such as glLightfv, glMaterialfv and glFogfv with a colour argument could do with a convenience method binding with 4 floats
  • Now that GLU is pure Java could we have some more friendly signatures to some methods?, e.g., gluUnproject (Vector3f, Matrix4f, Matrix4f, int [], Vector3f)
  • In fact can we go one step further and support javax.vecmath.Matrix4f/Vector3f throughout the apis?

Thanks for posting this. I’ve made the topic sticky to make it easier for others to find this information.

I’ve converted all of the NeHe tutorials that had JOGL code to use the new JSR 231 APIs. I have to fix it up a bit more, but when I have it ready I will zip up the source and the NetBeans project files (Ant stuff) and post it somewhere.
I am finally starting to learn OpenGL.

Some other points:

  • BufferUtils is now BufferUtil
  • GLCanvas is constructed with new GLCanvas() instead of the old factory method.

Great to hear. Are you talking with pepijnve on these forums? He has ports of some of the NeHe demos on this page – it would be great if you two could coordinate. I’m sorry I haven’t been more proactive in updating the main JOGL pages to point to more of this stuff – if you or anyone else wants to help organize some of these links please let me know. Or consider updating the wiki.

Actually I noticed pepijnve’s message just after I posted. I didn’t even know he had so many more of the NeHe code ported to JOGL 1.1 than I found on the NeHe site… I suspect he is well ahead of me. I only had lessons 1-14 and I’m mostly done the conversion, they all compile but I have a few kinks to work out with resource loading in some of the later lessons. (I’m bundling the resources in the .jar produced by the NetBeans project)

If he wants some help I will try to be of assistance.

Other difference between 1.1 and JSR231, the Version object returning the jogl version disapeared

It took me time to understand the rewind trick. Here is a piece of code making a texture from a BufferedImage
(some of the code is maybe useless)

GL1.glClearColor(1.0f, 1.0f, 1.0f, 0.0f);
GL1.glColor3f(0.0f, 0.0f, 0.0f);

BufferedImage  BufferedImage1  = new BufferedImage(512, 512, BufferedImage.TYPE_3BYTE_BGR);

int[]          tmp             = new int[1];
GL1.glGenTextures(1, tmp, 0);
TextureChart         = tmp[0];
GL1.glBindTexture(GL.GL_TEXTURE_2D, TextureChart);

ByteBuffer     dest            = null;
byte[]         data            = ((DataBufferByte)BufferedImage1.getRaster().getDataBuffer()).getData();
dest = ByteBuffer.allocateDirect(data.length);
dest.put(data, 0, data.length);
dest.rewind(); // <- NEW STUFF NEEDED BY JSR231
GL1.glTexImage2D(GL.GL_TEXTURE_2D, 0, GL.GL_RGB, 512, 512, 0, GL.GL_RGB, GL.GL_UNSIGNED_BYTE, dest);

Otherwise I have an exception with the new JSR version. Can someone help ?
$ /cygdrive/c/Program\ Files/Java/jdk1.6.0/bin/java -cp jogl-demos.jar demos.gears.Gears
INIT GL IS: com.sun.opengl.impl.GLImpl
Exception in thread “Thread-2” GL_VENDOR: NVIDIA Corporation
javax.media.opengl.GLException: java.lang.UnsatisfiedLinkError: glGenLists
at javax.media.opengl.Threading.invokeOnOpenGLThread(Threading.java:205)
at javax.media.opengl.GLCanvas.maybeDoSingleThreadedWorkaround(GLCanvas.java:234)
at javax.media.opengl.GLCanvas.display(GLCanvas.java:127)
at com.sun.opengl.util.Animator.display(Animator.java:144)
at com.sun.opengl.util.Animator$MainLoop.run(Animator.java:181)
at java.lang.Thread.run(Thread.java:620)
Caused by: java.lang.UnsatisfiedLinkError: glGenLists
at com.sun.opengl.impl.GLImpl.glGenLists(Native Method)
at demos.gears.Gears.init(Gears.java:71)
at com.sun.opengl.impl.GLDrawableHelper.init(GLDrawableHelper.java:71)
at javax.media.opengl.GLCanvas$InitAction.run(GLCanvas.java:242)
at com.sun.opengl.impl.GLDrawableHelper.invokeGL(GLDrawableHelper.java:123)
at javax.media.opengl.GLCanvas$DisplayOnEventDispatchThreadAction.run(GLCanvas.java:276)
at java.awt.event.InvocationEvent.dispatch(InvocationEvent.java:199)
at java.awt.EventQueue.dispatchEvent(EventQueue.java:597)
at java.awt.EventDispatchThread.pumpOneEventForFilters(EventDispatchThread.java:273)
at java.awt.EventDispatchThread.pumpEventsForFilter(EventDispatchThread.java:183)
at java.awt.EventDispatchThread.pumpEventsForHierarchy(EventDispatchThread.java:173)
at java.awt.EventDispatchThread.pumpEvents(EventDispatchThread.java:168)
at java.awt.EventDispatchThread.pumpEvents(EventDispatchThread.java:160)
at java.awt.EventDispatchThread.run(EventDispatchThread.java:121)

Somebody just reported this exact problem; you have a mismatched jogl.dll and jogl.jar.

FYI, you can now get the version information for JOGL using java.lang.Package. See demos.misc.VersionInfo in the jogl-demos workspace.

In VBO related code, the pointer passed to glVertexPointer, glTexCoordPointer, … is used as an offset in the VBO.
In JSR-231, glVertexPointer for instance maps to two distinct functions:

glVertexPointer(int size, int type, int stride, Buffer ptr)


glVertexPointer(int size, int type, int stride, long offset)

Pre JSR-231 code that looked like this:

gl.glBindBufferARB(GL.GL_ARRAY_BUFFER_ARB, vbo);
gl.glVertexPointer(3, GL.GL_FLOAT, 0, null);

should be updated to

gl.glBindBufferARB(GL.GL_ARRAY_BUFFER_ARB, vbo);
gl.glVertexPointer(3, GL.GL_FLOAT, 0, 0);

[quote]All GL calls where you pass in an array you need to add an extra offset parameter - 0 when refactoring (aside: this is particularly tedious and inelegant - do the extra method bindings really matter?)
I just started the big switch to JSR 231, and I agree. I appreciate all the work that has gone into this effort but, at the risk of seeming picky, I may as well speak up now, rather than not at all. After reading the original slides a couple of years ago, where it seemed the best of the best would be pulled from previous bindings, I expected a more elegent solution. When a new user decides to try OpenGL and Java together, they’ll punch in a simple example from the Red Book, and they’ll hit this. After all that has been overcome to create these bindings, there isn’t room for overloaded bindings that look like classic OpenGL?

Well, I think the ByteBuffer variant makes more sense anyway… so I agree that it isn’t worth the effort to add more overloaded members to the Array versions. If you don’t want that extra parameter try using NIO Buffer-based method instead.

Sorry the style isn’t to your taste, but all of the Java APIs which take arrays (look all throughout java.io, for example) also typically take an offset argument, specifically because Java doesn’t have pointer arithmetic like C. As swpalmer points out, you can always use the NIO variants if you don’t want to pass the extra parameter, because Buffers implicitly have an offset (the position of the buffer). At least for the initial release of the JSR, we will not be adding overloaded variants for arrays without the offset parameter. If there is high demand for this we can add such convenience methods in a future update without breaking backward compatibility.

OK, so my opinion has been registered. I can live with the extra comma and zero.

[quote]Some calls which used to allow a direct array argument now needs IntBuffer.wrap (array) (e.g., glDrawPixels)
One variant of glDrawPixels takes Buffer pixels and the other takes long pixels_buffer_offset . What is the difference, and how would you convert JOGL code to the latter?


glDrawPixels is one of the APIs affected by the ARB_pixel_buffer_extension. Take a look at the documentation for that extension to see how it is used. All APIs affected by the vertex_buffer_object and pixel_buffer_object extensions have additional overloadings taking the long offset into the buffer object for security reasons. There are checks in the JOGL implementation to make sure that the extension is appropriately enabled or disabled when each overloading is called.

Please never integrate any math package into GL/GLU directly. There are lots of diffrent math packages out there, and doing that would favor one. IMHO that’s no ok, even for javax.vecmath since OpenGL is math api independent.

If it is the easy of use, you want. Just derivate from the GLU class and extend it with the methods for the vector classes you like.

I’m sorry, but I couldn’t disagree more! The greatest strength of Java is its broad and consistent set of APIs. When you have a task in front of you, unlike with C++, you don’t have to choose between half a dozen different APIs (e.g, STL or MFC? Just for lists and things), there is just one that all other packages work cleanly with. The real bane for me with 3D is that when I work with some new software package the odds are that it uses a different vector package (GLEEM uses its own for example) and all of a sudden I do not have portable code. Remember: write once, run anywhere!

Vector algebra is a real basic of what we’re doing here. Perhaps we need the JCP to reexamine the javax.vecmath package (which I agree is sufficient but not very useable - though Java’s lack of user defined operators doesn’t help there).

I already build ontop of LWJGL’s math libs.
I WISH JOGL had some in there.
You could even consider GLUT(Not confused with GLU) methods to be a total waste but they are in JOGL too.
So why not actually add something more helpful like a math library for vectors, quaternions and matrices?

What’s worse is that no one offers any buffered operations on math libs.

Vectors and matrices are fundamental data structures. I would like to see them added but as primitves with special suport by the java vm. Just adding a common non-accelerated math api would not make much sense.

I would like 3 sets of matrices in the library:
n x m

The question is who do we make the request to?

What is the problem with using javax.vecmath from the the java3d project?

It has Matrix3d, Matrix3f, Matrix4d, Matrix4f and GMatrix.

As I migrate my application to JSR231, I have a question about nio.Buffer performance. In many cases (e.g. glLightfv()), I have a choice to use a primitive array with the extra 0 offset parameter or to supply an nio.Buffer. Is there much of a performance hit in wrapping an array in an nio.Buffer? While I can’t imagine it would be faster to supply the nio.Buffer, there are some cases where the type of array is not specified (e.g. glReadPixels()) and so I am forced to provide one.