Document and clean up Java code

Author: Janrupf

example/lwjgl3-opengl/src/main/java/com/labymedia/ultralight/lwjgl3/opengl/GPUDriverGL.java

@@ -48,10 +48,7 @@
 import java.io.InputStreamReader;
 import java.nio.ByteBuffer;
 import java.nio.charset.StandardCharsets;
-import java.util.HashMap;
-import java.util.LinkedList;
-import java.util.List;
-import java.util.Map;
+import java.util.*;
 import java.util.stream.Collectors;
 
 import static org.lwjgl.glfw.GLFW.*;
@@ -866,12 +863,10 @@ public void destroyGeometry(long geometryId) {
     }
 
     @Override
-    public void updateCommandList(UltralightCommandList list) {
+    public void updateCommandList(UltralightCommand[] list) {
         CHECK_GL();
-        if (list.data.length != 0) {
-            for (UltralightCommand datum : list.data) {
-                this.commands.add(datum);
-            }
+        if (list.length != 0) {
+            Collections.addAll(this.commands, list);
         }
         CHECK_GL();
     }

example/lwjgl3-opengl/src/main/java/com/labymedia/ultralight/lwjgl3/opengl/support/WebController.java

@@ -170,7 +170,7 @@ public void render() {
 
         long text = this.view.renderTarget().textureId;
         long buffer = this.view.renderTarget().renderBufferId;
-        float[] uv = this.view.renderTarget().uv_coords;
+        float[] uv = this.view.renderTarget().uvCoords;
         int width = (int) view.width();
         int height = (int) view.height();
         glClearColor(0,0,0,1);

ultralight-java-base/src/main/java/com/labymedia/ultralight/math/UltralightMatrix.java

@@ -24,19 +24,51 @@
 import com.labymedia.ultralight.ffi.ObjectWithHandle;
 import com.labymedia.ultralight.ffi.gc.DeletableObject;
 
+/**
+ * Transformation Matrix helper.
+ */
 @NativeType("ultralight::Matrix")
 public class UltralightMatrix implements ObjectWithHandle {
     private final DeletableObject<Long> handle;
 
+    /**
+     * Constructs a new {@link UltralightMatrix} and begins tracking the underlying handle.
+     *
+     * @param handle A pointer to a native ultralight::Matrix, the java object will take
+     *               ownership of the native pointer
+     */
     @NativeCall
     private UltralightMatrix(long handle) {
         this.handle = new DeletableObject<>(handle, UltralightMatrix::delete);
     }
 
+    /**
+     * Constructs a new, empty matrix.
+     */
     public UltralightMatrix() {
         this.handle = new DeletableObject<>(construct(), UltralightMatrix::delete);
     }
 
+    /**
+     * Sets the values of the matrix.
+     *
+     * @param m11 row 1, column 1
+     * @param m12 row 1, column 2
+     * @param m13 row 1, column 3
+     * @param m14 row 1, column 4
+     * @param m21 row 2, column 1
+     * @param m22 row 2, column 2
+     * @param m23 row 2, column 3
+     * @param m24 row 2, column 4
+     * @param m31 row 3, column 1
+     * @param m32 row 3, column 2
+     * @param m33 row 3, column 3
+     * @param m34 row 3, column 4
+     * @param m41 row 4, column 1
+     * @param m42 row 4, column 2
+     * @param m43 row 4, column 3
+     * @param m44 row 4, column 4
+     */
     public native void set(
             @NativeType("double") double m11, @NativeType("double") double m12, @NativeType(
             "double") double m13, @NativeType("double") double m14,
@@ -48,10 +80,52 @@ public native void set(
             "double") double m43, @NativeType("double") double m44
     );
 
+    /**
+     * Sets the values of this matrix by coping from a 4x4 matrix.
+     *
+     * @param ultralightMatrix4x4 The matrix to copy from
+     */
     public native void set(UltralightMatrix4x4 ultralightMatrix4x4);
 
+    /**
+     * Set to an orthographic projection matrix suitable for use with our
+     * vertex shaders. Optionally flip the y-coordinate space (eg, for OpenGL).
+     *
+     * @param screenWidth The width of the projection
+     * @param screenHeight The height of the projection
+     * @param flipY Whether the y coordinate space should be flipped
+     */
+    public native void setOrthographicProjection(@NativeType("double") double screenWidth, @NativeType(
+            "double") double screenHeight, @NativeType("bool") boolean flipY);
+
+    /**
+     * Transforms this matrix with another matrix.
+     *
+     * @param transformMat The matrix to transform with
+     */
+    public native void transform(UltralightMatrix transformMat);
+
+    /**
+     * Retrieves this matrix as a 4x4 matrix.
+     *
+     * @return This matrix as a 4x4 matrix
+     */
+    public native UltralightMatrix4x4 getMatrix4x4();
+
+    /**
+     * Constructs a native instance of the matrix.
+     *
+     * @return A pointer to the crated instance.
+     */
     private static native long construct();
 
+    /**
+     * Executes the deletion of the native `ultralight::Matrix` instance.
+     * This method is static to not keep a reference to the java object, which
+     * else would prevent deletion.
+     *
+     * @param handle A pointer to the instance to delete
+     */
     private static native void delete(long handle);
 
     @Override
@@ -60,10 +134,5 @@ public long getHandle() {
         return handle.get();
     }
 
-    public native void setOrthographicProjection(@NativeType("double") double screenWidth, @NativeType(
-            "double") double screenHeight, @NativeType("bool") boolean flipY);
-
-    public native void transform(UltralightMatrix transformMat);
-
-    public native UltralightMatrix4x4 getMatrix4x4();
+    // TODO: Other methods
 }

ultralight-java-base/src/main/java/com/labymedia/ultralight/math/UltralightMatrix4x4.java

@@ -24,26 +24,52 @@
 import com.labymedia.ultralight.ffi.ObjectWithHandle;
 import com.labymedia.ultralight.ffi.gc.DeletableObject;
 
+/**
+ * 4x4 Matrix Helper.
+ */
 @NativeType("ultralight::Matrix4x4")
 public class UltralightMatrix4x4 implements ObjectWithHandle {
-
     private final DeletableObject<Long> handle;
 
+    /**
+     * Constructs a new {@link UltralightMatrix4x4} and begins tracking the underlying handle.
+     *
+     * @param handle A pointer to a native ultralight::Matrix4x4, the java object will take
+     *               ownership of the native pointer
+     */
     @NativeCall
     private UltralightMatrix4x4(long handle) {
         this.handle = new DeletableObject<>(handle, UltralightMatrix4x4::delete);
     }
 
+    /**
+     * Constructs a new, empty 4x4 matrix.
+     */
     public UltralightMatrix4x4() {
         this.handle = new DeletableObject<>(construct(), UltralightMatrix4x4::delete);
     }
 
     public native @NativeType("float*") float[] getData();
 
+    /**
+     * Set to identity matrix.
+     */
     public native void setIdentity();
 
+    /**
+     * Constructs a native instance of the matrix.
+     *
+     * @return A pointer to the crated instance.
+     */
     private static native long construct();
 
+    /**
+     * Executes the deletion of the native `ultralight::Matrix4x4` instance.
+     * This method is static to not keep a reference to the java object, which
+     * else would prevent deletion.
+     *
+     * @param handle A pointer to the instance to delete
+     */
     private static native void delete(long handle);
 
     @Override

ultralight-java-base/src/main/java/com/labymedia/ultralight/math/Vec4.java

@@ -23,55 +23,126 @@
 
 import java.util.Arrays;
 
+/**
+ * 4D Vector Helper.
+ */
 @NativeType("ultralight::Vec4")
 public class Vec4 {
     private final float[] value = new float[4];
 
-    public Vec4() {
-    }
-
+    /**
+     * Constructs a new, empty 4D vector.
+     */
+    public Vec4() {}
+
+    /**
+     * Constructs a new 4D vector with the components set.
+     *
+     * @param x The first vector component
+     * @param y The second vector component
+     * @param z The third vector component
+     * @param w The forth vector component
+     */
     public Vec4(float x, float y, float z, float w) {
         this.set(x, y, z, w);
     }
 
+    /**
+     * Constructs a new 4D vector by setting all its components to the same value.
+     *
+     * @param value The value to set all vector components to
+     */
     public Vec4(float value) {
         set(value, value, value, value);
     }
 
+    /**
+     * Constructs a new 4D vector by copying the values from an array.
+     *
+     * @param value The array to copy the values from, must be exactly 4 floats
+     */
     public Vec4(float[] value) {
-        for (int i = 0; i < 4; i++) {
-            this.value[i] = value[i];
+        if(value.length != 4) {
+            throw new IllegalArgumentException("Expected value to be exactly 4 floats");
         }
+
+        System.arraycopy(value, 0, this.value, 0, 4);
     }
 
+    /**
+     * Sets the components of the vector.
+     *
+     * @param x The first vector component
+     * @param y The second vector component
+     * @param z The third vector component
+     * @param w The forth vector component
+     */
     public void set(float x, float y, float z, float w) {
         this.value[0] = x;
         this.value[1] = y;
         this.value[2] = z;
         this.value[3] = w;
     }
 
+    /**
+     * Retrieves the value of the vector as a float array.
+     * Can be used to mutate the vector.
+     *
+     * @return The value of this vector
+     * @see #getValueCopy()
+     */
     public float[] getValue() {
         return value;
     }
 
+    /**
+     * Copies the value of the vector as a float array.
+     *
+     * @return The value of this vector
+     * @see #getValue()
+     */
+    public float[] getValueCopy() {
+        float[] copy = new float[4];
+        System.arraycopy(value, 0, copy, 0, 4);
+        return copy;
+    }
+
+    /**
+     * Retrieves the first component of the vector.
+     *
+     * @return The first component of the vector
+     */
     public float getX() {
         return value[0];
     }
 
+    /**
+     * Retrieves the second component of the vector.
+     *
+     * @return The second component of the vector
+     */
     public float getY() {
         return value[1];
     }
 
+    /**
+     * Retrieves the third component of the vector.
+     *
+     * @return The third component of the vector
+     */
     public float getZ() {
         return value[2];
     }
 
+    /**
+     * Retrieves the forth component of the vector.
+     *
+     * @return The forth component of the vector
+     */
     public float getW() {
         return value[3];
     }
 
-
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;