New API: add a scaled vector (#5702)

* vec3

* vec2

* simplify vec3 example

* vec4

* Update src/core/math/vec4.js

Co-authored-by: Will Eastcott <[email protected]>

* Update src/core/math/vec3.js

Co-authored-by: Will Eastcott <[email protected]>

* Update src/core/math/vec2.js

Co-authored-by: Will Eastcott <[email protected]>

* number type

* * to number

---------

Co-authored-by: Will Eastcott <[email protected]>

Author: LeXXik

src/core/math/vec2.js

@@ -103,6 +103,27 @@ class Vec2 {
         return this;
     }
 
+    /**
+     * Adds a 2-dimensional vector scaled by scalar value. Does not modify the vector being added.
+     *
+     * @param {Vec2} rhs - The vector to add to the specified vector.
+     * @param {number} scalar - The number to multiply the added vector with.
+     * @returns {Vec2} Self for chaining.
+     * @example
+     * const vec = new pc.Vec2(1, 2);
+     *
+     * vec.addScaled(pc.Vec2.UP, 2);
+     *
+     * // Outputs [1, 4]
+     * console.log("The result of the addition is: " + vec.toString());
+     */
+    addScaled(rhs, scalar) {
+        this.x += rhs.x * scalar;
+        this.y += rhs.y * scalar;
+
+        return this;
+    }
+
     /**
      * Returns an identical copy of the specified 2-dimensional vector.
      *

src/core/math/vec3.js

@@ -114,6 +114,28 @@ class Vec3 {
         return this;
     }
 
+    /**
+     * Adds a 3-dimensional vector scaled by scalar value. Does not modify the vector being added.
+     *
+     * @param {Vec3} rhs - The vector to add to the specified vector.
+     * @param {number} scalar - The number to multiply the added vector with.
+     * @returns {Vec3} Self for chaining.
+     * @example
+     * const vec = new pc.Vec3(1, 2, 3);
+     *
+     * vec.addScaled(pc.Vec3.UP, 2);
+     *
+     * // Outputs [1, 4, 3]
+     * console.log("The result of the addition is: " + vec.toString());
+     */
+    addScaled(rhs, scalar) {
+        this.x += rhs.x * scalar;
+        this.y += rhs.y * scalar;
+        this.z += rhs.z * scalar;
+
+        return this;
+    }
+
     /**
      * Returns an identical copy of the specified 3-dimensional vector.
      *

src/core/math/vec4.js

@@ -127,6 +127,29 @@ class Vec4 {
         return this;
     }
 
+    /**
+     * Adds a 4-dimensional vector scaled by scalar value. Does not modify the vector being added.
+     *
+     * @param {Vec4} rhs - The vector to add to the specified vector.
+     * @param {number} scalar - The number to multiply the added vector with.
+     * @returns {Vec4} Self for chaining.
+     * @example
+     * const vec = new pc.Vec4(1, 2, 3, 4);
+     *
+     * vec.addScaled(pc.Vec4.ONE, 2);
+     *
+     * // Outputs [3, 4, 5, 6]
+     * console.log("The result of the addition is: " + vec.toString());
+     */
+    addScaled(rhs, scalar) {
+        this.x += rhs.x * scalar;
+        this.y += rhs.y * scalar;
+        this.z += rhs.z * scalar;
+        this.w += rhs.w * scalar;
+
+        return this;
+    }
+
     /**
      * Returns an identical copy of the specified 4-dimensional vector.
      *

test/core/math/vec2.test.mjs

@@ -76,6 +76,17 @@ describe('Vec2', function () {
 
     });
 
+    describe('#addScaled', function () {
+
+        it('adds a scaled vector', function () {
+            const v = new Vec2(1, 2);
+            v.addScaled(Vec2.UP, 2);
+            expect(v.x).to.equal(1);
+            expect(v.y).to.equal(4);
+        });
+
+    });
+
     describe('#ceil', function () {
 
         it('leaves integers unchanged', function () {

test/core/math/vec3.test.mjs

@@ -84,6 +84,18 @@ describe('Vec3', function () {
 
     });
 
+    describe('#addScaled', function () {
+
+        it('adds a scaled vector', function () {
+            const v = new Vec3(1, 2, 3);
+            v.addScaled(Vec3.UP, 2);
+            expect(v.x).to.equal(1);
+            expect(v.y).to.equal(4);
+            expect(v.z).to.equal(3);
+        });
+
+    });
+
     describe('#ceil', function () {
 
         it('leaves integers unchanged', function () {

test/core/math/vec4.test.mjs

@@ -92,6 +92,19 @@ describe('Vec4', function () {
 
     });
 
+    describe('#addScaled', function () {
+
+        it('adds a scaled vector', function () {
+            const v = new Vec4(1, 2, 3, 4);
+            v.addScaled(Vec4.ONE, 2);
+            expect(v.x).to.equal(3);
+            expect(v.y).to.equal(4);
+            expect(v.z).to.equal(5);
+            expect(v.w).to.equal(6);
+        });
+
+    });
+
     describe('#ceil', function () {
 
         it('leaves integers unchanged', function () {