[PMV]Matrix[4f]: Clarify 'mulVec[34]f' in-place arg properties, add pure in-place variant and use it in PMVMatrix dropping temporary

2 files changed, 113 insertions, 16 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/math/Matrix4f.java b/src/jogl/classes/com/jogamp/opengl/math/Matrix4f.java
index 67d7d48c1..77971b72d 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/Matrix4f.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/Matrix4f.java
@@ -800,7 +800,7 @@ public class Matrix4f {
     }
 
     /**
-     * @param v_in 4-component column-vector
+     * @param v_in 4-component column-vector, can be v_out for in-place transformation
      * @param v_out this * v_in
      * @returns v_out for chaining
      */
@@ -815,13 +815,27 @@ public class Matrix4f {
     }
 
     /**
+     * @param v_inout 4-component column-vector input and output, i.e. in-place transformation
+     * @returns v_inout for chaining
+     */
+    public final Vec4f mulVec4f(final Vec4f v_inout) {
+        // (one matrix row in column-major order) X (column vector)
+        final float x = v_inout.x(), y = v_inout.y(), z = v_inout.z(), w = v_inout.w();
+        v_inout.set( x * m00 + y * m01 + z * m02 + w * m03,
+                     x * m10 + y * m11 + z * m12 + w * m13,
+                     x * m20 + y * m21 + z * m22 + w * m23,
+                     x * m30 + y * m31 + z * m32 + w * m33 );
+        return v_inout;
+    }
+
+    /**
      * Affine 3f-vector transformation by 4x4 matrix
      *
      * 4x4 matrix multiplication with 3-component vector,
      * using {@code 1} for for {@code v_in.w()} and dropping {@code v_out.w()},
      * which shall be {@code 1}.
      *
-     * @param v_in 3-component column-vector {@link Vec3f}
+     * @param v_in 3-component column-vector {@link Vec3f}, can be v_out for in-place transformation
      * @param v_out m_in * v_in, 3-component column-vector {@link Vec3f}
      * @returns v_out for chaining
      */
@@ -834,6 +848,25 @@ public class Matrix4f {
         return v_out;
     }
 
+    /**
+     * Affine 3f-vector transformation by 4x4 matrix
+     *
+     * 4x4 matrix multiplication with 3-component vector,
+     * using {@code 1} for for {@code v_inout.w()} and dropping {@code v_inout.w()},
+     * which shall be {@code 1}.
+     *
+     * @param v_inout 3-component column-vector {@link Vec3f} input and output, i.e. in-place transformation
+     * @returns v_inout for chaining
+     */
+    public final Vec3f mulVec3f(final Vec3f v_inout) {
+        // (one matrix row in column-major order) X (column vector)
+        final float x = v_inout.x(), y = v_inout.y(), z = v_inout.z();
+        v_inout.set( x * m00 + y * m01 + z * m02 + 1f * m03,
+                     x * m10 + y * m11 + z * m12 + 1f * m13,
+                     x * m20 + y * m21 + z * m22 + 1f * m23 );
+        return v_inout;
+    }
+
     //
     // Matrix setTo...(), affine + basic
     //
diff --git a/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java b/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
index f99f6c891..b8b2925ae 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/PMVMatrix.java
@@ -310,8 +310,6 @@ public final class PMVMatrix implements GLMatrixFunc {
         }
 
         mat4Tmp1       = new Matrix4f();
-        vec3Tmp1       = new Vec3f();
-        vec4Tmp1       = new Vec4f();
 
         mat4Tmp2 = null; // on demand
         matPMv = null; // on demand
@@ -582,56 +580,111 @@ public final class PMVMatrix implements GLMatrixFunc {
 
     /**
      * v_out = Mv * v_in
-     * @param v_in input vector
+     * @param v_in input vector, can be v_out for in-place transformation
      * @param v_out output vector
-     * @return given result vector for chaining
+     * @returns v_out for chaining
      */
     public final Vec4f mulMvMatVec4f(final Vec4f v_in, final Vec4f v_out) {
         return matMv.mulVec4f(v_in, v_out);
     }
 
     /**
+     * v_inout = Mv * v_inout
+     * @param v_inout input and output vector, i.e. in-place transformation
+     * @returns v_inout for chaining
+     */
+    public final Vec4f mulMvMatVec4f(final Vec4f v_inout) {
+        return matMv.mulVec4f(v_inout);
+    }
+
+    /**
      * v_out = Mv * v_in
      *
      * Affine 3f-vector transformation by 4x4 matrix, see {@link Matrix4f#mulVec3f(Vec3f, Vec3f)}.
      *
-     * @param v_in input vector
+     * @param v_in input vector, can be v_out for in-place transformation
      * @param v_out output vector
-     * @return given result vector for chaining
+     * @returns v_out for chaining
      */
     public final Vec3f mulMvMatVec3f(final Vec3f v_in, final Vec3f v_out) {
         return matMv.mulVec3f(v_in, v_out);
     }
 
     /**
+     * v_inout = Mv * v_inout
+     *
+     * Affine 3f-vector transformation by 4x4 matrix, see {@link Matrix4f#mulVec3f(Vec3f, Vec3f)}.
+     *
+     * @param v_inout input and output vector, i.e. in-place transformation
+     * @returns v_inout for chaining
+     */
+    public final Vec3f mulMvMatVec3f(final Vec3f v_inout) {
+        return matMv.mulVec3f(v_inout);
+    }
+
+    /**
      * v_out = P * v_in
-     * @param v_in input vector
+     * @param v_in input vector, can be v_out for in-place transformation
      * @param v_out output vector
      * @return given result vector for chaining
+     * @returns v_out for chaining
      */
     public final Vec4f mulPMatVec4f(final Vec4f v_in, final Vec4f v_out) {
         return matP.mulVec4f(v_in, v_out);
     }
 
     /**
+     * v_inout = P * v_inout
+     * @param v_inout input and output vector, i.e. in-place transformation
+     * @return given result vector for chaining
+     * @returns v_inout for chaining
+     */
+    public final Vec4f mulPMatVec4f(final Vec4f v_inout) {
+        return matP.mulVec4f(v_inout);
+    }
+
+    /**
      * v_out = P * v_in
      *
      * Affine 3f-vector transformation by 4x4 matrix, see {@link Matrix4f#mulVec3f(Vec3f, Vec3f)}.
      *
-     * @param v_in float[3] input vector
+     * @param v_in float[3] input vector, can be v_out for in-place transformation
      * @param v_out float[3] output vector
+     * @returns v_out for chaining
      */
     public final Vec3f mulPMatVec3f(final Vec3f v_in, final Vec3f v_out) {
         return matP.mulVec3f(v_in, v_out);
     }
 
     /**
+     * v_inout = P * v_inout
+     *
+     * Affine 3f-vector transformation by 4x4 matrix, see {@link Matrix4f#mulVec3f(Vec3f, Vec3f)}.
+     *
+     * @param v_inout input and output vector, i.e. in-place transformation
+     * @returns v_inout for chaining
+     */
+    public final Vec3f mulPMatVec3f(final Vec3f v_inout) {
+        return matP.mulVec3f(v_inout);
+    }
+
+    /**
      * v_out = P * Mv * v_in
-     * @param v_in float[4] input vector
+     * @param v_in float[4] input vector, can be v_out for in-place transformation
      * @param v_out float[4] output vector
+     * @returns v_out for chaining
      */
     public final Vec4f mulPMvMatVec4f(final Vec4f v_in, final Vec4f v_out) {
-        return matP.mulVec4f( matMv.mulVec4f( v_in, vec4Tmp1 ), v_out );
+        return matP.mulVec4f( matMv.mulVec4f( v_in, v_out ) );
+    }
+
+    /**
+     * v_inout = P * Mv * v_inout
+     * @param v_inout input and output vector, i.e. in-place transformation
+     * @returns v_inout for chaining
+     */
+    public final Vec4f mulPMvMatVec4f(final Vec4f v_inout) {
+        return matP.mulVec4f( matMv.mulVec4f( v_inout ) );
     }
 
     /**
@@ -639,11 +692,24 @@ public final class PMVMatrix implements GLMatrixFunc {
      *
      * Affine 3f-vector transformation by 4x4 matrix, see {@link Matrix4f#mulVec3f(Vec3f, Vec3f)}.
      *
-     * @param v_in float[3] input vector
+     * @param v_in float[3] input vector, can be v_out for in-place transformation
      * @param v_out float[3] output vector
+     * @returns v_out for chaining
      */
     public final Vec3f mulPMvMatVec3f(final Vec3f v_in, final Vec3f v_out) {
-        return matP.mulVec3f( matMv.mulVec3f( v_in, vec3Tmp1 ), v_out );
+        return matP.mulVec3f( matMv.mulVec3f( v_in, v_out ) );
+    }
+
+    /**
+     * v_inout = P * Mv * v_inout
+     *
+     * Affine 3f-vector transformation by 4x4 matrix, see {@link Matrix4f#mulVec3f(Vec3f, Vec3f)}.
+     *
+     * @param v_inout float[3] input and output vector, i.e. in-place transformation
+     * @returns v_inout for chaining
+     */
+    public final Vec3f mulPMvMatVec3f(final Vec3f v_inout) {
+        return matP.mulVec3f( matMv.mulVec3f( v_inout ) );
     }
 
     //
@@ -1439,8 +1505,6 @@ public final class PMVMatrix implements GLMatrixFunc {
     private final SyncMatrices4f syncP_Mv, syncP_Mv_Mvi, syncP_Mv_Mvi_Mvit;
 
     private final Matrix4f mat4Tmp1;
-    private final Vec3f vec3Tmp1;
-    private final Vec4f vec4Tmp1;
 
     private int matrixMode = GL_MODELVIEW;
     private int modifiedBits = MODIFIED_ALL;