Migrating from LWJGL 2

This article is for people who are currently using LWJGL 2 and wanting to switch to LWJGL 3. So if you are using LWJGL 2 and especially its "util" jar with the classes in the included vector package, you can migrate easily to JOML.

Vector and Matrix operations

JOML uses a very similar design compared to LWJGL 2's util vecmath classes, by providing instance methods writing the result back into the same object, and instance methods accepting a destination parameter. Also, methods such as rotate(), translate() and scale() post-multiply their respective transformations to the current matrix values.

One important difference is the handling of NIO FloatBuffers when getting values from or writing values into a FloatBuffer. In LWJGL 2 the position of the FloatBuffer will be incremented by load and store operations. In JOML the position will not be changed!

Some Matrix4f operations have different names in JOML. These are listed in the following table:

LWJGL 2	JOML	Alternative in JOML
setIdentity	identity
setZero	zero
load	set
store	get
loadTransposed	setTransposed
storeTransposed	getTransposed
store3f	get3x3

The same table for vector operations in Vector4f:

LWJGL 2	JOML	Alternative in JOML
translate	add
normalise	normalize
load	set
scale	mul
store	get

GLU operations

The matrix operations implemented in the GLU class are part of the Matrix4f in JOML. However, unlike the methods in LWJGL 2, JOML does not interface with OpenGL to multiply the matrices. Instead, JOML post-multiplies the projection and view transformations by the Matrix4f they are invoked on. So, they work just like the other transformation methods rotate(), scale() and translate() in JOML.

Therefore, you need to fill a FloatBuffer and use glLoadMatrixf() if you want to upload the matrix to OpenGL:

Matrix4f m = new Matrix4f();
m.perspective((float) Math.toRadians(45), (float)width/height, 0.1f, 100.0f);
FloatBuffer fb = BufferUtils.createFloatBuffer(16);
glMatrixMode(GL_PROJECTION);
glLoadMatrixf(fb.get(fb));

The following table contains the differences between LWJGL 2's GLU class and JOML's Matrix4f class:

LWJGL 2	JOML	Differences
gluPerspective	perspective	In JOML the fov angle is given in radians
gluLookAt	lookAt
gluProject	project
gluUnProject	unproject
gluOrtho2D	ortho2D
gluPickMatrix	pick