Add JOGL migration guide

[httpdigest]

Add an article in the Wiki explaining how to convert from JOGL's vecmath math classes to JOML. This will help people switching from JOGL's to LWJGL 3 math classes to using JOML.

[ghost]

JOGL doesn't use vecmath, Java3D does. JOGL 2 provides com.jogamp.opengl.math and com.jogamp.opengl.math.geom but they aren't mandatory, i.e you can use JOGL 2 without them. Moreover, writing "help people switching from JOGL to LWJGL 3" is a bit counter-intuitive to me because JOML != LWJGL and I thought that it would be possible to use JOML with JOGL. Therefore, I suggest you to modify this report, it should be entitled "Add JogAmp OpenGL Math migration guide" and you could write a paragraph about using JOML with JOGL by adapting this one: https://github.com/JOML-CI/JOML#using-with-lwjgl

glUniformMatrix4fv is here: http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GL2ES2.html#glUniformMatrix4fv(int,%20int,%20boolean,%20float[],%20int)

Our method to create a direct NIO float buffer is here: http://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/com/jogamp/common/nio/Buffers.html#newDirectFloatBuffer(int)

glMatrixMode is here: http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/fixedfunc/GLMatrixFunc.html#glMatrixMode(int)

glLoadMatrixf is here: http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/fixedfunc/GLMatrixFunc.html#glLoadMatrixf(java.nio.FloatBuffer)

You can write migration guides for Apache Commons Math, Colt, Efficient Java Matrix Library, Jama, jblas, JScience, Matrix Toolkit Java, OjAlgo, Parallel Colt, Universal Java Matrix Package, Elegant Linear Algebra for Java, Xith3D vecmath and Ardor3D Math too. Good luck.

[httpdigest]

JOGL doesn't use vecmath, Java3D does. JOGL 2 provides com.jogamp.opengl.math and com.jogamp.opengl.math.geom

I am sorry for the misinterpretation of the text in my first comment. Yes, I know that JOGL uses its own math classes (there the expression "vecmath" just stood for any arbitrary "vector math" library).

This enhancement proposal issue here just exists for people currently using JOGL's math classes to easily switch over to JOML, or vice versa. And yes, you can of course use JOML together with JOGL.

We are also always happy taking contributions. So If you feel you could provide such a guide, this would be greatly appreciated!

Thanks!

[ghost]

Thank you for the edits. I can write a small paragraph about JOML with JOGL this week. I'll make a pull request.

[httpdigest]

That'd be great! I'd love to see JOML also being used with JOGL. Thanks for your offer!

[ghost]

Somebody already uses JOML with JOGL: http://stackoverflow.com/questions/31417835/opengl-depth-buffer-ortho-projection

I have to write this paragraph as soon as possible.

[ghost]

Using with JOGL

JOML can be used together with JOGL to build a transformation matrix and set it as a uniform mat4 in a shader (for example as a replacement of com.jogamp.opengl.util.glsl.fixedfunc.FixedFuncUtil and com.jogamp.opengl.util.PMVMatrix to emulate the fixed pipeline). For this, the Matrix4f class provides a method to transfer a matrix into a Java NIO FloatBuffer, which can then be used by JOGL when calling into OpenGL:

FloatBuffer fb = Buffers.newDirectFloatBuffer(16);
new Matrix4f().perspective((float) Math.toRadians(45.0f), 1.0f, 0.01f, 100.0f)
              .lookAt(0.0f, 0.0f, 10.0f,
                      0.0f, 0.0f, 0.0f,
                      0.0f, 1.0f, 0.0f)
              .get(fb);
gl.glUniformMatrix4fv(mat4Location, 16, false, fb);

The above example first creates a transformation matrix and then uploads that matrix to a uniform variable of the active shader program using the JOGL 2 method glUniformMatrix4fv.

If you prefer not to use shaders but the fixed-function pipeline and want to use JOML to build the transformation matrices, you can do so. Instead of uploading the matrix as a shader uniform you can then use the OpenGL API call glLoadMatrixf() provided by JOGL to set a JOML matrix as the current matrix in OpenGL's matrix stack:

FloatBuffer fb = Buffers.newDirectFloatBuffer(16);
Matrix4f m = new Matrix4f();
m.setPerspective((float) Math.toRadians(45.0f), 1.0f, 0.01f, 100.0f).get(fb);
gl.glMatrixMode(GLMatrixFunc.GL_PROJECTION);
gl.glLoadMatrixf(fb);
m.setLookAt(0.0f, 0.0f, 10.0f,
            0.0f, 0.0f, 0.0f,
            0.0f, 1.0f, 0.0f).get(fb);
gl.glMatrixMode(GLMatrixFunc.GL_MODELVIEW);
gl.glLoadMatrixf(fb);

[ghost]

Done: https://github.com/JOML-CI/JOML/pull/32

[httpdigest]

Somebody already uses JOML with JOGL: http://stackoverflow.com/questions/31417835/opengl-depth-buffer-ortho-projection

Oh, didn't know about that. And he/she is even doing it with slightly unnecessary Vector3f allocations. :) I don't have a stackoverflow account, but if you have, you could point him/her to your written section.

[httpdigest]

It's good to have a simple "getting started with JOGL" section on the README, but what this issue here was meant to be about was a section on how JOGL's math compares to JOML. Just like the Wiki article about how LWJGL2's vector package compares to JOML. So, it would be great to have that for people to switch from JOGL's math classes to JOML, or vice versa. This would be for people compaining about "why is the method XYZ" not available in JOML, where JOGL's XYZ could just be JOM's ZYX. :)

[ghost]

I see what you mean, we can have a look at those classes: http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/math/Matrix4.html http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/math/Quaternion.html

I'm going to point her/him to your post :)

[ghost]

@httpdigest Your matrix stack uses radians whereas PMVMatrix uses degrees: http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/util/PMVMatrix.html

It would be nice to mention it at the end of the section about the matrix stack.

[httpdigest]

Oh, thanks! That is a very important difference, yes. I'll probably add that to the "Using with JOGL" section. However it should belong into a proper "Migration from JOGL math" (or something) Wiki page.

[httpdigest]

I am closing this now, since I feel that the need for such a migration guide is not strong enough for people to feel motivated to donate their time writing such a guide.