Feat: Added reflect(Vector4f normal) to Vector4f

Author: ArtifactForms

src/main/java/math/Vector4f.java

@@ -365,6 +365,45 @@ public Vector4f projectOnto(Vector4f other) {
     return new Vector4f(other).multiplyLocal(scalar);
   }
 
+  /**
+   * Reflects this vector around the given normal vector.
+   *
+   * <p>Reflection is the process of "bouncing" a vector off a surface defined by the normal vector,
+   * such that the angle of incidence equals the angle of reflection. This is commonly used in
+   * physics simulations, computer graphics, and geometric calculations.
+   *
+   * <p>The reflection formula is:
+   *
+   * <pre>
+   * R = V - 2 * (V ⋅ N) * N
+   * </pre>
+   *
+   * where:
+   *
+   * <ul>
+   *   <li><b>R</b>: Reflected vector
+   *   <li><b>V</b>: Original vector (this vector)
+   *   <li><b>N</b>: Normal vector (should be normalized to ensure accurate results)
+   * </ul>
+   *
+   * This method computes the reflection of the current vector based on the specified normal and
+   * returns the resulting vector.
+   *
+   * @param normal the normal vector around which this vector will be reflected. Must not be {@code
+   *     null} or a zero vector.
+   * @return a new {@code Vector4f} instance representing the reflected vector.
+   * @throws IllegalArgumentException if the {@code normal} vector is {@code null} or a zero vector.
+   */
+  public Vector4f reflect(Vector4f normal) {
+    if (normal == null) {
+      throw new IllegalArgumentException("Normal cannot be null.");
+    }
+    if (normal.isZero()) {
+      throw new IllegalArgumentException("Normal cannot be zero vertor.");
+    }
+    return this.subtract(normal.multiply(2 * this.dot(normal)));
+  }
+
   /**
    * Returns the x component of the vector.
    *

src/test/java/math/Vector4fTest.java

@@ -2116,6 +2116,147 @@ public void testProjectOntoReturnsNewInstanceAndLeavesOriginalUntouched() {
     assertEquals(0.0f, vector2.getW(), "The original vector2's W component should be unchanged.");
   }
 
+  // ----------------------------------------------------------------------------------------------
+  // Reflect
+  // ----------------------------------------------------------------------------------------------
+
+  @Test
+  public void testReflectXAxis() {
+    Vector4f v1 = new Vector4f(1, 2, 3, 4);
+    Vector4f normal = new Vector4f(1, 0, 0, 0); // Normal of the x-axis
+    Vector4f expected = new Vector4f(-1, 2, 3, 4);
+    assertEquals(expected, v1.reflect(normal));
+  }
+
+  @Test
+  public void testReflectYAxis() {
+    Vector4f v1 = new Vector4f(1, 2, 3, 4);
+    Vector4f normal = new Vector4f(0, 1, 0, 0); // Normal of the y-axis
+    Vector4f expected = new Vector4f(1, -2, 3, 4);
+    assertEquals(expected, v1.reflect(normal));
+  }
+
+  @Test
+  public void testReflectZAxis() {
+    Vector4f v1 = new Vector4f(1, 2, 3, 4);
+    Vector4f normal = new Vector4f(0, 0, 1, 0); // Normal of the z-axis
+    Vector4f expected = new Vector4f(1, 2, -3, 4);
+    assertEquals(expected, v1.reflect(normal));
+  }
+
+  @Test
+  public void testReflectArbitraryNormal() {
+    // Setup
+    Vector4f v1 = new Vector4f(1, 1, 1, 1);
+    Vector4f normal = new Vector4f(1, 1, 1, 0).normalize();
+
+    // Expected reflection result calculated manually:
+    // Reflection formula: v' = v - 2 * (v ⋅ n) * n
+    // Dot product (v ⋅ n)
+    float dot =
+        v1.getX() * normal.getX()
+            + v1.getY() * normal.getY()
+            + v1.getZ() * normal.getZ()
+            + v1.getW() * normal.getW();
+
+    // Scale the normal by 2 * dot
+    Vector4f scaledNormal =
+        new Vector4f(
+            2 * dot * normal.getX(),
+            2 * dot * normal.getY(),
+            2 * dot * normal.getZ(),
+            2 * dot * normal.getW());
+
+    // Subtract scaledNormal from v1 to get the reflected vector
+    Vector4f expectedReflection =
+        new Vector4f(
+            v1.getX() - scaledNormal.getX(),
+            v1.getY() - scaledNormal.getY(),
+            v1.getZ() - scaledNormal.getZ(),
+            v1.getW() - scaledNormal.getW());
+
+    // Actual reflection
+    Vector4f reflected = v1.reflect(normal);
+
+    // Assert equality
+    assertEquals(expectedReflection.getX(), reflected.getX(), 1e-6);
+    assertEquals(expectedReflection.getY(), reflected.getY(), 1e-6);
+    assertEquals(expectedReflection.getZ(), reflected.getZ(), 1e-6);
+    assertEquals(expectedReflection.getW(), reflected.getW(), 1e-6);
+  }
+
+  @Test
+  public void testReflectAlongItself() {
+    Vector4f v1 = new Vector4f(1, 0, 0, 0);
+    Vector4f normal = new Vector4f(1, 0, 0, 0);
+    assertEquals(v1.negate(), v1.reflect(normal));
+  }
+
+  @Test
+  public void testReflectAlongZeroVector() {
+    Vector4f v1 = new Vector4f(1, 2, 3, 4);
+    Vector4f normal = new Vector4f(0, 0, 0, 0);
+    assertThrows(IllegalArgumentException.class, () -> v1.reflect(normal));
+  }
+
+  @Test
+  public void testReflectAlongNullVectorThrowsIllegalArgumentException() {
+    Vector4f v1 = new Vector4f(1, 2, 3, 4);
+    assertThrows(IllegalArgumentException.class, () -> v1.reflect(null));
+  }
+
+  @Test
+  public void testReflectParallelToNormal() {
+    // Vector and normal are parallel
+    Vector4f v1 = new Vector4f(2, 0, 0, 0);
+    Vector4f normal = new Vector4f(1, 0, 0, 0).normalize();
+
+    // Perform reflection
+    Vector4f reflected = v1.reflect(normal);
+
+    // Expected result: negation of the vector
+    Vector4f expected = new Vector4f(-2, 0, 0, 0);
+
+    // Assert the reflected vector is correct
+    assertEquals(
+        expected, reflected, "The reflected vector is incorrect when v1 is parallel to normal.");
+
+    // Assert v1 and normal remain unchanged
+    Vector4f originalV1 = new Vector4f(2, 0, 0, 0);
+    Vector4f originalNormal = new Vector4f(1, 0, 0, 0).normalize();
+    assertEquals(originalV1, v1, "The original vector should remain unchanged.");
+    assertEquals(originalNormal, normal, "The normal vector should remain unchanged.");
+  }
+
+  @Test
+  public void testReflectCreatesNewInstanceAndDoesNotChangeOriginalVectorAndInputNormal() {
+    // Original vector
+    Vector4f v1 = new Vector4f(3, -2, 1, 0);
+    // Normal vector
+    Vector4f normal = new Vector4f(0, 1, 0, 0).normalize();
+
+    // Store copies of the original vectors for later comparison
+    Vector4f originalV1 = new Vector4f(v1.getX(), v1.getY(), v1.getZ(), v1.getW());
+    Vector4f originalNormal =
+        new Vector4f(normal.getX(), normal.getY(), normal.getZ(), normal.getW());
+
+    // Perform reflection
+    Vector4f reflected = v1.reflect(normal);
+
+    // Assert that the returned instance is a new object
+    assertNotSame("The method should return a new Vector4f instance.", v1, reflected);
+
+    // Assert the original vector remains unchanged
+    assertEquals(originalV1, v1, "The original vector should remain unchanged.");
+
+    // Assert the normal vector remains unchanged
+    assertEquals(originalNormal, normal, "The normal vector should remain unchanged.");
+
+    // Optional: Assert that the reflection result is correct
+    Vector4f expected = new Vector4f(3, 2, 1, 0); // Reflection around Y-axis
+    assertEquals(expected, reflected, "The reflected vector is incorrect.");
+  }
+
   // ----------------------------------------------------------------------------------------------
   // Set Values
   // ----------------------------------------------------------------------------------------------